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> 25 Buildingandnotinstallingit<br> 26 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 27 TorunValgrindwithouthavingtoinstallit,runcoregrind/valgrind<br> 28 withtheVALGRIND_LIBenvironmentvariableset,where<dir>istheroot<br> 29 ofthesourcetree(andmustbeanabsolutepath).Eg:<br> 30 <br> 31 VALGRIND_LIB=~/grind/head4/.in_place~/grind/head4/coregrind/valgrind<br> 32 <br> 33 Thisallowsyoutocompileandrunwith"make"insteadof"makeinstall",<br> 34 savingyoutime.<br> 35 <br> 36 Or,youcanusethe'vg-in-place'scriptwhichdoesthatforyou.<br> 37 <br> 38 Irecommendcompilingwith"make--quiet"tofurtherreducetheamountof<br> 39 outputspewedoutduringcompilation,lettingyouactuallyseeanyerrors,<br> 40 warnings,etc.<br> 41 <br> 42 <br> 43 Buildingadistributiontarball<br> 44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 45 Tobuildadistributiontarballfromthevalgrindsources:<br> 46 <br> 47 makedist<br> 48 <br> 49 Inadditiontocompiling,linkingandpackagingeverythingup,thecommand<br> 50 willalsoattempttobuildthedocumentation.<br> 51 <br> 52 Ifyouonlywanttotestwhetherthegeneratedtarballiscompleteandruns<br> 53 regressiontestssuccessfully,buildingdocumentationisnotneeded.<br> 54 <br> 55 makedistBUILD_ALL_DOCS=no<br> 56 <br> 57 Ifyouinsistonbuildingdocumentationsomeembarrassinginstructions<br> 58 canbefoundindocs/README.<br> 59 <br> 60 <br> 61 Runningtheregressiontests<br> 62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 63 Tobuildandrunalltheregressiontests,run"make[--quiet]regtest".<br> 64 <br> 65 Torunasubsetoftheregressiontests,execute:<br> 66 <br> 67 perltests/vg_regtest<name><br> 68 <br> 69 where<name>isadirectory(alltestswithinwillberun)orasingle<br> 70 .vgtesttestfile,orthenameofaprogramwhichhasalike-named.vgtest<br> 71 file.Eg:<br> 72 <br> 73 perltests/vg_regtestmemcheck<br> 74 perltests/vg_regtestmemcheck/tests/badfree.vgtest<br> 75 perltests/vg_regtestmemcheck/tests/badfree<br> 76 <br> 77 <br> 78 Runningtheperformancetests<br> 79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 80 Tobuildandrunalltheperformancetests,run"make[--quiet]perf".<br> 81 <br> 82 Torunasubsetoftheperformancesuite,execute:<br> 83 <br> 84 perlperf/vg_perf<name><br> 85 <br> 86 where<name>isadirectory(alltestswithinwillberun)orasingle<br> 87 .vgperftestfile,orthenameofaprogramwhichhasalike-named.vgperf<br> 88 file.Eg:<br> 89 <br> 90 perlperf/vg_perfperf/<br> 91 perlperf/vg_perfperf/bz2.vgperf<br> 92 perlperf/vg_perfperf/bz2<br> 93 <br> 94 TocomparemultipleversionsofValgrind,usethe--vg=optionmultiple<br> 95 times.Forexample,ifyouhavetwoValgrindsnexttoeachother,onein<br> 96 trunk1/andoneintrunk2/,fromwithineithertrunk1/ortrunk2/dothisto<br> 97 comparethemonalltheperformancetests:<br> 98 <br> 99 perlperf/vg_perf--vg=../trunk1--vg=../trunk2perf/<br> 100 <br> 101 <br> 102 DebuggingValgrindwithGDB<br> 103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 104 Todebugthevalgrindlauncherprogram(<prefix>/bin/valgrind)just<br> 105 runitundergdbinthenormalway.<br> 106 <br> 107 Debuggingthemainbodyofthevalgrindcode(and/orthecodefor<br> 108 aparticulartool)requiresabitmoretrickerybutcanbeachieved<br> 109 withouttoomuchproblembyfollowingthesesteps:<br> 110 <br> 111 (1)SetVALGRIND_LAUNCHERtopointtothevalgrindexecutable.Eg:<br> 112 <br> 113 exportVALGRIND_LAUNCHER=/usr/local/bin/valgrind<br> 114 <br> 115 orforanuninstalledversioninasourcedirectory$DIR:<br> 116 <br> 117 exportVALGRIND_LAUNCHER=$DIR/coregrind/valgrind<br> 118 <br> 119 (2)Rungdbonthetoolexecutable.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"handleSIGSEGVSIGILLnostopnoprint"inGDBtopreventGDBfrom<br> 128 stoppingonaSIGSEGVorSIGILL:<br> 129 <br> 130 (gdb)handleSIGILLSIGSEGVnostopnoprint<br> 131 <br> 132 (4)Setanybreakpointsyouwantandproceedasnormalforgdb.The<br> 133 macroVG_(FUNC)isexpandedtovgPlain_FUNC,soIfyouwanttoset<br> 134 abreakpointVG_(do_exec),youcoulddolikethisinGDB:<br> 135 <br> 136 (gdb)bvgPlain_do_exec<br> 137 <br> 138 (5)Runthetoolwithrequiredoptions(the--tooloptionisrequired<br> 139 forcorrectsetup),e.g.<br> 140 <br> 141 (gdb)run--tool=lackeypwd<br> 142 <br> 143 Steps(1)--(3)canbeputina.gdbinitfile,butanydirectorynamesmust<br> 144 befullyexpanded(ie.notanenvironmentvariable).<br> 145 <br> 146 Adifferentandpossiblyeasierwayisasfollows:<br> 147 <br> 148 (1)RunValgrindasnormal,butaddtheflag--wait-for-gdb=yes.This<br> 149 putsthetoolexecutableintoawaitloopsoonafteritgains<br> 150 control.Thisdelaysstartupforafewseconds.<br> 151 <br> 152 (2)Inadifferentshell,do"gdb/proc/<pid>/exe<pid>",where<br> 153 <pid>youreadfromtheoutputprintedby(1).Thisattaches<br> 154 GDBtothetoolexecutable,whichshouldbeintheabovementioned<br> 155 waitloop.<br> 156 <br> 157 (3)Do"cont"tocontinue.Aftertheloopfinishesspinning,startup<br> 158 willcontinueasnormal.Notethatcomment(3)aboverepassing<br> 159 signalsappliesheretoo.<br> 160 <br> 161 <br> 162 Self-hosting<br> 163 ~~~~~~~~~~~~<br> 164 Thissectionexplains:<br> 165 (A)HowtoconfigureValgrindtorununderValgrind.<br> 166 Suchasetupiscalledselfhosting,orouter/innersetup.<br> 167 (B)HowtorunValgrindregressiontestsina'self-hosting'mode,<br> 168 e.g.toverifyValgrindhasnobugssuchasmemoryleaks.<br> 169 (C)HowtorunValgrindperformancetestsina'self-hosting'mode,<br> 170 toanalyseandoptimisetheperformanceofValgrindanditstools.<br> 171 <br> 172 (A)HowtoconfigureValgrindtorununderValgrind:<br> 173 <br> 174 (1)Checkout2trees,"Inner"and"Outer".Innerrunstheapp<br> 175 directly.OuterrunsInner.<br> 176 <br> 177 (2)Configureinnerwith--enable-innerandbuild/installasusual.<br> 178 <br> 179 (3)ConfigureOuternormallyandbuild/installasusual.<br> 180 <br> 181 (4)Chooseaverysimpleprogram(date)andtry<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-vprog<br> 187 <br> 188 Note:Youmustusea"makeinstall"-edvalgrind.<br> 189 Do*not*usevg-in-placefortheoutervalgrind.<br> 190 <br> 191 Ifyouomitthe--trace-children=yes,you'llonlymonitorInner'slauncher<br> 192 program,notitsstage2.Outerneeds--run-libc-freeres=no,asotherwise<br> 193 itwilltrytofindandrun__libc_freeresintheinner,whilelibcisnot<br> 194 usedbytheinner.Innerneeds--vgdb-prefix=./innertoavoidinner<br> 195 gdbservercollidingwithoutergdbserver.<br> 196 Currently,innerdoes*not*usetheclientrequest<br> 197 VALGRIND_DISCARD_TRANSLATIONSfortheJITtedcodeorthecodepatchedfor<br> 198 translationchaining.Sotheouterneeds--smc-check=all-non-fileto<br> 199 detectthemodifiedcode.<br> 200 <br> 201 Debuggingthewholethingmightimplytouseupto3GDB:<br> 202 *aGDBattachedtotheOutervalgrind,allowing<br> 203 toexaminethestateofOuter.<br> 204 *aGDBusingOutergdbserver,allowingto<br> 205 examinethestateofInner.<br> 206 *aGDBusingInnergdbserver,allowingto<br> 207 examinethestateofprog.<br> 208 <br> 209 Thewholethingisfragile,confusingandslow,butitdoesworkwellenough<br> 210 foryoutogetsomeusefulperformancedata.Innerhasmostof<br> 211 itsoutput(ie.thoselinesbeginningwith"==<pid>==")prefixedwitha'>',<br> 212 whichhelpsalot.However,whenrunningregressiontestsinanOuter/Inner<br> 213 setup,thisprefixcausestheregtestdifftofail.Give<br> 214 --sim-hints=no-inner-prefixtotheInnertodisabletheproduction<br> 215 oftheprefixinthestdout/stderroutputofInner.<br> 216 <br> 217 Theallocator(coregrind/m_mallocfree.c)isannotatedwithclientrequests<br> 218 soMemcheckcanbeusedtofindleaksanduseafterfreeinanInner<br> 219 Valgrind.<br> 220 <br> 221 TheValgrind"biglock"isannotatedwithhelgrindclientrequests<br> 222 sohelgrindanddrdcanbeusedtofindraceconditionsinanInner<br> 223 Valgrind.<br> 224 <br> 225 Allthishasnotbeentestedmuch,sodon'tbesurprisedifyouhitproblems.<br> 226 <br> 227 Whenusingself-hostingwithanouterCallgrindtool,use'--pop-on-jump'<br> 228 (ontheouter).Otherwise,Callgrindhasmuchhighermemoryrequirements.<br> 229 <br> 230 (B)Regressiontestsinanouter/innersetup:<br> 231 <br> 232 Torunalltheregressiontestswithanoutermemcheck,do:<br> 233 perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\<br> 234 --all<br> 235 <br> 236 Torunaspecificregressiontestswithanoutermemcheck,do:<br> 237 perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\<br> 238 none/tests/args.vgtest<br> 239 <br> 240 Torunregressiontestswithanotheroutertool:<br> 241 perltests/vg_regtest--outer-valgrind=../outer/.../bin/valgrind\<br> 242 --outer-tool=helgrind--all<br> 243 <br> 244 --outer-argsallowstogivespecificargumentstotheoutertool,<br> 245 replacingthedefaultoneprovidedbyvg_regtest.<br> 246 <br> 247 Note:--outer-valgrindmustbea"makeinstall"-edvalgrind.<br> 248 Do*not*usevg-in-place.<br> 249 <br> 250 Whenanoutervalgrindrunsaninnervalgrind,aregressiontest<br> 251 producesoneadditionalfile<testname>.outer.logwhichcontainsthe<br> 252 errorsdetectedbytheoutervalgrind.E.g.foranoutermemcheck,it<br> 253 containstheleaksfoundintheinner,foranouterhelgrindordrd,<br> 254 itcontainsthedetectedraceconditions.<br> 255 <br> 256 Thefiletests/outer_inner.suppcontainssuppressionsfor<br> 257 theirrelevantorbenignerrorsfoundintheinner.<br> 258 <br> 259 Anregressiontestrunningintheinner(e.g.memcheck/tests/badrw)will<br> 260 causetheinnertoreportanerror,whichisexpectedandchecked<br> 261 asusualwhenrunningtheregtestsinanouter/innersetup.<br> 262 However,theouterwilloftenalsoobserveanerror,e.g.ajump<br> 263 usinguninitialiseddata,oraread/writeoutsidetheboundsofaheap<br> 264 block.Whentheouterreportssuchanerror,itwilloutputthe<br> 265 innerhoststacktrace.Tothisstacktrace,itwillappendthe<br> 266 stacktraceoftheinnerguestprogram.Forexample,thisisanerror<br> 267 reportedbytheouterwhentheinnerrunsthebadrwregtest:<br> 268 ==8119==Invalidreadofsize2<br> 269 ==8119==at0x7F2EFD7AF:???<br> 270 ==8119==by0x7F2C82EAF:???<br> 271 ==8119==by0x7F180867F:???<br> 272 ==8119==by0x40051D:main(badrw.c:5)<br> 273 ==8119==by0x7F180867F:???<br> 274 ==8119==by0x1BFF:???<br> 275 ==8119==by0x3803B7F0:_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______(m_execontext.c:332)<br> 276 ==8119==by0x40055C:main(badrw.c:22)<br> 277 ==8119==Address0x55cd03cis4bytesbeforeablockofsize16alloc'd<br> 278 ==8119==at0x2804E26D:vgPlain_arena_malloc(m_mallocfree.c:1914)<br> 279 ==8119==by0x2800BAB4:vgMemCheck_new_block(mc_malloc_wrappers.c:368)<br> 280 ==8119==by0x2800BC87:vgMemCheck_malloc(mc_malloc_wrappers.c:403)<br> 281 ==8119==by0x28097EAE:do_client_request(scheduler.c:1861)<br> 282 ==8119==by0x28097EAE:vgPlain_scheduler(scheduler.c:1425)<br> 283 ==8119==by0x280A7237:thread_wrapper(syswrap-linux.c:103)<br> 284 ==8119==by0x280A7237:run_a_thread_NORETURN(syswrap-linux.c:156)<br> 285 ==8119==by0x3803B7F0:_______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______(m_execontext.c:332)<br> 286 ==8119==by0x4C294C4:malloc(vg_replace_malloc.c:298)<br> 287 ==8119==by0x40051D:main(badrw.c:5)<br> 288 Intheabove,thefirststacktracestartswiththeinnerhoststacktrace,<br> 289 whichinthiscaseissomeJITtedcode.SuchcodesometimescontainsIPs<br> 290 thatpointsintheinnerguestcode(0x40051D:main(badrw.c:5)).<br> 291 Aftertheseparator,wehavetheinnergueststacktrace.<br> 292 Thesecondstacktracegivesthestacktracewheretheheapblockthatwas<br> 293 overrunwasallocated.Weseeitwasallocatedbytheinnervalgrind<br> 294 intheclientarena(firstpartofthestacktrace).Thesecondpartis<br> 295 thegueststacktracethatdidtheallocation.<br> 296 <br> 297 <br> 298 (C)Performancetestsinanouter/innersetup:<br> 299 <br> 300 Torunalltheperformancetestswithanoutercachegrind,do:<br> 301 perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrindperf<br> 302 <br> 303 Torunaspecificperftest(e.g.bz2)inthissetup,do:<br> 304 perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrindperf/bz2<br> 305 <br> 306 Torunalltheperformancetestswithanoutercallgrind,do:<br> 307 perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrind\<br> 308 --outer-tool=callgrindperf<br> 309 <br> 310 Note:--outer-valgrindmustbea"makeinstall"-edvalgrind.<br> 311 Do*not*usevg-in-place.<br> 312 <br> 313 TocomparetheperformanceofmultipleValgrindversions,do:<br> 314 perlperf/vg_perf--outer-valgrind=../outer/.../bin/valgrind\<br> 315 --outer-tool=callgrind\<br> 316 --vg=../inner_xxxx--vg=../inner_yyyyperf<br> 317 (whereinner_xxxxandinner_yyyyarethetopleveldirectoriesof<br> 318 theversionstocompare).<br> 319 Cachegrindandcg_diffareparticularlyhandytoobtainadelta<br> 320 betweenthetwoversions.<br> 321 <br> 322 Whentheoutertooliscallgrindorcachegrind,thefollowing<br> 323 outputfileswillbecreatedforeachtest:<br> 324 <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid><br> 325 <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid><br> 326 (wherettisthetwolettersabbreviationfortheinnertool(s)run).<br> 327 <br> 328 Forexample,thecommand<br> 329 perlperf/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> 334 producesthefiles<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> 345 Printingoutproblematicblocks<br> 346 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 347 Ifyouwanttoprintoutadisassemblyofaparticularblockthat<br> 348 causesacrash,dothefollowing.<br> 349 <br> 350 Tryrunningwith"--vex-guest-chase-thresh=0--trace-flags=10000000<br> 351 --trace-notbelow=999999".Thisshouldprintonelineforeachblock<br> 352 translated,andthatincludestheaddress.<br> 353 <br> 354 Thenre-runwith999999changedtothehighestbbnumbershown.<br> 355 Thiswillprinttheonelineperblock,andalsowillprinta<br> 356 disassemblyoftheblockinwhichthefaultoccurred.<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
