1 <html> 2 <head> 3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4 <title>5.README_MISSING_SYSCALL_OR_IOCTL</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.html" title="4.README"> 10 <link rel="next" href="dist.readme-developers.html" title="6.README_DEVELOPERS"> 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.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-developers.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-missing"></a>5.README_MISSING_SYSCALL_OR_IOCTL</h1></div></div></div> 23 <div class="literallayout"><p><br> 24 <br> 25 DealingwithmissingsystemcallorioctlwrappersinValgrind<br> 26 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 27 You'reprobablyreadingthisbecauseValgrindbombedoutwhilst<br> 28 runningyourprogram,andadvisedyoutoreadthisfile.Thegood<br> 29 newsisthat,ingeneral,it'seasytowritethemissingsyscallor<br> 30 ioctlwrappersyouneed,sothatyoucancontinueyourdebugging.If<br> 31 yousendtheresultingpatchestome,thenyou'llbedoingafavourto<br> 32 allfutureValgrinduserstoo.<br> 33 <br> 34 Notethatan"ioctl"isjustaspecialkindofsystemcall,really;so<br> 35 there'snotalotofneedtodistinguishthem(atleastconceptually)<br> 36 inthediscussionthatfollows.<br> 37 <br> 38 Allthismachineryisincoregrind/m_syswrap.<br> 39 <br> 40 <br> 41 Whataresyscall/ioctlwrappers?Whatdotheydo?<br> 42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 43 Valgrinddoeswhatitdoes,inpart,bykeepingtrackofeverythingyour<br> 44 programdoes.Whenasystemcallhappens,forexamplearequesttoread<br> 45 partofafile,controlpassestotheLinuxkernel,whichfulfillsthe<br> 46 request,andreturnscontroltoyourprogram.Theproblemisthatthe<br> 47 kernelwilloftenchangethestatusofsomepartofyourprogram'smemory<br> 48 asaresult,andtools(instrumentationplug-ins)mayneedtoknowabout<br> 49 this.<br> 50 <br> 51 Syscallandioctlwrappershavetwojobs:<br> 52 <br> 53 1.Tellatoolwhat'sabouttohappen,beforethesyscalltakesplace.A<br> 54 toolcouldperformchecksbeforehand,eg.ifmemoryabouttobewritten<br> 55 isactuallywriteable.Thispartisuseful,butnotstrictly<br> 56 essential.<br> 57 <br> 58 2.Tellatoolwhatjusthappened,afterasyscalltakesplace.Thisis<br> 59 soitcanupdateitsviewoftheprogram'sstate,eg.thatmemoryhas<br> 60 justbeenwrittento.Thisstepisessential.<br> 61 <br> 62 The"happenings"mostlyinvolvereading/writingofmemory.<br> 63 <br> 64 So,let'slookatanexampleofawrapperforasystemcallwhich<br> 65 shouldbefamiliartomanyUnixprogrammers.<br> 66 <br> 67 <br> 68 Thesyscallwrapperfortime()<br> 69 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 70 Thewrapperforthetimesystemcalllookslikethis:<br> 71 <br> 72 PRE(sys_time)<br> 73 {<br> 74 /*time_ttime(time_t*t);*/<br> 75 PRINT("sys_time(%p)",ARG1);<br> 76 PRE_REG_READ1(long,"time",int*,t);<br> 77 if(ARG1!=0){<br> 78 PRE_MEM_WRITE("time(t)",ARG1,sizeof(vki_time_t));<br> 79 }<br> 80 }<br> 81 <br> 82 POST(sys_time)<br> 83 {<br> 84 if(ARG1!=0){<br> 85 POST_MEM_WRITE(ARG1,sizeof(vki_time_t));<br> 86 }<br> 87 }<br> 88 <br> 89 Thefirstthingwedohappensbeforethesyscalloccurs,inthePRE()function.<br> 90 ThePRE()functiontypicallystartswithinvokingtothePRINT()macro.This<br> 91 PRINT()macroimplementssupportforthe--trace-syscallscommandlineoption.<br> 92 Next,thetoolistoldthereturntypeofthesyscall,thatthesyscallhas<br> 93 oneargument,thetypeofthesyscallargumentandthattheargumentisbeing<br> 94 readfromaregister:<br> 95 <br> 96 PRE_REG_READ1(long,"time",int*,t);<br> 97 <br> 98 Next,ifanon-NULLbufferispassedinastheargument,tellthetoolthatthe<br> 99 bufferisabouttobewrittento:<br> 100 <br> 101 if(ARG1!=0){<br> 102 PRE_MEM_WRITE("time",ARG1,sizeof(vki_time_t));<br> 103 }<br> 104 <br> 105 Finally,thereallyimportantbit,afterthesyscalloccurs,inthePOST()<br> 106 function:if,andonlyif,thesystemcallwassuccessful,tellthetoolthat<br> 107 thememorywaswritten:<br> 108 <br> 109 if(ARG1!=0){<br> 110 POST_MEM_WRITE(ARG1,sizeof(vki_time_t));<br> 111 }<br> 112 <br> 113 ThePOST()functionwon'tbecalledifthesyscallfailed,soyou<br> 114 don'tneedtoworryaboutcheckingthatinthePOST()function.<br> 115 (Note:thisissometimesabug;somesyscallsdoreturnresultswhen<br> 116 they"fail"-forexample,nanosleepreturnstheamountofunslept<br> 117 timeifinterrupted.TODO:addanotherper-syscallflagforthis<br> 118 case.)<br> 119 <br> 120 Notethatweusethetype'vki_time_t'.Thisisacopyofthekernel<br> 121 type,with'vki_'prefixed.Ourcopiesofsuchtypesarekeptinthe<br> 122 appropriatevki*.hfile(s).Wedon'tincludekernelheadersorglibcheaders<br> 123 directly.<br> 124 <br> 125 <br> 126 Writingyourownsyscallwrappers(seebelowforioctlwrappers)<br> 127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 128 IfValgrindtellsyouthatsystemcallNNNisunimplemented,dothe<br> 129 following:<br> 130 <br> 131 1.Findoutthenameofthesystemcall:<br> 132 <br> 133 grepNNN/usr/include/asm/unistd*.h<br> 134 <br> 135 Thisshouldtellyousomethinglike__NR_mysyscallname.<br> 136 Copythisentrytoinclude/vki/vki-scnums-$(VG_PLATFORM).h.<br> 137 <br> 138 <br> 139 2.Do'man2mysyscallname'togetsomeideaofwhatthesyscall<br> 140 does.Notethattheactualkernelinterfacecandifferfromthis,<br> 141 soyoumightalsowanttocheckaversionoftheLinuxkernel<br> 142 source.<br> 143 <br> 144 NOTE:anysyscallwhichhassomethingtodowithsignalsor<br> 145 threadsisprobably"special",andneedsmorecarefulhandling.<br> 146 Postsomethingtovalgrind-developersifyouaren'tsure.<br> 147 <br> 148 <br> 149 3.Addacasetothealready-hugecollectionofwrappersin<br> 150 thecoregrind/m_syswrap/syswrap-*.cfiles.<br> 151 Foreachin-memoryparameterwhichisreadorwrittenby<br> 152 thesyscall,dooneof<br> 153 <br> 154 PRE_MEM_READ(...)<br> 155 PRE_MEM_RASCIIZ(...)<br> 156 PRE_MEM_WRITE(...)<br> 157 <br> 158 forthatparameter.Thendothesyscall.Then,ifthesyscall<br> 159 succeeds,issuesuitablePOST_MEM_WRITE(...)calls.<br> 160 (There'snoneedforPOST_MEM_READcalls.)<br> 161 <br> 162 Also,addittothesyscall_table[]array;useoneofGENX_,GENXY<br> 163 LINX_,LINXY,PLAX_,PLAXY.<br> 164 GEN*forgenericsyscalls(insyswrap-generic.c),LIN*forlinux<br> 165 specificones(insyswrap-linux.c)andPLA*fortheplatform<br> 166 dependentones(insyswrap-$(PLATFORM)-linux.c).<br> 167 The*XYvariantifitrequiresaPRE()andPOST()function,and<br> 168 the*X_variantifitonlyrequiresaPRE()<br> 169 function.<br> 170 <br> 171 Ifyoufindthisdifficult,readthewrappersforothersyscalls<br> 172 forideas.Agoodtipistolookforthewrapperforasyscall<br> 173 whichhasasimilarbehaviourtoyours,anduseitasa<br> 174 startingpoint.<br> 175 <br> 176 Ifyouneedstructuredefinitionsand/orconstantsforyoursyscall,<br> 177 copythemfromthekernelheadersintoinclude/vki.handco.,with<br> 178 theappropriatevki_*/VKI_*namemangling.Don't#includeany<br> 179 kernelheaders.Andcertainlydon't#includeanyglibcheaders.<br> 180 <br> 181 Testit.<br> 182 <br> 183 NotethatacommonerroristocallPOST_MEM_WRITE(...)<br> 184 with0(NULL)asthefirst(address)argument.Thisusuallymeans<br> 185 yourlogicisslightlyinadequate.It'sasufficientlycommonbug<br> 186 thatthere'sabuilt-incheckforit,andyou'llgeta"probably<br> 187 sanitycheckfailure"forthesyscallwrapperyoujustmade,ifthis<br> 188 isthecase.<br> 189 <br> 190 <br> 191 4.Oncehappy,sendusthepatch.Prettyplease.<br> 192 <br> 193 <br> 194 <br> 195 <br> 196 Writingyourownioctlwrappers<br> 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 198 <br> 199 Isprettymuchthesameaswritingsyscallwrappers,exceptthatall<br> 200 theactionhappenswithinPRE(ioctl)andPOST(ioctl).<br> 201 <br> 202 There'sadefaultcase,sometimesitisn'tcorrectandyouhavetowritea<br> 203 morespecificcasetogettherightbehaviour.<br> 204 <br> 205 Asabove,pleasecreateabugreportandattachthepatchasdescribed<br> 206 onhttp://www.valgrind.org.<br> 207 <br> 208 <br> 209 Writingyourowndoorcallwrappers(Solarisonly)<br> 210 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 211 <br> 212 Unlikesyscallsorioctls,doorcallstransferdatabetweentwouserspace<br> 213 programs,albeitthroughakernelinterface.Programsmayusecompletely<br> 214 proprietarysemanticsinthedatabufferspassedbetweenthem.<br> 215 Thereforeitmaynotbepossibletocapturethesesemanticswithin<br> 216 aValgrinddoorcallordoorreturnwrapper.<br> 217 <br> 218 Nevertheless,forsystemorwell-knowndoorservicesitwouldbebeneficial<br> 219 tohaveadoorcallandadoorreturnwrapper.Writingsuchwrapperispretty<br> 220 muchthesameaswritingioctlwrappers.Pleasetakeafewmomentstostudy<br> 221 thefollowingpicturedepictinghowadoorclientandadoorserverinteract<br> 222 throughthekernelinterfaceinatypicalscenario:<br> 223 <br> 224 <br> 225 doorclientthreadkerneldoorserverthread<br> 226 invokesdoor_call()invokesdoor_return()<br> 227 -------------------------------------------------------------------<br> 228 <----PRE(sys_door,DOOR_RETURN)<br> 229 PRE(sys_door,DOOR_CALL)---><br> 230 ---->POST(sys_door,DOOR_RETURN)<br> 231 ---->server_procedure()<br> 232 <----<br> 233 <----PRE(sys_door,DOOR_RETURN)<br> 234 POST(sys_door,DOOR_CALL)<---<br> 235 <br> 236 ThefirstPRE(sys_door,DOOR_RETURN)isinvokedwithdata_ptr=NULL<br> 237 anddata_size=0.That'sbecauseithasnotreceivedanydatafrom<br> 238 adoorcall,yet.<br> 239 <br> 240 Semanticsaredescribedbythefollowingfunctions<br> 241 incoregring/m_syswrap/syswrap-solaris.cmodule:<br> 242 oForadoorcallwrapperthefollowingattributesof'params'argument:<br> 243 -data_ptr(andassociateddata_size)asinputbuffer(request);<br> 244 describedindoor_call_pre_mem_params_data()<br> 245 -rbuf(andassociatedrsize)asoutputbuffer(response);<br> 246 describedindoor_call_post_mem_params_rbuf()<br> 247 oForadoorreturnwrapperthefollowingparameters:<br> 248 -data_ptr(andassociateddata_size)asinputbuffer(request);<br> 249 describedindoor_return_post_mem_data()<br> 250 -data_ptr(andassociateddata_size)asoutputbuffer(response);<br> 251 describedindoor_return_pre_mem_data()<br> 252 <br> 253 There'sadefaultcasewhichmaynotbecorrectandyouhavetowritea<br> 254 morespecificcasetogettherightbehaviour.UnlessValgrind'soption<br> 255 '--sim-hints=lax-doors'isspecified,thedefaultcasealsospitsawarning.<br> 256 <br> 257 Asabove,pleasecreateabugreportandattachthepatchasdescribed<br> 258 onhttp://www.valgrind.org.<br> 259 <br> 260 </p></div> 261 </div> 262 <div> 263 <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 264 <tr> 265 <td rowspan="2" width="40%" align="left"> 266 <a accesskey="p" href="dist.readme.html"><<4.README</a></td> 267 <td width="20%" align="center"><a accesskey="u" href="dist.html">Up</a></td> 268 <td rowspan="2" width="40%" align="right"><a accesskey="n" href="dist.readme-developers.html">6.README_DEVELOPERS>></a> 269 </td> 270 </tr> 271 <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 272 </table> 273 </div> 274 </body> 275 </html> 276
