valgrind_manual
Table of Contents
1. Introduction .....................................................................................1
1.1. An Overview of Valgrind ....................................................................... 1
1.2. How to navigate this manual .................................................................... 1
2. Using and understanding the Valgrind core ......................................................... 3
2.1. What Valgrind does with your program ...........................................................3
2.2. Getting started .................................................................................4
2.3. The Commentary .............................................................................. 4
2.4. Reporting of errors .............................................................................6
2.5. Suppressing errors ............................................................................. 7
2.6. Core Command-line Options ....................................................................9
2.6.1. Tool-selection Option ........................................................................10
2.6.2. Basic Options ...............................................................................10
2.6.3. Error-related Options ........................................................................13
2.6.4. malloc-related Options .......................................................................21
2.6.5. Uncommon Options .........................................................................22
2.6.6. Debugging Options ..........................................................................31
2.6.7. Setting Default Options ......................................................................31
2.7. Support for Threads ...........................................................................32
2.7.1. Scheduling and Multi-Thread Performance .....................................................32
2.8. Handling of Signals ...........................................................................33
2.9. Execution Trees .............................................................................. 33
2.10. Building and Installing Valgrind ...............................................................38
2.11. If You Have Problems ........................................................................39
2.12. Limitations ................................................................................. 39
2.13. An Example Run ............................................................................ 42
2.14. Warning Messages You Might See .............................................................43
3. Using and understanding the Valgrind core: Advanced Topics ....................................... 44
3.1. The Client Request mechanism .................................................................44
3.2. Debugging your program using Valgrind gdbserver and GDB ......................................47
3.2.1. Quick Start: debugging in 3 steps .............................................................47
3.2.2. Valgrind gdbserver overall organisation ........................................................47
3.2.3. Connecting GDB to a Valgrind gdbserver ......................................................48
3.2.4. Connecting to an Android gdbserver .......................................................... 50
3.2.5. Monitor command handling by the Valgrind gdbserver .......................................... 50
3.2.6. Valgrind gdbserver thread information .........................................................52
3.2.7. Examining and modifying Valgrind shadow registers ............................................52
3.2.8. Limitations of the Valgrind gdbserver ......................................................... 53
3.2.9. vgdb command line options .................................................................. 57
3.2.10. Valgrind monitor commands ................................................................ 59
3.3. Function wrapping ............................................................................62
3.3.1. A Simple Example .......................................................................... 62
3.3.2. Wrapping Specifications .....................................................................63
3.3.3. Wrapping Semantics ........................................................................ 64
3.3.4. Debugging ................................................................................. 65
3.3.5. Limitations - control flow .................................................................... 65
3.3.6. Limitations - original function signatures ...................................................... 66
3.3.7. Examples .................................................................................. 66
4. Memcheck: a memory error detector ............................................................. 67
4.1. Overview .................................................................................... 67
4.2. Explanation of error messages from Memcheck .................................................. 67
4.2.1. Illegal read / Illegal write errors ...............................................................67
4.2.2. Use of uninitialised values ................................................................... 68
v
Valgrind User Manual
4.2.3. Use of uninitialised or unaddressable values in system calls ......................................69
4.2.4. Illegal frees .................................................................................69
4.2.5. When a heap block is freed with an inappropriate deallocation function ........................... 70
4.2.6. Overlapping source and destination blocks .....................................................71
4.2.7. Fishy argument values .......................................................................71
4.2.8. Memory leak detection ...................................................................... 72
4.3. Memcheck Command-Line Options ............................................................ 76
4.4. Writing suppression files ...................................................................... 81
4.5. Details of Memcheck’s checking machinery ..................................................... 82
4.5.1. Valid-value (V) bits ......................................................................... 82
4.5.2. Valid-address (A) bits ....................................................................... 84
4.5.3. Putting it all together ........................................................................ 84
4.6. Memcheck Monitor Commands ................................................................ 85
4.7. Client Requests ...............................................................................91
4.8. Memory Pools: describing and working with custom allocators .................................... 92
4.9. Debugging MPI Parallel Programs with Valgrind .................................................95
4.9.1. Building and installing the wrappers .......................................................... 95
4.9.2. Getting started ..............................................................................96
4.9.3. Controlling the wrapper library ...............................................................96
4.9.4. Functions .................................................................................. 97
4.9.5. Types ......................................................................................98
4.9.6. Writing new wrappers ....................................................................... 98
4.9.7. What to expect when using the wrappers .......................................................98
5. Cachegrind: a cache and branch-prediction profiler ................................................100
5.1. Overview ...................................................................................100
5.2. Using Cachegrind, cg_annotate and cg_merge .................................................. 100
5.2.1. Running Cachegrind ....................................................................... 101
5.2.2. Output File ................................................................................101
5.2.3. Running cg_annotate .......................................................................102
5.2.4. The Output Preamble .......................................................................102
5.2.5. The Global and Function-level Counts ........................................................103
5.2.6. Line-by-line Counts ........................................................................104
5.2.7. Annotating Assembly Code Programs ........................................................106
5.2.8. Forking Programs ..........................................................................174
5.2.9. cg_annotate Warnings ...................................................................... 106
5.2.10. Unusual Annotation Cases .................................................................107
5.2.11. Merging Profiles with cg_merge ............................................................108
5.2.12. Differencing Profiles with cg_diff ...........................................................108
5.3. Cachegrind Command-line Options ............................................................109
5.4. cg_annotate Command-line Options ........................................................... 110
5.5. cg_merge Command-line Options ............................................................. 111
5.6. cg_diff Command-line Options ................................................................111
5.7. Acting on Cachegrind’s Information ........................................................... 112
5.8. Simulation Details ...........................................................................113
5.8.1. Cache Simulation Specifics ................................................................. 113
5.8.2. Branch Simulation Specifics ................................................................ 114
5.8.3. Accuracy ..................................................................................114
5.9. Implementation Details .......................................................................115
5.9.1. How Cachegrind Works .................................................................... 115
5.9.2. Cachegrind Output File Format ..............................................................115
6. Callgrind: a call-graph generating cache and branch prediction profiler ..............................117
6.1. Overview ...................................................................................117
6.1.1. Functionality .............................................................................. 117
6.1.2. Basic Usage ...............................................................................118
vi
Valgrind User Manual
6.2. Advanced Usage .............................................................................119
6.2.1. Multiple profiling dumps from one program run ...............................................119
6.2.2. Limiting the range of collected events ........................................................120
6.2.3. Counting global bus events ..................................................................121
6.2.4. Avoiding cycles ............................................................................121
6.2.5. Forking Programs ..........................................................................122
6.3. Callgrind Command-line Options ..............................................................122
6.3.1. Dump creation options ..................................................................... 123
6.3.2. Activity options ............................................................................123
6.3.3. Data collection options ..................................................................... 124
6.3.4. Cost entity separation options ............................................................... 125
6.3.5. Simulation options .........................................................................126
6.3.6. Cache simulation options ................................................................... 126
6.4. Callgrind Monitor Commands .................................................................127
6.5. Callgrind specific client requests .............................................................. 127
6.6. callgrind_annotate Command-line Options ..................................................... 128
6.7. callgrind_control Command-line Options .......................................................129
7. Helgrind: a thread error detector ................................................................ 131
7.1. Overview ...................................................................................131
7.2. Detected errors: Misuses of the POSIX pthreads API ............................................ 131
7.3. Detected errors: Inconsistent Lock Orderings ...................................................132
7.4. Detected errors: Data Races .................................................................. 134
7.4.1. A Simple Data Race ........................................................................134
7.4.2. Helgrind’s Race Detection Algorithm ........................................................ 136
7.4.3. Interpreting Race Error Messages ............................................................139
7.5. Hints and Tips for Effective Use of Helgrind ....................................................140
7.6. Helgrind Command-line Options ..............................................................144
7.7. Helgrind Monitor Commands .................................................................146
7.8. Helgrind Client Requests .....................................................................148
7.9. A To-Do List for Helgrind ....................................................................148
8. DRD: a thread error detector ....................................................................149
8.1. Overview ...................................................................................149
8.1.1. Multithreaded Programming Paradigms ...................................................... 149
8.1.2. POSIX Threads Programming Model ........................................................ 149
8.1.3. Multithreaded Programming Problems ....................................................... 150
8.1.4. Data Race Detection ....................................................................... 150
8.2. Using DRD ................................................................................. 151
8.2.1. DRD Command-line Options ................................................................151
8.2.2. Detected Errors: Data Races ................................................................ 154
8.2.3. Detected Errors: Lock Contention ........................................................... 155
8.2.4. Detected Errors: Misuse of the POSIX threads API ............................................156
8.2.5. Client Requests ............................................................................157
8.2.6. Debugging C 11 Programs ................................................................ 159
8.2.7. Debugging GNOME Programs .............................................................. 160
8.2.8. Debugging Boost.Thread Programs .......................................................... 160
8.2.9. Debugging OpenMP Programs .............................................................. 160
8.2.10. DRD and Custom Memory Allocators .......................................................161
8.2.11. DRD Versus Memcheck ................................................................... 162
8.2.12. Resource Requirements ....................................................................162
8.2.13. Hints and Tips for Effective Use of DRD .................................................... 162
8.3. Using the POSIX Threads API Effectively ......................................................163
8.3.1. Mutex types ...............................................................................163
8.3.2. Condition variables ........................................................................ 163
8.3.3. pthread_cond_timedwait and timeouts ........................................................163
vii
Valgrind User Manual
8.4. Limitations ................................................................................. 164
8.5. Feedback ................................................................................... 164
9. Massif: a heap profiler .........................................................................165
9.1. Overview ...................................................................................191
9.2. Using Massif and ms_print ................................................................... 165
9.2.1. An Example Program ...................................................................... 165
9.2.2. Running Massif ............................................................................166
9.2.3. Running ms_print ..........................................................................166
9.2.4. The Output Preamble .......................................................................167
9.2.5. The Output Graph ..........................................................................167
9.2.6. The Snapshot Details .......................................................................170
9.2.7. Forking Programs ..........................................................................174
9.2.8. Measuring All Memory in a Process ......................................................... 174
9.2.9. Acting on Massif’s Information ..............................................................174
9.3. Using massif-visualizer ...................................................................... 175
9.4. Massif Command-line Options ................................................................175
9.5. Massif Monitor Commands ...................................................................177
9.6. Massif Client Requests .......................................................................177
9.7. ms_print Command-line Options ..............................................................177
9.8. Massif’s Output File Format .................................................................. 178
10. DHAT: a dynamic heap analysis tool ........................................................... 179
10.1. Overview ..................................................................................179
10.2. Using DHAT ...............................................................................179
10.2.1. Running DHAT ...........................................................................179
10.2.2. Output File ...............................................................................180
10.3. DHAT’s Viewer ............................................................................ 180
10.3.1. The Output Header ........................................................................180
10.3.2. The AP Tree ............................................................................. 181
10.3.3. The Output Footer ........................................................................ 186
10.3.4. Sort Metrics ..............................................................................187
10.4. DHAT Command-line Options ...............................................................189
11. Lackey: an example tool ...................................................................... 190
11.1. Overview ..................................................................................190
11.2. Lackey Command-line Options .............................................................. 190
12. Nulgrind: the minimal Valgrind tool ............................................................191
12.1. Overview ..................................................................................191
13. SGCheck: an experimental stack and global array overrun detector ................................ 192
13.1. Overview ..................................................................................192
13.2. SGCheck Command-line Options ............................................................ 192
13.3. How SGCheck Works .......................................................................192
13.4. Comparison with Memcheck .................................................................193
13.5. Limitations ................................................................................ 193
13.6. Still To Do: User-visible Functionality ........................................................194
13.7. Still To Do: Implementation Tidying ..........................................................194
14. BBV: an experimental basic block vector generation tool ......................................... 195
14.1. Overview ..................................................................................195
14.2. Using Basic Block Vectors to create SimPoints ................................................ 195
14.3. BBV Command-line Options ................................................................ 196
14.4. Basic Block Vector File Format .............................................................. 196
14.5. Implementation ............................................................................ 197
14.6. Threaded Executable Support ................................................................197
14.7. Validation ................................................................................. 197
14.8. Performance ............................................................................... 198
vii
评论