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.

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.

[Nb: What follows is slightly out of date.]

The key idea behind Valgrind's architecture is the division between its "core" and "tools".

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.

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.

An important concept to understand before writing a tool is that there are three spaces in which program code executes:

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:

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).

Here is a list of ideas we have had for tools that should not be too hard to implement.

We would love to hear from anyone who implements these or other tools.

Tools must define various functions for instrumenting programs that are called by Valgrind's core. They are then linked against the coregrind library (libcoregrind.a) that valgrind provides as well as the VEX library (libvex.a) that also comes with valgrind and provides the JIT engine.

Each tool is linked as a statically linked program and placed in the valgrind library directory from where valgrind will load it automatically when the --tool option is used to select it.

To write your own tool, you'll need the Valgrind source code. A normal source distribution should do, although you might want to check out the latest code from the Subversion repository. See the information about how to do so at the Valgrind website.

Valgrind uses GNU automake and autoconf 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.

In what follows, all filenames are relative to Valgrind's top-level directory valgrind/.

These steps don't have to be followed exactly - you can choose different names for your source files, and use a different --prefix for ./configure.

Now that we've setup, built and tested the simplest possible tool, onto the interesting stuff...

A tool must define at least these four functions:

  pre_clo_init()
  post_clo_init()
  instrument()
  fini()

Also, it must use the macro VG_DETERMINE_INTERFACE_VERSION exactly once in its source code. If it doesn't, you will get a link error involving VG_(tool_interface_version). This macro is used to ensure the core/tool interface used by the core and a plugged-in tool are binary compatible.

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 code about them.

Most of the initialisation should be done in pre_clo_init(). Only use post_clo_init() if a tool provides command line options and must do some initialisation after option processing takes place ("clo" stands for "command line options").

First of all, various "details" need to be set for a tool, using the functions VG_(details_*)(). Some are all compulsory, some aren't. Some are used when constructing the startup message, detail_bug_reports_to is used if VG_(tool_panic)() is ever called, or a tool assertion fails. Others have other uses.

Second, various "needs" can be set for a tool, using the functions VG_(needs_*)(). They are mostly booleans, and can be left untouched (they default to False). 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.

For example, if a tool wants the core's help in recording and reporting errors, it must call VG_(needs_tool_errors) 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 VG_(needs_tool_errors) in include/pub_tool_tooliface.h for full details of all the needs.

Third, the tool can indicate which events in core it wants to be notified about, using the functions VG_(track_*)(). 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.

For example, if the tool want to be notified when a new block of memory is malloc'd, it should call VG_(track_new_mem_heap)() with an appropriate function pointer, and the assigned function will be called each time this happens.

More information about "details", "needs" and "trackable events" can be found in include/pub_tool_tooliface.h.

instrument() is the interesting one. It allows you to instrument VEX IR, which is Valgrind's RISC-like intermediate language. VEX IR is described in Introduction to UCode.

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

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.

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.

The files include/pub_tool_*.h contain all the types, macros, functions, etc. that a tool should (hopefully) need, and are the only .h files a tool should need to #include.

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 pub_tool_libc*.h.

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.

The pub_tool_*.h files have a reasonable amount of documentation in it that should hopefully be enough to get you going. But ultimately, the tools distributed (Memcheck, Cachegrind, Lackey, etc.) are probably the best documentation of all, for the moment.

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

Writing and debugging tools is not trivial. Here are some suggestions for solving common problems.

  gdb <prog> core

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 valgrind/*.supp; the final suppression file is aggregated from these files by combining the relevant .supp files depending on the versions of linux, X and glibc on a system.

Suppression types have the form tool_name:suppression_name. The tool_name here is the name you specify for the tool during initialisation with VG_(details_name)().

As of version 3.0.0, Valgrind documentation has been converted to XML. Why? See The XML FAQ.

 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

Valgrind has some support for regression tests. If you want to write regression tests for your tool:

To profile a tool, use Cachegrind on it. Read README_DEVELOPERS for details on running Valgrind under Valgrind.

To do simple tick-based profiling of a tool, include the line:

  #include "vg_profile.c"

in the tool somewhere, and rebuild (you may have to make clean first). Then run Valgrind with the --profile=yes option.

The profiler is stack-based; you can register a profiling event with VG_(register_profile_event)() and then use the VGP_PUSHCC and VGP_POPCC macros to record time spent doing certain things. New profiling event numbers must not overlap with the core profiling event numbers. See include/pub_tool_profile.h for details and Memcheck for an example.

If you add any directories under valgrind/foobar/, you will need to add an appropriate Makefile.am to it, and add a corresponding entry to the AC_OUTPUT list in valgrind/configure.in.

If you add any scripts to your tool (see Cachegrind for an example) you need to add them to the bin_SCRIPTS variable in valgrind/foobar/Makefile.am.

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 VG_DETERMINE_INTERFACE_VERSION macro exactly once in its code. If not, a link error will occur when the tool is built.

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.

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.