- publishing free software manuals
Valgrind 3.3 - Advanced Debugging and Profiling for GNU/Linux applications
by J. Seward, N. Nethercote, J. Weidendorfer and the Valgrind Development Team
Paperback (6"x9"), 164 pages
ISBN 0954612051
RRP £12.95 ($19.95)

Get a printed copy>>>

1 Introduction

Valgrind is a suite of simulation-based debugging and profiling tools for programs running on Linux (x86, amd64, ppc32 and ppc64). The system consists of a core, which provides a synthetic CPU in software, and a set of tools, each of which performs some kind of debugging, profiling, or similar task. The architecture is modular, so that new tools can be created easily and without disturbing the existing structure.

A number of useful tools are supplied as standard. In summary, these are:

  1. Memcheck detects memory-management problems in programs. All reads and writes of memory are checked, and calls to malloc, new, free and delete are intercepted. As a result, Memcheck can detect the following problems:
    • Use of uninitialised memory
    • Reading/writing memory after it has been free'd
    • Reading/writing off the end of malloc'd blocks
    • Reading/writing inappropriate areas on the stack
    • Memory leaks--where pointers to malloc'd blocks are lost forever
    • Mismatched use of malloc/new/new [] vs free/delete/delete []
    • Overlapping ‘src’ and ‘dst’ pointers in ‘memcpy()’ and related functions
    Problems like these can be difficult to find by other means, often remaining undetected for long periods, then causing occasional, difficult-to-diagnose crashes.
  2. Cachegrind is a cache profiler. It performs detailed simulation of the I1, D1 and L2 caches in your CPU and so can accurately pinpoint the sources of cache misses in your code. It will show the number of cache misses, memory references and instructions accruing to each line of source code, with per-function, per-module and whole-program summaries. If you ask really nicely it will even show counts for each individual machine instruction. On x86 and amd64, Cachegrind auto-detects your machine's cache configuration using the ‘CPUID’ instruction, and so needs no further configuration info, in most cases.
  3. Callgrind is a profiler similar in concept to Cachegrind, but which also tracks caller-callee relationships. By doing so it is able to show how instruction, memory reference and cache miss costs flow between callers and callees. Callgrind collects a large amount of data which is best navigated using Josef Weidendorfer's amazing KCachegrind visualisation tool (http://kcachegrind.sourceforge.net). KCachegrind is a KDE application which presents these profiling results in a graphical and easy-to-understand form.
  4. Massif is a heap profiler. It measures how much heap memory programs use. In particular, it can give you information about heap blocks, heap administration overheads, and stack sizes. Heap profiling can help you reduce the amount of memory your program uses. On modern machines with virtual memory, this reduces the chances that your program will run out of memory, and may make it faster by reducing the amount of paging needed.
  5. Helgrind detects synchronisation errors in programs that use the POSIX pthreads threading primitives. It detects the following three classes of errors:
    • Misuses of the POSIX pthreads API.
    • Potential deadlocks arising from lock ordering problems.
    • Data races--accessing memory without adequate locking.
    Problems like these often result in unreproducible, timing-dependent crashes, deadlocks and other misbehaviour, and can be difficult to find by other means.

A couple of minor tools (Lackey and Nulgrind) are also supplied. These aren't particularly useful--they exist to illustrate how to create simple tools and to help the valgrind developers in various ways. Nulgrind is the null tool--it adds no instrumentation. Lackey is a simple example tool which counts instructions, memory accesses, and the number of integer and floating point operations your program does.

Valgrind is closely tied to details of the CPU and operating system, and to a lesser extent, the compiler and basic C libraries. Nonetheless, as of version 3.3.0 it supports several platforms: x86/Linux (mature), amd64/Linux (maturing), ppc32/Linux and ppc64/Linux (less mature but work well). There is also experimental support for ppc32/AIX5 and ppc64/AIX5 (AIX 5.2 and 5.3 only). Valgrind uses the standard Unix ‘./configure’, ‘make’, ‘make install’ mechanism, and we have attempted to ensure that it works on machines with Linux kernel 2.4.X or 2.6.X and glibc 2.2.X to 2.7.X.

Valgrind is licensed under the GNU General Public License, version 2. The ‘valgrind/*.h’ headers that you may wish to include in your code (e.g. ‘valgrind.h’, ‘memcheck.h’, ‘helgrind.h’) are distributed under a BSD-style license, so you may include them in your code without worrying about license conflicts. Some of the PThreads test cases, ‘pth_*.c’, are taken from Pthreads Programming by Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by O'Reilly & Associates, Inc.

If you contribute code to Valgrind, please ensure your contributions are licensed as “GPLv2, or (at your option) any later version.” This is so as to allow the possibility of easily upgrading the license to GPLv3 in future. If you want to modify code in the VEX subdirectory, please also see VEX/HACKING.README.

ISBN 0954612051Valgrind 3.3 - Advanced Debugging and Profiling for GNU/Linux applicationsSee the print edition