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 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml
index cb79bdc..ceeee21 100644
--- a/callgrind/docs/cl-manual.xml
+++ b/callgrind/docs/cl-manual.xml
@@ -1078,7 +1078,7 @@
<sect1 id="cl-manual.monitor-commands" xreflabel="Callgrind Monitor Commands">
<title>Callgrind Monitor Commands</title>
<para>The Callgrind tool provides monitor commands handled by the Valgrind
-gdbserver (see <xref linkend="manual-core.gdbserver-commandhandling"/>).
+gdbserver (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>).
</para>
<itemizedlist>
diff --git a/docs/xml/manual-core-adv.xml b/docs/xml/manual-core-adv.xml
index 4d00ebf..a433984 100644
--- a/docs/xml/manual-core-adv.xml
+++ b/docs/xml/manual-core-adv.xml
@@ -273,6 +273,929 @@
+
+
+<sect1 id="manual-core-adv.gdbserver"
+ xreflabel="Debugging your program using Valgrind's gdbserver and GDB">
+<title>Debugging your program using Valgrind gdbserver and GDB</title>
+
+<para>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.
+</para>
+<para>
+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.
+</para>
+
+<sect2 id="manual-core-adv.gdbserver-simple"
+ xreflabel="gdbserver simple example">
+<title>Quick Start: debugging in 3 steps</title>
+
+<para>If you want to debug a program with GDB when using the Memcheck
+tool, start Valgrind the following way:
+<screen><![CDATA[
+valgrind --vgdb=yes --vgdb-error=0 prog
+]]></screen></para>
+
+<para>In another window, start a GDB the following way:
+<screen><![CDATA[
+gdb prog
+]]></screen></para>
+
+<para>Then give the following command to GDB:
+<screen><![CDATA[
+(gdb) target remote | vgdb
+]]></screen></para>
+
+<para>You can now debug your program e.g. by inserting a breakpoint
+and then using the GDB <computeroutput>continue</computeroutput>
+command.</para>
+
+<para>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 <option>--vgdb=yes</option> can be omitted,
+as this is the default value.
+</para>
+
+</sect2>
+
+<sect2 id="manual-core-adv.gdbserver-concept"
+ xreflabel="gdbserver">
+<title>Valgrind gdbserver overall organisation</title>
+<para>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.
+</para>
+
+<para>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.
+</para>
+
+<para>The Valgrind core provides a built-in gdbserver implementation,
+which is activated using <option>--vgdb=yes</option>
+or <option>--vgdb=full</option>. 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.
+</para>
+
+<para>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 <xref linkend="manual-core-adv.vgdb"/>, 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.
+</para>
+
+</sect2>
+
+<sect2 id="manual-core-adv.gdbserver-gdb"
+ xreflabel="Connecting GDB to a Valgrind gdbserver">
+<title>Connecting GDB to a Valgrind gdbserver</title>
+<para>To debug a program "<filename>prog</filename>" running under
+Valgrind, you must ensure that the Valgrind gdbserver is activated by
+specifying either <option>--vgdb=yes</option>
+or <option>--vgdb=full</option>). A secondary command line option,
+<option>--vgdb-error=number</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:
+<screen><![CDATA[
+valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
+]]></screen></para>
+
+<para>The Valgrind gdbserver is invoked at startup
+and indicates it is waiting for a connection from a GDB:</para>
+
+<programlisting><![CDATA[
+==2418== Memcheck, a memory error detector
+==2418== Copyright (C) 2002-2010, and GNU GPL'd, by Julian Seward et al.
+==2418== Using Valgrind-3.7.0.SVN and LibVEX; rerun with -h for copyright info
+==2418== Command: ./prog
+==2418==
+==2418== (action at startup) vgdb me ...
+]]></programlisting>
+
+
+<para>GDB (in another shell) can then be connected to the Valgrind gdbserver.
+For this, GDB must be started on the program <filename>prog</filename>:
+<screen><![CDATA[
+gdb ./prog
+]]></screen></para>
+
+
+<para>You then indicate to GDB that you want to debug a remote target:
+<screen><![CDATA[
+(gdb) target remote | vgdb
+]]></screen>
+GDB then starts a vgdb relay application to communicate with the
+Valgrind embedded gdbserver:</para>
+
+<programlisting><![CDATA[
+(gdb) target remote | vgdb
+Remote debugging using | vgdb
+relaying data between gdb and process 2418
+Reading symbols from /lib/ld-linux.so.2...done.
+Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done.
+Loaded symbols for /lib/ld-linux.so.2
+[Switching to Thread 2418]
+0x001f2850 in _start () from /lib/ld-linux.so.2
+(gdb)
+]]></programlisting>
+
+<para>Note that vgdb is provided as part of the Valgrind
+distribution. You do not need to install it separately.</para>
+
+<para>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:
+</para>
+
+<programlisting><![CDATA[
+(gdb) target remote | vgdb
+Remote debugging using | vgdb
+no --pid= arg given and multiple valgrind pids found:
+use --pid=2479 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
+use --pid=2481 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
+use --pid=2483 for valgrind --vgdb=yes --vgdb-error=0 ./another_prog
+Remote communication error: Resource temporarily unavailable.
+(gdb) target remote | vgdb --pid=2479
+Remote debugging using | vgdb --pid=2479
+relaying data between gdb and process 2479
+Reading symbols from /lib/ld-linux.so.2...done.
+Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done.
+Loaded symbols for /lib/ld-linux.so.2
+[Switching to Thread 2479]
+0x001f2850 in _start () from /lib/ld-linux.so.2
+(gdb)
+]]></programlisting>
+
+<para>Once GDB is connected to the Valgrind gdbserver, it can be used
+in the same way as if you were debugging the program natively:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Breakpoints can be inserted or deleted.</para>
+ </listitem>
+ <listitem>
+ <para>Variables and register values can be examined or modified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Signal handling can be configured (printing, ignoring).
+ </para>
+ </listitem>
+ <listitem>
+ <para>Execution can be controlled (continue, step, next, stepi, etc).
+ </para>
+ </listitem>
+ <listitem>
+ <para>Program execution can be interrupted using Control-C.</para>
+ </listitem>
+ </itemizedlist>
+
+<para>And so on. Refer to the GDB user manual for a complete
+description of GDB's functionality.
+</para>
+
+</sect2>
+
+<sect2 id="manual-core-adv.gdbserver-commandhandling"
+ xreflabel="Monitor command handling by the Valgrind gdbserver">
+<title>Monitor command handling by the Valgrind gdbserver</title>
+
+<para> 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
+<xref linkend="manual-core-adv.valgrind-monitor-commands"/> for the list
+of the Valgrind core monitor commands.
+</para>
+
+<para>Each tool can also provide tool-specific monitor commands.
+An example of a tool specific monitor command is the Memcheck monitor
+command <computeroutput>mc.leak_check any full
+reachable</computeroutput>. This requests a full reporting of the
+allocated memory blocks. To have this leak check executed, use the gdb
+command:
+<screen><![CDATA[
+(gdb) monitor mc.leak_check any full reachable
+]]></screen>
+</para>
+
+<para>GDB will send the <computeroutput>mc.leak_check</computeroutput>
+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:
+</para>
+<programlisting><![CDATA[
+(gdb) monitor mc.leak_check any full reachable
+==2418== 100 bytes in 1 blocks are still reachable in loss record 1 of 1
+==2418== at 0x4006E9E: malloc (vg_replace_malloc.c:236)
+==2418== by 0x804884F: main (prog.c:88)
+==2418==
+==2418== LEAK SUMMARY:
+==2418== definitely lost: 0 bytes in 0 blocks
+==2418== indirectly lost: 0 bytes in 0 blocks
+==2418== possibly lost: 0 bytes in 0 blocks
+==2418== still reachable: 100 bytes in 1 blocks
+==2418== suppressed: 0 bytes in 0 blocks
+==2418==
+(gdb)
+]]></programlisting>
+
+<para>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
+<computeroutput>mc.leak_check</computeroutput>
+command can also be typed as:
+<screen><![CDATA[
+(gdb) mo mc.l a f r
+]]></screen>
+
+The letters <computeroutput>mo</computeroutput> are recognised by GDB as being
+an abbreviation for <computeroutput>monitor</computeroutput>. So GDB sends the
+string <computeroutput>mc.l a f r</computeroutput> 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:
+<programlisting><![CDATA[
+(gdb) mo mc. a r f
+mc. can match mc.get_vbits mc.leak_check mc.make_memory mc.check_memory
+(gdb)
+]]></programlisting>
+</para>
+
+<para>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:
+<screen><![CDATA[
+vgdb --pid=3145 mc.leak_check any full reachable
+vgdb --pid=3145 mc.l a f r
+]]></screen></para>
+
+<para>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".</para>
+
+</sect2>
+
+<sect2 id="manual-core-adv.gdbserver-threads"
+ xreflabel="Valgrind gdbserver thread information">
+<title>Valgrind gdbserver thread information</title>
+
+<para>Valgrind's gdbserver enriches the output of the
+GDB <computeroutput>info threads</computeroutput> 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:</para>
+
+<programlisting><![CDATA[
+(gdb) info threads
+ 4 Thread 6239 (tid 4 VgTs_Yielding) 0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2
+* 3 Thread 6238 (tid 3 VgTs_Runnable) make_error (s=0x8048b76 "called from London") at prog.c:20
+ 2 Thread 6237 (tid 2 VgTs_WaitSys) 0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2
+ 1 Thread 6234 (tid 1 VgTs_Yielding) main (argc=1, argv=0xbedcc274) at prog.c:105
+(gdb)
+]]></programlisting>
+
+</sect2>
+
+<sect2 id="manual-core-adv.gdbserver-shadowregisters"
+ xreflabel="Examining and modifying Valgrind shadow registers">
+<title>Examining and modifying Valgrind shadow registers</title>
+
+<para> When the option <option>--vgdb-shadow-registers=yes</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.</para>
+
+<para>For each CPU register, the Valgrind core maintains two
+shadow registers. These shadow registers can be accessed from
+GDB by giving a postfix <computeroutput>s1</computeroutput>
+or <computeroutput>s2</computeroutput> for respectively the first
+and second shadow registers. For example, the x86 register
+<computeroutput>eax</computeroutput> and its two shadow
+registers can be examined using the following commands:</para>
+
+<programlisting><![CDATA[
+(gdb) p $eax
+$1 = 0
+(gdb) p $eaxs1
+$2 = 0
+(gdb) p $eaxs2
+$3 = 0
+(gdb)
+]]></programlisting>
+
+</sect2>
+
+
+<sect2 id="manual-core-adv.gdbserver-limitations"
+ xreflabel="Limitations of the Valgrind gdbserver">
+<title>Limitations of the Valgrind gdbserver</title>
+
+<para>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:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Precision of "stop-at" commands.</para>
+ <para>
+ GDB commands such as "step", "next", "stepi", breakpoints
+ and watchpoints, will stop the execution of the process. With
+ the option <option>--vgdb=yes</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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ If you use the option <option>--vgdb=full</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>--vgdb=no</option>. Option <option>--vgdb=yes</option>
+ has neglectible overhead compared
+ to <option>--vgdb=no</option>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Hardware watchpoint support by the Valgrind
+ gdbserver.</para>
+
+ <para> 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.
+ </para>
+ <para>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.
+ </para>
+ <para> 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.
+ </para>
+ <para>Write watchpoints might not be reported at the
+ exact instruction that writes the monitored area,
+ unless option <option>--vgdb=full</option> is given. Read watchpoints
+ will always be reported at the exact instruction reading the
+ watched memory.
+ </para>
+ <para> 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Stepping inside shared libraries on ARM.</para>
+ <para>For unknown reasons, stepping inside shared
+ libraries on ARM may fail. A workaround is to use the
+ <computeroutput>ldd</computeroutput> 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:
+ <programlisting><![CDATA[
+(gdb) shell ldd ./prog
+ libc.so.6 => /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)
+]]></programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>GDB version needed for ARM and PPC32/64.</para>
+ <para>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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Stack unwinding on PPC32/PPC64. </para>
+ <para>On PPC32/PPC64, stack unwinding for leaf functions
+ (functions that do not call any other functions) works properly
+ only when you give the option
+ <option>--vex-iropt-precise-memory-exns=yes</option>.
+ You must also pass this option in order to get a precise stack when
+ a signal is trapped by GDB.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Breakpoints encountered multiple times.</para>
+ <para>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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Execution of Inferior function calls by the Valgrind
+ gdbserver.</para>
+
+ <para>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:
+ </para>
+ <programlisting><![CDATA[
+(gdb) p printf("process being debugged has pid %d\n", getpid())
+$5 = 36
+(gdb)
+]]></programlisting>
+
+ <para>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 <computeroutput>vg.set vgdb-error</computeroutput> to set a
+ big value before the call, then manually reset it to its original
+ value when the call is complete.</para>
+
+ <para>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.</para>
+
+ <para>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.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>Connecting to or interrupting a Valgrind process blocked in
+ a system call.</para>
+
+ <para>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.</para>
+
+ <para>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.
+ </para>
+
+ <para>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 <option>--max-invoke-ms=0</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.
+ </para>
+
+ <para>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 <option>--vgdb-poll</option>. If your application is
+ blocked in system calls most of the time, using a very low value
+ for <option>--vgdb-poll</option> 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.
+ </para>
+
+ <para>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".
+ </para>
+
+ <para>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
+ <computeroutput>prctl(PR_SET_PTRACER, vgdb_pid, 0, 0,
+ 0)</computeroutput> to ensure vgdb can reliably use ptrace.
+ Once <computeroutput>vgdb_pid</computeroutput> 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 <option>--vgdb-error=0</option> to Valgrind.</para>
+
+ <para>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.
+ </para>
+
+ <para>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.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>Changing register values.</para>
+ <para>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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Unsupported GDB functionality.</para>
+ <para>GDB provides a lot of debugging functionality and not all
+ of it is supported. Specifically, the following are not
+ supported: reversible debugging and tracepoints.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Unknown limitations or problems.</para>
+ <para>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.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+</sect2>
+
+<sect2 id="manual-core-adv.vgdb"
+ xreflabel="vgdb">
+<title>vgdb command line options</title>
+<para> Usage: <computeroutput>vgdb [OPTION]... [[-c] COMMAND]...</computeroutput></para>
+
+<para> 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:
+</para>
+<orderedlist>
+ <listitem id="manual-core-adv.vgdb-standalone" xreflabel="vgdb standalone">
+ <para>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>-c</option> option.
+ </para>
+ </listitem>
+
+ <listitem id="manual-core-adv.vgdb-relay" xreflabel="vgdb relay">
+ <para>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.
+ </para>
+ </listitem>
+
+</orderedlist>
+
+<para><computeroutput>vgdb</computeroutput> accepts the following
+options:</para>
+<itemizedlist>
+ <listitem>
+ <para><option>--pid=<number></option>: 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 <option>--pid</option> argument is not given and multiple
+ Valgrind gdbserver processes are running, vgdb will report the
+ list of such processes and then exit.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>--vgdb-prefix</option> 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. </para>
+ </listitem>
+
+ <listitem>
+ <para><option>--max-invoke-ms=<number></option> 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.
+ </para>
+
+ <para>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 <option>--max-invoke-ms</option> value. For
+ example, for <option>--max-invoke-ms=5000</option>, the following
+ GDB command is suitable:
+ <screen><![CDATA[
+ (gdb) set remotetimeout 6
+ ]]></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><option>--wait=<number></option> 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 <option>--vgdb-prefix</option> that is
+ unique to the process you want to wait for.
+ Also, if you use the <option>--wait</option> argument in the GDB
+ "target remote" command, you must set the GDB remotetimeout to a
+ value bigger than the --wait argument value. See option
+ <option>--max-invoke-ms</option> (just above)
+ for an example of setting the remotetimeout value.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>-c</option> To give more than one command, separate
+ the commands by an option <option>-c</option>. Example:
+ <screen><![CDATA[
+vgdb vg.set log_output -c mc.leak_check any
+]]></screen></para>
+ </listitem>
+
+ <listitem>
+ <para><option>-d</option> instructs vgdb to produce debugging
+ output. Give multiple <option>-d</option> args to increase the
+ verbosity.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>-D</option> 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>-l</option> instructs vgdb to report the list of
+ the Valgrind gdbserver processes running and then exit.</para>
+ </listitem>
+</itemizedlist>
+
+</sect2>
+
+
+<sect2 id="manual-core-adv.valgrind-monitor-commands"
+ xreflabel="Valgrind monitor commands">
+<title>Valgrind monitor commands</title>
+
+<para>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.</para>
+
+<itemizedlist>
+ <listitem>
+ <para><varname>help [debug]</varname> 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.info all_errors</varname> shows all errors found
+ so far.</para>
+ </listitem>
+ <listitem>
+ <para><varname>vg.info last_error</varname> shows the last error
+ found.</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.info n_errs_found</varname> shows the number of
+ errors found so far and the current value of the
+ <option>--vgdb-error</option>
+ argument.</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.set {gdb_output | log_output |
+ mixed_output}</varname> allows redirection of the Valgrind output
+ (e.g. the errors detected by the tool). The default setting is
+ <computeroutput>mixed_output</computeroutput>.</para>
+
+ <para>With <computeroutput>mixed_output</computeroutput>, the
+ Valgrind output goes to the Valgrind log (typically stderr) while
+ the output of the interactive GDB monitor commands (e.g.
+ <computeroutput>vg.info last_error</computeroutput>)
+ is displayed by GDB.</para>
+
+ <para>With <computeroutput>gdb_output</computeroutput>, both the
+ Valgrind output and the interactive gdb monitor commands output are
+ displayed by gdb.</para>
+
+ <para>With <computeroutput>log_output</computeroutput>, both the
+ Valgrind output and the interactive gdb monitor commands output go
+ to the Valgrind log.</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.wait [ms (default 0)]</varname> 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.kill</varname> 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.set vgdb-error <errornr></varname>
+ dynamically changes the value of the
+ <option>--vgdb-error</option> argument. A
+ typical usage of this is to start with
+ <option>--vgdb-error=0</option> on the
+ command line, then set a few breakpoints, set the vgdb-error value
+ to a huge value and continue execution.</para>
+ </listitem>
+
+</itemizedlist>
+
+<para>The following Valgrind monitor commands are useful for
+investigating the behaviour of Valgrind or its gdbserver in case of
+problems or bugs.</para>
+
+<itemizedlist>
+
+ <listitem>
+ <para><varname>vg.info gdbserver_status</varname> 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
+ <computeroutput>set breakpoint always-inserted on</computeroutput>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.info memory</varname> shows the statistics of
+ Valgrind's internal heap management. If
+ option <option>--profile-heap=yes</option> was given, detailed
+ statistics will be output.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.set debuglog <intvalue></varname> 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>vg.translate <address>
+ [<traceflags>]</varname> shows the translation of the block
+ containing <computeroutput>address</computeroutput> with the given
+ trace flags. The <computeroutput>traceflags</computeroutput> value
+ bit pattern with similar meaning to Valgrind's
+ <option>--trace-flags</option> 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.</para>
+ <para>The additional bit flag 0b100000000 (bit 8)
+ has no equivalent in the <option>--trace-flags</option> 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.</para>
+ </listitem>
+
+</itemizedlist>
+
+</sect2>
+
+</sect1>
+
+
+
+
+
<sect1 id="manual-core-adv.wrapping" xreflabel="Function Wrapping">
<title>Function wrapping</title>
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
index 25f6724..614faff 100644
--- a/docs/xml/manual-core.xml
+++ b/docs/xml/manual-core.xml
@@ -730,15 +730,15 @@
or <option>--vgdb=full</option> is specified. This
allows an external GNU GDB debugger
to control and debug your program when it runs on Valgrind. See
- <xref linkend="manual-core.gdbserver"/> for a detailed
+ <xref linkend="manual-core-adv.gdbserver"/> for a detailed
description.
</para>
<para> If the embedded gdbserver is enabled but no gdb is
- currently being used, the <xref linkend="manual-core.vgdb"/>
+ currently being used, the <xref linkend="manual-core-adv.vgdb"/>
command line utility can send "monitor commands" to Valgrind
from a shell. The Valgrind core provides a set of
- <xref linkend="manual-core.valgrind-monitor-commands"/>. A tool
+ <xref linkend="manual-core-adv.valgrind-monitor-commands"/>. A tool
can optionally provide tool specific monitor commands, which are
documented in the tool specific chapter.
</para>
@@ -1822,922 +1822,6 @@
</sect1>
-<sect1 id="manual-core.gdbserver"
- xreflabel="Debugging your program using Valgrind's gdbserver and GDB">
-<title>Debugging your program using Valgrind gdbserver and GDB</title>
-
-<para>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.
-</para>
-<para>
-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.
-</para>
-
-<sect2 id="manual-core.gdbserver-simple"
- xreflabel="gdbserver simple example">
-<title>Quick Start: debugging in 3 steps</title>
-
-<para>If you want to debug a program with GDB when using the Memcheck
-tool, start Valgrind the following way:
-<screen><![CDATA[
-valgrind --vgdb=yes --vgdb-error=0 prog
-]]></screen></para>
-
-<para>In another window, start a GDB the following way:
-<screen><![CDATA[
-gdb prog
-]]></screen></para>
-
-<para>Then give the following command to GDB:
-<screen><![CDATA[
-(gdb) target remote | vgdb
-]]></screen></para>
-
-<para>You can now debug your program e.g. by inserting a breakpoint
-and then using the GDB <computeroutput>continue</computeroutput>
-command.</para>
-
-<para>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 <option>--vgdb=yes</option> can be omitted,
-as this is the default value.
-</para>
-
-</sect2>
-
-<sect2 id="manual-core.gdbserver-concept"
- xreflabel="gdbserver">
-<title>Valgrind gdbserver overall organisation</title>
-<para>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.
-</para>
-
-<para>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.
-</para>
-
-<para>The Valgrind core provides a built-in gdbserver implementation,
-which is activated using <option>--vgdb=yes</option>
-or <option>--vgdb=full</option>. 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.
-</para>
-
-<para>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 <xref linkend="manual-core.vgdb"/>, 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.
-</para>
-
-</sect2>
-
-<sect2 id="manual-core.gdbserver-gdb"
- xreflabel="Connecting GDB to a Valgrind gdbserver">
-<title>Connecting GDB to a Valgrind gdbserver</title>
-<para>To debug a program "<filename>prog</filename>" running under
-Valgrind, you must ensure that the Valgrind gdbserver is activated by
-specifying either <option>--vgdb=yes</option>
-or <option>--vgdb=full</option>). A secondary command line option,
-<option>--vgdb-error=number</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:
-<screen><![CDATA[
-valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
-]]></screen></para>
-
-<para>The Valgrind gdbserver is invoked at startup
-and indicates it is waiting for a connection from a GDB:</para>
-
-<programlisting><![CDATA[
-==2418== Memcheck, a memory error detector
-==2418== Copyright (C) 2002-2010, and GNU GPL'd, by Julian Seward et al.
-==2418== Using Valgrind-3.7.0.SVN and LibVEX; rerun with -h for copyright info
-==2418== Command: ./prog
-==2418==
-==2418== (action at startup) vgdb me ...
-]]></programlisting>
-
-
-<para>GDB (in another shell) can then be connected to the Valgrind gdbserver.
-For this, GDB must be started on the program <filename>prog</filename>:
-<screen><![CDATA[
-gdb ./prog
-]]></screen></para>
-
-
-<para>You then indicate to GDB that you want to debug a remote target:
-<screen><![CDATA[
-(gdb) target remote | vgdb
-]]></screen>
-GDB then starts a vgdb relay application to communicate with the
-Valgrind embedded gdbserver:</para>
-
-<programlisting><![CDATA[
-(gdb) target remote | vgdb
-Remote debugging using | vgdb
-relaying data between gdb and process 2418
-Reading symbols from /lib/ld-linux.so.2...done.
-Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done.
-Loaded symbols for /lib/ld-linux.so.2
-[Switching to Thread 2418]
-0x001f2850 in _start () from /lib/ld-linux.so.2
-(gdb)
-]]></programlisting>
-
-<para>Note that vgdb is provided as part of the Valgrind
-distribution. You do not need to install it separately.</para>
-
-<para>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:
-</para>
-
-<programlisting><![CDATA[
-(gdb) target remote | vgdb
-Remote debugging using | vgdb
-no --pid= arg given and multiple valgrind pids found:
-use --pid=2479 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
-use --pid=2481 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
-use --pid=2483 for valgrind --vgdb=yes --vgdb-error=0 ./another_prog
-Remote communication error: Resource temporarily unavailable.
-(gdb) target remote | vgdb --pid=2479
-Remote debugging using | vgdb --pid=2479
-relaying data between gdb and process 2479
-Reading symbols from /lib/ld-linux.so.2...done.
-Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done.
-Loaded symbols for /lib/ld-linux.so.2
-[Switching to Thread 2479]
-0x001f2850 in _start () from /lib/ld-linux.so.2
-(gdb)
-]]></programlisting>
-
-<para>Once GDB is connected to the Valgrind gdbserver, it can be used
-in the same way as if you were debugging the program natively:</para>
- <itemizedlist>
- <listitem>
- <para>Breakpoints can be inserted or deleted.</para>
- </listitem>
- <listitem>
- <para>Variables and register values can be examined or modified.
- </para>
- </listitem>
- <listitem>
- <para>Signal handling can be configured (printing, ignoring).
- </para>
- </listitem>
- <listitem>
- <para>Execution can be controlled (continue, step, next, stepi, etc).
- </para>
- </listitem>
- <listitem>
- <para>Program execution can be interrupted using Control-C.</para>
- </listitem>
- </itemizedlist>
-
-<para>And so on. Refer to the GDB user manual for a complete
-description of GDB's functionality.
-</para>
-
-</sect2>
-
-<sect2 id="manual-core.gdbserver-commandhandling"
- xreflabel="Monitor command handling by the Valgrind gdbserver">
-<title>Monitor command handling by the Valgrind gdbserver</title>
-
-<para> 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
-<xref linkend="manual-core.valgrind-monitor-commands"/> for the list
-of the Valgrind core monitor commands.
-</para>
-
-<para>Each tool can also provide tool-specific monitor commands.
-An example of a tool specific monitor command is the Memcheck monitor
-command <computeroutput>mc.leak_check any full
-reachable</computeroutput>. This requests a full reporting of the
-allocated memory blocks. To have this leak check executed, use the gdb
-command:
-<screen><![CDATA[
-(gdb) monitor mc.leak_check any full reachable
-]]></screen>
-</para>
-
-<para>GDB will send the <computeroutput>mc.leak_check</computeroutput>
-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:
-</para>
-<programlisting><![CDATA[
-(gdb) monitor mc.leak_check any full reachable
-==2418== 100 bytes in 1 blocks are still reachable in loss record 1 of 1
-==2418== at 0x4006E9E: malloc (vg_replace_malloc.c:236)
-==2418== by 0x804884F: main (prog.c:88)
-==2418==
-==2418== LEAK SUMMARY:
-==2418== definitely lost: 0 bytes in 0 blocks
-==2418== indirectly lost: 0 bytes in 0 blocks
-==2418== possibly lost: 0 bytes in 0 blocks
-==2418== still reachable: 100 bytes in 1 blocks
-==2418== suppressed: 0 bytes in 0 blocks
-==2418==
-(gdb)
-]]></programlisting>
-
-<para>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
-<computeroutput>mc.leak_check</computeroutput>
-command can also be typed as:
-<screen><![CDATA[
-(gdb) mo mc.l a f r
-]]></screen>
-
-The letters <computeroutput>mo</computeroutput> are recognised by GDB as being
-an abbreviation for <computeroutput>monitor</computeroutput>. So GDB sends the
-string <computeroutput>mc.l a f r</computeroutput> 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:
-<programlisting><![CDATA[
-(gdb) mo mc. a r f
-mc. can match mc.get_vbits mc.leak_check mc.make_memory mc.check_memory
-(gdb)
-]]></programlisting>
-</para>
-
-<para>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:
-<screen><![CDATA[
-vgdb --pid=3145 mc.leak_check any full reachable
-vgdb --pid=3145 mc.l a f r
-]]></screen></para>
-
-<para>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".</para>
-
-</sect2>
-
-<sect2 id="manual-core.gdbserver-threads"
- xreflabel="Valgrind gdbserver thread information">
-<title>Valgrind gdbserver thread information</title>
-
-<para>Valgrind's gdbserver enriches the output of the
-GDB <computeroutput>info threads</computeroutput> 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:</para>
-
-<programlisting><![CDATA[
-(gdb) info threads
- 4 Thread 6239 (tid 4 VgTs_Yielding) 0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2
-* 3 Thread 6238 (tid 3 VgTs_Runnable) make_error (s=0x8048b76 "called from London") at prog.c:20
- 2 Thread 6237 (tid 2 VgTs_WaitSys) 0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2
- 1 Thread 6234 (tid 1 VgTs_Yielding) main (argc=1, argv=0xbedcc274) at prog.c:105
-(gdb)
-]]></programlisting>
-
-</sect2>
-
-<sect2 id="manual-core.gdbserver-shadowregisters"
- xreflabel="Examining and modifying Valgrind shadow registers">
-<title>Examining and modifying Valgrind shadow registers</title>
-
-<para> When the option <option>--vgdb-shadow-registers=yes</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.</para>
-
-<para>For each CPU register, the Valgrind core maintains two
-shadow registers. These shadow registers can be accessed from
-GDB by giving a postfix <computeroutput>s1</computeroutput>
-or <computeroutput>s2</computeroutput> for respectively the first
-and second shadow registers. For example, the x86 register
-<computeroutput>eax</computeroutput> and its two shadow
-registers can be examined using the following commands:</para>
-
-<programlisting><![CDATA[
-(gdb) p $eax
-$1 = 0
-(gdb) p $eaxs1
-$2 = 0
-(gdb) p $eaxs2
-$3 = 0
-(gdb)
-]]></programlisting>
-
-</sect2>
-
-
-<sect2 id="manual-core.gdbserver-limitations"
- xreflabel="Limitations of the Valgrind gdbserver">
-<title>Limitations of the Valgrind gdbserver</title>
-
-<para>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:</para>
- <itemizedlist>
- <listitem>
- <para>Precision of "stop-at" commands.</para>
- <para>
- GDB commands such as "step", "next", "stepi", breakpoints
- and watchpoints, will stop the execution of the process. With
- the option <option>--vgdb=yes</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.
- </para>
- <para>
- 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.
- </para>
- <para>
- If you use the option <option>--vgdb=full</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>--vgdb=no</option>. Option <option>--vgdb=yes</option>
- has neglectible overhead compared
- to <option>--vgdb=no</option>.
- </para>
- </listitem>
-
- <listitem>
- <para>Hardware watchpoint support by the Valgrind
- gdbserver.</para>
-
- <para> 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.
- </para>
- <para>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.
- </para>
- <para> 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.
- </para>
- <para>Write watchpoints might not be reported at the
- exact instruction that writes the monitored area,
- unless option <option>--vgdb=full</option> is given. Read watchpoints
- will always be reported at the exact instruction reading the
- watched memory.
- </para>
- <para> 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.
- </para>
- </listitem>
-
- <listitem>
- <para>Stepping inside shared libraries on ARM.</para>
- <para>For unknown reasons, stepping inside shared
- libraries on ARM may fail. A workaround is to use the
- <computeroutput>ldd</computeroutput> 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:
- <programlisting><![CDATA[
-(gdb) shell ldd ./prog
- libc.so.6 => /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)
-]]></programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>GDB version needed for ARM and PPC32/64.</para>
- <para>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.
- </para>
- </listitem>
-
- <listitem>
- <para>Stack unwinding on PPC32/PPC64. </para>
- <para>On PPC32/PPC64, stack unwinding for leaf functions
- (functions that do not call any other functions) works properly
- only when you give the option
- <option>--vex-iropt-precise-memory-exns=yes</option>.
- You must also pass this option in order to get a precise stack when
- a signal is trapped by GDB.
- </para>
- </listitem>
-
- <listitem>
- <para>Breakpoints encountered multiple times.</para>
- <para>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.
- </para>
- </listitem>
-
- <listitem>
- <para>Execution of Inferior function calls by the Valgrind
- gdbserver.</para>
-
- <para>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:
- </para>
- <programlisting><![CDATA[
-(gdb) p printf("process being debugged has pid %d\n", getpid())
-$5 = 36
-(gdb)
-]]></programlisting>
-
- <para>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 <computeroutput>vg.set vgdb-error</computeroutput> to set a
- big value before the call, then manually reset it to its original
- value when the call is complete.</para>
-
- <para>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.</para>
-
- <para>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.
- </para>
-
- </listitem>
-
- <listitem>
- <para>Connecting to or interrupting a Valgrind process blocked in
- a system call.</para>
-
- <para>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.</para>
-
- <para>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.
- </para>
-
- <para>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 <option>--max-invoke-ms=0</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.
- </para>
-
- <para>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 <option>--vgdb-poll</option>. If your application is
- blocked in system calls most of the time, using a very low value
- for <option>--vgdb-poll</option> 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.
- </para>
-
- <para>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".
- </para>
-
- <para>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
- <computeroutput>prctl(PR_SET_PTRACER, vgdb_pid, 0, 0,
- 0)</computeroutput> to ensure vgdb can reliably use ptrace.
- Once <computeroutput>vgdb_pid</computeroutput> 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 <option>--vgdb-error=0</option> to Valgrind.</para>
-
- <para>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.
- </para>
-
- <para>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.
- </para>
-
- </listitem>
-
- <listitem>
- <para>Changing register values.</para>
- <para>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.
- </para>
- </listitem>
-
- <listitem>
- <para>Unsupported GDB functionality.</para>
- <para>GDB provides a lot of debugging functionality and not all
- of it is supported. Specifically, the following are not
- supported: reversible debugging and tracepoints.
- </para>
- </listitem>
-
- <listitem>
- <para>Unknown limitations or problems.</para>
- <para>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.
- </para>
- </listitem>
-
- </itemizedlist>
-
-</sect2>
-
-</sect1>
-
-<sect1 id="manual-core.vgdb"
- xreflabel="vgdb">
-<title>vgdb command line options</title>
-<para> Usage: <computeroutput>vgdb [OPTION]... [[-c] COMMAND]...</computeroutput></para>
-
-<para> 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:
-</para>
-<orderedlist>
- <listitem id="manual-core.vgdb-standalone" xreflabel="vgdb standalone">
- <para>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>-c</option> option.
- </para>
- </listitem>
-
- <listitem id="manual-core.vgdb-relay" xreflabel="vgdb relay">
- <para>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.
- </para>
- </listitem>
-
-</orderedlist>
-
-<para><computeroutput>vgdb</computeroutput> accepts the following
-options:</para>
-<itemizedlist>
- <listitem>
- <para><option>--pid=<number></option>: 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 <option>--pid</option> argument is not given and multiple
- Valgrind gdbserver processes are running, vgdb will report the
- list of such processes and then exit.</para>
- </listitem>
-
- <listitem>
- <para><option>--vgdb-prefix</option> 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. </para>
- </listitem>
-
- <listitem>
- <para><option>--max-invoke-ms=<number></option> 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.
- </para>
-
- <para>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 <option>--max-invoke-ms</option> value. For
- example, for <option>--max-invoke-ms=5000</option>, the following
- GDB command is suitable:
- <screen><![CDATA[
- (gdb) set remotetimeout 6
- ]]></screen>
- </para>
- </listitem>
-
- <listitem>
- <para><option>--wait=<number></option> 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 <option>--vgdb-prefix</option> that is
- unique to the process you want to wait for.
- Also, if you use the <option>--wait</option> argument in the GDB
- "target remote" command, you must set the GDB remotetimeout to a
- value bigger than the --wait argument value. See option
- <option>--max-invoke-ms</option> (just above)
- for an example of setting the remotetimeout value.</para>
- </listitem>
-
- <listitem>
- <para><option>-c</option> To give more than one command, separate
- the commands by an option <option>-c</option>. Example:
- <screen><![CDATA[
-vgdb vg.set log_output -c mc.leak_check any
-]]></screen></para>
- </listitem>
-
- <listitem>
- <para><option>-d</option> instructs vgdb to produce debugging
- output. Give multiple <option>-d</option> args to increase the
- verbosity.</para>
- </listitem>
-
- <listitem>
- <para><option>-D</option> 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.</para>
- </listitem>
-
- <listitem>
- <para><option>-l</option> instructs vgdb to report the list of
- the Valgrind gdbserver processes running and then exit.</para>
- </listitem>
-</itemizedlist>
-
-</sect1>
-
-
-<sect1 id="manual-core.valgrind-monitor-commands"
- xreflabel="Valgrind monitor commands">
-<title>Valgrind monitor commands</title>
-
-<para>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.</para>
-
-<itemizedlist>
- <listitem>
- <para><varname>help [debug]</varname> 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.
- </para>
- </listitem>
-
- <listitem>
- <para><varname>vg.info all_errors</varname> shows all errors found
- so far.</para>
- </listitem>
- <listitem>
- <para><varname>vg.info last_error</varname> shows the last error
- found.</para>
- </listitem>
-
- <listitem>
- <para><varname>vg.info n_errs_found</varname> shows the number of
- errors found so far and the current value of the
- <option>--vgdb-error</option>
- argument.</para>
- </listitem>
-
- <listitem>
- <para><varname>vg.set {gdb_output | log_output |
- mixed_output}</varname> allows redirection of the Valgrind output
- (e.g. the errors detected by the tool). The default setting is
- <computeroutput>mixed_output</computeroutput>.</para>
-
- <para>With <computeroutput>mixed_output</computeroutput>, the
- Valgrind output goes to the Valgrind log (typically stderr) while
- the output of the interactive GDB monitor commands (e.g.
- <computeroutput>vg.info last_error</computeroutput>)
- is displayed by GDB.</para>
-
- <para>With <computeroutput>gdb_output</computeroutput>, both the
- Valgrind output and the interactive gdb monitor commands output are
- displayed by gdb.</para>
-
- <para>With <computeroutput>log_output</computeroutput>, both the
- Valgrind output and the interactive gdb monitor commands output go
- to the Valgrind log.</para>
- </listitem>
-
- <listitem>
- <para><varname>vg.wait [ms (default 0)]</varname> 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.
- </para>
- </listitem>
-
- <listitem>
- <para><varname>vg.kill</varname> 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.</para>
- </listitem>
-
- <listitem>
- <para><varname>vg.set vgdb-error <errornr></varname>
- dynamically changes the value of the
- <option>--vgdb-error</option> argument. A
- typical usage of this is to start with
- <option>--vgdb-error=0</option> on the
- command line, then set a few breakpoints, set the vgdb-error value
- to a huge value and continue execution.</para>
- </listitem>
-
-</itemizedlist>
-
-<para>The following Valgrind monitor commands are useful for
-investigating the behaviour of Valgrind or its gdbserver in case of
-problems or bugs.</para>
-
-<itemizedlist>
-
- <listitem>
- <para><varname>vg.info gdbserver_status</varname> 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
- <computeroutput>set breakpoint always-inserted on</computeroutput>.
- </para>
- </listitem>
-
- <listitem>
- <para><varname>vg.info memory</varname> shows the statistics of
- Valgrind's internal heap management. If
- option <option>--profile-heap=yes</option> was given, detailed
- statistics will be output.
- </para>
- </listitem>
-
- <listitem>
- <para><varname>vg.set debuglog <intvalue></varname> 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.</para>
- </listitem>
-
- <listitem>
- <para><varname>vg.translate <address>
- [<traceflags>]</varname> shows the translation of the block
- containing <computeroutput>address</computeroutput> with the given
- trace flags. The <computeroutput>traceflags</computeroutput> value
- bit pattern with similar meaning to Valgrind's
- <option>--trace-flags</option> 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.</para>
- <para>The additional bit flag 0b100000000 (bit 8)
- has no equivalent in the <option>--trace-flags</option> 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.</para>
- </listitem>
-
-</itemizedlist>
-
-</sect1>
<sect1 id="manual-core.pthreads" xreflabel="Support for Threads">
<title>Support for Threads</title>
diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml
index 1389eb9..8402a55 100644
--- a/massif/docs/ms-manual.xml
+++ b/massif/docs/ms-manual.xml
@@ -861,7 +861,7 @@
<sect1 id="ms-manual.monitor-commands" xreflabel="Massif Monitor Commands">
<title>Massif Monitor Commands</title>
<para>The Massif tool provides monitor commands handled by the Valgrind
-gdbserver (see <xref linkend="manual-core.gdbserver-commandhandling"/>).
+gdbserver (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>).
</para>
<itemizedlist>
diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml
index 8c6294c..318179b 100644
--- a/memcheck/docs/mc-manual.xml
+++ b/memcheck/docs/mc-manual.xml
@@ -1273,7 +1273,7 @@
<sect1 id="mc-manual.monitor-commands" xreflabel="Memcheck Monitor Commands">
<title>Memcheck Monitor Commands</title>
<para>The Memcheck tool provides monitor commands handled by the Valgrind
-gdbserver (see <xref linkend="manual-core.gdbserver-commandhandling"/>).
+gdbserver (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>).
</para>
<itemizedlist>