Release notes for Valgrind
~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are building a binary package of Valgrind for distribution,
please read README_PACKAGERS.  It contains some important information.

If you are developing Valgrind, please read README_DEVELOPERS.  It contains
some useful information.

For instructions on how to build/install, see the end of this file.

If you have problems, consult the FAQ to see if there are workarounds.


Executive Summary
~~~~~~~~~~~~~~~~~
Valgrind is a framework for building dynamic analysis tools. There are
Valgrind tools that can automatically detect many memory management
and threading bugs, and profile your programs in detail. You can also
use Valgrind to build new tools.

The Valgrind distribution currently includes six production-quality
tools: a memory error detector, two thread error detectors, a cache
and branch-prediction profiler, a call-graph generating cache abd
branch-prediction profiler, and a heap profiler. It also includes
three experimental tools: a heap/stack/global array overrun detector,
a different kind of heap profiler, and a SimPoint basic block vector
generator.

Valgrind is closely tied to details of the CPU, operating system and to
a lesser extent, compiler and basic C libraries. This makes it difficult
to make it portable.  Nonetheless, it is available for the following
platforms:

- x86/Linux
- AMD64/Linux
- PPC32/Linux
- PPC64/Linux
- ARM/Linux
- x86/MacOSX
- AMD64/MacOSX

Note that AMD64 is just another name for x86-64, and Valgrind runs fine
on Intel processors.  Also note that the core of MacOSX is called
"Darwin" and this name is used sometimes.

Valgrind is licensed under the GNU General Public License, version 2.
Read the file COPYING in the source distribution for details.

However: if you contribute code, you need to make it available as GPL
version 2 or later, and not 2-only.


Documentation
~~~~~~~~~~~~~
A comprehensive user guide is supplied.  Point your browser at
$PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
specified with --prefix= when building.


Building and installing it
~~~~~~~~~~~~~~~~~~~~~~~~~~
To install from the Subversion repository :

  0. Check out the code from SVN, following the instructions at
     http://www.valgrind.org/downloads/repository.html.

  1. cd into the source directory.

  2. Run ./autogen.sh to setup the environment (you need the standard
     autoconf tools to do so).

  3. Continue with the following instructions...

To install from a tar.bz2 distribution:

  4. Run ./configure, with some options if you wish.  The only interesting
     one is the usual --prefix=/where/you/want/it/installed.

  5. Run "make".

  6. Run "make install", possibly as root if the destination permissions
     require that.

  7. See if it works.  Try "valgrind ls -l".  Either this works, or it
     bombs out with some complaint.  In that case, please let us know
     (see www.valgrind.org).

Important!  Do not move the valgrind installation into a place
different from that specified by --prefix at build time.  This will
cause things to break in subtle ways, mostly when Valgrind handles
fork/exec calls.


The Valgrind Developers

Building and not installing it
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To run Valgrind without having to install it, run coregrind/valgrind
with the VALGRIND_LIB environment variable set, where <dir> is the root
of the source tree (and must be an absolute path).  Eg:

  VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind

This allows you to compile and run with "make" instead of "make install",
saving you time.

Or, you can use the 'vg-in-place' script which does that for you.

I recommend compiling with "make --quiet" to further reduce the amount of
output spewed out during compilation, letting you actually see any errors,
warnings, etc.


Building a distribution tarball
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build a distribution tarball from the valgrind sources:

  make dist

In addition to compiling, linking and packaging everything up, the command
will also build the documentation. Even if all required tools for building the
documentation are installed, this step may not succeed because of hidden
dependencies. E.g. on Ubuntu you must have "docbook-xsl" installed.
Additionally, specific tool versions maybe needed.

If you only want to test whether the generated tarball is complete and runs
regression tests successfully, building documentation is not needed.
Edit docs/Makefile.am, search for BUILD_ALL_DOCS and follow instructions there.


Running the regression tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build and run all the regression tests, run "make [--quiet] regtest".

To run a subset of the regression tests, execute:

  perl tests/vg_regtest <name>

where <name> is a directory (all tests within will be run) or a single
.vgtest test file, or the name of a program which has a like-named .vgtest
file.  Eg:

  perl tests/vg_regtest memcheck
  perl tests/vg_regtest memcheck/tests/badfree.vgtest
  perl tests/vg_regtest memcheck/tests/badfree


