sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1 | <?xml version="1.0"?> <!-- -*- sgml -*- --> |
| 2 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 4 | [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]> |
| 5 | |
| 6 | |
| 7 | <chapter id="manual-core-adv" xreflabel="Valgrind's core: advanced topics"> |
| 8 | <title>Using and understanding the Valgrind core: Advanced Topics</title> |
| 9 | |
| 10 | <para>This chapter describes advanced aspects of the Valgrind core |
| 11 | services, which are mostly of interest to power users who wish to |
| 12 | customise and modify Valgrind's default behaviours in certain useful |
| 13 | ways. The subjects covered are:</para> |
| 14 | |
| 15 | <itemizedlist> |
| 16 | <listitem><para>The "Client Request" mechanism</para></listitem> |
sewardj | 47ffedb | 2011-10-24 07:36:57 +0000 | [diff] [blame] | 17 | <listitem><para>Debugging your program using Valgrind's gdbserver |
| 18 | and GDB</para></listitem> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 19 | <listitem><para>Function Wrapping</para></listitem> |
| 20 | </itemizedlist> |
| 21 | |
| 22 | |
| 23 | |
| 24 | <sect1 id="manual-core-adv.clientreq" |
| 25 | xreflabel="The Client Request mechanism"> |
| 26 | <title>The Client Request mechanism</title> |
| 27 | |
| 28 | <para>Valgrind has a trapdoor mechanism via which the client |
| 29 | program can pass all manner of requests and queries to Valgrind |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 30 | and the current tool. Internally, this is used extensively |
| 31 | to make various things work, although that's not visible from the |
| 32 | outside.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 33 | |
| 34 | <para>For your convenience, a subset of these so-called client |
| 35 | requests is provided to allow you to tell Valgrind facts about |
| 36 | the behaviour of your program, and also to make queries. |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 37 | In particular, your program can tell Valgrind about things that it |
| 38 | otherwise would not know, leading to better results. |
| 39 | </para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 40 | |
| 41 | <para>Clients need to include a header file to make this work. |
| 42 | Which header file depends on which client requests you use. Some |
| 43 | client requests are handled by the core, and are defined in the |
| 44 | header file <filename>valgrind/valgrind.h</filename>. Tool-specific |
| 45 | header files are named after the tool, e.g. |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 46 | <filename>valgrind/memcheck.h</filename>. Each tool-specific header file |
| 47 | includes <filename>valgrind/valgrind.h</filename> so you don't need to |
| 48 | include it in your client if you include a tool-specific header. All header |
| 49 | files can be found in the <literal>include/valgrind</literal> directory of |
| 50 | wherever Valgrind was installed.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 51 | |
| 52 | <para>The macros in these header files have the magical property |
| 53 | that they generate code in-line which Valgrind can spot. |
| 54 | However, the code does nothing when not run on Valgrind, so you |
| 55 | are not forced to run your program under Valgrind just because you |
| 56 | use the macros in this file. Also, you are not required to link your |
| 57 | program with any extra supporting libraries.</para> |
| 58 | |
| 59 | <para>The code added to your binary has negligible performance impact: |
sewardj | e089f01 | 2010-10-13 21:47:29 +0000 | [diff] [blame] | 60 | on x86, amd64, ppc32, ppc64 and ARM, the overhead is 6 simple integer |
| 61 | instructions and is probably undetectable except in tight loops. |
| 62 | However, if you really wish to compile out the client requests, you |
| 63 | can compile with <option>-DNVALGRIND</option> (analogous to |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 64 | <option>-DNDEBUG</option>'s effect on |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 65 | <function>assert</function>). |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 66 | </para> |
| 67 | |
| 68 | <para>You are encouraged to copy the <filename>valgrind/*.h</filename> headers |
| 69 | into your project's include directory, so your program doesn't have a |
| 70 | compile-time dependency on Valgrind being installed. The Valgrind headers, |
| 71 | unlike most of the rest of the code, are under a BSD-style license so you may |
| 72 | include them without worrying about license incompatibility.</para> |
| 73 | |
| 74 | <para>Here is a brief description of the macros available in |
| 75 | <filename>valgrind.h</filename>, which work with more than one |
| 76 | tool (see the tool-specific documentation for explanations of the |
| 77 | tool-specific macros).</para> |
| 78 | |
| 79 | <variablelist> |
| 80 | |
| 81 | <varlistentry> |
| 82 | <term><command><computeroutput>RUNNING_ON_VALGRIND</computeroutput></command>:</term> |
| 83 | <listitem> |
| 84 | <para>Returns 1 if running on Valgrind, 0 if running on the |
| 85 | real CPU. If you are running Valgrind on itself, returns the |
| 86 | number of layers of Valgrind emulation you're running on. |
| 87 | </para> |
| 88 | </listitem> |
| 89 | </varlistentry> |
| 90 | |
| 91 | <varlistentry> |
| 92 | <term><command><computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>:</command></term> |
| 93 | <listitem> |
| 94 | <para>Discards translations of code in the specified address |
| 95 | range. Useful if you are debugging a JIT compiler or some other |
| 96 | dynamic code generation system. After this call, attempts to |
| 97 | execute code in the invalidated address range will cause |
| 98 | Valgrind to make new translations of that code, which is |
| 99 | probably the semantics you want. Note that code invalidations |
| 100 | are expensive because finding all the relevant translations |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 101 | quickly is very difficult, so try not to call it often. |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 102 | Note that you can be clever about |
| 103 | this: you only need to call it when an area which previously |
| 104 | contained code is overwritten with new code. You can choose |
| 105 | to write code into fresh memory, and just call this |
| 106 | occasionally to discard large chunks of old code all at |
| 107 | once.</para> |
| 108 | <para> |
| 109 | Alternatively, for transparent self-modifying-code support, |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 110 | use<option>--smc-check=all</option>, or run |
sewardj | e089f01 | 2010-10-13 21:47:29 +0000 | [diff] [blame] | 111 | on ppc32/Linux, ppc64/Linux or ARM/Linux. |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 112 | </para> |
| 113 | </listitem> |
| 114 | </varlistentry> |
| 115 | |
| 116 | <varlistentry> |
| 117 | <term><command><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</command></term> |
| 118 | <listitem> |
| 119 | <para>Returns the number of errors found so far by Valgrind. Can be |
| 120 | useful in test harness code when combined with the |
| 121 | <option>--log-fd=-1</option> option; this runs Valgrind silently, |
| 122 | but the client program can detect when errors occur. Only useful |
| 123 | for tools that report errors, e.g. it's useful for Memcheck, but for |
| 124 | Cachegrind it will always return zero because Cachegrind doesn't |
| 125 | report errors.</para> |
| 126 | </listitem> |
| 127 | </varlistentry> |
| 128 | |
| 129 | <varlistentry> |
| 130 | <term><command><computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>:</command></term> |
| 131 | <listitem> |
| 132 | <para>If your program manages its own memory instead of using |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 133 | the standard <function>malloc</function> / |
| 134 | <function>new</function> / |
| 135 | <function>new[]</function>, tools that track |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 136 | information about heap blocks will not do nearly as good a |
| 137 | job. For example, Memcheck won't detect nearly as many |
| 138 | errors, and the error messages won't be as informative. To |
| 139 | improve this situation, use this macro just after your custom |
| 140 | allocator allocates some new memory. See the comments in |
| 141 | <filename>valgrind.h</filename> for information on how to use |
| 142 | it.</para> |
| 143 | </listitem> |
| 144 | </varlistentry> |
| 145 | |
| 146 | <varlistentry> |
| 147 | <term><command><computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput>:</command></term> |
| 148 | <listitem> |
| 149 | <para>This should be used in conjunction with |
| 150 | <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>. |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 151 | Again, see <filename>valgrind.h</filename> for |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 152 | information on how to use it.</para> |
| 153 | </listitem> |
| 154 | </varlistentry> |
| 155 | |
| 156 | <varlistentry> |
bart | 9134738 | 2011-03-25 20:07:25 +0000 | [diff] [blame] | 157 | <term><command><computeroutput>VALGRIND_RESIZEINPLACE_BLOCK</computeroutput>:</command></term> |
| 158 | <listitem> |
| 159 | <para>Informs a Valgrind tool that the size of an allocated block has been |
| 160 | modified but not its address. See <filename>valgrind.h</filename> for |
| 161 | more information on how to use it.</para> |
| 162 | </listitem> |
| 163 | </varlistentry> |
| 164 | |
| 165 | <varlistentry> |
njn | 23fd9bc | 2009-08-10 01:43:20 +0000 | [diff] [blame] | 166 | <term> |
| 167 | <command><computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput></command>, |
| 168 | <command><computeroutput>VALGRIND_DESTROY_MEMPOOL</computeroutput></command>, |
| 169 | <command><computeroutput>VALGRIND_MEMPOOL_ALLOC</computeroutput></command>, |
| 170 | <command><computeroutput>VALGRIND_MEMPOOL_FREE</computeroutput></command>, |
| 171 | <command><computeroutput>VALGRIND_MOVE_MEMPOOL</computeroutput></command>, |
| 172 | <command><computeroutput>VALGRIND_MEMPOOL_CHANGE</computeroutput></command>, |
| 173 | <command><computeroutput>VALGRIND_MEMPOOL_EXISTS</computeroutput></command>: |
| 174 | </term> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 175 | <listitem> |
njn | 23fd9bc | 2009-08-10 01:43:20 +0000 | [diff] [blame] | 176 | <para>These are similar to |
| 177 | <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput> and |
| 178 | <computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput> |
| 179 | but are tailored towards code that uses memory pools. See |
| 180 | <xref linkend="mc-manual.mempools"/> for a detailed description.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 181 | </listitem> |
| 182 | </varlistentry> |
| 183 | |
| 184 | <varlistentry> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 185 | <term><command><computeroutput>VALGRIND_NON_SIMD_CALL[0123]</computeroutput>:</command></term> |
| 186 | <listitem> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 187 | <para>Executes a function in the client program on the |
| 188 | <emphasis>real</emphasis> CPU, not the virtual CPU that Valgrind |
| 189 | normally runs code on. The function must take an integer (holding a |
| 190 | thread ID) as the first argument and then 0, 1, 2 or 3 more arguments |
| 191 | (depending on which client request is used). These are used in various |
| 192 | ways internally to Valgrind. They might be useful to client |
| 193 | programs.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 194 | |
| 195 | <para><command>Warning:</command> Only use these if you |
njn | 45fb4d3 | 2007-12-05 21:51:50 +0000 | [diff] [blame] | 196 | <emphasis>really</emphasis> know what you are doing. They aren't |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 197 | entirely reliable, and can cause Valgrind to crash. See |
| 198 | <filename>valgrind.h</filename> for more details. |
njn | 45fb4d3 | 2007-12-05 21:51:50 +0000 | [diff] [blame] | 199 | </para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 200 | </listitem> |
| 201 | </varlistentry> |
| 202 | |
| 203 | <varlistentry> |
| 204 | <term><command><computeroutput>VALGRIND_PRINTF(format, ...)</computeroutput>:</command></term> |
| 205 | <listitem> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 206 | <para>Print a printf-style message to the Valgrind log file. The |
| 207 | message is prefixed with the PID between a pair of |
| 208 | <computeroutput>**</computeroutput> markers. (Like all client requests, |
| 209 | nothing is output if the client program is not running under Valgrind.) |
bart | 924bb22 | 2010-08-27 10:01:32 +0000 | [diff] [blame] | 210 | Output is not produced until a newline is encountered, or subsequent |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 211 | Valgrind output is printed; this allows you to build up a single line of |
| 212 | output over multiple calls. Returns the number of characters output, |
| 213 | excluding the PID prefix.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 214 | </listitem> |
| 215 | </varlistentry> |
| 216 | |
| 217 | <varlistentry> |
| 218 | <term><command><computeroutput>VALGRIND_PRINTF_BACKTRACE(format, ...)</computeroutput>:</command></term> |
| 219 | <listitem> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 220 | <para>Like <computeroutput>VALGRIND_PRINTF</computeroutput> (in |
| 221 | particular, the return value is identical), but prints a stack backtrace |
| 222 | immediately afterwards.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 223 | </listitem> |
| 224 | </varlistentry> |
| 225 | |
| 226 | <varlistentry> |
philippe | 583ae93 | 2013-01-20 17:46:19 +0000 | [diff] [blame] | 227 | <term><command><computeroutput>VALGRIND_MONITOR_COMMAND(command)</computeroutput>:</command></term> |
| 228 | <listitem> |
| 229 | <para>Execute the given monitor command (a string). |
| 230 | Returns 0 if command is recognised. Returns 1 if command is not recognised. |
| 231 | Note that some monitor commands provide access to a functionality |
| 232 | also accessible via a specific client request. For example, |
| 233 | memcheck leak search can be requested from the client program |
| 234 | using VALGRIND_DO_LEAK_CHECK or via the monitor command "leak_search". |
| 235 | Note that the syntax of the command string is only verified at |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 236 | run-time. So, if it exists, it is preferable to use a specific |
philippe | 583ae93 | 2013-01-20 17:46:19 +0000 | [diff] [blame] | 237 | client request to have better compile time verifications of the |
| 238 | arguments. |
| 239 | </para> |
| 240 | </listitem> |
| 241 | </varlistentry> |
| 242 | |
| 243 | <varlistentry> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 244 | <term><command><computeroutput>VALGRIND_STACK_REGISTER(start, end)</computeroutput>:</command></term> |
| 245 | <listitem> |
| 246 | <para>Registers a new stack. Informs Valgrind that the memory range |
| 247 | between start and end is a unique stack. Returns a stack identifier |
| 248 | that can be used with other |
| 249 | <computeroutput>VALGRIND_STACK_*</computeroutput> calls.</para> |
philippe | 2046593 | 2013-03-13 22:03:31 +0000 | [diff] [blame] | 250 | <para>Valgrind will use this information to determine if a change |
| 251 | to the stack pointer is an item pushed onto the stack or a change |
| 252 | over to a new stack. Use this if you're using a user-level thread |
| 253 | package and are noticing crashes in stack trace recording or |
| 254 | spurious errors from Valgrind about uninitialized memory |
| 255 | reads.</para> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 256 | |
| 257 | <para><command>Warning:</command> Unfortunately, this client request is |
| 258 | unreliable and best avoided.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 259 | </listitem> |
| 260 | </varlistentry> |
| 261 | |
| 262 | <varlistentry> |
| 263 | <term><command><computeroutput>VALGRIND_STACK_DEREGISTER(id)</computeroutput>:</command></term> |
| 264 | <listitem> |
| 265 | <para>Deregisters a previously registered stack. Informs |
| 266 | Valgrind that previously registered memory range with stack id |
| 267 | <computeroutput>id</computeroutput> is no longer a stack.</para> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 268 | |
| 269 | <para><command>Warning:</command> Unfortunately, this client request is |
| 270 | unreliable and best avoided.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 271 | </listitem> |
| 272 | </varlistentry> |
| 273 | |
| 274 | <varlistentry> |
| 275 | <term><command><computeroutput>VALGRIND_STACK_CHANGE(id, start, end)</computeroutput>:</command></term> |
| 276 | <listitem> |
| 277 | <para>Changes a previously registered stack. Informs |
| 278 | Valgrind that the previously registered stack with stack id |
| 279 | <computeroutput>id</computeroutput> has changed its start and end |
| 280 | values. Use this if your user-level thread package implements |
| 281 | stack growth.</para> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 282 | |
| 283 | <para><command>Warning:</command> Unfortunately, this client request is |
| 284 | unreliable and best avoided.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 285 | </listitem> |
| 286 | </varlistentry> |
| 287 | |
| 288 | </variablelist> |
| 289 | |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 290 | </sect1> |
| 291 | |
| 292 | |
| 293 | |
| 294 | |
| 295 | |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 296 | |
philippe | a02e267 | 2013-03-06 22:39:18 +0000 | [diff] [blame] | 297 | <!-- Referenced from both the manual and manpage --> |
| 298 | <sect1 id="&vg-gdbserver-id;" |
| 299 | xreflabel="&vg-gdbserver-label;"> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 300 | <title>Debugging your program using Valgrind gdbserver and GDB</title> |
| 301 | |
| 302 | <para>A program running under Valgrind is not executed directly by the |
| 303 | CPU. Instead it runs on a synthetic CPU provided by Valgrind. This is |
| 304 | why a debugger cannot debug your program when it runs on Valgrind. |
| 305 | </para> |
| 306 | <para> |
| 307 | This section describes how GDB can interact with the |
| 308 | Valgrind gdbserver to provide a fully debuggable program under |
| 309 | Valgrind. Used in this way, GDB also provides an interactive usage of |
| 310 | Valgrind core or tool functionalities, including incremental leak search |
| 311 | under Memcheck and on-demand Massif snapshot production. |
| 312 | </para> |
| 313 | |
| 314 | <sect2 id="manual-core-adv.gdbserver-simple" |
| 315 | xreflabel="gdbserver simple example"> |
| 316 | <title>Quick Start: debugging in 3 steps</title> |
| 317 | |
sewardj | 1568e17 | 2011-06-18 08:28:04 +0000 | [diff] [blame] | 318 | <para>The simplest way to get started is to run Valgrind with the |
| 319 | flag <option>--vgdb-error=0</option>. Then follow the on-screen |
| 320 | directions, which give you the precise commands needed to start GDB |
| 321 | and connect it to your program.</para> |
| 322 | |
| 323 | <para>Otherwise, here's a slightly more verbose overview.</para> |
| 324 | |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 325 | <para>If you want to debug a program with GDB when using the Memcheck |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 326 | tool, start Valgrind like this: |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 327 | <screen><![CDATA[ |
| 328 | valgrind --vgdb=yes --vgdb-error=0 prog |
| 329 | ]]></screen></para> |
| 330 | |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 331 | <para>In another shell, start GDB: |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 332 | <screen><![CDATA[ |
| 333 | gdb prog |
| 334 | ]]></screen></para> |
| 335 | |
| 336 | <para>Then give the following command to GDB: |
| 337 | <screen><![CDATA[ |
| 338 | (gdb) target remote | vgdb |
| 339 | ]]></screen></para> |
| 340 | |
| 341 | <para>You can now debug your program e.g. by inserting a breakpoint |
| 342 | and then using the GDB <computeroutput>continue</computeroutput> |
| 343 | command.</para> |
| 344 | |
| 345 | <para>This quick start information is enough for basic usage of the |
| 346 | Valgrind gdbserver. The sections below describe more advanced |
| 347 | functionality provided by the combination of Valgrind and GDB. Note |
| 348 | that the command line flag <option>--vgdb=yes</option> can be omitted, |
| 349 | as this is the default value. |
| 350 | </para> |
| 351 | |
| 352 | </sect2> |
| 353 | |
| 354 | <sect2 id="manual-core-adv.gdbserver-concept" |
| 355 | xreflabel="gdbserver"> |
| 356 | <title>Valgrind gdbserver overall organisation</title> |
| 357 | <para>The GNU GDB debugger is typically used to debug a process |
| 358 | running on the same machine. In this mode, GDB uses system calls to |
| 359 | control and query the program being debugged. This works well, but |
| 360 | only allows GDB to debug a program running on the same computer. |
| 361 | </para> |
| 362 | |
| 363 | <para>GDB can also debug processes running on a different computer. |
| 364 | To achieve this, GDB defines a protocol (that is, a set of query and |
| 365 | reply packets) that facilitates fetching the value of memory or |
| 366 | registers, setting breakpoints, etc. A gdbserver is an implementation |
| 367 | of this "GDB remote debugging" protocol. To debug a process running |
| 368 | on a remote computer, a gdbserver (sometimes called a GDB stub) |
| 369 | must run at the remote computer side. |
| 370 | </para> |
| 371 | |
| 372 | <para>The Valgrind core provides a built-in gdbserver implementation, |
| 373 | which is activated using <option>--vgdb=yes</option> |
| 374 | or <option>--vgdb=full</option>. This gdbserver allows the process |
| 375 | running on Valgrind's synthetic CPU to be debugged remotely. |
| 376 | GDB sends protocol query packets (such as "get register contents") to |
| 377 | the Valgrind embedded gdbserver. The gdbserver executes the queries |
| 378 | (for example, it will get the register values of the synthetic CPU) |
| 379 | and gives the results back to GDB. |
| 380 | </para> |
| 381 | |
| 382 | <para>GDB can use various kinds of channels (TCP/IP, serial line, etc) |
| 383 | to communicate with the gdbserver. In the case of Valgrind's |
| 384 | gdbserver, communication is done via a pipe and a small helper program |
philippe | a02e267 | 2013-03-06 22:39:18 +0000 | [diff] [blame] | 385 | called <xref linkend="&vg-vgdb-id;"/>, which acts as an |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 386 | intermediary. If no GDB is in use, vgdb can also be |
| 387 | used to send monitor commands to the Valgrind gdbserver from a shell |
| 388 | command line. |
| 389 | </para> |
| 390 | |
| 391 | </sect2> |
| 392 | |
| 393 | <sect2 id="manual-core-adv.gdbserver-gdb" |
| 394 | xreflabel="Connecting GDB to a Valgrind gdbserver"> |
| 395 | <title>Connecting GDB to a Valgrind gdbserver</title> |
| 396 | <para>To debug a program "<filename>prog</filename>" running under |
| 397 | Valgrind, you must ensure that the Valgrind gdbserver is activated by |
| 398 | specifying either <option>--vgdb=yes</option> |
sewardj | 47ffedb | 2011-10-24 07:36:57 +0000 | [diff] [blame] | 399 | or <option>--vgdb=full</option>. A secondary command line option, |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 400 | <option>--vgdb-error=number</option>, can be used to tell the gdbserver |
| 401 | only to become active once the specified number of errors have been |
philippe | baf6964 | 2012-02-15 22:29:30 +0000 | [diff] [blame] | 402 | shown. A value of zero will therefore cause |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 403 | the gdbserver to become active at startup, which allows you to |
| 404 | insert breakpoints before starting the run. For example: |
| 405 | <screen><![CDATA[ |
| 406 | valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog |
| 407 | ]]></screen></para> |
| 408 | |
| 409 | <para>The Valgrind gdbserver is invoked at startup |
| 410 | and indicates it is waiting for a connection from a GDB:</para> |
| 411 | |
| 412 | <programlisting><![CDATA[ |
| 413 | ==2418== Memcheck, a memory error detector |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 414 | ==2418== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al. |
| 415 | ==2418== Using Valgrind-3.13.0.SVN and LibVEX; rerun with -h for copyright info |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 416 | ==2418== Command: ./prog |
| 417 | ==2418== |
| 418 | ==2418== (action at startup) vgdb me ... |
| 419 | ]]></programlisting> |
| 420 | |
| 421 | |
| 422 | <para>GDB (in another shell) can then be connected to the Valgrind gdbserver. |
| 423 | For this, GDB must be started on the program <filename>prog</filename>: |
| 424 | <screen><![CDATA[ |
| 425 | gdb ./prog |
| 426 | ]]></screen></para> |
| 427 | |
| 428 | |
| 429 | <para>You then indicate to GDB that you want to debug a remote target: |
| 430 | <screen><![CDATA[ |
| 431 | (gdb) target remote | vgdb |
| 432 | ]]></screen> |
| 433 | GDB then starts a vgdb relay application to communicate with the |
| 434 | Valgrind embedded gdbserver:</para> |
| 435 | |
| 436 | <programlisting><![CDATA[ |
| 437 | (gdb) target remote | vgdb |
| 438 | Remote debugging using | vgdb |
| 439 | relaying data between gdb and process 2418 |
| 440 | Reading symbols from /lib/ld-linux.so.2...done. |
| 441 | Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done. |
| 442 | Loaded symbols for /lib/ld-linux.so.2 |
| 443 | [Switching to Thread 2418] |
| 444 | 0x001f2850 in _start () from /lib/ld-linux.so.2 |
| 445 | (gdb) |
| 446 | ]]></programlisting> |
| 447 | |
| 448 | <para>Note that vgdb is provided as part of the Valgrind |
| 449 | distribution. You do not need to install it separately.</para> |
| 450 | |
| 451 | <para>If vgdb detects that there are multiple Valgrind gdbservers that |
| 452 | can be connected to, it will list all such servers and their PIDs, and |
| 453 | then exit. You can then reissue the GDB "target" command, but |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 454 | specifying the PID of the process you want to debug: |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 455 | </para> |
| 456 | |
| 457 | <programlisting><![CDATA[ |
| 458 | (gdb) target remote | vgdb |
| 459 | Remote debugging using | vgdb |
| 460 | no --pid= arg given and multiple valgrind pids found: |
| 461 | use --pid=2479 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog |
| 462 | use --pid=2481 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog |
| 463 | use --pid=2483 for valgrind --vgdb=yes --vgdb-error=0 ./another_prog |
| 464 | Remote communication error: Resource temporarily unavailable. |
| 465 | (gdb) target remote | vgdb --pid=2479 |
| 466 | Remote debugging using | vgdb --pid=2479 |
| 467 | relaying data between gdb and process 2479 |
| 468 | Reading symbols from /lib/ld-linux.so.2...done. |
| 469 | Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done. |
| 470 | Loaded symbols for /lib/ld-linux.so.2 |
| 471 | [Switching to Thread 2479] |
| 472 | 0x001f2850 in _start () from /lib/ld-linux.so.2 |
| 473 | (gdb) |
| 474 | ]]></programlisting> |
| 475 | |
| 476 | <para>Once GDB is connected to the Valgrind gdbserver, it can be used |
| 477 | in the same way as if you were debugging the program natively:</para> |
| 478 | <itemizedlist> |
| 479 | <listitem> |
| 480 | <para>Breakpoints can be inserted or deleted.</para> |
| 481 | </listitem> |
| 482 | <listitem> |
| 483 | <para>Variables and register values can be examined or modified. |
| 484 | </para> |
| 485 | </listitem> |
| 486 | <listitem> |
| 487 | <para>Signal handling can be configured (printing, ignoring). |
| 488 | </para> |
| 489 | </listitem> |
| 490 | <listitem> |
| 491 | <para>Execution can be controlled (continue, step, next, stepi, etc). |
| 492 | </para> |
| 493 | </listitem> |
| 494 | <listitem> |
| 495 | <para>Program execution can be interrupted using Control-C.</para> |
| 496 | </listitem> |
| 497 | </itemizedlist> |
| 498 | |
| 499 | <para>And so on. Refer to the GDB user manual for a complete |
| 500 | description of GDB's functionality. |
| 501 | </para> |
| 502 | |
| 503 | </sect2> |
| 504 | |
sewardj | 992d3cc | 2011-10-22 20:38:08 +0000 | [diff] [blame] | 505 | <sect2 id="manual-core-adv.gdbserver-gdb-android" |
| 506 | xreflabel="Connecting to an Android gdbserver"> |
| 507 | <title>Connecting to an Android gdbserver</title> |
| 508 | <para> When developping applications for Android, you will typically use |
| 509 | a development system (on which the Android NDK is installed) to compile your |
| 510 | application. An Android target system or emulator will be used to run |
| 511 | the application. |
| 512 | In this setup, Valgrind and vgdb will run on the Android system, |
| 513 | while GDB will run on the development system. GDB will connect |
| 514 | to the vgdb running on the Android system using the Android NDK |
| 515 | 'adb forward' application. |
| 516 | </para> |
| 517 | <para> Example: on the Android system, execute the following: |
| 518 | <screen><![CDATA[ |
philippe | 8bb9e04 | 2012-05-25 22:36:01 +0000 | [diff] [blame] | 519 | valgrind --vgdb-error=0 --vgdb=yes prog |
sewardj | 992d3cc | 2011-10-22 20:38:08 +0000 | [diff] [blame] | 520 | # and then in another shell, run: |
| 521 | vgdb --port=1234 |
| 522 | ]]></screen> |
| 523 | </para> |
| 524 | |
| 525 | <para> On the development system, execute the following commands: |
| 526 | <screen><![CDATA[ |
| 527 | adb forward tcp:1234 tcp:1234 |
| 528 | gdb prog |
| 529 | (gdb) target remote :1234 |
| 530 | ]]></screen> |
| 531 | GDB will use a local tcp/ip connection to connect to the Android adb forwarder. |
| 532 | Adb will establish a relay connection between the host system and the Android |
sewardj | badefc9 | 2011-10-27 10:01:17 +0000 | [diff] [blame] | 533 | target system. Be sure to use the GDB delivered in the |
sewardj | 992d3cc | 2011-10-22 20:38:08 +0000 | [diff] [blame] | 534 | Android NDK system (typically, arm-linux-androideabi-gdb), as the host |
| 535 | GDB is probably not able to debug Android arm applications. |
| 536 | Note that the local port nr (used by GDB) must not necessarily be equal |
| 537 | to the port number used by vgdb: adb can forward tcp/ip between different |
| 538 | port numbers. |
| 539 | </para> |
| 540 | |
philippe | 7ee8b88 | 2011-12-27 09:03:36 +0000 | [diff] [blame] | 541 | <para>In the current release, the GDB server is not enabled by default |
sewardj | badefc9 | 2011-10-27 10:01:17 +0000 | [diff] [blame] | 542 | for Android, due to problems in establishing a suitable directory in |
| 543 | which Valgrind can create the necessary FIFOs (named pipes) for |
| 544 | communication purposes. You can stil try to use the GDB server, but |
| 545 | you will need to explicitly enable it using the flag |
| 546 | <computeroutput>--vgdb=yes</computeroutput> or |
| 547 | <computeroutput>--vgdb=full</computeroutput>. |
| 548 | </para> |
| 549 | |
| 550 | <para>Additionally, you |
| 551 | will need to select a temporary directory which is (a) writable |
| 552 | by Valgrind, and (b) supports FIFOs. This is the main difficult |
| 553 | point. Often, <computeroutput>/sdcard</computeroutput> satisfies |
| 554 | requirement (a), but fails for (b) because it is a VFAT file system |
| 555 | and VFAT does not support pipes. Possibilities you could try are |
| 556 | <computeroutput>/data/local</computeroutput>, |
| 557 | <computeroutput>/data/local/Inst</computeroutput> (if you |
| 558 | installed Valgrind there), or |
| 559 | <computeroutput>/data/data/name.of.my.app</computeroutput>, if you |
| 560 | are running a specific application and it has its own directory of |
| 561 | that form. This last possibility may have the highest probability |
| 562 | of success.</para> |
| 563 | |
| 564 | <para>You can specify the temporary directory to use either via |
| 565 | the <computeroutput>--with-tmpdir=</computeroutput> configure time |
| 566 | flag, or by setting environment variable TMPDIR when running Valgrind |
philippe | ed3ac74 | 2011-11-16 20:43:39 +0000 | [diff] [blame] | 567 | (on the Android device, not on the Android NDK development host). |
| 568 | Another alternative is to specify the directory for the FIFOs using |
| 569 | the <computeroutput>--vgdb-prefix=</computeroutput> Valgrind command |
| 570 | line option. |
sewardj | badefc9 | 2011-10-27 10:01:17 +0000 | [diff] [blame] | 571 | </para> |
| 572 | |
| 573 | <para>We hope to have a better story for temporary directory handling |
| 574 | on Android in the future. The difficulty is that, unlike in standard |
| 575 | Unixes, there is no single temporary file directory that reliably |
| 576 | works across all devices and scenarios. |
| 577 | </para> |
| 578 | |
sewardj | 992d3cc | 2011-10-22 20:38:08 +0000 | [diff] [blame] | 579 | </sect2> |
| 580 | |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 581 | <sect2 id="manual-core-adv.gdbserver-commandhandling" |
| 582 | xreflabel="Monitor command handling by the Valgrind gdbserver"> |
| 583 | <title>Monitor command handling by the Valgrind gdbserver</title> |
| 584 | |
| 585 | <para> The Valgrind gdbserver provides additional Valgrind-specific |
philippe | 1de3783 | 2012-05-28 08:56:24 +0000 | [diff] [blame] | 586 | functionality via "monitor commands". Such monitor commands can be |
philippe | 583ae93 | 2013-01-20 17:46:19 +0000 | [diff] [blame] | 587 | sent from the GDB command line or from the shell command line or |
| 588 | requested by the client program using the VALGRIND_MONITOR_COMMAND |
| 589 | client request. See |
philippe | a02e267 | 2013-03-06 22:39:18 +0000 | [diff] [blame] | 590 | <xref linkend="&vg-monitor-id;"/> for the |
philippe | 583ae93 | 2013-01-20 17:46:19 +0000 | [diff] [blame] | 591 | list of the Valgrind core monitor commands available regardless of the |
| 592 | Valgrind tool selected. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 593 | </para> |
| 594 | |
philippe | 1de3783 | 2012-05-28 08:56:24 +0000 | [diff] [blame] | 595 | <para>The following tools provide tool-specific monitor commands: |
| 596 | <itemizedlist> |
| 597 | <listitem> |
| 598 | <para><xref linkend="mc-manual.monitor-commands"/></para> |
| 599 | </listitem> |
| 600 | <listitem> |
| 601 | <para><xref linkend="cl-manual.monitor-commands"/></para> |
| 602 | </listitem> |
| 603 | <listitem> |
| 604 | <para><xref linkend="ms-manual.monitor-commands"/></para> |
| 605 | </listitem> |
philippe | f577434 | 2014-05-03 11:12:50 +0000 | [diff] [blame] | 606 | <listitem> |
| 607 | <para><xref linkend="hg-manual.monitor-commands"/></para> |
| 608 | </listitem> |
philippe | 1de3783 | 2012-05-28 08:56:24 +0000 | [diff] [blame] | 609 | </itemizedlist> |
| 610 | </para> |
| 611 | |
| 612 | <para>An example of a tool specific monitor command is the Memcheck monitor |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 613 | command <computeroutput>leak_check full |
sewardj | c8bd1df | 2011-06-26 12:41:33 +0000 | [diff] [blame] | 614 | reachable any</computeroutput>. This requests a full reporting of the |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 615 | allocated memory blocks. To have this leak check executed, use the GDB |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 616 | command: |
| 617 | <screen><![CDATA[ |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 618 | (gdb) monitor leak_check full reachable any |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 619 | ]]></screen> |
| 620 | </para> |
| 621 | |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 622 | <para>GDB will send the <computeroutput>leak_check</computeroutput> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 623 | command to the Valgrind gdbserver. The Valgrind gdbserver will |
| 624 | execute the monitor command itself, if it recognises it to be a Valgrind core |
| 625 | monitor command. If it is not recognised as such, it is assumed to |
| 626 | be tool-specific and is handed to the tool for execution. For example: |
| 627 | </para> |
| 628 | <programlisting><![CDATA[ |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 629 | (gdb) monitor leak_check full reachable any |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 630 | ==2418== 100 bytes in 1 blocks are still reachable in loss record 1 of 1 |
| 631 | ==2418== at 0x4006E9E: malloc (vg_replace_malloc.c:236) |
| 632 | ==2418== by 0x804884F: main (prog.c:88) |
| 633 | ==2418== |
| 634 | ==2418== LEAK SUMMARY: |
| 635 | ==2418== definitely lost: 0 bytes in 0 blocks |
| 636 | ==2418== indirectly lost: 0 bytes in 0 blocks |
| 637 | ==2418== possibly lost: 0 bytes in 0 blocks |
| 638 | ==2418== still reachable: 100 bytes in 1 blocks |
| 639 | ==2418== suppressed: 0 bytes in 0 blocks |
| 640 | ==2418== |
| 641 | (gdb) |
| 642 | ]]></programlisting> |
| 643 | |
| 644 | <para>As with other GDB commands, the Valgrind gdbserver will accept |
| 645 | abbreviated monitor command names and arguments, as long as the given |
| 646 | abbreviation is unambiguous. For example, the above |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 647 | <computeroutput>leak_check</computeroutput> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 648 | command can also be typed as: |
| 649 | <screen><![CDATA[ |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 650 | (gdb) mo l f r a |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 651 | ]]></screen> |
| 652 | |
| 653 | The letters <computeroutput>mo</computeroutput> are recognised by GDB as being |
| 654 | an abbreviation for <computeroutput>monitor</computeroutput>. So GDB sends the |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 655 | string <computeroutput>l f r a</computeroutput> to the Valgrind |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 656 | gdbserver. The letters provided in this string are unambiguous for the |
| 657 | Valgrind gdbserver. This therefore gives the same output as the |
| 658 | unabbreviated command and arguments. If the provided abbreviation is |
| 659 | ambiguous, the Valgrind gdbserver will report the list of commands (or |
| 660 | argument values) that can match: |
| 661 | <programlisting><![CDATA[ |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 662 | (gdb) mo v. n |
philippe | 02ea413 | 2013-09-04 21:42:43 +0000 | [diff] [blame] | 663 | v. can match v.set v.info v.wait v.kill v.translate v.do |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 664 | (gdb) mo v.i n |
philippe | baf6964 | 2012-02-15 22:29:30 +0000 | [diff] [blame] | 665 | n_errs_found 0 n_errs_shown 0 (vgdb-error 0) |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 666 | (gdb) |
| 667 | ]]></programlisting> |
| 668 | </para> |
| 669 | |
| 670 | <para>Instead of sending a monitor command from GDB, you can also send |
| 671 | these from a shell command line. For example, the following command |
| 672 | lines, when given in a shell, will cause the same leak search to be executed |
| 673 | by the process 3145: |
| 674 | <screen><![CDATA[ |
sewardj | 47ffedb | 2011-10-24 07:36:57 +0000 | [diff] [blame] | 675 | vgdb --pid=3145 leak_check full reachable any |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 676 | vgdb --pid=3145 l f r a |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 677 | ]]></screen></para> |
| 678 | |
| 679 | <para>Note that the Valgrind gdbserver automatically continues the |
| 680 | execution of the program after a standalone invocation of |
| 681 | vgdb. Monitor commands sent from GDB do not cause the program to |
| 682 | continue: the program execution is controlled explicitly using GDB |
| 683 | commands such as "continue" or "next".</para> |
| 684 | |
| 685 | </sect2> |
| 686 | |
| 687 | <sect2 id="manual-core-adv.gdbserver-threads" |
| 688 | xreflabel="Valgrind gdbserver thread information"> |
| 689 | <title>Valgrind gdbserver thread information</title> |
| 690 | |
| 691 | <para>Valgrind's gdbserver enriches the output of the |
| 692 | GDB <computeroutput>info threads</computeroutput> command |
| 693 | with Valgrind-specific information. |
| 694 | The operating system's thread number is followed |
| 695 | by Valgrind's internal index for that thread ("tid") and by |
| 696 | the Valgrind scheduler thread state:</para> |
| 697 | |
| 698 | <programlisting><![CDATA[ |
| 699 | (gdb) info threads |
| 700 | 4 Thread 6239 (tid 4 VgTs_Yielding) 0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2 |
| 701 | * 3 Thread 6238 (tid 3 VgTs_Runnable) make_error (s=0x8048b76 "called from London") at prog.c:20 |
| 702 | 2 Thread 6237 (tid 2 VgTs_WaitSys) 0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2 |
| 703 | 1 Thread 6234 (tid 1 VgTs_Yielding) main (argc=1, argv=0xbedcc274) at prog.c:105 |
| 704 | (gdb) |
| 705 | ]]></programlisting> |
| 706 | |
| 707 | </sect2> |
| 708 | |
| 709 | <sect2 id="manual-core-adv.gdbserver-shadowregisters" |
| 710 | xreflabel="Examining and modifying Valgrind shadow registers"> |
| 711 | <title>Examining and modifying Valgrind shadow registers</title> |
| 712 | |
| 713 | <para> When the option <option>--vgdb-shadow-registers=yes</option> is |
| 714 | given, the Valgrind gdbserver will let GDB examine and/or modify |
| 715 | Valgrind's shadow registers. GDB version 7.1 or later is needed for this |
philippe | ede2d6c | 2012-03-14 21:27:35 +0000 | [diff] [blame] | 716 | to work. For x86 and amd64, GDB version 7.2 or later is needed.</para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 717 | |
| 718 | <para>For each CPU register, the Valgrind core maintains two |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 719 | shadow register sets. These shadow registers can be accessed from |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 720 | GDB by giving a postfix <computeroutput>s1</computeroutput> |
| 721 | or <computeroutput>s2</computeroutput> for respectively the first |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 722 | and second shadow register. For example, the x86 register |
| 723 | <computeroutput>eax</computeroutput> and its two shadows |
| 724 | can be examined using the following commands:</para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 725 | |
| 726 | <programlisting><![CDATA[ |
| 727 | (gdb) p $eax |
| 728 | $1 = 0 |
| 729 | (gdb) p $eaxs1 |
| 730 | $2 = 0 |
| 731 | (gdb) p $eaxs2 |
| 732 | $3 = 0 |
| 733 | (gdb) |
| 734 | ]]></programlisting> |
| 735 | |
philippe | ede2d6c | 2012-03-14 21:27:35 +0000 | [diff] [blame] | 736 | <para>Float shadow registers are shown by GDB as unsigned integer |
| 737 | values instead of float values, as it is expected that these |
| 738 | shadow values are mostly used for memcheck validity bits. </para> |
| 739 | |
philippe | 419d5f2 | 2012-05-24 21:33:17 +0000 | [diff] [blame] | 740 | <para>Intel/amd64 AVX registers <computeroutput>ymm0</computeroutput> |
| 741 | to <computeroutput>ymm15</computeroutput> have also their shadow |
| 742 | registers. However, GDB presents the shadow values using two |
| 743 | "half" registers. For example, the half shadow registers for |
| 744 | <computeroutput>ymm9</computeroutput> are |
| 745 | <computeroutput>xmm9s1</computeroutput> (lower half for set 1), |
| 746 | <computeroutput>ymm9hs1</computeroutput> (upper half for set 1), |
| 747 | <computeroutput>xmm9s2</computeroutput> (lower half for set 2), |
| 748 | <computeroutput>ymm9hs2</computeroutput> (upper half for set 2). |
| 749 | Note the inconsistent notation for the names of the half registers: |
| 750 | the lower part starts with an <computeroutput>x</computeroutput>, |
| 751 | the upper part starts with an <computeroutput>y</computeroutput> |
| 752 | and has an <computeroutput>h</computeroutput> before the shadow postfix. |
| 753 | </para> |
sewardj | ca456c7 | 2012-08-05 13:44:15 +0000 | [diff] [blame] | 754 | <para>The special presentation of the AVX shadow registers is due to |
| 755 | the fact that GDB independently retrieves the lower and upper half of |
| 756 | the <computeroutput>ymm</computeroutput> registers. GDB does not |
| 757 | however know that the shadow half registers have to be shown combined. |
philippe | 419d5f2 | 2012-05-24 21:33:17 +0000 | [diff] [blame] | 758 | </para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 759 | </sect2> |
| 760 | |
| 761 | |
| 762 | <sect2 id="manual-core-adv.gdbserver-limitations" |
| 763 | xreflabel="Limitations of the Valgrind gdbserver"> |
| 764 | <title>Limitations of the Valgrind gdbserver</title> |
| 765 | |
| 766 | <para>Debugging with the Valgrind gdbserver is very similar to native |
| 767 | debugging. Valgrind's gdbserver implementation is quite |
| 768 | complete, and so provides most of the GDB debugging functionality. There |
| 769 | are however some limitations and peculiarities:</para> |
| 770 | <itemizedlist> |
| 771 | <listitem> |
| 772 | <para>Precision of "stop-at" commands.</para> |
| 773 | <para> |
| 774 | GDB commands such as "step", "next", "stepi", breakpoints |
| 775 | and watchpoints, will stop the execution of the process. With |
| 776 | the option <option>--vgdb=yes</option>, the process might not |
| 777 | stop at the exact requested instruction. Instead, it might |
| 778 | continue execution of the current basic block and stop at one |
| 779 | of the following basic blocks. This is linked to the fact that |
| 780 | Valgrind gdbserver has to instrument a block to allow stopping |
| 781 | at the exact instruction requested. Currently, |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 782 | re-instrumentation of the block currently being executed is not |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 783 | supported. So, if the action requested by GDB (e.g. single |
| 784 | stepping or inserting a breakpoint) implies re-instrumentation |
| 785 | of the current block, the GDB action may not be executed |
| 786 | precisely. |
| 787 | </para> |
| 788 | <para> |
| 789 | This limitation applies when the basic block |
| 790 | currently being executed has not yet been instrumented for debugging. |
| 791 | This typically happens when the gdbserver is activated due to the |
| 792 | tool reporting an error or to a watchpoint. If the gdbserver |
| 793 | block has been activated following a breakpoint, or if a |
| 794 | breakpoint has been inserted in the block before its execution, |
| 795 | then the block has already been instrumented for debugging. |
| 796 | </para> |
| 797 | <para> |
| 798 | If you use the option <option>--vgdb=full</option>, then GDB |
| 799 | "stop-at" commands will be obeyed precisely. The |
| 800 | downside is that this requires each instruction to be |
| 801 | instrumented with an additional call to a gdbserver helper |
philippe | 1e433b8 | 2012-07-25 21:58:40 +0000 | [diff] [blame] | 802 | function, which gives considerable overhead (+500% for memcheck) |
| 803 | compared to <option>--vgdb=no</option>. |
| 804 | Option <option>--vgdb=yes</option> has neglectible overhead compared |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 805 | to <option>--vgdb=no</option>. |
| 806 | </para> |
| 807 | </listitem> |
| 808 | |
| 809 | <listitem> |
philippe | 5a5d6b6 | 2012-07-24 20:24:39 +0000 | [diff] [blame] | 810 | <para>Processor registers and flags values.</para> |
| 811 | <para>When Valgrind gdbserver stops on an error, on a breakpoint |
| 812 | or when single stepping, registers and flags values might not be always |
| 813 | up to date due to the optimisations done by the Valgrind core. |
philippe | 0c0291a | 2012-08-01 22:03:12 +0000 | [diff] [blame] | 814 | The default value |
| 815 | <option>--vex-iropt-register-updates=unwindregs-at-mem-access</option> |
| 816 | ensures that the registers needed to make a stack trace (typically |
| 817 | PC/SP/FP) are up to date at each memory access (i.e. memory exception |
| 818 | points). |
| 819 | Disabling some optimisations using the following values will increase |
philippe | 1e433b8 | 2012-07-25 21:58:40 +0000 | [diff] [blame] | 820 | the precision of registers and flags values (a typical performance |
| 821 | impact for memcheck is given for each option). |
philippe | 5a5d6b6 | 2012-07-24 20:24:39 +0000 | [diff] [blame] | 822 | <itemizedlist> |
| 823 | <listitem> |
philippe | 0c0291a | 2012-08-01 22:03:12 +0000 | [diff] [blame] | 824 | <option>--vex-iropt-register-updates=allregs-at-mem-access</option> (+10%) |
| 825 | ensures that all registers and flags are up to date at each memory |
| 826 | access. |
philippe | 5a5d6b6 | 2012-07-24 20:24:39 +0000 | [diff] [blame] | 827 | </listitem> |
| 828 | <listitem> |
philippe | 0c0291a | 2012-08-01 22:03:12 +0000 | [diff] [blame] | 829 | <option>--vex-iropt-register-updates=allregs-at-each-insn</option> (+25%) |
| 830 | ensures that all registers and flags are up to date at each instruction. |
philippe | 5a5d6b6 | 2012-07-24 20:24:39 +0000 | [diff] [blame] | 831 | </listitem> |
| 832 | </itemizedlist> |
philippe | 0c0291a | 2012-08-01 22:03:12 +0000 | [diff] [blame] | 833 | Note that <option>--vgdb=full</option> (+500%, see above |
| 834 | Precision of "stop-at" commands) automatically |
| 835 | activates <option>--vex-iropt-register-updates=allregs-at-each-insn</option>. |
philippe | 0d366ad | 2012-03-05 22:09:20 +0000 | [diff] [blame] | 836 | </para> |
| 837 | </listitem> |
| 838 | |
| 839 | <listitem> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 840 | <para>Hardware watchpoint support by the Valgrind |
| 841 | gdbserver.</para> |
| 842 | |
| 843 | <para> The Valgrind gdbserver can simulate hardware watchpoints |
| 844 | if the selected tool provides support for it. Currently, |
| 845 | only Memcheck provides hardware watchpoint simulation. The |
| 846 | hardware watchpoint simulation provided by Memcheck is much |
| 847 | faster that GDB software watchpoints, which are implemented by |
| 848 | GDB checking the value of the watched zone(s) after each |
| 849 | instruction. Hardware watchpoint simulation also provides read |
| 850 | watchpoints. The hardware watchpoint simulation by Memcheck has |
| 851 | some limitations compared to real hardware |
| 852 | watchpoints. However, the number and length of simulated |
| 853 | watchpoints are not limited. |
| 854 | </para> |
| 855 | <para>Typically, the number of (real) hardware watchpoints is |
| 856 | limited. For example, the x86 architecture supports a maximum of |
| 857 | 4 hardware watchpoints, each watchpoint watching 1, 2, 4 or 8 |
| 858 | bytes. The Valgrind gdbserver does not have any limitation on the |
| 859 | number of simulated hardware watchpoints. It also has no |
| 860 | limitation on the length of the memory zone being |
sewardj | 47ffedb | 2011-10-24 07:36:57 +0000 | [diff] [blame] | 861 | watched. Using GDB version 7.4 or later allow full use of the |
| 862 | flexibility of the Valgrind gdbserver's simulated hardware watchpoints. |
| 863 | Previous GDB versions do not understand that Valgrind gdbserver |
| 864 | watchpoints have no length limit. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 865 | </para> |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 866 | <para>Memcheck implements hardware watchpoint simulation by |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 867 | marking the watched address ranges as being unaddressable. When |
| 868 | a hardware watchpoint is removed, the range is marked as |
| 869 | addressable and defined. Hardware watchpoint simulation of |
| 870 | addressable-but-undefined memory zones works properly, but has |
| 871 | the undesirable side effect of marking the zone as defined when |
| 872 | the watchpoint is removed. |
| 873 | </para> |
| 874 | <para>Write watchpoints might not be reported at the |
| 875 | exact instruction that writes the monitored area, |
| 876 | unless option <option>--vgdb=full</option> is given. Read watchpoints |
| 877 | will always be reported at the exact instruction reading the |
| 878 | watched memory. |
| 879 | </para> |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 880 | <para>It is better to avoid using hardware watchpoint of not |
| 881 | addressable (yet) memory: in such a case, GDB will fall back to |
| 882 | extremely slow software watchpoints. Also, if you do not quit GDB |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 883 | between two debugging sessions, the hardware watchpoints of the |
| 884 | previous sessions will be re-inserted as software watchpoints if |
| 885 | the watched memory zone is not addressable at program startup. |
| 886 | </para> |
| 887 | </listitem> |
| 888 | |
| 889 | <listitem> |
| 890 | <para>Stepping inside shared libraries on ARM.</para> |
| 891 | <para>For unknown reasons, stepping inside shared |
| 892 | libraries on ARM may fail. A workaround is to use the |
| 893 | <computeroutput>ldd</computeroutput> command |
| 894 | to find the list of shared libraries and their loading address |
| 895 | and inform GDB of the loading address using the GDB command |
| 896 | "add-symbol-file". Example: |
| 897 | <programlisting><![CDATA[ |
| 898 | (gdb) shell ldd ./prog |
| 899 | libc.so.6 => /lib/libc.so.6 (0x4002c000) |
| 900 | /lib/ld-linux.so.3 (0x40000000) |
| 901 | (gdb) add-symbol-file /lib/libc.so.6 0x4002c000 |
| 902 | add symbol table from file "/lib/libc.so.6" at |
| 903 | .text_addr = 0x4002c000 |
| 904 | (y or n) y |
| 905 | Reading symbols from /lib/libc.so.6...(no debugging symbols found)...done. |
| 906 | (gdb) |
| 907 | ]]></programlisting> |
| 908 | </para> |
| 909 | </listitem> |
| 910 | |
| 911 | <listitem> |
| 912 | <para>GDB version needed for ARM and PPC32/64.</para> |
| 913 | <para>You must use a GDB version which is able to read XML |
| 914 | target description sent by a gdbserver. This is the standard setup |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 915 | if GDB was configured and built with the "expat" |
| 916 | library. If your GDB was not configured with XML support, it |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 917 | will report an error message when using the "target" |
| 918 | command. Debugging will not work because GDB will then not be |
| 919 | able to fetch the registers from the Valgrind gdbserver. |
| 920 | For ARM programs using the Thumb instruction set, you must use |
| 921 | a GDB version of 7.1 or later, as earlier versions have problems |
| 922 | with next/step/breakpoints in Thumb code. |
| 923 | </para> |
| 924 | </listitem> |
| 925 | |
| 926 | <listitem> |
| 927 | <para>Stack unwinding on PPC32/PPC64. </para> |
| 928 | <para>On PPC32/PPC64, stack unwinding for leaf functions |
| 929 | (functions that do not call any other functions) works properly |
| 930 | only when you give the option |
philippe | 0c0291a | 2012-08-01 22:03:12 +0000 | [diff] [blame] | 931 | <option>--vex-iropt-register-updates=allregs-at-mem-access</option> |
| 932 | or <option>--vex-iropt-register-updates=allregs-at-each-insn</option>. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 933 | You must also pass this option in order to get a precise stack when |
| 934 | a signal is trapped by GDB. |
| 935 | </para> |
| 936 | </listitem> |
| 937 | |
| 938 | <listitem> |
| 939 | <para>Breakpoints encountered multiple times.</para> |
| 940 | <para>Some instructions (e.g. x86 "rep movsb") |
| 941 | are translated by Valgrind using a loop. If a breakpoint is placed |
| 942 | on such an instruction, the breakpoint will be encountered |
| 943 | multiple times -- once for each step of the "implicit" loop |
| 944 | implementing the instruction. |
| 945 | </para> |
| 946 | </listitem> |
| 947 | |
| 948 | <listitem> |
| 949 | <para>Execution of Inferior function calls by the Valgrind |
| 950 | gdbserver.</para> |
| 951 | |
| 952 | <para>GDB allows the user to "call" functions inside the process |
| 953 | being debugged. Such calls are named "inferior calls" in the GDB |
| 954 | terminology. A typical use of an inferior call is to execute |
| 955 | a function that prints a human-readable version of a complex data |
| 956 | structure. To make an inferior call, use the GDB "print" command |
| 957 | followed by the function to call and its arguments. As an |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 958 | example, the following GDB command causes an inferior call to the |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 959 | libc "printf" function to be executed by the process |
| 960 | being debugged: |
| 961 | </para> |
| 962 | <programlisting><![CDATA[ |
| 963 | (gdb) p printf("process being debugged has pid %d\n", getpid()) |
| 964 | $5 = 36 |
| 965 | (gdb) |
| 966 | ]]></programlisting> |
| 967 | |
| 968 | <para>The Valgrind gdbserver supports inferior function calls. |
| 969 | Whilst an inferior call is running, the Valgrind tool will report |
| 970 | errors as usual. If you do not want to have such errors stop the |
| 971 | execution of the inferior call, you can |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 972 | use <computeroutput>v.set vgdb-error</computeroutput> to set a |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 973 | big value before the call, then manually reset it to its original |
| 974 | value when the call is complete.</para> |
| 975 | |
| 976 | <para>To execute inferior calls, GDB changes registers such as |
| 977 | the program counter, and then continues the execution of the |
| 978 | program. In a multithreaded program, all threads are continued, |
| 979 | not just the thread instructed to make the inferior call. If |
| 980 | another thread reports an error or encounters a breakpoint, the |
| 981 | evaluation of the inferior call is abandoned.</para> |
| 982 | |
| 983 | <para>Note that inferior function calls are a powerful GDB |
| 984 | feature, but should be used with caution. For example, if |
| 985 | the program being debugged is stopped inside the function "printf", |
| 986 | forcing a recursive call to printf via an inferior call will |
| 987 | very probably create problems. The Valgrind tool might also add |
| 988 | another level of complexity to inferior calls, e.g. by reporting |
| 989 | tool errors during the Inferior call or due to the |
| 990 | instrumentation done. |
| 991 | </para> |
| 992 | |
| 993 | </listitem> |
| 994 | |
| 995 | <listitem> |
| 996 | <para>Connecting to or interrupting a Valgrind process blocked in |
| 997 | a system call.</para> |
| 998 | |
| 999 | <para>Connecting to or interrupting a Valgrind process blocked in |
| 1000 | a system call requires the "ptrace" system call to be usable. |
philippe | 2558317 | 2013-05-09 21:29:23 +0000 | [diff] [blame] | 1001 | This may be disabled in your kernel for security reasons. |
| 1002 | </para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1003 | |
| 1004 | <para>When running your program, Valgrind's scheduler |
| 1005 | periodically checks whether there is any work to be handled by |
| 1006 | the gdbserver. Unfortunately this check is only done if at least |
| 1007 | one thread of the process is runnable. If all the threads of the |
| 1008 | process are blocked in a system call, then the checks do not |
| 1009 | happen, and the Valgrind scheduler will not invoke the gdbserver. |
| 1010 | In such a case, the vgdb relay application will "force" the |
| 1011 | gdbserver to be invoked, without the intervention of the Valgrind |
| 1012 | scheduler. |
| 1013 | </para> |
| 1014 | |
| 1015 | <para>Such forced invocation of the Valgrind gdbserver is |
| 1016 | implemented by vgdb using ptrace system calls. On a properly |
| 1017 | implemented kernel, the ptrace calls done by vgdb will not |
| 1018 | influence the behaviour of the program running under Valgrind. |
| 1019 | If however they do, giving the |
| 1020 | option <option>--max-invoke-ms=0</option> to the vgdb relay |
| 1021 | application will disable the usage of ptrace calls. The |
| 1022 | consequence of disabling ptrace usage in vgdb is that a Valgrind |
| 1023 | process blocked in a system call cannot be woken up or |
| 1024 | interrupted from GDB until it executes enough basic blocks to let |
| 1025 | the Valgrind scheduler's normal checking take effect. |
| 1026 | </para> |
| 1027 | |
| 1028 | <para>When ptrace is disabled in vgdb, you can increase the |
| 1029 | responsiveness of the Valgrind gdbserver to commands or |
| 1030 | interrupts by giving a lower value to the |
| 1031 | option <option>--vgdb-poll</option>. If your application is |
| 1032 | blocked in system calls most of the time, using a very low value |
| 1033 | for <option>--vgdb-poll</option> will cause a the gdbserver to be |
| 1034 | invoked sooner. The gdbserver polling done by Valgrind's |
| 1035 | scheduler is very efficient, so the increased polling frequency |
| 1036 | should not cause significant performance degradation. |
| 1037 | </para> |
| 1038 | |
| 1039 | <para>When ptrace is disabled in vgdb, a query packet sent by GDB |
| 1040 | may take significant time to be handled by the Valgrind |
| 1041 | gdbserver. In such cases, GDB might encounter a protocol |
| 1042 | timeout. To avoid this, |
| 1043 | you can increase the value of the timeout by using the GDB |
| 1044 | command "set remotetimeout". |
| 1045 | </para> |
| 1046 | |
| 1047 | <para>Ubuntu versions 10.10 and later may restrict the scope of |
| 1048 | ptrace to the children of the process calling ptrace. As the |
| 1049 | Valgrind process is not a child of vgdb, such restricted scoping |
philippe | 2558317 | 2013-05-09 21:29:23 +0000 | [diff] [blame] | 1050 | causes the ptrace calls to fail. To avoid that, Valgrind will |
| 1051 | automatically allow all processes belonging to the same userid to |
| 1052 | "ptrace" a Valgrind process, by using PR_SET_PTRACER.</para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1053 | |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1054 | <para>Unblocking processes blocked in system calls is not |
sewardj | 992d3cc | 2011-10-22 20:38:08 +0000 | [diff] [blame] | 1055 | currently implemented on Mac OS X and Android. So you cannot |
| 1056 | connect to or interrupt a process blocked in a system call on Mac |
| 1057 | OS X or Android. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1058 | </para> |
| 1059 | |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 1060 | <para>Unblocking processes blocked in system calls is implemented |
| 1061 | via agent thread on Solaris. This is quite a different approach |
| 1062 | than using ptrace on Linux, but leads to equivalent result - Valgrind |
| 1063 | gdbserver is invoked. Note that agent thread is a Solaris OS |
| 1064 | feature and cannot be disabled. |
| 1065 | </para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1066 | </listitem> |
| 1067 | |
| 1068 | <listitem> |
| 1069 | <para>Changing register values.</para> |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1070 | <para>The Valgrind gdbserver will only modify the values of the |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1071 | thread's registers when the thread is in status Runnable or |
| 1072 | Yielding. In other states (typically, WaitSys), attempts to |
| 1073 | change register values will fail. Amongst other things, this |
| 1074 | means that inferior calls are not executed for a thread which is |
| 1075 | in a system call, since the Valgrind gdbserver does not implement |
| 1076 | system call restart. |
| 1077 | </para> |
| 1078 | </listitem> |
| 1079 | |
| 1080 | <listitem> |
| 1081 | <para>Unsupported GDB functionality.</para> |
| 1082 | <para>GDB provides a lot of debugging functionality and not all |
| 1083 | of it is supported. Specifically, the following are not |
| 1084 | supported: reversible debugging and tracepoints. |
| 1085 | </para> |
| 1086 | </listitem> |
| 1087 | |
| 1088 | <listitem> |
| 1089 | <para>Unknown limitations or problems.</para> |
| 1090 | <para>The combination of GDB, Valgrind and the Valgrind gdbserver |
| 1091 | probably has unknown other limitations and problems. If you |
| 1092 | encounter strange or unexpected behaviour, feel free to report a |
| 1093 | bug. But first please verify that the limitation or problem is |
| 1094 | not inherent to GDB or the GDB remote protocol. You may be able |
| 1095 | to do so by checking the behaviour when using standard gdbserver |
| 1096 | part of the GDB package. |
| 1097 | </para> |
| 1098 | </listitem> |
| 1099 | |
| 1100 | </itemizedlist> |
| 1101 | |
| 1102 | </sect2> |
| 1103 | |
philippe | a02e267 | 2013-03-06 22:39:18 +0000 | [diff] [blame] | 1104 | <!-- Referenced from both the manual and manpage --> |
| 1105 | <sect2 id="&vg-vgdb-id;" |
| 1106 | xreflabel="&vg-vgdb-label;"> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1107 | <title>vgdb command line options</title> |
| 1108 | <para> Usage: <computeroutput>vgdb [OPTION]... [[-c] COMMAND]...</computeroutput></para> |
| 1109 | |
| 1110 | <para> vgdb ("Valgrind to GDB") is a small program that is used as an |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1111 | intermediary between Valgrind and GDB or a shell. |
| 1112 | Therefore, it has two usage modes: |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1113 | </para> |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1114 | <!-- start of xi:include in the manpage --> |
| 1115 | <orderedlist id="vgdb.desc.modes"> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1116 | <listitem id="manual-core-adv.vgdb-standalone" xreflabel="vgdb standalone"> |
| 1117 | <para>As a standalone utility, it is used from a shell command |
| 1118 | line to send monitor commands to a process running under |
| 1119 | Valgrind. For this usage, the vgdb OPTION(s) must be followed by |
| 1120 | the monitor command to send. To send more than one command, |
| 1121 | separate them with the <option>-c</option> option. |
| 1122 | </para> |
| 1123 | </listitem> |
| 1124 | |
| 1125 | <listitem id="manual-core-adv.vgdb-relay" xreflabel="vgdb relay"> |
| 1126 | <para>In combination with GDB "target remote |" command, it is |
| 1127 | used as the relay application between GDB and the Valgrind |
| 1128 | gdbserver. For this usage, only OPTION(s) can be given, but no |
| 1129 | COMMAND can be given. |
| 1130 | </para> |
| 1131 | </listitem> |
| 1132 | |
| 1133 | </orderedlist> |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1134 | <!-- end of xi:include in the manpage --> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1135 | |
| 1136 | <para><computeroutput>vgdb</computeroutput> accepts the following |
| 1137 | options:</para> |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1138 | <!-- start of xi:include in the manpage --> |
| 1139 | <variablelist id="vgdb.opts.list"> |
| 1140 | <varlistentry> |
| 1141 | <term><option>--pid=<number></option></term> |
| 1142 | <listitem><para>Specifies the PID of |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1143 | the process to which vgdb must connect to. This option is useful |
| 1144 | in case more than one Valgrind gdbserver can be connected to. If |
| 1145 | the <option>--pid</option> argument is not given and multiple |
| 1146 | Valgrind gdbserver processes are running, vgdb will report the |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1147 | list of such processes and then exit.</para></listitem> |
| 1148 | </varlistentry> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1149 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1150 | <varlistentry> |
| 1151 | <term><option>--vgdb-prefix</option></term> |
| 1152 | <listitem><para>Must be given to both |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1153 | Valgrind and vgdb if you want to change the default prefix for the |
| 1154 | FIFOs (named pipes) used for communication between the Valgrind |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1155 | gdbserver and vgdb.</para></listitem> |
| 1156 | </varlistentry> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1157 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1158 | <varlistentry> |
| 1159 | <term><option>--wait=<number></option></term> |
| 1160 | <listitem><para>Instructs vgdb to |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1161 | search for available Valgrind gdbservers for the specified number |
| 1162 | of seconds. This makes it possible start a vgdb process |
| 1163 | before starting the Valgrind gdbserver with which you intend the |
| 1164 | vgdb to communicate. This option is useful when used in |
| 1165 | conjunction with a <option>--vgdb-prefix</option> that is |
| 1166 | unique to the process you want to wait for. |
| 1167 | Also, if you use the <option>--wait</option> argument in the GDB |
| 1168 | "target remote" command, you must set the GDB remotetimeout to a |
| 1169 | value bigger than the --wait argument value. See option |
| 1170 | <option>--max-invoke-ms</option> (just below) |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1171 | for an example of setting the remotetimeout value.</para></listitem> |
| 1172 | </varlistentry> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1173 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1174 | <varlistentry> |
| 1175 | <term><option>--max-invoke-ms=<number></option></term> |
| 1176 | <listitem><para>Gives the |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1177 | number of milliseconds after which vgdb will force the invocation |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1178 | of gdbserver embedded in Valgrind. The default value is 100 |
| 1179 | milliseconds. A value of 0 disables forced invocation. The forced |
| 1180 | invocation is used when vgdb is connected to a Valgrind gdbserver, |
| 1181 | and the Valgrind process has all its threads blocked in a system |
| 1182 | call. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1183 | </para> |
| 1184 | |
| 1185 | <para>If you specify a large value, you might need to increase the |
| 1186 | GDB "remotetimeout" value from its default value of 2 seconds. |
| 1187 | You should ensure that the timeout (in seconds) is |
| 1188 | bigger than the <option>--max-invoke-ms</option> value. For |
| 1189 | example, for <option>--max-invoke-ms=5000</option>, the following |
| 1190 | GDB command is suitable: |
| 1191 | <screen><![CDATA[ |
| 1192 | (gdb) set remotetimeout 6 |
| 1193 | ]]></screen> |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1194 | </para></listitem> |
| 1195 | </varlistentry> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1196 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1197 | <varlistentry> |
| 1198 | <term><option>--cmd-time-out=<number></option></term> |
| 1199 | <listitem><para>Instructs a |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1200 | standalone vgdb to exit if the Valgrind gdbserver it is connected |
| 1201 | to does not process a command in the specified number of seconds. |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1202 | The default value is to never time out.</para></listitem> |
| 1203 | </varlistentry> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1204 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1205 | <varlistentry> |
| 1206 | <term><option>--port=<portnr></option></term> |
| 1207 | <listitem><para>Instructs vgdb to |
sewardj | 992d3cc | 2011-10-22 20:38:08 +0000 | [diff] [blame] | 1208 | use tcp/ip and listen for GDB on the specified port nr rather than |
| 1209 | to use a pipe to communicate with GDB. Using tcp/ip allows to have |
| 1210 | GDB running on one computer and debugging a Valgrind process |
| 1211 | running on another target computer. |
| 1212 | Example: |
| 1213 | <screen><![CDATA[ |
| 1214 | # On the target computer, start your program under valgrind using |
| 1215 | valgrind --vgdb-error=0 prog |
| 1216 | # and then in another shell, run: |
| 1217 | vgdb --port=1234 |
| 1218 | ]]></screen></para> |
| 1219 | <para>On the computer which hosts GDB, execute the command: |
| 1220 | <screen><![CDATA[ |
| 1221 | gdb prog |
| 1222 | (gdb) target remote targetip:1234 |
| 1223 | ]]></screen> |
| 1224 | where targetip is the ip address or hostname of the target computer. |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1225 | </para></listitem> |
| 1226 | </varlistentry> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1227 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1228 | <varlistentry> |
| 1229 | <term><option>-c</option></term> |
| 1230 | <listitem><para>To give more than one command to a |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1231 | standalone vgdb, separate the commands by an |
| 1232 | option <option>-c</option>. Example: |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1233 | <screen><![CDATA[ |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1234 | vgdb v.set log_output -c leak_check any |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1235 | ]]></screen></para></listitem> |
| 1236 | </varlistentry> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1237 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1238 | <varlistentry> |
| 1239 | <term><option>-l</option></term> |
| 1240 | <listitem><para>Instructs a standalone vgdb to report |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1241 | the list of the Valgrind gdbserver processes running and then |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1242 | exit.</para></listitem> |
| 1243 | </varlistentry> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1244 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1245 | <varlistentry> |
| 1246 | <term><option>-D</option></term> |
| 1247 | <listitem><para>Instructs a standalone vgdb to show the |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1248 | state of the shared memory used by the Valgrind gdbserver. vgdb |
| 1249 | will exit after having shown the Valgrind gdbserver shared memory |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1250 | state.</para></listitem> |
| 1251 | </varlistentry> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1252 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1253 | <varlistentry> |
| 1254 | <term><option>-d</option></term> |
| 1255 | <listitem><para>Instructs vgdb to produce debugging |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1256 | output. Give multiple <option>-d</option> args to increase the |
| 1257 | verbosity. When giving <option>-d</option> to a relay vgdb, you better |
| 1258 | redirect the standard error (stderr) of vgdb to a file to avoid |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1259 | interaction between GDB and vgdb debugging output.</para></listitem> |
| 1260 | </varlistentry> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1261 | |
mjw | 3e8d634 | 2013-07-03 10:00:19 +0000 | [diff] [blame] | 1262 | </variablelist> |
| 1263 | <!-- end of xi:include in the manpage --> |
| 1264 | |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1265 | </sect2> |
| 1266 | |
| 1267 | |
philippe | a02e267 | 2013-03-06 22:39:18 +0000 | [diff] [blame] | 1268 | <!-- Referenced from both the manual and manpage --> |
| 1269 | <sect2 id="&vg-monitor-id;" |
| 1270 | xreflabel="&vg-monitor-label;"> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1271 | <title>Valgrind monitor commands</title> |
| 1272 | |
philippe | 1de3783 | 2012-05-28 08:56:24 +0000 | [diff] [blame] | 1273 | <para>This section describes the Valgrind monitor commands, available |
| 1274 | regardless of the Valgrind tool selected. For the tool specific |
| 1275 | commands, refer to <xref linkend="mc-manual.monitor-commands"/>, |
philippe | 07c0852 | 2014-05-14 20:39:27 +0000 | [diff] [blame] | 1276 | <xref linkend="hg-manual.monitor-commands"/>, |
philippe | 1de3783 | 2012-05-28 08:56:24 +0000 | [diff] [blame] | 1277 | <xref linkend="cl-manual.monitor-commands"/> and |
| 1278 | <xref linkend="ms-manual.monitor-commands"/>. </para> |
| 1279 | |
| 1280 | <para> The monitor commands can be sent either from a shell command line, by using a |
| 1281 | standalone vgdb, or from GDB, by using GDB's "monitor" |
philippe | 583ae93 | 2013-01-20 17:46:19 +0000 | [diff] [blame] | 1282 | command (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>). |
| 1283 | They can also be launched by the client program, using the VALGRIND_MONITOR_COMMAND |
| 1284 | client request. |
| 1285 | </para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1286 | |
| 1287 | <itemizedlist> |
| 1288 | <listitem> |
| 1289 | <para><varname>help [debug]</varname> instructs Valgrind's gdbserver |
| 1290 | to give the list of all monitor commands of the Valgrind core and |
| 1291 | of the tool. The optional "debug" argument tells to also give help |
| 1292 | for the monitor commands aimed at Valgrind internals debugging. |
| 1293 | </para> |
| 1294 | </listitem> |
| 1295 | |
| 1296 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1297 | <para><varname>v.info all_errors</varname> shows all errors found |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1298 | so far.</para> |
| 1299 | </listitem> |
| 1300 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1301 | <para><varname>v.info last_error</varname> shows the last error |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1302 | found.</para> |
| 1303 | </listitem> |
| 1304 | |
| 1305 | <listitem> |
philippe | 07c0852 | 2014-05-14 20:39:27 +0000 | [diff] [blame] | 1306 | <para><varname>v.info location <addr></varname> outputs |
| 1307 | information about the location <addr>. Possibly, the |
| 1308 | following are described: global variables, local (stack) |
| 1309 | variables, allocated or freed blocks, ... The information |
| 1310 | produced depends on the tool and on the options given to valgrind. |
| 1311 | Some tools (e.g. memcheck and helgrind) produce more detailed |
| 1312 | information for client heap blocks. For example, these tools show |
| 1313 | the stacktrace where the heap block was allocated. If a tool does |
| 1314 | not replace the malloc/free/... functions, then client heap blocks |
| 1315 | will not be described. Use the |
| 1316 | option <varname>--read-var-info=yes</varname> to obtain more |
| 1317 | detailed information about global or local (stack) variables. |
| 1318 | </para> |
| 1319 | <programlisting><![CDATA[ |
| 1320 | (gdb) monitor v.info location 0x8050b20 |
| 1321 | Location 0x8050b20 is 0 bytes inside global var "mx" |
| 1322 | declared at tc19_shadowmem.c:19 |
| 1323 | |
| 1324 | (gdb) mo v.in loc 0x582f33c |
| 1325 | Location 0x582f33c is 0 bytes inside local var "info" |
| 1326 | declared at tc19_shadowmem.c:282, in frame #1 of thread 3 |
| 1327 | (gdb) |
| 1328 | ]]></programlisting> |
| 1329 | </listitem> |
| 1330 | |
| 1331 | <listitem> |
philippe | 02ea413 | 2013-09-04 21:42:43 +0000 | [diff] [blame] | 1332 | <para><varname>v.info n_errs_found [msg]</varname> shows the number of |
philippe | baf6964 | 2012-02-15 22:29:30 +0000 | [diff] [blame] | 1333 | errors found so far, the nr of errors shown so far and the current |
philippe | 02ea413 | 2013-09-04 21:42:43 +0000 | [diff] [blame] | 1334 | value of the <option>--vgdb-error</option> argument. The optional |
| 1335 | <computeroutput>msg</computeroutput> (one or more words) is appended. |
| 1336 | Typically, this can be used to insert markers in a process output |
| 1337 | file between several tests executed in sequence by a process |
| 1338 | started only once. This allows to associate the errors reported |
| 1339 | by Valgrind with the specific test that produced these errors. |
| 1340 | </para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1341 | </listitem> |
| 1342 | |
| 1343 | <listitem> |
philippe | c336038 | 2012-10-21 14:37:14 +0000 | [diff] [blame] | 1344 | <para><varname>v.info open_fds</varname> shows the list of open file |
| 1345 | descriptors and details related to the file descriptor. |
| 1346 | This only works if <option>--track-fds=yes</option> |
| 1347 | was given at Valgrind startup.</para> |
| 1348 | </listitem> |
| 1349 | |
| 1350 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1351 | <para><varname>v.set {gdb_output | log_output | |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1352 | mixed_output}</varname> allows redirection of the Valgrind output |
| 1353 | (e.g. the errors detected by the tool). The default setting is |
| 1354 | <computeroutput>mixed_output</computeroutput>.</para> |
| 1355 | |
| 1356 | <para>With <computeroutput>mixed_output</computeroutput>, the |
| 1357 | Valgrind output goes to the Valgrind log (typically stderr) while |
| 1358 | the output of the interactive GDB monitor commands (e.g. |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1359 | <computeroutput>v.info last_error</computeroutput>) |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1360 | is displayed by GDB.</para> |
| 1361 | |
| 1362 | <para>With <computeroutput>gdb_output</computeroutput>, both the |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1363 | Valgrind output and the interactive GDB monitor commands output are |
| 1364 | displayed by GDB.</para> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1365 | |
| 1366 | <para>With <computeroutput>log_output</computeroutput>, both the |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1367 | Valgrind output and the interactive GDB monitor commands output go |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1368 | to the Valgrind log.</para> |
| 1369 | </listitem> |
| 1370 | |
| 1371 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1372 | <para><varname>v.wait [ms (default 0)]</varname> instructs |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1373 | Valgrind gdbserver to sleep "ms" milli-seconds and then |
| 1374 | continue. When sent from a standalone vgdb, if this is the last |
| 1375 | command, the Valgrind process will continue the execution of the |
| 1376 | guest process. The typical usage of this is to use vgdb to send a |
| 1377 | "no-op" command to a Valgrind gdbserver so as to continue the |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1378 | execution of the guest process. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1379 | </para> |
| 1380 | </listitem> |
| 1381 | |
| 1382 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1383 | <para><varname>v.kill</varname> requests the gdbserver to kill |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1384 | the process. This can be used from a standalone vgdb to properly |
| 1385 | kill a Valgrind process which is currently expecting a vgdb |
| 1386 | connection.</para> |
| 1387 | </listitem> |
| 1388 | |
| 1389 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1390 | <para><varname>v.set vgdb-error <errornr></varname> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1391 | dynamically changes the value of the |
| 1392 | <option>--vgdb-error</option> argument. A |
| 1393 | typical usage of this is to start with |
| 1394 | <option>--vgdb-error=0</option> on the |
| 1395 | command line, then set a few breakpoints, set the vgdb-error value |
| 1396 | to a huge value and continue execution.</para> |
| 1397 | </listitem> |
| 1398 | |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 1399 | <listitem> |
| 1400 | <para><varname>xtmemory [<filename> default xtmemory.kcg.%p.%n]</varname> |
| 1401 | requests the tool to produce an xtree heap memory report. |
| 1402 | See <xref linkend="manual-core.xtree"/> for |
| 1403 | a detailed explanation about execution trees. </para> |
| 1404 | </listitem> |
| 1405 | |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1406 | </itemizedlist> |
| 1407 | |
| 1408 | <para>The following Valgrind monitor commands are useful for |
| 1409 | investigating the behaviour of Valgrind or its gdbserver in case of |
| 1410 | problems or bugs.</para> |
| 1411 | |
| 1412 | <itemizedlist> |
| 1413 | |
| 1414 | <listitem> |
philippe | 6ec8d63 | 2013-01-23 22:10:28 +0000 | [diff] [blame] | 1415 | <para><varname>v.do expensive_sanity_check_general</varname> |
| 1416 | executes various sanity checks. In particular, the sanity of the |
| 1417 | Valgrind heap is verified. This can be useful if you suspect that |
| 1418 | your program and/or Valgrind has a bug corrupting Valgrind data |
| 1419 | structure. It can also be used when a Valgrind tool |
| 1420 | reports a client error to the connected GDB, in order to verify |
| 1421 | the sanity of Valgrind before continuing the execution. |
| 1422 | </para> |
| 1423 | </listitem> |
| 1424 | |
| 1425 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1426 | <para><varname>v.info gdbserver_status</varname> shows the |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1427 | gdbserver status. In case of problems (e.g. of communications), |
sewardj | 47ffedb | 2011-10-24 07:36:57 +0000 | [diff] [blame] | 1428 | this shows the values of some relevant Valgrind gdbserver internal |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1429 | variables. Note that the variables related to breakpoints and |
| 1430 | watchpoints (e.g. the number of breakpoint addresses and the number of |
| 1431 | watchpoints) will be zero, as GDB by default removes all |
| 1432 | watchpoints and breakpoints when execution stops, and re-inserts |
| 1433 | them when resuming the execution of the debugged process. You can |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1434 | change this GDB behaviour by using the GDB command |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1435 | <computeroutput>set breakpoint always-inserted on</computeroutput>. |
| 1436 | </para> |
| 1437 | </listitem> |
| 1438 | |
| 1439 | <listitem> |
philippe | 93a6a8d | 2012-04-27 22:59:43 +0000 | [diff] [blame] | 1440 | <para><varname>v.info memory [aspacemgr]</varname> shows the statistics of |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1441 | Valgrind's internal heap management. If |
| 1442 | option <option>--profile-heap=yes</option> was given, detailed |
philippe | 93a6a8d | 2012-04-27 22:59:43 +0000 | [diff] [blame] | 1443 | statistics will be output. With the optional argument |
| 1444 | <computeroutput>aspacemgr</computeroutput>. the segment list maintained |
| 1445 | by valgrind address space manager will be output. Note that |
| 1446 | this list of segments is always output on the Valgrind log. |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1447 | </para> |
| 1448 | </listitem> |
| 1449 | |
| 1450 | <listitem> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 1451 | <para><varname>v.info exectxt</varname> shows information about |
philippe | f3a6e93 | 2013-01-10 20:42:51 +0000 | [diff] [blame] | 1452 | the "executable contexts" (i.e. the stack traces) recorded by |
| 1453 | Valgrind. For some programs, Valgrind can record a very high |
| 1454 | number of such stack traces, causing a high memory usage. This |
| 1455 | monitor command shows all the recorded stack traces, followed by |
| 1456 | some statistics. This can be used to analyse the reason for having |
| 1457 | a big number of stack traces. Typically, you will use this command |
| 1458 | if <varname>v.info memory</varname> has shown significant memory |
| 1459 | usage by the "exectxt" arena. |
| 1460 | </para> |
| 1461 | </listitem> |
| 1462 | |
| 1463 | <listitem> |
philippe | 4f6f336 | 2014-04-19 00:25:54 +0000 | [diff] [blame] | 1464 | <para><varname>v.info scheduler</varname> shows various |
| 1465 | information about threads. First, it outputs the host stack trace, |
| 1466 | i.e. the Valgrind code being executed. Then, for each thread, it |
| 1467 | outputs the thread state. For non terminated threads, the state is |
| 1468 | followed by the guest (client) stack trace. Finally, for each |
| 1469 | active thread or for each terminated thread slot not yet re-used, |
| 1470 | it shows the max usage of the valgrind stack.</para> |
| 1471 | <para>Showing the client stack traces allows to compare the stack |
| 1472 | traces produced by the Valgrind unwinder with the stack traces |
| 1473 | produced by GDB+Valgrind gdbserver. Pay attention that GDB and |
| 1474 | Valgrind scheduler status have their own thread numbering |
| 1475 | scheme. To make the link between the GDB thread number and the |
| 1476 | corresponding Valgrind scheduler thread number, use the GDB |
| 1477 | command <computeroutput>info threads</computeroutput>. The output |
| 1478 | of this command shows the GDB thread number and the valgrind |
| 1479 | 'tid'. The 'tid' is the thread number output |
| 1480 | by <computeroutput>v.info scheduler</computeroutput>. When using |
| 1481 | the callgrind tool, the callgrind monitor command |
sewardj | d6e13d8 | 2011-10-22 20:23:30 +0000 | [diff] [blame] | 1482 | <computeroutput>status</computeroutput> outputs internal callgrind |
| 1483 | information about the stack/call graph it maintains. |
| 1484 | </para> |
| 1485 | </listitem> |
| 1486 | |
| 1487 | <listitem> |
philippe | 8587b54 | 2013-12-15 20:24:43 +0000 | [diff] [blame] | 1488 | <para><varname>v.info stats</varname> shows various valgrind core and |
| 1489 | tool statistics. With this, Valgrind and tool statistics can |
| 1490 | be examined while running, even without option <option>--stats=yes</option>. |
| 1491 | </para> |
| 1492 | </listitem> |
| 1493 | |
| 1494 | <listitem> |
philippe | 97bfa19 | 2015-06-02 22:09:42 +0000 | [diff] [blame] | 1495 | <para><varname>v.info unwind <addr> [<len>]</varname> shows |
| 1496 | the CFI unwind debug info for the address range [addr, addr+len-1]. |
| 1497 | The default value of <len> is 1, giving the unwind information |
| 1498 | for the instruction at <addr>. |
| 1499 | </para> |
| 1500 | </listitem> |
| 1501 | |
| 1502 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1503 | <para><varname>v.set debuglog <intvalue></varname> sets the |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1504 | Valgrind debug log level to <intvalue>. This allows to |
| 1505 | dynamically change the log level of Valgrind e.g. when a problem |
| 1506 | is detected.</para> |
| 1507 | </listitem> |
| 1508 | |
| 1509 | <listitem> |
philippe | 180a750 | 2014-04-20 13:41:10 +0000 | [diff] [blame] | 1510 | <para><varname>v.set hostvisibility [yes*|no]</varname> The value |
| 1511 | "yes" indicates to gdbserver that GDB can look at the Valgrind |
| 1512 | 'host' (internal) status/memory. "no" disables this access. |
| 1513 | When hostvisibility is activated, GDB can e.g. look at Valgrind |
| 1514 | global variables. As an example, to examine a Valgrind global |
| 1515 | variable of the memcheck tool on an x86, do the following setup:</para> |
| 1516 | |
| 1517 | <screen><![CDATA[ |
| 1518 | (gdb) monitor v.set hostvisibility yes |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 1519 | (gdb) add-symbol-file /path/to/tool/executable/file/memcheck-x86-linux 0x58000000 |
philippe | 180a750 | 2014-04-20 13:41:10 +0000 | [diff] [blame] | 1520 | add symbol table from file "/path/to/tool/executable/file/memcheck-x86-linux" at |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame^] | 1521 | .text_addr = 0x58000000 |
philippe | 180a750 | 2014-04-20 13:41:10 +0000 | [diff] [blame] | 1522 | (y or n) y |
| 1523 | Reading symbols from /path/to/tool/executable/file/memcheck-x86-linux...done. |
| 1524 | (gdb) |
| 1525 | ]]></screen> |
| 1526 | |
| 1527 | <para>After that, variables defined in memcheck-x86-linux can be accessed, e.g.</para> |
| 1528 | |
| 1529 | <screen><![CDATA[ |
| 1530 | (gdb) p /x vgPlain_threads[1].os_state |
| 1531 | $3 = {lwpid = 0x4688, threadgroup = 0x4688, parent = 0x0, |
| 1532 | valgrind_stack_base = 0x62e78000, valgrind_stack_init_SP = 0x62f79fe0, |
| 1533 | exitcode = 0x0, fatalsig = 0x0} |
| 1534 | (gdb) p vex_control |
| 1535 | $5 = {iropt_verbosity = 0, iropt_level = 2, |
| 1536 | iropt_register_updates = VexRegUpdUnwindregsAtMemAccess, |
| 1537 | iropt_unroll_thresh = 120, guest_max_insns = 60, guest_chase_thresh = 10, |
| 1538 | guest_chase_cond = 0 '\000'} |
| 1539 | (gdb) |
| 1540 | ]]></screen> |
| 1541 | </listitem> |
| 1542 | |
| 1543 | <listitem> |
sewardj | 30b3eca | 2011-06-28 08:20:39 +0000 | [diff] [blame] | 1544 | <para><varname>v.translate <address> |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1545 | [<traceflags>]</varname> shows the translation of the block |
| 1546 | containing <computeroutput>address</computeroutput> with the given |
| 1547 | trace flags. The <computeroutput>traceflags</computeroutput> value |
sewardj | e81a454 | 2011-06-25 10:05:28 +0000 | [diff] [blame] | 1548 | bit patterns have similar meaning to Valgrind's |
sewardj | 350c0fe | 2011-06-17 08:31:22 +0000 | [diff] [blame] | 1549 | <option>--trace-flags</option> option. It can be given |
| 1550 | in hexadecimal (e.g. 0x20) or decimal (e.g. 32) or in binary 1s |
| 1551 | and 0s bit (e.g. 0b00100000). The default value of the traceflags |
| 1552 | is 0b00100000, corresponding to "show after instrumentation". |
| 1553 | The output of this command always goes to the Valgrind |
| 1554 | log.</para> |
| 1555 | <para>The additional bit flag 0b100000000 (bit 8) |
| 1556 | has no equivalent in the <option>--trace-flags</option> option. |
| 1557 | It enables tracing of the gdbserver specific instrumentation. Note |
| 1558 | that this bit 8 can only enable the addition of gdbserver |
| 1559 | instrumentation in the trace. Setting it to 0 will not |
| 1560 | disable the tracing of the gdbserver instrumentation if it is |
| 1561 | active for some other reason, for example because there is a breakpoint at |
| 1562 | this address or because gdbserver is in single stepping |
| 1563 | mode.</para> |
| 1564 | </listitem> |
| 1565 | |
| 1566 | </itemizedlist> |
| 1567 | |
| 1568 | </sect2> |
| 1569 | |
| 1570 | </sect1> |
| 1571 | |
| 1572 | |
| 1573 | |
| 1574 | |
| 1575 | |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1576 | <sect1 id="manual-core-adv.wrapping" xreflabel="Function Wrapping"> |
| 1577 | <title>Function wrapping</title> |
| 1578 | |
| 1579 | <para> |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1580 | Valgrind allows calls to some specified functions to be intercepted and |
| 1581 | rerouted to a different, user-supplied function. This can do whatever it |
| 1582 | likes, typically examining the arguments, calling onwards to the original, |
| 1583 | and possibly examining the result. Any number of functions may be |
| 1584 | wrapped.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1585 | |
| 1586 | <para> |
| 1587 | Function wrapping is useful for instrumenting an API in some way. For |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1588 | example, Helgrind wraps functions in the POSIX pthreads API so it can know |
| 1589 | about thread status changes, and the core is able to wrap |
| 1590 | functions in the MPI (message-passing) API so it can know |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1591 | of memory status changes associated with message arrival/departure. |
| 1592 | Such information is usually passed to Valgrind by using client |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1593 | requests in the wrapper functions, although the exact mechanism may vary. |
| 1594 | </para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1595 | |
| 1596 | <sect2 id="manual-core-adv.wrapping.example" xreflabel="A Simple Example"> |
| 1597 | <title>A Simple Example</title> |
| 1598 | |
| 1599 | <para>Supposing we want to wrap some function</para> |
| 1600 | |
| 1601 | <programlisting><![CDATA[ |
| 1602 | int foo ( int x, int y ) { return x + y; }]]></programlisting> |
| 1603 | |
| 1604 | <para>A wrapper is a function of identical type, but with a special name |
| 1605 | which identifies it as the wrapper for <computeroutput>foo</computeroutput>. |
| 1606 | Wrappers need to include |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1607 | supporting macros from <filename>valgrind.h</filename>. |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1608 | Here is a simple wrapper which prints the arguments and return value:</para> |
| 1609 | |
| 1610 | <programlisting><![CDATA[ |
| 1611 | #include <stdio.h> |
| 1612 | #include "valgrind.h" |
| 1613 | int I_WRAP_SONAME_FNNAME_ZU(NONE,foo)( int x, int y ) |
| 1614 | { |
| 1615 | int result; |
| 1616 | OrigFn fn; |
| 1617 | VALGRIND_GET_ORIG_FN(fn); |
| 1618 | printf("foo's wrapper: args %d %d\n", x, y); |
| 1619 | CALL_FN_W_WW(result, fn, x,y); |
| 1620 | printf("foo's wrapper: result %d\n", result); |
| 1621 | return result; |
| 1622 | } |
| 1623 | ]]></programlisting> |
| 1624 | |
| 1625 | <para>To become active, the wrapper merely needs to be present in a text |
| 1626 | section somewhere in the same process' address space as the function |
| 1627 | it wraps, and for its ELF symbol name to be visible to Valgrind. In |
| 1628 | practice, this means either compiling to a |
| 1629 | <computeroutput>.o</computeroutput> and linking it in, or |
| 1630 | compiling to a <computeroutput>.so</computeroutput> and |
| 1631 | <computeroutput>LD_PRELOAD</computeroutput>ing it in. The latter is more |
| 1632 | convenient in that it doesn't require relinking.</para> |
| 1633 | |
| 1634 | <para>All wrappers have approximately the above form. There are three |
| 1635 | crucial macros:</para> |
| 1636 | |
| 1637 | <para><computeroutput>I_WRAP_SONAME_FNNAME_ZU</computeroutput>: |
| 1638 | this generates the real name of the wrapper. |
| 1639 | This is an encoded name which Valgrind notices when reading symbol |
| 1640 | table information. What it says is: I am the wrapper for any function |
| 1641 | named <computeroutput>foo</computeroutput> which is found in |
| 1642 | an ELF shared object with an empty |
| 1643 | ("<computeroutput>NONE</computeroutput>") soname field. The specification |
| 1644 | mechanism is powerful in |
| 1645 | that wildcards are allowed for both sonames and function names. |
| 1646 | The details are discussed below.</para> |
| 1647 | |
| 1648 | <para><computeroutput>VALGRIND_GET_ORIG_FN</computeroutput>: |
mjw | 2be5122 | 2013-04-05 13:19:12 +0000 | [diff] [blame] | 1649 | once in the wrapper, the first priority is |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1650 | to get hold of the address of the original (and any other supporting |
| 1651 | information needed). This is stored in a value of opaque |
| 1652 | type <computeroutput>OrigFn</computeroutput>. |
| 1653 | The information is acquired using |
| 1654 | <computeroutput>VALGRIND_GET_ORIG_FN</computeroutput>. It is crucial |
| 1655 | to make this macro call before calling any other wrapped function |
| 1656 | in the same thread.</para> |
| 1657 | |
| 1658 | <para><computeroutput>CALL_FN_W_WW</computeroutput>: eventually we will |
| 1659 | want to call the function being |
| 1660 | wrapped. Calling it directly does not work, since that just gets us |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1661 | back to the wrapper and leads to an infinite loop. Instead, the result |
| 1662 | lvalue, |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1663 | <computeroutput>OrigFn</computeroutput> and arguments are |
| 1664 | handed to one of a family of macros of the form |
| 1665 | <computeroutput>CALL_FN_*</computeroutput>. These |
| 1666 | cause Valgrind to call the original and avoid recursion back to the |
| 1667 | wrapper.</para> |
| 1668 | </sect2> |
| 1669 | |
| 1670 | <sect2 id="manual-core-adv.wrapping.specs" xreflabel="Wrapping Specifications"> |
| 1671 | <title>Wrapping Specifications</title> |
| 1672 | |
| 1673 | <para>This scheme has the advantage of being self-contained. A library of |
| 1674 | wrappers can be compiled to object code in the normal way, and does |
| 1675 | not rely on an external script telling Valgrind which wrappers pertain |
| 1676 | to which originals.</para> |
| 1677 | |
| 1678 | <para>Each wrapper has a name which, in the most general case says: I am the |
| 1679 | wrapper for any function whose name matches FNPATT and whose ELF |
| 1680 | "soname" matches SOPATT. Both FNPATT and SOPATT may contain wildcards |
| 1681 | (asterisks) and other characters (spaces, dots, @, etc) which are not |
| 1682 | generally regarded as valid C identifier names.</para> |
| 1683 | |
| 1684 | <para>This flexibility is needed to write robust wrappers for POSIX pthread |
| 1685 | functions, where typically we are not completely sure of either the |
| 1686 | function name or the soname, or alternatively we want to wrap a whole |
| 1687 | set of functions at once.</para> |
| 1688 | |
| 1689 | <para>For example, <computeroutput>pthread_create</computeroutput> |
| 1690 | in GNU libpthread is usually a |
| 1691 | versioned symbol - one whose name ends in, eg, |
| 1692 | <computeroutput>@GLIBC_2.3</computeroutput>. Hence we |
| 1693 | are not sure what its real name is. We also want to cover any soname |
| 1694 | of the form <computeroutput>libpthread.so*</computeroutput>. |
| 1695 | So the header of the wrapper will be</para> |
| 1696 | |
| 1697 | <programlisting><![CDATA[ |
| 1698 | int I_WRAP_SONAME_FNNAME_ZZ(libpthreadZdsoZd0,pthreadZucreateZAZa) |
| 1699 | ( ... formals ... ) |
| 1700 | { ... body ... } |
| 1701 | ]]></programlisting> |
| 1702 | |
| 1703 | <para>In order to write unusual characters as valid C function names, a |
| 1704 | Z-encoding scheme is used. Names are written literally, except that |
| 1705 | a capital Z acts as an escape character, with the following encoding:</para> |
| 1706 | |
| 1707 | <programlisting><![CDATA[ |
| 1708 | Za encodes * |
| 1709 | Zp + |
| 1710 | Zc : |
| 1711 | Zd . |
| 1712 | Zu _ |
| 1713 | Zh - |
| 1714 | Zs (space) |
| 1715 | ZA @ |
| 1716 | ZZ Z |
| 1717 | ZL ( # only in valgrind 3.3.0 and later |
| 1718 | ZR ) # only in valgrind 3.3.0 and later |
| 1719 | ]]></programlisting> |
| 1720 | |
| 1721 | <para>Hence <computeroutput>libpthreadZdsoZd0</computeroutput> is an |
| 1722 | encoding of the soname <computeroutput>libpthread.so.0</computeroutput> |
| 1723 | and <computeroutput>pthreadZucreateZAZa</computeroutput> is an encoding |
| 1724 | of the function name <computeroutput>pthread_create@*</computeroutput>. |
| 1725 | </para> |
| 1726 | |
| 1727 | <para>The macro <computeroutput>I_WRAP_SONAME_FNNAME_ZZ</computeroutput> |
| 1728 | constructs a wrapper name in which |
| 1729 | both the soname (first component) and function name (second component) |
| 1730 | are Z-encoded. Encoding the function name can be tiresome and is |
| 1731 | often unnecessary, so a second macro, |
| 1732 | <computeroutput>I_WRAP_SONAME_FNNAME_ZU</computeroutput>, can be |
| 1733 | used instead. The <computeroutput>_ZU</computeroutput> variant is |
| 1734 | also useful for writing wrappers for |
| 1735 | C++ functions, in which the function name is usually already mangled |
| 1736 | using some other convention in which Z plays an important role. Having |
| 1737 | to encode a second time quickly becomes confusing.</para> |
| 1738 | |
| 1739 | <para>Since the function name field may contain wildcards, it can be |
| 1740 | anything, including just <computeroutput>*</computeroutput>. |
| 1741 | The same is true for the soname. |
| 1742 | However, some ELF objects - specifically, main executables - do not |
| 1743 | have sonames. Any object lacking a soname is treated as if its soname |
| 1744 | was <computeroutput>NONE</computeroutput>, which is why the original |
| 1745 | example above had a name |
| 1746 | <computeroutput>I_WRAP_SONAME_FNNAME_ZU(NONE,foo)</computeroutput>.</para> |
| 1747 | |
| 1748 | <para>Note that the soname of an ELF object is not the same as its |
| 1749 | file name, although it is often similar. You can find the soname of |
| 1750 | an object <computeroutput>libfoo.so</computeroutput> using the command |
| 1751 | <computeroutput>readelf -a libfoo.so | grep soname</computeroutput>.</para> |
| 1752 | </sect2> |
| 1753 | |
| 1754 | <sect2 id="manual-core-adv.wrapping.semantics" xreflabel="Wrapping Semantics"> |
| 1755 | <title>Wrapping Semantics</title> |
| 1756 | |
| 1757 | <para>The ability for a wrapper to replace an infinite family of functions |
| 1758 | is powerful but brings complications in situations where ELF objects |
| 1759 | appear and disappear (are dlopen'd and dlclose'd) on the fly. |
| 1760 | Valgrind tries to maintain sensible behaviour in such situations.</para> |
| 1761 | |
| 1762 | <para>For example, suppose a process has dlopened (an ELF object with |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1763 | soname) <filename>object1.so</filename>, which contains |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1764 | <computeroutput>function1</computeroutput>. It starts to use |
| 1765 | <computeroutput>function1</computeroutput> immediately.</para> |
| 1766 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1767 | <para>After a while it dlopens <filename>wrappers.so</filename>, |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1768 | which contains a wrapper |
| 1769 | for <computeroutput>function1</computeroutput> in (soname) |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1770 | <filename>object1.so</filename>. All subsequent calls to |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1771 | <computeroutput>function1</computeroutput> are rerouted to the wrapper.</para> |
| 1772 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1773 | <para>If <filename>wrappers.so</filename> is |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1774 | later dlclose'd, calls to <computeroutput>function1</computeroutput> are |
| 1775 | naturally routed back to the original.</para> |
| 1776 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1777 | <para>Alternatively, if <filename>object1.so</filename> |
| 1778 | is dlclose'd but <filename>wrappers.so</filename> remains, |
| 1779 | then the wrapper exported by <filename>wrappers.so</filename> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1780 | becomes inactive, since there |
| 1781 | is no way to get to it - there is no original to call any more. However, |
| 1782 | Valgrind remembers that the wrapper is still present. If |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1783 | <filename>object1.so</filename> is |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1784 | eventually dlopen'd again, the wrapper will become active again.</para> |
| 1785 | |
| 1786 | <para>In short, valgrind inspects all code loading/unloading events to |
| 1787 | ensure that the set of currently active wrappers remains consistent.</para> |
| 1788 | |
| 1789 | <para>A second possible problem is that of conflicting wrappers. It is |
| 1790 | easily possible to load two or more wrappers, both of which claim |
| 1791 | to be wrappers for some third function. In such cases Valgrind will |
| 1792 | complain about conflicting wrappers when the second one appears, and |
| 1793 | will honour only the first one.</para> |
| 1794 | </sect2> |
| 1795 | |
| 1796 | <sect2 id="manual-core-adv.wrapping.debugging" xreflabel="Debugging"> |
| 1797 | <title>Debugging</title> |
| 1798 | |
| 1799 | <para>Figuring out what's going on given the dynamic nature of wrapping |
| 1800 | can be difficult. The |
njn | f4b4758 | 2009-08-10 01:15:30 +0000 | [diff] [blame] | 1801 | <option>--trace-redir=yes</option> option makes |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1802 | this possible |
| 1803 | by showing the complete state of the redirection subsystem after |
| 1804 | every |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1805 | <function>mmap</function>/<function>munmap</function> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1806 | event affecting code (text).</para> |
| 1807 | |
| 1808 | <para>There are two central concepts:</para> |
| 1809 | |
| 1810 | <itemizedlist> |
| 1811 | |
| 1812 | <listitem><para>A "redirection specification" is a binding of |
| 1813 | a (soname pattern, fnname pattern) pair to a code address. |
| 1814 | These bindings are created by writing functions with names |
| 1815 | made with the |
| 1816 | <computeroutput>I_WRAP_SONAME_FNNAME_{ZZ,_ZU}</computeroutput> |
| 1817 | macros.</para></listitem> |
| 1818 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1819 | <listitem><para>An "active redirection" is a code-address to |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1820 | code-address binding currently in effect.</para></listitem> |
| 1821 | |
| 1822 | </itemizedlist> |
| 1823 | |
| 1824 | <para>The state of the wrapping-and-redirection subsystem comprises a set of |
| 1825 | specifications and a set of active bindings. The specifications are |
| 1826 | acquired/discarded by watching all |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1827 | <function>mmap</function>/<function>munmap</function> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1828 | events on code (text) |
| 1829 | sections. The active binding set is (conceptually) recomputed from |
| 1830 | the specifications, and all known symbol names, following any change |
| 1831 | to the specification set.</para> |
| 1832 | |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 1833 | <para><option>--trace-redir=yes</option> shows the contents |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1834 | of both sets following any such event.</para> |
| 1835 | |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 1836 | <para><option>-v</option> prints a line of text each |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1837 | time an active specification is used for the first time.</para> |
| 1838 | |
| 1839 | <para>Hence for maximum debugging effectiveness you will need to use both |
njn | f4b4758 | 2009-08-10 01:15:30 +0000 | [diff] [blame] | 1840 | options.</para> |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1841 | |
| 1842 | <para>One final comment. The function-wrapping facility is closely |
| 1843 | tied to Valgrind's ability to replace (redirect) specified |
| 1844 | functions, for example to redirect calls to |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1845 | <function>malloc</function> to its |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1846 | own implementation. Indeed, a replacement function can be |
| 1847 | regarded as a wrapper function which does not call the original. |
| 1848 | However, to make the implementation more robust, the two kinds |
| 1849 | of interception (wrapping vs replacement) are treated differently. |
| 1850 | </para> |
| 1851 | |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 1852 | <para><option>--trace-redir=yes</option> shows |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1853 | specifications and bindings for both |
| 1854 | replacement and wrapper functions. To differentiate the |
| 1855 | two, replacement bindings are printed using |
| 1856 | <computeroutput>R-></computeroutput> whereas |
| 1857 | wraps are printed using <computeroutput>W-></computeroutput>. |
| 1858 | </para> |
| 1859 | </sect2> |
| 1860 | |
| 1861 | |
| 1862 | <sect2 id="manual-core-adv.wrapping.limitations-cf" |
| 1863 | xreflabel="Limitations - control flow"> |
| 1864 | <title>Limitations - control flow</title> |
| 1865 | |
| 1866 | <para>For the most part, the function wrapping implementation is robust. |
| 1867 | The only important caveat is: in a wrapper, get hold of |
| 1868 | the <computeroutput>OrigFn</computeroutput> information using |
| 1869 | <computeroutput>VALGRIND_GET_ORIG_FN</computeroutput> before calling any |
| 1870 | other wrapped function. Once you have the |
| 1871 | <computeroutput>OrigFn</computeroutput>, arbitrary |
| 1872 | calls between, recursion between, and longjumps out of wrappers |
| 1873 | should work correctly. There is never any interaction between wrapped |
| 1874 | functions and merely replaced functions |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1875 | (eg <function>malloc</function>), so you can call |
| 1876 | <function>malloc</function> etc safely from within wrappers. |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1877 | </para> |
| 1878 | |
sewardj | ca456c7 | 2012-08-05 13:44:15 +0000 | [diff] [blame] | 1879 | <para>The above comments are true for {x86,amd64,ppc32,arm,mips32,s390}-linux. |
| 1880 | On |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1881 | ppc64-linux function wrapping is more fragile due to the (arguably |
| 1882 | poorly designed) ppc64-linux ABI. This mandates the use of a shadow |
| 1883 | stack which tracks entries/exits of both wrapper and replacement |
| 1884 | functions. This gives two limitations: firstly, longjumping out of |
| 1885 | wrappers will rapidly lead to disaster, since the shadow stack will |
| 1886 | not get correctly cleared. Secondly, since the shadow stack has |
| 1887 | finite size, recursion between wrapper/replacement functions is only |
| 1888 | possible to a limited depth, beyond which Valgrind has to abort the |
| 1889 | run. This depth is currently 16 calls.</para> |
| 1890 | |
sewardj | ca456c7 | 2012-08-05 13:44:15 +0000 | [diff] [blame] | 1891 | <para>For all platforms ({x86,amd64,ppc32,ppc64,arm,mips32,s390}-linux) |
| 1892 | all the above |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1893 | comments apply on a per-thread basis. In other words, wrapping is |
| 1894 | thread-safe: each thread must individually observe the above |
| 1895 | restrictions, but there is no need for any kind of inter-thread |
| 1896 | cooperation.</para> |
| 1897 | </sect2> |
| 1898 | |
| 1899 | |
| 1900 | <sect2 id="manual-core-adv.wrapping.limitations-sigs" |
| 1901 | xreflabel="Limitations - original function signatures"> |
| 1902 | <title>Limitations - original function signatures</title> |
| 1903 | |
| 1904 | <para>As shown in the above example, to call the original you must use a |
| 1905 | macro of the form <computeroutput>CALL_FN_*</computeroutput>. |
| 1906 | For technical reasons it is impossible |
| 1907 | to create a single macro to deal with all argument types and numbers, |
| 1908 | so a family of macros covering the most common cases is supplied. In |
| 1909 | what follows, 'W' denotes a machine-word-typed value (a pointer or a |
| 1910 | C <computeroutput>long</computeroutput>), |
| 1911 | and 'v' denotes C's <computeroutput>void</computeroutput> type. |
| 1912 | The currently available macros are:</para> |
| 1913 | |
| 1914 | <programlisting><![CDATA[ |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1915 | CALL_FN_v_v -- call an original of type void fn ( void ) |
| 1916 | CALL_FN_W_v -- call an original of type long fn ( void ) |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1917 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1918 | CALL_FN_v_W -- call an original of type void fn ( long ) |
| 1919 | CALL_FN_W_W -- call an original of type long fn ( long ) |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1920 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1921 | CALL_FN_v_WW -- call an original of type void fn ( long, long ) |
| 1922 | CALL_FN_W_WW -- call an original of type long fn ( long, long ) |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1923 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1924 | CALL_FN_v_WWW -- call an original of type void fn ( long, long, long ) |
| 1925 | CALL_FN_W_WWW -- call an original of type long fn ( long, long, long ) |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1926 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1927 | CALL_FN_W_WWWW -- call an original of type long fn ( long, long, long, long ) |
| 1928 | CALL_FN_W_5W -- call an original of type long fn ( long, long, long, long, long ) |
| 1929 | CALL_FN_W_6W -- call an original of type long fn ( long, long, long, long, long, long ) |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1930 | and so on, up to |
| 1931 | CALL_FN_W_12W |
| 1932 | ]]></programlisting> |
| 1933 | |
| 1934 | <para>The set of supported types can be expanded as needed. It is |
| 1935 | regrettable that this limitation exists. Function wrapping has proven |
| 1936 | difficult to implement, with a certain apparently unavoidable level of |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1937 | ickiness. After several implementation attempts, the present |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1938 | arrangement appears to be the least-worst tradeoff. At least it works |
| 1939 | reliably in the presence of dynamic linking and dynamic code |
| 1940 | loading/unloading.</para> |
| 1941 | |
| 1942 | <para>You should not attempt to wrap a function of one type signature with a |
| 1943 | wrapper of a different type signature. Such trickery will surely lead |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1944 | to crashes or strange behaviour. This is not a limitation |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1945 | of the function wrapping implementation, merely a reflection of the |
| 1946 | fact that it gives you sweeping powers to shoot yourself in the foot |
| 1947 | if you are not careful. Imagine the instant havoc you could wreak by |
| 1948 | writing a wrapper which matched any function name in any soname - in |
| 1949 | effect, one which claimed to be a wrapper for all functions in the |
| 1950 | process.</para> |
| 1951 | </sect2> |
| 1952 | |
| 1953 | <sect2 id="manual-core-adv.wrapping.examples" xreflabel="Examples"> |
| 1954 | <title>Examples</title> |
| 1955 | |
| 1956 | <para>In the source tree, |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1957 | <filename>memcheck/tests/wrap[1-8].c</filename> provide a series of |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1958 | examples, ranging from very simple to quite advanced.</para> |
| 1959 | |
njn | a437a60 | 2009-08-04 05:24:46 +0000 | [diff] [blame] | 1960 | <para><filename>mpi/libmpiwrap.c</filename> is an example |
sewardj | a5fac79 | 2007-11-25 00:55:11 +0000 | [diff] [blame] | 1961 | of wrapping a big, complex API (the MPI-2 interface). This file defines |
| 1962 | almost 300 different wrappers.</para> |
| 1963 | </sect2> |
| 1964 | |
| 1965 | </sect1> |
| 1966 | |
| 1967 | |
| 1968 | |
| 1969 | |
| 1970 | </chapter> |