zenithsiz/ftmemsim-valgrind
1
0
Fork 0
mirror of https://github.com/Zenithsiz/ftmemsim-valgrind.git synced 2026-02-03 18:13:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Move the GDBserver documentation from the "Valgrind core" chapter

Browse Source 
to the "Valgrind core: advanced topics" chapter.


git-svn-id: svn://svn.valgrind.org/valgrind/trunk@11821
This commit is contained in:
Julian Seward 2011-06-17 08:31:22 +00:00
parent 97024bcccb
commit 48d69a241a
5 changed files with 929 additions and 922 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
callgrind/docs/cl-manual.xml
View File

@ -1078,7 +1078,7 @@ Also see <xref linkend="cl-manual.cycles"/>.</para>
<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>

923
docs/xml/manual-core-adv.xml
View File

@ -273,6 +273,929 @@ tool-specific macros).</para>
<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=&lt;number&gt;</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=&lt;number&gt;</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=&lt;number&gt;</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 &lt;errornr&gt;</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 &lt;intvalue&gt;</varname> sets the
Valgrind debug log level to &lt;intvalue&gt;. This allows to
dynamically change the log level of Valgrind e.g. when a problem
is detected.</para>
</listitem>
<listitem>
<para><varname>vg.translate &lt;address&gt;
[&lt;traceflags&gt;]</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>

922
docs/xml/manual-core.xml
View File

@ -730,15 +730,15 @@ in most cases. We group the available options by rough categories.</para>
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 @@ don't understand
</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=&lt;number&gt;</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=&lt;number&gt;</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=&lt;number&gt;</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 &lt;errornr&gt;</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 &lt;intvalue&gt;</varname> sets the
Valgrind debug log level to &lt;intvalue&gt;. This allows to
dynamically change the log level of Valgrind e.g. when a problem
is detected.</para>
</listitem>
<listitem>
<para><varname>vg.translate &lt;address&gt;
[&lt;traceflags&gt;]</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>

2
massif/docs/ms-manual.xml
View File

@ -861,7 +861,7 @@ in a particular column, which makes following the allocation chains easier.
<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>

2
memcheck/docs/mc-manual.xml
View File

@ -1273,7 +1273,7 @@ is:</para>
<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>