docs/xml/manual-writing-tools.xml

<?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 "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>

So you want to write a Valgrind tool?  Here are some instructions that may
help.  They were last updated for Valgrind 3.2.2.

<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 "tool plug-ins".</para>

<para>The core provides the common low-level infrastructure to
support program instrumentation, including the JIT
compiler, low-level memory manager, signal handling and a
scheduler (for pthreads).  It also provides certain services that
are useful to some but not all tools, such as support for error
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 call certain
functions to indicate to the core that they would like to use
certain services, or be notified when certain interesting events
occur.  But the core takes care of all the hard work.</para>

</sect2>

</sect1>



<sect1 id="writing-tools.writingatool" xreflabel="Writing a Tool">
<title>Writing a Tool</title>

<sect2 id="writing-tools.howtoolswork" xreflabel="How tools work">
<title>How tools work</title>

<para>Tool plug-ins must define various functions for instrumenting programs
that are called by Valgrind's core. They are then linked against
Valgrind's core to define a complete Valgrind tool which will be used
when the <option>--tool</option> option is used to select it.</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 the Valgrind source code.  You'll
need a check-out of the Subversion repository for the automake/autoconf
build instructions to work.  See the information about how to do check-out
from the repository at <ulink url="&vg-svn-repo;">the Valgrind
website</ulink>.</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 a two-letter 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 three new directories <filename>foobar/</filename>,
  <filename>foobar/docs/</filename> and
  <filename>foobar/tests/</filename>.
  </para>
 </listitem>

 <listitem>
  <para>Create empty files
  <filename>foobar/docs/Makefile.am</filename> and
  <filename>foobar/tests/Makefile.am</filename>.
  </para>
 </listitem>

 <listitem>
  <para>Copy <filename>none/Makefile.am</filename> into
  <filename>foobar/</filename>.  Edit it by replacing all
  occurrences of the string <computeroutput>"none"</computeroutput> with
  <computeroutput>"foobar"</computeroutput>, and all occurrences of
  the string <computeroutput>"nl_"</computeroutput> with
  <computeroutput>"fb_"</computeroutput>.</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
  <computeroutput>details</computeroutput> lines in
  <function>nl_pre_clo_init()</function> 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.  Also replace the string
  <computeroutput>"nl_"</computeroutput> with  
  <computeroutput>"fb_"</computeroutput> again.</para>
 </listitem>

  <listitem>
   <para>Edit <filename>Makefile.am</filename>, adding the new directory
   <filename>foobar</filename> to the
   <computeroutput>TOOLS</computeroutput> variable.</para>
  </listitem>

  <listitem>
   <para>Edit <filename>configure.in</filename>, adding
   <filename>foobar/Makefile</filename>,
   <filename>foobar/docs/Makefile</filename> and
   <filename>foobar/tests/Makefile</filename> 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 in
   <filename>foobar/</filename> and
   <filename>inst/lib/valgrind/</filename>.</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
<option>--prefix</option> 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[
  pre_clo_init()
  post_clo_init()
  instrument()
  fini()]]></programlisting>

<para>The names can be different to the above, but these are the usual
names.  The first one is registered using the macro
<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> (which also
checks that the core/tool interface of the tool matches that of the core).
The last three are registered using the
<computeroutput>VG_(basic_tool_funcs)</computeroutput> function.</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 and tell the
core about them.</para>

</sect2>



<sect2 id="writing-tools.init" xreflabel="Initialisation">
<title>Initialisation</title>

<para>Most of the initialisation should be done in
<function>pre_clo_init()</function>.  Only use
<function>post_clo_init()</function> 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 <function>VG_(details_*)()</function>.  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_(tool_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
<function>VG_(needs_*)()</function>.  They are mostly booleans, and can
be left untouched (they default to <varname>False</varname>).  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 call
<function>VG_(needs_tool_errors)</function> and provide definitions of
eight 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
function <function>VG_(needs_tool_errors)</function> in
<filename>include/pub_tool_tooliface.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 <function>VG_(track_*)()</function>.
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 provide a pointer to a function, which will be
called when that event happens.</para>

<para>For example, if the tool want to be notified when a new block of
memory is malloc'd, it should call
<function>VG_(track_new_mem_heap)()</function> 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/pub_tool_tooliface.h</filename>.</para>

</sect2>



<sect2 id="writing-tools.instr" xreflabel="Instrumentation">
<title>Instrumentation</title>

<para><function>instrument()</function> is the interesting one.  It
allows you to instrument <emphasis>VEX IR</emphasis>, which is
Valgrind's RISC-like intermediate language.  VEX IR is best described in
the header file <filename>VEX/pub/libvex_ir.h</filename>.</para>

<para>The easiest way to instrument VEX IR is to insert calls to C
functions when interesting things happen.  See the tool "Lackey"
(<filename>lackey/lk_main.c</filename>) for a simple example of this, or
Cachegrind (<filename>cachegrind/cg_main.c</filename>) for a more
complex example.</para>

</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 files <filename>include/pub_tool_*.h</filename> contain all the
types, macros, functions, etc. that a tool should (hopefully) need, and are
the only <filename>.h</filename> files a tool should need to
<computeroutput>#include</computeroutput>.</para>

<para>In particular, you can't use anything from the C library (there
are deep reasons for this, trust us).  Valgrind provides an
implementation of a reasonable subset of the C library, details of which
are in <filename>pub_tool_libc*.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>The <filename>pub_tool_*.h</filename> files have a reasonable
amount of documentation in it that should hopefully be enough to get
you going.  
Also, <filename>VEX/pub/libvex_basictypes.h</filename> and
<filename>VEX/pub/libvex_ir.h</filename> have some more details that are
worth reading, particularly about VEX IR.  But ultimately, the tools
distributed (Memcheck, Cachegrind, Lackey, etc.) are probably the best
documentation of all, for the moment.</para>

