Details of Memcheck's checking machinery

Read this section if you want to know, in detail, exactly what and how Memcheck is
checking.

3.5.1 Valid-value (V) bits

It is simplest to think of Memcheck implementing a synthetic Intel x86 CPU which is

identical to a real CPU, except for one crucial detail. Every bit (literally) of data
processed, stored and handled by the real CPU has, in the synthetic CPU, an
associated "valid-value" bit, which says whether or not the accompanying bit has a
legitimate value. In the discussions which follow, this bit is referred to as the V (valid-
value) bit.

Each byte in the system therefore has a 8 V bits which follow it wherever it goes. For
example, when the CPU loads a word-size item (4 bytes) from memory, it also loads
the corresponding 32 V bits from a bitmap which stores the V bits for the process'
entire address space. If the CPU should later write the whole or some part of that
value to memory at a different address, the relevant V bits will be stored back in the
V-bit bitmap.

In short, each bit in the system has an associated V bit, which follows it around
everywhere, even inside the CPU. Yes, the CPU's (integer and %eflags) registers have
their own V bit vectors.

Copying values around does not cause Memcheck to check for, or report on, errors.
However, when a value is used in a way which might conceivably affect the outcome
of your program's computation, the associated V bits are immediately checked. If any
of these indicate that the value is undefined, an error is reported.

Here's an (admittedly nonsensical) example:

int i, j;
int a[10], b[10];
for (i = 0; i < 10; i++) {
j = a[i];
b[i] = j;
}
Memcheck emits no complaints about this, since it merely copies uninitialised values
from a[] into b[], and doesn't use them in any way. However, if the loop is changed to
for (i = 0; i < 10; i++) {
j += a[i];
}
if (j == 77)
printf("hello there\n");
then Valgrind will complain, at the if, that the condition depends on uninitialised
values. Note that it doesn't complain at the j += a[i];, since at that point the
undefinedness is not "observable". It's only when a decision has to be made as to
whether or not to do the printf -- an observable action of your program -- that
Memcheck complains.

Most low level operations, such as adds, cause Memcheck to use the V bits for the
operands to calculate the V bits for the result. Even if the result is partially or wholly
undefined, it does not complain.

Checks on definedness only occur in two places: when a value is used to generate a
memory address, and where control flow decision needs to be made. Also, when a
system call is detected, valgrind checks definedness of parameters as required.

If a check should detect undefinedness, an error message is issued. The resulting value
is subsequently regarded as well-defined. To do otherwise would give long chains of
error messages. In effect, we say that undefined values are non-infectious.

This sounds overcomplicated. Why not just check all reads from memory, and
complain if an undefined value is loaded into a CPU register? Well, that doesn't work
well, because perfectly legitimate C programs routinely copy uninitialised values
around in memory, and we don't want endless complaints about that. Here's the
canonical example. Consider a struct like this:
struct S { int x; char c; };
struct S s1, s2;
s1.x = 42;
s1.c = 'z';
s2 = s1;

The question to ask is: how large is struct S, in bytes? An int is 4 bytes and a char one
byte, so perhaps a struct S occupies 5 bytes? Wrong. All (non-toy) compilers we know
of will round the size of struct S up to a whole number of words, in this case 8 bytes.
Not doing this forces compilers to generate truly appalling code for subscripting
arrays of struct S's.
So s1 occupies 8 bytes, yet only 5 of them will be initialised. For the assignment s2 =
s1, gcc generates code to copy all 8 bytes wholesale into s2 without regard for their
meaning. If Memcheck simply checked values as they came out of memory, it would
yelp every time a structure assignment like this happened. So the more complicated
semantics described above is necessary. This allows gcc to copy s1 into s2 any way it
likes, and a warning will only be emitted if the uninitialised values are later used.

One final twist to this story. The above scheme allows garbage to pass through the
CPU's integer registers without complaint. It does this by giving the integer registers
V tags, passing these around in the expected way. This complicated and
computationally expensive to do, but is necessary. Memcheck is more simplistic about
floating-point loads and stores. In particular, V bits for data read as a result of
floating-point loads are checked at the load instruction. So if your program uses the
floating-point registers to do memory-to-memory copies, you will get complaints
about uninitialised values. Fortunately, I have not yet encountered a program which
(ab)uses the floating-point registers in this way.