Running the performance tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build and run all the performance tests, run "make [--quiet] perf".

To run a subset of the performance suite, execute:

  perl perf/vg_perf <name>

where <name> is a directory (all tests within will be run) or a single
.vgperf test file, or the name of a program which has a like-named .vgperf
file.  Eg:

  perl perf/vg_perf perf/
  perl perf/vg_perf perf/bz2.vgperf
  perl perf/vg_perf perf/bz2

To compare multiple versions of Valgrind, use the --vg= option multiple
times.  For example, if you have two Valgrinds next to each other, one in
trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
compare them on all the performance tests:

  perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/


Debugging Valgrind with GDB
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To debug the valgrind launcher program (<prefix>/bin/valgrind) just
run it under gdb in the normal way.

Debugging the main body of the valgrind code (and/or the code for
a particular tool) requires a bit more trickery but can be achieved
without too much problem by following these steps:

(1) Set VALGRIND_LAUNCHER to point to the valgrind executable.  Eg:

      export VALGRIND_LAUNCHER=/usr/local/bin/valgrind

    or for an uninstalled version in a source directory $DIR:

      export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind

(2) Run gdb on the tool executable.  Eg:

      gdb /usr/local/lib/valgrind/ppc32-linux/lackey

    or

      gdb $DIR/.in_place/x86-linux/memcheck

