sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 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 | |
tom | 645de78 | 2005-10-05 08:27:08 +0000 | [diff] [blame] | 15 | All this machinery is in coregrind/m_syswrap. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 16 | |
| 17 | |
| 18 | What are syscall/ioctl wrappers? What do they do? |
| 19 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 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 |
nethercote | 137bc55 | 2003-11-14 17:47:54 +0000 | [diff] [blame] | 25 | as a result, and tools (instrumentation plug-ins) may need to know about |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 26 | this. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 27 | |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 28 | Syscall and ioctl wrappers have two jobs: |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 29 | |
nethercote | 137bc55 | 2003-11-14 17:47:54 +0000 | [diff] [blame] | 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 |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 32 | is actually writeable. This part is useful, but not strictly |
| 33 | essential. |
| 34 | |
nethercote | 137bc55 | 2003-11-14 17:47:54 +0000 | [diff] [blame] | 35 | 2. Tell a tool what just happened, after a syscall takes place. This is |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 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. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 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 | |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 45 | The syscall wrapper for time() |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 46 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 47 | The wrapper for the time system call looks like this: |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 48 | |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 49 | PRE(sys_time) |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 50 | { |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 51 | /* time_t time(time_t *t); */ |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 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) ); |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 56 | } |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 57 | } |
| 58 | |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 59 | POST(sys_time) |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 60 | { |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 61 | if (ARG1 != 0) { |
| 62 | POST_MEM_WRITE( ARG1, sizeof(vki_time_t) ); |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 63 | } |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 64 | } |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 65 | |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 66 | The first thing we do happens before the syscall occurs, in the PRE() function: |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 67 | tell the tool the return type of the syscall, that the syscall has one |
| 68 | argument, the type of the argument and that the argument is being read from a |
| 69 | register: |
| 70 | |
| 71 | PRE_REG_READ1(long, "time", int *, t); |
| 72 | |
| 73 | Next, if a non-NULL buffer is passed in as the argument, tell the tool that the |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 74 | buffer is about to be written to: |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 75 | |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 76 | if (ARG1 != 0) { |
| 77 | PRE_MEM_WRITE( "time", ARG1, sizeof(vki_time_t) ); |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 78 | } |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 79 | |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 80 | Finally, the really important bit, after the syscall occurs, in the POST() |
| 81 | function: if, and only if, the system call was successful, tell the tool that |
| 82 | the memory was written: |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 83 | |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 84 | if (ARG1 != 0) { |
| 85 | POST_MEM_WRITE( ARG1, sizeof(vki_time_t) ); |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 86 | } |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 87 | |
fitzhardinge | 603e8c5 | 2004-01-19 22:02:43 +0000 | [diff] [blame] | 88 | The POST() function won't be called if the syscall failed, so you |
| 89 | don't need to worry about checking that in the POST() function. |
| 90 | (Note: this is sometimes a bug; some syscalls do return results when |
| 91 | they "fail" - for example, nanosleep returns the amount of unslept |
| 92 | time if interrupted. TODO: add another per-syscall flag for this |
| 93 | case.) |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 94 | |
nethercote | ef0c766 | 2004-11-06 15:38:43 +0000 | [diff] [blame] | 95 | Note that we use the type 'vki_time_t'. This is a copy of the kernel |
| 96 | type, with 'vki_' prefixed. Our copies of such types are kept in the |
| 97 | appropriate vki*.h file(s). We don't include kernel headers or glibc headers |
| 98 | directly. |
| 99 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 100 | |
| 101 | Writing your own syscall wrappers (see below for ioctl wrappers) |
| 102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 103 | If Valgrind tells you that system call NNN is unimplemented, do the |
| 104 | following: |
| 105 | |
| 106 | 1. Find out the name of the system call: |
| 107 | |
| 108 | grep NNN /usr/include/asm/unistd.h |
| 109 | |
| 110 | This should tell you something like __NR_mysyscallname. |
njn | 71043fe | 2007-03-10 00:52:54 +0000 | [diff] [blame] | 111 | Copy this entry to include/vki/vki-scnums-$(VG_PLATFORM).h. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 112 | |
nethercote | ef0c766 | 2004-11-06 15:38:43 +0000 | [diff] [blame] | 113 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 114 | 2. Do 'man 2 mysyscallname' to get some idea of what the syscall |
fitzhardinge | 603e8c5 | 2004-01-19 22:02:43 +0000 | [diff] [blame] | 115 | does. Note that the actual kernel interface can differ from this, |
| 116 | so you might also want to check a version of the Linux kernel |
| 117 | source. |
| 118 | |
| 119 | NOTE: any syscall which has something to do with signals or |
| 120 | threads is probably "special", and needs more careful handling. |
| 121 | Post something to valgrind-developers if you aren't sure. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 122 | |
| 123 | |
| 124 | 3. Add a case to the already-huge collection of wrappers in |
tom | 645de78 | 2005-10-05 08:27:08 +0000 | [diff] [blame] | 125 | the coregrind/m_syswrap/syswrap-*.c files. |
| 126 | For each in-memory parameter which is read or written by |
| 127 | the syscall, do one of |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 128 | |
nethercote | ef0c766 | 2004-11-06 15:38:43 +0000 | [diff] [blame] | 129 | PRE_MEM_READ( ... ) |
| 130 | PRE_MEM_RASCIIZ( ... ) |
| 131 | PRE_MEM_WRITE( ... ) |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 132 | |
| 133 | for that parameter. Then do the syscall. Then, if the syscall |
nethercote | ef0c766 | 2004-11-06 15:38:43 +0000 | [diff] [blame] | 134 | succeeds, issue suitable POST_MEM_WRITE( ... ) calls. |
| 135 | (There's no need for POST_MEM_READ calls.) |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 136 | |
tom | 645de78 | 2005-10-05 08:27:08 +0000 | [diff] [blame] | 137 | Also, add it to the syscall_table[] array; use one of GENX_, GENXY |
| 138 | LINX_, LINXY, PLAX_, PLAXY. |
| 139 | GEN* for generic syscalls (in syswrap-generic.c), LIN* for linux |
| 140 | specific ones (in syswrap-linux.c) and PLA* for the platform |
| 141 | dependant ones (in syswrap-$(PLATFORM)-linux.c). |
| 142 | The *XY variant if it requires a PRE() and POST() function, and |
| 143 | the *X_ variant if it only requires a PRE() |
bart | f477549 | 2008-04-26 10:47:29 +0000 | [diff] [blame] | 144 | function. |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 145 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 146 | If you find this difficult, read the wrappers for other syscalls |
| 147 | for ideas. A good tip is to look for the wrapper for a syscall |
| 148 | which has a similar behaviour to yours, and use it as a |
| 149 | starting point. |
| 150 | |
nethercote | 73b526f | 2004-10-31 18:48:21 +0000 | [diff] [blame] | 151 | If you need structure definitions and/or constants for your syscall, |
| 152 | copy them from the kernel headers into include/vki.h and co., with |
| 153 | the appropriate vki_*/VKI_* name mangling. Don't #include any |
| 154 | kernel headers. And certainly don't #include any glibc headers. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 155 | |
| 156 | Test it. |
| 157 | |
nethercote | ef0c766 | 2004-11-06 15:38:43 +0000 | [diff] [blame] | 158 | Note that a common error is to call POST_MEM_WRITE( ... ) |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 159 | with 0 (NULL) as the first (address) argument. This usually means |
| 160 | your logic is slightly inadequate. It's a sufficiently common bug |
| 161 | that there's a built-in check for it, and you'll get a "probably |
| 162 | sanity check failure" for the syscall wrapper you just made, if this |
| 163 | is the case. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 164 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 165 | |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 166 | 4. Once happy, send us the patch. Pretty please. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 167 | |
| 168 | |
| 169 | |
| 170 | |
| 171 | Writing your own ioctl wrappers |
| 172 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
fitzhardinge | 603e8c5 | 2004-01-19 22:02:43 +0000 | [diff] [blame] | 173 | |
| 174 | Is pretty much the same as writing syscall wrappers, except that all |
| 175 | the action happens within PRE(ioctl) and POST(ioctl). |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 176 | |
njn | 75b31b3 | 2003-06-12 11:24:10 +0000 | [diff] [blame] | 177 | There's a default case, sometimes it isn't correct and you have to write a |
| 178 | more specific case to get the right behaviour. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 179 | |
nethercote | 98ae6da | 2004-01-19 19:32:30 +0000 | [diff] [blame] | 180 | As above, please create a bug report and attach the patch as described |
njn | 272b216 | 2005-05-17 03:22:38 +0000 | [diff] [blame] | 181 | on http://www.valgrind.org. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 182 | |