Make the tool writing documentation align a bit more closely
with reality.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@4999 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
index cd74ea0..84d37c6 100644
--- a/docs/xml/writing-tools.xml
+++ b/docs/xml/writing-tools.xml
@@ -35,7 +35,7 @@
between its "core" and "tools".</para>
<para>The core provides the common low-level infrastructure to
-support program instrumentation, including the x86-to-x86 JIT
+support program instrumentation, including the JIT
compiler, low-level memory manager, signal handling and a
scheduler (for pthreads). It also provides certain services that
are useful to some but not all tools, such as support for error
@@ -43,8 +43,8 @@
<para>But the core leaves certain operations undefined, which
must be filled by tools. Most notably, tools define how program
-code should be instrumented. They can also define certain
-variables to indicate to the core that they would like to use
+code should be instrumented. They can also call certain
+functions to indicate to the core that they would like to use
certain services, or be notified when certain interesting events
occur. But the core takes care of all the hard work.</para>
@@ -81,7 +81,7 @@
(<computeroutput>malloc()</computeroutput> etc.)</para>
</listitem>
<listitem>
- <para>Pthread operations and scheduling</para>
+ <para>Thread scheduling</para>
</listitem>
<listitem>
<para>Signal handling</para>
@@ -177,7 +177,7 @@
<para><command>lackey</command>: does simple counting of
various things: the number of calls to a particular function
(<computeroutput>_dl_runtime_resolve()</computeroutput>); the
- number of basic blocks, x86 instruction, UCode instructions
+ number of basic blocks, guest instructions, VEX instructions
executed; the number of branches executed and the proportion of
them which were taken.</para>
</listitem>
@@ -281,28 +281,17 @@
<title>How tools work</title>
<para>Tools must define various functions for instrumenting
-programs that are called by Valgrind's core, yet they must be
-implemented in such a way that they can be written and compiled
-without touching Valgrind's core. This is important, because one
-of our aims is to allow people to write and distribute their own
-tools that can be plugged into Valgrind's core easily.</para>
+programs that are called by Valgrind's core. They are then linked
+against the coregrind library
+(<computeroutput>libcoregrind.a</computeroutput>) that valgrind
+provides as well as the VEX library
+(<computeroutput>libvex.a</computeroutput>) that also comes with
+valgrind and provides the JIT engine.
-<para>This is achieved by packaging each tool into a separate
-shared object which is then loaded ahead of the core shared
-object <computeroutput>valgrind.so</computeroutput>, using the
-dynamic linker's <computeroutput>LD_PRELOAD</computeroutput>
-variable. Any functions defined in the tool that share the name
-with a function defined in core (such as the instrumentation
-function <computeroutput>instrument()</computeroutput>)
-override the core's definition. Thus the core can call the
-necessary tool functions.</para>
-
-<para>This magic is all done for you; the shared object used is
-chosen with the <computeroutput>--tool</computeroutput> option to
-the <computeroutput>valgrind</computeroutput> startup script.
-The default tool used is
-<computeroutput>memcheck</computeroutput>, Valgrind's original
-memory checker.</para>
+<para>Each tool is linked as a statically linked program and placed
+in the valgrind library directory from where valgrind will load it
+automatically when the <computeroutput>--tool</computeroutput> option
+is used to select it.</para>
</sect2>
@@ -357,8 +346,8 @@
trying to understand this file, at least a little; you might
have to do more complicated things with it later on. In
particular, the name of the
- <computeroutput>vgtool_foobar_so_SOURCES</computeroutput>
- variable determines the name of the tool's shared object, which
+ <computeroutput>foobar_SOURCES</computeroutput>
+ variable determines the name of the tool, which
determines what name must be passed to the
<computeroutput>--tool</computeroutput> option to use the
tool.</para>
@@ -396,8 +385,7 @@
make install]]></programlisting>
<para>It should automake, configure and compile without
- errors, putting copies of the tool's shared object
- <computeroutput>vgtool_foobar.so</computeroutput> in
+ errors, putting copies of the tool in
<computeroutput>foobar/</computeroutput> and
<computeroutput>inst/lib/valgrind/</computeroutput>.</para>
</listitem>
@@ -458,7 +446,7 @@
<para>In addition, if a tool wants to use some of the optional
services provided by the core, it may have to define other
-functions.</para>
+functions and tell the code about them.</para>
</sect2>
@@ -509,9 +497,8 @@
<computeroutput>VG_(track_*)()</computeroutput>. These include
things such as blocks of memory being malloc'd, the stack pointer
changing, a mutex being locked, etc. If a tool wants to know
-about this, it should set the relevant pointer in the structure
-to point to a function, which will be called when that event
-happens.</para>
+about this, it should provide a pointer to a function, which will
+be called when that event happens.</para>
<para>For example, if the tool want to be notified when a new
block of memory is malloc'd, it should call
@@ -532,21 +519,16 @@
<para><computeroutput>instrument()</computeroutput> is the
interesting one. It allows you to instrument
-<emphasis>UCode</emphasis>, which is Valgrind's RISC-like
-intermediate language. UCode is described in
+<emphasis>VEX IR</emphasis>, which is Valgrind's RISC-like
+intermediate language. VEX IR is described in
<xref linkend="mc-tech-docs.ucode"/>.</para>
-<para>The easiest way to instrument UCode is to insert calls to C
+<para>The easiest way to instrument VEX IR is to insert calls to C
functions when interesting things happen. See the tool "Lackey"
(<filename>lackey/lk_main.c</filename>) for a simple example of
this, or Cachegrind (<filename>cachegrind/cg_main.c</filename>)
for a more complex example.</para>
-<para>A much more complicated way to instrument UCode, albeit one
-that might result in faster instrumented programs, is to extend
-UCode with new UCode instructions. This is recommended for
-advanced Valgrind hackers only! See Memcheck for an example.</para>
-
</sect2>
@@ -576,7 +558,7 @@
a tool should need to
<computeroutput>#include</computeroutput>.</para>
-<para>In particular, you probably shouldn't use anything from the
+<para>In particular, you can't use anything from the
C library (there are deep reasons for this, trust us). Valgrind
provides an implementation of a reasonable subset of the C
library, details of which are in
@@ -592,13 +574,9 @@
Addrcheck, Cachegrind, Lackey, etc.) are probably the best
documentation of all, for the moment.</para>
-<para>Note that the <computeroutput>VG_</computeroutput> and
-<computeroutput>TL_</computeroutput> macros are used heavily.
-These just prepend longer strings in front of names to avoid
-potential namespace clashes. We strongly recommend using the
-<computeroutput>TL_</computeroutput> macro for any global
-functions and variables in your tool, or writing a similar
-macro.</para>
+<para>Note that the <computeroutput>VG_</computeroutput> macro is used
+heavily. This just prepends a longer string in front of names to
+avoid potential namespace clashes.</para>
</sect2>
@@ -672,9 +650,9 @@
<sect3 id="writing-tools.ucode-probs">
<title>UCode Instrumentation Problems</title>
-<para>If you are having problems with your UCode instrumentation,
+<para>If you are having problems with your VEX UIR instrumentation,
it's likely that GDB won't be able to help at all. In this case,
-Valgrind's <computeroutput>--trace-codegen</computeroutput>
+Valgrind's <computeroutput>--trace-flags</computeroutput>
option is invaluable for observing the results of
instrumentation.</para>
@@ -690,7 +668,7 @@
than using GDB.</para>
<para>The other debugging command line options can be useful too
-(run <computeroutput>valgrind -h</computeroutput> for the
+(run <computeroutput>valgrind --help-debug</computeroutput> for the
list).</para>
</sect3>