| |
| |
| <a name="intro"></a> |
| <h2>1 Introduction</h2> |
| |
| <a name="intro-overview"></a> |
| <h3>1.1 An overview of Valgrind</h3> |
| |
| Valgrind is a flexible tool for debugging and profiling Linux-x86 |
| executables. The tool consists of a core, which provides a synthetic |
| x86 CPU in software, and a series of "skins", each of which is a |
| debugging or profiling tool. The architecture is modular, so that new |
| skins can be created easily and without disturbing the existing |
| structure. |
| |
| <p> |
| A number of useful skins are supplied as standard. In summary, these |
| are: |
| |
| <ul> |
| <li>The <b>memcheck</b> skin detects memory-management problems in |
| your programs. It provides services identical to those supplied |
| by the valgrind-1.0.X series. Memcheck is essentially |
| valgrind-1.0.X packaged up into a skin. |
| <p> |
| All reads and writes of memory are checked, and calls to |
| malloc/new/free/delete are intercepted. As a result, memcheck can |
| detect the following problems: |
| <ul> |
| <li>Use of uninitialised memory</li> |
| <li>Reading/writing memory after it has been free'd</li> |
| <li>Reading/writing off the end of malloc'd blocks</li> |
| <li>Reading/writing inappropriate areas on the stack</li> |
| <li>Memory leaks -- where pointers to malloc'd blocks are lost |
| forever</li> |
| <li>Mismatched use of malloc/new/new [] vs free/delete/delete []</li> |
| <li>Some misuses of the POSIX pthreads API</li> |
| </ul> |
| <p> |
| Problems like these can be difficult to find by other means, often |
| lying undetected for long periods, then causing occasional, |
| difficult-to-diagnose crashes. |
| <p> |
| <li><b>cachegrind</b> is a packaging of Nick Nethercote's cache |
| profiler from valgrind-1.0.X. 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. If you desire, |
| 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 x86 |
| instruction. |
| <p> |
| Cachegrind auto-detects your machine's cache configuration |
| using the <code>CPUID</code> instruction, and so needs no further |
| configuration info, in most cases. |
| <p> |
| Cachegrind is nicely complemented by Josef Weidendorfer's |
| amazing KCacheGrind visualisation tool (<A |
| HREF="http://kcachegrind.sourceforge.net"> |
| http://kcachegrind.sourceforge.net</A>), a KDE application which |
| presents these profiling results in a graphical and |
| easier-to-understand form. |
| <p> |
| <li>The new <b>addrcheck</b> skin is a lightweight version of |
| memcheck. It is identical to memcheck except |
| for the single detail that it does not do any uninitialised-value |
| checks. All of the other checks -- primarily the fine-grained |
| address checking -- are still done. The downside of this is that |
| you don't catch the uninitialised-value errors that |
| memcheck can find. |
| <p> |
| But the upside is significant: programs run about twice as fast as |
| they do on memcheck, and a lot less memory is used. It |
| still finds reads/writes of freed memory, memory off the end of |
| blocks and in other invalid places, bugs which you really want to |
| find before release! |
| <p> |
| Because addrcheck is lighter and faster than |
| memcheck, you can run more programs for longer, and so you |
| may be able to cover more test scenarios. Addrcheck was |
| created because one of us (Julian) wanted to be able to |
| run a complete KDE desktop session with checking. As of early |
| November 2002, we have been able to run KDE-3.0.3 on a 1.7 GHz P4 |
| with 512 MB of memory, using addrcheck. Although the |
| result is not stellar, it's quite usable, and it seems plausible |
| to run KDE for long periods at a time like this, collecting up |
| all the addressing errors that appear. |
| <p> |
| <li><b>helgrind</b> is a new debugging skin, designed to find data |
| races in multithreaded programs. What helgrind looks for |
| is memory locations which are accessed by more than one (POSIX |
| p-)thread, but for which no consistently used (pthread_mutex_)lock |
| can be found. Such locations are indicative of missing |
| synchronisation between threads, and could cause hard-to-find |
| timing-dependent problems. |
| <p> |
| Helgrind ("Hell's Gate", in Norse mythology) implements the |
| so-called "Eraser" data-race-detection algorithm, along with |
| various refinements (thread-segment lifetimes) which reduce the |
| number of false errors it reports. It is as yet somewhat of an |
| experimental skin, so your feedback is especially welcomed here. |
| <p> |
| Helgrind has been hacked on extensively by Jeremy |
| Fitzhardinge, and we have him to thank for getting it to a |
| releasable state. |
| </ul> |
| |
| A number of minor skins (<b>corecheck</b>, <b>lackey</b> and |
| <b>none</b>) are also supplied. These aren't particularly useful -- |
| they exist to illustrate how to create simple skins and to help the |
| valgrind developers in various ways. |
| |
| |
| <p> |
| Valgrind is closely tied to details of the CPU, operating system and |
| to a less extent, compiler and basic C libraries. This makes it |
| difficult to make it portable, so we have chosen at the outset to |
| concentrate on what we believe to be a widely used platform: Linux on |
| x86s. Valgrind uses the standard Unix <code>./configure</code>, |
| <code>make</code>, <code>make install</code> mechanism, and we have |
| attempted to ensure that it works on machines with kernel 2.2 or 2.4 |
| and glibc 2.1.X, 2.2.X or 2.3.X. This should cover the vast majority |
| of modern Linux installations. |
| |
| |
| <p> |
| Valgrind is licensed under the GNU General Public License, version |
| 2. Read the file LICENSE in the source distribution for details. Some |
| of the PThreads test cases, <code>pth_*.c</code>, are taken from |
| "Pthreads Programming" by Bradford Nichols, Dick Buttlar & |
| Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by O'Reilly |
| & Associates, Inc. |
| |
| |
| |
| |
| <a name="intro-navigation"></a> |
| <h3>1.2 How to navigate this manual</h3> |
| |
| Valgrind is structured as a set of core services supporting a number |
| of profiling and debugging tools ("skins"). This manual is structured |
| similarly. Below, we continue with a description of the valgrind |
| core, how to use it, and the flags it supports. |
| |
| <p> |
| The skins each have their own chapters in this manual. You only need |
| to read the documentation for the core services and for the skin(s) |
| you actually use, although you may find it helpful to be at least a |
| little bit familar with what all skins do. |
| |
| <p> |
| If you're new to all this, you're most likely to be using the Memcheck |
| skin, since that's the one selected by default. So, read the rest of |
| this page, and the section Memcheck. |
| |
| <p> |
| Be aware that the core understands some command line flags, and the |
| skins have their own flags which they know about. This means |
| there is no central place describing all the flags that are accepted |
| -- you have to read the flags documentation both for |
| <A HREF="coregrind_core.html#core">valgrind's core</A> |
| and for the skin you want to use. |
| |
| <p> |
| <a name="intro-migrating"></a> |
| <h4>1.2.1 For users migrating from valgrind-1.0.X</h4> |
| <p> |
| Valgrind-2.0.X is a major redesign of the 1.0.X series. You should at |
| least be familiar with the concept of the new core/skin division, |
| as explained above in the Introduction. Having said that, we've tried |
| to make the command line handling and behaviour as |
| backwards-compatible as we can. In particular, just running |
| <code>valgrind [args-for-valgrind] my_prog [args-for-my-prog]</code> |
| should work pretty much as before. |
| |
| <p> |
| |