diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
new file mode 100644
index 0000000..96897d6
--- /dev/null
+++ b/docs/xml/FAQ.xml
@@ -0,0 +1,674 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
+
+<book id="FAQ" xreflabel="Valgrind FAQ">
+
+  <bookinfo>
+    <title>Valgrind FAQ</title>
+  </bookinfo>
+
+
+<chapter id="faq.background" xreflabel="Background">
+<title>Background</title>
+
+<qandaset id="qset.background">
+
+<qandaentry id="faq.pronounce">
+ <question>
+  <para>How do you pronounce "Valgrind"?</para>
+ </question>
+ <answer>
+  <para>The "Val" as in the world "value".  The "grind" is
+  pronounced with a short 'i' -- ie. "grinned" (rhymes with
+  "tinned") rather than "grined" (rhymes with "find").</para>
+  <para>Don't feel bad: almost everyone gets it wrong at
+  first.</para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.whence">
+ <question>
+  <para>Where does the name "Valgrind" come from?</para>
+ </question>
+ <answer>
+  <para>From Nordic mythology.  Originally (before release) the
+  project was named Heimdall, after the watchman of the Nordic
+  gods.  He could "see a hundred miles by day or night, hear the
+  grass growing, see the wool growing on a sheep's back" (etc).
+  This would have been a great name, but it was already taken by
+  a security package "Heimdal".</para> <para>Keeping with the
+  Nordic theme, Valgrind was chosen.  Valgrind is the name of the
+  main entrance to Valhalla (the Hall of the Chosen Slain in
+  Asgard).  Over this entrance there resides a wolf and over it
+  there is the head of a boar and on it perches a huge eagle,
+  whose eyes can see to the far regions of the nine worlds.  Only
+  those judged worthy by the guardians are allowed to pass
+  through Valgrind.  All others are refused entrance.</para>
+  <para>It's not short for "value grinder", although that's not a
+  bad guess.</para>
+  </answer>
+ </qandaentry>
+
+</qandaset>
+
+</chapter>
+
+
+<chapter id="faq.installing" 
+       xreflabel="Compiling, installing and configuring">
+<title>Compiling, installing and configuring</title>
+<qandaset id="qset.installing">
+
+<qandaentry id="faq.make_dies">
+ <question>
+  <para>When I trying building Valgrind, 'make' dies partway with
+  an assertion failure, something like this: 
+<screen>
+% make: expand.c:489: allocated_variable_append: 
+        Assertion 'current_variable_set_list->next != 0' failed.
+</screen>
+  </para>
+ </question>
+ <answer>
+  <para>It's probably a bug in 'make'.  Some, but not all,
+  instances of version 3.79.1 have this bug, see
+  www.mail-archive.com/bug-make@gnu.org/msg01658.html.  Try
+  upgrading to a more recent version of 'make'.  Alternatively,
+  we have heard that unsetting the CFLAGS environment variable
+  avoids the problem.</para>
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+
+<chapter id="faq.abort" 
+       xreflabel="Valgrind aborts unexpectedly">
+<title>Valgrind aborts unexpectedly</title>
+<qandaset id="qset.abort">
+
+<qandaentry id="faq.exit_errors">
+ <question>
+  <para>Programs run OK on Valgrind, but at exit produce a bunch
+  of errors a bit like this:</para>
+ </question>
+ <answer><para>
+<programlisting>
+==20755== Invalid read of size 4
+==20755==    at 0x40281C8A: _nl_unload_locale (loadlocale.c:238)
+==20755==    by 0x4028179D: free_mem (findlocale.c:257)
+==20755==    by 0x402E0962: __libc_freeres (set-freeres.c:34)
+==20755==    by 0x40048DCC: vgPlain___libc_freeres_wrapper (vg_clientfuncs.c:585)
+==20755==    Address 0x40CC304C is 8 bytes inside a block of size 380 free'd
+==20755==    at 0x400484C9: free (vg_clientfuncs.c:180)
+==20755==    by 0x40281CBA: _nl_unload_locale (loadlocale.c:246)
+==20755==    by 0x40281218: free_mem (setlocale.c:461)
+==20755==    by 0x402E0962: __libc_freeres (set-freeres.c:34)
+</programlisting>
+
+ and then die with a segmentation fault.</para>
+ <para>When the program exits, Valgrind runs the procedure
+ <literal>__libc_freeres()</literal> in glibc.  This is a hook
+ for memory debuggers, so they can ask glibc to free up any
+ memory it has used.  Doing that is needed to ensure that
+ Valgrind doesn't incorrectly report space leaks in glibc.</para>
+ <para>Problem is that running
+ <literal>__libc_freeres()</literal> in older glibc versions
+ causes this crash.</para> <para>WORKAROUND FOR 1.1.X and later
+ versions of Valgrind: use the
+ <literal>--run-libc-freeres=no</literal> flag.  You may then get
+ space leak reports for glibc-allocations (please _don't_ report
+ these to the glibc people, since they are not real leaks), but
+ at least the program runs.</para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.bugdeath">
+ <question>
+  <para>My (buggy) program dies like this:</para>
+ </question>
+ <answer>
+  <screen>
+% valgrind: vg_malloc2.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.
+</screen>
+
+  <para>If Memcheck (the memory checker) shows any invalid reads,
+  invalid writes and invalid frees in your program, the above may
+  happen.  Reason is that your program may trash Valgrind's
+  low-level memory manager, which then dies with the above
+  assertion, or something like this.  The cure is to fix your
+  program so that it doesn't do any illegal memory accesses.  The
+  above failure will hopefully go away after that.</para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.msgdeath">
+ <question>
+  <para>My program dies, printing a message like this along the
+    way:</para>
+ </question>
+ <answer>
+<screen>
+% disInstr: unhandled instruction bytes: 0x66 0xF 0x2E 0x5
+</screen>
+
+  <para>Older versions did not support some x86 instructions,
+  particularly SSE/SSE2 instructions.  Try a newer Valgrind; we
+  now support almost all instructions.  If it still happens with
+  newer versions, if the failing instruction is an SSE/SSE2
+  instruction, you might be able to recompile your progrma
+  without it by using the flag
+  <computeroutput>-march</computeroutput> to gcc.  Either way,
+  let us know and we'll try to fix it.</para>
+
+  <para>Another possibility is that your program has a bug and
+  erroneously jumps to a non-code address, in which case you'll
+  get a SIGILL signal.  Memcheck/Addrcheck may issue a warning
+  just before this happens, but they might not if the jump
+  happens to land in addressable memory.</para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.defdeath">
+ <question>
+  <para>My program dies like this:</para>
+ </question>
+ <answer>
+<screen>
+% error: /lib/librt.so.1: symbol __pthread_clock_settime, 
+  version GLIBC_PRIVATE not defined in file libpthread.so.0 with link time reference
+</screen>
+
+  <para>This is a total swamp.  Nevertheless there is a way out.
+  It's a problem which is not easy to fix.  Really the problem is
+  that <filename>/lib/librt.so.1</filename> refers to some
+  symbols <literal>__pthread_clock_settime</literal> and
+  <literal>__pthread_clock_gettime</literal> in
+  <filename>/lib/libpthread.so</filename> which are not intended
+  to be exported, ie they are private.</para>
+
+  <para>Best solution is to ensure your program does not use
+  <filename>/lib/librt.so.1</filename>.</para>
+
+  <para>However ... since you're probably not using it directly,
+  or even knowingly, that's hard to do.  You might instead be
+  able to fix it by playing around with
+  <filename>coregrind/vg_libpthread.vs</filename>.  Things to
+  try:</para>
+
+  <para>Remove this:</para>
+<programlisting>
+GLIBC_PRIVATE {
+  __pthread_clock_gettime;
+  __pthread_clock_settime;
+};
+</programlisting>
+
+<para>or maybe remove this</para>
+<programlisting>
+GLIBC_2.2.3 {
+  __pthread_clock_gettime;
+  __pthread_clock_settime;
+}  GLIBC_2.2;
+</programlisting>
+
+<para>or maybe add this:</para>
+<programlisting>
+GLIBC_2.2.4 {
+  __pthread_clock_gettime;
+  __pthread_clock_settime;
+} GLIBC_2.2;
+
+GLIBC_2.2.5 {
+  __pthread_clock_gettime;
+  __pthread_clock_settime;
+} GLIBC_2.2;
+</programlisting>
+
+  <para>or some combination of the above.  After each change you
+  need to delete <filename>coregrind/libpthread.so</filename> and
+  do <computeroutput>make &amp;&amp; make
+  install</computeroutput>.</para>
+
+  <para>I just don't know if any of the above will work.  If you
+  can find a solution which works, I would be interested to hear
+  it.</para>
+
+  <para>To which someone replied:</para>
+<screen>
+I deleted this:
+
+GLIBC_2.2.3 { 
+   __pthread_clock_gettime; 
+   __pthread_clock_settime; 
+} GLIBC_2.2; 
+
+and it worked.
+</screen>
+
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="faq.unexpected" 
+       xreflabel="Valgrind behaves unexpectedly">
+<title>Valgrind behaves unexpectedly</title>
+<qandaset id="qset.unexpected">
+
+<qandaentry id="faq.no-output">
+ <question>
+  <para>I try running "valgrind my-program", but my-program runs
+  normally, and Valgrind doesn't emit any output at all.</para>
+ </question>
+ <answer>
+  <para><command>For versions prior to 2.1.1:</command></para>
+
+  <para>Valgrind doesn't work out-of-the-box with programs that
+  are entirely statically linked.  It does a quick test at
+  startup, and if it detects that the program is statically
+  linked, it aborts with an explanation.</para>
+
+  <para>This test may fail in some obscure cases, eg. if you run
+  a script under Valgrind and the script interpreter is
+  statically linked.</para>
+
+  <para>If you still want static linking, you can ask gcc to link
+  certain libraries statically.  Try the following options:</para>
+<screen>
+-Wl,-Bstatic -lmyLibrary1 -lotherLibrary -Wl,-Bdynamic
+</screen>
+
+  <para>Just make sure you end with
+  <computeroutput>-Wl,-Bdynamic</computeroutput> so that libc is
+  dynamically linked.</para>
+
+  <para>If you absolutely cannot use dynamic libraries, you can
+  try statically linking together all the .o files in coregrind/,
+  all the .o files of the tool of your choice (eg. those in
+  memcheck/), and the .o files of your program.  You'll end up
+  with a statically linked binary that runs permanently under
+  Valgrind's control.  Note that we haven't tested this procedure
+  thoroughly.</para>
+
+  <para><command>For versions 2.1.1 and later:</command></para>
+  <para>Valgrind does now work with static binaries, although
+  beware that some of the tools won't operate as well as normal,
+  because they have access to less information about how the
+  program runs.  Eg. Memcheck will miss some errors that it would
+  otherwise find.  This is because Valgrind doesn't replace
+  malloc() and friends with its own versions.  It's best if your
+  program is dynamically linked with glibc.</para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.slowthread">
+ <question>
+  <para>My threaded server process runs unbelievably slowly on
+  Valgrind.  So slowly, in fact, that at first I thought it had
+  completely locked up.</para>
+ </question>
+ <answer>
+  <para>We are not completely sure about this, but one
+  possibility is that laptops with power management fool
+  Valgrind's timekeeping mechanism, which is (somewhat in error)
+  based on the x86 RDTSC instruction.  A "fix" which is claimed
+  to work is to run some other cpu-intensive process at the same
+  time, so that the laptop's power-management clock-slowing does
+  not kick in.  We would be interested in hearing more feedback
+  on this.</para>
+
+  <para>Another possible cause is that versions prior to 1.9.6
+  did not support threading on glibc 2.3.X systems well.
+  Hopefully the situation is much improved with 1.9.6 and later
+  versions.</para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.reports">
+ <question>
+  <para>My program uses the C++ STL and string classes.  Valgrind
+  reports 'still reachable' memory leaks involving these classes
+  at the exit of the program, but there should be none.</para>
+ </question>
+ <answer>
+  <para>First of all: relax, it's probably not a bug, but a
+  feature.  Many implementations of the C++ standard libraries
+  use their own memory pool allocators.  Memory for quite a
+  number of destructed objects is not immediately freed and given
+  back to the OS, but kept in the pool(s) for later re-use.  The
+  fact that the pools are not freed at the exit() of the program
+  cause Valgrind to report this memory as still reachable.  The
+  behaviour not to free pools at the exit() could be called a bug
+  of the library though.</para>
+
+  <para>Using gcc, you can force the STL to use malloc and to
+  free memory as soon as possible by globally disabling memory
+  caching.  Beware!  Doing so will probably slow down your
+  program, sometimes drastically.</para>
+  <itemizedlist>
+   <listitem>
+    <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source
+    using the STL with <literal>-D__USE_MALLOC</literal>. Beware!
+    This is removed from gcc starting with version 3.3.</para>
+   </listitem>
+   <listitem>
+    <para>With 3.2.2 and later, you should export the environment
+    variable <literal>GLIBCPP_FORCE_NEW</literal> before running
+    your program.</para>
+   </listitem>
+  </itemizedlist>
+
+  <para>There are other ways to disable memory pooling: using the
+  <literal>malloc_alloc</literal> template with your objects (not
+  portable, but should work for gcc) or even writing your own
+  memory allocators. But all this goes beyond the scope of this
+  FAQ.  Start by reading <ulink
+  url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3">
+  http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3</ulink>
+  if you absolutely want to do that. But beware:</para>
+
+  <orderedlist>
+   <listitem>
+    <para>there are currently changes underway for gcc which are
+    not totally reflected in the docs right now ("now" == 26 Apr
+    03)</para>
+   </listitem>
+   <listitem>
+    <para>allocators belong to the more messy parts of the STL
+    and people went at great lengths to make it portable across
+    platforms. Chances are good that your solution will work on
+    your platform, but not on others.</para>
+   </listitem>
+  </orderedlist>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.unhelpful">
+ <question>
+  <para>The stack traces given by Memcheck (or another tool)
+  aren't helpful.  How can I improve them?</para>
+ </question>
+ <answer>
+  <para>If they're not long enough, use
+  <literal>--num-callers</literal> to make them longer.</para>
+  <para>If they're not detailed enough, make sure you are
+  compiling with <literal>-g</literal> to add debug information.
+  And don't strip symbol tables (programs should be unstripped
+  unless you run 'strip' on them; some libraries ship
+  stripped).</para>
+
+  <para>Also, <literal>-fomit-frame-pointer</literal> and
+  <literal>-fstack-check</literal> can make stack traces
+  worse.</para>
+
+  <para>Some example sub-traces:</para>
+
+  <para>With debug information and unstripped (best):</para>
+<programlisting>
+Invalid write of size 1
+   at 0x80483BF: really (malloc1.c:20)
+   by 0x8048370: main (malloc1.c:9)
+</programlisting>
+
+  <para>With no debug information, unstripped:</para>
+<programlisting>
+Invalid write of size 1
+   at 0x80483BF: really (in /auto/homes/njn25/grind/head5/a.out)
+   by 0x8048370: main (in /auto/homes/njn25/grind/head5/a.out)
+</programlisting>
+
+  <para>With no debug information, stripped:</para>
+<programlisting>
+Invalid write of size 1
+   at 0x80483BF: (within /auto/homes/njn25/grind/head5/a.out)
+   by 0x8048370: (within /auto/homes/njn25/grind/head5/a.out)
+   by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
+   by 0x80482CC: (within /auto/homes/njn25/grind/head5/a.out)
+</programlisting>
+
+  <para>With debug information and -fomit-frame-pointer:</para>
+<programlisting>
+Invalid write of size 1
+   at 0x80483C4: really (malloc1.c:20)
+   by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
+   by 0x80482CC: ??? (start.S:81)
+</programlisting>
+
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
+<title>Memcheck doesn't find my bug</title>
+<qandaset id="qset.notfound">
+
+<qandaentry id="faq.hiddenbug">
+ <question>
+  <para>I try running "valgrind --tool=memcheck my_program" and
+  get Valgrind's startup message, but I don't get any errors and
+  I know my program has errors.</para>
+ </question>
+ <answer>
+  <para>By default, Valgrind only traces the top-level process.
+  So if your program spawns children, they won't be traced by
+  Valgrind by default.  Also, if your program is started by a
+  shell script, Perl script, or something similar, Valgrind will
+  trace the shell, or the Perl interpreter, or equivalent.</para>
+
+  <para>To trace child processes, use the
+  <literal>--trace-children=yes</literal> option.</para>
+
+  <para>If you are tracing large trees of processes, it can be
+  less disruptive to have the output sent over the network.  Give
+  Valgrind the flag
+  <literal>--log-socket=127.0.0.1:12345</literal> (if you want
+  logging output sent to <literal>port 12345</literal> on
+  <literal>localhost</literal>).  You can use the
+  valgrind-listener program to listen on that port:</para>
+<programlisting>
+valgrind-listener 12345
+</programlisting>
+
+  <para>Obviously you have to start the listener process first.
+  See the Manual: <ulink url="http://www.valgrind.org/docs/bookset/manual-core.out2file.html">Directing output to file</ulink> for more details.</para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.overruns">
+ <question>
+  <para>Why doesn't Memcheck find the array overruns in this program?</para>
+ </question>
+ <answer>
+<programlisting>
+int static[5];
+
+int main(void)
+{
+  int stack[5];
+
+  static[5] = 0;
+  stack [5] = 0;
+          
+  return 0;
+}
+</programlisting>
+  <para>Unfortunately, Memcheck doesn't do bounds checking on
+  static or stack arrays.  We'd like to, but it's just not
+  possible to do in a reasonable way that fits with how Memcheck
+  works.  Sorry.</para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.segfault">
+ <question>
+  <para>My program dies with a segmentation fault, but Memcheck
+  doesn't give any error messages before it, or none that look
+  related.</para>
+ </question>
+ <answer>
+  <para>One possibility is that your program accesses to memory
+  with inappropriate permissions set, such as writing to
+  read-only memory.  Maybe your program is writing to a static
+  string like this:</para>
+<programlisting>
+char* s = "hello";
+s[0] = 'j';
+</programlisting>
+
+  <para>or something similar.  Writing to read-only memory can
+  also apparently make LinuxThreads behave strangely.</para>
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="faq.misc" 
+       xreflabel="Miscellaneous">
+<title>Miscellaneous</title>
+<qandaset id="qset.misc">
+
+<qandaentry id="faq.writesupp">
+ <question>
+  <para>I tried writing a suppression but it didn't work.  Can
+  you write my suppression for me?</para>
+ </question>
+ <answer>
+  <para>Yes!  Use the
+  <computeroutput>--gen-suppressions=yes</computeroutput> feature
+  to spit out suppressions automatically for you.  You can then
+  edit them if you like, eg.  combining similar automatically
+  generated suppressions using wildcards like
+  <literal>'*'</literal>.</para>
+
+  <para>If you really want to write suppressions by hand, read
+  the manual carefully.  Note particularly that C++ function
+  names must be <literal>_mangled_</literal>.</para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.deflost">
+ <question>
+  <para>With Memcheck/Addrcheck's memory leak detector, what's
+  the difference between "definitely lost", "possibly lost",
+  "still reachable", and "suppressed"?</para>
+ </question>
+ <answer>
+  <para>The details are in the Manual: 
+   <ulink url="http://www.valgrind.org/docs/bookset/mc-manual.leaks.html">Memory leak detection</ulink>.</para>
+
+  <para>In short:</para>
+   <itemizedlist>
+    <listitem>
+     <para>"definitely lost" means your program is leaking memory
+     -- fix it!</para>
+    </listitem>
+    <listitem>
+     <para>"possibly lost" means your program is probably leaking
+     memory, unless you're doing funny things with
+     pointers.</para>
+    </listitem>
+    <listitem>
+     <para>"still reachable" means your program is probably ok --
+     it didn't free some memory it could have.  This is quite
+     common and often reasonable.  Don't use
+     <computeroutput>--show-reachable=yes</computeroutput> if you
+     don't want to see these reports.</para>
+    </listitem>
+    <listitem>
+     <para>"suppressed" means that a leak error has been
+     suppressed.  There are some suppressions in the default
+     suppression files.  You can ignore suppressed errors.</para>
+    </listitem>
+   </itemizedlist>
+  </answer>
+</qandaentry>
+
+
+</qandaset>
+</chapter>
+
+
+<!-- template 
+<chapter id="faq." 
+       xreflabel="xx">
+<title>xx</title>
+<qandaset id="qset.">
+
+<qandaentry id="faq.deflost">
+ <question>
+  <para></para>
+ </question>
+ <answer>
+  <para></para>
+ </answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+-->
+
+
+
+<chapter id="faq.help" xreflabel="How To Get Further Assistance">
+<title>How To Get Further Assistance</title>
+
+
+<para>Please read all of this section before posting.</para>
+
+<para>If you think an answer is incomplete or inaccurate, please
+e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
+
+<para>Read the appropriate section(s) of the Manual(s): 
+<ulink url="http://www.valgrind.org/docs/">Valgrind 
+Documentation</ulink>.</para>
+
+<para>Read the <ulink url="http://www.valgrind.org/docs/">Distribution Documents</ulink>.</para>
+
+<para><ulink url="http://search.gmane.org">Search</ulink> the 
+<ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name 
+<computeroutput>gmane.comp.debugging.valgrind</computeroutput>.</para>
+
+<para>Only when you have tried all of these things and are still stuck,
+should you post to the <ulink url="&vg-users-list;">valgrind-users
+mailing list</ulink>. In which case, please read the following
+carefully.  Making a complete posting will greatly increase the chances
+that an expert or fellow user reading it will have enough information
+and motivation to reply.</para>
+
+<para>Make sure you give full details of the problem,
+including the full output of <computeroutput>valgrind
+-v</computeroutput>, if applicable.  Also which Linux distribution
+you're using (Red Hat, Debian, etc) and its version number.</para>
+
+<para>You are in little danger of making your posting too long
+unless you include large chunks of valgrind's (unsuppressed)
+output, so err on the side of giving too much information.</para>
+
+<para>Clearly written subject lines and message bodies are appreciated,
+too.</para>
+
+<para>Finally, remember that, despite the fact that most of the
+community are very helpful and responsive to emailed questions,
+you are probably requesting help from unpaid volunteers, so you
+have no guarantee of receiving an answer.</para>
+
+</chapter>
+
+</book>
diff --git a/docs/xml/Makefile.am b/docs/xml/Makefile.am
new file mode 100644
index 0000000..c07286e
--- /dev/null
+++ b/docs/xml/Makefile.am
@@ -0,0 +1,10 @@
+EXTRA_DIST =  \
+	index.xml 		\
+	FAQ.xml 		\
+	manual.xml manual-intro.xml manual-core.xml \
+	writing-tools.xml	\
+	dist-docs.xml 		\
+	tech-docs.xml 		\
+	licenses.xml 		\
+	vg-entities.xml 	\
+	xml_help.txt
diff --git a/docs/xml/dist-docs.xml b/docs/xml/dist-docs.xml
new file mode 100644
index 0000000..6fb0244
--- /dev/null
+++ b/docs/xml/dist-docs.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id="dist" xreflabel="Distribution Documents">
+
+  <bookinfo>
+    <title>Distribution Documents</title>
+  </bookinfo>
+
+  <!-- Nb: because these are all text files, we have to wrap them in suitable
+       XML.  Hence the chapter/title stuff -->
+
+  <chapter id="dist.acknowledge" xreflabel="Acknowledgements">
+    <title>ACKNOWLEDGEMENTS</title>
+    <literallayout>
+      <xi:include href="../../ACKNOWLEDGEMENTS" parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.authors" xreflabel="Valgrind Developers">
+    <title id="dist.authors.title">AUTHORS</title>
+    <literallayout>
+        <xi:include href="../../AUTHORS" parse="text"  
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.install" xreflabel="Install">
+    <title>INSTALL</title>
+    <literallayout>
+      <xi:include href="../../INSTALL" parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.news" xreflabel="News">
+    <title>NEWS</title>
+    <literallayout>
+      <xi:include href="../../NEWS" parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.readme" xreflabel="Readme">
+    <title>README</title>
+    <literallayout>
+      <xi:include href="../../README" parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.readme-missing" 
+             xreflabel="Readme Missing Syscall or Ioctl">
+    <title>README_MISSING_SYSCALL_OR_IOCTL</title>
+    <literallayout>
+      <xi:include href="../../README_MISSING_SYSCALL_OR_IOCTL" 
+          parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.readme-packagers" 
+             xreflabel="Readme Packagers">
+    <title>README_PACKAGERS</title>
+    <literallayout>
+      <xi:include href="../../README_PACKAGERS" 
+          parse="text" 
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+
+  <chapter id="dist.todo" xreflabel="Todo">
+    <title>TODO</title>
+    <literallayout>
+      <xi:include href="../../TODO" 
+          parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </literallayout>
+    </chapter>
+</book>
diff --git a/docs/xml/index.xml b/docs/xml/index.xml
new file mode 100644
index 0000000..97d7231
--- /dev/null
+++ b/docs/xml/index.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[
+ <!-- various strings, dates etc. common to all docs -->
+ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities;
+]>
+
+<set lang="en" id="index">
+
+  <setinfo>
+    <title>Valgrind Documentation</title>
+    <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
+    <copyright>
+      <year>&vg-lifespan;</year>
+      <holder>
+       <link linkend="dist.authors" endterm="dist.authors.title"></link>
+      </holder>
+    </copyright>
+
+    <legalnotice>
+      <para>Permission is granted to copy, distribute and/or
+      modify this document under the terms of the GNU Free
+      Documentation License, Version 1.2 or any later version
+      published by the Free Software Foundation; with no
+      Invariant Sections, with no Front-Cover Texts, and with no
+      Back-Cover Texts.  A copy of the license is included in the
+      section entitled <xref linkend="license.gfdl"/>.</para>
+    </legalnotice>
+
+  </setinfo>
+
+  <!-- User Manual -->
+  <xi:include href="manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <!-- FAQ -->
+  <xi:include href="FAQ.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <!-- Technical Docs -->
+  <xi:include href="tech-docs.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <!-- Distribution Docs -->
+  <xi:include href="dist-docs.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <!-- GNU Licenses -->
+  <xi:include href="licenses.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+</set>
diff --git a/docs/xml/licenses.xml b/docs/xml/licenses.xml
new file mode 100644
index 0000000..2b31e9a
--- /dev/null
+++ b/docs/xml/licenses.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id="licenses" xreflabel="GNU Licenses">
+
+  <bookinfo>
+   <title>GNU Licenses</title>
+  </bookinfo>
+
+  <chapter id="license.gpl" xreflabel=" The GNU General Public License">
+    <title>The GNU General Public License</title>
+      <literallayout>
+      <xi:include href="../../COPYING" 
+          parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+      </literallayout>
+  </chapter>
+
+  <chapter id="license.gfdl" xreflabel="The GNU Free Documentation License">
+    <title>The GNU Free Documentation License</title>
+      <literallayout>
+      <xi:include href="../../COPYING.DOCS" 
+          parse="text"  
+          xmlns:xi="http://www.w3.org/2001/XInclude" />
+      </literallayout>
+  </chapter>
+
+</book>
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
new file mode 100644
index 0000000..6ed8eea
--- /dev/null
+++ b/docs/xml/manual-core.xml
@@ -0,0 +1,1951 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="manual-core" xreflabel="Valgrind's core">
+<title>Using and understanding the Valgrind core</title>
+
+<para>This section describes the Valgrind core services, flags
+and behaviours.  That means it is relevant regardless of what
+particular tool you are using.  A point of terminology: most
+references to "valgrind" in the rest of this section (Section 2)
+refer to the valgrind core services.</para>
+
+<sect1 id="manual-core.whatdoes" 
+       xreflabel="What Valgrind does with your program">
+<title>What Valgrind does with your program</title>
+
+<para>Valgrind is designed to be as non-intrusive as possible. It
+works directly with existing executables. You don't need to
+recompile, relink, or otherwise modify, the program to be
+checked.</para>
+
+<para>Simply put <computeroutput>valgrind
+--tool=tool_name</computeroutput> at the start of the command
+line normally used to run the program.  For example, if want to
+run the command <computeroutput>ls -l</computeroutput> using the
+heavyweight memory-checking tool Memcheck, issue the
+command:</para>
+
+<programlisting><![CDATA[
+valgrind --tool=memcheck ls -l]]></programlisting>
+
+<para>Regardless of which tool is in use, Valgrind takes control
+of your program before it starts.  Debugging information is read
+from the executable and associated libraries, so that error
+messages and other outputs can be phrased in terms of source code
+locations (if that is appropriate).</para>
+
+<para>Your program is then run on a synthetic x86 CPU provided by
+the Valgrind core.  As new code is executed for the first time,
+the core hands the code to the selected tool.  The tool adds its
+own instrumentation code to this and hands the result back to the
+core, which coordinates the continued execution of this
+instrumented code.</para>
+
+<para>The amount of instrumentation code added varies widely
+between tools.  At one end of the scale, Memcheck adds code to
+check every memory access and every value computed, increasing
+the size of the code at least 12 times, and making it run 25-50
+times slower than natively.  At the other end of the spectrum,
+the ultra-trivial "none" tool (a.k.a. Nulgrind) adds no
+instrumentation at all and causes in total "only" about a 4 times
+slowdown.</para>
+
+<para>Valgrind simulates every single instruction your program
+executes.  Because of this, the active tool checks, or profiles,
+not only the code in your application but also in all supporting
+dynamically-linked (<computeroutput>.so</computeroutput>-format)
+libraries, including the GNU C library, the X client libraries,
+Qt, if you work with KDE, and so on.</para>
+
+<para>If you're using one of the error-detection tools, Valgrind
+will often detect errors in libraries, for example the GNU C or
+X11 libraries, which you have to use.  You might not be
+interested in these errors, since you probably have no control
+over that code.  Therefore, Valgrind allows you to selectively
+suppress errors, by recording them in a suppressions file which
+is read when Valgrind starts up.  The build mechanism attempts to
+select suppressions which give reasonable behaviour for the libc
+and XFree86 versions detected on your machine.  To make it easier
+to write suppressions, you can use the
+<computeroutput>--gen-suppressions=yes</computeroutput> option
+which tells Valgrind to print out a suppression for each error
+that appears, which you can then copy into a suppressions
+file.</para>
+
+<para>Different error-checking tools report different kinds of
+errors.  The suppression mechanism therefore allows you to say
+which tool or tool(s) each suppression applies to.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.started" xreflabel="Getting started">
+<title>Getting started</title>
+
+<para>First off, consider whether it might be beneficial to
+recompile your application and supporting libraries with
+debugging info enabled (the <computeroutput>-g</computeroutput>
+flag).  Without debugging info, the best Valgrind tools will be
+able to do is guess which function a particular piece of code
+belongs to, which makes both error messages and profiling output
+nearly useless.  With <computeroutput>-g</computeroutput>, you'll
+hopefully get messages which point directly to the relevant
+source code lines.</para>
+
+<para>Another flag you might like to consider, if you are working
+with C++, is <computeroutput>-fno-inline</computeroutput>.  That
+makes it easier to see the function-call chain, which can help
+reduce confusion when navigating around large C++ apps.  For
+whatever it's worth, debugging OpenOffice.org with Memcheck is a
+bit easier when using this flag.</para>
+
+<para>You don't have to do this, but doing so helps Valgrind
+produce more accurate and less confusing error reports.  Chances
+are you're set up like this already, if you intended to debug
+your program with GNU gdb, or some other debugger.</para>
+
+<para>This paragraph applies only if you plan to use Memcheck: On
+rare occasions, optimisation levels at
+<computeroutput>-O2</computeroutput> and above have been observed
+to generate code which fools Memcheck into wrongly reporting
+uninitialised value errors.  We have looked in detail into fixing
+this, and unfortunately the result is that doing so would give a
+further significant slowdown in what is already a slow tool.  So
+the best solution is to turn off optimisation altogether.  Since
+this often makes things unmanagably slow, a plausible compromise
+is to use <computeroutput>-O</computeroutput>.  This gets you the
+majority of the benefits of higher optimisation levels whilst
+keeping relatively small the chances of false complaints from
+Memcheck.  All other tools (as far as we know) are unaffected by
+optimisation level.</para>
+
+<para>Valgrind understands both the older "stabs" debugging
+format, used by gcc versions prior to 3.1, and the newer DWARF2
+format used by gcc 3.1 and later.  We continue to refine and
+debug our debug-info readers, although the majority of effort
+will naturally enough go into the newer DWARF2 reader.</para>
+
+<para>When you're ready to roll, just run your application as you
+would normally, but place <computeroutput>valgrind
+--tool=tool_name</computeroutput> in front of your usual
+command-line invocation.  Note that you should run the real
+(machine-code) executable here.  If your application is started
+by, for example, a shell or perl script, you'll need to modify it
+to invoke Valgrind on the real executables.  Running such scripts
+directly under Valgrind will result in you getting error reports
+pertaining to <computeroutput>/bin/sh</computeroutput>,
+<computeroutput>/usr/bin/perl</computeroutput>, or whatever
+interpreter you're using.  This may not be what you want and can
+be confusing.  You can force the issue by giving the flag
+<computeroutput>--trace-children=yes</computeroutput>, but
+confusion is still likely.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.comment" xreflabel="The commentary">
+<title>The commentary</title>
+
+<para>Valgrind tools write a commentary, a stream of text,
+detailing error reports and other significant events.  All lines
+in the commentary have following form:
+
+<programlisting><![CDATA[
+==12345== some-message-from-Valgrind]]></programlisting>
+</para>
+
+<para>The <computeroutput>12345</computeroutput> is the process
+ID.  This scheme makes it easy to distinguish program output from
+Valgrind commentary, and also easy to differentiate commentaries
+from different processes which have become merged together, for
+whatever reason.</para>
+
+<para>By default, Valgrind tools write only essential messages to
+the commentary, so as to avoid flooding you with information of
+secondary importance.  If you want more information about what is
+happening, re-run, passing the
+<computeroutput>-v</computeroutput> flag to Valgrind.</para>
+
+<para>You can direct the commentary to three different
+places:</para>
+
+<orderedlist>
+
+ <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
+   <para>The default: send it to a file descriptor, which is by
+   default 2 (stderr).  So, if you give the core no options, it
+   will write commentary to the standard error stream.  If you
+   want to send it to some other file descriptor, for example
+   number 9, you can specify
+   <computeroutput>--log-fd=9</computeroutput>.</para>
+  </listitem>
+
+  <listitem id="manual-core.out2file" 
+            xreflabel="Directing output to file">
+   <para>A less intrusive option is to write the commentary to a
+   file, which you specify by
+   <computeroutput>--log-file=filename</computeroutput>.  Note
+   carefully that the commentary is <command>not</command>
+   written to the file you specify, but instead to one called
+   <computeroutput>filename.pid12345</computeroutput>, if for
+   example the pid of the traced process is 12345.  This is
+   helpful when valgrinding a whole tree of processes at once,
+   since it means that each process writes to its own logfile,
+   rather than the result being jumbled up in one big
+   logfile.</para>
+  </listitem>
+
+  <listitem id="manual-core.out2socket" 
+            xreflabel="Directing output to network socket">
+   <para>The least intrusive option is to send the commentary to
+   a network socket.  The socket is specified as an IP address
+   and port number pair, like this:
+   <computeroutput>--log-socket=192.168.0.1:12345</computeroutput>
+   if you want to send the output to host IP 192.168.0.1 port
+   12345 (I have no idea if 12345 is a port of pre-existing
+   significance).  You can also omit the port number:
+   <computeroutput>--log-socket=192.168.0.1</computeroutput>, in
+   which case a default port of 1500 is used.  This default is
+   defined by the constant
+   <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
+   sources.</para>
+
+   <para>Note, unfortunately, that you have to use an IP address
+   here, rather than a hostname.</para>
+
+   <para>Writing to a network socket is pretty useless if you
+   don't have something listening at the other end.  We provide a
+   simple listener program,
+   <computeroutput>valgrind-listener</computeroutput>, which
+   accepts connections on the specified port and copies whatever
+   it is sent to stdout.  Probably someone will tell us this is a
+   horrible security risk.  It seems likely that people will
+   write more sophisticated listeners in the fullness of
+   time.</para>
+
+   <para>valgrind-listener can accept simultaneous connections
+   from up to 50 valgrinded processes.  In front of each line of
+   output it prints the current number of active connections in
+   round brackets.</para>
+
+   <para>valgrind-listener accepts two command-line flags:</para>
+    <itemizedlist>
+     <listitem>
+      <para><computeroutput>-e</computeroutput> or 
+      <computeroutput>--exit-at-zero</computeroutput>: when the
+      number of connected processes falls back to zero, exit.
+      Without this, it will run forever, that is, until you send
+      it Control-C.</para>
+     </listitem>
+     <listitem>
+      <para><computeroutput>portnumber</computeroutput>: changes
+      the port it listens on from the default (1500).  The
+      specified port must be in the range 1024 to 65535.  The
+      same restriction applies to port numbers specified by a
+      <computeroutput>--log-socket=</computeroutput> to Valgrind
+      itself.</para>
+     </listitem>
+    </itemizedlist>
+
+    <para>If a valgrinded process fails to connect to a listener,
+    for whatever reason (the listener isn't running, invalid or
+    unreachable host or port, etc), Valgrind switches back to
+    writing the commentary to stderr.  The same goes for any
+    process which loses an established connection to a listener.
+    In other words, killing the listener doesn't kill the
+    processes sending data to it.</para>
+  </listitem>
+ </orderedlist>
+
+<para>Here is an important point about the relationship between
+the commentary and profiling output from tools.  The commentary
+contains a mix of messages from the Valgrind core and the
+selected tool.  If the tool reports errors, it will report them
+to the commentary.  However, if the tool does profiling, the
+profile data will be written to a file of some kind, depending on
+the tool, and independent of what
+<computeroutput>--log-*</computeroutput> options are in force.
+The commentary is intended to be a low-bandwidth, human-readable
+channel.  Profiling data, on the other hand, is usually
+voluminous and not meaningful without further processing, which
+is why we have chosen this arrangement.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.report" xreflabel="Reporting of errors">
+<title>Reporting of errors</title>
+
+<para>When one of the error-checking tools (Memcheck, Addrcheck,
+Helgrind) detects something bad happening in the program, an
+error message is written to the commentary.  For example:</para>
+
+<programlisting><![CDATA[
+==25832== Invalid read of size 4
+==25832==    at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45)
+==25832==    by 0x80487AF: main (bogon.cpp:66)
+==25832==    by 0x40371E5E: __libc_start_main (libc-start.c:129)
+==25832==    by 0x80485D1: (within /home/sewardj/newmat10/bogon)
+==25832==    Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting>
+
+<para>This message says that the program did an illegal 4-byte
+read of address 0xBFFFF74C, which, as far as Memcheck can tell,
+is not a valid stack address, nor corresponds to any currently
+malloc'd or free'd blocks.  The read is happening at line 45 of
+<filename>bogon.cpp</filename>, called from line 66 of the same
+file, etc.  For errors associated with an identified
+malloc'd/free'd block, for example reading free'd memory,
+Valgrind reports not only the location where the error happened,
+but also where the associated block was malloc'd/free'd.</para>
+
+<para>Valgrind remembers all error reports.  When an error is
+detected, it is compared against old reports, to see if it is a
+duplicate.  If so, the error is noted, but no further commentary
+is emitted.  This avoids you being swamped with bazillions of
+duplicate error reports.</para>
+
+<para>If you want to know how many times each error occurred, run
+with the <computeroutput>-v</computeroutput> option.  When
+execution finishes, all the reports are printed out, along with,
+and sorted by, their occurrence counts.  This makes it easy to
+see which errors have occurred most frequently.</para>
+
+<para>Errors are reported before the associated operation
+actually happens.  If you're using a tool (Memcheck, Addrcheck)
+which does address checking, and your program attempts to read
+from address zero, the tool will emit a message to this effect,
+and the program will then duly die with a segmentation
+fault.</para>
+
+<para>In general, you should try and fix errors in the order that
+they are reported.  Not doing so can be confusing.  For example,
+a program which copies uninitialised values to several memory
+locations, and later uses them, will generate several error
+messages, when run on Memcheck.  The first such error message may
+well give the most direct clue to the root cause of the
+problem.</para>
+
+<para>The process of detecting duplicate errors is quite an
+expensive one and can become a significant performance overhead
+if your program generates huge quantities of errors.  To avoid
+serious problems here, Valgrind will simply stop collecting
+errors after 300 different errors have been seen, or 30000 errors
+in total have been seen.  In this situation you might as well
+stop your program and fix it, because Valgrind won't tell you
+anything else useful after this.  Note that the 300/30000 limits
+apply after suppressed errors are removed.  These limits are
+defined in <filename>vg_include.h</filename> and can be increased
+if necessary.</para>
+
+<para>To avoid this cutoff you can use the
+<computeroutput>--error-limit=no</computeroutput> flag.  Then
+Valgrind will always show errors, regardless of how many there
+are.  Use this flag carefully, since it may have a dire effect on
+performance.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.suppress" xreflabel="Suppressing errors">
+<title>Suppressing errors</title>
+
+<para>The error-checking tools detect numerous problems in the
+base libraries, such as the GNU C library, and the XFree86 client
+libraries, which come pre-installed on your GNU/Linux system.
+You can't easily fix these, but you don't want to see these
+errors (and yes, there are many!)  So Valgrind reads a list of
+errors to suppress at startup.  A default suppression file is
+cooked up by the <computeroutput>./configure</computeroutput>
+script when the system is built.</para>
+
+<para>You can modify and add to the suppressions file at your
+leisure, or, better, write your own.  Multiple suppression files
+are allowed.  This is useful if part of your project contains
+errors you can't or don't want to fix, yet you don't want to
+continuously be reminded of them.</para>
+
+<formalpara><title>Note:</title>
+<para>By far the easiest way to add suppressions is to use the
+<computeroutput>--gen-suppressions=yes</computeroutput> flag
+described in <xref linkend="manual-core.flags"/>.</para>
+</formalpara>
+
+<para>Each error to be suppressed is described very specifically,
+to minimise the possibility that a suppression-directive
+inadvertantly suppresses a bunch of similar errors which you did
+want to see.  The suppression mechanism is designed to allow
+precise yet flexible specification of errors to suppress.</para>
+
+<para>If you use the <computeroutput>-v</computeroutput> flag, at
+the end of execution, Valgrind prints out one line for each used
+suppression, giving its name and the number of times it got used.
+Here's the suppressions used by a run of <computeroutput>valgrind
+--tool=memcheck ls -l</computeroutput>:</para>
+
+<programlisting><![CDATA[
+--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r
+--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r
+--27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object]]></programlisting>
+
+<para>Multiple suppressions files are allowed.  By default,
+Valgrind uses
+<computeroutput>$PREFIX/lib/valgrind/default.supp</computeroutput>.
+You can ask to add suppressions from another file, by specifying
+<computeroutput>--suppressions=/path/to/file.supp</computeroutput>.
+</para>
+
+<para>If you want to understand more about suppressions, look at
+an existing suppressions file whilst reading the following
+documentation.  The file
+<computeroutput>glibc-2.2.supp</computeroutput>, in the source
+distribution, provides some good examples.</para>
+
+<para>Each suppression has the following components:</para>
+
+ <itemizedlist>
+
+  <listitem>
+   <para>First line: its name.  This merely gives a handy name to
+   the suppression, by which it is referred to in the summary of
+   used suppressions printed out when a program finishes.  It's
+   not important what the name is; any identifying string will
+   do.</para>
+  </listitem>
+
+  <listitem>
+   <para>Second line: name of the tool(s) that the suppression is
+   for (if more than one, comma-separated), and the name of the
+   suppression itself, separated by a colon (Nb: no spaces are
+   allowed), eg:</para>
+
+<programlisting><![CDATA[
+tool_name1,tool_name2:suppression_name]]></programlisting>
+
+   <para>Recall that Valgrind-2.0.X is a modular system, in which
+   different instrumentation tools can observe your program
+   whilst it is running.  Since different tools detect different
+   kinds of errors, it is necessary to say which tool(s) the
+   suppression is meaningful to.</para>
+
+   <para>Tools will complain, at startup, if a tool does not
+   understand any suppression directed to it.  Tools ignore
+   suppressions which are not directed to them.  As a result, it
+   is quite practical to put suppressions for all tools into the
+   same suppression file.</para>
+
+   <para>Valgrind's core can detect certain PThreads API errors,
+   for which this line reads:</para>
+
+<programlisting><![CDATA[
+core:PThread]]></programlisting>
+  </listitem>
+
+  <listitem>
+   <para>Next line: a small number of suppression types have
+   extra information after the second line (eg. the
+   <computeroutput>Param</computeroutput> suppression for
+   Memcheck)</para>
+  </listitem>
+
+  <listitem>
+   <para>Remaining lines: This is the calling context for the
+   error -- the chain of function calls that led to it.  There
+   can be up to four of these lines.</para>
+
+   <para>Locations may be either names of shared
+   objects/executables or wildcards matching function names.
+   They begin <computeroutput>obj:</computeroutput> and
+   <computeroutput>fun:</computeroutput> respectively.  Function
+   and object names to match against may use the wildcard
+   characters <computeroutput>*</computeroutput> and
+   <computeroutput>?</computeroutput>.</para>
+
+   <formalpara><title>Important note:</title>
+    <para>C++ function names must be <command>mangled</command>.
+    If you are writing suppressions by hand, use the
+    <computeroutput>--demangle=no</computeroutput> option to get
+    the mangled names in your error messages.</para>
+   </formalpara>
+  </listitem>
+
+  <listitem>
+   <para>Finally, the entire suppression must be between curly
+   braces. Each brace must be the first character on its own
+   line.</para>
+  </listitem>
+
+ </itemizedlist>
+
+<para>A suppression only suppresses an error when the error
+matches all the details in the suppression.  Here's an
+example:</para>
+
+<programlisting><![CDATA[
+{
+  __gconv_transform_ascii_internal/__mbrtowc/mbtowc
+  Memcheck:Value4
+  fun:__gconv_transform_ascii_internal
+  fun:__mbr*toc
+  fun:mbtowc
+}]]></programlisting>
+
+
+<para>What it means is: for Memcheck only, suppress a
+use-of-uninitialised-value error, when the data size is 4, when
+it occurs in the function
+<computeroutput>__gconv_transform_ascii_internal</computeroutput>,
+when that is called from any function of name matching
+<computeroutput>__mbr*toc</computeroutput>, when that is called
+from <computeroutput>mbtowc</computeroutput>.  It doesn't apply
+under any other circumstances.  The string by which this
+suppression is identified to the user is
+<computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para>
+
+<para>(See <xref linkend="mc-manual.suppfiles"/> for more details
+on the specifics of Memcheck's suppression kinds.)</para>
+
+<para>Another example, again for the Memcheck tool:</para>
+
+<programlisting><![CDATA[
+{
+  libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
+  Memcheck:Value4
+  obj:/usr/X11R6/lib/libX11.so.6.2
+  obj:/usr/X11R6/lib/libX11.so.6.2
+  obj:/usr/X11R6/lib/libXaw.so.7.0
+}]]></programlisting>
+
+<para>Suppress any size 4 uninitialised-value error which occurs
+anywhere in <computeroutput>libX11.so.6.2</computeroutput>, when
+called from anywhere in the same library, when called from
+anywhere in <computeroutput>libXaw.so.7.0</computeroutput>.  The
+inexact specification of locations is regrettable, but is about
+all you can hope for, given that the X11 libraries shipped with
+Red Hat 7.2 have had their symbol tables removed.</para>
+
+<para>Note: since the above two examples did not make it clear,
+you can freely mix the <computeroutput>obj:</computeroutput> and
+<computeroutput>fun:</computeroutput> styles of description
+within a single suppression record.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.flags" 
+       xreflabel="Command-line flags for the Valgrind core">
+<title>Command-line flags for the Valgrind core</title>
+
+<para>As mentioned above, Valgrind's core accepts a common set of
+flags.  The tools also accept tool-specific flags, which are
+documented seperately for each tool.</para>
+
+<para>You invoke Valgrind like this:</para>
+
+<programlisting><![CDATA[
+valgrind --tool=<emphasis>tool_name</emphasis> [valgrind-options] your-prog [your-prog options]]]></programlisting>
+
+<para>Valgrind's default settings succeed in giving reasonable
+behaviour in most cases.  We group the available options by rough
+categories.</para>
+
+<sect2 id="manual-core.toolopts" xreflabel="Tool-selection option">
+<title>Tool-selection option</title>
+
+<para>The single most important option.</para>
+  <itemizedlist>
+   <listitem>
+    <para><computeroutput>--tool=name</computeroutput></para>
+    <para>Run the Valgrind tool called <emphasis>name</emphasis>,
+    e.g. Memcheck, Addrcheck, Cachegrind, etc.</para>
+   </listitem>
+  </itemizedlist>
+</sect2>
+
+<sect2 id="manual-core.basicopts" xreflabel="Basic Options">
+<title>Basic Options</title>
+
+<para>These options work with all tools.</para>
+
+ <itemizedlist>
+   <listitem>
+    <para><computeroutput>--help</computeroutput></para>
+    <para>Show help for all options, both for the core and for
+    the selected tool.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--help-debug</computeroutput></para>
+    <para>Same as <computeroutput>--help</computeroutput>, but
+     also lists debugging options which usually are only of use
+     to developers.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--version</computeroutput></para>
+    <para>Show the version number of the Valgrind core.  Tools
+    can have their own version numbers.  There is a scheme in
+    place to ensure that tools only execute when the core version
+    is one they are known to work with.  This was done to
+    minimise the chances of strange problems arising from
+    tool-vs-core version incompatibilities.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>-v --verbose</computeroutput></para>
+    <para>Be more verbose.  Gives extra information on various
+    aspects of your program, such as: the shared objects loaded,
+    the suppressions used, the progress of the instrumentation
+    and execution engines, and warnings about unusual behaviour.
+    Repeating the flag increases the verbosity level.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>-q --quiet</computeroutput></para>
+    <para>Run silently, and only print error messages.  Useful if
+    you are running regression tests or have some other automated
+    test machinery.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-children=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-children=yes</computeroutput></para>
+    <para>When enabled, Valgrind will trace into child processes.
+    This is confusing and usually not what you want, so is
+    disabled by default.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--log-fd=&lt;number&gt;</computeroutput>
+    [default: 2, stderr]</para>
+    <para>Specifies that Valgrind should send all of its messages
+    to the specified file descriptor.  The default, 2, is the
+    standard error channel (stderr).  Note that this may
+    interfere with the client's own use of stderr.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--log-file=&lt;filename&gt;</computeroutput></para>
+    <para>Specifies that Valgrind should send all of its messages
+    to the specified file.  In fact, the file name used is
+    created by concatenating the text
+    <computeroutput>filename</computeroutput>, ".pid" and the
+    process ID, so as to create a file per process.  The
+    specified file name may not be the empty string.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--log-socket=&lt;ip-address:port-number&gt;</computeroutput></para>
+    <para>Specifies that Valgrind should send all of its messages
+    to the specified port at the specified IP address.  The port
+    may be omitted, in which case port 1500 is used.  If a
+    connection cannot be made to the specified socket, Valgrind
+    falls back to writing output to the standard error (stderr).
+    This option is intended to be used in conjunction with the
+    <computeroutput>valgrind-listener</computeroutput> program.
+    For further details, see <xref linkend="manual-core.comment"/>.</para>
+   </listitem>
+
+  </itemizedlist>
+ </sect2>
+
+
+<sect2 id="manual-core.erropts" xreflabel="Error-related Options">
+<title>Error-related options</title>
+
+<para>These options are used by all tools that can report
+errors, e.g. Memcheck, but not Cachegrind.</para>
+
+  <itemizedlist>
+
+   <listitem>
+    <para><computeroutput>--demangle=no</computeroutput></para>
+    <para><computeroutput>--demangle=yes</computeroutput> [default]</para>
+    <para>Disable/enable automatic demangling (decoding) of C++
+    names.  Enabled by default.  When enabled, Valgrind will
+    attempt to translate encoded C++ procedure names back to
+    something approaching the original.  The demangler handles
+    symbols mangled by g++ versions 2.X and 3.X.</para>
+
+    <para>An important fact about demangling is that function
+    names mentioned in suppressions files should be in their
+    mangled form.  Valgrind does not demangle function names when
+    searching for applicable suppressions, because to do
+    otherwise would make suppressions file contents dependent on
+    the state of Valgrind's demangling machinery, and would also
+    be slow and pointless.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--num-callers=&lt;number&gt;</computeroutput> [default=4]</para>
+    <para>By default, Valgrind shows four levels of function call
+    names to help you identify program locations.  You can change
+    that number with this option.  This can help in determining
+    the program's location in deeply-nested call chains.  Note
+    that errors are commoned up using only the top three function
+    locations (the place in the current function, and that of its
+    two immediate callers).  So this doesn't affect the total
+    number of errors reported.</para>
+
+    <para>The maximum value for this is 50.  Note that higher
+    settings will make Valgrind run a bit more slowly and take a
+    bit more memory, but can be useful when working with programs
+    with deeply-nested call chains.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--error-limit=yes</computeroutput>
+    [default]</para>
+    <para><computeroutput>--error-limit=no</computeroutput></para>
+    <para>When enabled, Valgrind stops reporting errors after
+    30000 in total, or 300 different ones, have been seen.  This
+    is to stop the error tracking machinery from becoming a huge
+    performance overhead in programs with many errors.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--show-below-main=yes</computeroutput></para>
+    <para><computeroutput>--show-below-main=no</computeroutput>
+    [default]</para>
+    <para>By default, stack traces for errors do not show any
+    functions that appear beneath
+    <computeroutput>main()</computeroutput>; most of the time
+    it's uninteresting C library stuff.  If this option is
+    enabled, these entries below
+    <computeroutput>main()</computeroutput> will be shown.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--suppressions=&lt;filename&gt;</computeroutput>
+    [default: $PREFIX/lib/valgrind/default.supp]</para>
+    <para>Specifies an extra file from which to read descriptions
+    of errors to suppress.  You may use as many extra
+    suppressions files as you like.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--gen-suppressions=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--gen-suppressions=yes</computeroutput></para>
+    <para>When enabled, Valgrind will pause after every error
+    shown, and print the line: <computeroutput>---- Print
+    suppression ?  --- [Return/N/n/Y/y/C/c] ----</computeroutput></para>
+
+    <para>The prompt's behaviour is the same as for the 
+    <computeroutput>--db-attach</computeroutput> option.</para>
+
+    <para>If you choose to, Valgrind will print out a suppression
+    for this error.  You can then cut and paste it into a
+    suppression file if you don't want to hear about the error in
+    the future.</para>
+
+    <para>This option is particularly useful with C++ programs,
+    as it prints out the suppressions with mangled names, as
+    required.</para>
+
+    <para>Note that the suppressions printed are as specific as
+    possible.  You may want to common up similar ones, eg. by
+    adding wildcards to function names.  Also, sometimes two
+    different errors are suppressed by the same suppression, in
+    which case Valgrind will output the suppression more than
+    once, but you only need to have one copy in your suppression
+    file (but having more than one won't cause problems).  Also,
+    the suppression name is given as <computeroutput>&lt;insert a
+    suppression name here&gt;</computeroutput>; the name doesn't
+    really matter, it's only used with the
+    <computeroutput>-v</computeroutput> option which prints out
+    all used suppression records.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--track-fds=no</computeroutput> [default]</para>
+    <para><computeroutput>--track-fds=yes</computeroutput></para>
+    <para>When enabled, Valgrind will print out a list of open
+    file descriptors on exit.  Along with each file descriptor,
+    Valgrind prints out a stack backtrace of where the file was
+    opened and any details relating to the file descriptor such
+    as the file name or socket details.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--db-attach=no</computeroutput> [default]</para>
+    <para><computeroutput>--db-attach=yes</computeroutput></para>
+    <para>When enabled, Valgrind will pause after every error
+    shown, and print the line: <computeroutput>---- Attach to
+    debugger ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></para>
+
+    <para>Pressing <literal>Ret</literal>, or 
+    <literal>N Ret</literal> or <literal>n Ret</literal>, causes
+    Valgrind not to start a debugger for this error.</para>
+
+    <para><literal>Y Ret</literal> or <literal>y Ret</literal>
+    causes Valgrind to start a debugger, for the program at this
+    point.  When you have finished with the debugger, quit from
+    it, and the program will continue.  Trying to continue from
+    inside the debugger doesn't work.</para>
+
+    <para><literal>C Ret</literal> or <literal>c Ret</literal>
+    causes Valgrind not to start a debugger, and not to ask
+    again.</para>
+
+    <formalpara>
+     <title>Note:</title>
+     <para><computeroutput>--db-attach=yes</computeroutput>
+     conflicts with
+     <computeroutput>--trace-children=yes</computeroutput>.  You
+     can't use them together.  Valgrind refuses to start up in
+     this situation.</para>
+    </formalpara>
+    <para>1 May 2002: this is a historical relic which could be
+    easily fixed if it gets in your way.  Mail me and complain if
+    this is a problem for you.</para> <para>Nov 2002: if you're
+    sending output to a logfile or to a network socket, I guess
+    this option doesn't make any sense.  Caveat emptor.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--db-command=&lt;command&gt;</computeroutput>
+    [default: gdb -nw %f %p]</para>
+    <para>This specifies how Valgrind will invoke the debugger.
+    By default it will use whatever GDB is detected at build
+    time, which is usually
+    <computeroutput>/usr/bin/gdb</computeroutput>.  Using this
+    command, you can specify some alternative command to invoke
+    the debugger you want to use.</para>
+
+    <para>The command string given can include one or instances
+    of the <literal>%p</literal> and <literal>%f</literal>
+    expansions. Each instance of <literal>%p</literal> expands to
+    the PID of the process to be debugged and each instance of
+    <literal>%f</literal> expands to the path to the executable
+    for the process to be debugged.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--input-fd=&lt;number&gt;</computeroutput>
+    [default=0, stdin]</para>
+    <para>When using
+    <computeroutput>--db-attach=yes</computeroutput> and
+    <computeroutput>--gen-suppressions=yes</computeroutput>,
+    Valgrind will stop so as to read keyboard input from you,
+    when each error occurs.  By default it reads from the
+    standard input (stdin), which is problematic for programs
+    which close stdin.  This option allows you to specify an
+    alternative file descriptor from which to read input.</para>
+   </listitem>
+
+  </itemizedlist>
+</sect2>
+
+<sect2 id="manual-core.mallocopts" xreflabel="malloc()-related Options">
+<title><computeroutput>malloc()</computeroutput>-related Options</title>
+
+<para>For tools that use their own version of
+<computeroutput>malloc()</computeroutput> (e.g. Memcheck and
+Addrcheck), the following options apply.</para>
+
+  <itemizedlist>
+
+   <listitem>
+    <para><computeroutput>--alignment=&lt;number&gt;</computeroutput>
+    [default: 8]</para>
+    <para>By default Valgrind's
+    <computeroutput>malloc</computeroutput>,
+    <computeroutput>realloc</computeroutput>, etc, return 4-byte
+    aligned addresses.  These are suitable for any accesses on
+    x86 processors.  Some programs might however assume that
+    <computeroutput>malloc</computeroutput> et al return 8- or
+    more aligned memory.  The supplied value must be between 4
+    and 4096 inclusive, and must be a power of two.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--sloppy-malloc=no</computeroutput>
+     [default]</para>
+    <para><computeroutput>--sloppy-malloc=yes</computeroutput></para>
+    <para>When enabled, all requests for malloc/calloc are
+    rounded up to a whole number of machine words -- in other
+    words, made divisible by 4.  For example, a request for 17
+    bytes of space would result in a 20-byte area being made
+    available.  This works around bugs in sloppy libraries which
+    assume that they can safely rely on malloc/calloc requests
+    being rounded up in this fashion.  Without the workaround,
+    these libraries tend to generate large numbers of errors when
+    they access the ends of these areas.</para>
+
+    <para>Valgrind snapshots dated 17 Feb 2002 and later are
+    cleverer about this problem, and you should no longer need to
+    use this flag.  To put it bluntly, if you do need to use this
+    flag, your program violates the ANSI C semantics defined for
+    <computeroutput>malloc</computeroutput> and
+    <computeroutput>free</computeroutput>, even if it appears to
+    work correctly, and you should fix it, at least if you hope
+    for maximum portability.</para>
+   </listitem>
+  </itemizedlist>
+
+ </sect2>
+
+
+ <sect2 id="manual-core.rareopts" xreflabel="Rare Options">
+  <title>Rare Options</title>
+
+  <para>These options apply to all tools, as they affect certain
+  obscure workings of the Valgrind core.  Most people won't need
+  to use these.</para>
+
+  <itemizedlist>
+
+   <listitem>
+    <para><computeroutput>--run-libc-freeres=yes</computeroutput>
+     [default]</para>
+    <para><computeroutput>--run-libc-freeres=no</computeroutput></para>
+    <para>The GNU C library
+    (<computeroutput>libc.so</computeroutput>), which is used by
+    all programs, may allocate memory for its own uses.  Usually
+    it doesn't bother to free that memory when the program ends -
+    there would be no point, since the Linux kernel reclaims all
+    process resources when a process exits anyway, so it would
+    just slow things down.</para>
+
+    <para>The glibc authors realised that this behaviour causes
+    leak checkers, such as Valgrind, to falsely report leaks in
+    glibc, when a leak check is done at exit.  In order to avoid
+    this, they provided a routine called
+    <computeroutput>__libc_freeres</computeroutput> specifically
+    to make glibc release all memory it has allocated.  Memcheck
+    and Addrcheck therefore try and run
+    <computeroutput>__libc_freeres</computeroutput> at
+    exit.</para>
+
+    <para>Unfortunately, in some versions of glibc,
+    <computeroutput>__libc_freeres</computeroutput> is
+    sufficiently buggy to cause segmentation faults.  This is
+    particularly noticeable on Red Hat 7.1.  So this flag is
+    provided in order to inhibit the run of
+    <computeroutput>__libc_freeres</computeroutput>.  If your
+    program seems to run fine on Valgrind, but segfaults at exit,
+    you may find that
+    <computeroutput>--run-libc-freeres=no</computeroutput> fixes
+    that, although at the cost of possibly falsely reporting
+    space leaks in
+    <computeroutput>libc.so</computeroutput>.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--weird-hacks=hack1,hack2,...</computeroutput></para>
+    <para>Pass miscellaneous hints to Valgrind which slightly
+    modify the simulated behaviour in nonstandard or dangerous
+    ways, possibly to help the simulation of strange features.
+    By default no hacks are enabled.  Use with caution!
+    Currently known hacks are:</para>
+    <itemizedlist>
+     <listitem><para><computeroutput>lax-ioctls</computeroutput></para>
+      <para>Be very lax about ioctl handling; the only assumption
+      is that the size is correct. Doesn't require the full
+      buffer to be initialized when writing.  Without this, using
+      some device drivers with a large number of strange ioctl
+      commands becomes very tiresome.</para>
+     </listitem>
+    </itemizedlist>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--signal-polltime=&lt;time&gt;</computeroutput>
+    [default=50]</para>
+    <para>How often to poll for signals (in milliseconds).  Only
+    applies for older kernels that need signal routing.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--lowlat-signals=no</computeroutput>
+     [default]</para>
+    <para><computeroutput>--lowlat-signals=yes</computeroutput></para>
+    <para>Improve wake-up latency when a thread receives a signal.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--lowlat-syscalls=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--lowlat-syscalls=yes</computeroutput></para>
+    <para>Improve wake-up latency when a thread's syscall
+    completes.</para>
+   </listitem>
+
+  </itemizedlist>
+</sect2>
+
+
+<sect2 id="manual-core.debugopts" xreflabel="Debugging Valgrind Options">
+<title>Debugging Valgrind Options</title>
+
+<para>There are also some options for debugging Valgrind itself.
+You shouldn't need to use them in the normal run of things.
+Nevertheless:</para>
+
+ <itemizedlist>
+
+   <listitem>
+    <para><computeroutput>--single-step=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--single-step=yes</computeroutput></para>
+    <para>When enabled, each x86 insn is translated separately
+    into instrumented code.  When disabled, translation is done
+    on a per-basic-block basis, giving much better
+    translations.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--optimise=no</computeroutput></para>
+    <para><computeroutput>--optimise=yes</computeroutput> [default]</para>
+    <para>When enabled, various improvements are applied to the
+    intermediate code, mainly aimed at allowing the simulated
+    CPU's registers to be cached in the real CPU's registers over
+    several simulated instructions.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--profile=no</computeroutput></para>
+    <para><computeroutput>--profile=yes</computeroutput> [default]</para>
+    <para>When enabled, does crude internal profiling of Valgrind
+    itself.  This is not for profiling your programs.  Rather it
+    is to allow the developers to assess where Valgrind is
+    spending its time.  The tools must be built for profiling for
+    this to work.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-syscalls=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-syscalls=yes</computeroutput></para>
+    <para>Enable/disable tracing of system call intercepts.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-signals=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-signals=yes</computeroutput></para>
+    <para>Enable/disable tracing of signal handling.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-sched=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-sched=yes</computeroutput></para>
+    <para>Enable/disable tracing of thread scheduling events.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-pthread=none</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-pthread=some</computeroutput></para>
+    <para><computeroutput>--trace-pthread=all</computeroutput></para>
+    <para>Specifies amount of trace detail for pthread-related
+    events.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-symtab=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-symtab=yes</computeroutput></para>
+    <para>Enable/disable tracing of symbol table reading.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-malloc=no</computeroutput>
+    [default]</para>
+    <para><computeroutput>--trace-malloc=yes</computeroutput></para>
+    <para>Enable/disable tracing of malloc/free (et al)
+    intercepts.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--trace-codegen=XXXXX</computeroutput>
+    [default: 00000]</para>
+    <para>Enable/disable tracing of code generation.  Code can be
+    printed at five different stages of translation; each
+    <computeroutput>X</computeroutput> element must be 0 or
+    1.</para>
+   </listitem>
+
+   <listitem>
+    <para><computeroutput>--dump-error=&lt;number></computeroutput>
+    [default: inactive]</para>
+    <para>After the program has exited, show gory details of the
+    translation of the basic block containing the &lt;number>'th
+    error context.  When used with
+    <computeroutput>--single-step=yes</computeroutput>, can show
+    the exact x86 instruction causing an error.  This is all
+    fairly dodgy and doesn't work at all if threads are
+    involved.</para>
+   </listitem>
+
+  </itemizedlist>
+</sect2>
+
+
+<sect2 id="manual-core.defopts" xreflabel="Setting default options">
+<title>Setting default Options</title>
+
+<para>Note that Valgrind also reads options from three places:</para>
+
+  <orderedlist>
+   <listitem>
+    <para>The file <computeroutput>~/.valgrindrc</computeroutput></para>
+   </listitem>
+
+   <listitem>
+    <para>The environment variable
+    <computeroutput>$VALGRIND_OPTS</computeroutput></para>
+   </listitem>
+
+   <listitem>
+    <para>The file <computeroutput>./.valgrindrc</computeroutput></para>
+   </listitem>
+  </orderedlist>
+
+<para>These are processed in the given order, before the
+command-line options.  Options processed later override those
+processed earlier; for example, options in
+<computeroutput>./.valgrindrc</computeroutput> will take
+precedence over those in
+<computeroutput>~/.valgrindrc</computeroutput>.  The first two
+are particularly useful for setting the default tool to
+use.</para>
+
+<para>Any tool-specific options put in
+<computeroutput>$VALGRIND_OPTS</computeroutput> or the
+<computeroutput>.valgrindrc</computeroutput> files should be
+prefixed with the tool name and a colon.  For example, if you
+want Memcheck to always do leak checking, you can put the
+following entry in <literal>~/.valgrindrc</literal>:</para>
+
+<programlisting><![CDATA[
+--memcheck:leak-check=yes]]></programlisting>
+
+<para>This will be ignored if any tool other than Memcheck is
+run.  Without the <computeroutput>memcheck:</computeroutput>
+part, this will cause problems if you select other tools that
+don't understand
+<computeroutput>--leak-check=yes</computeroutput>.</para>
+
+</sect2>
+
+</sect1>
+
+
+<sect1 id="manual-core.clientreq" 
+       xreflabel="The Client Request mechanism">
+<title>The Client Request mechanism</title>
+
+<para>Valgrind has a trapdoor mechanism via which the client
+program can pass all manner of requests and queries to Valgrind
+and the current tool.  Internally, this is used extensively to
+make malloc, free, signals, threads, etc, work, although you
+don't see that.</para>
+
+<para>For your convenience, a subset of these so-called client
+requests is provided to allow you to tell Valgrind facts about
+the behaviour of your program, and conversely to make queries.
+In particular, your program can tell Valgrind about changes in
+memory range permissions that Valgrind would not otherwise know
+about, and so allows clients to get Valgrind to do arbitrary
+custom checks.</para>
+
+<para>Clients need to include a header file to make this work.
+Which header file depends on which client requests you use.  Some
+client requests are handled by the core, and are defined in the
+header file <filename>valgrind.h</filename>.  Tool-specific
+header files are named after the tool, e.g.
+<filename>memcheck.h</filename>.  All header files can be found
+in the <literal>include</literal> directory of wherever Valgrind
+was installed.</para>
+
+<para>The macros in these header files have the magical property
+that they generate code in-line which Valgrind can spot.
+However, the code does nothing when not run on Valgrind, so you
+are not forced to run your program on Valgrind just because you
+use the macros in this file.  Also, you are not required to link
+your program with any extra supporting libraries.</para>
+
+<para>Here is a brief description of the macros available in
+<filename>valgrind.h</filename>, which work with more than one
+tool (see the tool-specific documentation for explanations of the
+tool-specific macros).</para>
+
+ <variablelist>
+
+  <varlistentry>
+   <term><computeroutput>RUNNING_ON_VALGRIND</computeroutput>:</term>
+   <listitem>
+    <para>returns 1 if running on Valgrind, 0 if running on the
+    real CPU.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>:</term>
+   <listitem>
+    <para>discard translations of code in the specified address
+    range.  Useful if you are debugging a JITter or some other
+    dynamic code generation system.  After this call, attempts to
+    execute code in the invalidated address range will cause
+    Valgrind to make new translations of that code, which is
+    probably the semantics you want.  Note that this is
+    implemented naively, and involves checking all 200191 entries
+    in the translation table to see if any of them overlap the
+    specified address range.  So try not to call it often, or
+    performance will nosedive.  Note that you can be clever about
+    this: you only need to call it when an area which previously
+    contained code is overwritten with new code.  You can choose
+    to write coode into fresh memory, and just call this
+    occasionally to discard large chunks of old code all at
+    once.</para>
+
+    <para><command>Warning:</command> minimally tested,
+    especially for tools other than Memcheck.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</term>
+   <listitem>
+    <para>returns the number of errors found so far by Valgrind.
+    Can be useful in test harness code when combined with the
+    <computeroutput>--log-fd=-1</computeroutput> option; this
+    runs Valgrind silently, but the client program can detect
+    when errors occur.  Only useful for tools that report errors,
+    e.g. it's useful for Memcheck, but for Cachegrind it will
+    always return zero because Cachegrind doesn't report
+    errors.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>:</term>
+   <listitem>
+    <para>If your program manages its own memory instead of using
+    the standard <computeroutput>malloc()</computeroutput> /
+    <computeroutput>new</computeroutput> /
+    <computeroutput>new[]</computeroutput>, tools that track
+    information about heap blocks will not do nearly as good a
+    job.  For example, Memcheck won't detect nearly as many
+    errors, and the error messages won't be as informative.  To
+    improve this situation, use this macro just after your custom
+    allocator allocates some new memory.  See the comments in
+    <filename>valgrind.h</filename> for information on how to use
+    it.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput>:</term>
+   <listitem>
+    <para>This should be used in conjunction with
+    <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>.
+    Again, see <filename>memcheck/memcheck.h</filename> for
+    information on how to use it.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>:</term>
+   <listitem>
+    <para>This is similar to
+    <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>,
+    but is tailored towards code that uses memory pools.  See the
+    comments in <filename>valgrind.h</filename> for information
+    on how to use it.</para>
+   </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term><computeroutput>VALGRIND_DESTROY_MEMPOOL</computeroutput>:</term>
+   <listitem>
+    <para>This should be used in conjunction with
+    <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>
+    Again, see the comments in <filename>valgrind.h</filename> for
+    information on how to use it.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_MEMPOOL_ALLOC</computeroutput>:</term>
+   <listitem>
+    <para>This should be used in conjunction with
+    <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>
+    Again, see the comments in <filename>valgrind.h</filename> for
+    information on how to use it.</para>
+   </listitem>
+  </varlistentry>
+   
+  <varlistentry>
+   <term><computeroutput>VALGRIND_MEMPOOL_FREE</computeroutput>:</term>
+   <listitem>
+    <para>This should be used in conjunction with
+    <computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput>
+    Again, see the comments in <filename>valgrind.h</filename> for
+    information on how to use it.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_NON_SIMD_CALL[0123]</computeroutput>:</term>
+   <listitem>
+    <para>executes a function of 0, 1, 2 or 3 args in the client
+    program on the <emphasis>real</emphasis> CPU, not the virtual
+    CPU that Valgrind normally runs code on.  These are used in
+    various ways internally to Valgrind.  They might be useful to
+    client programs.</para> <formalpara><title>Warning:</title>
+    <para>Only use these if you <emphasis>really</emphasis> know
+    what you are doing.</para>
+    </formalpara>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_PRINTF(format, ...)</computeroutput>:</term>
+   <listitem>
+    <para>printf a message to the log file when running under
+    Valgrind.  Nothing is output if not running under Valgrind.
+    Returns the number of characters output.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><computeroutput>VALGRIND_PRINTF_BACKTRACE(format, ...)</computeroutput>:</term>
+   <listitem>
+    <para>printf a message to the log file along with a stack
+    backtrace when running under Valgrind.  Nothing is output if
+    not running under Valgrind.  Returns the number of characters
+    output.</para>
+   </listitem>
+  </varlistentry>
+
+ </variablelist>
+
+<para>Note that <filename>valgrind.h</filename> is included by
+all the tool-specific header files (such as
+<filename>memcheck.h</filename>), so you don't need to include it
+in your client if you include a tool-specific header.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.pthreads" xreflabel="Support for POSIX Pthreads">
+<title>Support for POSIX Pthreads</title>
+
+<para>Valgrind supports programs which use POSIX pthreads.
+Getting this to work was technically challenging but it all works
+well enough for significant threaded applications to work.</para>
+
+<para>It works as follows: threaded apps are (dynamically) linked
+against <literal>libpthread.so</literal>.  Usually this is the
+one installed with your Linux distribution.  Valgrind, however,
+supplies its own <literal>libpthread.so</literal> and
+automatically connects your program to it instead.</para>
+
+<para>The fake <literal>libpthread.so</literal> and Valgrind
+cooperate to implement a user-space pthreads package.  This
+approach avoids the horrible implementation problems of
+implementing a truly multiprocessor version of Valgrind, but it
+does mean that threaded apps run only on one CPU, even if you
+have a multiprocessor machine.</para>
+
+<para>Valgrind schedules your threads in a round-robin fashion,
+with all threads having equal priority.  It switches threads
+every 50000 basic blocks (typically around 300000 x86
+instructions), which means you'll get a much finer interleaving
+of thread executions than when run natively.  This in itself may
+cause your program to behave differently if you have some kind of
+concurrency, critical race, locking, or similar, bugs.</para>
+
+<para>As of the Valgrind-1.0 release, the state of pthread
+support was as follows:</para>
+
+ <itemizedlist>
+
+  <listitem>
+   <para>Mutexes, condition variables, thread-specific data,
+   <computeroutput>pthread_once</computeroutput>, reader-writer
+   locks, semaphores, cleanup stacks, cancellation and thread
+   detaching currently work.  Various attribute-like calls are
+   handled but ignored; you get a warning message.</para>
+  </listitem>
+
+  <listitem>
+   <para>Currently the following syscalls are thread-safe
+   (nonblocking): <literal>write</literal>,
+   <literal>read</literal>, <literal>nanosleep</literal>,
+   <literal>sleep</literal>, <literal>select</literal>,
+   <literal>poll</literal>, <literal>recvmsg</literal> and
+   <literal>accept</literal>.</para>
+  </listitem>
+
+  <listitem>
+   <para>Signals in pthreads are now handled properly(ish):
+   <literal>pthread_sigmask</literal>,
+   <literal>pthread_kill</literal>, <literal>sigwait</literal>
+   and <literal>raise</literal> are now implemented.  Each thread
+   has its own signal mask, as POSIX requires.  It's a bit
+   kludgey -- there's a system-wide pending signal set, rather
+   than one for each thread.  But hey.</para>
+  </listitem>
+
+ </itemizedlist>
+
+<formalpara>
+<title>Note:</title> 
+<para>As of 18 May 2002, the following threaded programs now work
+fine on my RedHat 7.2 box: Opera 6.0Beta2, KNode in KDE 3.0,
+Mozilla-0.9.2.1 and Galeon-0.11.3, both as supplied with RedHat
+7.2.  Also Mozilla 1.0RC2.  OpenOffice 1.0.  MySQL 3.something
+(the current stable release).</para>
+</formalpara>
+
+</sect1>
+
+
+<sect1 id="manual-core.signals" xreflabel="Handling of Signals">
+<title>Handling of Signals</title>
+
+<para>Valgrind provides suitable handling of signals, so,
+provided you stick to POSIX stuff, you should be ok.  Basic
+sigaction() and sigprocmask() are handled.  Signal handlers may
+return in the normal way or do longjmp(); both should work ok.
+As specified by POSIX, a signal is blocked in its own handler.
+Default actions for signals should work as before.  Etc,
+etc.</para>
+
+<para>Under the hood, dealing with signals is a real pain, and
+Valgrind's simulation leaves much to be desired.  If your program
+does way-strange stuff with signals, bad things may happen.  If
+so, let us know.  We don't promise to fix it, but we'd at least
+like to be aware of it.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.install" xreflabel="Building and Installing">
+<title>Building and Installing</title>
+
+<para>We use the standard Unix
+<computeroutput>./configure</computeroutput>,
+<computeroutput>make</computeroutput>, <computeroutput>make
+install</computeroutput> mechanism, and we have attempted to
+ensure that it works on machines with kernel 2.4 or 2.6 and glibc
+2.2.X or 2.3.X.  I don't think there is much else to say.  There
+are no options apart from the usual
+<computeroutput>--prefix</computeroutput> that you should give to
+<computeroutput>./configure</computeroutput>.</para>
+
+<para>The <computeroutput>configure</computeroutput> script tests
+the version of the X server currently indicated by the current
+<computeroutput>$DISPLAY</computeroutput>.  This is a known bug.
+The intention was to detect the version of the current XFree86
+client libraries, so that correct suppressions could be selected
+for them, but instead the test checks the server version.  This
+is just plain wrong.</para>
+
+<para>If you are building a binary package of Valgrind for
+distribution, please read <literal>README_PACKAGERS</literal>
+<xref linkend="dist.readme-packagers"/>.  It contains some
+important information.</para>
+
+<para>Apart from that, there's not much excitement here.  Let us
+know if you have build problems.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.problems" xreflabel="If You Have Problems">
+<title>If You Have Problems</title>
+
+<para>Contact us at <ulink url="http://www.valgrind.org">http://www.valgrind.org</ulink>.</para>
+
+<para>See <xref linkend="manual-core.limits"/> for the known
+limitations of Valgrind, and for a list of programs which are
+known not to work on it.</para>
+
+<para>The translator/instrumentor has a lot of assertions in it.
+They are permanently enabled, and I have no plans to disable
+them.  If one of these breaks, please mail us!</para>
+
+<para>If you get an assertion failure on the expression
+<computeroutput>chunkSane(ch)</computeroutput> in
+<computeroutput>vg_free()</computeroutput> in
+<filename>vg_malloc.c</filename>, this may have happened because
+your program wrote off the end of a malloc'd block, or before its
+beginning.  Valgrind should have emitted a proper message to that
+effect before dying in this way.  This is a known problem which
+we should fix.</para>
+
+<para>Read the 
+<ulink url="http://www.valgrind.org/docs/faq/index.html">FAQ</ulink> for
+more advice about common problems, crashes, etc.</para>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.limits" xreflabel="Limitations">
+<title>Limitations</title>
+
+<para>The following list of limitations seems depressingly long.
+However, most programs actually work fine.</para>
+
+<para>Valgrind will run x86-GNU/Linux ELF dynamically linked
+binaries, on a kernel 2.4.X or 2.6.X system, subject to
+the following constraints:</para>
+
+ <itemizedlist>
+
+  <listitem>
+   <para>No support for 3DNow instructions.  If the translator
+   encounters these, Valgrind will generate a SIGILL when the
+   instruction is executed.</para>
+  </listitem>
+
+  <listitem>
+   <para>Pthreads support is improving, but there are still
+   significant limitations in that department.  See the section
+   above on Pthreads.  Note that your program must be dynamically
+   linked against <literal>libpthread.so</literal>, so that
+   Valgrind can substitute its own implementation at program
+   startup time.  If you're statically linked against it, things
+   will fail badly.</para>
+  </listitem>
+
+  <listitem>
+   <para>Memcheck assumes that the floating point registers are
+   not used as intermediaries in memory-to-memory copies, so it
+   immediately checks definedness of values loaded from memory by
+   floating-point loads.  If you want to write code which copies
+   around possibly-uninitialised values, you must ensure these
+   travel through the integer registers, not the FPU.</para>
+  </listitem>
+
+  <listitem>
+   <para>If your program does its own memory management, rather
+   than using malloc/new/free/delete, it should still work, but
+   Valgrind's error checking won't be so effective.  If you
+   describe your program's memory management scheme using "client
+   requests" (Section 3.7 of this manual), Memcheck can do
+   better.  Nevertheless, using malloc/new and free/delete is
+   still the best approach.</para>
+  </listitem>
+
+  <listitem>
+   <para>Valgrind's signal simulation is not as robust as it
+   could be.  Basic POSIX-compliant sigaction and sigprocmask
+   functionality is supplied, but it's conceivable that things
+   could go badly awry if you do weird things with signals.
+   Workaround: don't.  Programs that do non-POSIX signal tricks
+   are in any case inherently unportable, so should be avoided if
+   possible.</para>
+  </listitem>
+
+  <listitem>
+   <para>Programs which switch stacks are not well handled.
+   Valgrind does have support for this, but I don't have great
+   faith in it.  It's difficult -- there's no cast-iron way to
+   decide whether a large change in %esp is as a result of the
+   program switching stacks, or merely allocating a large object
+   temporarily on the current stack -- yet Valgrind needs to
+   handle the two situations differently.</para>
+  </listitem>
+
+  <listitem>
+   <para>x86 instructions, and system calls, have been
+   implemented on demand.  So it's possible, although unlikely,
+   that a program will fall over with a message to that effect.
+   If this happens, please report ALL the details printed out, so
+   we can try and implement the missing feature.</para>
+  </listitem>
+
+  <listitem>
+   <para>x86 floating point works correctly, but floating-point
+   code may run even more slowly than integer code, due to my
+   simplistic approach to FPU emulation.</para>
+  </listitem>
+
+  <listitem>
+   <para>Memory consumption of your program is majorly increased
+   whilst running under Valgrind.  This is due to the large
+   amount of administrative information maintained behind the
+   scenes.  Another cause is that Valgrind dynamically translates
+   the original executable.  Translated, instrumented code is
+   14-16 times larger than the original (!) so you can easily end
+   up with 30+ MB of translations when running (eg) a web
+   browser.</para>
+  </listitem>
+
+  <listitem>
+   <para>Valgrind can handle dynamically-generated code just
+   fine. However, if you regenerate code over the top of old code
+   (ie. at the same memory addresses) Valgrind will not realise
+   the code has changed, and will run its old translations, which
+   will be out-of-date.  You need to use the
+   VALGRIND_DISCARD_TRANSLATIONS client request in that case. For
+   the same reason gcc's <ulink
+   url="http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html">trampolines
+   for nested functions</ulink> are currently unsupported, see
+   <ulink url="http://bugs.kde.org/show_bug.cgi?id=69511">bug
+   69511</ulink>.</para>
+  </listitem>
+
+ </itemizedlist>
+
+
+ <para>Programs which are known not to work are:</para>
+ <itemizedlist>
+  <listitem>
+   <para>emacs starts up but immediately concludes it is out of
+   memory and aborts.  Emacs has it's own memory-management
+   scheme, but I don't understand why this should interact so
+   badly with Valgrind.  Emacs works fine if you build it to use
+   the standard malloc/free routines.</para>
+  </listitem>
+ </itemizedlist>
+
+
+ <para>Known platform-specific limitations, as of release 1.0.0:</para>
+ <itemizedlist>
+  <listitem>
+   <para>On Red Hat 7.3, there have been reports of link errors
+   (at program start time) for threaded programs using
+   <computeroutput>__pthread_clock_gettime</computeroutput> and
+   <computeroutput>__pthread_clock_settime</computeroutput>.
+   This appears to be due to
+   <computeroutput>/lib/librt-2.2.5.so</computeroutput> needing
+   them.  Unfortunately I do not understand enough about this
+   problem to fix it properly, and I can't reproduce it on my
+   test RedHat 7.3 system.  Please mail me if you have more
+   information / understanding.</para>
+  </listitem>
+ </itemizedlist>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.howworks" xreflabel="How It Works - A Rough Overview">
+<title>How It Works -- A Rough Overview</title>
+
+<para>Some gory details, for those with a passion for gory
+details.  You don't need to read this section if all you want to
+do is use Valgrind.  What follows is an outline of the machinery.
+A more detailed (and somewhat out of date) description is to be
+found <xref linkend="mc-tech-docs"/>.</para>
+
+<sect2 id="manual-core.startb" xreflabel="Getting Started">
+<title>Getting started</title>
+
+<para>Valgrind is compiled into a shared object, valgrind.so.
+The shell script valgrind sets the LD_PRELOAD environment
+variable to point to valgrind.so.  This causes the .so to be
+loaded as an extra library to any subsequently executed
+dynamically-linked ELF binary, viz, the program you want to
+debug.</para>
+
+<para>The dynamic linker allows each .so in the process image to
+have an initialisation function which is run before main().  It
+also allows each .so to have a finalisation function run after
+main() exits.</para>
+
+<para>When valgrind.so's initialisation function is called by the
+dynamic linker, the synthetic CPU to starts up.  The real CPU
+remains locked in valgrind.so for the entire rest of the program,
+but the synthetic CPU returns from the initialisation function.
+Startup of the program now continues as usual -- the dynamic
+linker calls all the other .so's initialisation routines, and
+eventually runs main().  This all runs on the synthetic CPU, not
+the real one, but the client program cannot tell the
+difference.</para>
+
+<para>Eventually main() exits, so the synthetic CPU calls
+valgrind.so's finalisation function.  Valgrind detects this, and
+uses it as its cue to exit.  It prints summaries of all errors
+detected, possibly checks for memory leaks, and then exits the
+finalisation routine, but now on the real CPU.  The synthetic CPU
+has now lost control -- permanently -- so the program exits back
+to the OS on the real CPU, just as it would have done
+anyway.</para>
+
+<para>On entry, Valgrind switches stacks, so it runs on its own
+stack.  On exit, it switches back.  This means that the client
+program continues to run on its own stack, so we can switch back
+and forth between running it on the simulated and real CPUs
+without difficulty.  This was an important design decision,
+because it makes it easy (well, significantly less difficult) to
+debug the synthetic CPU.</para>
+
+</sect2>
+
+
+<sect2 id="manual-core.engine" 
+       xreflabel="The translation/instrumentation engine">
+<title>The translation/instrumentation engine</title>
+
+<para>Valgrind does not directly run any of the original
+program's code.  Only instrumented translations are run.
+Valgrind maintains a translation table, which allows it to find
+the translation quickly for any branch target (code address).  If
+no translation has yet been made, the translator - a just-in-time
+translator - is summoned.  This makes an instrumented
+translation, which is added to the collection of translations.
+Subsequent jumps to that address will use this
+translation.</para>
+
+<para>Valgrind no longer directly supports detection of
+self-modifying code.  Such checking is expensive, and in practice
+(fortunately) almost no applications need it.  However, to help
+people who are debugging dynamic code generation systems, there
+is a Client Request (basically a macro you can put in your
+program) which directs Valgrind to discard translations in a
+given address range.  So Valgrind can still work in this
+situation provided the client tells it when code has become
+out-of-date and needs to be retranslated.</para>
+
+<para>The JITter translates basic blocks -- blocks of
+straight-line-code -- as single entities.  To minimise the
+considerable difficulties of dealing with the x86 instruction
+set, x86 instructions are first translated to a RISC-like
+intermediate code, similar to sparc code, but with an infinite
+number of virtual integer registers.  Initially each insn is
+translated seperately, and there is no attempt at
+instrumentation.</para>
+
+<para>The intermediate code is improved, mostly so as to try and
+cache the simulated machine's registers in the real machine's
+registers over several simulated instructions.  This is often
+very effective.  Also, we try to remove redundant updates of the
+simulated machines's condition-code register.</para>
+
+<para>The intermediate code is then instrumented, giving more
+intermediate code.  There are a few extra intermediate-code
+operations to support instrumentation; it is all refreshingly
+simple.  After instrumentation there is a cleanup pass to remove
+redundant value checks.</para>
+
+<para>This gives instrumented intermediate code which mentions
+arbitrary numbers of virtual registers.  A linear-scan register
+allocator is used to assign real registers and possibly generate
+spill code.  All of this is still phrased in terms of the
+intermediate code.  This machinery is inspired by the work of
+Reuben Thomas (Mite).</para>
+
+<para>Then, and only then, is the final x86 code emitted.  The
+intermediate code is carefully designed so that x86 code can be
+generated from it without need for spare registers or other
+inconveniences.</para>
+
+<para>The translations are managed using a traditional LRU-based
+caching scheme.  The translation cache has a default size of
+about 14MB.</para>
+
+</sect2>
+
+
+<sect2 id="manual-core.track" 
+       xreflabel="Tracking the Status of Memory">
+<title>Tracking the Status of Memory</title>
+
+<para>Each byte in the process' address space has nine bits
+associated with it: one A bit and eight V bits.  The A and V bits
+for each byte are stored using a sparse array, which flexibly and
+efficiently covers arbitrary parts of the 32-bit address space
+without imposing significant space or performance overheads for
+the parts of the address space never visited.  The scheme used,
+and speedup hacks, are described in detail at the top of the
+source file <filename>coregrind/vg_memory.c</filename>, so you
+should read that for the gory details.</para>
+
+</sect2>
+
+
+
+<sect2 id="manual-core.syscalls" xreflabel="System calls">
+<title>System calls</title>
+
+<para>All system calls are intercepted.  The memory status map is
+consulted before and updated after each call.  It's all rather
+tiresome.  See <filename>coregrind/vg_syscalls.c</filename> for
+details.</para>
+
+</sect2>
+
+
+<sect2 id="manual-core.syssignals" xreflabel="Signals">
+<title>Signals</title>
+
+<para>All system calls to sigaction() and sigprocmask() are
+intercepted.  If the client program is trying to set a signal
+handler, Valgrind makes a note of the handler address and which
+signal it is for.  Valgrind then arranges for the same signal to
+be delivered to its own handler.</para>
+
+<para>When such a signal arrives, Valgrind's own handler catches
+it, and notes the fact.  At a convenient safe point in execution,
+Valgrind builds a signal delivery frame on the client's stack and
+runs its handler.  If the handler longjmp()s, there is nothing
+more to be said.  If the handler returns, Valgrind notices this,
+zaps the delivery frame, and carries on where it left off before
+delivering the signal.</para>
+
+<para>The purpose of this nonsense is that setting signal
+handlers essentially amounts to giving callback addresses to the
+Linux kernel.  We can't allow this to happen, because if it did,
+signal handlers would run on the real CPU, not the simulated one.
+This means the checking machinery would not operate during the
+handler run, and, worse, memory permissions maps would not be
+updated, which could cause spurious error reports once the
+handler had returned.</para>
+
+<para>An even worse thing would happen if the signal handler
+longjmp'd rather than returned: Valgrind would completely lose
+control of the client program.</para>
+
+<para>Upshot: we can't allow the client to install signal
+handlers directly.  Instead, Valgrind must catch, on behalf of
+the client, any signal the client asks to catch, and must
+delivery it to the client on the simulated CPU, not the real one.
+This involves considerable gruesome fakery; see
+<filename>coregrind/vg_signals.c</filename> for details.</para>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="manual-core.example" xreflabel="An Example Run">
+<title>An Example Run</title>
+
+<para>This is the log for a run of a small program using Memcheck
+The program is in fact correct, and the reported error is as the
+result of a potentially serious code generation bug in GNU g++
+(snapshot 20010527).</para>
+
+<programlisting><![CDATA[
+sewardj@phoenix:~/newmat10$
+~/Valgrind-6/valgrind -v ./bogon 
+==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1.
+==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward.
+==25832== Startup, with flags:
+==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp
+==25832== reading syms from /lib/ld-linux.so.2
+==25832== reading syms from /lib/libc.so.6
+==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0
+==25832== reading syms from /lib/libm.so.6
+==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3
+==25832== reading syms from /home/sewardj/Valgrind/valgrind.so
+==25832== reading syms from /proc/self/exe
+==25832== loaded 5950 symbols, 142333 line number locations
+==25832== 
+==25832== Invalid read of size 4
+==25832==    at 0x8048724: _ZN10BandMatrix6ReSizeEiii (bogon.cpp:45)
+==25832==    by 0x80487AF: main (bogon.cpp:66)
+==25832==    by 0x40371E5E: __libc_start_main (libc-start.c:129)
+==25832==    by 0x80485D1: (within /home/sewardj/newmat10/bogon)
+==25832==    Address 0xBFFFF74C is not stack'd, malloc'd or free'd
+==25832==
+==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0)
+==25832== malloc/free: in use at exit: 0 bytes in 0 blocks.
+==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated.
+==25832== For a detailed leak analysis, rerun with: --leak-check=yes
+==25832==
+==25832== exiting, did 1881 basic blocks, 0 misses.
+==25832== 223 translations, 3626 bytes in, 56801 bytes out.]]></programlisting>
+
+<para>The GCC folks fixed this about a week before gcc-3.0
+shipped.</para>
+
+</sect1>
+
+
+<sect1 id="manual-core.warnings" xreflabel="Warning Messages">
+<title>Warning Messages You Might See</title>
+
+<para>Most of these only appear if you run in verbose mode
+(enabled by <computeroutput>-v</computeroutput>):</para>
+
+ <itemizedlist>
+
+  <listitem>
+   <para><computeroutput>More than 50 errors detected.
+   Subsequent errors will still be recorded, but in less detail
+   than before.</computeroutput></para>
+   <para>After 50 different errors have been shown, Valgrind
+   becomes more conservative about collecting them.  It then
+   requires only the program counters in the top two stack frames
+   to match when deciding whether or not two errors are really
+   the same one.  Prior to this point, the PCs in the top four
+   frames are required to match.  This hack has the effect of
+   slowing down the appearance of new errors after the first 50.
+   The 50 constant can be changed by recompiling Valgrind.</para>
+  </listitem>
+
+  <listitem>
+   <para><computeroutput>More than 300 errors detected.  I'm not
+   reporting any more.  Final error counts may be inaccurate.  Go
+   fix your program!</computeroutput></para>
+   <para>After 300 different errors have been detected, Valgrind
+   ignores any more.  It seems unlikely that collecting even more
+   different ones would be of practical help to anybody, and it
+   avoids the danger that Valgrind spends more and more of its
+   time comparing new errors against an ever-growing collection.
+   As above, the 300 number is a compile-time constant.</para>
+  </listitem>
+
+  <listitem>
+   <para><computeroutput>Warning: client switching
+   stacks?</computeroutput></para>
+   <para>Valgrind spotted such a large change in the stack
+   pointer, <literal>%esp</literal>, that it guesses the client
+   is switching to a different stack.  At this point it makes a
+   kludgey guess where the base of the new stack is, and sets
+   memory permissions accordingly.  You may get many bogus error
+   messages following this, if Valgrind guesses wrong.  At the
+   moment "large change" is defined as a change of more that
+   2000000 in the value of the <literal>%esp</literal> (stack
+   pointer) register.</para>
+  </listitem>
+
+  <listitem>
+   <para><computeroutput>Warning: client attempted to close
+   Valgrind's logfile fd &lt;number&gt;</computeroutput></para>
+   <para>Valgrind doesn't allow the client to close the logfile,
+   because you'd never see any diagnostic information after that
+   point.  If you see this message, you may want to use the
+   <computeroutput>--log-fd=&lt;number&gt;</computeroutput> option
+   to specify a different logfile file-descriptor number.</para>
+  </listitem>
+
+  <listitem>
+   <para><computeroutput>Warning: noted but unhandled ioctl
+   &lt;number&gt;</computeroutput></para>
+   <para>Valgrind observed a call to one of the vast family of
+   <computeroutput>ioctl</computeroutput> system calls, but did
+   not modify its memory status info (because I have not yet got
+   round to it).  The call will still have gone through, but you
+   may get spurious errors after this as a result of the
+   non-update of the memory info.</para>
+  </listitem>
+
+  <listitem>
+   <para><computeroutput>Warning: set address range perms: large
+   range &lt;number></computeroutput></para>
+   <para>Diagnostic message, mostly for benefit of the valgrind
+   developers, to do with memory permissions.</para>
+  </listitem>
+
+ </itemizedlist>
+
+</sect1>
+</chapter>
diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml
new file mode 100644
index 0000000..844774b
--- /dev/null
+++ b/docs/xml/manual-intro.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="manual-intro" xreflabel="Introduction">
+<title>Introduction</title>
+
+<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
+<title>An Overview of Valgrind</title>
+
+<para>Valgrind is a flexible system for debugging and profiling
+Linux-x86 executables.  The system consists of a core, which
+provides a synthetic x86 CPU in software, and a series of tools,
+each of which performs some kind of debugging, profiling, or
+similar task.  The architecture is modular, so that new tools can
+be created easily and without disturbing the existing
+structure.</para>
+
+<para>A number of useful tools are supplied as standard.  In
+summary, these are:</para>
+
+<orderedlist>
+
+  <listitem>
+    <para><command>Memcheck</command> detects memory-management
+    problems in your programs.  All reads and writes of memory
+    are checked, and calls to malloc/new/free/delete are
+    intercepted. As a result, Memcheck can detect the following
+    problems:</para>
+
+    <itemizedlist>
+     <listitem>
+      <para>Use of uninitialised memory</para>
+     </listitem>
+     <listitem>
+      <para>Reading/writing memory after it has been
+      free'd</para>
+     </listitem>
+     <listitem>
+      <para>Reading/writing off the end of malloc'd
+      blocks</para>
+     </listitem>
+     <listitem>
+      <para>Reading/writing inappropriate areas on the
+      stack</para>
+     </listitem>
+     <listitem>
+      <para>Memory leaks -- where pointers to malloc'd
+      blocks are lost forever</para>
+     </listitem>
+     <listitem>
+      <para>Mismatched use of malloc/new/new [] vs
+      free/delete/delete []</para>
+      </listitem>
+     <listitem>
+      <para>Overlapping <computeroutput>src</computeroutput> and
+      <computeroutput>dst</computeroutput> pointers in
+      <computeroutput>memcpy()</computeroutput> and related
+      functions</para></listitem> <listitem><para>Some misuses of
+      the POSIX pthreads API</para>
+     </listitem>
+    </itemizedlist>
+
+    <para>Problems like these can be difficult to find by other
+    means, often lying undetected for long periods, then causing
+    occasional, difficult-to-diagnose crashes.</para>
+   </listitem>
+ 
+   <listitem>
+    <para><command>Addrcheck</command> is a lightweight version
+    of Memcheck.  It is identical to Memcheck except for the
+    single detail that it does not do any uninitialised-value
+    checks.  All of the other checks -- primarily the
+    fine-grained address checking -- are still done.  The
+    downside of this is that you don't catch the
+    uninitialised-value errors that Memcheck can find.</para>
+
+    <para>But the upside is significant: programs run about twice
+    as fast as they do on Memcheck, and a lot less memory is
+    used.  It still finds reads/writes of freed memory, memory
+    off the end of blocks and in other invalid places, bugs which
+    you really want to find before release!</para>
+
+    <para>Because Addrcheck is lighter and faster than Memcheck,
+    you can run more programs for longer, and so you may be able
+    to cover more test scenarios.  Addrcheck was created because
+    one of us (Julian) wanted to be able to run a complete KDE
+    desktop session with checking.  As of early November 2002, we
+    have been able to run KDE-3.0.3 on a 1.7 GHz P4 with 512 MB
+    of memory, using Addrcheck.  Although the result is not
+    stellar, it's quite usable, and it seems plausible to run KDE
+    for long periods at a time like this, collecting up all the
+    addressing errors that appear.</para>
+   </listitem>
+
+   <listitem>
+    <para><command>Cachegrind</command> is a cache profiler.  It
+    performs detailed simulation of the I1, D1 and L2 caches in
+    your CPU and so can accurately pinpoint the sources of cache
+    misses in your code.  If you desire, it will show the number
+    of cache misses, memory references and instructions accruing
+    to each line of source code, with per-function, per-module
+    and whole-program summaries.  If you ask really nicely it
+    will even show counts for each individual x86
+    instruction.</para>
+
+    <para>Cachegrind auto-detects your machine's cache
+    configuration using the
+    <computeroutput>CPUID</computeroutput> instruction, and so
+    needs no further configuration info, in most cases.</para>
+
+    <para>Cachegrind is nicely complemented by Josef
+    Weidendorfer's amazing KCacheGrind visualisation tool 
+    (<ulink url="http://kcachegrind.sourceforge.net">http://kcachegrind.sourceforge.net</ulink>),
+    a KDE application which presents these profiling results in a
+    graphical and easier-to-understand form.</para>
+   </listitem>
+
+   <listitem>
+    <para><command>Helgrind</command> finds data races in
+    multithreaded programs.  Helgrind looks for memory locations
+    which are accessed by more than one (POSIX p-)thread, but for
+    which no consistently used (pthread_mutex_)lock can be found.
+    Such locations are indicative of missing synchronisation
+    between threads, and could cause hard-to-find
+    timing-dependent problems.</para>
+
+    <para>Helgrind ("Hell's Gate", in Norse mythology) implements
+    the so-called "Eraser" data-race-detection algorithm, along
+    with various refinements (thread-segment lifetimes) which
+    reduce the number of false errors it reports.  It is as yet
+    somewhat of an experimental tool, so your feedback is
+    especially welcomed here.</para>
+
+    <para>Helgrind has been hacked on extensively by Jeremy
+    Fitzhardinge, and we have him to thank for getting it to a
+    releasable state.</para>
+   </listitem>
+
+</orderedlist>
+  
+
+<para>A number of minor tools (<command>Corecheck</command>,
+<command>Lackey</command> and <command>Nulgrind</command>) are
+also supplied.  These aren't particularly useful -- they exist to
+illustrate how to create simple tools and to help the valgrind
+developers in various ways.</para>
+
+<para>Valgrind is closely tied to details of the CPU, operating
+system and to a less extent, compiler and basic C libraries. This
+makes it difficult to make it portable, so we have chosen at the
+outset to concentrate on what we believe to be a widely used
+platform: Linux on x86s.  Valgrind uses the standard Unix
+<computeroutput>./configure</computeroutput>,
+<computeroutput>make</computeroutput>, <computeroutput>make
+install</computeroutput> mechanism, and we have attempted to
+ensure that it works on machines with kernel 2.2 or 2.4 and glibc
+2.1.X, 2.2.X or 2.3.1.  This should cover the vast majority of
+modern Linux installations.  Note that glibc-2.3.2+, with the
+NPTL (Native Posix Threads Library) package won't work.  We hope
+to be able to fix this, but it won't be easy.</para>
+
+<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
+version 2. Some of the PThreads test cases,
+<computeroutput>pth_*.c</computeroutput>, are taken from
+"Pthreads Programming" by Bradford Nichols, Dick Buttlar &amp;
+Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by
+O'Reilly &amp; Associates, Inc.</para>
+
+</sect1>
+
+
+<sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
+<title>How to navigate this manual</title>
+
+<para>The Valgrind distribution consists of the Valgrind core,
+upon which are built Valgrind tools, which do different kinds of
+debugging and profiling.  This manual is structured
+similarly.</para>
+
+<para>First, we describe the Valgrind core, how to use it, and
+the flags it supports.  Then, each tool has its own chapter in
+this manual.  You only need to read the documentation for the
+core and for the tool(s) you actually use, although you may find
+it helpful to be at least a little bit familar with what all
+tools do.  If you're new to all this, you probably want to run
+the Memcheck tool.  If you want to write a new tool, read 
+<xref linkend="writing-tools"/>.</para>
+
+<para>Be aware that the core understands some command line flags,
+and the tools have their own flags which they know about.  This
+means there is no central place describing all the flags that are
+accepted -- you have to read the flags documentation both for
+<xref linkend="manual-core"/> and for the tool you want to
+use.</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml
new file mode 100644
index 0000000..f68f2eb
--- /dev/null
+++ b/docs/xml/manual.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id="manual" xreflabel="Valgrind User Manual">
+
+  <bookinfo>
+    <title>Valgrind User Manual</title>
+  </bookinfo>
+
+  <xi:include href="manual-intro.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="manual-core.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../memcheck/docs/mc-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../addrcheck/docs/ac-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../cachegrind/docs/cg-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../massif/docs/ms-manual.xml" parse="xml"  
+       xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../helgrind/docs/hg-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../none/docs/nl-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../corecheck/docs/cc-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../lackey/docs/lk-manual.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</book>
diff --git a/docs/xml/tech-docs.xml b/docs/xml/tech-docs.xml
new file mode 100644
index 0000000..3e8a60b
--- /dev/null
+++ b/docs/xml/tech-docs.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id="tech-docs" xreflabel="Valgrind Technical Documentation">
+
+  <bookinfo>
+    <title>Valgrind Technical Documentation</title>
+  </bookinfo>
+
+  <xi:include href="../../memcheck/docs/mc-tech-docs.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="../../cachegrind/docs/cg-tech-docs.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="writing-tools.xml" parse="xml"  
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</book>
diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml
new file mode 100644
index 0000000..638d436
--- /dev/null
+++ b/docs/xml/vg-entities.xml
@@ -0,0 +1,12 @@
+<!-- misc. strings -->
+<!ENTITY vg-url      "http://www.valgrind.org">
+<!ENTITY vg-jemail   "jseward@valgrind.org">
+<!ENTITY vg-vemail   "valgrind@valgrind.org">
+<!ENTITY vg-lifespan "2000-2004">
+<!ENTITY vg-users-list "http://lists.sourceforge.net/lists/listinfo/valgrind-users">
+
+<!-- valgrind release + version stuff -->
+<!ENTITY rel-type    "Development release">
+<!ENTITY rel-version "2.1.2">
+<!ENTITY rel-date    "July 18 2004">
+
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
new file mode 100644
index 0000000..b8b8aff
--- /dev/null
+++ b/docs/xml/writing-tools.xml
@@ -0,0 +1,1248 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
+<!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities;
+]>
+
+<chapter id="writing-tools" xreflabel="Writing a New Valgrind Tool">
+<title>Writing a New Valgrind Tool</title>
+
+<sect1 id="writing-tools.intro" xreflabel="Introduction">
+<title>Introduction</title>
+
+<sect2 id="writing-tools.supexec" xreflabel="Supervised Execution">
+<title>Supervised Execution</title>
+
+<para>Valgrind provides a generic infrastructure for supervising
+the execution of programs.  This is done by providing a way to
+instrument programs in very precise ways, making it relatively
+easy to support activities such as dynamic error detection and
+profiling.</para>
+
+<para>Although writing a tool is not easy, and requires learning
+quite a few things about Valgrind, it is much easier than
+instrumenting a program from scratch yourself.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.tools" xreflabel="Tools">
+<title>Tools</title>
+
+<para>The key idea behind Valgrind's architecture is the division
+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
+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
+recording and suppression.</para>
+
+<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
+certain services, or be notified when certain interesting events
+occur.  But the core takes care of all the hard work.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.execspaces" xreflabel="Execution Spaces">
+<title>Execution Spaces</title>
+
+<para>An important concept to understand before writing a tool is
+that there are three spaces in which program code executes:</para>
+
+
+<orderedlist>
+
+ <listitem>
+  <para>User space: this covers most of the program's execution.
+  The tool is given the code and can instrument it any way it
+  likes, providing (more or less) total control over the
+  code.</para>
+
+  <para>Code executed in user space includes all the program
+  code, almost all of the C library (including things like the
+  dynamic linker), and almost all parts of all other
+  libraries.</para>
+ </listitem>
+
+  <listitem>
+   <para>Core space: a small proportion of the program's execution
+   takes place entirely within Valgrind's core.  This includes:</para>
+   <itemizedlist>
+    <listitem>
+      <para>Dynamic memory management 
+      (<computeroutput>malloc()</computeroutput> etc.)</para>
+    </listitem>
+    <listitem>
+     <para>Pthread operations and scheduling</para>
+    </listitem>
+    <listitem>
+     <para>Signal handling</para>
+    </listitem>
+   </itemizedlist>
+
+   <para>A tool has no control over these operations; it never
+   "sees" the code doing this work and thus cannot instrument it.
+   However, the core provides hooks so a tool can be notified
+   when certain interesting events happen, for example when when
+   dynamic memory is allocated or freed, the stack pointer is
+   changed, or a pthread mutex is locked, etc.</para>
+
+   <para>Note that these hooks only notify tools of events
+   relevant to user space.  For example, when the core allocates
+   some memory for its own use, the tool is not notified of this,
+   because it's not directly part of the supervised program's
+   execution.</para>
+  </listitem>
+
+  <listitem>
+   <para>Kernel space: execution in the kernel.  Two kinds:</para>
+    <orderedlist>
+     <listitem>
+      <para>System calls: can't be directly observed by either
+      the tool or the core.  But the core does have some idea of
+      what happens to the arguments, and it provides hooks for a
+      tool to wrap system calls.</para>
+     </listitem>
+     <listitem>
+      <para>Other: all other kernel activity (e.g. process
+      scheduling) is totally opaque and irrelevant to the
+      program.</para>
+     </listitem>
+    </orderedlist>
+  </listitem>
+
+  <listitem>
+   <para>It should be noted that a tool only has direct control
+   over code executed in user space.  This is the vast majority
+   of code executed, but it is not absolutely all of it, so any
+   profiling information recorded by a tool won't be totally
+   accurate.</para>
+  </listitem>
+
+</orderedlist>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="writing-tools.writingatool" xreflabel="Writing a Tool">
+<title>Writing a Tool</title>
+
+
+<sect2 id="writing-tools.whywriteatool" xreflabel="Why write a tool?">
+<title>Why write a tool?</title>
+
+<para>Before you write a tool, you should have some idea of what
+it should do.  What is it you want to know about your programs of
+interest?  Consider some existing tools:</para>
+
+<itemizedlist>
+
+ <listitem>
+  <para><command>memcheck</command>: among other things, performs
+  fine-grained validity and addressibility checks of every memory
+  reference performed by the program.</para>
+ </listitem>
+
+ <listitem>
+  <para><command>addrcheck</command>: performs lighterweight
+  addressibility checks of every memory reference performed by
+  the program.</para>
+ </listitem>
+
+ <listitem>
+  <para><command>cachegrind</command>: tracks every instruction
+  and memory reference to simulate instruction and data caches,
+  tracking cache accesses and misses that occur on every line in
+  the program.</para>
+ </listitem>
+
+ <listitem>
+  <para><command>helgrind</command>: tracks every memory access
+  and mutex lock/unlock to determine if a program contains any
+  data races.</para>
+ </listitem>
+
+ <listitem>
+  <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
+  executed; the number of branches executed and the proportion of
+  those which were taken.</para>
+ </listitem>
+</itemizedlist>
+
+<para>These examples give a reasonable idea of what kinds of
+things Valgrind can be used for.  The instrumentation can range
+from very lightweight (e.g. counting the number of times a
+particular function is called) to very intrusive (e.g.
+memcheck's memory checking).</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.suggestedtools" xreflabel="Suggested tools">
+<title>Suggested tools</title>
+
+<para>Here is a list of ideas we have had for tools that should
+not be too hard to implement.</para>
+
+<itemizedlist>
+ <listitem>
+  <para><command>branch profiler</command>: A machine's branch
+  prediction hardware could be simulated, and each branch
+  annotated with the number of predicted and mispredicted
+  branches.  Would be implemented quite similarly to Cachegrind,
+  and could reuse the
+  <computeroutput>cg_annotate</computeroutput> script to annotate
+  source code.</para>
+
+  <para>The biggest difficulty with this is the simulation; the
+  chip-makers are very cagey about how their chips do branch
+  prediction.  But implementing one or more of the basic
+  algorithms could still give good information.</para>
+ </listitem>
+
+ <listitem>
+  <para><command>coverage tool</command>: Cachegrind can already
+  be used for doing test coverage, but it's massive overkill to
+  use it just for that.</para>
+
+  <para>It would be easy to write a coverage tool that records
+  how many times each basic block was recorded.  Again, the
+  <computeroutput>cg_annotate</computeroutput> script could be
+  used for annotating source code with the gathered information.
+  Although, <computeroutput>cg_annotate</computeroutput> is only
+  designed for working with single program runs.  It could be
+  extended relatively easily to deal with multiple runs of a
+  program, so that the coverage of a whole test suite could be
+  determined.</para>
+
+  <para>In addition to the standard coverage information, such a
+  tool could record extra information that would help a user
+  generate test cases to exercise unexercised paths.  For
+  example, for each conditional branch, the tool could record all
+  inputs to the conditional test, and print these out when
+  annotating.</para>
+ </listitem>
+
+ <listitem>
+  <para><command>run-time type checking</command>: A nice example
+  of a dynamic checker is given in this paper:</para>
+  <address>Debugging via Run-Time Type Checking
+  Alexey Loginov, Suan Hsi Yong, Susan Horwitz and Thomas Reps
+  Proceedings of Fundamental Approaches to Software Engineering
+  April 2001.
+  </address>
+
+  <para>Similar is the tool described in this paper:</para>
+  <address>Run-Time Type Checking for Binary Programs
+  Michael Burrows, Stephen N. Freund, Janet L. Wiener
+  Proceedings of the 12th International Conference on Compiler Construction (CC 2003)
+  April 2003.
+  </address>
+
+  <para>This approach can find quite a range of bugs,
+  particularly in C and C++ programs, and could be implemented
+  quite nicely as a Valgrind tool.</para>
+
+  <para>Ways to speed up this run-time type checking are
+  described in this paper:</para>
+  <address>Reducing the Overhead of Dynamic Analysis
+  Suan Hsi Yong and Susan Horwitz
+  Proceedings of Runtime Verification '02
+  July 2002.
+  </address>
+
+  <para>Valgrind's client requests could be used to pass
+  information to a tool about which elements need instrumentation
+  and which don't.</para>
+ </listitem>
+</itemizedlist>
+
+<para>We would love to hear from anyone who implements these or
+other tools.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.howtoolswork" xreflabel="How tools work">
+<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>
+
+<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>SK_(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>
+
+</sect2>
+
+
+<sect2 id="writing-tools.gettingcode" xreflabel="Getting the code">
+<title>Getting the code</title>
+
+<para>To write your own tool, you'll need to check out a copy of
+Valgrind from the CVS repository, rather than using a packaged
+distribution.  This is because it contains several extra files
+needed for writing tools.</para>
+
+<para>To check out the code from the CVS repository, first login:</para>
+<programlisting><![CDATA[
+cvs -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind
+login]]></programlisting>
+
+<para>Then checkout the code.  To get a copy of the current
+development version (recommended for the brave only):</para>
+<programlisting><![CDATA[
+cvs -z3 -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind 
+co valgrind]]></programlisting>
+
+<para>To get a copy of the stable released branch:</para>
+<programlisting><![CDATA[
+cvs -z3 -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind
+co -r <TAG> valgrind]]></programlisting>
+
+<para>where &lt;<computeroutput>TAG</computeroutput>&gt; has the
+form <computeroutput>VALGRIND_X_Y_Z</computeroutput> for version
+X.Y.Z.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.gettingstarted" xreflabel="Getting started">
+<title>Getting started</title>
+
+<para>Valgrind uses GNU <computeroutput>automake</computeroutput>
+and <computeroutput>autoconf</computeroutput> for the creation of
+Makefiles and configuration.  But don't worry, these instructions
+should be enough to get you started even if you know nothing
+about those tools.</para>
+
+<para>In what follows, all filenames are relative to Valgrind's
+top-level directory <computeroutput>valgrind/</computeroutput>.</para>
+
+<orderedlist>
+ <listitem>
+  <para>Choose a name for the tool, and an abbreviation that can
+  be used as a short prefix.  We'll use
+  <computeroutput>foobar</computeroutput> and
+  <computeroutput>fb</computeroutput> as an example.</para>
+ </listitem>
+
+ <listitem>
+  <para>Make a new directory
+  <computeroutput>foobar/</computeroutput> which will hold the
+  tool.</para>
+ </listitem>
+
+ <listitem>
+  <para>Copy <computeroutput>none/Makefile.am</computeroutput>
+  into <computeroutput>foobar/</computeroutput>.  Edit it by
+  replacing all occurrences of the string
+  <computeroutput>"none"</computeroutput> with
+  <computeroutput>"foobar"</computeroutput> and the one
+  occurrence of the string <computeroutput>"nl_"</computeroutput>
+  with <computeroutput>"fb_"</computeroutput>.  It might be worth
+  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>vgskin_foobar_so_SOURCES</computeroutput>
+  variable determines the name of the tool's shared object, which
+  determines what name must be passed to the
+  <computeroutput>--tool</computeroutput> option to use the
+  tool.</para>
+ </listitem>
+
+ <listitem>
+  <para>Copy <filename>none/nl_main.c</filename> into
+  <computeroutput>foobar/</computeroutput>, renaming it as
+  <filename>fb_main.c</filename>.  Edit it by changing the lines
+  in <computeroutput>SK_(pre_clo_init)()</computeroutput> to
+  something appropriate for the tool.  These fields are used in
+  the startup message, except for
+  <computeroutput>bug_reports_to</computeroutput> which is used
+  if a tool assertion fails.</para>
+ </listitem>
+
+  <listitem>
+   <para>Edit <computeroutput>Makefile.am</computeroutput>,
+   adding the new directory
+   <computeroutput>foobar</computeroutput> to the
+   <computeroutput>SUBDIRS</computeroutput> variable.</para>
+  </listitem>
+
+  <listitem>
+   <para>Edit <computeroutput>configure.in</computeroutput>,
+   adding <computeroutput>foobar/Makefile</computeroutput> to the
+   <computeroutput>AC_OUTPUT</computeroutput> list.</para>
+  </listitem>
+
+  <listitem>
+   <para>Run:</para>
+<programlisting><![CDATA[
+  autogen.sh
+  ./configure --prefix=`pwd`/inst
+  make install]]></programlisting>
+
+   <para>It should automake, configure and compile without
+   errors, putting copies of the tool's shared object
+   <computeroutput>vgskin_foobar.so</computeroutput> in
+   <computeroutput>foobar/</computeroutput> and
+   <computeroutput>inst/lib/valgrind/</computeroutput>.</para>
+  </listitem>
+
+  <listitem>
+   <para>You can test it with a command like:</para>
+<programlisting><![CDATA[
+  inst/bin/valgrind --tool=foobar date]]></programlisting>
+
+   <para>(almost any program should work;
+   <computeroutput>date</computeroutput> is just an example).
+   The output should be something like this:</para>
+<programlisting><![CDATA[
+  ==738== foobar-0.0.1, a foobarring tool for x86-linux.
+  ==738== Copyright (C) 1066AD, and GNU GPL'd, by J. Random Hacker.
+  ==738== Built with valgrind-1.1.0, a program execution monitor.
+  ==738== Copyright (C) 2000-2003, and GNU GPL'd, by Julian Seward.
+  ==738== Estimated CPU clock rate is 1400 MHz
+  ==738== For more details, rerun with: -v
+  ==738== Wed Sep 25 10:31:54 BST 2002
+  ==738==]]></programlisting>
+
+   <para>The tool does nothing except run the program
+   uninstrumented.</para>
+  </listitem>
+
+</orderedlist>
+
+<para>These steps don't have to be followed exactly - you can
+choose different names for your source files, and use a different
+<computeroutput>--prefix</computeroutput> for
+<computeroutput>./configure</computeroutput>.</para>
+
+<para>Now that we've setup, built and tested the simplest
+possible tool, onto the interesting stuff...</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.writingcode" xreflabel="Writing the Code">
+<title>Writing the code</title>
+
+<para>A tool must define at least these four functions:</para>
+<programlisting><![CDATA[
+  SK_(pre_clo_init)()
+  SK_(post_clo_init)()
+  SK_(instrument)()
+  SK_(fini)()]]></programlisting>
+
+<para>Also, it must use the macro
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
+exactly once in its source code.  If it doesn't, you will get a
+link error involving
+<computeroutput>VG_(skin_interface_major_version)</computeroutput>.
+This macro is used to ensure the core/tool interface used by the
+core and a plugged-in tool are binary compatible.</para>
+
+<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>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.init" xreflabel="Initialisation">
+<title>Initialisation</title>
+
+<para>Most of the initialisation should be done in
+<computeroutput>SK_(pre_clo_init)()</computeroutput>.  Only use
+<computeroutput>SK_(post_clo_init)()</computeroutput> if a tool
+provides command line options and must do some initialisation
+after option processing takes place
+(<computeroutput>"clo"</computeroutput> stands for "command line
+options").</para>
+
+<para>First of all, various "details" need to be set for a tool,
+using the functions
+<computeroutput>VG_(details_*)()</computeroutput>.  Some are all
+compulsory, some aren't.  Some are used when constructing the
+startup message,
+<computeroutput>detail_bug_reports_to</computeroutput> is used if
+<computeroutput>VG_(skin_panic)()</computeroutput> is ever
+called, or a tool assertion fails.  Others have other uses.</para>
+
+<para>Second, various "needs" can be set for a tool, using the
+functions <computeroutput>VG_(needs_*)()</computeroutput>.  They
+are mostly booleans, and can be left untouched (they default to
+<computeroutput>False</computeroutput>).  They determine whether
+a tool can do various things such as: record, report and suppress
+errors; process command line options; wrap system calls; record
+extra information about malloc'd blocks, etc.</para>
+
+<para>For example, if a tool wants the core's help in recording
+and reporting errors, it must set the
+<computeroutput>skin_errors</computeroutput> need to
+<computeroutput>True</computeroutput>, and then provide
+definitions of six functions for comparing errors, printing out
+errors, reading suppressions from a suppressions file, etc.
+While writing these functions requires some work, it's much less
+than doing error handling from scratch because the core is doing
+most of the work.  See the type
+<computeroutput>VgNeeds</computeroutput> in
+<filename>include/vg_skin.h</filename> for full details of all
+the needs.</para>
+
+<para>Third, the tool can indicate which events in core it wants
+to be notified about, using the functions
+<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>
+
+<para>For example, if the tool want to be notified when a new
+block of memory is malloc'd, it should call
+<computeroutput>VG_(track_new_mem_heap)()</computeroutput> with
+an appropriate function pointer, and the assigned function will
+be called each time this happens.</para>
+
+<para>More information about "details", "needs" and "trackable
+events" can be found in
+<filename>include/vg_skin.h</filename>.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.instr" xreflabel="Instrumentation">
+<title>Instrumentation</title>
+
+<para><computeroutput>SK_(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 
+<xref linkend="mc-tech-docs.ucode"/>.</para>
+
+<para>The easiest way to instrument UCode 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>
+
+
+
+<sect2 id="writing-tools.fini" xreflabel="Finalisation">
+<title>Finalisation</title>
+
+<para>This is where you can present the final results, such as a
+summary of the information collected.  Any log files should be
+written out at this point.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.otherinfo" xreflabel="Other Important Information">
+<title>Other Important Information</title>
+
+<para>Please note that the core/tool split infrastructure is
+quite complex and not brilliantly documented.  Here are some
+important points, but there are undoubtedly many others that I
+should note but haven't thought of.</para>
+
+<para>The file <filename>include/vg_skin.h</filename> contains
+all the types, macros, functions, etc. that a tool should
+(hopefully) need, and is the only <filename>.h</filename> file a
+tool should need to
+<computeroutput>#include</computeroutput>.</para>
+
+<para>In particular, you probably shouldn'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
+<filename>vg_skin.h</filename>.</para>
+
+<para>Similarly, when writing a tool, you shouldn't need to look
+at any of the code in Valgrind's core.  Although it might be
+useful sometimes to help understand something.</para>
+
+<para><filename>vg_skin.h</filename> has a reasonable amount of
+documentation in it that should hopefully be enough to get you
+going.  But ultimately, the tools distributed (Memcheck,
+Addrcheck, Cachegrind, Lackey, etc.) are probably the best
+documentation of all, for the moment.</para>
+
+<para>Note that the <computeroutput>VG_</computeroutput> and
+<computeroutput>SK_</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>SK_</computeroutput> macro for any global
+functions and variables in your tool, or writing a similar
+macro.</para>
+
+</sect2>
+
+
+<sect2 id="writing-tools.advice" xreflabel="Words of Advice">
+<title>Words of Advice</title>
+
+<para>Writing and debugging tools is not trivial.  Here are some
+suggestions for solving common problems.</para>
+
+
+<sect3 id="writing-tools.segfaults">
+<title>Segmentation Faults</title>
+
+<para>If you are getting segmentation faults in C functions used
+by your tool, the usual GDB command:</para>
+<screen><![CDATA[
+  gdb <prog> core]]></screen>
+<para>usually gives the location of the segmentation fault.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.debugfns">
+<title>Debugging C functions</title>
+
+<para>If you want to debug C functions used by your tool, you can
+attach GDB to Valgrind with some effort:</para>
+<orderedlist>
+ <listitem>
+  <para>Enable the following code in
+  <filename>coregrind/vg_main.c</filename> by changing
+  <computeroutput>if (0)</computeroutput> 
+  into <computeroutput>if (1)</computeroutput>:
+<programlisting><![CDATA[
+  /* Hook to delay things long enough so we can get the pid and
+     attach GDB in another shell. */
+  if (0) { 
+    Int p, q;
+    for ( p = 0; p < 50000; p++ )
+      for ( q = 0; q < 50000; q++ ) ;
+  }]]></programlisting>
+  and rebuild Valgrind.</para>
+ </listitem>
+
+ <listitem>
+  <para>Then run:</para>
+<programlisting><![CDATA[
+  valgrind <prog>]]></programlisting>
+  <para>Valgrind starts the program, printing its process id, and
+  then delays for a few seconds (you may have to change the loop
+  bounds to get a suitable delay).</para>
+ </listitem>
+
+ <listitem>
+  <para>In a second shell run:</para>
+<programlisting><![CDATA[
+  gdb <prog pid>]]></programlisting>
+ </listitem>
+
+</orderedlist>
+
+<para>GDB may be able to give you useful information.  Note that
+by default most of the system is built with
+<computeroutput>-fomit-frame-pointer</computeroutput>, and you'll
+need to get rid of this to extract useful tracebacks from GDB.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.ucode-probs">
+<title>UCode Instrumentation Problems</title>
+
+<para>If you are having problems with your UCode instrumentation,
+it's likely that GDB won't be able to help at all.  In this case,
+Valgrind's <computeroutput>--trace-codegen</computeroutput>
+option is invaluable for observing the results of
+instrumentation.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.misc">
+<title>Miscellaneous</title>
+
+<para>If you just want to know whether a program point has been
+reached, using the <computeroutput>OINK</computeroutput> macro
+(in <filename>include/vg_skin.h</filename>) can be easier than
+using GDB.</para>
+
+<para>The other debugging command line options can be useful too
+(run <computeroutput>valgrind -h</computeroutput> for the
+list).</para>
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="writing-tools.advtopics" xreflabel="Advanced Topics">
+<title>Advanced Topics</title>
+
+<para>Once a tool becomes more complicated, there are some extra
+things you may want/need to do.</para>
+
+<sect2 id="writing-tools.suppressions" xreflabel="Suppressions">
+<title>Suppressions</title>
+
+<para>If your tool reports errors and you want to suppress some
+common ones, you can add suppressions to the suppression files.
+The relevant files are
+<computeroutput>valgrind/*.supp</computeroutput>; the final
+suppression file is aggregated from these files by combining the
+relevant <computeroutput>.supp</computeroutput> files depending
+on the versions of linux, X and glibc on a system.</para>
+
+<para>Suppression types have the form
+<computeroutput>tool_name:suppression_name</computeroutput>.  The
+<computeroutput>tool_name</computeroutput> here is the name you
+specify for the tool during initialisation with
+<computeroutput>VG_(details_name)()</computeroutput>.</para>
+
+</sect2>
+
+
+<!--
+<sect2 id="writing-tools.docs" xreflabel="Documentation">
+<title>Documentation</title>
+
+<para>As of version &rel-version;, Valgrind documentation has
+been converted to XML. Why? 
+See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
+</para>
+
+
+<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
+<title>The XML Toolchain</title>
+
+<para>If you are feeling conscientious and want to write some
+documentation for your tool, please use XML.  The Valgrind
+Docs use the following toolchain and versions:</para>
+
+<programlisting>
+ xmllint:   using libxml version 20607
+ xsltproc:  using libxml 20607, libxslt 10102 and libexslt 802
+ pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
+ pdftops:   version 3.00
+ DocBook:   version 4.2
+</programlisting>
+
+<para><command>Latency:</command> you should note that latency is
+a big problem: DocBook is constantly being updated, but the tools
+tend to lag behind somewhat.  It is important that the versions
+get on with each other, so if you decide to upgrade something,
+then you need to ascertain whether things still work nicely -
+this *cannot* be assumed.</para>
+
+<para><command>Stylesheets:</command> The Valgrind docs use
+various custom stylesheet layers, all of which are in
+<computeroutput>valgrind/docs/lib/</computeroutput>. You
+shouldn't need to modify these in any way.</para>
+
+<para><command>Catalogs:</command> Assuming that you have the
+various tools listed above installed, you will probably need to
+modify
+<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
+so that the parser can find your DocBook installation. Catalogs
+provide a mapping from generic addresses to specific local
+directories on a given machine.  Just add another
+<computeroutput>group</computeroutput> to this file, reflecting
+your local installation.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
+<title>Writing the Documentation</title>
+
+<para>If you aren't confident using XML, or you have problems
+with the toolchain, then write your documentation in text format,
+email it to
+<computeroutput>valgrind@valgrind.org</computeroutput>, and
+someone will convert it to XML for you.  Otherwise, follow these
+steps (using <computeroutput>foobar</computeroutput> as the
+example tool name again):</para>
+
+<orderedlist>
+
+  <listitem>
+   <para>Make a directory
+  <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+  <para>Copy the xml tool documentation template file 
+  <computeroutput>valgrind/docs/xml/tool-template.xml</computeroutput>
+  to <computeroutput>foobar/docs/</computeroutput>, and rename it
+  to
+  <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
+  <para><command>Note</command>: there is a *really stupid* tetex
+  bug with underscores in filenames, so don't use '_'.</para>
+ </listitem>
+
+ <listitem>
+  <para>Write the documentation. There are some helpful bits and
+  pieces on using xml markup in
+  <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
+ </listitem>
+
+ <listitem>
+  <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
+  using the shell script
+  <filename>valgrind/docs/lib/xmlproc.sh</filename>.</para>
+<screen><![CDATA[
+% cd valgrind/docs/lib/
+% ./xmlproc.sh -valid ../../foobar/docs/fb-manual.xml
+]]></screen>
+
+   <para>If you have linked to other documents in the Valgrind
+   Documentation Set, you will get errors of the form:</para>
+
+<screen><![CDATA[
+fb-manual.xml:1632: element xref: validity error : 
+        IDREF attribute linkend references an unknown ID "mc-tech-docs"
+]]></screen>
+
+   <para>Ignore (only) these - they will disappear when
+   <filename>fb-manual.xml</filename> is integrated into the
+   Set.</para>
+
+  <para>Because the xml toolchain is fragile, it is important to
+  ensure that <computeroutput>fb-manual.xml</computeroutput> won't
+  break the documentation set build.  Note that just because an
+  xml file happily transforms to html does not necessarily mean
+  the same holds true for pdf/ps.</para>
+ </listitem>
+
+ <listitem>
+  <para>You can (re-)generate <filename>fb-manual.html</filename>
+  while you are writing <filename>fb-manual.xml</filename> to help
+  you see how it's looking.  The generated file
+  <filename>fb-manual.html</filename> will be output in
+  <computeroutput>foobar/docs/</computeroutput>.</para>
+
+<screen><![CDATA[
+% ./xmlproc.sh -html ../../foobar/docs/fb-manual.xml
+]]></screen>
+ </listitem>
+
+ <listitem>
+  <para>When you have finished, generate html, pdf and ps output
+  to check all is well:</para>
+
+<screen><![CDATA[
+% cp ../../foobar/fb-manual.xml .
+% ./xmlproc.sh -test fb-manual.xml
+]]></screen>
+
+   <para>Check the output files (<filename>index.html,
+   fb-manual.pdf, fb-manual.ps</filename>) in
+   <computeroutput>/lib/test/</computeroutput> with the relevant
+   viewers.  When you are happy and have finished tinkering with
+   <computeroutput>fb-manual.xml</computeroutput>:</para>
+
+<screen><![CDATA[
+% ./xmlproc.sh -clean fb-manual.xml
+]]></screen>
+</listitem>
+
+ <listitem>
+  <para>In order for your documentation to be included in the
+  User Manual, the relevant entries must be made in
+  <filename>/valgrind/docs/xml/vg-bookset.xml</filename> in this
+  format (hopefully, it should be pretty obvious):</para>
+
+<programlisting><![CDATA[
+<!ENTITY fb-manual   SYSTEM "../../foobar/docs/fb-manual.xml">
+... ...
+&fb-manual;
+]]></programlisting>
+
+  <para>Send a patch for this to
+  <computeroutput>valgrind@valgrind.org</computeroutput>.</para>
+
+  <para>To achieve true anality, try for a full doc-set build:</para>
+<screen><![CDATA[
+% cd valgrind/docs/
+% make all
+]]></screen>
+ </listitem>
+
+</orderedlist>
+
+</sect3>
+
+</sect2>
+-->
+<sect2 id="writing-tools.docs" xreflabel="Documentation">
+<title>Documentation</title>
+
+<para>As of version &rel-version;, Valgrind documentation has
+been converted to XML. Why? 
+See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
+</para>
+
+
+<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
+<title>The XML Toolchain</title>
+
+<para>If you are feeling conscientious and want to write some
+documentation for your tool, please use XML.  The Valgrind
+Docs use the following toolchain and versions:</para>
+
+<programlisting>
+ xmllint:   using libxml version 20607
+ xsltproc:  using libxml 20607, libxslt 10102 and libexslt 802
+ pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
+ pdftops:   version 3.00
+ DocBook:   version 4.2
+</programlisting>
+
+<para><command>Latency:</command> you should note that latency is
+a big problem: DocBook is constantly being updated, but the tools
+tend to lag behind somewhat.  It is important that the versions
+get on with each other, so if you decide to upgrade something,
+then you need to ascertain whether things still work nicely -
+this *cannot* be assumed.</para>
+
+<para><command>Stylesheets:</command> The Valgrind docs use
+various custom stylesheet layers, all of which are in
+<computeroutput>valgrind/docs/lib/</computeroutput>. You
+shouldn't need to modify these in any way.</para>
+
+<para><command>Catalogs:</command> Assuming that you have the
+various tools listed above installed, you will probably need to
+modify
+<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
+so that the parser can find your DocBook installation. Catalogs
+provide a mapping from generic addresses to specific local
+directories on a given machine.  Just add another
+<computeroutput>group</computeroutput> to this file, reflecting
+your local installation.</para>
+
+</sect3>
+
+
+<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
+<title>Writing the Documentation</title>
+
+<para>Follow these steps (using <computeroutput>foobar</computeroutput>
+as the example tool name again):</para>
+
+<orderedlist>
+
+  <listitem>
+   <para>Make a directory
+  <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+  <para>Copy the XML documentation file for the tool Nulgrind from
+  <computeroutput>valgrind/none/docs/nl-manual.xml</computeroutput>
+  to <computeroutput>foobar/docs/</computeroutput>, and rename it
+  to
+  <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
+  <para><command>Note</command>: there is a *really stupid* tetex
+  bug with underscores in filenames, so don't use '_'.</para>
+ </listitem>
+
+ <listitem>
+  <para>Write the documentation. There are some helpful bits and
+  pieces on using xml markup in
+  <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
+ </listitem>
+
+ <listitem>
+  <para>Include it in the User Manual by adding the relevant entry must
+  be added to <filename>valgrind/docs/xml/manual.xml</filename>.  Copy
+  and edit an existing entry.</para>
+ </listitem>
+
+ <listitem>
+  <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
+  using the following command from within <filename>valgrind/docs/</filename>:
+  </para>
+<screen><![CDATA[
+% make valid
+]]></screen>
+
+   <para>You will probably get errors that look like this:</para>
+
+<screen><![CDATA[
+./xml/index.xml:5: element chapter: validity error : No declaration for
+attribute base of element chapter
+]]></screen>
+
+  <para>Ignore (only) these -- they're not important.</para>
+
+  <para>Because the xml toolchain is fragile, it is important to
+  ensure that <filename>fb-manual.xml</filename> won't
+  break the documentation set build.  Note that just because an
+  xml file happily transforms to html does not necessarily mean
+  the same holds true for pdf/ps.</para>
+ </listitem>
+
+ <listitem>
+  <para>You can (re-)generate the HTML docs
+  while you are writing <filename>fb-manual.xml</filename> to help
+  you see how it's looking.  The generated files end up in
+  <filename>valgrind/docs/html/</filename>.  Use the following
+  command, within <filename>valgrind/docs/</filename>:</para>
+
+<screen><![CDATA[
+% make html-docs
+]]></screen>
+ </listitem>
+
+ <listitem>
+  <para>When you have finished, also generate pdf and ps output
+  to check all is well, from within <filename>valgrind/docs/</filename>:
+  </para>
+
+<screen><![CDATA[
+% make print-docs
+]]></screen>
+
+   <para>Check the output <filename>.pdf</filename> and
+   <filename>.ps</filename> files in
+   <computeroutput>valgrind/docs/print/</computeroutput>. 
+   </para>
+</listitem>
+
+</orderedlist>
+
+</sect3>
+
+</sect2>
+
+
+<sect2 id="writing-tools.regtests" xreflabel="Regression Tests">
+<title>Regression Tests</title>
+
+<para>Valgrind has some support for regression tests.  If you
+want to write regression tests for your tool:</para>
+
+<orderedlist>
+ <listitem>
+  <para>Make a directory
+  <computeroutput>foobar/tests/</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+  <para>Edit <computeroutput>foobar/Makefile.am</computeroutput>,
+  adding <computeroutput>tests</computeroutput> to the
+  <computeroutput>SUBDIRS</computeroutput> variable.</para>
+ </listitem>
+
+ <listitem>
+  <para>Edit <computeroutput>configure.in</computeroutput>,
+  adding <computeroutput>foobar/tests/Makefile</computeroutput>
+  to the <computeroutput>AC_OUTPUT</computeroutput> list.</para>
+ </listitem>
+
+ <listitem>
+  <para>Write
+  <computeroutput>foobar/tests/Makefile.am</computeroutput>.  Use
+  <computeroutput>memcheck/tests/Makefile.am</computeroutput> as
+  an example.</para>
+ </listitem>
+
+ <listitem>
+  <para>Write the tests, <computeroutput>.vgtest</computeroutput>
+  test description files,
+  <computeroutput>.stdout.exp</computeroutput> and
+  <computeroutput>.stderr.exp</computeroutput> expected output
+  files.  (Note that Valgrind's output goes to stderr.)  Some
+  details on writing and running tests are given in the comments
+  at the top of the testing script
+  <computeroutput>tests/vg_regtest</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+  <para>Write a filter for stderr results
+  <computeroutput>foobar/tests/filter_stderr</computeroutput>.
+  It can call the existing filters in
+  <computeroutput>tests/</computeroutput>.  See
+  <computeroutput>memcheck/tests/filter_stderr</computeroutput>
+  for an example; in particular note the
+  <computeroutput>$dir</computeroutput> trick that ensures the
+  filter works correctly from any directory.</para>
+ </listitem>
+
+</orderedlist>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.profiling" xreflabel="Profiling">
+<title>Profiling</title>
+
+<para>To do simple tick-based profiling of a tool, include the
+line:</para>
+<programlisting><![CDATA[
+  #include "vg_profile.c"]]></programlisting>
+<para>in the tool somewhere, and rebuild (you may have to
+<computeroutput>make clean</computeroutput> first).  Then run
+Valgrind with the <computeroutput>--profile=yes</computeroutput>
+option.</para>
+
+<para>The profiler is stack-based; you can register a profiling
+event with
+<computeroutput>VGP_(register_profile_event)()</computeroutput>
+and then use the <computeroutput>VGP_PUSHCC</computeroutput> and
+<computeroutput>VGP_POPCC</computeroutput> macros to record time
+spent doing certain things.  New profiling event numbers must not
+overlap with the core profiling event numbers.  See
+<filename>include/vg_skin.h</filename> for details and Memcheck
+for an example.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.mkhackery" xreflabel="Other Makefile Hackery">
+<title>Other Makefile Hackery</title>
+
+<para>If you add any directories under
+<computeroutput>valgrind/foobar/</computeroutput>, you will need
+to add an appropriate <filename>Makefile.am</filename> to it, and
+add a corresponding entry to the
+<computeroutput>AC_OUTPUT</computeroutput> list in
+<filename>valgrind/configure.in</filename>.</para>
+
+<para>If you add any scripts to your tool (see Cachegrind for an
+example) you need to add them to the
+<computeroutput>bin_SCRIPTS</computeroutput> variable in
+<filename>valgrind/foobar/Makefile.am</filename>.</para>
+
+</sect2>
+
+
+
+<sect2 id="writing-tools.ifacever" xreflabel="Core/tool Interface Versions">
+<title>Core/tool Interface Versions</title>
+
+<para>In order to allow for the core/tool interface to evolve
+over time, Valgrind uses a basic interface versioning system.
+All a tool has to do is use the
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
+macro exactly once in its code.  If not, a link error will occur
+when the tool is built.</para>
+
+<para>The interface version number has the form X.Y.  Changes in
+Y indicate binary compatible changes.  Changes in X indicate
+binary incompatible changes.  If the core and tool has the same
+major version number X they should work together.  If X doesn't
+match, Valgrind will abort execution with an explanation of the
+problem.</para>
+
+<para>This approach was chosen so that if the interface changes
+in the future, old tools won't work and the reason will be
+clearly explained, instead of possibly crashing mysteriously.  We
+have attempted to minimise the potential for binary incompatible
+changes by means such as minimising the use of naked structs in
+the interface.</para>
+
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="writing-tools.finalwords" xreflabel="Final Words">
+<title>Final Words</title>
+
+<para>This whole core/tool business is under active development,
+although it's slowly maturing.</para>
+
+<para>The first consequence of this is that the core/tool
+interface will continue to change in the future; we have no
+intention of freezing it and then regretting the inevitable
+stupidities.  Hopefully most of the future changes will be to add
+new features, hooks, functions, etc, rather than to change old
+ones, which should cause a minimum of trouble for existing tools,
+and we've put some effort into future-proofing the interface to
+avoid binary incompatibility.  But we can't guarantee anything.
+The versioning system should catch any incompatibilities.  Just
+something to be aware of.</para>
+
+<para>The second consequence of this is that we'd love to hear
+your feedback about it:</para>
+
+<itemizedlist>
+ <listitem>
+  <para>If you love it or hate it</para>
+ </listitem>
+ <listitem>
+  <para>If you find bugs</para>
+ </listitem>
+ <listitem>
+  <para>If you write a tool</para>
+ </listitem>
+ <listitem>
+  <para>If you have suggestions for new features, needs,
+  trackable events, functions</para>
+ </listitem>
+ <listitem>
+  <para>If you have suggestions for making tools easier to
+  write</para>
+ </listitem>
+ <listitem>
+  <para>If you have suggestions for improving this
+  documentation</para>
+ </listitem>
+ <listitem>
+  <para>If you don't understand something</para>
+ </listitem>
+</itemizedlist>
+
+<para>or anything else!</para>
+
+<para>Happy programming.</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs/xml/xml_help.txt b/docs/xml/xml_help.txt
new file mode 100644
index 0000000..41d5ed7
--- /dev/null
+++ b/docs/xml/xml_help.txt
@@ -0,0 +1,174 @@
+ <!-- -*- sgml -*- -->
+----------------------------------------------
+Docbook Reference Manual (1999):
+- http://www.oreilly.com/catalog/docbook/
+DocBook XSL: The Complete Guide (2002)
+- http://www.sagehill.net/docbookxsl/index.html
+
+DocBook elements (what tags are allowed where)
+- http://www.oreilly.com/catalog/docbook/chapter/book/refelem.html
+
+Catalogs:
+- http://www.sagehill.net/docbookxsl/WriteCatalog.html
+
+
+----------------------------------------------
+xml to html markup transformations:
+
+<programlisting> --> <pre class="programlisting">
+<screen>         --> <pre class="screen">
+<computeroutput> --> <tt class="computeroutput">
+<literal>        --> <tt>
+<emphasis>       --> <i>
+<command>        --> <b class="command">
+<blockquote>     --> <div class="blockquote">
+                     <blockquote class="blockquote">
+
+Important: inside <screen> and <programlisting> blocks, do NOT
+use 'html entities' in your markup, eg. '&lt;' If you *do* use
+them, they will be output verbatim, which is not what you want.
+
+
+----------------------------------------------
+
+<ulink url="http://..">http://kcachegrind.sourceforge.net</ulink>
+
+
+----------------------------------------------
+<variablelist>                         --> <dl>
+ <varlistentry>
+  <term>TTF</term>                     --> <dt>
+  <listitem>TrueType fonts.</listitem> --> <dd>
+ </varlistentry>
+</variablelist>                        --> <dl>
+
+
+----------------------------------------------
+<itemizedlist>          --> <ul>
+ <listitem>             --> <li>
+  <para>....</para>
+  <para>....</para>
+ </listitem>            --> </li>
+</itemizedlist>         --> </ul>
+
+
+----------------------------------------------
+<orderedlist>           --> <ol>
+ <listitem>             --> <li>
+  <para>....</para>
+  <para>....</para>
+ </listitem>            --> </li>
+</orderedlist>          --> </ol>
+
+
+----------------------------------------------
+To achieve this:
+
+This is a paragraph of text before a list:
+
+  * some text
+
+  * some more text
+
+and this is some more text after the list.
+
+Do this:
+<para>This is a paragraph of text before a list:</para>
+<itemizedlist>
+ <listitem>
+  <para>some text</para>
+ </listitem>
+ <listitem>
+  <para>some more text</para>
+ </listitem>
+</itemizedlist>
+
+
+----------------------------------------------
+To achieve this:
+For further details, see <a href="clientreq">The Mechanism</a>
+
+Do this:
+
+  Given:
+  <sect1 id="clientreq" xreflabel="The Mechanism">
+   <title>The Mechanism</title>
+   <para>...</para>
+  </sect1>
+
+  Then do:
+  For further details, see <xref linkend="clientreq"/>.
+
+
+----------------------------------------------
+To achieve this:
+<p><b>Warning:</b> Only do this if ...</p>
+
+Do this:
+<formalpara>
+ <title>Warning:</title>
+ <para>Only do this if ...</para>
+</formalpara>
+
+Or this:
+<para><command>Warning:</command> Only do this if ... </para>
+
+
+----------------------------------------------
+To achieve this:
+<p>It uses the Eraser algorithm described in:<br />
+<br />
+  Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br />
+  Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br />
+  ACM Transactions on Computer Systems, 15(4):391-411<br />
+  November 1997.<br />
+</p>
+
+Do this:
+<literallayout>
+It uses the Eraser algorithm described in:
+
+  Eraser: A Dynamic Data Race Detector for Multithreaded Programs
+  Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson
+  ACM Transactions on Computer Systems, 15(4):391-411
+  November 1997.
+</literallayout>
+
+
+----------------------------------------------
+To achieve this:
+<pre>
+/* Hook to delay things long enough so we can get the pid 
+   and attach GDB in another shell. */
+if (0) { 
+  Int p, q;
+  for ( p = 0; p < 50000; p++ )
+    for ( q = 0; q < 50000; q++ ) ;
+</pre>
+
+Do this:
+<programlisting><![CDATA[
+/* Hook to delay things long enough so we can get the pid
+   and attach GDB in another shell. */
+if (0) { 
+  Int p, q;
+  for ( p = 0; p < 50000; p++ )
+    for ( q = 0; q < 50000; q++ ) ;
+}]]></programlisting>
+
+
+(do the same thing for <screen> tag)
+
+
+----------------------------------------------
+To achieve this:
+  where <i><code>TAG</code></i> has the ...
+
+Do this:
+  where <emphasis><computeroutput>TAG</computeroutput></emphasis> has the ...
+
+Note: you cannot put <emphasis> inside <computeroutput>, unfortunately.
+
+----------------------------------------------
+
+Any other helpful hints?  Please tell us.