| Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame^] | 1 | <html> |
| 2 | <head> |
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| 4 | <title>6. README_DEVELOPERS</title> |
| 5 | <link rel="stylesheet" type="text/css" href="vg_basic.css"> |
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> |
| 7 | <link rel="home" href="index.html" title="Valgrind Documentation"> |
| 8 | <link rel="up" href="dist.html" title="Valgrind Distribution Documents"> |
| 9 | <link rel="prev" href="dist.readme-missing.html" title="5. README_MISSING_SYSCALL_OR_IOCTL"> |
| 10 | <link rel="next" href="dist.readme-packagers.html" title="7. README_PACKAGERS"> |
| 11 | </head> |
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| 13 | <div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr> |
| 14 | <td width="22px" align="center" valign="middle"><a accesskey="p" href="dist.readme-missing.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td> |
| 15 | <td width="25px" align="center" valign="middle"><a accesskey="u" href="dist.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td> |
| 16 | <td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td> |
| 17 | <th align="center" valign="middle">Valgrind Distribution Documents</th> |
| 18 | <td width="22px" align="center" valign="middle"><a accesskey="n" href="dist.readme-packagers.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td> |
| 19 | </tr></table></div> |
| 20 | <div class="chapter"> |
| 21 | <div class="titlepage"><div><div><h1 class="title"> |
| 22 | <a name="dist.readme-developers"></a>6. README_DEVELOPERS</h1></div></div></div> |
| 23 | <div class="literallayout"><p><br> |
| 24 | <br> |
| 25 | Building and not installing it<br> |
| 26 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> |
| 27 | To run Valgrind without having to install it, run coregrind/valgrind<br> |
| 28 | with the VALGRIND_LIB environment variable set, where <dir> is the root<br> |
| 29 | of the source tree (and must be an absolute path). Eg:<br> |
| 30 | <br> |
| 31 | VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind <br> |
| 32 | <br> |
| 33 | This allows you to compile and run with "make" instead of "make install",<br> |
| 34 | saving you time.<br> |
| 35 | <br> |
| 36 | Or, you can use the 'vg-in-place' script which does that for you.<br> |
| 37 | <br> |
| 38 | I recommend compiling with "make --quiet" to further reduce the amount of<br> |
| 39 | output spewed out during compilation, letting you actually see any errors,<br> |
| 40 | warnings, etc.<br> |
| 41 | <br> |
| 42 | <br> |
| 43 | Building a distribution tarball<br> |
| 44 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> |
| 45 | To build a distribution tarball from the valgrind sources:<br> |
| 46 | <br> |
| 47 | make dist<br> |
| 48 | <br> |
| 49 | In addition to compiling, linking and packaging everything up, the command<br> |
| 50 | will also attempt to build the documentation.<br> |
| 51 | <br> |
| 52 | If you only want to test whether the generated tarball is complete and runs<br> |
| 53 | regression tests successfully, building documentation is not needed.<br> |
| 54 | <br> |
| 55 | make dist BUILD_ALL_DOCS=no<br> |
| 56 | <br> |
| 57 | If you insist on building documentation some embarrassing instructions<br> |
| 58 | can be found in docs/README.<br> |
| 59 | <br> |
| 60 | <br> |
| 61 | Running the regression tests<br> |
| 62 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> |
| 63 | To build and run all the regression tests, run "make [--quiet] regtest".<br> |
| 64 | <br> |
| 65 | To run a subset of the regression tests, execute:<br> |
| 66 | <br> |
| 67 | perl tests/vg_regtest <name><br> |
| 68 | <br> |
| 69 | where <name> is a directory (all tests within will be run) or a single<br> |
| 70 | .vgtest test file, or the name of a program which has a like-named .vgtest<br> |
| 71 | file. Eg:<br> |
| 72 | <br> |
| 73 | perl tests/vg_regtest memcheck<br> |
| 74 | perl tests/vg_regtest memcheck/tests/badfree.vgtest<br> |
| 75 | perl tests/vg_regtest memcheck/tests/badfree<br> |
| 76 | <br> |
| 77 | <br> |
| 78 | Running the performance tests<br> |
| 79 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> |
| 80 | To build and run all the performance tests, run "make [--quiet] perf".<br> |
| 81 | <br> |
| 82 | To run a subset of the performance suite, execute:<br> |
| 83 | <br> |
| 84 | perl perf/vg_perf <name><br> |
| 85 | <br> |
| 86 | where <name> is a directory (all tests within will be run) or a single<br> |
| 87 | .vgperf test file, or the name of a program which has a like-named .vgperf<br> |
| 88 | file. Eg:<br> |
| 89 | <br> |
| 90 | perl perf/vg_perf perf/<br> |
| 91 | perl perf/vg_perf perf/bz2.vgperf<br> |
| 92 | perl perf/vg_perf perf/bz2<br> |
| 93 | <br> |
| 94 | To compare multiple versions of Valgrind, use the --vg= option multiple<br> |
| 95 | times. For example, if you have two Valgrinds next to each other, one in<br> |
| 96 | trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to<br> |
| 97 | compare them on all the performance tests:<br> |
| 98 | <br> |
| 99 | perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/<br> |
| 100 | <br> |
| 101 | <br> |
| 102 | Debugging Valgrind with GDB<br> |
| 103 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> |
| 104 | To debug the valgrind launcher program (<prefix>/bin/valgrind) just<br> |
| 105 | run it under gdb in the normal way.<br> |
| 106 | <br> |
| 107 | Debugging the main body of the valgrind code (and/or the code for<br> |
| 108 | a particular tool) requires a bit more trickery but can be achieved<br> |
| 109 | without too much problem by following these steps:<br> |
| 110 | <br> |
| 111 | (1) Set VALGRIND_LAUNCHER to point to the valgrind executable. Eg:<br> |
| 112 | <br> |
| 113 | export VALGRIND_LAUNCHER=/usr/local/bin/valgrind<br> |
| 114 | <br> |
| 115 | or for an uninstalled version in a source directory $DIR:<br> |
| 116 | <br> |
| 117 | export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind<br> |
| 118 | <br> |
| 119 | (2) Run gdb on the tool executable. Eg:<br> |
| 120 | <br> |
| 121 | gdb /usr/local/lib/valgrind/ppc32-linux/lackey<br> |
| 122 | <br> |
| 123 | or<br> |
| 124 | <br> |
| 125 | gdb $DIR/.in_place/x86-linux/memcheck<br> |
| 126 | <br> |
| 127 | (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from<br> |
| 128 | stopping on a SIGSEGV or SIGILL:<br> |
| 129 | <br> |
| 130 | (gdb) handle SIGILL SIGSEGV nostop noprint<br> |
| 131 | <br> |
| 132 | (4) Set any breakpoints you want and proceed as normal for gdb. The<br> |
| 133 | macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set<br> |
| 134 | a breakpoint VG_(do_exec), you could do like this in GDB:<br> |
| 135 | <br> |
| 136 | (gdb) b vgPlain_do_exec<br> |
| 137 | <br> |
| 138 | (5) Run the tool with required options (the --tool option is required<br> |
| 139 | for correct setup), e.g.<br> |
| 140 | <br> |
| 141 | (gdb) run --tool=lackey pwd<br> |
| 142 | <br> |
| 143 | Steps (1)--(3) can be put in a .gdbinit file, but any directory names must<br> |
| 144 | be fully expanded (ie. not an environment variable).<br> |
| 145 | <br> |
| 146 | A different and possibly easier way is as follows:<br> |
| 147 | <br> |
| 148 | (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes. This<br> |
| 149 | puts the tool executable into a wait loop soon after it gains<br> |
| 150 | control. This delays startup for a few seconds.<br> |
| 151 | <br> |
| 152 | (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where<br> |
| 153 | <pid> you read from the output printed by (1). This attaches<br> |
| 154 | GDB to the tool executable, which should be in the abovementioned<br> |
| 155 | wait loop.<br> |
| 156 | <br> |
| 157 | (3) Do "cont" to continue. After the loop finishes spinning, startup<br> |
| 158 | will continue as normal. Note that comment (3) above re passing<br> |
| 159 | signals applies here too.<br> |
| 160 | <br> |
| 161 | <br> |
| 162 | Self-hosting<br> |
| 163 | ~~~~~~~~~~~~<br> |
| 164 | This section explains :<br> |
| 165 | (A) How to configure Valgrind to run under Valgrind.<br> |
| 166 | Such a setup is called self hosting, or outer/inner setup.<br> |
| 167 | (B) How to run Valgrind regression tests in a 'self-hosting' mode,<br> |
| 168 | e.g. to verify Valgrind has no bugs such as memory leaks.<br> |
| 169 | (C) How to run Valgrind performance tests in a 'self-hosting' mode,<br> |
| 170 | to analyse and optimise the performance of Valgrind and its tools.<br> |
| 171 | <br> |
| 172 | (A) How to configure Valgrind to run under Valgrind:<br> |
| 173 | <br> |
| 174 | (1) Check out 2 trees, "Inner" and "Outer". Inner runs the app<br> |
| 175 | directly. Outer runs Inner.<br> |
| 176 | <br> |
| 177 | (2) Configure inner with --enable-inner and build/install as usual.<br> |
| 178 | <br> |
| 179 | (3) Configure Outer normally and build/install as usual.<br> |
| 180 | <br> |
| 181 | (4) Choose a very simple program (date) and try<br> |
| 182 | <br> |
| 183 | outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \<br> |
| 184 | --smc-check=all-non-file \<br> |
| 185 | --run-libc-freeres=no --tool=cachegrind -v \<br> |
| 186 | inner/.../bin/valgrind --vgdb-prefix=./inner --tool=none -v prog<br> |
| 187 | <br> |
| 188 | Note: You must use a "make install"-ed valgrind.<br> |
| 189 | Do *not* use vg-in-place for the outer valgrind.<br> |
| 190 | <br> |
| 191 | If you omit the --trace-children=yes, you'll only monitor Inner's launcher<br> |
| 192 | program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise<br> |
| 193 | it will try to find and run __libc_freeres in the inner, while libc is not<br> |
| 194 | used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner<br> |
| 195 | gdbserver colliding with outer gdbserver.<br> |
| 196 | Currently, inner does *not* use the client request <br> |
| 197 | VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for<br> |
| 198 | translation chaining. So the outer needs --smc-check=all-non-file to<br> |
| 199 | detect the modified code.<br> |
| 200 | <br> |
| 201 | Debugging the whole thing might imply to use up to 3 GDB:<br> |
| 202 | * a GDB attached to the Outer valgrind, allowing<br> |
| 203 | to examine the state of Outer.<br> |
| 204 | * a GDB using Outer gdbserver, allowing to<br> |
| 205 | examine the state of Inner.<br> |
| 206 | * a GDB using Inner gdbserver, allowing to<br> |
| 207 | examine the state of prog.<br> |
| 208 | <br> |
| 209 | The whole thing is fragile, confusing and slow, but it does work well enough<br> |
| 210 | for you to get some useful performance data. Inner has most of<br> |
| 211 | its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',<br> |
| 212 | which helps a lot. However, when running regression tests in an Outer/Inner<br> |
| 213 | setup, this prefix causes the reg test diff to fail. Give <br> |
| 214 | --sim-hints=no-inner-prefix to the Inner to disable the production<br> |
| 215 | of the prefix in the stdout/stderr output of Inner.<br> |
| 216 | <br> |
| 217 | The allocator (coregrind/m_mallocfree.c) is annotated with client requests<br> |
| 218 | so Memcheck can be used to find leaks and use after free in an Inner<br> |
| 219 | Valgrind.<br> |
| 220 | <br> |
| 221 | The Valgrind "big lock" is annotated with helgrind client requests<br> |
| 222 | so helgrind and drd can be used to find race conditions in an Inner<br> |
| 223 | Valgrind.<br> |
| 224 | <br> |
| 225 | All this has not been tested much, so don't be surprised if you hit problems.<br> |
| 226 | <br> |
| 227 | When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'<br> |
| 228 | (on the outer). Otherwise, Callgrind has much higher memory requirements. <br> |
| 229 | <br> |
| 230 | (B) Regression tests in an outer/inner setup:<br> |
| 231 | <br> |
| 232 | To run all the regression tests with an outer memcheck, do :<br> |
| 233 | perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \<br> |
| 234 | --all<br> |
| 235 | <br> |
| 236 | To run a specific regression tests with an outer memcheck, do:<br> |
| 237 | perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \<br> |
| 238 | none/tests/args.vgtest<br> |
| 239 | <br> |
| 240 | To run regression tests with another outer tool:<br> |
| 241 | perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \<br> |
| 242 | --outer-tool=helgrind --all<br> |
| 243 | <br> |
| 244 | --outer-args allows to give specific arguments to the outer tool,<br> |
| 245 | replacing the default one provided by vg_regtest.<br> |
| 246 | <br> |
| 247 | Note: --outer-valgrind must be a "make install"-ed valgrind.<br> |
| 248 | Do *not* use vg-in-place.<br> |
| 249 | <br> |
| 250 | When an outer valgrind runs an inner valgrind, a regression test<br> |
| 251 | produces one additional file <testname>.outer.log which contains the<br> |
| 252 | errors detected by the outer valgrind. E.g. for an outer memcheck, it<br> |
| 253 | contains the leaks found in the inner, for an outer helgrind or drd,<br> |
| 254 | it contains the detected race conditions.<br> |
| 255 | <br> |
| 256 | The file tests/outer_inner.supp contains suppressions for <br> |
| 257 | the irrelevant or benign errors found in the inner.<br> |
| 258 | <br> |
| 259 | (C) Performance tests in an outer/inner setup:<br> |
| 260 | <br> |
| 261 | To run all the performance tests with an outer cachegrind, do :<br> |
| 262 | perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf<br> |
| 263 | <br> |
| 264 | To run a specific perf test (e.g. bz2) in this setup, do :<br> |
| 265 | perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2<br> |
| 266 | <br> |
| 267 | To run all the performance tests with an outer callgrind, do :<br> |
| 268 | perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \<br> |
| 269 | --outer-tool=callgrind perf<br> |
| 270 | <br> |
| 271 | Note: --outer-valgrind must be a "make install"-ed valgrind.<br> |
| 272 | Do *not* use vg-in-place.<br> |
| 273 | <br> |
| 274 | To compare the performance of multiple Valgrind versions, do :<br> |
| 275 | perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \<br> |
| 276 | --outer-tool=callgrind \<br> |
| 277 | --vg=../inner_xxxx --vg=../inner_yyyy perf<br> |
| 278 | (where inner_xxxx and inner_yyyy are the toplevel directories of<br> |
| 279 | the versions to compare).<br> |
| 280 | Cachegrind and cg_diff are particularly handy to obtain a delta<br> |
| 281 | between the two versions.<br> |
| 282 | <br> |
| 283 | When the outer tool is callgrind or cachegrind, the following<br> |
| 284 | output files will be created for each test:<br> |
| 285 | <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid><br> |
| 286 | <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid><br> |
| 287 | (where tt is the two letters abbreviation for the inner tool(s) run).<br> |
| 288 | <br> |
| 289 | For example, the command<br> |
| 290 | perl perf/vg_perf \<br> |
| 291 | --outer-valgrind=../outer_trunk/install/bin/valgrind \<br> |
| 292 | --outer-tool=callgrind \<br> |
| 293 | --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records<br> |
| 294 | <br> |
| 295 | produces the files<br> |
| 296 | callgrind.out.inner_tchain.no.many-loss-records.18465<br> |
| 297 | callgrind.outer.log.inner_tchain.no.many-loss-records.18465<br> |
| 298 | callgrind.out.inner_tchain.me.many-loss-records.21899<br> |
| 299 | callgrind.outer.log.inner_tchain.me.many-loss-records.21899<br> |
| 300 | callgrind.out.inner_trunk.no.many-loss-records.21224<br> |
| 301 | callgrind.outer.log.inner_trunk.no.many-loss-records.21224<br> |
| 302 | callgrind.out.inner_trunk.me.many-loss-records.22916<br> |
| 303 | callgrind.outer.log.inner_trunk.me.many-loss-records.22916<br> |
| 304 | <br> |
| 305 | <br> |
| 306 | Printing out problematic blocks<br> |
| 307 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> |
| 308 | If you want to print out a disassembly of a particular block that<br> |
| 309 | causes a crash, do the following.<br> |
| 310 | <br> |
| 311 | Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000<br> |
| 312 | --trace-notbelow=999999". This should print one line for each block<br> |
| 313 | translated, and that includes the address.<br> |
| 314 | <br> |
| 315 | Then re-run with 999999 changed to the highest bb number shown.<br> |
| 316 | This will print the one line per block, and also will print a<br> |
| 317 | disassembly of the block in which the fault occurred.<br> |
| 318 | <br> |
| 319 | </p></div> |
| 320 | </div> |
| 321 | <div> |
| 322 | <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> |
| 323 | <tr> |
| 324 | <td rowspan="2" width="40%" align="left"> |
| 325 | <a accesskey="p" href="dist.readme-missing.html"><< 5. README_MISSING_SYSCALL_OR_IOCTL</a> </td> |
| 326 | <td width="20%" align="center"><a accesskey="u" href="dist.html">Up</a></td> |
| 327 | <td rowspan="2" width="40%" align="right"> <a accesskey="n" href="dist.readme-packagers.html">7. README_PACKAGERS >></a> |
| 328 | </td> |
| 329 | </tr> |
| 330 | <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> |
| 331 | </table> |
| 332 | </div> |
| 333 | </body> |
| 334 | </html> |