• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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�&lt;dir&gt;�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�&lt;name&gt;<br>
68<br>
69where�&lt;name&gt;�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_regtestmemcheck/tests/badfree.vgtest<br>
75��perl�tests/vg_regtestmemcheck/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�&lt;name&gt;<br>
85<br>
86where�&lt;name&gt;�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_perfperf/bz2.vgperf<br>
92��perl�perf/vg_perfperf/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�(&lt;prefix&gt;/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/&lt;pid&gt;/exe�&lt;pid&gt;",�where<br>
153����&lt;pid&gt;�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�"==&lt;pid&gt;==")�prefixed�with�a�'&gt;',<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�&lt;testname&gt;.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/valgrindperf/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���&lt;outertoolname&gt;.out.&lt;inner_valgrind_dir&gt;.&lt;tt&gt;.&lt;perftestname&gt;.&lt;pid&gt;<br>
325���&lt;outertoolname&gt;.outer.log.&lt;inner_valgrind_dir&gt;.&lt;tt&gt;.&lt;perftestname&gt;.&lt;pid&gt;<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_trunkperf/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">&lt;&lt;�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�&gt;&gt;</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