\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
@c Free Software Foundation, Inc.
@c
@c %**start of header
@copying
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2009 Free Software Foundation, Inc.
+Copyright (C) 1988-2010 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
* GDB/MI:: @value{GDBN}'s Machine Interface.
* Annotations:: @value{GDBN}'s annotation interface.
+* JIT Interface:: Using the JIT debugging interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
@value{GDBN}
* Operating System Information:: Getting additional information from
the operating system
+* Trace File Format:: GDB trace file format
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
who have worked on the Xtensa port of @value{GDBN} in the past include
Steve Tjiang, John Newlin, and Scott Foehner.
+Michael Eager and staff of Xilinx, Inc., contributed support for the
+Xilinx MicroBlaze architecture.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
@itemx -x @var{file}
@cindex @code{--command}
@cindex @code{-x}
-Execute @value{GDBN} commands from file @var{file}. @xref{Command
-Files,, Command files}.
+Execute commands from file @var{file}. The contents of this file is
+evaluated exactly as the @code{source} command would.
+@xref{Command Files,, Command files}.
@item -eval-command @var{command}
@itemx -ex @var{command}
@item apropos @var{args}
The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
-@var{args}. It prints out all matches found. For example:
+@var{args}. It prints out all matches found. For example:
@smallexample
apropos reload
* Attach:: Debugging an already-running process
* Kill Process:: Killing the child process
-* Inferiors:: Debugging multiple inferiors
+* Inferiors and Programs:: Debugging multiple inferiors and programs
* Threads:: Debugging programs with multiple threads
-* Processes:: Debugging programs with multiple processes
+* Forks:: Debugging forks
* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
@end menu
reads the symbol table again (while trying to preserve your current
breakpoint settings).
-@node Inferiors
-@section Debugging Multiple Inferiors
+@node Inferiors and Programs
+@section Debugging Multiple Inferiors and Programs
-Some @value{GDBN} targets are able to run multiple processes created
-from a single executable. This can happen, for instance, with an
-embedded system reporting back several processes via the remote
-protocol.
+@value{GDBN} lets you run and debug multiple programs in a single
+session. In addition, @value{GDBN} on some systems may let you run
+several programs simultaneously (otherwise you have to exit from one
+before starting another). In the most general case, you can have
+multiple threads of execution in each of multiple processes, launched
+from multiple executables.
@cindex inferior
@value{GDBN} represents the state of each program execution with an
object called an @dfn{inferior}. An inferior typically corresponds to
a process, but is more general and applies also to targets that do not
have processes. Inferiors may be created before a process runs, and
-may (in future) be retained after a process exits. Each run of an
-executable creates a new inferior, as does each attachment to an
-existing process. Inferiors have unique identifiers that are
-different from process ids, and may optionally be named as well.
-Usually each inferior will also have its own distinct address space,
-although some embedded targets may have several inferiors running in
-different parts of a single space.
+may be retained after a process exits. Inferiors have unique
+identifiers that are different from process ids. Usually each
+inferior will also have its own distinct address space, although some
+embedded targets may have several inferiors running in different parts
+of a single address space. Each inferior may in turn have multiple
+threads running in it.
-Each inferior may in turn have multiple threads running in it.
-
-To find out what inferiors exist at any moment, use @code{info inferiors}:
+To find out what inferiors exist at any moment, use @w{@code{info
+inferiors}}:
@table @code
@kindex info inferiors
@item info inferiors
Print a list of all inferiors currently being managed by @value{GDBN}.
+
+@value{GDBN} displays for each inferior (in this order):
+
+@enumerate
+@item
+the inferior number assigned by @value{GDBN}
+
+@item
+the target system's inferior identifier
+
+@item
+the name of the executable the inferior is running.
+
+@end enumerate
+
+@noindent
+An asterisk @samp{*} preceding the @value{GDBN} inferior number
+indicates the current inferior.
+
+For example,
@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info inferiors
+ Num Description Executable
+ 2 process 2307 hello
+* 1 process 3401 goodbye
+@end smallexample
To switch focus between inferiors, use the @code{inferior} command:
@table @code
-@kindex inferior @var{inferior-id}
-@item inferior @var{inferior-id}
-Make inferior number @var{inferior-id} the current inferior. The
-argument @var{inferior-id} is the internal inferior number assigned by
-@value{GDBN}, as shown in the first field of the @samp{info inferiors}
-display.
+@kindex inferior @var{infno}
+@item inferior @var{infno}
+Make inferior number @var{infno} the current inferior. The argument
+@var{infno} is the inferior number assigned by @value{GDBN}, as shown
+in the first field of the @samp{info inferiors} display.
+@end table
+
+
+You can get multiple executables into a debugging session via the
+@code{add-inferior} and @w{@code{clone-inferior}} commands. On some
+systems @value{GDBN} can add inferiors to the debug session
+automatically by following calls to @code{fork} and @code{exec}. To
+remove inferiors from the debugging session use the
+@w{@code{remove-inferior}} command.
+
+@table @code
+@kindex add-inferior
+@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
+Adds @var{n} inferiors to be run using @var{executable} as the
+executable. @var{n} defaults to 1. If no executable is specified,
+the inferiors begins empty, with no program. You can still assign or
+change the program assigned to the inferior at any time by using the
+@code{file} command with the executable name as its argument.
+
+@kindex clone-inferior
+@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
+Adds @var{n} inferiors ready to execute the same program as inferior
+@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
+number of the current inferior. This is a convenient command when you
+want to run another instance of the inferior you are debugging.
+
+@smallexample
+(@value{GDBP}) info inferiors
+ Num Description Executable
+* 1 process 29964 helloworld
+(@value{GDBP}) clone-inferior
+Added inferior 2.
+1 inferiors added.
+(@value{GDBP}) info inferiors
+ Num Description Executable
+ 2 <null> helloworld
+* 1 process 29964 helloworld
+@end smallexample
+
+You can now simply switch focus to inferior 2 and run it.
+
+@kindex remove-inferior
+@item remove-inferior @var{infno}
+Removes the inferior @var{infno}. It is not possible to remove an
+inferior that is running with this command. For those, use the
+@code{kill} or @code{detach} command first.
+
@end table
-To quit debugging one of the inferiors, you can either detach from it
-by using the @w{@code{detach inferior}} command (allowing it to run
-independently), or kill it using the @w{@code{kill inferior}} command:
+To quit debugging one of the running inferiors that is not the current
+inferior, you can either detach from it by using the @w{@code{detach
+inferior}} command (allowing it to run independently), or kill it
+using the @w{@code{kill inferior}} command:
@table @code
-@kindex detach inferior @var{inferior-id}
-@item detach inferior @var{inferior-id}
+@kindex detach inferior @var{infno}
+@item detach inferior @var{infno}
Detach from the inferior identified by @value{GDBN} inferior number
-@var{inferior-id}, and remove it from the inferior list.
+@var{infno}, and remove it from the inferior list.
-@kindex kill inferior @var{inferior-id}
-@item kill inferior @var{inferior-id}
+@kindex kill inferior @var{infno}
+@item kill inferior @var{infno}
Kill the inferior identified by @value{GDBN} inferior number
-@var{inferior-id}, and remove it from the inferior list.
+@var{infno}, and remove it from the inferior list.
@end table
+After the successful completion of a command such as @code{detach},
+@code{detach inferior}, @code{kill} or @code{kill inferior}, or after
+a normal process exit, the inferior is still valid and listed with
+@code{info inferiors}, ready to be restarted.
+
+
To be notified when inferiors are started or exit under @value{GDBN}'s
control use @w{@code{set print inferior-events}}:
inferiors have started, exited or have been detached.
@end table
+Many commands will work the same with multiple programs as with a
+single program: e.g., @code{print myglobal} will simply display the
+value of @code{myglobal} in the current inferior.
+
+
+Occasionaly, when debugging @value{GDBN} itself, it may be useful to
+get more info about the relationship of inferiors, programs, address
+spaces in a debug session. You can do that with the @w{@code{maint
+info program-spaces}} command.
+
+@table @code
+@kindex maint info program-spaces
+@item maint info program-spaces
+Print a list of all program spaces currently being managed by
+@value{GDBN}.
+
+@value{GDBN} displays for each program space (in this order):
+
+@enumerate
+@item
+the program space number assigned by @value{GDBN}
+
+@item
+the name of the executable loaded into the program space, with e.g.,
+the @code{file} command.
+
+@end enumerate
+
+@noindent
+An asterisk @samp{*} preceding the @value{GDBN} program space number
+indicates the current program space.
+
+In addition, below each program space line, @value{GDBN} prints extra
+information that isn't suitable to display in tabular form. For
+example, the list of inferiors bound to the program space.
+
+@smallexample
+(@value{GDBP}) maint info program-spaces
+ Id Executable
+ 2 goodbye
+ Bound inferiors: ID 1 (process 21561)
+* 1 hello
+@end smallexample
+
+Here we can see that no inferior is running the program @code{hello},
+while @code{process 21561} is running the program @code{goodbye}. On
+some targets, it is possible that multiple inferiors are bound to the
+same program space. The most common example is that of debugging both
+the parent and child processes of a @code{vfork} call. For example,
+
+@smallexample
+(@value{GDBP}) maint info program-spaces
+ Id Executable
+* 1 vfork-test
+ Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
+@end smallexample
+
+Here, both inferior 2 and inferior 1 are running in the same program
+space as a result of inferior 1 having executed a @code{vfork} call.
+@end table
+
@node Threads
@section Debugging Programs with Multiple Threads
Display current libthread_db search path.
@end table
-@node Processes
-@section Debugging Programs with Multiple Processes
+@node Forks
+@section Debugging Forks
@cindex fork, debugging programs which call
@cindex multiple processes
will retain control of all forked processes (including nested forks).
You can list the forked processes under the control of @value{GDBN} by
using the @w{@code{info inferiors}} command, and switch from one fork
-to another by using the @code{inferior} command (@pxref{Inferiors,
-,Debugging Multiple Inferiors}).
+to another by using the @code{inferior} command (@pxref{Inferiors and
+Programs, ,Debugging Multiple Inferiors and Programs}).
To quit debugging one of the forked processes, you can either detach
from it by using the @w{@code{detach inferior}} command (allowing it
to run independently), or kill it using the @w{@code{kill inferior}}
-command. @xref{Inferiors, ,Debugging Multiple Inferiors}.
+command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
+and Programs}.
If you ask to debug a child process and a @code{vfork} is followed by an
@code{exec}, @value{GDBN} executes the new target up to the first
cannot debug the child or parent until an @code{exec} call completes.
If you issue a @code{run} command to @value{GDBN} after an @code{exec}
-call executes, the new target restarts. To restart the parent process,
-use the @code{file} command with the parent executable name as its
-argument.
+call executes, the new target restarts. To restart the parent
+process, use the @code{file} command with the parent executable name
+as its argument. By default, after an @code{exec} call executes,
+@value{GDBN} discards the symbols of the previous executable image.
+You can change this behaviour with the @w{@code{set follow-exec-mode}}
+command.
+
+@table @code
+@kindex set follow-exec-mode
+@item set follow-exec-mode @var{mode}
+
+Set debugger response to a program call of @code{exec}. An
+@code{exec} call replaces the program image of a process.
+
+@code{follow-exec-mode} can be:
+
+@table @code
+@item new
+@value{GDBN} creates a new inferior and rebinds the process to this
+new inferior. The program the process was running before the
+@code{exec} call can be restarted afterwards by restarting the
+original inferior.
+
+For example:
+
+@smallexample
+(@value{GDBP}) info inferiors
+(gdb) info inferior
+ Id Description Executable
+* 1 <null> prog1
+(@value{GDBP}) run
+process 12020 is executing new program: prog2
+Program exited normally.
+(@value{GDBP}) info inferiors
+ Id Description Executable
+* 2 <null> prog2
+ 1 <null> prog1
+@end smallexample
+
+@item same
+@value{GDBN} keeps the process bound to the same inferior. The new
+executable image replaces the previous executable loaded in the
+inferior. Restarting the inferior after the @code{exec} call, with
+e.g., the @code{run} command, restarts the executable the process was
+running after the @code{exec} call. This is the default mode.
+
+For example:
+
+@smallexample
+(@value{GDBP}) info inferiors
+ Id Description Executable
+* 1 <null> prog1
+(@value{GDBP}) run
+process 12020 is executing new program: prog2
+Program exited normally.
+(@value{GDBP}) info inferiors
+ Id Description Executable
+* 1 <null> prog2
+@end smallexample
+
+@end table
+@end table
You can use the @code{catch} command to make @value{GDBN} stop whenever
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
A call to @code{exec}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
+@item syscall
+@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @r{...}
+@cindex break on a system call.
+A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
+syscall is a mechanism for application programs to request a service
+from the operating system (OS) or one of the OS system services.
+@value{GDBN} can catch some or all of the syscalls issued by the
+debuggee, and show the related information for each syscall. If no
+argument is specified, calls to and returns from all system calls
+will be caught.
+
+@var{name} can be any system call name that is valid for the
+underlying OS. Just what syscalls are valid depends on the OS. On
+GNU and Unix systems, you can find the full list of valid syscall
+names on @file{/usr/include/asm/unistd.h}.
+
+@c For MS-Windows, the syscall names and the corresponding numbers
+@c can be found, e.g., on this URL:
+@c http://www.metasploit.com/users/opcode/syscalls.html
+@c but we don't support Windows syscalls yet.
+
+Normally, @value{GDBN} knows in advance which syscalls are valid for
+each OS, so you can use the @value{GDBN} command-line completion
+facilities (@pxref{Completion,, command completion}) to list the
+available choices.
+
+You may also specify the system call numerically. A syscall's
+number is the value passed to the OS's syscall dispatcher to
+identify the requested service. When you specify the syscall by its
+name, @value{GDBN} uses its database of syscalls to convert the name
+into the corresponding numeric code, but using the number directly
+may be useful if @value{GDBN}'s database does not have the complete
+list of syscalls on your system (e.g., because @value{GDBN} lags
+behind the OS upgrades).
+
+The example below illustrates how this command works if you don't provide
+arguments to it:
+
+@smallexample
+(@value{GDBP}) catch syscall
+Catchpoint 1 (syscall)
+(@value{GDBP}) r
+Starting program: /tmp/catch-syscall
+
+Catchpoint 1 (call to syscall 'close'), \
+ 0xffffe424 in __kernel_vsyscall ()
+(@value{GDBP}) c
+Continuing.
+
+Catchpoint 1 (returned from syscall 'close'), \
+ 0xffffe424 in __kernel_vsyscall ()
+(@value{GDBP})
+@end smallexample
+
+Here is an example of catching a system call by name:
+
+@smallexample
+(@value{GDBP}) catch syscall chroot
+Catchpoint 1 (syscall 'chroot' [61])
+(@value{GDBP}) r
+Starting program: /tmp/catch-syscall
+
+Catchpoint 1 (call to syscall 'chroot'), \
+ 0xffffe424 in __kernel_vsyscall ()
+(@value{GDBP}) c
+Continuing.
+
+Catchpoint 1 (returned from syscall 'chroot'), \
+ 0xffffe424 in __kernel_vsyscall ()
+(@value{GDBP})
+@end smallexample
+
+An example of specifying a system call numerically. In the case
+below, the syscall number has a corresponding entry in the XML
+file, so @value{GDBN} finds its name and prints it:
+
+@smallexample
+(@value{GDBP}) catch syscall 252
+Catchpoint 1 (syscall(s) 'exit_group')
+(@value{GDBP}) r
+Starting program: /tmp/catch-syscall
+
+Catchpoint 1 (call to syscall 'exit_group'), \
+ 0xffffe424 in __kernel_vsyscall ()
+(@value{GDBP}) c
+Continuing.
+
+Program exited normally.
+(@value{GDBP})
+@end smallexample
+
+However, there can be situations when there is no corresponding name
+in XML file for that syscall number. In this case, @value{GDBN} prints
+a warning message saying that it was not able to find the syscall name,
+but the catchpoint will be set anyway. See the example below:
+
+@smallexample
+(@value{GDBP}) catch syscall 764
+warning: The number '764' does not represent a known syscall.
+Catchpoint 2 (syscall 764)
+(@value{GDBP})
+@end smallexample
+
+If you configure @value{GDBN} using the @samp{--without-expat} option,
+it will not be able to display syscall names. Also, if your
+architecture does not have an XML file describing its system calls,
+you will not be able to see the syscall names. It is important to
+notice that these two features are used for accessing the syscall
+name database. In either case, you will see a warning like this:
+
+@smallexample
+(@value{GDBP}) catch syscall
+warning: Could not open "syscalls/i386-linux.xml"
+warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
+GDB will not be able to display syscall names.
+Catchpoint 1 (syscall)
+(@value{GDBP})
+@end smallexample
+
+Of course, the file name will change depending on your architecture and system.
+
+Still using the example above, you can also try to catch a syscall by its
+number. In this case, you would see something like:
+
+@smallexample
+(@value{GDBP}) catch syscall 252
+Catchpoint 1 (syscall(s) 252)
+@end smallexample
+
+Again, in this case @value{GDBN} would not be able to display syscall's names.
+
@item fork
A call to @code{fork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
Break conditions can have side effects, and may even call functions in
your program. This can be useful, for example, to activate functions
that log program progress, or to use your own print functions to
-format special data structures. The effects are completely predictable
+format special data structures. The effects are completely predictable
unless there is another enabled breakpoint at the same address. (In
that case, @value{GDBN} might see the other breakpoint first and stop your
program without checking the condition of this one.) Note that
program.
You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before the
-breakpoint condition, like this:
+well; in this case, place @samp{thread @var{threadno}} before or
+after the breakpoint condition, like this:
@smallexample
(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
to the caller of that function, @emph{before} the function was called,
just as the normal @code{next} command would take you from the last
line of a function back to its return to its caller
-@footnote{Unles the code is too heavily optimized.}.
+@footnote{Unless the code is too heavily optimized.}.
@kindex reverse-nexti
@kindex rni @r{(@code{reverse-nexti})}
@item show record stop-at-limit
Show the current setting of @code{stop-at-limit}.
-@kindex info record insn-number
-@item info record insn-number
-Show the current number of recorded instructions.
+@kindex info record
+@item info record
+Show various statistics about the state of process record and its
+in-memory execution log buffer, including:
+
+@itemize @bullet
+@item
+Whether in record mode or replay mode.
+@item
+Lowest recorded instruction number (counting from when the current execution log started recording instructions).
+@item
+Highest recorded instruction number.
+@item
+Current instruction about to be replayed (if in replay mode).
+@item
+Number of instructions contained in the execution log.
+@item
+Maximum number of instructions that may be contained in the execution log.
+@end itemize
@kindex record delete
@kindex rec del
@cindex listing machine instructions
@item disassemble
@itemx disassemble /m
+@itemx disassemble /r
This specialized command dumps a range of memory as machine
instructions. It can also print mixed source+disassembly by specifying
-the @code{/m} modifier.
+the @code{/m} modifier and print the raw instructions in hex as well as
+in symbolic form by specifying the @code{/r}.
The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
-surrounding this value. Two arguments specify a range of addresses
-(first inclusive, second exclusive) to dump.
+surrounding this value. When two arguments are given, they should
+be separated by a comma, possibly surrounded by whitespace. The
+arguments specify a range of addresses (first inclusive, second exclusive)
+to dump. In that case, the name of the function is also printed (since
+there could be several functions in the given range).
+
+The argument(s) can be any expression yielding a numeric value, such as
+@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
+
+If the range of memory being disassembled contains current program counter,
+the instruction at that location is shown with a @code{=>} marker.
@end table
The following example shows the disassembly of a range of addresses of
HP PA-RISC 2.0 code:
@smallexample
-(@value{GDBP}) disas 0x32c4 0x32e4
+(@value{GDBP}) disas 0x32c4, 0x32e4
Dump of assembler code from 0x32c4 to 0x32e4:
-0x32c4 <main+204>: addil 0,dp
-0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
-0x32cc <main+212>: ldil 0x3000,r31
-0x32d0 <main+216>: ble 0x3f8(sr4,r31)
-0x32d4 <main+220>: ldo 0(r31),rp
-0x32d8 <main+224>: addil -0x800,dp
-0x32dc <main+228>: ldo 0x588(r1),r26
-0x32e0 <main+232>: ldil 0x3000,r31
+ 0x32c4 <main+204>: addil 0,dp
+ 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
+ 0x32cc <main+212>: ldil 0x3000,r31
+ 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
+ 0x32d4 <main+220>: ldo 0(r31),rp
+ 0x32d8 <main+224>: addil -0x800,dp
+ 0x32dc <main+228>: ldo 0x588(r1),r26
+ 0x32e0 <main+232>: ldil 0x3000,r31
End of assembler dump.
@end smallexample
-Here is an example showing mixed source+assembly for Intel x86:
+Here is an example showing mixed source+assembly for Intel x86, when the
+program is stopped just after function prologue:
@smallexample
(@value{GDBP}) disas /m main
Dump of assembler code for function main:
5 @{
-0x08048330 <main+0>: push %ebp
-0x08048331 <main+1>: mov %esp,%ebp
-0x08048333 <main+3>: sub $0x8,%esp
-0x08048336 <main+6>: and $0xfffffff0,%esp
-0x08048339 <main+9>: sub $0x10,%esp
+ 0x08048330 <+0>: push %ebp
+ 0x08048331 <+1>: mov %esp,%ebp
+ 0x08048333 <+3>: sub $0x8,%esp
+ 0x08048336 <+6>: and $0xfffffff0,%esp
+ 0x08048339 <+9>: sub $0x10,%esp
6 printf ("Hello.\n");
-0x0804833c <main+12>: movl $0x8048440,(%esp)
-
0x08048343 <main+19>: call 0x8048284 <puts@@plt>
+=> 0x0804833c <+12>: movl $0x8048440,(%esp)
+
0x08048343 <+19>: call 0x8048284 <puts@@plt>
7 return 0;
8 @}
-0x08048348 <main+24>: mov $0x0,%eax
-0x0804834d <main+29>: leave
-0x0804834e <main+30>: ret
+ 0x08048348 <+24>: mov $0x0,%eax
+ 0x0804834d <+29>: leave
+ 0x0804834e <+30>: ret
End of assembler dump.
@end smallexample
the repeat count @var{n} is used again; the other arguments default as
for successive uses of @code{x}.
+When examining machine instructions, the instruction at current program
+counter is shown with a @code{=>} marker. For example:
+
+@smallexample
+(@value{GDBP}) x/5i $pc-6
+ 0x804837f <main+11>: mov %esp,%ebp
+ 0x8048381 <main+13>: push %ecx
+ 0x8048382 <main+14>: sub $0x4,%esp
+=> 0x8048385 <main+17>: movl $0x8048460,(%esp)
+ 0x804838c <main+24>: call 0x80482d4 <puts@@plt>
+@end smallexample
+
@cindex @code{$_}, @code{$__}, and value history
The addresses and contents printed by the @code{x} command are not saved
in the value history because there is often too much of them and they
@item $_siginfo
@vindex $_siginfo@r{, convenience variable}
-The variable @code{$_siginfo} is bound to extra signal information
-inspection (@pxref{extra signal information}).
+The variable @code{$_siginfo} contains extra signal information
+(@pxref{extra signal information}). Note that @code{$_siginfo}
+could be empty, if the application has not yet received any signals.
+For example, it will be empty before you execute the @code{run} command.
@end table
On HP-UX systems, if you refer to a function or variable name that
@section Caching Data of Remote Targets
@cindex caching data of remote targets
-@value{GDBN} can cache data exchanged between the debugger and a
+@value{GDBN} caches data exchanged between the debugger and a
remote target (@pxref{Remote Debugging}). Such caching generally improves
performance, because it reduces the overhead of the remote protocol by
-bundling memory reads and writes into large chunks. Unfortunately,
-@value{GDBN} does not currently know anything about volatile
-registers, and thus data caching will produce incorrect results when
-volatile registers are in use.
+bundling memory reads and writes into large chunks. Unfortunately, simply
+caching everything would lead to incorrect results, since @value{GDBN}
+does not necessarily know anything about volatile values, memory-mapped I/O
+addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
+memory can be changed @emph{while} a gdb command is executing.
+Therefore, by default, @value{GDBN} only caches data
+known to be on the stack@footnote{In non-stop mode, it is moderately
+rare for a running thread to modify the stack of a stopped thread
+in a way that would interfere with a backtrace, and caching of
+stack reads provides a significant speed up of remote backtraces.}.
+Other regions of memory can be explicitly marked as
+cacheable; see @pxref{Memory Region Attributes}.
@table @code
@kindex set remotecache
@item set remotecache on
@itemx set remotecache off
-Set caching state for remote targets. When @code{ON}, use data
-caching. By default, this option is @code{OFF}.
+This option no longer does anything; it exists for compatibility
+with old scripts.
@kindex show remotecache
@item show remotecache
-Show the current state of data caching for remote targets.
+Show the current state of the obsolete remotecache flag.
+
+@kindex set stack-cache
+@item set stack-cache on
+@itemx set stack-cache off
+Enable or disable caching of stack accesses. When @code{ON}, use
+caching. By default, this option is @code{ON}.
+
+@kindex show stack-cache
+@item show stack-cache
+Show the current state of data caching for memory accesses.
@kindex info dcache
-@item info dcache
+@item info dcache @r{[}line@r{]}
Print the information about the data cache performance. The
-information displayed includes: the dcache width and depth; and for
-each cache line, how many times it was referenced, and its data and
-state (invalid, dirty, valid). This command is useful for debugging
-the data cache operation.
+information displayed includes the dcache width and depth, and for
+each cache line, its number, address, and how many times it was
+referenced. This command is useful for debugging the data cache
+operation.
+
+If a line number is specified, the contents of that line will be
+printed in hex.
@end table
@node Searching Memory
packets used to implement tracepoints are described in @ref{Tracepoint
Packets}.
+It is also possible to get trace data from a file, in a manner reminiscent
+of corefiles; you specify the filename, and use @code{tfind} to search
+through the file. @xref{Trace Files}, for more details.
+
This chapter describes the tracepoint commands and features.
@menu
* Set Tracepoints::
* Analyze Collected Data::
* Tracepoint Variables::
+* Trace Files::
@end menu
@node Set Tracepoints
tracepoints cannot run @value{GDBN} commands when they are
hit. Tracepoints may not be thread-specific either.
+@cindex fast tracepoints
+Some targets may support @dfn{fast tracepoints}, which are inserted in
+a different way (such as with a jump instead of a trap), that is
+faster but possibly restricted in where they may be installed.
+
This section describes commands to set tracepoints and associated
conditions and actions.
* Create and Delete Tracepoints::
* Enable and Disable Tracepoints::
* Tracepoint Passcounts::
+* Tracepoint Conditions::
+* Trace State Variables::
* Tracepoint Actions::
* Listing Tracepoints::
* Starting and Stopping Trace Experiments::
@noindent
You can abbreviate @code{trace} as @code{tr}.
+@item trace @var{location} if @var{cond}
+Set a tracepoint with condition @var{cond}; evaluate the expression
+@var{cond} each time the tracepoint is reached, and collect data only
+if the value is nonzero---that is, if @var{cond} evaluates as true.
+@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
+information on tracepoint conditions.
+
+@item ftrace @var{location} [ if @var{cond} ]
+@cindex set fast tracepoint
+@kindex ftrace
+The @code{ftrace} command sets a fast tracepoint. For targets that
+support them, fast tracepoints will use a more efficient but possibly
+less general technique to trigger data collection, such as a jump
+instruction instead of a trap, or some sort of hardware support. It
+may not be possible to create a fast tracepoint at the desired
+location, in which case the command will exit with an explanatory
+message.
+
+@value{GDBN} handles arguments to @code{ftrace} exactly as for
+@code{trace}.
+
@vindex $tpnum
@cindex last tracepoint number
@cindex recent tracepoint number
@end smallexample
@end table
+@node Tracepoint Conditions
+@subsection Tracepoint Conditions
+@cindex conditional tracepoints
+@cindex tracepoint conditions
+
+The simplest sort of tracepoint collects data every time your program
+reaches a specified place. You can also specify a @dfn{condition} for
+a tracepoint. A condition is just a Boolean expression in your
+programming language (@pxref{Expressions, ,Expressions}). A
+tracepoint with a condition evaluates the expression each time your
+program reaches it, and data collection happens only if the condition
+is true.
+
+Tracepoint conditions can be specified when a tracepoint is set, by
+using @samp{if} in the arguments to the @code{trace} command.
+@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can
+also be set or changed at any time with the @code{condition} command,
+just as with breakpoints.
+
+Unlike breakpoint conditions, @value{GDBN} does not actually evaluate
+the conditional expression itself. Instead, @value{GDBN} encodes the
+expression into an agent expression (@pxref{Agent Expressions}
+suitable for execution on the target, independently of @value{GDBN}.
+Global variables become raw memory locations, locals become stack
+accesses, and so forth.
+
+For instance, suppose you have a function that is usually called
+frequently, but should not be called after an error has occurred. You
+could use the following tracepoint command to collect data about calls
+of that function that happen while the error code is propagating
+through the program; an unconditional tracepoint could end up
+collecting thousands of useless trace frames that you would have to
+search through.
+
+@smallexample
+(@value{GDBP}) @kbd{trace normal_operation if errcode > 0}
+@end smallexample
+
+@node Trace State Variables
+@subsection Trace State Variables
+@cindex trace state variables
+
+A @dfn{trace state variable} is a special type of variable that is
+created and managed by target-side code. The syntax is the same as
+that for GDB's convenience variables (a string prefixed with ``$''),
+but they are stored on the target. They must be created explicitly,
+using a @code{tvariable} command. They are always 64-bit signed
+integers.
+
+Trace state variables are remembered by @value{GDBN}, and downloaded
+to the target along with tracepoint information when the trace
+experiment starts. There are no intrinsic limits on the number of
+trace state variables, beyond memory limitations of the target.
+
+@cindex convenience variables, and trace state variables
+Although trace state variables are managed by the target, you can use
+them in print commands and expressions as if they were convenience
+variables; @value{GDBN} will get the current value from the target
+while the trace experiment is running. Trace state variables share
+the same namespace as other ``$'' variables, which means that you
+cannot have trace state variables with names like @code{$23} or
+@code{$pc}, nor can you have a trace state variable and a convenience
+variable with the same name.
+
+@table @code
+
+@item tvariable $@var{name} [ = @var{expression} ]
+@kindex tvariable
+The @code{tvariable} command creates a new trace state variable named
+@code{$@var{name}}, and optionally gives it an initial value of
+@var{expression}. @var{expression} is evaluated when this command is
+entered; the result will be converted to an integer if possible,
+otherwise @value{GDBN} will report an error. A subsequent
+@code{tvariable} command specifying the same name does not create a
+variable, but instead assigns the supplied initial value to the
+existing variable of that name, overwriting any previous initial
+value. The default initial value is 0.
+
+@item info tvariables
+@kindex info tvariables
+List all the trace state variables along with their initial values.
+Their current values may also be displayed, if the trace experiment is
+currently running.
+
+@item delete tvariable @r{[} $@var{name} @dots{} @r{]}
+@kindex delete tvariable
+Delete the given trace state variables, or all of them if no arguments
+are specified.
+
+@end table
+
@node Tracepoint Actions
@subsection Tracepoint Action Lists
The command @code{info scope} (@pxref{Symbols, info scope}) is
particularly useful for figuring out what data to collect.
+@kindex teval @r{(tracepoints)}
+@item teval @var{expr1}, @var{expr2}, @dots{}
+Evaluate the given expressions when the tracepoint is hit. This
+command accepts a comma-separated list of expressions. The results
+are discarded, so this is mainly useful for assigning values to trace
+state variables (@pxref{Trace State Variables}) without adding those
+values to the trace buffer, as would be the case if the @code{collect}
+action were used.
+
@kindex while-stepping @r{(tracepoints)}
@item while-stepping @var{n}
Perform @var{n} single-step traces after the tracepoint, collecting
@noindent
You may abbreviate @code{while-stepping} as @code{ws} or
@code{stepping}.
+
+@item set default-collect @var{expr1}, @var{expr2}, @dots{}
+@kindex set default-collect
+@cindex default collection action
+This variable is a list of expressions to collect at each tracepoint
+hit. It is effectively an additional @code{collect} action prepended
+to every tracepoint action list. The expressions are parsed
+individually for each tracepoint, so for instance a variable named
+@code{xyz} may be interpreted as a global for one tracepoint, and a
+local for another, as appropriate to the tracepoint's location.
+
+@item show default-collect
+@kindex show default-collect
+Show the list of expressions that are collected by default at each
+tracepoint hit.
+
@end table
@node Listing Tracepoints
(@value{GDBP}) @b{tstop}
@end smallexample
+@cindex disconnected tracing
+You can choose to continue running the trace experiment even if
+@value{GDBN} disconnects from the target, voluntarily or
+involuntarily. For commands such as @code{detach}, the debugger will
+ask what you want to do with the trace. But for unexpected
+terminations (@value{GDBN} crash, network outage), it would be
+unfortunate to lose hard-won trace data, so the variable
+@code{disconnected-tracing} lets you decide whether the trace should
+continue running without @value{GDBN}.
+
+@table @code
+@item set disconnected-tracing on
+@itemx set disconnected-tracing off
+@kindex set disconnected-tracing
+Choose whether a tracing run should continue to run if @value{GDBN}
+has disconnected from the target. Note that @code{detach} or
+@code{quit} will ask you directly what to do about a running trace no
+matter what this variable's setting, so the variable is mainly useful
+for handling unexpected situations, such as loss of the network.
+
+@item show disconnected-tracing
+@kindex show disconnected-tracing
+Show the current choice for disconnected tracing.
+
+@end table
+
+When you reconnect to the target, the trace experiment may or may not
+still be running; it might have filled the trace buffer in the
+meantime, or stopped for one of the other reasons. If it is running,
+it will continue after reconnection.
+
+Upon reconnection, the target will upload information about the
+tracepoints in effect. @value{GDBN} will then compare that
+information to the set of tracepoints currently defined, and attempt
+to match them up, allowing for the possibility that the numbers may
+have changed due to creation and deletion in the meantime. If one of
+the target's tracepoints does not match any in @value{GDBN}, the
+debugger will create a new tracepoint, so that you have a number with
+which to specify that tracepoint. This matching-up process is
+necessarily heuristic, and it may result in useless tracepoints being
+created; you may simply delete them if they are of no use.
@node Analyze Collected Data
@section Using the Collected Data
Here's a simple example of using these convenience variables for
stepping through all the trace snapshots and printing some of their
-data.
+data. Note that these are not the same as trace state variables,
+which are managed by the target.
@smallexample
(@value{GDBP}) @b{tfind start}
> end
@end smallexample
+@node Trace Files
+@section Using Trace Files
+@cindex trace files
+
+In some situations, the target running a trace experiment may no
+longer be available; perhaps it crashed, or the hardware was needed
+for a different activity. To handle these cases, you can arrange to
+dump the trace data into a file, and later use that file as a source
+of trace data, via the @code{target tfile} command.
+
+@table @code
+
+@kindex tsave
+@item tsave [ -r ] @var{filename}
+Save the trace data to @var{filename}. By default, this command
+assumes that @var{filename} refers to the host filesystem, so if
+necessary @value{GDBN} will copy raw trace data up from the target and
+then save it. If the target supports it, you can also supply the
+optional argument @code{-r} (``remote'') to direct the target to save
+the data directly into @var{filename} in its own filesystem, which may be
+more efficient if the trace buffer is very large. (Note, however, that
+@code{target tfile} can only read from files accessible to the host.)
+
+@kindex target tfile
+@kindex tfile
+@item target tfile @var{filename}
+Use the file named @var{filename} as a source of trace data. Commands
+that examine data work as they do with a live target, but it is not
+possible to run any new trace experiments. @code{tstatus} will report
+the state of the trace run at the moment the data was saved, as well
+as the current trace frame you are examining. @var{filename} must be
+on a filesystem accessible to the host.
+
+@end table
+
@node Overlays
@chapter Debugging Programs That Use Overlays
@cindex overlays
There are two encodings in use, depending on the architecture: BID (Binary
Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
-PowerPC. @value{GDBN} will use the appropriate encoding for the configured
+PowerPC. @value{GDBN} will use the appropriate encoding for the configured
target.
Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
underflow, overflow and divide by zero exceptions.
In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers
-to inspect @code{_Decimal128} values stored in floating point registers. See
-@ref{PowerPC,,PowerPC} for more details.
+to inspect @code{_Decimal128} values stored in floating point registers.
+See @ref{PowerPC,,PowerPC} for more details.
@node Objective-C
@subsection Objective-C
@table @code
@item **
-The exponentiation operator. It raises the first operand to the power
+The exponentiation operator. It raises the first operand to the power
of the second one.
@item :
precedence as @code{*}.
@item -
-Negative. Defined on @code{INTEGER} and @code{REAL} data.
+Negative. Defined on @code{INTEGER} and @code{REAL} data.
@item ^
Pointer dereferencing. Defined on pointer types.
@code{Standard} explicitly.
@end itemize
+Older versions of the compiler sometimes generate erroneous debugging
+information, resulting in the debugger incorrectly printing the value
+of affected entities. In some cases, the debugger is able to work
+around an issue automatically. In other cases, the debugger is able
+to work around the issue, but the work-around has to be specifically
+enabled.
+
+@kindex set ada trust-PAD-over-XVS
+@kindex show ada trust-PAD-over-XVS
+@table @code
+
+@item set ada trust-PAD-over-XVS on
+Configure GDB to strictly follow the GNAT encoding when computing the
+value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS}
+types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for
+a complete description of the encoding used by the GNAT compiler).
+This is the default.
+
+@item set ada trust-PAD-over-XVS off
+This is related to the encoding using by the GNAT compiler. If @value{GDBN}
+sometimes prints the wrong value for certain entities, changing @code{ada
+trust-PAD-over-XVS} to @code{off} activates a work-around which may fix
+the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to
+@code{off}, but this incurs a slight performance penalty, so it is
+recommended to leave this setting to @code{on} unless necessary.
+
+@end table
+
@node Unsupported Languages
@section Unsupported Languages
@kindex info variables
@item info variables
-Print the names and data types of all variables that are declared
+Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
@item info variables @var{regexp}
@item show opaque-type-resolution
Show whether opaque types are resolved or not.
-@kindex set print symbol-loading
-@cindex print messages when symbols are loaded
-@item set print symbol-loading
-@itemx set print symbol-loading on
-@itemx set print symbol-loading off
-The @code{set print symbol-loading} command allows you to enable or
-disable printing of messages when @value{GDBN} loads symbols.
-By default, these messages will be printed, and normally this is what
-you want. Disabling these messages is useful when debugging applications
-with lots of shared libraries where the quantity of output can be more
-annoying than useful.
-
-@kindex show print symbol-loading
-@item show print symbol-loading
-Show whether messages will be printed when @value{GDBN} loads symbols.
-
@kindex maint print symbols
@cindex symbol dump
@kindex maint print psymbols
@kindex readnow
@cindex reading symbols immediately
@cindex symbols, reading immediately
-@item symbol-file @var{filename} @r{[} -readnow @r{]}
-@itemx file @var{filename} @r{[} -readnow @r{]}
+@item symbol-file @r{[} -readnow @r{]} @var{filename}
+@itemx file @r{[} -readnow @r{]} @var{filename}
You can override the @value{GDBN} two-stage strategy for reading symbol
tables by using the @samp{-readnow} option with any of the commands that
load symbol table information, if you want to be sure @value{GDBN} has the
@table @code
@kindex info sharedlibrary
@kindex info share
-@item info share
-@itemx info sharedlibrary
-Print the names of the shared libraries which are currently loaded.
+@item info share @var{regex}
+@itemx info sharedlibrary @var{regex}
+Print the names of the shared libraries which are currently loaded
+that match @var{regex}. If @var{regex} is omitted then print
+all shared libraries that are loaded.
@kindex sharedlibrary
@kindex share
usually @file{@var{executable}.debug}, where @var{executable} is the
name of the corresponding executable file without leading directories
(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
-debug link specifies a CRC32 checksum for the debug file, which
-@value{GDBN} uses to validate that the executable and the debug file
-came from the same build.
+debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC)
+checksum for the debug file, which @value{GDBN} uses to validate that
+the executable and the debug file came from the same build.
@item
The executable contains a @dfn{build ID}, a unique bit string that is
@table @code
@kindex set debug-file-directory
-@item set debug-file-directory @var{directory}
-Set the directory which @value{GDBN} searches for separate debugging
-information files to @var{directory}.
+@item set debug-file-directory @var{directories}
+Set the directories which @value{GDBN} searches for separate debugging
+information files to @var{directory}. Multiple directory components can be set
+concatenating them by a directory separator.
@kindex show debug-file-directory
@item show debug-file-directory
-Show the directory @value{GDBN} searches for separate debugging
+Show the directories @value{GDBN} searches for separate debugging
information files.
@end table
@noindent
-Since there are many different ways to compute CRC's for the debug
-link (different polynomials, reversals, byte ordering, etc.), the
-simplest way to describe the CRC used in @code{.gnu_debuglink}
-sections is to give the complete code for a function that computes it:
+@cindex CRC algorithm definition
+The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in
+IEEE 802.3 using the polynomial:
+
+@c TexInfo requires naked braces for multi-digit exponents for Tex
+@c output, but this causes HTML output to barf. HTML has to be set using
+@c raw commands. So we end up having to specify this equation in 2
+@c different ways!
+@ifhtml
+@display
+@html
+ <em>x</em><sup>32</sup> + <em>x</em><sup>26</sup> + <em>x</em><sup>23</sup> + <em>x</em><sup>22</sup> + <em>x</em><sup>16</sup> + <em>x</em><sup>12</sup> + <em>x</em><sup>11</sup>
+ + <em>x</em><sup>10</sup> + <em>x</em><sup>8</sup> + <em>x</em><sup>7</sup> + <em>x</em><sup>5</sup> + <em>x</em><sup>4</sup> + <em>x</em><sup>2</sup> + <em>x</em> + 1
+@end html
+@end display
+@end ifhtml
+@ifnothtml
+@display
+ @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}}
+ @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1}
+@end display
+@end ifnothtml
+
+The function is computed byte at a time, taking the least
+significant bit of each byte first. The initial pattern
+@code{0xffffffff} is used, to ensure leading zeros affect the CRC and
+the final result is inverted to ensure trailing zeros also affect the
+CRC.
+
+@emph{Note:} This is the same CRC polynomial as used in handling the
+@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{Remote Protocol,
+, @value{GDBN} Remote Serial Protocol}). However in the
+case of the Remote Serial Protocol, the CRC is computed @emph{most}
+significant bit first, and the result is not inverted, so trailing
+zeros have no effect on the CRC value.
+
+To complete the description, we show below the code of the function
+which produces the CRC used in @code{.gnu_debuglink}. Inverting the
+initially supplied @code{crc} argument means that an initial call to
+this function passing in zero will start computing the CRC using
+@code{0xffffffff}.
@kindex gnu_debuglink_crc32
@smallexample
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor set libthread-db-search-path [PATH]
+@cindex gdbserver, search path for @code{libthread_db}
+When this command is issued, @var{path} is a colon-separated list of
+directories to search for @code{libthread_db} (@pxref{Threads,,set
+libthread-db-search-path}). If you omit @var{path},
+@samp{libthread-db-search-path} will be reset to an empty list.
+
@item monitor exit
Tell gdbserver to exit immediately. This command should be followed by
@code{disconnect} to close the debugging session. @code{gdbserver} will
target system. If it is not set, the target will use a default
filename (e.g.@: the last program run).
+@item set remote interrupt-sequence
+@cindex interrupt remote programs
+@cindex select Ctrl-C, BREAK or BREAK-g
+Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or
+@samp{BREAK-g} as the
+sequence to the remote target in order to interrupt the execution.
+@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which
+is high level of serial line for some certain time.
+Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g.
+It is @code{BREAK} signal followed by character @code{g}.
+
+@item show interrupt-sequence
+Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g}
+is sent by @value{GDBN} to interrupt the remote program.
+@code{BREAK-g} is BREAK signal followed by @code{g} and
+also known as Magic SysRq g.
+
+@item set remote interrupt-on-connect
+@cindex send interrupt-sequence on start
+Specify whether interrupt-sequence is sent to remote target when
+@value{GDBN} connects to it. This is mostly needed when you debug
+Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g}
+which is known as Magic SysRq g in order to connect @value{GDBN}.
+
+@item show interrupt-on-connect
+Show whether interrupt-sequence is sent
+to remote target when @value{GDBN} connects to it.
+
@kindex set tcp
@kindex show tcp
@item set tcp auto-retry on
@tab @code{qXfer:siginfo:write}
@tab @code{set $_siginfo}
+@item @code{threads}
+@tab @code{qXfer:threads:read}
+@tab @code{info threads}
+
@item @code{get-thread-local-@*storage-address}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
@cindex Cygwin-specific commands
@value{GDBN} supports native debugging of MS Windows programs, including
-DLLs with and without symbolic debugging information. There are various
-additional Cygwin-specific commands, described in this section.
-Working with DLLs that have no debugging symbols is described in
-@ref{Non-debug DLL Symbols}.
+DLLs with and without symbolic debugging information.
+
+@cindex Ctrl-BREAK, MS-Windows
+@cindex interrupt debuggee on MS-Windows
+MS-Windows programs that call @code{SetConsoleMode} to switch off the
+special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted
+by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows
+supports @kbd{C-@key{BREAK}} as an alternative interrupt key
+sequence, which can be used to interrupt the debuggee even if it
+ignores @kbd{C-c}.
+
+There are various additional Cygwin-specific commands, described in
+this section. Working with DLLs that have no debugging symbols is
+described in @ref{Non-debug DLL Symbols}.
@table @code
@kindex info w32
tools, DLL export symbols are made available with a prefix based on the
DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is
also entered into the symbol table, so @code{CreateFileA} is often
-sufficient. In some cases there will be name clashes within a program
+sufficient. In some cases there will be name clashes within a program
(particularly if the executable itself includes full debugging symbols)
necessitating the use of the fully qualified name when referring to the
-contents of the DLL. Use single-quotes around the name to avoid the
+contents of the DLL. Use single-quotes around the name to avoid the
exclamation mark (``!'') being interpreted as a language operator.
Note that the internal name of the DLL may be all upper-case, even
-though the file name of the DLL is lower-case, or vice-versa. Since
+though the file name of the DLL is lower-case, or vice-versa. Since
symbols within @value{GDBN} are @emph{case-sensitive} this may cause
some confusion. If in doubt, try the @code{info functions} and
@code{info variables} commands or even @code{maint print msymbols}
* ARM:: ARM RDI
* M32R/D:: Renesas M32R/D
* M68K:: Motorola M68K
+* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
@end table
+@node MicroBlaze
+@subsection MicroBlaze
+@cindex Xilinx MicroBlaze
+@cindex XMD, Xilinx Microprocessor Debugger
+
+The MicroBlaze is a soft-core processor supported on various Xilinx
+FPGAs, such as Spartan or Virtex series. Boards with these processors
+usually have JTAG ports which connect to a host system running the Xilinx
+Embedded Development Kit (EDK) or Software Development Kit (SDK).
+This host system is used to download the configuration bitstream to
+the target FPGA. The Xilinx Microprocessor Debugger (XMD) program
+communicates with the target board using the JTAG interface and
+presents a @code{gdbserver} interface to the board. By default
+@code{xmd} uses port @code{1234}. (While it is possible to change
+this default port, it requires the use of undocumented @code{xmd}
+commands. Contact Xilinx support if you need to do this.)
+
+Use these GDB commands to connect to the MicroBlaze target processor.
+
+@table @code
+@item target remote :1234
+Use this command to connect to the target if you are running @value{GDBN}
+on the same system as @code{xmd}.
+
+@item target remote @var{xmd-host}:1234
+Use this command to connect to the target if it is connected to @code{xmd}
+running on a different system named @var{xmd-host}.
+
+@item load
+Use this command to download a program to the MicroBlaze target.
+
+@item set debug microblaze @var{n}
+Enable MicroBlaze-specific debugging messages if non-zero.
+
+@item show debug microblaze @var{n}
+Show MicroBlaze-specific debugging level.
+@end table
+
@node MIPS Embedded
@subsection MIPS Embedded
@end table
+When @value{GDBN} is debugging a combined PowerPC/SPU application
+on the Cell Broadband Engine, it provides in addition the following
+special commands:
+
+@table @code
+@item set spu stop-on-load @var{arg}
+@kindex set spu
+Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN}
+will give control to the user when a new SPE thread enters its @code{main}
+function. The default is @code{off}.
+
+@item show spu stop-on-load
+@kindex show spu
+Show whether to stop for new SPE threads.
+
+@item set spu auto-flush-cache @var{arg}
+Set whether to automatically flush the software-managed cache. When set to
+@code{on}, @value{GDBN} will automatically cause the SPE software-managed
+cache to be flushed whenever SPE execution stops. This provides a consistent
+view of PowerPC memory that is accessed via the cache. If an application
+does not use the software-managed cache, this option has no effect.
+
+@item show spu auto-flush-cache
+Show whether to automatically flush the software-managed cache.
+
+@end table
+
@node PowerPC
@subsection PowerPC
@cindex PowerPC architecture
* ABI:: Configuring the current ABI
* Messages/Warnings:: Optional warnings and messages
* Debugging Output:: Optional messages about internal happenings
+* Other Misc Settings:: Other Miscellaneous Settings
@end menu
@node Prompt
@end table
+@anchor{confirmation requests}
By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
lot of stupid questions to confirm certain commands. For example, if
you try to run a program which is already running:
Displays the current state of XML debugging messages.
@end table
+@node Other Misc Settings
+@section Other Miscellaneous Settings
+@cindex miscellaneous settings
+
+@table @code
+@kindex set interactive-mode
+@item set interactive-mode
+If @code{on}, forces @value{GDBN} to operate interactively.
+If @code{off}, forces @value{GDBN} to operate non-interactively,
+If @code{auto} (the default), @value{GDBN} guesses which mode to use,
+based on whether the debugger was started in a terminal or not.
+
+In the vast majority of cases, the debugger should be able to guess
+correctly which mode should be used. But this setting can be useful
+in certain specific cases, such as running a MinGW @value{GDBN}
+inside a cygwin window.
+
+@kindex show interactive-mode
+@item show interactive-mode
+Displays whether the debugger is operating in interactive mode or not.
+@end table
+
@node Extending GDB
@chapter Extending @value{GDBN}
@cindex extending GDB
on composition of @value{GDBN} commands, and the second is based on the
Python scripting language.
+To facilitate the use of these extensions, @value{GDBN} is capable
+of evaluating the contents of a file. When doing so, @value{GDBN}
+can recognize which scripting language is being used by looking at
+the filename extension. Files with an unrecognized filename extension
+are always treated as a @value{GDBN} Command Files.
+@xref{Command Files,, Command files}.
+
+You can control how @value{GDBN} evaluates these files with the following
+setting:
+
+@table @code
+@kindex set script-extension
+@kindex show script-extension
+@item set script-extension off
+All scripts are always evaluated as @value{GDBN} Command Files.
+
+@item set script-extension soft
+The debugger determines the scripting language based on filename
+extension. If this scripting language is supported, @value{GDBN}
+evaluates the script using that language. Otherwise, it evaluates
+the file as a @value{GDBN} Command File.
+
+@item set script-extension strict
+The debugger determines the scripting language based on filename
+extension, and evaluates the script using that language. If the
+language is not supported, then the evaluation fails.
+
+@item show script-extension
+Display the current value of the @code{script-extension} option.
+
+@end table
+
@menu
* Sequences:: Canned Sequences of Commands
* Python:: Scripting @value{GDBN} using Python
terminal.
You can request the execution of a command file with the @code{source}
-command:
+command. Note that the @code{source} command is also used to evaluate
+scripts that are not Command Files. The exact behavior can be configured
+using the @code{script-extension} setting.
+@xref{Extending GDB,, Extending GDB}.
@table @code
@kindex source
disabled.
@end table
+It is also possible to execute a Python script from the @value{GDBN}
+interpreter:
+
+@table @code
+@item source @file{script-name}
+The script name must end with @samp{.py} and @value{GDBN} must be configured
+to recognize the script language based on filename extension using
+the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
+
+@item python execfile ("script-name")
+This method is based on the @code{execfile} Python built-in function,
+and thus is always available.
+@end table
+
@node Python API
@subsection Python API
@cindex python api
* Functions In Python:: Writing new convenience functions.
* Objfiles In Python:: Object files.
* Frames In Python:: Acessing inferior stack frames from Python.
+* Lazy Strings In Python:: Python representation of lazy strings.
@end menu
@node Basic Python
@code{gdb.Value} (@pxref{Values From Inferior}).
@end defun
+@findex gdb.parse_and_eval
+@defun parse_and_eval expression
+Parse @var{expression} as an expression in the current language,
+evaluate it, and return the result as a @code{gdb.Value}.
+@var{expression} must be a string.
+
+This function can be useful when implementing a new command
+(@pxref{Commands In Python}), as it provides a way to parse the
+command's argument as an expression. It is also useful simply to
+compute values, for example, it is the only way to get the value of a
+convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
+@end defun
+
@findex gdb.write
@defun write string
Print a string to @value{GDBN}'s paginated standard output stream.
If this file does not exist, and if the parameter
@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
-then @value{GDBN} will use the file named
-@file{@var{debug-file-directory}/@var{real-name}}, where
+then @value{GDBN} will use for its each separated directory component
+@code{component} the file named @file{@code{component}/@var{real-name}}, where
@var{real-name} is the object file's real name, as described above.
Finally, if this file does not exist, then @value{GDBN} will look for
The following methods are provided:
@table @code
+@defmethod Value cast type
+Return a new instance of @code{gdb.Value} that is the result of
+casting this instance to the type described by @var{type}, which must
+be a @code{gdb.Type} object. If the cast cannot be performed for some
+reason, this method throws an exception.
+@end defmethod
+
@defmethod Value dereference
For pointer data types, this method returns a new @code{gdb.Value} object
whose contents is the object pointed to by the pointer. For example, if
value pointed to by @code{foo}.
@end defmethod
-@defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]}
+@defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]} @r{[}length@r{]}
If this @code{gdb.Value} represents a string, then this method
converts the contents to a Python string. Otherwise, this method will
throw an exception.
For C-like languages, a value is a string if it is a pointer to or an
array of characters or ints. The string is assumed to be terminated
-by a zero of the appropriate width.
+by a zero of the appropriate width. However if the optional length
+argument is given, the string will be converted to that given length,
+ignoring any embedded zeros that the string may contain.
If the optional @var{encoding} argument is given, it must be a string
naming the encoding of the string in the @code{gdb.Value}, such as
The optional @var{errors} argument is the same as the corresponding
argument to Python's @code{string.decode} method.
+
+If the optional @var{length} argument is given, the string will be
+fetched and converted to the given length.
+@end defmethod
+
+@defmethod Value lazy_string @r{[}encoding@r{]} @r{[}length@r{]}
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
+In Python}). Otherwise, this method will throw an exception.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the @code{gdb.LazyString}. Some examples are:
+@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
+@var{encoding} argument is an encoding that @value{GDBN} does
+recognize, @value{GDBN} will raise an error.
+
+When a lazy string is printed, the @value{GDBN} encoding machinery is
+used to convert the string during printing. If the optional
+@var{encoding} argument is not provided, or is an empty string,
+@value{GDBN} will automatically select the encoding most suitable for
+the string type. For further information on encoding in @value{GDBN}
+please see @ref{Character Sets}.
+
+If the optional @var{length} argument is given, the string will be
+fetched and encoded to the length of characters specified. If
+the @var{length} argument is not provided, the string will be fetched
+and encoded until a null of appropriate width is found.
@end defmethod
@end table
it was provided by the compiler and not the user. This attribute is
always provided, and is @code{False} if the field is not artificial.
+@item is_base_class
+This is @code{True} if the field represents a base class of a C@t{++}
+structure. This attribute is always provided, and is @code{False}
+if the field is not a base class of the type that is the argument of
+@code{fields}, or if that type was not a C@t{++} class.
+
@item bitsize
If the field is packed, or is a bitfield, then this will have a
non-zero value, which is the size of the field in bits. Otherwise,
@code{volatile}.
@end defmethod
+@defmethod Type range
+Return a Python @code{Tuple} object that contains two elements: the
+low bound of the argument type and the high bound of that type. If
+the type does not have a range, @value{GDBN} will raise a
+@code{RuntimeError} exception.
+@end defmethod
+
@defmethod Type reference
Return a new @code{gdb.Type} object which represents a reference to this
type.
@end defmethod
+@defmethod Type pointer
+Return a new @code{gdb.Type} object which represents a pointer to this
+type.
+@end defmethod
+
@defmethod Type strip_typedefs
Return a new @code{gdb.Type} that represents the real type,
after removing all layers of typedefs.
@end defmethod
@end table
-@node Interpreters
-@chapter Command Interpreters
-@cindex command interpreters
+@node Lazy Strings In Python
+@subsubsection Python representation of lazy strings.
-@value{GDBN} supports multiple command interpreters, and some command
-infrastructure to allow users or user interface writers to switch
-between interpreters or run commands in other interpreters.
+@cindex lazy strings in python
+@tindex gdb.LazyString
-@value{GDBN} currently supports two command interpreters, the console
-interpreter (sometimes called the command-line interpreter or @sc{cli})
-and the machine interface interpreter (or @sc{gdb/mi}). This manual
-describes both of these interfaces in great detail.
+A @dfn{lazy string} is a string whose contents is not retrieved or
+encoded until it is needed.
-By default, @value{GDBN} will start with the console interpreter.
-However, the user may choose to start @value{GDBN} with another
-interpreter by specifying the @option{-i} or @option{--interpreter}
+A @code{gdb.LazyString} is represented in @value{GDBN} as an
+@code{address} that points to a region of memory, an @code{encoding}
+that will be used to encode that region of memory, and a @code{length}
+to delimit the region of memory that represents the string. The
+difference between a @code{gdb.LazyString} and a string wrapped within
+a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
+differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
+retrieved and encoded during printing, while a @code{gdb.Value}
+wrapping a string is immediately retrieved and encoded on creation.
+
+A @code{gdb.LazyString} object has the following functions:
+
+@defmethod LazyString value
+Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
+will point to the string in memory, but will lose all the delayed
+retrieval, encoding and handling that @value{GDBN} applies to a
+@code{gdb.LazyString}.
+@end defmethod
+
+@defivar LazyString address
+This attribute holds the address of the string. This attribute is not
+writable.
+@end defivar
+
+@defivar LazyString length
+This attribute holds the length of the string in characters. If the
+length is -1, then the string will be fetched and encoded up to the
+first null of appropriate width. This attribute is not writable.
+@end defivar
+
+@defivar LazyString encoding
+This attribute holds the encoding that will be applied to the string
+when the string is printed by @value{GDBN}. If the encoding is not
+set, or contains an empty string, then @value{GDBN} will select the
+most appropriate encoding when the string is printed. This attribute
+is not writable.
+@end defivar
+
+@defivar LazyString type
+This attribute holds the type that is represented by the lazy string's
+type. For a lazy string this will always be a pointer type. To
+resolve this to the lazy string's character type, use the type's
+@code{target} method. @xref{Types In Python}. This attribute is not
+writable.
+@end defivar
+
+@node Interpreters
+@chapter Command Interpreters
+@cindex command interpreters
+
+@value{GDBN} supports multiple command interpreters, and some command
+infrastructure to allow users or user interface writers to switch
+between interpreters or run commands in other interpreters.
+
+@value{GDBN} currently supports two command interpreters, the console
+interpreter (sometimes called the command-line interpreter or @sc{cli})
+and the machine interface interpreter (or @sc{gdb/mi}). This manual
+describes both of these interfaces in great detail.
+
+By default, @value{GDBN} will start with the console interpreter.
+However, the user may choose to start @value{GDBN} with another
+interpreter by specifying the @option{-i} or @option{--interpreter}
startup options. Defined interpreters include:
@table @code
* GDB/MI Stream Records::
* GDB/MI Async Records::
* GDB/MI Frame Information::
+* GDB/MI Thread Information::
@end menu
@node GDB/MI Result Records
all threads together, or even for a single thread, if the thread must
be stepped though some code before letting it run freely.
-@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}"
+@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
The target has stopped. The @var{reason} field can have one of the
following values:
value of @code{"all"}. Otherwise, the value of the @var{stopped}
field will be a list of thread identifiers. Presently, this list will
always include a single thread, but frontend should be prepared to see
-several threads in the list.
+several threads in the list. The @var{core} field reports the
+processor core on which the stop event has happened. This field may be absent
+if such information is not available.
@item =thread-group-created,id="@var{id}"
@itemx =thread-group-exited,id="@var{id}"
@end table
+@node GDB/MI Thread Information
+@subsection @sc{gdb/mi} Thread Information
+
+Whenever @value{GDBN} has to report an information about a thread, it
+uses a tuple with the following fields:
+
+@table @code
+@item id
+The numeric id assigned to the thread by @value{GDBN}. This field is
+always present.
+
+@item target-id
+Target-specific string identifying the thread. This field is always present.
+
+@item details
+Additional information about the thread provided by the target.
+It is supposed to be human-readable and not interpreted by the
+frontend. This field is optional.
+
+@item state
+Either @samp{stopped} or @samp{running}, depending on whether the
+thread is presently running. This field is always present.
+
+@item core
+The value of this field is an integer number of the processor core the
+thread was last seen on. This field is optional.
+@end table
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Simple Examples
<- ^exit
@end smallexample
+Please note that @samp{^exit} is printed immediately, but it might
+take some time for @value{GDBN} to actually exit. During that time, @value{GDBN}
+performs necessary cleanups, including killing programs being debugged
+or disconnecting from debug hardware, so the frontend should wait till
+@value{GDBN} exits and should only forcibly kill @value{GDBN} if it
+fails to exit in reasonable time.
+
@subheading A Bad Command
Here's what happens if you pass a non-existent command:
@ignore
@subheading The @code{-break-catch} Command
@findex -break-catch
+@end ignore
@subheading The @code{-break-commands} Command
@findex -break-commands
-@end ignore
+@subsubheading Synopsis
+
+@smallexample
+ -break-commands @var{number} [ @var{command1} ... @var{commandN} ]
+@end smallexample
+
+Specifies the CLI commands that should be executed when breakpoint
+@var{number} is hit. The parameters @var{command1} to @var{commandN}
+are the commands. If no command is specified, any previously-set
+commands are cleared. @xref{Break Commands}. Typical use of this
+functionality is tracing a program, that is, printing of values of
+some variables whenever breakpoint is hit and then continuing.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{commands}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-break-insert main
+^done,bkpt=@{number="1",type="breakpoint",disp="keep",
+enabled="y",addr="0x000100d0",func="main",file="hello.c",
+fullname="/home/foo/hello.c",line="5",times="0"@}
+(gdb)
+-break-commands 1 "print v" "continue"
+^done
+(gdb)
+@end smallexample
@subheading The @code{-break-condition} Command
@findex -break-condition
@subsubheading Synopsis
@smallexample
- -stack-list-arguments @var{show-values}
+ -stack-list-arguments @var{print-values}
[ @var{low-frame} @var{high-frame} ]
@end smallexample
@var{high-frame} may be larger than the actual number of frames, in
which case only existing frames will be returned.
-The @var{show-values} argument must have a value of 0 or 1. A value of
-0 means that only the names of the arguments are listed, a value of 1
-means that both names and values of the arguments are printed.
+If @var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types, and the name and type for arrays,
+structures and unions.
+
+Use of this command to obtain arguments in a single frame is
+deprecated in favor of the @samp{-stack-list-variables} command.
@subsubheading @value{GDBN} Command
@var{print-values} is 0 or @code{--no-values}, print only the names of
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
-type and value for simple data types and the name and type for arrays,
+type and value for simple data types, and the name and type for arrays,
structures and unions. In this last case, a frontend can immediately
display the value of simple data types and create variable objects for
other data types when the user wishes to explore their values in
more detail.
+This command is deprecated in favor of the
+@samp{-stack-list-variables} command.
+
@subsubheading @value{GDBN} Command
@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
(gdb)
@end smallexample
+@subheading The @code{-stack-list-variables} Command
+@findex -stack-list-variables
+
+@subsubheading Synopsis
+
+@smallexample
+ -stack-list-variables @var{print-values}
+@end smallexample
+
+Display the names of local variables and function arguments for the selected frame. If
+@var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types, and the name and type for arrays,
+structures and unions.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-stack-list-variables --thread 1 --frame 0 --all-values
+^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}]
+(gdb)
+@end smallexample
+
@subheading The @code{-stack-select-frame} Command
@findex -stack-select-frame
@item @strong{Operation}
@tab @strong{Description}
+@item @code{-enable-pretty-printing}
+@tab enable Python-based pretty-printing
@item @code{-var-create}
@tab create a variable object
@item @code{-var-delete}
@tab update the variable and its children
@item @code{-var-set-frozen}
@tab set frozeness attribute
+@item @code{-var-set-update-range}
+@tab set range of children to display on update
@end multitable
In the next subsection we describe each operation in detail and suggest
@subheading Description And Use of Operations on Variable Objects
+@subheading The @code{-enable-pretty-printing} Command
+@findex -enable-pretty-printing
+
+@smallexample
+-enable-pretty-printing
+@end smallexample
+
+@value{GDBN} allows Python-based visualizers to affect the output of the
+MI variable object commands. However, because there was no way to
+implement this in a fully backward-compatible way, a front end must
+request that this functionality be enabled.
+
+Once enabled, this feature cannot be disabled.
+
+Note that if Python support has not been compiled into @value{GDBN},
+this command will still succeed (and do nothing).
+
+This feature is currently (as of @value{GDBN} 7.0) experimental, and
+may work differently in future versions of @value{GDBN}.
+
@subheading The @code{-var-create} Command
@findex -var-create
@samp{$@var{regname}} --- a CPU register name
@end itemize
+@cindex dynamic varobj
+A varobj's contents may be provided by a Python-based pretty-printer. In this
+case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs
+have slightly different semantics in some cases. If the
+@code{-enable-pretty-printing} command is not sent, then @value{GDBN}
+will never create a dynamic varobj. This ensures backward
+compatibility for existing clients.
+
@subsubheading Result
-This operation returns the name, number of children and the type of the
-object created. Type is returned as a string as the ones generated by
-the @value{GDBN} CLI. If a fixed variable object is bound to a
-specific thread, the thread is is also printed:
+This operation returns attributes of the newly-created varobj. These
+are:
+
+@table @samp
+@item name
+The name of the varobj.
+
+@item numchild
+The number of children of the varobj. This number is not necessarily
+reliable for a dynamic varobj. Instead, you must examine the
+@samp{has_more} attribute.
+
+@item value
+The varobj's scalar value. For a varobj whose type is some sort of
+aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value
+will not be interesting.
+
+@item type
+The varobj's type. This is a string representation of the type, as
+would be printed by the @value{GDBN} CLI.
+
+@item thread-id
+If a variable object is bound to a specific thread, then this is the
+thread's identifier.
+
+@item has_more
+For a dynamic varobj, this indicates whether there appear to be any
+children available. For a non-dynamic varobj, this will be 0.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing}.
+@end table
+
+Typical output will look like this:
@smallexample
- name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}",
+ has_more="@var{has_more}"
@end smallexample
numchild=@var{n}
@end smallexample
+Note that this number is not completely reliable for a dynamic varobj.
+It will return the current number of children, but more children may
+be available.
+
@subheading The @code{-var-list-children} Command
@findex -var-list-children
@subsubheading Synopsis
@smallexample
- -var-list-children [@var{print-values}] @var{name}
+ -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
@end smallexample
-@anchor{-var-list-children}
+@anchor{-var-list-children}
Return a list of the children of the specified variable object and
create variable objects for them, if they do not already exist. With
value for simple data types and just the name for arrays, structures
and unions.
+@var{from} and @var{to}, if specified, indicate the range of children
+to report. If @var{from} or @var{to} is less than zero, the range is
+reset and all children will be reported. Otherwise, children starting
+at @var{from} (zero-based) and up to and excluding @var{to} will be
+reported.
+
+If a child range is requested, it will only affect the current call to
+@code{-var-list-children}, but not future calls to @code{-var-update}.
+For this, you must instead use @code{-var-set-update-range}. The
+intent of this approach is to enable a front end to implement any
+update approach it likes; for example, scrolling a view may cause the
+front end to request more children with @code{-var-list-children}, and
+then the front end could call @code{-var-set-update-range} with a
+different range to ensure that future updates are restricted to just
+the visible items.
+
+For each child the following results are returned:
+
+@table @var
+
+@item name
+Name of the variable object created for this child.
+
+@item exp
+The expression to be shown to the user by the front end to designate this child.
+For example this may be the name of a structure member.
+
+For a dynamic varobj, this value cannot be used to form an
+expression. There is no way to do this at all with a dynamic varobj.
+
+For C/C@t{++} structures there are several pseudo children returned to
+designate access qualifiers. For these pseudo children @var{exp} is
+@samp{public}, @samp{private}, or @samp{protected}. In this case the
+type and value are not present.
+
+A dynamic varobj will not report the access qualifying
+pseudo-children, regardless of the language. This information is not
+available at all with a dynamic varobj.
+
+@item numchild
+Number of children this child has. For a dynamic varobj, this will be
+0.
+
+@item type
+The type of the child.
+
+@item value
+If values were requested, this is the value.
+
+@item thread-id
+If this variable object is associated with a thread, this is the thread id.
+Otherwise this result is not present.
+
+@item frozen
+If the variable object is frozen, this variable will be present with a value of 1.
+@end table
+
+The result may have its own attributes:
+
+@table @samp
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing}.
+
+@item has_more
+This is an integer attribute which is nonzero if there are children
+remaining after the end of the selected range.
+@end table
+
@subsubheading Example
@smallexample
(gdb)
-var-list-children n
- ^done,numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
(gdb)
-var-list-children --all-values n
- ^done,numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
@end smallexample
the @code{-var-info-path-expression} command is creating a
watchpoint from a variable object.
+This command is currently not valid for children of a dynamic varobj,
+and will give an error when invoked on one.
+
For example, suppose @code{C} is a C@t{++} class, derived from class
@code{Base}, and that the @code{Base} class has a member called
@code{m_size}. Assume a variable @code{c} is has the type of
currently running thread, it will not be updated, without any
diagnostic.
-@subsubheading Example
+If @code{-var-set-update-range} was previously used on a varobj, then
+only the selected range of children will be reported.
-@smallexample
-(gdb)
--var-assign var1 3
-^done,value="3"
-(gdb)
--var-update --all-values var1
-^done,changelist=[@{name="var1",value="3",in_scope="true",
-type_changed="false"@}]
-(gdb)
-@end smallexample
+@code{-var-update} reports all the changed varobjs in a tuple named
+@samp{changelist}.
+
+Each item in the change list is itself a tuple holding:
+
+@table @samp
+@item name
+The name of the varobj.
+
+@item value
+If values were requested for this update, then this field will be
+present and will hold the value of the varobj.
+@item in_scope
@anchor{-var-update}
-The field in_scope may take three values:
+This field is a string which may take one of three values:
@table @code
@item "true"
In the future new values may be added to this list so the front should
be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
+@item type_changed
+This is only present if the varobj is still valid. If the type
+changed, then this will be the string @samp{true}; otherwise it will
+be @samp{false}.
+
+@item new_type
+If the varobj's type changed, then this field will be present and will
+hold the new type.
+
+@item new_num_children
+For a dynamic varobj, if the number of children changed, or if the
+type changed, this will be the new number of children.
+
+The @samp{numchild} field in other varobj responses is generally not
+valid for a dynamic varobj -- it will show the number of children that
+@value{GDBN} knows about, but because dynamic varobjs lazily
+instantiate their children, this will not reflect the number of
+children which may be available.
+
+The @samp{new_num_children} attribute only reports changes to the
+number of children known by @value{GDBN}. This is the only way to
+detect whether an update has removed children (which necessarily can
+only happen at the end of the update range).
+
+@item displayhint
+The display hint, if any.
+
+@item has_more
+This is an integer value, which will be 1 if there are more children
+available outside the varobj's update range.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
+@item new_children
+If new children were added to a dynamic varobj within the selected
+update range (as set by @code{-var-set-update-range}), then they will
+be listed in this attribute.
+@end table
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-var-assign var1 3
+^done,value="3"
+(gdb)
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(gdb)
+@end smallexample
+
@subheading The @code{-var-set-frozen} Command
@findex -var-set-frozen
@anchor{-var-set-frozen}
(gdb)
@end smallexample
+@subheading The @code{-var-set-update-range} command
+@findex -var-set-update-range
+@anchor{-var-set-update-range}
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-set-update-range @var{name} @var{from} @var{to}
+@end smallexample
+
+Set the range of children to be returned by future invocations of
+@code{-var-update}.
+
+@var{from} and @var{to} indicate the range of children to report. If
+@var{from} or @var{to} is less than zero, the range is reset and all
+children will be reported. Otherwise, children starting at @var{from}
+(zero-based) and up to and excluding @var{to} will be reported.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-var-set-update-range V 1 2
+^done
+@end smallexample
+
@subheading The @code{-var-set-visualizer} command
@findex -var-set-visualizer
@anchor{-var-set-visualizer}
@subheading Synopsis
@smallexample
--list-thread-groups [ --available ] [ @var{group} ]
+-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ]
@end smallexample
-When used without the @var{group} parameter, lists top-level thread
-groups that are being debugged. When used with the @var{group}
-parameter, the children of the specified group are listed. The
-children can be either threads, or other groups. At present,
-@value{GDBN} will not report both threads and groups as children at
-the same time, but it may change in future.
+Lists thread groups (@pxref{Thread groups}). When a single thread
+group is passed as the argument, lists the children of that group.
+When several thread group are passed, lists information about those
+thread groups. Without any parameters, lists information about all
+top-level thread groups.
+
+Normally, thread groups that are being debugged are reported.
+With the @samp{--available} option, @value{GDBN} reports thread groups
+available on the target.
+
+The output of this command may have either a @samp{threads} result or
+a @samp{groups} result. The @samp{thread} result has a list of tuples
+as value, with each tuple describing a thread (@pxref{GDB/MI Thread
+Information}). The @samp{groups} result has a list of tuples as value,
+each tuple describing a thread group. If top-level groups are
+requested (that is, no parameter is passed), or when several groups
+are passed, the output always has a @samp{groups} result. The format
+of the @samp{group} result is described below.
+
+To reduce the number of roundtrips it's possible to list thread groups
+together with their children, by passing the @samp{--recurse} option
+and the recursion depth. Presently, only recursion depth of 1 is
+permitted. If this option is present, then every reported thread group
+will also include its children, either as @samp{group} or
+@samp{threads} field.
+
+In general, any combination of option and parameters is permitted, with
+the following caveats:
+
+@itemize @bullet
+@item
+When a single thread group is passed, the output will typically
+be the @samp{threads} result. Because threads may not contain
+anything, the @samp{recurse} option will be ignored.
+
+@item
+When the @samp{--available} option is passed, limited information may
+be available. In particular, the list of threads of a process might
+be inaccessible. Further, specifying specific thread groups might
+not give any performance advantage over listing all thread groups.
+The frontend should assume that @samp{-list-thread-groups --available}
+is always an expensive operation and cache the results.
+
+@end itemize
+
+The @samp{groups} result is a list of tuples, where each tuple may
+have the following fields:
+
+@table @code
+@item id
+Identifier of the thread group. This field is always present.
+
+@item type
+The type of the thread group. At present, only @samp{process} is a
+valid type.
+
+@item pid
+The target-specific process identifier. This field is only present
+for thread groups of type @samp{process}.
+
+@item num_children
+The number of children this thread group has. This field may be
+absent for an available thread group.
-With the @samp{--available} option, instead of reporting groups that
-are been debugged, GDB will report all thread groups available on the
-target. Using the @samp{--available} option together with @var{group}
-is not allowed.
+@item threads
+This field has a list of tuples as value, each tuple describing a
+thread. It may be present if the @samp{--recurse} option is
+specified, and it's actually possible to obtain the threads.
+
+@item cores
+This field is a list of integers, each identifying a core that one
+thread of the group is running on. This field may be absent if
+such information is not available.
+
+@end table
@subheading Example
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+-list-thread-groups --available
+^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
+-list-thread-groups --available --recurse 1
+ ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
+ threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
+ @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..]
+-list-thread-groups --available --recurse 1 17 18
+^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
+ threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
+ @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
@end smallexample
@subheading The @code{-interpreter-exec} Command
means that commands can be run behind a user's back by a front-end in
a transparent manner.
-The server prefix does not affect the recording of values into the value
-history; to print a value without recording it into the value history,
-use the @code{output} command instead of the @code{print} command.
+The @code{server } prefix does not affect the recording of values into
+the value history; to print a value without recording it into the
+value history, use the @code{output} command instead of the
+@code{print} command.
+
+Using this prefix also disables confirmation requests
+(@pxref{confirmation requests}).
@node Prompting
@section Annotation for @value{GDBN} Input
followed by one or more lowercase hex digits (note that this does not
depend on the language).
+@node JIT Interface
+@chapter JIT Compilation Interface
+@cindex just-in-time compilation
+@cindex JIT compilation interface
+
+This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation
+interface. A JIT compiler is a program or library that generates native
+executable code at runtime and executes it, usually in order to achieve good
+performance while maintaining platform independence.
+
+Programs that use JIT compilation are normally difficult to debug because
+portions of their code are generated at runtime, instead of being loaded from
+object files, which is where @value{GDBN} normally finds the program's symbols
+and debug information. In order to debug programs that use JIT compilation,
+@value{GDBN} has an interface that allows the program to register in-memory
+symbol files with @value{GDBN} at runtime.
+
+If you are using @value{GDBN} to debug a program that uses this interface, then
+it should work transparently so long as you have not stripped the binary. If
+you are developing a JIT compiler, then the interface is documented in the rest
+of this chapter. At this time, the only known client of this interface is the
+LLVM JIT.
+
+Broadly speaking, the JIT interface mirrors the dynamic loader interface. The
+JIT compiler communicates with @value{GDBN} by writing data into a global
+variable and calling a fuction at a well-known symbol. When @value{GDBN}
+attaches, it reads a linked list of symbol files from the global variable to
+find existing code, and puts a breakpoint in the function so that it can find
+out about additional code.
+
+@menu
+* Declarations:: Relevant C struct declarations
+* Registering Code:: Steps to register code
+* Unregistering Code:: Steps to unregister code
+@end menu
+
+@node Declarations
+@section JIT Declarations
+
+These are the relevant struct declarations that a C program should include to
+implement the interface:
+
+@smallexample
+typedef enum
+@{
+ JIT_NOACTION = 0,
+ JIT_REGISTER_FN,
+ JIT_UNREGISTER_FN
+@} jit_actions_t;
+
+struct jit_code_entry
+@{
+ struct jit_code_entry *next_entry;
+ struct jit_code_entry *prev_entry;
+ const char *symfile_addr;
+ uint64_t symfile_size;
+@};
+
+struct jit_descriptor
+@{
+ uint32_t version;
+ /* This type should be jit_actions_t, but we use uint32_t
+ to be explicit about the bitwidth. */
+ uint32_t action_flag;
+ struct jit_code_entry *relevant_entry;
+ struct jit_code_entry *first_entry;
+@};
+
+/* GDB puts a breakpoint in this function. */
+void __attribute__((noinline)) __jit_debug_register_code() @{ @};
+
+/* Make sure to specify the version statically, because the
+ debugger may check the version before we can set it. */
+struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @};
+@end smallexample
+
+If the JIT is multi-threaded, then it is important that the JIT synchronize any
+modifications to this global data properly, which can easily be done by putting
+a global mutex around modifications to these structures.
+
+@node Registering Code
+@section Registering Code
+
+To register code with @value{GDBN}, the JIT should follow this protocol:
+
+@itemize @bullet
+@item
+Generate an object file in memory with symbols and other desired debug
+information. The file must include the virtual addresses of the sections.
+
+@item
+Create a code entry for the file, which gives the start and size of the symbol
+file.
+
+@item
+Add it to the linked list in the JIT descriptor.
+
+@item
+Point the relevant_entry field of the descriptor at the entry.
+
+@item
+Set @code{action_flag} to @code{JIT_REGISTER} and call
+@code{__jit_debug_register_code}.
+@end itemize
+
+When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the
+@code{relevant_entry} pointer so it doesn't have to walk the list looking for
+new code. However, the linked list must still be maintained in order to allow
+@value{GDBN} to attach to a running process and still find the symbol files.
+
+@node Unregistering Code
+@section Unregistering Code
+
+If code is freed, then the JIT should use the following protocol:
+
+@itemize @bullet
+@item
+Remove the code entry corresponding to the code from the linked list.
+
+@item
+Point the @code{relevant_entry} field of the descriptor at the code entry.
+
+@item
+Set @code{action_flag} to @code{JIT_UNREGISTER} and call
+@code{__jit_debug_register_code}.
+@end itemize
+
+If the JIT frees or recompiles code without unregistering it, then @value{GDBN}
+and the JIT will leak the memory used for the associated symbol files.
+
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
@table @code
@kindex maint agent
+@kindex maint agent-eval
@item maint agent @var{expression}
+@itemx maint agent-eval @var{expression}
Translate the given @var{expression} into remote agent bytecodes.
This command is useful for debugging the Agent Expression mechanism
-(@pxref{Agent Expressions}).
+(@pxref{Agent Expressions}). The @samp{agent} version produces an
+expression useful for data collection, such as by tracepoints, while
+@samp{maint agent-eval} produces an expression that evaluates directly
+to a result. For instance, a collection expression for @code{globa +
+globb} will include bytecodes to record four bytes of memory at each
+of the addresses of @code{globa} and @code{globb}, while discarding
+the result of the addition, while an evaluation expression will do the
+addition and return the sum.
@kindex maint info breakpoints
@item @anchor{maint info breakpoints}maint info breakpoints
* Packets::
* Stop Reply Packets::
* General Query Packets::
-* Register Packet Format::
+* Architecture-Specific Protocol Details::
* Tracepoint Packets::
* Host I/O Packets::
* Interrupts::
* File-I/O Remote Protocol Extension::
* Library List Format::
* Memory Map Format::
+* Thread List Format::
@end menu
@node Overview
Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
-@item bc
@cindex @samp{bc} packet
+@anchor{bc}
+@item bc
Backward continue. Execute the target system in reverse. No parameter.
@xref{Reverse Execution}, for more information.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item bs
@cindex @samp{bs} packet
+@anchor{bs}
+@item bs
Backward single step. Execute one instruction in reverse. No parameter.
@xref{Reverse Execution}, for more information.
Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item t
Stop.
-@item T @var{sig}
-Stop with signal @var{sig}. The signal @var{sig} should be two hex digits.
@end table
The optional argument @var{addr} normally associated with the
@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
not supported in @samp{vCont}.
-The @samp{t} and @samp{T} actions are only relevant in non-stop mode
-(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
+The @samp{t} action is only relevant in non-stop mode
+(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
A stop reply should be generated for any affected thread not already stopped.
When a thread is stopped by means of a @samp{t} action,
the corresponding stop reply should indicate that the thread has stopped with
for an error
@end table
-@item z @var{type},@var{addr},@var{length}
-@itemx Z @var{type},@var{addr},@var{length}
+@item z @var{type},@var{addr},@var{kind}
+@itemx Z @var{type},@var{addr},@var{kind}
@anchor{insert breakpoint or watchpoint packet}
@cindex @samp{z} packet
@cindex @samp{Z} packets
Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
-watchpoint starting at address @var{address} and covering the next
-@var{length} bytes.
+watchpoint starting at address @var{address} of kind @var{kind}.
Each breakpoint and watchpoint packet @var{type} is documented
separately.
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.}
-@item z0,@var{addr},@var{length}
-@itemx Z0,@var{addr},@var{length}
+@item z0,@var{addr},@var{kind}
+@itemx Z0,@var{addr},@var{kind}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
-@var{addr} of size @var{length}.
+@var{addr} of type @var{kind}.
A memory breakpoint is implemented by replacing the instruction at
@var{addr} with a software breakpoint or trap instruction. The
-@var{length} is used by targets that indicates the size of the
-breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and
-@sc{mips} can insert either a 2 or 4 byte breakpoint).
+@var{kind} is target-specific and typically indicates the size of
+the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
+and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
+architectures have additional meanings for @var{kind};
+see @ref{Architecture-Specific Protocol Details}.
@emph{Implementation note: It is possible for a target to copy or move
code that contains memory breakpoints (e.g., when implementing
for an error
@end table
-@item z1,@var{addr},@var{length}
-@itemx Z1,@var{addr},@var{length}
+@item z1,@var{addr},@var{kind}
+@itemx Z1,@var{addr},@var{kind}
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
-address @var{addr} of size @var{length}.
+address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
-dependant on being able to modify the target's memory.
+dependant on being able to modify the target's memory. @var{kind}
+has the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
for an error
@end table
-@item z2,@var{addr},@var{length}
-@itemx Z2,@var{addr},@var{length}
+@item z2,@var{addr},@var{kind}
+@itemx Z2,@var{addr},@var{kind}
@cindex @samp{z2} packet
@cindex @samp{Z2} packet
-Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint.
+Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
+@var{kind} is interpreted as the number of bytes to watch.
Reply:
@table @samp
for an error
@end table
-@item z3,@var{addr},@var{length}
-@itemx Z3,@var{addr},@var{length}
+@item z3,@var{addr},@var{kind}
+@itemx Z3,@var{addr},@var{kind}
@cindex @samp{z3} packet
@cindex @samp{Z3} packet
-Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint.
+Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
+@var{kind} is interpreted as the number of bytes to watch.
Reply:
@table @samp
for an error
@end table
-@item z4,@var{addr},@var{length}
-@itemx Z4,@var{addr},@var{length}
+@item z4,@var{addr},@var{kind}
+@itemx Z4,@var{addr},@var{kind}
@cindex @samp{z4} packet
@cindex @samp{Z4} packet
-Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint.
+Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
+@var{kind} is interpreted as the number of bytes to watch.
Reply:
@table @samp
If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
the stopped thread, as specified in @ref{thread-id syntax}.
+@item
+If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of
+the core on which the stop event was detected.
+
@item
If @var{n} is a recognized @dfn{stop reason}, it describes a more
specific event that stopped the target. The currently defined stop
beginning when executing backward) of the log. The value of @var{r}
will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
for more information.
-
-
@end table
@item W @var{AA}
@item qCRC:@var{addr},@var{length}
@cindex CRC of memory block, remote request
@cindex @samp{qCRC} packet
-Compute the CRC checksum of a block of memory.
+Compute the CRC checksum of a block of memory using CRC-32 defined in
+IEEE 802.3. The CRC is computed byte at a time, taking the most
+significant bit of each byte first. The initial pattern code
+@code{0xffffffff} is used to ensure leading zeros affect the CRC.
+
+@emph{Note:} This is the same CRC used in validating separate debug
+files (@pxref{Separate Debug Files, , Debugging Information in Separate
+Files}). However the algorithm is slightly different. When validating
+separate debug files, the CRC is computed taking the @emph{least}
+significant bit of each byte first, and the final result is inverted to
+detect trailing zeros.
+
Reply:
@table @samp
@item E @var{NN}
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:threads:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{ConditionalTracepoints}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{ReverseContinue}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{ReverseStep}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:siginfo:write} packet
(@pxref{qXfer siginfo write}).
+@item qXfer:threads:read
+The remote stub understands the @samp{qXfer:threads:read} packet
+(@pxref{qXfer threads read}).
+
@item QNonStop
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
The remote stub understands the @samp{qXfer:osdata:read} packet
((@pxref{qXfer osdata read}).
+@item ConditionalTracepoints
+The remote stub accepts and implements conditional expressions defined
+for tracepoints (@pxref{Tracepoint Conditions}).
+
+@item ReverseContinue
+The remote stub accepts and implements the reverse continue packet
+(@pxref{bc}).
+
+@item ReverseStep
+The remote stub accepts and implements the reverse step packet
+(@pxref{bs}).
+
@end table
@item qSymbol::
(if available), until the target ceases to request them.
@end table
-@item QTDP
+@item qTBuffer
+@item QTDisconnected
+@itemx QTDP
+@itemx QTDV
+@itemx qTfP
+@itemx qTfV
@itemx QTFrame
@xref{Tracepoint Packets}.
conventions above. Please don't use this packet as a model for new
packets.)
-@item QTStart
+@item QTSave
+@item qTsP
+@item qTsV
+@itemx QTStart
@itemx QTStop
@itemx QTinit
@itemx QTro
@itemx qTStatus
+@itemx qTV
@xref{Tracepoint Packets}.
@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
by supplying an appropriate @samp{qSupported} response
(@pxref{qSupported}).
+@item qXfer:threads:read::@var{offset},@var{length}
+@anchor{qXfer threads read}
+Access the list of threads on target. @xref{Thread List Format}. The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
Access the target's @dfn{operating system information}.
@end table
-@node Register Packet Format
-@section Register Packet Format
+@node Architecture-Specific Protocol Details
+@section Architecture-Specific Protocol Details
+
+This section describes how the remote protocol is applied to specific
+target architectures. Also see @ref{Standard Target Features}, for
+details of XML target descriptions for each architecture.
+
+@subsection ARM
+
+@subsubsection Breakpoint Kinds
+
+These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
+
+@table @r
+
+@item 2
+16-bit Thumb mode breakpoint.
+
+@item 3
+32-bit Thumb mode (Thumb-2) breakpoint.
+
+@item 4
+32-bit ARM mode breakpoint.
+
+@end table
+
+@subsection MIPS
+
+@subsubsection Register Packet Format
The following @code{g}/@code{G} packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
@table @samp
-@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}@r{[}-@r{]}
+@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]}
Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
the tracepoint is disabled. @var{step} is the tracepoint's step
-count, and @var{pass} is its pass count. If the trailing @samp{-} is
-present, further @samp{QTDP} packets will follow to specify this
-tracepoint's actions.
+count, and @var{pass} is its pass count. If an @samp{F} is present,
+then the tracepoint is to be a fast tracepoint, and the @var{flen} is
+the number of bytes that the target should copy elsewhere to make room
+for the tracepoint. If an @samp{X} is present, it introduces a
+tracepoint condition, which consists of a hexadecimal length, followed
+by a comma and hex-encoded bytes, in a manner similar to action
+encodings as described below. If the trailing @samp{-} is present,
+further @samp{QTDP} packets will follow to specify this tracepoint's
+actions.
Replies:
@table @samp
The packet was not recognized.
@end table
+@item QTDV:@var{n}:@var{value}
+@cindex define trace state variable, remote request
+@cindex @samp{QTDV} packet
+Create a new trace state variable, number @var{n}, with an initial
+value of @var{value}, which is a 64-bit signed integer. Both @var{n}
+and @var{value} are encoded as hexadecimal values. @value{GDBN} has
+the option of not using this packet for initial values of zero; the
+target should simply create the trace state variables as they are
+mentioned in expressions.
+
@item QTFrame:@var{n}
Select the @var{n}'th tracepoint frame from the buffer, and use the
register and memory contents recorded there to answer subsequent
still have the same contents they did when the tracepoint was hit, so
there's no reason for the stub to refuse to provide their contents.
+@item QTDisconnected:@var{value}
+Set the choice to what to do with the tracing run when @value{GDBN}
+disconnects from the target. A @var{value} of 1 directs the target to
+continue the tracing run, while 0 tells the target to stop tracing if
+@value{GDBN} is no longer in the picture.
+
@item qTStatus
Ask the stub if there is a trace experiment running right now.
There is a trace experiment running.
@end table
-@end table
+@item qTV:@var{var}
+@cindex trace state variable value, remote request
+@cindex @samp{qTV} packet
+Ask the stub for the value of the trace state variable number @var{var}.
+Replies:
+@table @samp
+@item V@var{value}
+The value of the variable is @var{value}. This will be the current
+value of the variable if the user is examining a running target, or a
+saved value if the variable was collected in the trace frame that the
+user is looking at. Note that multiple requests may result in
+different reply values, such as when requesting values while the
+program is running.
+
+@item U
+The value of the variable is unknown. This would occur, for example,
+if the user is examining a trace frame in which the requested variable
+was not collected.
+@end table
+
+@item qTfP
+@itemx qTsP
+These packets request data about tracepoints that are being used by
+the target. @value{GDBN} sends @code{qTfP} to get the first piece
+of data, and multiple @code{qTsP} to get additional pieces. Replies
+to these packets generally take the form of the @code{QTDP} packets
+that define tracepoints. (FIXME add detailed syntax)
+
+@item qTfV
+@itemx qTsV
+These packets request data about trace state variables that are on the
+target. @value{GDBN} sends @code{qTfV} to get the first vari of data,
+and multiple @code{qTsV} to get additional variables. Replies to
+these packets follow the syntax of the @code{QTDV} packets that define
+trace state variables.
+
+@item QTSave:@var{filename}
+This packet directs the target to save trace data to the file name
+@var{filename} in the target's filesystem. @var{filename} is encoded
+as a hex string; the interpretation of the file name (relative vs
+absolute, wild cards, etc) is up to the target.
+
+@item qTBuffer:@var{offset},@var{len}
+Return up to @var{len} bytes of the current contents of trace buffer,
+starting at @var{offset}. The trace buffer is treated as if it were
+a contiguous collection of traceframes, as per the trace file format.
+The reply consists as many hex-encoded bytes as the target can deliver
+in a packet; it is not an error to return fewer than were asked for.
+A reply consisting of just @code{l} indicates that no bytes are
+available.
+
+@end table
@node Host I/O Packets
@section Host I/O Packets
@cindex interrupts (remote protocol)
When a program on the remote target is running, @value{GDBN} may
-attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
-control of which is specified via @value{GDBN}'s @samp{remotebreak}
-setting (@pxref{set remotebreak}).
+attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or
+a @code{BREAK} followed by @code{g},
+control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}.
The precise meaning of @code{BREAK} is defined by the transport
mechanism and may, in fact, be undefined. @value{GDBN} does not
(@pxref{X packet}), used for binary downloads, may include an unescaped
@code{0x03} as part of its packet.
+@code{BREAK} followed by @code{g} is also known as Magic SysRq g.
+When Linux kernel receives this sequence from serial port,
+it stops execution and connects to gdb.
+
Stubs are not required to recognize these interrupt mechanisms and the
precise meaning associated with receipt of the interrupt is
implementation defined. If the target supports debugging of multiple
<!ATTLIST property name CDATA #REQUIRED>
@end smallexample
+@node Thread List Format
+@section Thread List Format
+@cindex thread list format
+
+To efficiently update the list of threads and their attributes,
+@value{GDBN} issues the @samp{qXfer:threads:read} packet
+(@pxref{qXfer threads read}) and obtains the XML document with
+the following structure:
+
+@smallexample
+<?xml version="1.0"?>
+<threads>
+ <thread id="id" core="0">
+ ... description ...
+ </thread>
+</threads>
+@end smallexample
+
+Each @samp{thread} element must have the @samp{id} attribute that
+identifies the thread (@pxref{thread-id syntax}). The
+@samp{core} attribute, if present, specifies which processor core
+the thread was last executing on. The content of the of @samp{thread}
+element is interpreted as human-readable auxilliary information.
+
@include agentexpr.texi
+@node Trace File Format
+@appendix Trace File Format
+@cindex trace file format
+
+The trace file comes in three parts: a header, a textual description
+section, and a trace frame section with binary data.
+
+The header has the form @code{\x7fTRACE0\n}. The first byte is
+@code{0x7f} so as to indicate that the file contains binary data,
+while the @code{0} is a version number that may have different values
+in the future.
+
+The description section consists of multiple lines of @sc{ascii} text
+separated by newline characters (@code{0xa}). The lines may include a
+variety of optional descriptive or context-setting information, such
+as tracepoint definitions or register set size. @value{GDBN} will
+ignore any line that it does not recognize. An empty line marks the end
+of this section.
+
+@c FIXME add some specific types of data
+
+The trace frame section consists of a number of consecutive frames.
+Each frame begins with a two-byte tracepoint number, followed by a
+four-byte size giving the amount of data in the frame. The data in
+the frame consists of a number of blocks, each introduced by a
+character indicating its type (at least register, memory, and trace
+state variable). The data in this section is raw binary, not a
+hexadecimal or other encoding; its endianness matches the target's
+endianness.
+
+@c FIXME bi-arch may require endianness/arch info in description section
+
+@table @code
+@item R @var{bytes}
+Register block. The number and ordering of bytes matches that of a
+@code{g} packet in the remote protocol. Note that these are the
+actual bytes, in target order and @value{GDBN} register order, not a
+hexadecimal encoding.
+
+@item M @var{address} @var{length} @var{bytes}...
+Memory block. This is a contiguous block of memory, at the 8-byte
+address @var{address}, with a 2-byte length @var{length}, followed by
+@var{length} bytes.
+
+@item V @var{number} @var{value}
+Trace state variable block. This records the 8-byte signed value
+@var{value} of trace state variable numbered @var{number}.
+
+@end table
+
+Future enhancements of the trace file format may include additional types
+of blocks.
+
@node Target Descriptions
@appendix Target Descriptions
@cindex target descriptions
Target descriptions can identify the architecture of the remote target
and (for some architectures) provide information about custom register
-sets. @value{GDBN} can use this information to autoconfigure for your
+sets. They can also identify the OS ABI of the remote target.
+@value{GDBN} can use this information to autoconfigure for your
target, or to warn you if you connect to an unsupported target.
Here is a simple target description:
<!DOCTYPE target SYSTEM "gdb-target.dtd">
<target version="1.0">
@r{[}@var{architecture}@r{]}
+ @r{[}@var{osabi}@r{]}
+ @r{[}@var{compatible}@r{]}
@r{[}@var{feature}@dots{}@r{]}
</target>
@end smallexample
<architecture>@var{arch}</architecture>
@end smallexample
-@var{arch} is an architecture name from the same selection
-accepted by @code{set architecture} (@pxref{Targets, ,Specifying a
-Debugging Target}).
+@var{arch} is one of the architectures from the set accepted by
+@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
+
+@subsection OS ABI
+@cindex @code{<osabi>}
+
+This optional field was introduced in @value{GDBN} version 7.0.
+Previous versions of @value{GDBN} ignore it.
+
+An @samp{<osabi>} element has this form:
+
+@smallexample
+ <osabi>@var{abi-name}</osabi>
+@end smallexample
+
+@var{abi-name} is an OS ABI name from the same selection accepted by
+@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}).
+
+@subsection Compatible Architecture
+@cindex @code{<compatible>}
+
+This optional field was introduced in @value{GDBN} version 7.0.
+Previous versions of @value{GDBN} ignore it.
+
+A @samp{<compatible>} element has this form:
+
+@smallexample
+ <compatible>@var{arch}</compatible>
+@end smallexample
+
+@var{arch} is one of the architectures from the set accepted by
+@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
+
+A @samp{<compatible>} element is used to specify that the target
+is able to run binaries in some other than the main target architecture
+given by the @samp{<architecture>} element. For example, on the
+Cell Broadband Engine, the main architecture is @code{powerpc:common}
+or @code{powerpc:common64}, but the system is able to run binaries
+in the @code{spu} architecture as well. The way to describe this
+capability with @samp{<compatible>} is as follows:
+
+@smallexample
+ <architecture>powerpc:common</architecture>
+ <compatible>spu</compatible>
+@end smallexample
@subsection Features
@cindex <feature>
@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
@samp{wCSSF}, and @samp{wCASF} registers are optional.
+The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it
+should contain at least registers @samp{d0} through @samp{d15}. If
+they are present, @samp{d16} through @samp{d31} should also be included.
+@value{GDBN} will synthesize the single-precision registers from
+halves of the double-precision registers.
+
+The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not
+need to contain registers; it instructs @value{GDBN} to display the
+VFP double-precision registers as vectors and to synthesize the
+quad-precision registers from pairs of double-precision registers.
+If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
+be present and include 32 double-precision registers.
+
@node MIPS Features
@subsection MIPS Features
@cindex target descriptions, MIPS features
<column name="pid">1</column>
<column name="user">root</column>
<column name="command">/sbin/init</column>
+ <column name="cores">1,2,3</column>
</item>
</osdata>
@end smallexample
Each item should include a column whose name is @samp{pid}. The value
of that column should identify the process on the target. The
@samp{user} and @samp{command} columns are optional, and will be
-displayed by @value{GDBN}. Target may provide additional columns,
+displayed by @value{GDBN}. The @samp{cores} column, if present,
+should contain a comma-separated list of cores that this process
+is running on. Target may provide additional columns,
which @value{GDBN} currently ignores.
@include gpl.texi
projects / deliverable / binutils-gdb.git / blobdiff