README_MISSING_SYSCALL_OR_IOCTL

   1
   2 Dealing with missing system call or ioctl wrappers in Valgrind
   3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4 You're probably reading this because Valgrind bombed out whilst
   5 running your program, and advised you to read this file.  The good
   6 news is that, in general, it's easy to write the missing syscall or
   7 ioctl wrappers you need, so that you can continue your debugging.  If
   8 you send the resulting patches to me, then you'll be doing a favour to
   9 all future Valgrind users too.
  10
  11 Note that an "ioctl" is just a special kind of system call, really; so
  12 there's not a lot of need to distinguish them (at least conceptually)
  13 in the discussion that follows.
  14
  15 All this machinery is in coregrind/m_syswrap.
  16
  17
  18 What are syscall/ioctl wrappers?  What do they do?
  19 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20 Valgrind does what it does, in part, by keeping track of everything your
  21 program does.  When a system call happens, for example a request to read
  22 part of a file, control passes to the Linux kernel, which fulfills the
  23 request, and returns control to your program.  The problem is that the
  24 kernel will often change the status of some part of your program's memory
  25 as a result, and tools (instrumentation plug-ins) may need to know about
  26 this.
  27
  28 Syscall and ioctl wrappers have two jobs:
  29
  30 1. Tell a tool what's about to happen, before the syscall takes place.  A
  31    tool could perform checks beforehand, eg. if memory about to be written
  32    is actually writeable.  This part is useful, but not strictly
  33    essential.
  34
  35 2. Tell a tool what just happened, after a syscall takes place.  This is
  36    so it can update its view of the program's state, eg. that memory has
  37    just been written to.  This step is essential.
  38
  39 The "happenings" mostly involve reading/writing of memory.
  40
  41 So, let's look at an example of a wrapper for a system call which
  42 should be familiar to many Unix programmers.
  43
  44
  45 The syscall wrapper for time()
  46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  47 The wrapper for the time system call looks like this:
  48
  49   PRE(sys_time)
  50   {
  51      /* time_t time(time_t *t); */
  52      PRINT("sys_time ( %p )",ARG1);
  53      PRE_REG_READ1(long, "time", int *, t);
  54      if (ARG1 != 0) {
  55         PRE_MEM_WRITE( "time(t)", ARG1, sizeof(vki_time_t) );
  56      }
  57   }
  58
  59   POST(sys_time)
  60   {
  61      if (ARG1 != 0) {
  62         POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
  63      }
  64   }
  65
  66 The first thing we do happens before the syscall occurs, in the PRE() function.
  67 The PRE() function typically starts with invoking to the PRINT() macro. This
  68 PRINT() macro implements support for the --trace-syscalls command line option.
  69 Next, the tool is told the return type of the syscall, that the syscall has
  70 one argument, the type of the syscall argument and that the argument is being
  71 read from a register:
  72
  73      PRE_REG_READ1(long, "time", int *, t);
  74
  75 Next, if a non-NULL buffer is passed in as the argument, tell the tool that the
  76 buffer is about to be written to:
  77
  78      if (ARG1 != 0) {
  79         PRE_MEM_WRITE( "time", ARG1, sizeof(vki_time_t) );
  80      }
  81
  82 Finally, the really important bit, after the syscall occurs, in the POST()
  83 function:  if, and only if, the system call was successful, tell the tool that
  84 the memory was written:
  85
  86      if (ARG1 != 0) {
  87         POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
  88      }
  89
  90 The POST() function won't be called if the syscall failed, so you
  91 don't need to worry about checking that in the POST() function.
  92 (Note: this is sometimes a bug; some syscalls do return results when
  93 they "fail" - for example, nanosleep returns the amount of unslept
  94 time if interrupted. TODO: add another per-syscall flag for this
  95 case.)
  96
  97 Note that we use the type 'vki_time_t'.  This is a copy of the kernel
  98 type, with 'vki_' prefixed.  Our copies of such types are kept in the
  99 appropriate vki*.h file(s).  We don't include kernel headers or glibc headers
 100 directly.
 101
 102
 103 Writing your own syscall wrappers (see below for ioctl wrappers)
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105 If Valgrind tells you that system call NNN is unimplemented, do the
 106 following:
 107
 108 1.  Find out the name of the system call:
 109
 110        grep NNN /usr/include/asm/unistd*.h
 111
 112     This should tell you something like  __NR_mysyscallname.
 113     Copy this entry to include/vki/vki-scnums-$(VG_PLATFORM).h.
 114
 115     If you can't find the system call in /usr/include, try looking in the
 116     strace source code (https://github.com/strace/strace). Some syscalls/ioctls
 117     are not defined explicitly, but strace may have already figured it out.
 118
 119
 120 2.  Do 'man 2 mysyscallname' to get some idea of what the syscall
 121     does.  Note that the actual kernel interface can differ from this,
 122     so you might also want to check a version of the Linux kernel
 123     source.
 124
 125     NOTE: any syscall which has something to do with signals or
 126     threads is probably "special", and needs more careful handling.
 127     Post something to valgrind-developers if you aren't sure.
 128
 129
 130 3.  Add a case to the already-huge collection of wrappers in
 131     the coregrind/m_syswrap/syswrap-*.c files.
 132     For each in-memory parameter which is read or written by
 133     the syscall, do one of
 134
 135       PRE_MEM_READ( ... )
 136       PRE_MEM_RASCIIZ( ... )
 137       PRE_MEM_WRITE( ... )
 138
 139     for  that parameter.  Then do the syscall.  Then, if the syscall
 140     succeeds, issue suitable POST_MEM_WRITE( ... ) calls.
 141     (There's no need for POST_MEM_READ calls.)
 142
 143     Also, add it to the syscall_table[] array; use one of GENX_, GENXY
 144     LINX_, LINXY, PLAX_, PLAXY.
 145     GEN* for generic syscalls (in syswrap-generic.c), LIN* for linux
 146     specific ones (in syswrap-linux.c) and PLA* for the platform
 147     dependent ones (in syswrap-$(PLATFORM)-linux.c).
 148     The *XY variant if it requires a PRE() and POST() function, and
 149     the *X_ variant if it only requires a PRE()
 150     function.
 151
 152     If you find this difficult, read the wrappers for other syscalls
 153     for ideas.  A good tip is to look for the wrapper for a syscall
 154     which has a similar behaviour to yours, and use it as a
 155     starting point.
 156
 157     If you need structure definitions and/or constants for your syscall,
 158     copy them from the kernel headers into include/vki.h and co., with
 159     the appropriate vki_*/VKI_* name mangling.  Don't #include any
 160     kernel headers.  And certainly don't #include any glibc headers.
 161
 162     Test it.
 163
 164     Note that a common error is to call POST_MEM_WRITE( ... )
 165     with 0 (NULL) as the first (address) argument.  This usually means
 166     your logic is slightly inadequate.  It's a sufficiently common bug
 167     that there's a built-in check for it, and you'll get a "probably
 168     sanity check failure" for the syscall wrapper you just made, if this
 169     is the case.
 170
 171
 172 4.  Once happy, send us the patch.  Pretty please.
 173
 174
 175
 176
 177 Writing your own ioctl wrappers
 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 179
 180 Is pretty much the same as writing syscall wrappers, except that all
 181 the action happens within PRE(ioctl) and POST(ioctl).
 182
 183 There's a default case, sometimes it isn't correct and you have to write a
 184 more specific case to get the right behaviour.
 185
 186 As above, please create a bug report and attach the patch as described
 187 on http://www.valgrind.org.
 188
 189
 190 Writing your own door call wrappers (Solaris only)
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192
 193 Unlike syscalls or ioctls, door calls transfer data between two userspace
 194 programs, albeit through a kernel interface. Programs may use completely
 195 proprietary semantics in the data buffers passed between them.
 196 Therefore it may not be possible to capture these semantics within
 197 a Valgrind door call or door return wrapper.
 198
 199 Nevertheless, for system or well-known door services it would be beneficial
 200 to have a door call and a door return wrapper. Writing such wrapper is pretty
 201 much the same as writing ioctl wrappers. Please take a few moments to study
 202 the following picture depicting how a door client and a door server interact
 203 through the kernel interface in a typical scenario:
 204
 205
 206 door client thread          kernel       door server thread
 207 invokes door_call()                     invokes door_return()
 208 -------------------------------------------------------------------
 209                                <----  PRE(sys_door, DOOR_RETURN)
 210 PRE(sys_door, DOOR_CALL)  --->
 211                                ---->  POST(sys_door, DOOR_RETURN)
 212                                            ----> server_procedure()
 213                                            <----
 214                                <----  PRE(sys_door, DOOR_RETURN)
 215 POST(sys_door, DOOR_CALL) <---
 216
 217 The first PRE(sys_door, DOOR_RETURN) is invoked with data_ptr=NULL
 218 and data_size=0. That's because it has not received any data from
 219 a door call, yet.
 220
 221 Semantics are described by the following functions
 222 in coregring/m_syswrap/syswrap-solaris.c module:
 223 o For a door call wrapper the following attributes of 'params' argument:
 224   - data_ptr (and associated data_size) as input buffer (request);
 225       described in door_call_pre_mem_params_data()
 226   - rbuf (and associated rsize) as output buffer (response);
 227       described in door_call_post_mem_params_rbuf()
 228 o For a door return wrapper the following parameters:
 229   - data_ptr (and associated data_size) as input buffer (request);
 230       described in door_return_post_mem_data()
 231   - data_ptr (and associated data_size) as output buffer (response);
 232       described in door_return_pre_mem_data()
 233
 234 There's a default case which may not be correct and you have to write a
 235 more specific case to get the right behaviour. Unless Valgrind's option
 236 '--sim-hints=lax-doors' is specified, the default case also spits a warning.
 237
 238 As above, please create a bug report and attach the patch as described
 239 on http://www.valgrind.org.