<para>Note that the <computeroutput>VG_</computeroutput> macro is used
heavily.  This just prepends a longer string in front of names to avoid
potential namespace clashes.</para>

</sect2>


<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
achieve this by following these steps:</para>
<orderedlist>
  <listitem>
    <para>Set <computeroutput>VALGRIND_LAUNCHER</computeroutput> to
    <computeroutput><![CDATA[<prefix>/bin/valgrind]]></computeroutput>:</para>
<programlisting>
  export VALGRIND_LAUNCHER=/usr/local/bin/valgrind</programlisting>
  </listitem>

  <listitem>
    <para>Then run <computeroutput><![CDATA[ gdb <prefix>/lib/valgrind/<platform>/<tool>:]]></computeroutput></para>
<programlisting>
  gdb /usr/local/lib/valgrind/ppc32-linux/lackey</programlisting>
  </listitem>

  <listitem>
    <para>Do <computeroutput>handle SIGSEGV SIGILL nostop
    noprint</computeroutput> in GDB to prevent GDB from stopping on a
    SIGSEGV or SIGILL:</para>
<programlisting>
  (gdb) handle SIGILL SIGSEGV nostop noprint</programlisting>
  </listitem>

  <listitem>
    <para>Set any breakpoints you want and proceed as normal for GDB:</para>
<programlisting>
  (gdb) b vgPlain_do_exec</programlisting>
    <para>The macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you
    want to set a breakpoint VG_(do_exec), you could do like this in
    GDB.</para>
  </listitem>

  <listitem>
    <para>Run the tool with required options:</para>
<programlisting>
  (gdb) run `pwd`</programlisting>
  </listitem>

</orderedlist>

<para>GDB may be able to give you useful information.  Note that by
default most of the system is built with
<option>-fomit-frame-pointer</option>, and you'll need to get rid of
this to extract useful tracebacks from GDB.</para>

</sect3>


<sect3 id="writing-tools.ucode-probs">
<title>IR Instrumentation Problems</title>

<para>If you are having problems with your VEX IR instrumentation, it's
likely that GDB won't be able to help at all.  In this case, Valgrind's
<option>--trace-flags</option> 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/pub_tool_libcprint.h</filename>) can be easier than
using GDB.</para>

<para>The other debugging command line options can be useful too (run
<computeroutput>valgrind --help-debug</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 <filename>valgrind/*.supp</filename>; the final suppression
file is aggregated from these files by combining the relevant
<filename>.supp</filename> 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
<function>VG_(details_name)()</function>.</para>

</sect2>


<sect2 id="writing-tools.docs" xreflabel="Documentation">
<title>Documentation</title>

<para>As of version 3.0.0, 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> Catalogs provide a mapping from
generic addresses to specific local directories on a given machine.
Most recent Linux distributions have adopted a common place for storing
catalogs (<filename>/etc/xml/</filename>).  Assuming that you have the
various tools listed above installed, you probably won't need to modify
your catalogs.  But if you do, then 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>The docs go in
   <computeroutput>valgrind/foobar/docs/</computeroutput>, which you will
   have created when you started writing the tool.</para>
  </listitem>

  <listitem>
    <para>Write <filename>foobar/docs/Makefile.am</filename>.  Use
    <filename>memcheck/docs/Makefile.am</filename> as an
    example.</para>
  </listitem>

  <listitem>
    <para>Copy the XML documentation file for the tool Nulgrind from
    <filename>valgrind/none/docs/nl-manual.xml</filename> to
    <computeroutput>foobar/docs/</computeroutput>, and rename it to
    <filename>foobar/docs/fb-manual.xml</filename>.</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 to
    <filename>valgrind/docs/xml/manual.xml</filename>.  Copy and edit an
    existing entry.</para>
  </listitem>

  <listitem>
    <para>Validate <filename>foobar/docs/fb-manual.xml</filename> 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>The tests go in <computeroutput>foobar/tests/</computeroutput>,
    which you will have created when you started writing the tool.</para>
  </listitem>

  <listitem>
    <para>Write <filename>foobar/tests/Makefile.am</filename>.  Use
    <filename>memcheck/tests/Makefile.am</filename> 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 profile a tool, use Cachegrind on it.  Read README_DEVELOPERS for
details on running Valgrind under Valgrind.</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 is changed when binary incompatible
changes are made to the interface.  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>The core/tool interface is not fixed.  It's pretty stable these days,
but it does change.  We deliberately do not provide backward compatibility
with old interfaces, because it is too difficult and too restrictive.
The interface checking should catch any incompatibilities.  We view this as
a good thing -- if we had to be backward compatible with earlier versions,
many improvements now in the system could not have been added.
</para>


<para>Happy programming.</para>

</sect1>

</chapter>