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.79.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> 25Building�and�not�installing�it<br> 26~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 27To�run�Valgrind�without�having�to�install�it,�run�coregrind/valgrind<br> 28with�the�VALGRIND_LIB�environment�variable�set,�where�<dir>�is�the�root<br> 29of�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> 33This�allows�you�to�compile�and�run�with�"make"�instead�of�"make�install",<br> 34saving�you�time.<br> 35<br> 36Or,�you�can�use�the�'vg-in-place'�script�which�does�that�for�you.<br> 37<br> 38I�recommend�compiling�with�"make�--quiet"�to�further�reduce�the�amount�of<br> 39output�spewed�out�during�compilation,�letting�you�actually�see�any�errors,<br> 40warnings,�etc.<br> 41<br> 42<br> 43Building�a�distribution�tarball<br> 44~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 45To�build�a�distribution�tarball�from�the�valgrind�sources:<br> 46<br> 47��make�dist<br> 48<br> 49In�addition�to�compiling,�linking�and�packaging�everything�up,�the�command<br> 50will�also�attempt�to�build�the�documentation.<br> 51<br> 52If�you�only�want�to�test�whether�the�generated�tarball�is�complete�and�runs<br> 53regression�tests�successfully,�building�documentation�is�not�needed.<br> 54<br> 55��make�dist�BUILD_ALL_DOCS=no<br> 56<br> 57If�you�insist�on�building�documentation�some�embarrassing�instructions<br> 58can�be�found�in�docs/README.<br> 59<br> 60<br> 61Running�the�regression�tests<br> 62~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 63To�build�and�run�all�the�regression�tests,�run�"make�[--quiet]�regtest".<br> 64<br> 65To�run�a�subset�of�the�regression�tests,�execute:<br> 66<br> 67��perl�tests/vg_regtest�<name><br> 68<br> 69where�<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> 71file.��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> 78Running�the�performance�tests<br> 79~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 80To�build�and�run�all�the�performance�tests,�run�"make�[--quiet]�perf".<br> 81<br> 82To�run�a�subset�of�the�performance�suite,�execute:<br> 83<br> 84��perl�perf/vg_perf�<name><br> 85<br> 86where�<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> 88file.��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> 94To�compare�multiple�versions�of�Valgrind,�use�the�--vg=�option�multiple<br> 95times.��For�example,�if�you�have�two�Valgrinds�next�to�each�other,�one�in<br> 96trunk1/�and�one�in�trunk2/,�from�within�either�trunk1/�or�trunk2/�do�this�to<br> 97compare�them�on�all�the�performance�tests:<br> 98<br> 99��perl�perf/vg_perf�--vg=../trunk1�--vg=../trunk2�perf/<br> 100<br> 101<br> 102Debugging�Valgrind�with�GDB<br> 103~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 104To�debug�the�valgrind�launcher�program�(<prefix>/bin/valgrind)�just<br> 105run�it�under�gdb�in�the�normal�way.<br> 106<br> 107Debugging�the�main�body�of�the�valgrind�code�(and/or�the�code�for<br> 108a�particular�tool)�requires�a�bit�more�trickery�but�can�be�achieved<br> 109without�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> 143Steps�(1)--(3)�can�be�put�in�a�.gdbinit�file,�but�any�directory�names�must<br> 144be�fully�expanded�(ie.�not�an�environment�variable).<br> 145<br> 146A�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> 162Self-hosting<br> 163~~~~~~~~~~~~<br> 164This�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> 188Note:�You�must�use�a�"make�install"-ed�valgrind.<br> 189Do�*not*�use�vg-in-place�for�the�outer�valgrind.<br> 190<br> 191If�you�omit�the�--trace-children=yes,�you'll�only�monitor�Inner's�launcher<br> 192program,�not�its�stage2.�Outer�needs�--run-libc-freeres=no,�as�otherwise<br> 193it�will�try�to�find�and�run�__libc_freeres�in�the�inner,�while�libc�is�not<br> 194used�by�the�inner.�Inner�needs�--vgdb-prefix=./inner�to�avoid�inner<br> 195gdbserver�colliding�with�outer�gdbserver.<br> 196Currently,�inner�does�*not*�use�the�client�request�<br> 197VALGRIND_DISCARD_TRANSLATIONS�for�the�JITted�code�or�the�code�patched�for<br> 198translation�chaining.�So�the�outer�needs�--smc-check=all-non-file�to<br> 199detect�the�modified�code.<br> 200<br> 201Debugging�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> 209The�whole�thing�is�fragile,�confusing�and�slow,�but�it�does�work�well�enough<br> 210for�you�to�get�some�useful�performance�data.��Inner�has�most�of<br> 211its�output�(ie.�those�lines�beginning�with�"==<pid>==")�prefixed�with�a�'>',<br> 212which�helps�a�lot.�However,�when�running�regression�tests�in�an�Outer/Inner<br> 213setup,�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> 215of�the�prefix�in�the�stdout/stderr�output�of�Inner.<br> 216<br> 217The�allocator�(coregrind/m_mallocfree.c)�is�annotated�with�client�requests<br> 218so�Memcheck�can�be�used�to�find�leaks�and�use�after�free�in�an�Inner<br> 219Valgrind.<br> 220<br> 221The�Valgrind�"big�lock"�is�annotated�with�helgrind�client�requests<br> 222so�helgrind�and�drd�can�be�used�to�find�race�conditions�in�an�Inner<br> 223Valgrind.<br> 224<br> 225All�this�has�not�been�tested�much,�so�don't�be�surprised�if�you�hit�problems.<br> 226<br> 227When�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> 247Note:�--outer-valgrind�must�be�a�"make�install"-ed�valgrind.<br> 248Do�*not*�use�vg-in-place.<br> 249<br> 250When�an�outer�valgrind�runs�an�inner�valgrind,�a�regression�test<br> 251produces�one�additional�file�<testname>.outer.log�which�contains�the<br> 252errors�detected�by�the�outer�valgrind.��E.g.�for�an�outer�memcheck,�it<br> 253contains�the�leaks�found�in�the�inner,�for�an�outer�helgrind�or�drd,<br> 254it�contains�the�detected�race�conditions.<br> 255<br> 256The�file�tests/outer_inner.supp�contains�suppressions�for�<br> 257the�irrelevant�or�benign�errors�found�in�the�inner.<br> 258<br> 259An�regression�test�running�in�the�inner�(e.g.�memcheck/tests/badrw)�will<br> 260cause�the�inner�to�report�an�error,�which�is�expected�and�checked<br> 261as�usual�when�running�the�regtests�in�an�outer/inner�setup.<br> 262However,�the�outer�will�often�also�observe�an�error,�e.g.�a�jump<br> 263using�uninitialised�data,�or�a�read/write�outside�the�bounds�of�a�heap<br> 264block.�When�the�outer�reports�such�an�error,�it�will�output�the<br> 265inner�host�stacktrace.�To�this�stacktrace,�it�will�append�the<br> 266stacktrace�of�the�inner�guest�program.�For�example,�this�is�an�error<br> 267reported�by�the�outer�when�the�inner�runs�the�badrw�regtest:<br> 268��==8119==�Invalid�read�of�size�2<br> 269��==8119==����at�0x7F2EFD7AF:�???<br> 270��==8119==����by�0x7F2C82EAF:�???<br> 271��==8119==����by�0x7F180867F:�???<br> 272��==8119==����by�0x40051D:�main�(badrw.c:5)<br> 273��==8119==����by�0x7F180867F:�???<br> 274��==8119==����by�0x1BFF:�???<br> 275��==8119==����by�0x3803B7F0:�_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______�(m_execontext.c:332)<br> 276��==8119==����by�0x40055C:�main�(badrw.c:22)<br> 277��==8119==��Address�0x55cd03c�is�4�bytes�before�a�block�of�size�16�alloc'd<br> 278��==8119==����at�0x2804E26D:�vgPlain_arena_malloc�(m_mallocfree.c:1914)<br> 279��==8119==����by�0x2800BAB4:�vgMemCheck_new_block�(mc_malloc_wrappers.c:368)<br> 280��==8119==����by�0x2800BC87:�vgMemCheck_malloc�(mc_malloc_wrappers.c:403)<br> 281��==8119==����by�0x28097EAE:�do_client_request�(scheduler.c:1861)<br> 282��==8119==����by�0x28097EAE:�vgPlain_scheduler�(scheduler.c:1425)<br> 283��==8119==����by�0x280A7237:�thread_wrapper�(syswrap-linux.c:103)<br> 284��==8119==����by�0x280A7237:�run_a_thread_NORETURN�(syswrap-linux.c:156)<br> 285��==8119==����by�0x3803B7F0:�_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______�(m_execontext.c:332)<br> 286��==8119==����by�0x4C294C4:�malloc�(vg_replace_malloc.c:298)<br> 287��==8119==����by�0x40051D:�main�(badrw.c:5)<br> 288In�the�above,�the�first�stacktrace�starts�with�the�inner�host�stacktrace,<br> 289which�in�this�case�is�some�JITted�code.�Such�code�sometimes�contains�IPs<br> 290that�points�in�the�inner�guest�code�(0x40051D:�main�(badrw.c:5)).<br> 291After�the�separator,�we�have�the�inner�guest�stacktrace.<br> 292The�second�stacktrace�gives�the�stacktrace�where�the�heap�block�that�was<br> 293overrun�was�allocated.�We�see�it�was�allocated�by�the�inner�valgrind<br> 294in�the�client�arena�(first�part�of�the�stacktrace).�The�second�part�is<br> 295the�guest�stacktrace�that�did�the�allocation.<br> 296<br> 297<br> 298(C)�Performance�tests�in�an�outer/inner�setup:<br> 299<br> 300�To�run�all�the�performance�tests�with�an�outer�cachegrind,�do�:<br> 301����perl�perf/vg_perf�--outer-valgrind=../outer/.../bin/valgrind�perf<br> 302<br> 303�To�run�a�specific�perf�test�(e.g.�bz2)�in�this�setup,�do�:<br> 304����perl�perf/vg_perf�--outer-valgrind=../outer/.../bin/valgrind�perf/bz2<br> 305<br> 306�To�run�all�the�performance�tests�with�an�outer�callgrind,�do�:<br> 307����perl�perf/vg_perf�--outer-valgrind=../outer/.../bin/valgrind�\<br> 308����������������������--outer-tool=callgrind�perf<br> 309<br> 310Note:�--outer-valgrind�must�be�a�"make�install"-ed�valgrind.<br> 311Do�*not*�use�vg-in-place.<br> 312<br> 313�To�compare�the�performance�of�multiple�Valgrind�versions,�do�:<br> 314����perl�perf/vg_perf�--outer-valgrind=../outer/.../bin/valgrind�\<br> 315������--outer-tool=callgrind�\<br> 316������--vg=../inner_xxxx�--vg=../inner_yyyy�perf<br> 317��(where�inner_xxxx�and�inner_yyyy�are�the�toplevel�directories�of<br> 318��the�versions�to�compare).<br> 319��Cachegrind�and�cg_diff�are�particularly�handy�to�obtain�a�delta<br> 320��between�the�two�versions.<br> 321<br> 322When�the�outer�tool�is�callgrind�or�cachegrind,�the�following<br> 323output�files�will�be�created�for�each�test:<br> 324���<outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid><br> 325���<outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid><br> 326�(where�tt�is�the�two�letters�abbreviation�for�the�inner�tool(s)�run).<br> 327<br> 328For�example,�the�command<br> 329����perl�perf/vg_perf�\<br> 330������--outer-valgrind=../outer_trunk/install/bin/valgrind�\<br> 331������--outer-tool=callgrind�\<br> 332������--vg=../inner_tchain�--vg=../inner_trunk�perf/many-loss-records<br> 333<br> 334produces�the�files<br> 335����callgrind.out.inner_tchain.no.many-loss-records.18465<br> 336����callgrind.outer.log.inner_tchain.no.many-loss-records.18465<br> 337����callgrind.out.inner_tchain.me.many-loss-records.21899<br> 338����callgrind.outer.log.inner_tchain.me.many-loss-records.21899<br> 339����callgrind.out.inner_trunk.no.many-loss-records.21224<br> 340����callgrind.outer.log.inner_trunk.no.many-loss-records.21224<br> 341����callgrind.out.inner_trunk.me.many-loss-records.22916<br> 342����callgrind.outer.log.inner_trunk.me.many-loss-records.22916<br> 343<br> 344<br> 345Printing�out�problematic�blocks<br> 346~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 347If�you�want�to�print�out�a�disassembly�of�a�particular�block�that<br> 348causes�a�crash,�do�the�following.<br> 349<br> 350Try�running�with�"--vex-guest-chase-thresh=0�--trace-flags=10000000<br> 351--trace-notbelow=999999".��This�should�print�one�line�for�each�block<br> 352translated,�and�that�includes�the�address.<br> 353<br> 354Then�re-run�with�999999�changed�to�the�highest�bb�number�shown.<br> 355This�will�print�the�one�line�per�block,�and�also�will�print�a<br> 356disassembly�of�the�block�in�which�the�fault�occurred.<br> 357<br> 358����</p></div> 359</div> 360<div> 361<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 362<tr> 363<td rowspan="2" width="40%" align="left"> 364<a accesskey="p" href="dist.readme-missing.html"><<�5.�README_MISSING_SYSCALL_OR_IOCTL</a>�</td> 365<td width="20%" align="center"><a accesskey="u" href="dist.html">Up</a></td> 366<td rowspan="2" width="40%" align="right">�<a accesskey="n" href="dist.readme-packagers.html">7.�README_PACKAGERS�>></a> 367</td> 368</tr> 369<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 370</table> 371</div> 372</body> 373</html> 374