Use for LKL
~~~~~~~~~~~
Since LKL can grab shared resources during LD_PRELOAD (e.g. a TAP
device), it can have a problem with Vaglrind: the host kernel runs the
code in LD_PRELOAD for the Valgrind process, then Valgrind re-runs
LD_PRELOAD for the process it is instrumenting. Now the "inner" LKL
will fail with an error that its TAP device is used and quit
immediately, while the "outer" LKL uselessly holds on to it.

We can fix this by adding two new environment variables,
LKL_LIBRARY_PATH and LKL_PRELOAD, that Valgrind waits to put into
LD_LIBRARY_PATH and LD_PRELOAD until right before it starts executing
the instrumented process. For example:

Desired behavior:

    $ sudo LKL_HIJACK_NET_TAP=eth0 LD_LIBRARY_PATH=lib LD_PRELOAD=liblkl-hijack.so ip link         
    1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default 
        link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN mode DEFAULT group default qlen 1000
        link/ether 76:fb:8f:22:3d:77 brd ff:ff:ff:ff:ff:ff
    3: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN mode DEFAULT group default 


Incorrect behavior under normal Valgrind: 

    $ sudo LKL_HIJACK_NET_TAP=eth0 LD_LIBRARY_PATH=lib LD_PRELOAD=liblkl-hijack.so valgrind ip link
    failed to attach to eth0: Device or resource busy
    ==40345== Memcheck, a memory error detector
    ==40345== Copyright (C) 2002-2013, and GNU GPL'd, by Julian Seward et al.
    ==40345== Using Valgrind-3.10.1 and LibVEX; rerun with -h for copyright info
    ==40345== Command: ip link
    ==40345== 
    failed to attach to eth0: Device or resource busy

Correct behavior under patched Vaglrind:

    $ sudo LKL_HIJACK_NET_TAP=eth0 LKL_LIBRARY_PATH=lib LKL_PRELOAD=liblkl-hijack.so taskset -c 10 /tmp/valgrind-build2/bin/valgrind ip link
    ==68392== Memcheck, a memory error detector
    ==68392== Copyright (C) 2002-2015, and GNU GPL'd, by Julian Seward et al.
    ==68392== Using Valgrind-3.12.0.SVN and LibVEX; rerun with -h for copyright info
    ==68392== Command: ip link
    ==68392== 
    1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default 
        link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN mode DEFAULT group default qlen 1000
        link/ether 86:c8:d0:f8:b6:31 brd ff:ff:ff:ff:ff:ff
    3: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN mode DEFAULT group default 
        link/sit 0.0.0.0 brd 0.0.0.0
    ==68392== 
    ==68392== HEAP SUMMARY:
    ==68392==     in use at exit: 11,616 bytes in 52 blocks
    ==68392==   total heap usage: 440 allocs, 388 frees, 67,147,414 bytes allocated
    ==68392== 
    ...


Build changes for GitHub clone
~~~~~~~~~~~~~~~~~~~~~~~~
Valgrind's svn pulls down an external repo into a directory named VEX
that's needed to build it. You can meet that requirement by running
the following in the root of this project:

    git clone https://github.com/svn2github/valgrind-vex.git VEX

before continuing with:

    ./autogen.sh
    ./configure --prefix=where/to/install
    make -j
    make install

as normal.


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
- S390X/Linux
- MIPS32/Linux
- MIPS64/Linux

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