From: Julian Seward Date: Fri, 17 Jun 2011 08:31:22 +0000 (+0000) Subject: Move the GDBserver documentation from the "Valgrind core" chapter X-Git-Tag: svn/VALGRIND_3_7_0~416 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=48d69a241a78398f0efe0718ae5c734fd5fbaad0;p=thirdparty%2Fvalgrind.git Move the GDBserver documentation from the "Valgrind core" chapter to the "Valgrind core: advanced topics" chapter. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@11821 --- diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index cb79bdc6b9..ceeee210b8 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -1078,7 +1078,7 @@ Also see . Callgrind Monitor Commands The Callgrind tool provides monitor commands handled by the Valgrind -gdbserver (see ). +gdbserver (see ). diff --git a/docs/xml/manual-core-adv.xml b/docs/xml/manual-core-adv.xml index 4d00ebfcda..a43398417f 100644 --- a/docs/xml/manual-core-adv.xml +++ b/docs/xml/manual-core-adv.xml @@ -273,6 +273,929 @@ tool-specific macros). + + + +Debugging your program using Valgrind gdbserver and GDB + +A program running under Valgrind is not executed directly by the +CPU. Instead it runs on a synthetic CPU provided by Valgrind. This is +why a debugger cannot debug your program when it runs on Valgrind. + + +This section describes how GDB can interact with the +Valgrind gdbserver to provide a fully debuggable program under +Valgrind. Used in this way, GDB also provides an interactive usage of +Valgrind core or tool functionalities, including incremental leak search +under Memcheck and on-demand Massif snapshot production. + + + +Quick Start: debugging in 3 steps + +If you want to debug a program with GDB when using the Memcheck +tool, start Valgrind the following way: + + +In another window, start a GDB the following way: + + +Then give the following command to GDB: + + +You can now debug your program e.g. by inserting a breakpoint +and then using the GDB continue +command. + +This quick start information is enough for basic usage of the +Valgrind gdbserver. The sections below describe more advanced +functionality provided by the combination of Valgrind and GDB. Note +that the command line flag can be omitted, +as this is the default value. + + + + + +Valgrind gdbserver overall organisation +The GNU GDB debugger is typically used to debug a process +running on the same machine. In this mode, GDB uses system calls to +control and query the program being debugged. This works well, but +only allows GDB to debug a program running on the same computer. + + +GDB can also debug processes running on a different computer. +To achieve this, GDB defines a protocol (that is, a set of query and +reply packets) that facilitates fetching the value of memory or +registers, setting breakpoints, etc. A gdbserver is an implementation +of this "GDB remote debugging" protocol. To debug a process running +on a remote computer, a gdbserver (sometimes called a GDB stub) +must run at the remote computer side. + + +The Valgrind core provides a built-in gdbserver implementation, +which is activated using +or . This gdbserver allows the process +running on Valgrind's synthetic CPU to be debugged remotely. +GDB sends protocol query packets (such as "get register contents") to +the Valgrind embedded gdbserver. The gdbserver executes the queries +(for example, it will get the register values of the synthetic CPU) +and gives the results back to GDB. + + +GDB can use various kinds of channels (TCP/IP, serial line, etc) +to communicate with the gdbserver. In the case of Valgrind's +gdbserver, communication is done via a pipe and a small helper program +called , which acts as an +intermediary. If no GDB is in use, vgdb can also be +used to send monitor commands to the Valgrind gdbserver from a shell +command line. + + + + + +Connecting GDB to a Valgrind gdbserver +To debug a program "prog" running under +Valgrind, you must ensure that the Valgrind gdbserver is activated by +specifying either +or ). A secondary command line option, +, can be used to tell the gdbserver +only to become active once the specified number of errors have been +reported. A value of zero will therefore cause +the gdbserver to become active at startup, which allows you to +insert breakpoints before starting the run. For example: + + +The Valgrind gdbserver is invoked at startup +and indicates it is waiting for a connection from a GDB: + + + + +GDB (in another shell) can then be connected to the Valgrind gdbserver. +For this, GDB must be started on the program prog: + + + +You then indicate to GDB that you want to debug a remote target: + +GDB then starts a vgdb relay application to communicate with the +Valgrind embedded gdbserver: + + + +Note that vgdb is provided as part of the Valgrind +distribution. You do not need to install it separately. + +If vgdb detects that there are multiple Valgrind gdbservers that +can be connected to, it will list all such servers and their PIDs, and +then exit. You can then reissue the GDB "target" command, but +specifying the PID the process you want to debug: + + + + +Once GDB is connected to the Valgrind gdbserver, it can be used +in the same way as if you were debugging the program natively: + + + Breakpoints can be inserted or deleted. + + + Variables and register values can be examined or modified. + + + + Signal handling can be configured (printing, ignoring). + + + + Execution can be controlled (continue, step, next, stepi, etc). + + + + Program execution can be interrupted using Control-C. + + + +And so on. Refer to the GDB user manual for a complete +description of GDB's functionality. + + + + + +Monitor command handling by the Valgrind gdbserver + + The Valgrind gdbserver provides additional Valgrind-specific +functionality via "monitor commands". Such monitor commands can +be sent from the GDB command line or from the shell command line. See + for the list +of the Valgrind core monitor commands. + + +Each tool can also provide tool-specific monitor commands. +An example of a tool specific monitor command is the Memcheck monitor +command mc.leak_check any full +reachable. This requests a full reporting of the +allocated memory blocks. To have this leak check executed, use the gdb +command: + + + +GDB will send the mc.leak_check +command to the Valgrind gdbserver. The Valgrind gdbserver will +execute the monitor command itself, if it recognises it to be a Valgrind core +monitor command. If it is not recognised as such, it is assumed to +be tool-specific and is handed to the tool for execution. For example: + + + +As with other GDB commands, the Valgrind gdbserver will accept +abbreviated monitor command names and arguments, as long as the given +abbreviation is unambiguous. For example, the above +mc.leak_check +command can also be typed as: + + +The letters mo are recognised by GDB as being +an abbreviation for monitor. So GDB sends the +string mc.l a f r to the Valgrind +gdbserver. The letters provided in this string are unambiguous for the +Valgrind gdbserver. This therefore gives the same output as the +unabbreviated command and arguments. If the provided abbreviation is +ambiguous, the Valgrind gdbserver will report the list of commands (or +argument values) that can match: + + + +Instead of sending a monitor command from GDB, you can also send +these from a shell command line. For example, the following command +lines, when given in a shell, will cause the same leak search to be executed +by the process 3145: + + +Note that the Valgrind gdbserver automatically continues the +execution of the program after a standalone invocation of +vgdb. Monitor commands sent from GDB do not cause the program to +continue: the program execution is controlled explicitly using GDB +commands such as "continue" or "next". + + + + +Valgrind gdbserver thread information + +Valgrind's gdbserver enriches the output of the +GDB info threads command +with Valgrind-specific information. +The operating system's thread number is followed +by Valgrind's internal index for that thread ("tid") and by +the Valgrind scheduler thread state: + + + + + + +Examining and modifying Valgrind shadow registers + + When the option is +given, the Valgrind gdbserver will let GDB examine and/or modify +Valgrind's shadow registers. GDB version 7.1 or later is needed for this +to work. + +For each CPU register, the Valgrind core maintains two +shadow registers. These shadow registers can be accessed from +GDB by giving a postfix s1 +or s2 for respectively the first +and second shadow registers. For example, the x86 register +eax and its two shadow +registers can be examined using the following commands: + + + + + + + +Limitations of the Valgrind gdbserver + +Debugging with the Valgrind gdbserver is very similar to native +debugging. Valgrind's gdbserver implementation is quite +complete, and so provides most of the GDB debugging functionality. There +are however some limitations and peculiarities: + + + Precision of "stop-at" commands. + + GDB commands such as "step", "next", "stepi", breakpoints + and watchpoints, will stop the execution of the process. With + the option , the process might not + stop at the exact requested instruction. Instead, it might + continue execution of the current basic block and stop at one + of the following basic blocks. This is linked to the fact that + Valgrind gdbserver has to instrument a block to allow stopping + at the exact instruction requested. Currently, + re-instrumentation the block currently being executed is not + supported. So, if the action requested by GDB (e.g. single + stepping or inserting a breakpoint) implies re-instrumentation + of the current block, the GDB action may not be executed + precisely. + + + This limitation applies when the basic block + currently being executed has not yet been instrumented for debugging. + This typically happens when the gdbserver is activated due to the + tool reporting an error or to a watchpoint. If the gdbserver + block has been activated following a breakpoint, or if a + breakpoint has been inserted in the block before its execution, + then the block has already been instrumented for debugging. + + + If you use the option , then GDB + "stop-at" commands will be obeyed precisely. The + downside is that this requires each instruction to be + instrumented with an additional call to a gdbserver helper + function, which gives considerable overhead compared to + . Option + has neglectible overhead compared + to . + + + + + Hardware watchpoint support by the Valgrind + gdbserver. + + The Valgrind gdbserver can simulate hardware watchpoints + if the selected tool provides support for it. Currently, + only Memcheck provides hardware watchpoint simulation. The + hardware watchpoint simulation provided by Memcheck is much + faster that GDB software watchpoints, which are implemented by + GDB checking the value of the watched zone(s) after each + instruction. Hardware watchpoint simulation also provides read + watchpoints. The hardware watchpoint simulation by Memcheck has + some limitations compared to real hardware + watchpoints. However, the number and length of simulated + watchpoints are not limited. + + Typically, the number of (real) hardware watchpoints is + limited. For example, the x86 architecture supports a maximum of + 4 hardware watchpoints, each watchpoint watching 1, 2, 4 or 8 + bytes. The Valgrind gdbserver does not have any limitation on the + number of simulated hardware watchpoints. It also has no + limitation on the length of the memory zone being + watched. However, GDB currently does not understand that + Valgrind gdbserver watchpoints have no length limit. A GDB patch + providing a command "set remote hardware-watchpoint-length-limit" + has been developped. Integration of this patch into GDB would + allow full use of the flexibility of the Valgrind gdbserver's + simulated hardware watchpoints. + + Memcheck implements hardware watchpoint simulation by + marking the watched address ranges as being unaddressable. When + a hardware watchpoint is removed, the range is marked as + addressable and defined. Hardware watchpoint simulation of + addressable-but-undefined memory zones works properly, but has + the undesirable side effect of marking the zone as defined when + the watchpoint is removed. + + Write watchpoints might not be reported at the + exact instruction that writes the monitored area, + unless option is given. Read watchpoints + will always be reported at the exact instruction reading the + watched memory. + + It is better to avoid using hardware watchpoint of not + addressable (yet) memory: in such a case, gdb will fallback to + extremely slow software watchpoints. Also, if you do not quit gdb + between two debugging sessions, the hardware watchpoints of the + previous sessions will be re-inserted as software watchpoints if + the watched memory zone is not addressable at program startup. + + + + + Stepping inside shared libraries on ARM. + For unknown reasons, stepping inside shared + libraries on ARM may fail. A workaround is to use the + ldd command + to find the list of shared libraries and their loading address + and inform GDB of the loading address using the GDB command + "add-symbol-file". Example: + /lib/libc.so.6 (0x4002c000) + /lib/ld-linux.so.3 (0x40000000) +(gdb) add-symbol-file /lib/libc.so.6 0x4002c000 +add symbol table from file "/lib/libc.so.6" at + .text_addr = 0x4002c000 +(y or n) y +Reading symbols from /lib/libc.so.6...(no debugging symbols found)...done. +(gdb) +]]> + + + + + GDB version needed for ARM and PPC32/64. + You must use a GDB version which is able to read XML + target description sent by a gdbserver. This is the standard setup + if GDB was configured and built "expat" + library. If your gdb was not configured with XML support, it + will report an error message when using the "target" + command. Debugging will not work because GDB will then not be + able to fetch the registers from the Valgrind gdbserver. + For ARM programs using the Thumb instruction set, you must use + a GDB version of 7.1 or later, as earlier versions have problems + with next/step/breakpoints in Thumb code. + + + + + Stack unwinding on PPC32/PPC64. + On PPC32/PPC64, stack unwinding for leaf functions + (functions that do not call any other functions) works properly + only when you give the option + . + You must also pass this option in order to get a precise stack when + a signal is trapped by GDB. + + + + + Breakpoints encountered multiple times. + Some instructions (e.g. x86 "rep movsb") + are translated by Valgrind using a loop. If a breakpoint is placed + on such an instruction, the breakpoint will be encountered + multiple times -- once for each step of the "implicit" loop + implementing the instruction. + + + + + Execution of Inferior function calls by the Valgrind + gdbserver. + + GDB allows the user to "call" functions inside the process + being debugged. Such calls are named "inferior calls" in the GDB + terminology. A typical use of an inferior call is to execute + a function that prints a human-readable version of a complex data + structure. To make an inferior call, use the GDB "print" command + followed by the function to call and its arguments. As an + example, the following gdb command causes an inferior call to the + libc "printf" function to be executed by the process + being debugged: + + + + The Valgrind gdbserver supports inferior function calls. + Whilst an inferior call is running, the Valgrind tool will report + errors as usual. If you do not want to have such errors stop the + execution of the inferior call, you can + use vg.set vgdb-error to set a + big value before the call, then manually reset it to its original + value when the call is complete. + + To execute inferior calls, GDB changes registers such as + the program counter, and then continues the execution of the + program. In a multithreaded program, all threads are continued, + not just the thread instructed to make the inferior call. If + another thread reports an error or encounters a breakpoint, the + evaluation of the inferior call is abandoned. + + Note that inferior function calls are a powerful GDB + feature, but should be used with caution. For example, if + the program being debugged is stopped inside the function "printf", + forcing a recursive call to printf via an inferior call will + very probably create problems. The Valgrind tool might also add + another level of complexity to inferior calls, e.g. by reporting + tool errors during the Inferior call or due to the + instrumentation done. + + + + + + Connecting to or interrupting a Valgrind process blocked in + a system call. + + Connecting to or interrupting a Valgrind process blocked in + a system call requires the "ptrace" system call to be usable. + This may be disabled in your kernel for security reasons. + + When running your program, Valgrind's scheduler + periodically checks whether there is any work to be handled by + the gdbserver. Unfortunately this check is only done if at least + one thread of the process is runnable. If all the threads of the + process are blocked in a system call, then the checks do not + happen, and the Valgrind scheduler will not invoke the gdbserver. + In such a case, the vgdb relay application will "force" the + gdbserver to be invoked, without the intervention of the Valgrind + scheduler. + + + Such forced invocation of the Valgrind gdbserver is + implemented by vgdb using ptrace system calls. On a properly + implemented kernel, the ptrace calls done by vgdb will not + influence the behaviour of the program running under Valgrind. + If however they do, giving the + option to the vgdb relay + application will disable the usage of ptrace calls. The + consequence of disabling ptrace usage in vgdb is that a Valgrind + process blocked in a system call cannot be woken up or + interrupted from GDB until it executes enough basic blocks to let + the Valgrind scheduler's normal checking take effect. + + + When ptrace is disabled in vgdb, you can increase the + responsiveness of the Valgrind gdbserver to commands or + interrupts by giving a lower value to the + option . If your application is + blocked in system calls most of the time, using a very low value + for will cause a the gdbserver to be + invoked sooner. The gdbserver polling done by Valgrind's + scheduler is very efficient, so the increased polling frequency + should not cause significant performance degradation. + + + When ptrace is disabled in vgdb, a query packet sent by GDB + may take significant time to be handled by the Valgrind + gdbserver. In such cases, GDB might encounter a protocol + timeout. To avoid this, + you can increase the value of the timeout by using the GDB + command "set remotetimeout". + + + Ubuntu versions 10.10 and later may restrict the scope of + ptrace to the children of the process calling ptrace. As the + Valgrind process is not a child of vgdb, such restricted scoping + causes the ptrace calls to fail. To avoid that, when Valgrind + gdbserver receives the first packet from a vgdb, it calls + prctl(PR_SET_PTRACER, vgdb_pid, 0, 0, + 0) to ensure vgdb can reliably use ptrace. + Once vgdb_pid has been marked as + a ptracer, vgdb can then properly force the invocation of + Valgrind gdbserver when needed. To ensure the vgdb is set as a + ptracer before the Valgrind process gets blocked in a system + call, connect your GDB to the Valgrind gdbserver at startup by + passing to Valgrind. + + Note that + this "set ptracer" technique does not solve the problem in the + case where a standalone vgdb process wants to connect to the + gdbserver, since the first command to be sent by a standalone + vgdb must wake up the Valgrind process before Valgrind gdbserver + will mark vgdb as a ptracer. + + + Unblocking a processes blocked in a system calls is not + currently implemented on Mac OS X. So you cannot connect to or + interrupt a process blocked in a system call on Mac OS X. + + + + + + Changing register values. + The Valgrind gdbserver will only modify the values of the a + thread's registers when the thread is in status Runnable or + Yielding. In other states (typically, WaitSys), attempts to + change register values will fail. Amongst other things, this + means that inferior calls are not executed for a thread which is + in a system call, since the Valgrind gdbserver does not implement + system call restart. + + + + + Unsupported GDB functionality. + GDB provides a lot of debugging functionality and not all + of it is supported. Specifically, the following are not + supported: reversible debugging and tracepoints. + + + + + Unknown limitations or problems. + The combination of GDB, Valgrind and the Valgrind gdbserver + probably has unknown other limitations and problems. If you + encounter strange or unexpected behaviour, feel free to report a + bug. But first please verify that the limitation or problem is + not inherent to GDB or the GDB remote protocol. You may be able + to do so by checking the behaviour when using standard gdbserver + part of the GDB package. + + + + + + + + +vgdb command line options + Usage: vgdb [OPTION]... [[-c] COMMAND]... + + vgdb ("Valgrind to GDB") is a small program that is used as an +intermediary between GDB and Valgrind. Normally you should not use it +directly. It has two usage modes: + + + + As a standalone utility, it is used from a shell command + line to send monitor commands to a process running under + Valgrind. For this usage, the vgdb OPTION(s) must be followed by + the monitor command to send. To send more than one command, + separate them with the option. + + + + + In combination with GDB "target remote |" command, it is + used as the relay application between GDB and the Valgrind + gdbserver. For this usage, only OPTION(s) can be given, but no + COMMAND can be given. + + + + + +vgdb accepts the following +options: + + + : specifies the PID of + the process to which vgdb must connect to. This option is useful + in case more than one Valgrind gdbserver can be connected to. If + the argument is not given and multiple + Valgrind gdbserver processes are running, vgdb will report the + list of such processes and then exit. + + + + must be given to both + Valgrind and vgdb if you want to change the default prefix for the + FIFOs (named pipes) used for communication between the Valgrind + gdbserver and vgdb. + + + + gives the + number of milliseconds after which vgdb will force the invocation + of gdbserver embedded in valgrind. The default value is 100 + milliseconds. A value of 0 disables forced invocation. + + + If you specify a large value, you might need to increase the + GDB "remotetimeout" value from its default value of 2 seconds. + You should ensure that the timeout (in seconds) is + bigger than the value. For + example, for , the following + GDB command is suitable: + + + + + + instructs vgdb to + search for available Valgrind gdbservers for the specified number + of seconds. This makes it possible start a vgdb process + before starting the Valgrind gdbserver with which you intend the + vgdb to communicate. This option is useful when used in + conjunction with a that is + unique to the process you want to wait for. + Also, if you use the argument in the GDB + "target remote" command, you must set the GDB remotetimeout to a + value bigger than the --wait argument value. See option + (just above) + for an example of setting the remotetimeout value. + + + + To give more than one command, separate + the commands by an option . Example: + + + + + instructs vgdb to produce debugging + output. Give multiple args to increase the + verbosity. + + + + instructs vgdb to show the state of the + shared memory used by the Valgrind gdbserver. vgdb will exit after + having shown the Valgrind gdbserver shared memory state. + + + + instructs vgdb to report the list of + the Valgrind gdbserver processes running and then exit. + + + + + + + +Valgrind monitor commands + +The Valgrind monitor commands are available regardless of the +Valgrind tool selected. They can be sent either from a shell command +line, by using a standalone vgdb, or from GDB, by using GDB's +"monitor" command. + + + + help [debug] instructs Valgrind's gdbserver + to give the list of all monitor commands of the Valgrind core and + of the tool. The optional "debug" argument tells to also give help + for the monitor commands aimed at Valgrind internals debugging. + + + + + vg.info all_errors shows all errors found + so far. + + + vg.info last_error shows the last error + found. + + + + vg.info n_errs_found shows the number of + errors found so far and the current value of the + + argument. + + + + vg.set {gdb_output | log_output | + mixed_output} allows redirection of the Valgrind output + (e.g. the errors detected by the tool). The default setting is + mixed_output. + + With mixed_output, the + Valgrind output goes to the Valgrind log (typically stderr) while + the output of the interactive GDB monitor commands (e.g. + vg.info last_error) + is displayed by GDB. + + With gdb_output, both the + Valgrind output and the interactive gdb monitor commands output are + displayed by gdb. + + With log_output, both the + Valgrind output and the interactive gdb monitor commands output go + to the Valgrind log. + + + + vg.wait [ms (default 0)] instructs + Valgrind gdbserver to sleep "ms" milli-seconds and then + continue. When sent from a standalone vgdb, if this is the last + command, the Valgrind process will continue the execution of the + guest process. The typical usage of this is to use vgdb to send a + "no-op" command to a Valgrind gdbserver so as to continue the + execution of the guess process. + + + + + vg.kill requests the gdbserver to kill + the process. This can be used from a standalone vgdb to properly + kill a Valgrind process which is currently expecting a vgdb + connection. + + + + vg.set vgdb-error <errornr> + dynamically changes the value of the + argument. A + typical usage of this is to start with + on the + command line, then set a few breakpoints, set the vgdb-error value + to a huge value and continue execution. + + + + +The following Valgrind monitor commands are useful for +investigating the behaviour of Valgrind or its gdbserver in case of +problems or bugs. + + + + + vg.info gdbserver_status shows the + gdbserver status. In case of problems (e.g. of communications), + this showns the values of some relevant Valgrind gdbserver internal + variables. Note that the variables related to breakpoints and + watchpoints (e.g. the number of breakpoint addresses and the number of + watchpoints) will be zero, as GDB by default removes all + watchpoints and breakpoints when execution stops, and re-inserts + them when resuming the execution of the debugged process. You can + change this gdb behaviour by using the GDB command + set breakpoint always-inserted on. + + + + + vg.info memory shows the statistics of + Valgrind's internal heap management. If + option was given, detailed + statistics will be output. + + + + + vg.set debuglog <intvalue> sets the + Valgrind debug log level to <intvalue>. This allows to + dynamically change the log level of Valgrind e.g. when a problem + is detected. + + + + vg.translate <address> + [<traceflags>] shows the translation of the block + containing address with the given + trace flags. The traceflags value + bit pattern with similar meaning to Valgrind's + option. It can be given + in hexadecimal (e.g. 0x20) or decimal (e.g. 32) or in binary 1s + and 0s bit (e.g. 0b00100000). The default value of the traceflags + is 0b00100000, corresponding to "show after instrumentation". + The output of this command always goes to the Valgrind + log. + The additional bit flag 0b100000000 (bit 8) + has no equivalent in the option. + It enables tracing of the gdbserver specific instrumentation. Note + that this bit 8 can only enable the addition of gdbserver + instrumentation in the trace. Setting it to 0 will not + disable the tracing of the gdbserver instrumentation if it is + active for some other reason, for example because there is a breakpoint at + this address or because gdbserver is in single stepping + mode. + + + + + + + + + + + + Function wrapping diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml index 25f6724068..614faff19d 100644 --- a/docs/xml/manual-core.xml +++ b/docs/xml/manual-core.xml @@ -730,15 +730,15 @@ in most cases. We group the available options by rough categories. or is specified. This allows an external GNU GDB debugger to control and debug your program when it runs on Valgrind. See - for a detailed + for a detailed description. If the embedded gdbserver is enabled but no gdb is - currently being used, the + currently being used, the command line utility can send "monitor commands" to Valgrind from a shell. The Valgrind core provides a set of - . A tool + . A tool can optionally provide tool specific monitor commands, which are documented in the tool specific chapter. @@ -1822,922 +1822,6 @@ don't understand - -Debugging your program using Valgrind gdbserver and GDB - -A program running under Valgrind is not executed directly by the -CPU. Instead it runs on a synthetic CPU provided by Valgrind. This is -why a debugger cannot debug your program when it runs on Valgrind. - - -This section describes how GDB can interact with the -Valgrind gdbserver to provide a fully debuggable program under -Valgrind. Used in this way, GDB also provides an interactive usage of -Valgrind core or tool functionalities, including incremental leak search -under Memcheck and on-demand Massif snapshot production. - - - -Quick Start: debugging in 3 steps - -If you want to debug a program with GDB when using the Memcheck -tool, start Valgrind the following way: - - -In another window, start a GDB the following way: - - -Then give the following command to GDB: - - -You can now debug your program e.g. by inserting a breakpoint -and then using the GDB continue -command. - -This quick start information is enough for basic usage of the -Valgrind gdbserver. The sections below describe more advanced -functionality provided by the combination of Valgrind and GDB. Note -that the command line flag can be omitted, -as this is the default value. - - - - - -Valgrind gdbserver overall organisation -The GNU GDB debugger is typically used to debug a process -running on the same machine. In this mode, GDB uses system calls to -control and query the program being debugged. This works well, but -only allows GDB to debug a program running on the same computer. - - -GDB can also debug processes running on a different computer. -To achieve this, GDB defines a protocol (that is, a set of query and -reply packets) that facilitates fetching the value of memory or -registers, setting breakpoints, etc. A gdbserver is an implementation -of this "GDB remote debugging" protocol. To debug a process running -on a remote computer, a gdbserver (sometimes called a GDB stub) -must run at the remote computer side. - - -The Valgrind core provides a built-in gdbserver implementation, -which is activated using -or . This gdbserver allows the process -running on Valgrind's synthetic CPU to be debugged remotely. -GDB sends protocol query packets (such as "get register contents") to -the Valgrind embedded gdbserver. The gdbserver executes the queries -(for example, it will get the register values of the synthetic CPU) -and gives the results back to GDB. - - -GDB can use various kinds of channels (TCP/IP, serial line, etc) -to communicate with the gdbserver. In the case of Valgrind's -gdbserver, communication is done via a pipe and a small helper program -called , which acts as an -intermediary. If no GDB is in use, vgdb can also be -used to send monitor commands to the Valgrind gdbserver from a shell -command line. - - - - - -Connecting GDB to a Valgrind gdbserver -To debug a program "prog" running under -Valgrind, you must ensure that the Valgrind gdbserver is activated by -specifying either -or ). A secondary command line option, -, can be used to tell the gdbserver -only to become active once the specified number of errors have been -reported. A value of zero will therefore cause -the gdbserver to become active at startup, which allows you to -insert breakpoints before starting the run. For example: - - -The Valgrind gdbserver is invoked at startup -and indicates it is waiting for a connection from a GDB: - - - - -GDB (in another shell) can then be connected to the Valgrind gdbserver. -For this, GDB must be started on the program prog: - - - -You then indicate to GDB that you want to debug a remote target: - -GDB then starts a vgdb relay application to communicate with the -Valgrind embedded gdbserver: - - - -Note that vgdb is provided as part of the Valgrind -distribution. You do not need to install it separately. - -If vgdb detects that there are multiple Valgrind gdbservers that -can be connected to, it will list all such servers and their PIDs, and -then exit. You can then reissue the GDB "target" command, but -specifying the PID the process you want to debug: - - - - -Once GDB is connected to the Valgrind gdbserver, it can be used -in the same way as if you were debugging the program natively: - - - Breakpoints can be inserted or deleted. - - - Variables and register values can be examined or modified. - - - - Signal handling can be configured (printing, ignoring). - - - - Execution can be controlled (continue, step, next, stepi, etc). - - - - Program execution can be interrupted using Control-C. - - - -And so on. Refer to the GDB user manual for a complete -description of GDB's functionality. - - - - - -Monitor command handling by the Valgrind gdbserver - - The Valgrind gdbserver provides additional Valgrind-specific -functionality via "monitor commands". Such monitor commands can -be sent from the GDB command line or from the shell command line. See - for the list -of the Valgrind core monitor commands. - - -Each tool can also provide tool-specific monitor commands. -An example of a tool specific monitor command is the Memcheck monitor -command mc.leak_check any full -reachable. This requests a full reporting of the -allocated memory blocks. To have this leak check executed, use the gdb -command: - - - -GDB will send the mc.leak_check -command to the Valgrind gdbserver. The Valgrind gdbserver will -execute the monitor command itself, if it recognises it to be a Valgrind core -monitor command. If it is not recognised as such, it is assumed to -be tool-specific and is handed to the tool for execution. For example: - - - -As with other GDB commands, the Valgrind gdbserver will accept -abbreviated monitor command names and arguments, as long as the given -abbreviation is unambiguous. For example, the above -mc.leak_check -command can also be typed as: - - -The letters mo are recognised by GDB as being -an abbreviation for monitor. So GDB sends the -string mc.l a f r to the Valgrind -gdbserver. The letters provided in this string are unambiguous for the -Valgrind gdbserver. This therefore gives the same output as the -unabbreviated command and arguments. If the provided abbreviation is -ambiguous, the Valgrind gdbserver will report the list of commands (or -argument values) that can match: - - - -Instead of sending a monitor command from GDB, you can also send -these from a shell command line. For example, the following command -lines, when given in a shell, will cause the same leak search to be executed -by the process 3145: - - -Note that the Valgrind gdbserver automatically continues the -execution of the program after a standalone invocation of -vgdb. Monitor commands sent from GDB do not cause the program to -continue: the program execution is controlled explicitly using GDB -commands such as "continue" or "next". - - - - -Valgrind gdbserver thread information - -Valgrind's gdbserver enriches the output of the -GDB info threads command -with Valgrind-specific information. -The operating system's thread number is followed -by Valgrind's internal index for that thread ("tid") and by -the Valgrind scheduler thread state: - - - - - - -Examining and modifying Valgrind shadow registers - - When the option is -given, the Valgrind gdbserver will let GDB examine and/or modify -Valgrind's shadow registers. GDB version 7.1 or later is needed for this -to work. - -For each CPU register, the Valgrind core maintains two -shadow registers. These shadow registers can be accessed from -GDB by giving a postfix s1 -or s2 for respectively the first -and second shadow registers. For example, the x86 register -eax and its two shadow -registers can be examined using the following commands: - - - - - - - -Limitations of the Valgrind gdbserver - -Debugging with the Valgrind gdbserver is very similar to native -debugging. Valgrind's gdbserver implementation is quite -complete, and so provides most of the GDB debugging functionality. There -are however some limitations and peculiarities: - - - Precision of "stop-at" commands. - - GDB commands such as "step", "next", "stepi", breakpoints - and watchpoints, will stop the execution of the process. With - the option , the process might not - stop at the exact requested instruction. Instead, it might - continue execution of the current basic block and stop at one - of the following basic blocks. This is linked to the fact that - Valgrind gdbserver has to instrument a block to allow stopping - at the exact instruction requested. Currently, - re-instrumentation the block currently being executed is not - supported. So, if the action requested by GDB (e.g. single - stepping or inserting a breakpoint) implies re-instrumentation - of the current block, the GDB action may not be executed - precisely. - - - This limitation applies when the basic block - currently being executed has not yet been instrumented for debugging. - This typically happens when the gdbserver is activated due to the - tool reporting an error or to a watchpoint. If the gdbserver - block has been activated following a breakpoint, or if a - breakpoint has been inserted in the block before its execution, - then the block has already been instrumented for debugging. - - - If you use the option , then GDB - "stop-at" commands will be obeyed precisely. The - downside is that this requires each instruction to be - instrumented with an additional call to a gdbserver helper - function, which gives considerable overhead compared to - . Option - has neglectible overhead compared - to . - - - - - Hardware watchpoint support by the Valgrind - gdbserver. - - The Valgrind gdbserver can simulate hardware watchpoints - if the selected tool provides support for it. Currently, - only Memcheck provides hardware watchpoint simulation. The - hardware watchpoint simulation provided by Memcheck is much - faster that GDB software watchpoints, which are implemented by - GDB checking the value of the watched zone(s) after each - instruction. Hardware watchpoint simulation also provides read - watchpoints. The hardware watchpoint simulation by Memcheck has - some limitations compared to real hardware - watchpoints. However, the number and length of simulated - watchpoints are not limited. - - Typically, the number of (real) hardware watchpoints is - limited. For example, the x86 architecture supports a maximum of - 4 hardware watchpoints, each watchpoint watching 1, 2, 4 or 8 - bytes. The Valgrind gdbserver does not have any limitation on the - number of simulated hardware watchpoints. It also has no - limitation on the length of the memory zone being - watched. However, GDB currently does not understand that - Valgrind gdbserver watchpoints have no length limit. A GDB patch - providing a command "set remote hardware-watchpoint-length-limit" - has been developped. Integration of this patch into GDB would - allow full use of the flexibility of the Valgrind gdbserver's - simulated hardware watchpoints. - - Memcheck implements hardware watchpoint simulation by - marking the watched address ranges as being unaddressable. When - a hardware watchpoint is removed, the range is marked as - addressable and defined. Hardware watchpoint simulation of - addressable-but-undefined memory zones works properly, but has - the undesirable side effect of marking the zone as defined when - the watchpoint is removed. - - Write watchpoints might not be reported at the - exact instruction that writes the monitored area, - unless option is given. Read watchpoints - will always be reported at the exact instruction reading the - watched memory. - - It is better to avoid using hardware watchpoint of not - addressable (yet) memory: in such a case, gdb will fallback to - extremely slow software watchpoints. Also, if you do not quit gdb - between two debugging sessions, the hardware watchpoints of the - previous sessions will be re-inserted as software watchpoints if - the watched memory zone is not addressable at program startup. - - - - - Stepping inside shared libraries on ARM. - For unknown reasons, stepping inside shared - libraries on ARM may fail. A workaround is to use the - ldd command - to find the list of shared libraries and their loading address - and inform GDB of the loading address using the GDB command - "add-symbol-file". Example: - /lib/libc.so.6 (0x4002c000) - /lib/ld-linux.so.3 (0x40000000) -(gdb) add-symbol-file /lib/libc.so.6 0x4002c000 -add symbol table from file "/lib/libc.so.6" at - .text_addr = 0x4002c000 -(y or n) y -Reading symbols from /lib/libc.so.6...(no debugging symbols found)...done. -(gdb) -]]> - - - - - GDB version needed for ARM and PPC32/64. - You must use a GDB version which is able to read XML - target description sent by a gdbserver. This is the standard setup - if GDB was configured and built "expat" - library. If your gdb was not configured with XML support, it - will report an error message when using the "target" - command. Debugging will not work because GDB will then not be - able to fetch the registers from the Valgrind gdbserver. - For ARM programs using the Thumb instruction set, you must use - a GDB version of 7.1 or later, as earlier versions have problems - with next/step/breakpoints in Thumb code. - - - - - Stack unwinding on PPC32/PPC64. - On PPC32/PPC64, stack unwinding for leaf functions - (functions that do not call any other functions) works properly - only when you give the option - . - You must also pass this option in order to get a precise stack when - a signal is trapped by GDB. - - - - - Breakpoints encountered multiple times. - Some instructions (e.g. x86 "rep movsb") - are translated by Valgrind using a loop. If a breakpoint is placed - on such an instruction, the breakpoint will be encountered - multiple times -- once for each step of the "implicit" loop - implementing the instruction. - - - - - Execution of Inferior function calls by the Valgrind - gdbserver. - - GDB allows the user to "call" functions inside the process - being debugged. Such calls are named "inferior calls" in the GDB - terminology. A typical use of an inferior call is to execute - a function that prints a human-readable version of a complex data - structure. To make an inferior call, use the GDB "print" command - followed by the function to call and its arguments. As an - example, the following gdb command causes an inferior call to the - libc "printf" function to be executed by the process - being debugged: - - - - The Valgrind gdbserver supports inferior function calls. - Whilst an inferior call is running, the Valgrind tool will report - errors as usual. If you do not want to have such errors stop the - execution of the inferior call, you can - use vg.set vgdb-error to set a - big value before the call, then manually reset it to its original - value when the call is complete. - - To execute inferior calls, GDB changes registers such as - the program counter, and then continues the execution of the - program. In a multithreaded program, all threads are continued, - not just the thread instructed to make the inferior call. If - another thread reports an error or encounters a breakpoint, the - evaluation of the inferior call is abandoned. - - Note that inferior function calls are a powerful GDB - feature, but should be used with caution. For example, if - the program being debugged is stopped inside the function "printf", - forcing a recursive call to printf via an inferior call will - very probably create problems. The Valgrind tool might also add - another level of complexity to inferior calls, e.g. by reporting - tool errors during the Inferior call or due to the - instrumentation done. - - - - - - Connecting to or interrupting a Valgrind process blocked in - a system call. - - Connecting to or interrupting a Valgrind process blocked in - a system call requires the "ptrace" system call to be usable. - This may be disabled in your kernel for security reasons. - - When running your program, Valgrind's scheduler - periodically checks whether there is any work to be handled by - the gdbserver. Unfortunately this check is only done if at least - one thread of the process is runnable. If all the threads of the - process are blocked in a system call, then the checks do not - happen, and the Valgrind scheduler will not invoke the gdbserver. - In such a case, the vgdb relay application will "force" the - gdbserver to be invoked, without the intervention of the Valgrind - scheduler. - - - Such forced invocation of the Valgrind gdbserver is - implemented by vgdb using ptrace system calls. On a properly - implemented kernel, the ptrace calls done by vgdb will not - influence the behaviour of the program running under Valgrind. - If however they do, giving the - option to the vgdb relay - application will disable the usage of ptrace calls. The - consequence of disabling ptrace usage in vgdb is that a Valgrind - process blocked in a system call cannot be woken up or - interrupted from GDB until it executes enough basic blocks to let - the Valgrind scheduler's normal checking take effect. - - - When ptrace is disabled in vgdb, you can increase the - responsiveness of the Valgrind gdbserver to commands or - interrupts by giving a lower value to the - option . If your application is - blocked in system calls most of the time, using a very low value - for will cause a the gdbserver to be - invoked sooner. The gdbserver polling done by Valgrind's - scheduler is very efficient, so the increased polling frequency - should not cause significant performance degradation. - - - When ptrace is disabled in vgdb, a query packet sent by GDB - may take significant time to be handled by the Valgrind - gdbserver. In such cases, GDB might encounter a protocol - timeout. To avoid this, - you can increase the value of the timeout by using the GDB - command "set remotetimeout". - - - Ubuntu versions 10.10 and later may restrict the scope of - ptrace to the children of the process calling ptrace. As the - Valgrind process is not a child of vgdb, such restricted scoping - causes the ptrace calls to fail. To avoid that, when Valgrind - gdbserver receives the first packet from a vgdb, it calls - prctl(PR_SET_PTRACER, vgdb_pid, 0, 0, - 0) to ensure vgdb can reliably use ptrace. - Once vgdb_pid has been marked as - a ptracer, vgdb can then properly force the invocation of - Valgrind gdbserver when needed. To ensure the vgdb is set as a - ptracer before the Valgrind process gets blocked in a system - call, connect your GDB to the Valgrind gdbserver at startup by - passing to Valgrind. - - Note that - this "set ptracer" technique does not solve the problem in the - case where a standalone vgdb process wants to connect to the - gdbserver, since the first command to be sent by a standalone - vgdb must wake up the Valgrind process before Valgrind gdbserver - will mark vgdb as a ptracer. - - - Unblocking a processes blocked in a system calls is not - currently implemented on Mac OS X. So you cannot connect to or - interrupt a process blocked in a system call on Mac OS X. - - - - - - Changing register values. - The Valgrind gdbserver will only modify the values of the a - thread's registers when the thread is in status Runnable or - Yielding. In other states (typically, WaitSys), attempts to - change register values will fail. Amongst other things, this - means that inferior calls are not executed for a thread which is - in a system call, since the Valgrind gdbserver does not implement - system call restart. - - - - - Unsupported GDB functionality. - GDB provides a lot of debugging functionality and not all - of it is supported. Specifically, the following are not - supported: reversible debugging and tracepoints. - - - - - Unknown limitations or problems. - The combination of GDB, Valgrind and the Valgrind gdbserver - probably has unknown other limitations and problems. If you - encounter strange or unexpected behaviour, feel free to report a - bug. But first please verify that the limitation or problem is - not inherent to GDB or the GDB remote protocol. You may be able - to do so by checking the behaviour when using standard gdbserver - part of the GDB package. - - - - - - - - - - -vgdb command line options - Usage: vgdb [OPTION]... [[-c] COMMAND]... - - vgdb ("Valgrind to GDB") is a small program that is used as an -intermediary between GDB and Valgrind. Normally you should not use it -directly. It has two usage modes: - - - - As a standalone utility, it is used from a shell command - line to send monitor commands to a process running under - Valgrind. For this usage, the vgdb OPTION(s) must be followed by - the monitor command to send. To send more than one command, - separate them with the option. - - - - - In combination with GDB "target remote |" command, it is - used as the relay application between GDB and the Valgrind - gdbserver. For this usage, only OPTION(s) can be given, but no - COMMAND can be given. - - - - - -vgdb accepts the following -options: - - - : specifies the PID of - the process to which vgdb must connect to. This option is useful - in case more than one Valgrind gdbserver can be connected to. If - the argument is not given and multiple - Valgrind gdbserver processes are running, vgdb will report the - list of such processes and then exit. - - - - must be given to both - Valgrind and vgdb if you want to change the default prefix for the - FIFOs (named pipes) used for communication between the Valgrind - gdbserver and vgdb. - - - - gives the - number of milliseconds after which vgdb will force the invocation - of gdbserver embedded in valgrind. The default value is 100 - milliseconds. A value of 0 disables forced invocation. - - - If you specify a large value, you might need to increase the - GDB "remotetimeout" value from its default value of 2 seconds. - You should ensure that the timeout (in seconds) is - bigger than the value. For - example, for , the following - GDB command is suitable: - - - - - - instructs vgdb to - search for available Valgrind gdbservers for the specified number - of seconds. This makes it possible start a vgdb process - before starting the Valgrind gdbserver with which you intend the - vgdb to communicate. This option is useful when used in - conjunction with a that is - unique to the process you want to wait for. - Also, if you use the argument in the GDB - "target remote" command, you must set the GDB remotetimeout to a - value bigger than the --wait argument value. See option - (just above) - for an example of setting the remotetimeout value. - - - - To give more than one command, separate - the commands by an option . Example: - - - - - instructs vgdb to produce debugging - output. Give multiple args to increase the - verbosity. - - - - instructs vgdb to show the state of the - shared memory used by the Valgrind gdbserver. vgdb will exit after - having shown the Valgrind gdbserver shared memory state. - - - - instructs vgdb to report the list of - the Valgrind gdbserver processes running and then exit. - - - - - - - -Valgrind monitor commands - -The Valgrind monitor commands are available regardless of the -Valgrind tool selected. They can be sent either from a shell command -line, by using a standalone vgdb, or from GDB, by using GDB's -"monitor" command. - - - - help [debug] instructs Valgrind's gdbserver - to give the list of all monitor commands of the Valgrind core and - of the tool. The optional "debug" argument tells to also give help - for the monitor commands aimed at Valgrind internals debugging. - - - - - vg.info all_errors shows all errors found - so far. - - - vg.info last_error shows the last error - found. - - - - vg.info n_errs_found shows the number of - errors found so far and the current value of the - - argument. - - - - vg.set {gdb_output | log_output | - mixed_output} allows redirection of the Valgrind output - (e.g. the errors detected by the tool). The default setting is - mixed_output. - - With mixed_output, the - Valgrind output goes to the Valgrind log (typically stderr) while - the output of the interactive GDB monitor commands (e.g. - vg.info last_error) - is displayed by GDB. - - With gdb_output, both the - Valgrind output and the interactive gdb monitor commands output are - displayed by gdb. - - With log_output, both the - Valgrind output and the interactive gdb monitor commands output go - to the Valgrind log. - - - - vg.wait [ms (default 0)] instructs - Valgrind gdbserver to sleep "ms" milli-seconds and then - continue. When sent from a standalone vgdb, if this is the last - command, the Valgrind process will continue the execution of the - guest process. The typical usage of this is to use vgdb to send a - "no-op" command to a Valgrind gdbserver so as to continue the - execution of the guess process. - - - - - vg.kill requests the gdbserver to kill - the process. This can be used from a standalone vgdb to properly - kill a Valgrind process which is currently expecting a vgdb - connection. - - - - vg.set vgdb-error <errornr> - dynamically changes the value of the - argument. A - typical usage of this is to start with - on the - command line, then set a few breakpoints, set the vgdb-error value - to a huge value and continue execution. - - - - -The following Valgrind monitor commands are useful for -investigating the behaviour of Valgrind or its gdbserver in case of -problems or bugs. - - - - - vg.info gdbserver_status shows the - gdbserver status. In case of problems (e.g. of communications), - this showns the values of some relevant Valgrind gdbserver internal - variables. Note that the variables related to breakpoints and - watchpoints (e.g. the number of breakpoint addresses and the number of - watchpoints) will be zero, as GDB by default removes all - watchpoints and breakpoints when execution stops, and re-inserts - them when resuming the execution of the debugged process. You can - change this gdb behaviour by using the GDB command - set breakpoint always-inserted on. - - - - - vg.info memory shows the statistics of - Valgrind's internal heap management. If - option was given, detailed - statistics will be output. - - - - - vg.set debuglog <intvalue> sets the - Valgrind debug log level to <intvalue>. This allows to - dynamically change the log level of Valgrind e.g. when a problem - is detected. - - - - vg.translate <address> - [<traceflags>] shows the translation of the block - containing address with the given - trace flags. The traceflags value - bit pattern with similar meaning to Valgrind's - option. It can be given - in hexadecimal (e.g. 0x20) or decimal (e.g. 32) or in binary 1s - and 0s bit (e.g. 0b00100000). The default value of the traceflags - is 0b00100000, corresponding to "show after instrumentation". - The output of this command always goes to the Valgrind - log. - The additional bit flag 0b100000000 (bit 8) - has no equivalent in the option. - It enables tracing of the gdbserver specific instrumentation. Note - that this bit 8 can only enable the addition of gdbserver - instrumentation in the trace. Setting it to 0 will not - disable the tracing of the gdbserver instrumentation if it is - active for some other reason, for example because there is a breakpoint at - this address or because gdbserver is in single stepping - mode. - - - - - Support for Threads diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index 1389eb9249..8402a55d99 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -861,7 +861,7 @@ in a particular column, which makes following the allocation chains easier. Massif Monitor Commands The Massif tool provides monitor commands handled by the Valgrind -gdbserver (see ). +gdbserver (see ). diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 8c6294c6fa..318179b252 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -1273,7 +1273,7 @@ is: Memcheck Monitor Commands The Memcheck tool provides monitor commands handled by the Valgrind -gdbserver (see ). +gdbserver (see ).