3.5.2 Valid-address (A) bits

Notice that the previous subsection describes how the validity of values is established
and maintained without having to say whether the program does or does not have the
right to access any particular memory location. We now consider the latter issue.

As described above, every bit in memory or in the CPU has an associated valid-value
(V) bit. In addition, all bytes in memory, but not in the CPU, have an associated valid-
address (A) bit. This indicates whether or not the program can legitimately read or
write that location. It does not give any indication of the validity or the data at that
location -- that's the job of the V bits -- only whether or not the location may be
accessed.

Every time your program reads or writes memory, Memcheck checks the A bits
associated with the address. If any of them indicate an invalid address, an error is
emitted. Note that the reads and writes themselves do not change the A bits, only
consult them.

So how do the A bits get set/cleared? Like this:

When the program starts, all the global data areas are marked as accessible.
 When the program does malloc/new, the A bits for the exactly the area
allocated, and not a byte more, are marked as accessible. Upon freeing the area
the A bits are changed to indicate inaccessibility.

When the stack pointer register (%esp) moves up or down, A bits are set. The
rule is that the area from %esp up to the base of the stack is marked as
accessible, and below %esp is inaccessible. (If that sounds illogical, bear in
mind that the stack grows down, not up, on almost all Unix systems, including
GNU/Linux.) Tracking %esp like this has the useful side-effect that the section
of stack used by a function for local variables etc is automatically marked
accessible on function entry and inaccessible on exit.

When doing system calls, A bits are changed appropriately. For example,
mmap() magically makes files appear in the process's address space, so the A
bits must be updated if mmap() succeeds.

Optionally, your program can tell Valgrind about such changes explicitly, using
the client request mechanism described above.

3.5.3 Putting it all together

Memcheck's checking machinery can be summarised as follows:

Each byte in memory has 8 associated V (valid-value) bits, saying whether or

not the byte has a defined value, and a single A (valid-address) bit, saying
whether or not the program currently has the right to read/write that address.

When memory is read or written, the relevant A bits are consulted. If they
indicate an invalid address, Valgrind emits an Invalid read or Invalid write
error.

When memory is read into the CPU's integer registers, the relevant V bits are
fetched from memory and stored in the simulated CPU. They are not consulted.
 When an integer register is written out to memory, the V bits for that register
are written back to memory too.

When memory is read into the CPU's floating point registers, the relevant V
bits are read from memory and they are immediately checked. If any are
invalid, an uninitialised value error is emitted. This precludes using the
floating-point registers to copy possibly-uninitialised memory, but simplifies
Valgrind in that it does not have to track the validity status of the floating-point
registers.

As a result, when a floating-point register is written to memory, the associated

V bits are set to indicate a valid value.

When values in integer CPU registers are used to generate a memory address,
or to determine the outcome of a conditional branch, the V bits for those values
are checked, and an error emitted if any of them are undefined.

When values in integer CPU registers are used for any other purpose, Valgrind
computes the V bits for the result, but does not check them.

One the V bits for a value in the CPU have been checked, they are then set to
indicate validity. This avoids long chains of errors.

When values are loaded from memory, valgrind checks the A bits for that
location and issues an illegal-address warning if needed. In that case, the V bits
loaded are forced to indicate Valid, despite the location being invalid.

This apparently strange choice reduces the amount of confusing information

presented to the user. It avoids the unpleasant phenomenon in which memory is
 read from a place which is both unaddressible and contains invalid values, and,
as a result, you get not only an invalid-address (read/write) error, but also a
potentially large set of uninitialised-value errors, one for every time the value is
used.

There is a hazy boundary case to do with multi-byte loads from addresses

which are partially valid and partially invalid. See details of the flag --partial-loads-
ok for details.

Memcheck intercepts calls to malloc, calloc, realloc, valloc, memalign, free, new and
delete. The behaviour you get is:

malloc/new: the returned memory is marked as addressible but not having valid
values. This means you have to write on it before you can read it.

calloc: returned memory is marked both addressible and valid, since calloc()
clears the area to zero.

realloc: if the new size is larger than the old, the new section is addressible but
invalid, as with malloc.

If the new size is smaller, the dropped-off section is marked as unaddressible.