(3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
    stopping on a SIGSEGV or SIGILL:

    (gdb) handle SIGILL SIGSEGV nostop noprint

(4) Set any breakpoints you want and proceed as normal for gdb. 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:

    (gdb) b vgPlain_do_exec

(5) Run the tool with required options:

    (gdb) run pwd

Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
be fully expanded (ie. not an environment variable).

A different and possibly easier way is as follows:

(1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes.  This
    puts the tool executable into a wait loop soon after it gains
    control.  This delays startup for a few seconds.

(2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
    <pid> you read from the output printed by (1).  This attaches
    GDB to the tool executable, which should be in the abovementioned
    wait loop.

(3) Do "cont" to continue.  After the loop finishes spinning, startup
    will continue as normal.  Note that comment (3) above re passing
    signals applies here too.


Self-hosting
~~~~~~~~~~~~
To run Valgrind under Valgrind:

(1) Check out 2 trees, "Inner" and "Outer".  Inner runs the app
    directly.  Outer runs Inner.

(2) Configure inner with --enable-inner and build/install as
    usual.

(3) Configure Outer normally and build/install as usual.

(4) Choose a very simple program (date) and try

    outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
       --tool=cachegrind -v inner/.../bin/valgrind --tool=none -v prog

If you omit the --trace-children=yes, you'll only monitor Inner's launcher
program, not its stage2.

The whole thing is fragile, confusing and slow, but it does work well enough
for you to get some useful performance data.  Inner has most of
its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
which helps a lot.

At the time of writing the allocator is not annotated with client requests
so Memcheck is not as useful as it could be.  It also has not been tested
much, so don't be surprised if you hit problems.

When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
(on the outer). Otherwise, Callgrind has much higher memory requirements.


Printing out problematic blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to print out a disassembly of a particular block that
causes a crash, do the following.

Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
--trace-notbelow=999999".  This should print one line for each block
translated, and that includes the address.

Then re-run with 999999 changed to the highest bb number shown.
This will print the one line per block, and also will print a
disassembly of the block in which the fault occurred.

Dealing with missing system call or ioctl wrappers in Valgrind
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You're probably reading this because Valgrind bombed out whilst
running your program, and advised you to read this file.  The good
news is that, in general, it's easy to write the missing syscall or
ioctl wrappers you need, so that you can continue your debugging.  If
you send the resulting patches to me, then you'll be doing a favour to
all future Valgrind users too.

Note that an "ioctl" is just a special kind of system call, really; so
there's not a lot of need to distinguish them (at least conceptually)
in the discussion that follows.

All this machinery is in coregrind/m_syswrap.


What are syscall/ioctl wrappers?  What do they do?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Valgrind does what it does, in part, by keeping track of everything your
program does.  When a system call happens, for example a request to read
part of a file, control passes to the Linux kernel, which fulfills the
request, and returns control to your program.  The problem is that the
kernel will often change the status of some part of your program's memory
as a result, and tools (instrumentation plug-ins) may need to know about
this.

Syscall and ioctl wrappers have two jobs:

1. Tell a tool what's about to happen, before the syscall takes place.  A
   tool could perform checks beforehand, eg. if memory about to be written
   is actually writeable.  This part is useful, but not strictly
   essential.

2. Tell a tool what just happened, after a syscall takes place.  This is
   so it can update its view of the program's state, eg. that memory has
   just been written to.  This step is essential.

The "happenings" mostly involve reading/writing of memory.

So, let's look at an example of a wrapper for a system call which
should be familiar to many Unix programmers.


The syscall wrapper for time()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The wrapper for the time system call looks like this:

  PRE(sys_time)
  {
     /* time_t time(time_t *t); */
     PRINT("sys_time ( %p )",ARG1);
     PRE_REG_READ1(long, "time", int *, t);
     if (ARG1 != 0) {
        PRE_MEM_WRITE( "time(t)", ARG1, sizeof(vki_time_t) );
     }
  }

  POST(sys_time)
  {
     if (ARG1 != 0) {
        POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
     }
  }

The first thing we do happens before the syscall occurs, in the PRE() function.
The PRE() function typically starts with invoking to the PRINT() macro. This
PRINT() macro implements support for the --trace-syscalls command line option.
Next, the tool is told the return type of the syscall, that the syscall has
one argument, the type of the syscall argument and that the argument is being
read from a register:

     PRE_REG_READ1(long, "time", int *, t);

Next, if a non-NULL buffer is passed in as the argument, tell the tool that the
buffer is about to be written to:

     if (ARG1 != 0) {
        PRE_MEM_WRITE( "time", ARG1, sizeof(vki_time_t) );
     }

Finally, the really important bit, after the syscall occurs, in the POST()
function:  if, and only if, the system call was successful, tell the tool that
the memory was written:

     if (ARG1 != 0) {
        POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
     }

The POST() function won't be called if the syscall failed, so you
don't need to worry about checking that in the POST() function.
(Note: this is sometimes a bug; some syscalls do return results when
they "fail" - for example, nanosleep returns the amount of unslept
time if interrupted. TODO: add another per-syscall flag for this
case.)

Note that we use the type 'vki_time_t'.  This is a copy of the kernel
type, with 'vki_' prefixed.  Our copies of such types are kept in the
appropriate vki*.h file(s).  We don't include kernel headers or glibc headers
directly.


Writing your own syscall wrappers (see below for ioctl wrappers)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If Valgrind tells you that system call NNN is unimplemented, do the
following:

1.  Find out the name of the system call:

       grep NNN /usr/include/asm/unistd*.h

    This should tell you something like  __NR_mysyscallname.
    Copy this entry to include/vki/vki-scnums-$(VG_PLATFORM).h.


2.  Do 'man 2 mysyscallname' to get some idea of what the syscall
    does.  Note that the actual kernel interface can differ from this,
    so you might also want to check a version of the Linux kernel
    source.

    NOTE: any syscall which has something to do with signals or
    threads is probably "special", and needs more careful handling.
    Post something to valgrind-developers if you aren't sure.


3.  Add a case to the already-huge collection of wrappers in
    the coregrind/m_syswrap/syswrap-*.c files.
    For each in-memory parameter which is read or written by
    the syscall, do one of

      PRE_MEM_READ( ... )
      PRE_MEM_RASCIIZ( ... )
      PRE_MEM_WRITE( ... )

    for  that parameter.  Then do the syscall.  Then, if the syscall
    succeeds, issue suitable POST_MEM_WRITE( ... ) calls.
    (There's no need for POST_MEM_READ calls.)

    Also, add it to the syscall_table[] array; use one of GENX_, GENXY
    LINX_, LINXY, PLAX_, PLAXY.
    GEN* for generic syscalls (in syswrap-generic.c), LIN* for linux
    specific ones (in syswrap-linux.c) and PLA* for the platform
    dependant ones (in syswrap-$(PLATFORM)-linux.c).
    The *XY variant if it requires a PRE() and POST() function, and
    the *X_ variant if it only requires a PRE()
    function.

    If you find this difficult, read the wrappers for other syscalls
    for ideas.  A good tip is to look for the wrapper for a syscall
    which has a similar behaviour to yours, and use it as a
    starting point.

    If you need structure definitions and/or constants for your syscall,
    copy them from the kernel headers into include/vki.h and co., with
    the appropriate vki_*/VKI_* name mangling.  Don't #include any
    kernel headers.  And certainly don't #include any glibc headers.

    Test it.

    Note that a common error is to call POST_MEM_WRITE( ... )
    with 0 (NULL) as the first (address) argument.  This usually means
    your logic is slightly inadequate.  It's a sufficiently common bug
    that there's a built-in check for it, and you'll get a "probably
    sanity check failure" for the syscall wrapper you just made, if this
    is the case.


4.  Once happy, send us the patch.  Pretty please.




Writing your own ioctl wrappers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Is pretty much the same as writing syscall wrappers, except that all
the action happens within PRE(ioctl) and POST(ioctl).

There's a default case, sometimes it isn't correct and you have to write a
more specific case to get the right behaviour.

As above, please create a bug report and attach the patch as described
on http://www.valgrind.org.

Greetings, packaging person!  This information is aimed at people
building binary distributions of Valgrind.

Thanks for taking the time and effort to make a binary distribution of
Valgrind.  The following notes may save you some trouble.


-- Do not ship your Linux distro with a completely stripped
   /lib/ld.so.  At least leave the debugging symbol names on -- line
   number info isn't necessary.  If you don't want to leave symbols on
   ld.so, alternatively you can have your distro install ld.so's
   debuginfo package by default, or make ld.so.debuginfo be a
   requirement of your Valgrind RPM/DEB/whatever.

   Reason for this is that Valgrind's Memcheck tool needs to intercept
   calls to, and provide replacements for, some symbols in ld.so at
   startup (most importantly strlen).  If it cannot do that, Memcheck
   shows a large number of false positives due to the highly optimised
   strlen (etc) routines in ld.so.  This has caused some trouble in
   the past.  As of version 3.3.0, on some targets (ppc32-linux,
   ppc64-linux), Memcheck will simply stop at startup (and print an
   error message) if such symbols are not present, because it is
   infeasible to continue.

   It's not like this is going to cost you much space.  We only need
   the symbols for ld.so (a few K at most).  Not the debug info and
   not any debuginfo or extra symbols for any other libraries.


-- (Unfortunate but true) When you configure to build with the
   --prefix=/foo/bar/xyzzy option, the prefix /foo/bar/xyzzy gets
   baked into valgrind.  The consequence is that you _must_ install
   valgrind at the location specified in the prefix.  If you don't,
   it may appear to work, but will break doing some obscure things,
   particularly doing fork() and exec().

   So you can't build a relocatable RPM / whatever from Valgrind.


-- Don't strip the debug info off lib/valgrind/$platform/vgpreload*.so
   in the installation tree.  Either Valgrind won't work at all, or it
   will still work if you do, but will generate less helpful error
   messages.  Here's an example:

   Mismatched free() / delete / delete []
      at 0x40043249: free (vg_clientfuncs.c:171)
      by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
      by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
      by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
      Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
      at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152)
      by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
      by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
      by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)

   This tells you that some memory allocated with new[] was freed with
   free().

   Mismatched free() / delete / delete []
      at 0x40043249: (inside vgpreload_memcheck.so)
      by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
      by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
      by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
      Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
      at 0x4004318C: (inside vgpreload_memcheck.so)
      by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
      by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
      by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)

   This isn't so helpful.  Although you can tell there is a mismatch,
   the names of the allocating and deallocating functions are no longer
   visible.  The same kind of thing occurs in various other messages
   from valgrind.


-- Don't strip symbols from lib/valgrind/* in the installation tree.
   Doing so will likely cause problems.  Removing the line number info is
   probably OK (at least for some of the files in that directory), although
   that has not been tested by the Valgrind developers.


-- Please test the final installation works by running it on something
   huge.  I suggest checking that it can start and exit successfully
   both Firefox and OpenOffice.org.  I use these as test programs, and I
   know they fairly thoroughly exercise Valgrind.  The command lines to use
   are:

   valgrind -v --trace-children=yes firefox

   valgrind -v --trace-children=yes soffice


If you find any more hints/tips for packaging, please report
it as a bugreport. See http://www.valgrind.org for details.