File: dist.readme-developers.html

package info (click to toggle)
valgrind 1%3A3.14.0-3
links: PTS, VCS
area: main
in suites: buster
size: 156,980 kB
sloc: ansic: 728,128; exp: 26,134; xml: 22,268; cpp: 7,638; asm: 7,312; makefile: 6,102; perl: 5,910; sh: 5,717
file content (372 lines) | stat: -rw-r--r-- 17,394 bytes
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>6.README_DEVELOPERS</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="dist.html" title="Valgrind Distribution Documents">
<link rel="prev" href="dist.readme-missing.html" title="5.README_MISSING_SYSCALL_OR_IOCTL">
<link rel="next" href="dist.readme-packagers.html" title="7.README_PACKAGERS">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
<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>
<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>
<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>
<th align="center" valign="middle">Valgrind Distribution Documents</th>
<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>
</tr></table></div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="dist.readme-developers"></a>6.README_DEVELOPERS</h1></div></div></div>
<div class="literallayout"><p><br>
<br>
Buildingandnotinstallingit<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
TorunValgrindwithouthavingtoinstallit,runcoregrind/valgrind<br>
withtheVALGRIND_LIBenvironmentvariableset,where&lt;dir&gt;istheroot<br>
ofthesourcetree(andmustbeanabsolutepath).Eg:<br>
<br>
VALGRIND_LIB=~/grind/head4/.in_place~/grind/head4/coregrind/valgrind<br>
<br>
Thisallowsyoutocompileandrunwith"make"insteadof"makeinstall",<br>
savingyoutime.<br>
<br>
Or,youcanusethe'vg-in-place'scriptwhichdoesthatforyou.<br>
<br>
Irecommendcompilingwith"make--quiet"tofurtherreducetheamountof<br>
outputspewedoutduringcompilation,lettingyouactuallyseeanyerrors,<br>
warnings,etc.<br>
<br>
<br>
Buildingadistributiontarball<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Tobuildadistributiontarballfromthevalgrindsources:<br>
<br>
makedist<br>
<br>
Inadditiontocompiling,linkingandpackagingeverythingup,thecommand<br>
willalsoattempttobuildthedocumentation.<br>
<br>
Ifyouonlywanttotestwhetherthegeneratedtarballiscompleteandruns<br>
regressiontestssuccessfully,buildingdocumentationisnotneeded.<br>
<br>
makedistBUILD_ALL_DOCS=no<br>
<br>
Ifyouinsistonbuildingdocumentationsomeembarrassinginstructions<br>
canbefoundindocs/README.<br>
<br>
<br>
Runningtheregressiontests<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Tobuildandrunalltheregressiontests,run"make[--quiet]regtest".<br>
<br>
Torunasubsetoftheregressiontests,execute:<br>
<br>
perltests/vg_regtest&lt;name&gt;<br>
<br>
where&lt;name&gt;isadirectory(alltestswithinwillberun)orasingle<br>
.vgtesttestfile,orthenameofaprogramwhichhasalike-named.vgtest<br>
file.Eg:<br>
<br>
perltests/vg_regtestmemcheck<br>
perltests/vg_regtestmemcheck/tests/badfree.vgtest<br>
perltests/vg_regtestmemcheck/tests/badfree<br>
<br>
<br>
Runningtheperformancetests<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Tobuildandrunalltheperformancetests,run"make[--quiet]perf".<br>
<br>
Torunasubsetoftheperformancesuite,execute:<br>
<br>
perlperf/vg_perf&lt;name&gt;<br>
<br>
where&lt;name&gt;isadirectory(alltestswithinwillberun)orasingle<br>
.vgperftestfile,orthenameofaprogramwhichhasalike-named.vgperf<br>
file.Eg:<br>
<br>
perlperf/vg_perfperf/<br>
perlperf/vg_perfperf/bz2.vgperf<br>
perlperf/vg_perfperf/bz2<br>
<br>
TocomparemultipleversionsofValgrind,usethe--vg=optionmultiple<br>
times.Forexample,ifyouhavetwoValgrindsnexttoeachother,onein<br>
trunk1/andoneintrunk2/,fromwithineithertrunk1/ortrunk2/dothisto<br>
comparethemonalltheperformancetests:<br>
<br>
perlperf/vg_perf--vg=../trunk1--vg=../trunk2perf/<br>
<br>
<br>
DebuggingValgrindwithGDB<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Todebugthevalgrindlauncherprogram(&lt;prefix&gt;/bin/valgrind)just<br>
runitundergdbinthenormalway.<br>
<br>
Debuggingthemainbodyofthevalgrindcode(and/orthecodefor<br>
aparticulartool)requiresabitmoretrickerybutcanbeachieved<br>
withouttoomuchproblembyfollowingthesesteps:<br>
<br>
(1)SetVALGRIND_LAUNCHERtopointtothevalgrindexecutable.Eg:<br>
<br>
exportVALGRIND_LAUNCHER=/usr/local/bin/valgrind<br>
<br>
orforanuninstalledversioninasourcedirectory$DIR:<br>
<br>
exportVALGRIND_LAUNCHER=$DIR/coregrind/valgrind<br>
<br>
(2)Rungdbonthetoolexecutable.Eg:<br>
<br>
gdb/usr/local/lib/valgrind/ppc32-linux/lackey<br>
<br>
or<br>
<br>
gdb$DIR/.in_place/x86-linux/memcheck<br>
<br>
(3)Do"handleSIGSEGVSIGILLnostopnoprint"inGDBtopreventGDBfrom<br>
stoppingonaSIGSEGVorSIGILL:<br>
<br>
(gdb)handleSIGILLSIGSEGVnostopnoprint<br>
<br>
(4)Setanybreakpointsyouwantandproceedasnormalforgdb.The<br>
macroVG_(FUNC)isexpandedtovgPlain_FUNC,soIfyouwanttoset<br>
abreakpointVG_(do_exec),youcoulddolikethisinGDB:<br>
<br>
(gdb)bvgPlain_do_exec<br>
<br>
(5)Runthetoolwithrequiredoptions(the--tooloptionisrequired<br>
forcorrectsetup),e.g.<br>
<br>
(gdb)run--tool=lackeypwd<br>
<br>
Steps(1)--(3)canbeputina.gdbinitfile,butanydirectorynamesmust<br>
befullyexpanded(ie.notanenvironmentvariable).<br>
<br>
Adifferentandpossiblyeasierwayisasfollows:<br>
<br>
(1)RunValgrindasnormal,butaddtheflag--wait-for-gdb=yes.This<br>
putsthetoolexecutableintoawaitloopsoonafteritgains<br>
control.Thisdelaysstartupforafewseconds.<br>
<br>
(2)Inadifferentshell,do"gdb/proc/&lt;pid&gt;/exe&lt;pid&gt;",where<br>
&lt;pid&gt;youreadfromtheoutputprintedby(1).Thisattaches<br>
GDBtothetoolexecutable,whichshouldbeintheabovementioned<br>
waitloop.<br>
<br>
(3)Do"cont"tocontinue.Aftertheloopfinishesspinning,startup<br>
willcontinueasnormal.Notethatcomment(3)aboverepassing<br>
signalsappliesheretoo.<br>
<br>
<br>
Self-hosting<br>
~~~~~~~~~~~~<br>
Thissectionexplains:<br>
(A)HowtoconfigureValgrindtorununderValgrind.<br>
Suchasetupiscalledselfhosting,orouter/innersetup.<br>
(B)HowtorunValgrindregressiontestsina'self-hosting'mode,<br>
e.g.toverifyValgrindhasnobugssuchasmemoryleaks.<br>
(C)HowtorunValgrindperformancetestsina'self-hosting'mode,<br>
toanalyseandoptimisetheperformanceofValgrindanditstools.<br>
<br>
(A)HowtoconfigureValgrindtorununderValgrind:<br>
<br>
(1)Checkout2trees,"Inner"and"Outer".Innerrunstheapp<br>
directly.OuterrunsInner.<br>
<br>
(2)ConfigureInnerwith--enable-innerandbuildasusual.<br>
<br>
(3)ConfigureOuternormallyandbuild+installasusual.<br>
Note:Youmustusea"makeinstall"-edvalgrind.<br>
Do*not*usevg-in-placefortheOutervalgrind.<br>
<br>
(4)Chooseaverysimpleprogram(date)andtry<br>
<br>
outer/.../bin/valgrind--sim-hints=enable-outer--trace-children=yes\<br>
--smc-check=all-non-file\<br>
--run-libc-freeres=no--tool=cachegrind-v\<br>
inner/.../vg-in-place--vgdb-prefix=./inner--tool=none-vprog<br>
<br>
Ifyouomitthe--trace-children=yes,you'llonlymonitorInner'slauncher<br>
program,notitsstage2.Outerneeds--run-libc-freeres=no,asotherwise<br>
itwilltrytofindandrun__libc_freeresintheinner,whilelibcisnot<br>
usedbytheinner.Innerneeds--vgdb-prefix=./innertoavoidinner<br>
gdbservercollidingwithoutergdbserver.<br>
Currently,innerdoes*not*usetheclientrequest<br>
VALGRIND_DISCARD_TRANSLATIONSfortheJITtedcodeorthecodepatchedfor<br>
translationchaining.Sotheouterneeds--smc-check=all-non-fileto<br>
detectthemodifiedcode.<br>
<br>
Debuggingthewholethingmightimplytouseupto3GDB:<br>
*aGDBattachedtotheOutervalgrind,allowing<br>
toexaminethestateofOuter.<br>
*aGDBusingOutergdbserver,allowingto<br>
examinethestateofInner.<br>
*aGDBusingInnergdbserver,allowingto<br>
examinethestateofprog.<br>
<br>
Thewholethingisfragile,confusingandslow,butitdoesworkwellenough<br>
foryoutogetsomeusefulperformancedata.Innerhasmostof<br>
itsoutput(ie.thoselinesbeginningwith"==&lt;pid&gt;==")prefixedwitha'&gt;',<br>
whichhelpsalot.However,whenrunningregressiontestsinanOuter/Inner<br>
setup,thisprefixcausestheregtestdifftofail.Give<br>
--sim-hints=no-inner-prefixtotheInnertodisabletheproduction<br>
oftheprefixinthestdout/stderroutputofInner.<br>
<br>
Theallocatorsincoregrind/m_mallocfree.candVEX/priv/main_util.hare<br>
annotatedwithclientrequestssoMemcheckcanbeusedtofindleaks<br>
anduseafterfreeinanInnerValgrind.<br>
<br>
TheValgrind"biglock"isannotatedwithhelgrindclientrequests<br>
soHelgrindandDRDcanbeusedtofindraceconditionsinanInner<br>
Valgrind.<br>
<br>
Allthishasnotbeentestedmuch,sodon'tbesurprisedifyouhitproblems.<br>
<br>
Whenusingself-hostingwithanouterCallgrindtool,use'--pop-on-jump'<br>
(ontheouter).Otherwise,Callgrindhasmuchhighermemoryrequirements.<br>
<br>
(B)Regressiontestsinanouter/innersetup:<br>
<br>
Torunalltheregressiontestswithanoutermemcheck,do:<br>
perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\<br>
--all<br>
<br>
Torunaspecificregressiontestswithanoutermemcheck,do:<br>
perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\<br>
none/tests/args.vgtest<br>
<br>
Torunregressiontestswithanotheroutertool:<br>
perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\<br>
--outer-tool=helgrind--all<br>
<br>
--outer-argsallowstogivespecificargumentstotheoutertool,<br>
replacingthedefaultoneprovidedbyvg_regtest.<br>
<br>
Note:--outer-valgrindmustbea"makeinstall"-edvalgrind.<br>
Do*not*usevg-in-place.<br>
<br>
Whenanoutervalgrindrunsaninnervalgrind,aregressiontest<br>
producesoneadditionalfile&lt;testname&gt;.outer.logwhichcontainsthe<br>
errorsdetectedbytheoutervalgrind.E.g.foranoutermemcheck,it<br>
containstheleaksfoundintheinner,foranouterhelgrindordrd,<br>
itcontainsthedetectedraceconditions.<br>
<br>
Thefiletests/outer_inner.suppcontainssuppressionsfor<br>
theirrelevantorbenignerrorsfoundintheinner.<br>
<br>
Anregressiontestrunningintheinner(e.g.memcheck/tests/badrw)will<br>
causetheinnertoreportanerror,whichisexpectedandchecked<br>
asusualwhenrunningtheregtestsinanouter/innersetup.<br>
However,theouterwilloftenalsoobserveanerror,e.g.ajump<br>
usinguninitialiseddata,oraread/writeoutsidetheboundsofaheap<br>
block.Whentheouterreportssuchanerror,itwilloutputthe<br>
innerhoststacktrace.Tothisstacktrace,itwillappendthe<br>
stacktraceoftheinnerguestprogram.Forexample,thisisanerror<br>
reportedbytheouterwhentheinnerrunsthebadrwregtest:<br>
==8119==Invalidreadofsize2<br>
==8119==at0x7F2EFD7AF:???<br>
==8119==by0x7F2C82EAF:???<br>
==8119==by0x7F180867F:???<br>
==8119==by0x40051D:main(badrw.c:5)<br>
==8119==by0x7F180867F:???<br>
==8119==by0x1BFF:???<br>
==8119==by0x3803B7F0:_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______(m_execontext.c:332)<br>
==8119==by0x40055C:main(badrw.c:22)<br>
==8119==Address0x55cd03cis4bytesbeforeablockofsize16alloc'd<br>
==8119==at0x2804E26D:vgPlain_arena_malloc(m_mallocfree.c:1914)<br>
==8119==by0x2800BAB4:vgMemCheck_new_block(mc_malloc_wrappers.c:368)<br>
==8119==by0x2800BC87:vgMemCheck_malloc(mc_malloc_wrappers.c:403)<br>
==8119==by0x28097EAE:do_client_request(scheduler.c:1861)<br>
==8119==by0x28097EAE:vgPlain_scheduler(scheduler.c:1425)<br>
==8119==by0x280A7237:thread_wrapper(syswrap-linux.c:103)<br>
==8119==by0x280A7237:run_a_thread_NORETURN(syswrap-linux.c:156)<br>
==8119==by0x3803B7F0:_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______(m_execontext.c:332)<br>
==8119==by0x4C294C4:malloc(vg_replace_malloc.c:298)<br>
==8119==by0x40051D:main(badrw.c:5)<br>
Intheabove,thefirststacktracestartswiththeinnerhoststacktrace,<br>
whichinthiscaseissomeJITtedcode.SuchcodesometimescontainsIPs<br>
thatpointsintheinnerguestcode(0x40051D:main(badrw.c:5)).<br>
Aftertheseparator,wehavetheinnergueststacktrace.<br>
Thesecondstacktracegivesthestacktracewheretheheapblockthatwas<br>
overrunwasallocated.Weseeitwasallocatedbytheinnervalgrind<br>
intheclientarena(firstpartofthestacktrace).Thesecondpartis<br>
thegueststacktracethatdidtheallocation.<br>
<br>
<br>
(C)Performancetestsinanouter/innersetup:<br>
<br>
Torunalltheperformancetestswithanoutercachegrind,do:<br>
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrindperf<br>
<br>
Torunaspecificperftest(e.g.bz2)inthissetup,do:<br>
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrindperf/bz2<br>
<br>
Torunalltheperformancetestswithanoutercallgrind,do:<br>
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrind\<br>
--outer-tool=callgrindperf<br>
<br>
Note:--outer-valgrindmustbea"makeinstall"-edvalgrind.<br>
Do*not*usevg-in-place.<br>
<br>
TocomparetheperformanceofmultipleValgrindversions,do:<br>
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrind\<br>
--outer-tool=callgrind\<br>
--vg=../inner_xxxx--vg=../inner_yyyyperf<br>
(whereinner_xxxxandinner_yyyyarethetopleveldirectoriesof<br>
theversionstocompare).<br>
Cachegrindandcg_diffareparticularlyhandytoobtainadelta<br>
betweenthetwoversions.<br>
<br>
Whentheoutertooliscallgrindorcachegrind,thefollowing<br>
outputfileswillbecreatedforeachtest:<br>
&lt;outertoolname&gt;.out.&lt;inner_valgrind_dir&gt;.&lt;tt&gt;.&lt;perftestname&gt;.&lt;pid&gt;<br>
&lt;outertoolname&gt;.outer.log.&lt;inner_valgrind_dir&gt;.&lt;tt&gt;.&lt;perftestname&gt;.&lt;pid&gt;<br>
(wherettisthetwolettersabbreviationfortheinnertool(s)run).<br>
<br>
Forexample,thecommand<br>
perlperf/vg_perf\<br>
--outer-valgrind=../outer_trunk/install/bin/valgrind\<br>
--outer-tool=callgrind\<br>
--vg=../inner_tchain--vg=../inner_trunkperf/many-loss-records<br>
<br>
producesthefiles<br>
callgrind.out.inner_tchain.no.many-loss-records.18465<br>
callgrind.outer.log.inner_tchain.no.many-loss-records.18465<br>
callgrind.out.inner_tchain.me.many-loss-records.21899<br>
callgrind.outer.log.inner_tchain.me.many-loss-records.21899<br>
callgrind.out.inner_trunk.no.many-loss-records.21224<br>
callgrind.outer.log.inner_trunk.no.many-loss-records.21224<br>
callgrind.out.inner_trunk.me.many-loss-records.22916<br>
callgrind.outer.log.inner_trunk.me.many-loss-records.22916<br>
<br>
<br>
Printingoutproblematicblocks<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Ifyouwanttoprintoutadisassemblyofaparticularblockthat<br>
causesacrash,dothefollowing.<br>
<br>
Tryrunningwith"--vex-guest-chase-thresh=0--trace-flags=10000000<br>
--trace-notbelow=999999".Thisshouldprintonelineforeachblock<br>
translated,andthatincludestheaddress.<br>
<br>
Thenre-runwith999999changedtothehighestbbnumbershown.<br>
Thiswillprinttheonelineperblock,andalsowillprinta<br>
disassemblyoftheblockinwhichthefaultoccurred.<br>
<br>
</p></div>
</div>
<div>
<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
<tr>
<td rowspan="2" width="40%" align="left">
<a accesskey="p" href="dist.readme-missing.html">&lt;&lt;5.README_MISSING_SYSCALL_OR_IOCTL</a></td>
<td width="20%" align="center"><a accesskey="u" href="dist.html">Up</a></td>
<td rowspan="2" width="40%" align="right"><a accesskey="n" href="dist.readme-packagers.html">7.README_PACKAGERS&gt;&gt;</a>
</td>
</tr>
<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr>
</table>
</div>
</body>
</html>