You may only pass to realloc a pointer previously issued to you by
malloc/calloc/realloc.

free/delete: you may only pass to free a pointer previously issued to you by
malloc/calloc/realloc, or the value NULL. Otherwise, Valgrind complains. If
the pointer is indeed valid, Valgrind marks the entire area it points at as
unaddressible, and places the block in the freed-blocks-queue. The aim is to
defer as long as possible reallocation of this block. Until that happens, all
attempts to access it will elicit an invalid-address error, as you would hope.
3.6 Memory leak detection

Memcheck keeps track of all memory blocks issued in response to calls to

malloc/calloc/realloc/new. So when the program exits, it knows which blocks are still
outstanding -- have not been returned, in other words. Ideally, you want your program
to have no blocks still in use at exit. But many programs do.

For each such block, Memcheck scans the entire address space of the process, looking
for pointers to the block. One of three situations may result:

A pointer to the start of the block is found. This usually indicates programming
sloppiness; since the block is still pointed at, the programmer could, at least in
principle, free'd it before program exit.

A pointer to the interior of the block is found. The pointer might originally
have pointed to the start and have been moved along, or it might be entirely
unrelated. Memcheck deems such a block as "dubious", that is, possibly leaked,
because it's unclear whether or not a pointer to it still exists.

The worst outcome is that no pointer to the block can be found. The block is
classified as "leaked", because the programmer could not possibly have free'd it
at program exit, since no pointer to it exists. This might be a symptom of
having lost the pointer at some earlier point in the program.

Memcheck reports summaries about leaked and dubious blocks. For each such block,
it will also tell you where the block was allocated. This should help you figure out
why the pointer to it has been lost. In general, you should attempt to ensure your
programs do not have any leaked or dubious blocks at exit.

The precise area of memory in which Memcheck searches for pointers is: all
naturally-aligned 4-byte words for which all A bits indicate addressibility and all V
bits indicated that the stored value is actually valid.

3.7 Client Requests

The following client requests are defined in memcheck.h. They also work for Addrcheck.
See memcheck.h for exact details of their arguments.
 VALGRIND_MAKE_NOACCESS, VALGRIND_MAKE_WRITABLE and VALGRIND_MAKE_REA
DABLE. These mark address ranges as completely inaccessible, accessible but
containing undefined data, and accessible and containing defined data,
respectively. Subsequent errors may have their faulting addresses described in
terms of these blocks. Returns a "block handle". Returns zero when not run on
Valgrind.
VALGRIND_DISCARD: At some point you may want Valgrind to stop reporting
errors in terms of the blocks defined by the previous three macros. To do this,
the above macros return a small-integer "block handle". You can pass this
block handle to VALGRIND_DISCARD. After doing so, Valgrind will no longer be
able to relate addressing errors to the user-defined block associated with the
handle. The permissions settings associated with the handle remain in place;
this just affects how errors are reported, not whether they are reported. Returns
1 for an invalid handle and 0 for a valid handle (although passing invalid
handles is harmless). Always returns 0 when not run on Valgrind.
VALGRIND_CHECK_WRITABLE and VALGRIND_CHECK_READABLE: check
immediately whether or not the given address range has the relevant property,
and if not, print an error message. Also, for the convenience of the client,
returns zero if the relevant property holds; otherwise, the returned value is the
address of the first byte for which the property is not true. Always returns 0
when not run on Valgrind.
VALGRIND_CHECK_DEFINED: a quick and easy way to find out whether Valgrind
thinks a particular variable (lvalue, to be precise) is addressible and defined.
Prints an error message if not. Returns no value.
VALGRIND_DO_LEAK_CHECK: run the memory leak detector right now. Returns no
value. I guess this could be used to incrementally check for leaks between
arbitrary places in the program's execution. Warning: not properly tested!
VALGRIND_COUNT_LEAKS: fills in the four arguments with the number of bytes of
memory found by the previous leak check to be leaked, dubious, reachable and
suppressed. Again, useful in test harness code, after
calling VALGRIND_DO_LEAK_CHECK.
VALGRIND_GET_VBITS and VALGRIND_SET_VBITS: allow you to get and set the V
(validity) bits for an address range. You should probably only set V bits that
you have got with VALGRIND_GET_VBITS. Only for those who really know what
they are doing.