File: dist.readme-missing.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 (275 lines) | stat: -rw-r--r-- 12,735 bytes
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>5.README_MISSING_SYSCALL_OR_IOCTL</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.html" title="4.README">
<link rel="next" href="dist.readme-developers.html" title="6.README_DEVELOPERS">
</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.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-developers.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-missing"></a>5.README_MISSING_SYSCALL_OR_IOCTL</h1></div></div></div>
<div class="literallayout"><p><br>
<br>
DealingwithmissingsystemcallorioctlwrappersinValgrind<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
You'reprobablyreadingthisbecauseValgrindbombedoutwhilst<br>
runningyourprogram,andadvisedyoutoreadthisfile.Thegood<br>
newsisthat,ingeneral,it'seasytowritethemissingsyscallor<br>
ioctlwrappersyouneed,sothatyoucancontinueyourdebugging.If<br>
yousendtheresultingpatchestome,thenyou'llbedoingafavourto<br>
allfutureValgrinduserstoo.<br>
<br>
Notethatan"ioctl"isjustaspecialkindofsystemcall,really;so<br>
there'snotalotofneedtodistinguishthem(atleastconceptually)<br>
inthediscussionthatfollows.<br>
<br>
Allthismachineryisincoregrind/m_syswrap.<br>
<br>
<br>
Whataresyscall/ioctlwrappers?Whatdotheydo?<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Valgrinddoeswhatitdoes,inpart,bykeepingtrackofeverythingyour<br>
programdoes.Whenasystemcallhappens,forexamplearequesttoread<br>
partofafile,controlpassestotheLinuxkernel,whichfulfillsthe<br>
request,andreturnscontroltoyourprogram.Theproblemisthatthe<br>
kernelwilloftenchangethestatusofsomepartofyourprogram'smemory<br>
asaresult,andtools(instrumentationplug-ins)mayneedtoknowabout<br>
this.<br>
<br>
Syscallandioctlwrappershavetwojobs:<br>
<br>
1.Tellatoolwhat'sabouttohappen,beforethesyscalltakesplace.A<br>
toolcouldperformchecksbeforehand,eg.ifmemoryabouttobewritten<br>
isactuallywriteable.Thispartisuseful,butnotstrictly<br>
essential.<br>
<br>
2.Tellatoolwhatjusthappened,afterasyscalltakesplace.Thisis<br>
soitcanupdateitsviewoftheprogram'sstate,eg.thatmemoryhas<br>
justbeenwrittento.Thisstepisessential.<br>
<br>
The"happenings"mostlyinvolvereading/writingofmemory.<br>
<br>
So,let'slookatanexampleofawrapperforasystemcallwhich<br>
shouldbefamiliartomanyUnixprogrammers.<br>
<br>
<br>
Thesyscallwrapperfortime()<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
Thewrapperforthetimesystemcalllookslikethis:<br>
<br>
PRE(sys_time)<br>
{<br>
/*time_ttime(time_t*t);*/<br>
PRINT("sys_time(%p)",ARG1);<br>
PRE_REG_READ1(long,"time",int*,t);<br>
if(ARG1!=0){<br>
PRE_MEM_WRITE("time(t)",ARG1,sizeof(vki_time_t));<br>
}<br>
}<br>
<br>
POST(sys_time)<br>
{<br>
if(ARG1!=0){<br>
POST_MEM_WRITE(ARG1,sizeof(vki_time_t));<br>
}<br>
}<br>
<br>
Thefirstthingwedohappensbeforethesyscalloccurs,inthePRE()function.<br>
ThePRE()functiontypicallystartswithinvokingtothePRINT()macro.This<br>
PRINT()macroimplementssupportforthe--trace-syscallscommandlineoption.<br>
Next,thetoolistoldthereturntypeofthesyscall,thatthesyscallhas<br>
oneargument,thetypeofthesyscallargumentandthattheargumentisbeing<br>
readfromaregister:<br>
<br>
PRE_REG_READ1(long,"time",int*,t);<br>
<br>
Next,ifanon-NULLbufferispassedinastheargument,tellthetoolthatthe<br>
bufferisabouttobewrittento:<br>
<br>
if(ARG1!=0){<br>
PRE_MEM_WRITE("time",ARG1,sizeof(vki_time_t));<br>
}<br>
<br>
Finally,thereallyimportantbit,afterthesyscalloccurs,inthePOST()<br>
function:if,andonlyif,thesystemcallwassuccessful,tellthetoolthat<br>
thememorywaswritten:<br>
<br>
if(ARG1!=0){<br>
POST_MEM_WRITE(ARG1,sizeof(vki_time_t));<br>
}<br>
<br>
ThePOST()functionwon'tbecalledifthesyscallfailed,soyou<br>
don'tneedtoworryaboutcheckingthatinthePOST()function.<br>
(Note:thisissometimesabug;somesyscallsdoreturnresultswhen<br>
they"fail"-forexample,nanosleepreturnstheamountofunslept<br>
timeifinterrupted.TODO:addanotherper-syscallflagforthis<br>
case.)<br>
<br>
Notethatweusethetype'vki_time_t'.Thisisacopyofthekernel<br>
type,with'vki_'prefixed.Ourcopiesofsuchtypesarekeptinthe<br>
appropriatevki*.hfile(s).Wedon'tincludekernelheadersorglibcheaders<br>
directly.<br>
<br>
<br>
Writingyourownsyscallwrappers(seebelowforioctlwrappers)<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
IfValgrindtellsyouthatsystemcallNNNisunimplemented,dothe<br>
following:<br>
<br>
1.Findoutthenameofthesystemcall:<br>
<br>
grepNNN/usr/include/asm/unistd*.h<br>
<br>
Thisshouldtellyousomethinglike__NR_mysyscallname.<br>
Copythisentrytoinclude/vki/vki-scnums-$(VG_PLATFORM).h.<br>
<br>
<br>
2.Do'man2mysyscallname'togetsomeideaofwhatthesyscall<br>
does.Notethattheactualkernelinterfacecandifferfromthis,<br>
soyoumightalsowanttocheckaversionoftheLinuxkernel<br>
source.<br>
<br>
NOTE:anysyscallwhichhassomethingtodowithsignalsor<br>
threadsisprobably"special",andneedsmorecarefulhandling.<br>
Postsomethingtovalgrind-developersifyouaren'tsure.<br>
<br>
<br>
3.Addacasetothealready-hugecollectionofwrappersin<br>
thecoregrind/m_syswrap/syswrap-*.cfiles.<br>
Foreachin-memoryparameterwhichisreadorwrittenby<br>
thesyscall,dooneof<br>
<br>
PRE_MEM_READ(...)<br>
PRE_MEM_RASCIIZ(...)<br>
PRE_MEM_WRITE(...)<br>
<br>
forthatparameter.Thendothesyscall.Then,ifthesyscall<br>
succeeds,issuesuitablePOST_MEM_WRITE(...)calls.<br>
(There'snoneedforPOST_MEM_READcalls.)<br>
<br>
Also,addittothesyscall_table[]array;useoneofGENX_,GENXY<br>
LINX_,LINXY,PLAX_,PLAXY.<br>
GEN*forgenericsyscalls(insyswrap-generic.c),LIN*forlinux<br>
specificones(insyswrap-linux.c)andPLA*fortheplatform<br>
dependentones(insyswrap-$(PLATFORM)-linux.c).<br>
The*XYvariantifitrequiresaPRE()andPOST()function,and<br>
the*X_variantifitonlyrequiresaPRE()<br>
function.<br>
<br>
Ifyoufindthisdifficult,readthewrappersforothersyscalls<br>
forideas.Agoodtipistolookforthewrapperforasyscall<br>
whichhasasimilarbehaviourtoyours,anduseitasa<br>
startingpoint.<br>
<br>
Ifyouneedstructuredefinitionsand/orconstantsforyoursyscall,<br>
copythemfromthekernelheadersintoinclude/vki.handco.,with<br>
theappropriatevki_*/VKI_*namemangling.Don't#includeany<br>
kernelheaders.Andcertainlydon't#includeanyglibcheaders.<br>
<br>
Testit.<br>
<br>
NotethatacommonerroristocallPOST_MEM_WRITE(...)<br>
with0(NULL)asthefirst(address)argument.Thisusuallymeans<br>
yourlogicisslightlyinadequate.It'sasufficientlycommonbug<br>
thatthere'sabuilt-incheckforit,andyou'llgeta"probably<br>
sanitycheckfailure"forthesyscallwrapperyoujustmade,ifthis<br>
isthecase.<br>
<br>
<br>
4.Oncehappy,sendusthepatch.Prettyplease.<br>
<br>
<br>
<br>
<br>
Writingyourownioctlwrappers<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
<br>
Isprettymuchthesameaswritingsyscallwrappers,exceptthatall<br>
theactionhappenswithinPRE(ioctl)andPOST(ioctl).<br>
<br>
There'sadefaultcase,sometimesitisn'tcorrectandyouhavetowritea<br>
morespecificcasetogettherightbehaviour.<br>
<br>
Asabove,pleasecreateabugreportandattachthepatchasdescribed<br>
onhttp://www.valgrind.org.<br>
<br>
<br>
Writingyourowndoorcallwrappers(Solarisonly)<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
<br>
Unlikesyscallsorioctls,doorcallstransferdatabetweentwouserspace<br>
programs,albeitthroughakernelinterface.Programsmayusecompletely<br>
proprietarysemanticsinthedatabufferspassedbetweenthem.<br>
Thereforeitmaynotbepossibletocapturethesesemanticswithin<br>
aValgrinddoorcallordoorreturnwrapper.<br>
<br>
Nevertheless,forsystemorwell-knowndoorservicesitwouldbebeneficial<br>
tohaveadoorcallandadoorreturnwrapper.Writingsuchwrapperispretty<br>
muchthesameaswritingioctlwrappers.Pleasetakeafewmomentstostudy<br>
thefollowingpicturedepictinghowadoorclientandadoorserverinteract<br>
throughthekernelinterfaceinatypicalscenario:<br>
<br>
<br>
doorclientthreadkerneldoorserverthread<br>
invokesdoor_call()invokesdoor_return()<br>
-------------------------------------------------------------------<br>
&lt;----PRE(sys_door,DOOR_RETURN)<br>
PRE(sys_door,DOOR_CALL)---&gt;<br>
----&gt;POST(sys_door,DOOR_RETURN)<br>
----&gt;server_procedure()<br>
&lt;----<br>
&lt;----PRE(sys_door,DOOR_RETURN)<br>
POST(sys_door,DOOR_CALL)&lt;---<br>
<br>
ThefirstPRE(sys_door,DOOR_RETURN)isinvokedwithdata_ptr=NULL<br>
anddata_size=0.That'sbecauseithasnotreceivedanydatafrom<br>
adoorcall,yet.<br>
<br>
Semanticsaredescribedbythefollowingfunctions<br>
incoregring/m_syswrap/syswrap-solaris.cmodule:<br>
oForadoorcallwrapperthefollowingattributesof'params'argument:<br>
-data_ptr(andassociateddata_size)asinputbuffer(request);<br>
describedindoor_call_pre_mem_params_data()<br>
-rbuf(andassociatedrsize)asoutputbuffer(response);<br>
describedindoor_call_post_mem_params_rbuf()<br>
oForadoorreturnwrapperthefollowingparameters:<br>
-data_ptr(andassociateddata_size)asinputbuffer(request);<br>
describedindoor_return_post_mem_data()<br>
-data_ptr(andassociateddata_size)asoutputbuffer(response);<br>
describedindoor_return_pre_mem_data()<br>
<br>
There'sadefaultcasewhichmaynotbecorrectandyouhavetowritea<br>
morespecificcasetogettherightbehaviour.UnlessValgrind'soption<br>
'--sim-hints=lax-doors'isspecified,thedefaultcasealsospitsawarning.<br>
<br>
Asabove,pleasecreateabugreportandattachthepatchasdescribed<br>
onhttp://www.valgrind.org.<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.html">&lt;&lt;4.README</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-developers.html">6.README_DEVELOPERS&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>