Buildingandnotinstallingit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TorunValgrindwithouthavingtoinstallit,runcoregrind/valgrind
withtheVALGRIND_LIBenvironmentvariableset,where<dir>istheroot
ofthesourcetree(andmustbeanabsolutepath).Eg:
VALGRIND_LIB=~/grind/head4/.in_place~/grind/head4/coregrind/valgrind
Thisallowsyoutocompileandrunwith"make"insteadof"makeinstall",
savingyoutime.
Or,youcanusethe'vg-in-place'scriptwhichdoesthatforyou.
Irecommendcompilingwith"make--quiet"tofurtherreducetheamountof
outputspewedoutduringcompilation,lettingyouactuallyseeanyerrors,
warnings,etc.
Buildingadistributiontarball
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tobuildadistributiontarballfromthevalgrindsources:
makedist
Inadditiontocompiling,linkingandpackagingeverythingup,thecommand
willalsoattempttobuildthedocumentation.
Ifyouonlywanttotestwhetherthegeneratedtarballiscompleteandruns
regressiontestssuccessfully,buildingdocumentationisnotneeded.
makedistBUILD_ALL_DOCS=no
Ifyouinsistonbuildingdocumentationsomeembarrassinginstructions
canbefoundindocs/README.
Runningtheregressiontests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tobuildandrunalltheregressiontests,run"make[--quiet]regtest".
Torunasubsetoftheregressiontests,execute:
perltests/vg_regtest<name>
where<name>isadirectory(alltestswithinwillberun)orasingle
.vgtesttestfile,orthenameofaprogramwhichhasalike-named.vgtest
file.Eg:
perltests/vg_regtestmemcheck
perltests/vg_regtestmemcheck/tests/badfree.vgtest
perltests/vg_regtestmemcheck/tests/badfree
Runningtheperformancetests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tobuildandrunalltheperformancetests,run"make[--quiet]perf".
Torunasubsetoftheperformancesuite,execute:
perlperf/vg_perf<name>
where<name>isadirectory(alltestswithinwillberun)orasingle
.vgperftestfile,orthenameofaprogramwhichhasalike-named.vgperf
file.Eg:
perlperf/vg_perfperf/
perlperf/vg_perfperf/bz2.vgperf
perlperf/vg_perfperf/bz2
TocomparemultipleversionsofValgrind,usethe--vg=optionmultiple
times.Forexample,ifyouhavetwoValgrindsnexttoeachother,onein
trunk1/andoneintrunk2/,fromwithineithertrunk1/ortrunk2/dothisto
comparethemonalltheperformancetests:
perlperf/vg_perf--vg=../trunk1--vg=../trunk2perf/
DebuggingValgrindwithGDB
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Todebugthevalgrindlauncherprogram(<prefix>/bin/valgrind)just
runitundergdbinthenormalway.
Debuggingthemainbodyofthevalgrindcode(and/orthecodefor
aparticulartool)requiresabitmoretrickerybutcanbeachieved
withouttoomuchproblembyfollowingthesesteps:
(1)SetVALGRIND_LAUNCHERtopointtothevalgrindexecutable.Eg:
exportVALGRIND_LAUNCHER=/usr/local/bin/valgrind
orforanuninstalledversioninasourcedirectory$DIR:
exportVALGRIND_LAUNCHER=$DIR/coregrind/valgrind
(2)Rungdbonthetoolexecutable.Eg:
gdb/usr/local/lib/valgrind/ppc32-linux/lackey
or
gdb$DIR/.in_place/x86-linux/memcheck
(3)Do"handleSIGSEGVSIGILLnostopnoprint"inGDBtopreventGDBfrom
stoppingonaSIGSEGVorSIGILL:
(gdb)handleSIGILLSIGSEGVnostopnoprint
(4)Setanybreakpointsyouwantandproceedasnormalforgdb.The
macroVG_(FUNC)isexpandedtovgPlain_FUNC,soIfyouwanttoset
abreakpointVG_(do_exec),youcoulddolikethisinGDB:
(gdb)bvgPlain_do_exec
(5)Runthetoolwithrequiredoptions(the--tooloptionisrequired
forcorrectsetup),e.g.
(gdb)run--tool=lackeypwd
Steps(1)--(3)canbeputina.gdbinitfile,butanydirectorynamesmust
befullyexpanded(ie.notanenvironmentvariable).
Adifferentandpossiblyeasierwayisasfollows:
(1)RunValgrindasnormal,butaddtheflag--wait-for-gdb=yes.This
putsthetoolexecutableintoawaitloopsoonafteritgains
control.Thisdelaysstartupforafewseconds.
(2)Inadifferentshell,do"gdb/proc/<pid>/exe<pid>",where
<pid>youreadfromtheoutputprintedby(1).Thisattaches
GDBtothetoolexecutable,whichshouldbeintheabovementioned
waitloop.
(3)Do"cont"tocontinue.Aftertheloopfinishesspinning,startup
willcontinueasnormal.Notethatcomment(3)aboverepassing
signalsappliesheretoo.
Self-hosting
~~~~~~~~~~~~
Thissectionexplains:
(A)HowtoconfigureValgrindtorununderValgrind.
Suchasetupiscalledselfhosting,orouter/innersetup.
(B)HowtorunValgrindregressiontestsina'self-hosting'mode,
e.g.toverifyValgrindhasnobugssuchasmemoryleaks.
(C)HowtorunValgrindperformancetestsina'self-hosting'mode,
toanalyseandoptimisetheperformanceofValgrindanditstools.
(A)HowtoconfigureValgrindtorununderValgrind:
(1)Checkout2trees,"Inner"and"Outer".Innerrunstheapp
directly.OuterrunsInner.
(2)Configureinnerwith--enable-innerandbuild/installasusual.
(3)ConfigureOuternormallyandbuild/installasusual.
(4)Chooseaverysimpleprogram(date)andtry
outer/.../bin/valgrind--sim-hints=enable-outer--trace-children=yes\
--smc-check=all-non-file\
--run-libc-freeres=no--tool=cachegrind-v\
inner/.../bin/valgrind--vgdb-prefix=./inner--tool=none-vprog
Note:Youmustusea"makeinstall"-edvalgrind.
Do*not*usevg-in-placefortheoutervalgrind.
Ifyouomitthe--trace-children=yes,you'llonlymonitorInner'slauncher
program,notitsstage2.Outerneeds--run-libc-freeres=no,asotherwise
itwilltrytofindandrun__libc_freeresintheinner,whilelibcisnot
usedbytheinner.Innerneeds--vgdb-prefix=./innertoavoidinner
gdbservercollidingwithoutergdbserver.
Currently,innerdoes*not*usetheclientrequest
VALGRIND_DISCARD_TRANSLATIONSfortheJITtedcodeorthecodepatchedfor
translationchaining.Sotheouterneeds--smc-check=all-non-fileto
detectthemodifiedcode.
Debuggingthewholethingmightimplytouseupto3GDB:
*aGDBattachedtotheOutervalgrind,allowing
toexaminethestateofOuter.
*aGDBusingOutergdbserver,allowingto
examinethestateofInner.
*aGDBusingInnergdbserver,allowingto
examinethestateofprog.
Thewholethingisfragile,confusingandslow,butitdoesworkwellenough
foryoutogetsomeusefulperformancedata.Innerhasmostof
itsoutput(ie.thoselinesbeginningwith"==<pid>==")prefixedwitha'>',
whichhelpsalot.However,whenrunningregressiontestsinanOuter/Inner
setup,thisprefixcausestheregtestdifftofail.Give
--sim-hints=no-inner-prefixtotheInnertodisabletheproduction
oftheprefixinthestdout/stderroutputofInner.
Theallocator(coregrind/m_mallocfree.c)isannotatedwithclientrequests
soMemcheckcanbeusedtofindleaksanduseafterfreeinanInner
Valgrind.
TheValgrind"biglock"isannotatedwithhelgrindclientrequests
sohelgrindanddrdcanbeusedtofindraceconditionsinanInner
Valgrind.
Allthishasnotbeentestedmuch,sodon'tbesurprisedifyouhitproblems.
Whenusingself-hostingwithanouterCallgrindtool,use'--pop-on-jump'
(ontheouter).Otherwise,Callgrindhasmuchhighermemoryrequirements.
(B)Regressiontestsinanouter/innersetup:
Torunalltheregressiontestswithanoutermemcheck,do:
perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\
--all
Torunaspecificregressiontestswithanoutermemcheck,do:
perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\
none/tests/args.vgtest
Torunregressiontestswithanotheroutertool:
perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\
--outer-tool=helgrind--all
--outer-argsallowstogivespecificargumentstotheoutertool,
replacingthedefaultoneprovidedbyvg_regtest.
Note:--outer-valgrindmustbea"makeinstall"-edvalgrind.
Do*not*usevg-in-place.
Whenanoutervalgrindrunsaninnervalgrind,aregressiontest
producesoneadditionalfile<testname>.outer.logwhichcontainsthe
errorsdetectedbytheoutervalgrind.E.g.foranoutermemcheck,it
containstheleaksfoundintheinner,foranouterhelgrindordrd,
itcontainsthedetectedraceconditions.
Thefiletests/outer_inner.suppcontainssuppressionsfor
theirrelevantorbenignerrorsfoundintheinner.
Anregressiontestrunningintheinner(e.g.memcheck/tests/badrw)will
causetheinnertoreportanerror,whichisexpectedandchecked
asusualwhenrunningtheregtestsinanouter/innersetup.
However,theouterwilloftenalsoobserveanerror,e.g.ajump
usinguninitialiseddata,oraread/writeoutsidetheboundsofaheap
block.Whentheouterreportssuchanerror,itwilloutputthe
innerhoststacktrace.Tothisstacktrace,itwillappendthe
stacktraceoftheinnerguestprogram.Forexample,thisisanerror
reportedbytheouterwhentheinnerrunsthebadrwregtest:
==8119==Invalidreadofsize2
==8119==at0x7F2EFD7AF:???
==8119==by0x7F2C82EAF:???
==8119==by0x7F180867F:???
==8119==by0x40051D:main(badrw.c:5)
==8119==by0x7F180867F:???
==8119==by0x1BFF:???
==8119==by0x3803B7F0:_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______(m_execontext.c:332)
==8119==by0x40055C:main(badrw.c:22)
==8119==Address0x55cd03cis4bytesbeforeablockofsize16alloc'd
==8119==at0x2804E26D:vgPlain_arena_malloc(m_mallocfree.c:1914)
==8119==by0x2800BAB4:vgMemCheck_new_block(mc_malloc_wrappers.c:368)
==8119==by0x2800BC87:vgMemCheck_malloc(mc_malloc_wrappers.c:403)
==8119==by0x28097EAE:do_client_request(scheduler.c:1861)
==8119==by0x28097EAE:vgPlain_scheduler(scheduler.c:1425)
==8119==by0x280A7237:thread_wrapper(syswrap-linux.c:103)
==8119==by0x280A7237:run_a_thread_NORETURN(syswrap-linux.c:156)
==8119==by0x3803B7F0:_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______(m_execontext.c:332)
==8119==by0x4C294C4:malloc(vg_replace_malloc.c:298)
==8119==by0x40051D:main(badrw.c:5)
Intheabove,thefirststacktracestartswiththeinnerhoststacktrace,
whichinthiscaseissomeJITtedcode.SuchcodesometimescontainsIPs
thatpointsintheinnerguestcode(0x40051D:main(badrw.c:5)).
Aftertheseparator,wehavetheinnergueststacktrace.
Thesecondstacktracegivesthestacktracewheretheheapblockthatwas
overrunwasallocated.Weseeitwasallocatedbytheinnervalgrind
intheclientarena(firstpartofthestacktrace).Thesecondpartis
thegueststacktracethatdidtheallocation.
(C)Performancetestsinanouter/innersetup:
Torunalltheperformancetestswithanoutercachegrind,do:
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrindperf
Torunaspecificperftest(e.g.bz2)inthissetup,do:
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrindperf/bz2
Torunalltheperformancetestswithanoutercallgrind,do:
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrind\
--outer-tool=callgrindperf
Note:--outer-valgrindmustbea"makeinstall"-edvalgrind.
Do*not*usevg-in-place.
TocomparetheperformanceofmultipleValgrindversions,do:
perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrind\
--outer-tool=callgrind\
--vg=../inner_xxxx--vg=../inner_yyyyperf
(whereinner_xxxxandinner_yyyyarethetopleveldirectoriesof
theversionstocompare).
Cachegrindandcg_diffareparticularlyhandytoobtainadelta
betweenthetwoversions.
Whentheoutertooliscallgrindorcachegrind,thefollowing
outputfileswillbecreatedforeachtest:
<outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
<outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
(wherettisthetwolettersabbreviationfortheinnertool(s)run).
Forexample,thecommand
perlperf/vg_perf\
--outer-valgrind=../outer_trunk/install/bin/valgrind\
--outer-tool=callgrind\
--vg=../inner_tchain--vg=../inner_trunkperf/many-loss-records
producesthefiles
callgrind.out.inner_tchain.no.many-loss-records.18465
callgrind.outer.log.inner_tchain.no.many-loss-records.18465
callgrind.out.inner_tchain.me.many-loss-records.21899
callgrind.outer.log.inner_tchain.me.many-loss-records.21899
callgrind.out.inner_trunk.no.many-loss-records.21224
callgrind.outer.log.inner_trunk.no.many-loss-records.21224
callgrind.out.inner_trunk.me.many-loss-records.22916
callgrind.outer.log.inner_trunk.me.many-loss-records.22916
Printingoutproblematicblocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ifyouwanttoprintoutadisassemblyofaparticularblockthat
causesacrash,dothefollowing.
Tryrunningwith"--vex-guest-chase-thresh=0--trace-flags=10000000
--trace-notbelow=999999".Thisshouldprintonelineforeachblock
translated,andthatincludestheaddress.
Thenre-runwith999999changedtothehighestbbnumbershown.
Thiswillprinttheonelineperblock,andalsowillprinta
disassemblyoftheblockinwhichthefaultoccurred.