\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, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
+@c 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+@c 2010, 2011 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
* GDB Bugs:: Reporting bugs in @value{GDBN}
+@ifset SYSTEM_READLINE
+* Command Line Editing: (rluserman). Command Line Editing
+* Using History Interactively: (history). Using History Interactively
+@end ifset
+@ifclear SYSTEM_READLINE
* Command Line Editing:: Command Line Editing
* Using History Interactively:: Using History Interactively
+@end ifclear
* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Installing GDB:: Installing GDB
* Maintenance Commands:: Maintenance Commands
Support for Modula-2 is partial. For information on Modula-2, see
@ref{Modula-2,,Modula-2}.
+Support for OpenCL C is partial. For information on OpenCL C, see
+@ref{OpenCL C,,OpenCL C}.
+
@cindex Pascal
Debugging Pascal programs which use sets, subranges, file variables, or
nested functions does not currently work. @value{GDBN} does not support
command files specified with @samp{-x} (and all commands from
initialization files, if not inhibited with @samp{-n}). Exit with
nonzero status if an error occurs in executing the @value{GDBN} commands
-in the command files. Batch mode also disables pagination;
-@pxref{Screen Size} and acts as if @kbd{set confirm off} were in
-effect (@pxref{Messages/Warnings}).
+in the command files. Batch mode also disables pagination, sets unlimited
+terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm
+off} were in effect (@pxref{Messages/Warnings}).
Batch mode may be useful for running @value{GDBN} as a filter, for
example to download and run a program on another computer; in order to
Run @value{GDBN} using @var{directory} as its working directory,
instead of the current directory.
+@item -data-directory @var{directory}
+@cindex @code{--data-directory}
+Run @value{GDBN} using @var{directory} as its data directory.
+The data directory is where @value{GDBN} searches for its
+auxiliary files. @xref{Data Files}.
+
@item -fullname
@itemx -f
@cindex @code{--fullname}
to the program you are debugging, in the directory where you invoke
@value{GDBN}.
+@item
+If the command line specified a program to debug, or a process to
+attach to, or a core file, @value{GDBN} loads any auto-loaded
+scripts provided for the program or for its loaded shared libraries.
+@xref{Auto-loading}.
+
+If you wish to disable the auto-loading during startup,
+you must do something like the following:
+
+@smallexample
+$ gdb -ex "set auto-load-scripts off" -ex "file myprogram"
+@end smallexample
+
+The following does not work because the auto-loading is turned off too late:
+
+@smallexample
+$ gdb -ex "set auto-load-scripts off" myprogram
+@end smallexample
+
@item
Reads command files specified by the @samp{-x} option. @xref{Command
Files}, for more details about @value{GDBN} command files.
@kindex detach inferior @var{infno}
@item detach inferior @var{infno}
Detach from the inferior identified by @value{GDBN} inferior number
-@var{infno}, and remove it from the inferior list.
+@var{infno}. Note that the inferior's entry still stays on the list
+of inferiors shown by @code{info inferiors}, but its Description will
+show @samp{<null>}.
@kindex kill inferior @var{infno}
@item kill inferior @var{infno}
Kill the inferior identified by @value{GDBN} inferior number
-@var{infno}, and remove it from the inferior list.
+@var{infno}. Note that the inferior's entry still stays on the list
+of inferiors shown by @code{info inferiors}, but its Description will
+show @samp{<null>}.
@end table
After the successful completion of a command such as @code{detach},
@kindex show libthread-db-search-path
@item show libthread-db-search-path
Display current libthread_db search path.
+
+@kindex set debug libthread-db
+@kindex show debug libthread-db
+@cindex debugging @code{libthread_db}
+@item set debug libthread-db
+@itemx show debug libthread-db
+Turns on or off display of @code{libthread_db}-related events.
+Use @code{1} to enable, @code{0} to disable.
@end table
@node Forks
@table @code
@kindex watch
-@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
+@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint for an expression. @value{GDBN} will break when the
expression @var{expr} is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.
+Ordinarily a watchpoint respects the scope of variables in @var{expr}
+(see below). The @code{-location} argument tells @value{GDBN} to
+instead watch the memory referred to by @var{expr}. In this case,
+@value{GDBN} will evaluate @var{expr}, take the address of the result,
+and watch the memory at that address. The type of the result is used
+to determine the size of the watched memory. If the expression's
+result does not have an address, then @value{GDBN} will print an
+error.
+
@kindex rwatch
-@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
+@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint that will break when the value of @var{expr} is read
by the program.
@kindex awatch
-@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
+@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
function name to avoid ambiguity when there are identically named
functions in different source files.
+@item @var{label}
+Specifies the line at which the label named @var{label} appears.
+@value{GDBN} searches for the label in the function corresponding to
+the currently selected stack frame. If there is no current selected
+stack frame (for instance, if the inferior is not running), then
+@value{GDBN} will not search for a label.
+
@item *@var{address}
Specifies the program address @var{address}. For line-oriented
commands, such as @code{list} and @code{edit}, this specifies a source
@c RET-repeat for @code{directory} is explicitly disabled, but since
@c repeating it would be a no-op we do not say that. (thanks to RMS)
+@item set directories @var{path-list}
+@kindex set directories
+Set the source path to @var{path-list}.
+@samp{$cdir:$cwd} are added if missing.
+
@item show directories
@kindex show directories
Print the source path: show which directories it contains.
command is a program counter value; @value{GDBN} dumps the function
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).
+arguments specify a range of addresses to dump, in one of two forms:
+
+@table @code
+@item @var{start},@var{end}
+the addresses from @var{start} (inclusive) to @var{end} (exclusive)
+@item @var{start},+@var{length}
+the addresses from @var{start} (inclusive) to
+@code{@var{start}+@var{length}} (exclusive).
+@end table
+
+@noindent
+When 2 arguments are specified, 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}.
End of assembler dump.
@end smallexample
+Here is another example showing raw instructions in hex for AMD x86-64,
+
+@smallexample
+(gdb) disas /r 0x400281,+10
+Dump of assembler code from 0x400281 to 0x40028b:
+ 0x0000000000400281: 38 36 cmp %dh,(%rsi)
+ 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
+ 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
+ 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
+End of assembler dump.
+@end smallexample
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
Python code. It greatly simplifies the display of complex objects. This
mechanism works for both MI and the CLI.
-For example, here is how a C@t{++} @code{std::string} looks without a
-pretty-printer:
+@menu
+* Pretty-Printer Introduction:: Introduction to pretty-printers
+* Pretty-Printer Example:: An example pretty-printer
+* Pretty-Printer Commands:: Pretty-printer commands
+@end menu
+
+@node Pretty-Printer Introduction
+@subsection Pretty-Printer Introduction
+
+When @value{GDBN} prints a value, it first sees if there is a pretty-printer
+registered for the value. If there is then @value{GDBN} invokes the
+pretty-printer to print the value. Otherwise the value is printed normally.
+
+Pretty-printers are normally named. This makes them easy to manage.
+The @samp{info pretty-printer} command will list all the installed
+pretty-printers with their names.
+If a pretty-printer can handle multiple data types, then its
+@dfn{subprinters} are the printers for the individual data types.
+Each such subprinter has its own name.
+The format of the name is @var{printer-name};@var{subprinter-name}.
+
+Pretty-printers are installed by @dfn{registering} them with @value{GDBN}.
+Typically they are automatically loaded and registered when the corresponding
+debug information is loaded, thus making them available without having to
+do anything special.
+
+There are three places where a pretty-printer can be registered.
+
+@itemize @bullet
+@item
+Pretty-printers registered globally are available when debugging
+all inferiors.
+
+@item
+Pretty-printers registered with a program space are available only
+when debugging that program.
+@xref{Progspaces In Python}, for more details on program spaces in Python.
+
+@item
+Pretty-printers registered with an objfile are loaded and unloaded
+with the corresponding objfile (e.g., shared library).
+@xref{Objfiles In Python}, for more details on objfiles in Python.
+@end itemize
+
+@xref{Selecting Pretty-Printers}, for further information on how
+pretty-printers are selected,
+
+@xref{Writing a Pretty-Printer}, for implementing pretty printers
+for new types.
+
+@node Pretty-Printer Example
+@subsection Pretty-Printer Example
+
+Here is how a C@t{++} @code{std::string} looks without a pretty-printer:
@smallexample
(@value{GDBP}) print s
$2 = "abcd"
@end smallexample
-For implementing pretty printers for new types you should read the Python API
-details (@pxref{Pretty Printing API}).
+@node Pretty-Printer Commands
+@subsection Pretty-Printer Commands
+@cindex pretty-printer commands
+
+@table @code
+@kindex info pretty-printer
+@item info pretty-printer [@var{object-regexp} [@var{name-regexp}]]
+Print the list of installed pretty-printers.
+This includes disabled pretty-printers, which are marked as such.
+
+@var{object-regexp} is a regular expression matching the objects
+whose pretty-printers to list.
+Objects can be @code{global}, the program space's file
+(@pxref{Progspaces In Python}),
+and the object files within that program space (@pxref{Objfiles In Python}).
+@xref{Selecting Pretty-Printers}, for details on how @value{GDBN}
+looks up a printer from these three objects.
+
+@var{name-regexp} is a regular expression matching the name of the printers
+to list.
+
+@kindex disable pretty-printer
+@item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]]
+Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}.
+A disabled pretty-printer is not forgotten, it may be enabled again later.
+
+@kindex enable pretty-printer
+@item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]]
+Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}.
+@end table
+
+Example:
+
+Suppose we have three pretty-printers installed: one from library1.so
+named @code{foo} that prints objects of type @code{foo}, and
+another from library2.so named @code{bar} that prints two types of objects,
+@code{bar1} and @code{bar2}.
+
+@smallexample
+(gdb) info pretty-printer
+library1.so:
+ foo
+library2.so:
+ bar
+ bar1
+ bar2
+(gdb) info pretty-printer library2
+library2.so:
+ bar
+ bar1
+ bar2
+(gdb) disable pretty-printer library1
+1 printer disabled
+2 of 3 printers enabled
+(gdb) info pretty-printer
+library1.so:
+ foo [disabled]
+library2.so:
+ bar
+ bar1
+ bar2
+(gdb) disable pretty-printer library2 bar:bar1
+1 printer disabled
+1 of 3 printers enabled
+(gdb) info pretty-printer library2
+library1.so:
+ foo [disabled]
+library2.so:
+ bar
+ bar1 [disabled]
+ bar2
+(gdb) disable pretty-printer library2 bar
+1 printer disabled
+0 of 3 printers enabled
+(gdb) info pretty-printer library2
+library1.so:
+ foo [disabled]
+library2.so:
+ bar [disabled]
+ bar1 [disabled]
+ bar2
+@end smallexample
+
+Note that for @code{bar} the entire printer can be disabled,
+as can each individual subprinter.
@node Value History
@section Value History
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
+@item $_sdata
+@vindex $_sdata@r{, inspect, convenience variable}
+The variable @code{$_sdata} contains extra collected static tracepoint
+data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that
+@code{$_sdata} could be empty, if not inspecting a trace buffer, or
+if extra static tracepoint data has not been collected.
+
@item $_siginfo
@vindex $_siginfo@r{, convenience variable}
The variable @code{$_siginfo} contains extra signal information
case, @value{GDBN} uses @samp{UTF-8}.
@value{GDBN} can only use certain character sets as its host character
-set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}},
+set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}},
@value{GDBN} will list the host character sets it supports.
@item set charset @var{charset}
a different way (such as with a jump instead of a trap), that is
faster but possibly restricted in where they may be installed.
+@cindex static tracepoints
+@cindex markers, static tracepoints
+@cindex probing markers, static tracepoints
+Regular and fast tracepoints are dynamic tracing facilities, meaning
+that they can be used to insert tracepoints at (almost) any location
+in the target. Some targets may also support controlling @dfn{static
+tracepoints} from @value{GDBN}. With static tracing, a set of
+instrumentation points, also known as @dfn{markers}, are embedded in
+the target program, and can be activated or deactivated by name or
+address. These are usually placed at locations which facilitate
+investigating what the target is actually doing. @value{GDBN}'s
+support for static tracing includes being able to list instrumentation
+points, and attach them with @value{GDBN} defined high level
+tracepoints that expose the whole range of convenience of
+@value{GDBN}'s tracepoints support. Namelly, support for collecting
+registers values and values of global or local (to the instrumentation
+point) variables; tracepoint conditions and trace state variables.
+The act of installing a @value{GDBN} static tracepoint on an
+instrumentation point, or marker, is referred to as @dfn{probing} a
+static tracepoint marker.
+
@code{gdbserver} supports tracepoints on some target systems.
@xref{Server,,Tracepoints support in @code{gdbserver}}.
* Trace State Variables::
* Tracepoint Actions::
* Listing Tracepoints::
+* Listing Static Tracepoint Markers::
* Starting and Stopping Trace Experiments::
* Tracepoint Restrictions::
@end menu
@item ftrace @var{location} [ if @var{cond} ]
@cindex set fast tracepoint
+@cindex fast tracepoints, setting
@kindex ftrace
The @code{ftrace} command sets a fast tracepoint. For targets that
support them, fast tracepoints will use a more efficient but possibly
@value{GDBN} handles arguments to @code{ftrace} exactly as for
@code{trace}.
+@item strace @var{location} [ if @var{cond} ]
+@cindex set static tracepoint
+@cindex static tracepoints, setting
+@cindex probe static tracepoint marker
+@kindex strace
+The @code{strace} command sets a static tracepoint. For targets that
+support it, setting a static tracepoint probes a static
+instrumentation point, or marker, found at @var{location}. It may not
+be possible to set a static tracepoint at the desired location, in
+which case the command will exit with an explanatory message.
+
+@value{GDBN} handles arguments to @code{strace} exactly as for
+@code{trace}, with the addition that the user can also specify
+@code{-m @var{marker}} as @var{location}. This probes the marker
+identified by the @var{marker} string identifier. This identifier
+depends on the static tracepoint backend library your program is
+using. You can find all the marker identifiers in the @samp{ID} field
+of the @code{info static-tracepoint-markers} command output.
+@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint
+Markers}. For example, in the following small program using the UST
+tracing engine:
+
+@smallexample
+main ()
+@{
+ trace_mark(ust, bar33, "str %s", "FOOBAZ");
+@}
+@end smallexample
+
+@noindent
+the marker id is composed of joining the first two arguments to the
+@code{trace_mark} call with a slash, which translates to:
+
+@smallexample
+(@value{GDBP}) info static-tracepoint-markers
+Cnt Enb ID Address What
+1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22
+ Data: "str %s"
+[etc...]
+@end smallexample
+
+@noindent
+so you may probe the marker above with:
+
+@smallexample
+(@value{GDBP}) strace -m ust/bar33
+@end smallexample
+
+Static tracepoints accept an extra collect action --- @code{collect
+$_sdata}. This collects arbitrary user data passed in the probe point
+call to the tracing library. In the UST example above, you'll see
+that the third argument to @code{trace_mark} is a printf-like format
+string. The user data is then the result of running that formating
+string against the following arguments. Note that @code{info
+static-tracepoint-markers} command output lists that format string in
+the @samp{Data:} field.
+
+You can inspect this data when analyzing the trace buffer, by printing
+the $_sdata variable like any other variable available to
+@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}.
+
@vindex $tpnum
@cindex last tracepoint number
@cindex recent tracepoint number
@table @code
@item $regs
-collect all registers
+Collect all registers.
@item $args
-collect all function arguments
+Collect all function arguments.
@item $locals
-collect all local variables.
+Collect all local variables.
+
+@item $_sdata
+@vindex $_sdata@r{, collect}
+Collect static tracepoint marker specific data. Only available for
+static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action
+Lists}. On the UST static tracepoints library backend, an
+instrumentation point resembles a @code{printf} function call. The
+tracing library is able to collect user specified data formatted to a
+character string using the format provided by the programmer that
+instrumented the program. Other backends have similar mechanisms.
+Here's an example of a UST marker call:
+
+@smallexample
+ const char master_name[] = "$your_name";
+ trace_mark(channel1, marker1, "hello %s", master_name)
+@end smallexample
+
+In this case, collecting @code{$_sdata} collects the string
+@samp{hello $yourname}. When analyzing the trace buffer, you can
+inspect @samp{$_sdata} like any other variable available to
+@value{GDBN}.
@end table
You can give several consecutive @code{collect} commands, each one
This command can be abbreviated @code{info tp}.
@end table
+@node Listing Static Tracepoint Markers
+@subsection Listing Static Tracepoint Markers
+
+@table @code
+@kindex info static-tracepoint-markers
+@cindex information about static tracepoint markers
+@item info static-tracepoint-markers
+Display information about all static tracepoint markers defined in the
+program.
+
+For each marker, the following columns are printed:
+
+@table @emph
+@item Count
+An incrementing counter, output to help readability. This is not a
+stable identifier.
+@item ID
+The marker ID, as reported by the target.
+@item Enabled or Disabled
+Probed markers are tagged with @samp{y}. @samp{n} identifies marks
+that are not enabled.
+@item Address
+Where the marker is in your program, as a memory address.
+@item What
+Where the marker is in the source for your program, as a file and line
+number. If the debug information included in the program does not
+allow @value{GDBN} to locate the source of the marker, this column
+will be left blank.
+@end table
+
+@noindent
+In addition, the following information may be printed for each marker:
+
+@table @emph
+@item Data
+User data passed to the tracing library by the marker call. In the
+UST backend, this is the format string passed as argument to the
+marker call.
+@item Static tracepoints probing the marker
+The list of static tracepoints attached to the marker.
+@end table
+
+@smallexample
+(@value{GDBP}) info static-tracepoint-markers
+Cnt ID Enb Address What
+1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25
+ Data: number1 %d number2 %d
+ Probed by static tracepoints: #2
+2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24
+ Data: str %s
+(@value{GDBP})
+@end smallexample
+@end table
+
@node Starting and Stopping Trace Experiments
@subsection Starting and Stopping Trace Experiments
@node Supported Languages
@section Supported Languages
-@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, Pascal,
+@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, OpenCL C, Pascal,
assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
* C:: C and C@t{++}
* D:: D
* Objective-C:: Objective-C
+* OpenCL C:: OpenCL C
* Fortran:: Fortran
* Pascal:: Pascal
* Modula-2:: Modula-2
with certain Objective-C libraries that have a particular hook
function, @code{_NSPrintForDebugger}, defined.
+@node OpenCL C
+@subsection OpenCL C
+
+@cindex OpenCL C
+This section provides information about @value{GDBN}s OpenCL C support.
+
+@menu
+* OpenCL C Datatypes::
+* OpenCL C Expressions::
+* OpenCL C Operators::
+@end menu
+
+@node OpenCL C Datatypes
+@subsubsection OpenCL C Datatypes
+
+@cindex OpenCL C Datatypes
+@value{GDBN} supports the builtin scalar and vector datatypes specified
+by OpenCL 1.1. In addition the half- and double-precision floating point
+data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL
+extensions are also known to @value{GDBN}.
+
+@node OpenCL C Expressions
+@subsubsection OpenCL C Expressions
+
+@cindex OpenCL C Expressions
+@value{GDBN} supports accesses to vector components including the access as
+lvalue where possible. Since OpenCL C is based on C99 most C expressions
+supported by @value{GDBN} can be used as well.
+
+@node OpenCL C Operators
+@subsubsection OpenCL C Operators
+
+@cindex OpenCL C Operators
+@value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and
+vector data types.
+
@node Fortran
@subsection Fortran
@cindex Fortran-specific support in @value{GDBN}
* Stopping Before Main Program:: Debugging the program during elaboration.
* Ada Tasks:: Listing and setting breakpoints in tasks.
* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
+* Ravenscar Profile:: Tasking Support when using the Ravenscar
+ Profile
* Ada Glitches:: Known peculiarities of Ada mode.
@end menu
Under these circumstances, you should make a backup copy of the core
file before inspecting it with @value{GDBN}.
+@node Ravenscar Profile
+@subsubsection Tasking Support when using the Ravenscar Profile
+@cindex Ravenscar Profile
+
+The @dfn{Ravenscar Profile} is a subset of the Ada tasking features,
+specifically designed for systems with safety-critical real-time
+requirements.
+
+@table @code
+@kindex set ravenscar task-switching on
+@cindex task switching with program using Ravenscar Profile
+@item set ravenscar task-switching on
+Allows task switching when debugging a program that uses the Ravenscar
+Profile. This is the default.
+
+@kindex set ravenscar task-switching off
+@item set ravenscar task-switching off
+Turn off task switching when debugging a program that uses the Ravenscar
+Profile. This is mostly intended to disable the code that adds support
+for the Ravenscar Profile, in case a bug in either @value{GDBN} or in
+the Ravenscar runtime is preventing @value{GDBN} from working properly.
+To be effective, this command should be run before the program is started.
+
+@kindex show ravenscar task-switching
+@item show ravenscar task-switching
+Show whether it is possible to switch from task to task in a program
+using the Ravenscar Profile.
+
+@end table
+
@node Ada Glitches
@subsubsection Known Peculiarities of Ada Mode
@cindex Ada, problems
and the GNU Ada compiler.
@itemize @bullet
-@item
-Currently, the debugger
-has insufficient information to determine whether certain pointers represent
-pointers to objects or the objects themselves.
-Thus, the user may have to tack an extra @code{.all} after an expression
-to get it printed properly.
-
@item
Static constants that the compiler chooses not to materialize as objects in
storage are invisible to the debugger.
@menu
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
+* Index Files:: Index files speed up GDB
* Symbol Errors:: Errors reading symbol files
* Data Files:: GDB data files
@end menu
This computation does not apply to the ``build ID'' method.
+@node Index Files
+@section Index Files Speed Up @value{GDBN}
+@cindex index files
+@cindex @samp{.gdb_index} section
+
+When @value{GDBN} finds a symbol file, it scans the symbols in the
+file in order to construct an internal symbol table. This lets most
+@value{GDBN} operations work quickly---at the cost of a delay early
+on. For large programs, this delay can be quite lengthy, so
+@value{GDBN} provides a way to build an index, which speeds up
+startup.
+
+The index is stored as a section in the symbol file. @value{GDBN} can
+write the index to a file, then you can put it into the symbol file
+using @command{objcopy}.
+
+To create an index file, use the @code{save gdb-index} command:
+
+@table @code
+@item save gdb-index @var{directory}
+@kindex save gdb-index
+Create an index file for each symbol file currently known by
+@value{GDBN}. Each file is named after its corresponding symbol file,
+with @samp{.gdb-index} appended, and is written into the given
+@var{directory}.
+@end table
+
+Once you have created an index file you can merge it into your symbol
+file, here named @file{symfile}, using @command{objcopy}:
+
+@smallexample
+$ objcopy --add-section .gdb_index=symfile.gdb-index \
+ --set-section-flags .gdb_index=readonly symfile symfile
+@end smallexample
+
+There are currently some limitation on indices. They only work when
+for DWARF debugging information, not stabs. And, they do not
+currently work for programs using Ada.
+
@node Symbol Errors
@section Errors Reading Symbol Files
automatically if the installed @value{GDBN} is moved to a new
location.
+The data directory may also be specified with the
+@code{--data-directory} command line option.
+@xref{Mode Options}.
+
@node Targets
@chapter Specifying a Debugging Target
@cindex active targets
@cindex multiple targets
-There are three classes of targets: processes, core files, and
-executable files. @value{GDBN} can work concurrently on up to three
-active targets, one in each class. This allows you to (for example)
-start a process and inspect its activity without abandoning your work on
-a core file.
-
-For example, if you execute @samp{gdb a.out}, then the executable file
-@code{a.out} is the only active target. If you designate a core file as
-well---presumably from a prior run that crashed and coredumped---then
-@value{GDBN} has two active targets and uses them in tandem, looking
-first in the corefile target, then in the executable file, to satisfy
-requests for memory addresses. (Typically, these two classes of target
-are complementary, since core files contain only a program's
-read-write memory---variables and so on---plus machine status, while
-executable files contain only the program text and initialized data.)
-
-When you type @code{run}, your executable file becomes an active process
-target as well. When a process target is active, all @value{GDBN}
-commands requesting memory addresses refer to that target; addresses in
-an active core file or executable file target are obscured while the
-process target is active.
-
-Use the @code{core-file} and @code{exec-file} commands to select a new
-core file or executable target (@pxref{Files, ,Commands to Specify
-Files}). To specify as a target a process that is already running, use
-the @code{attach} command (@pxref{Attach, ,Debugging an Already-running
-Process}).
+There are multiple classes of targets such as: processes, executable files or
+recording sessions. Core files belong to the process class, making core file
+and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently
+on multiple active targets, one in each class. This allows you to (for
+example) start a process and inspect its activity, while still having access to
+the executable file after the process finishes. Or if you start process
+recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are
+presented a virtual layer of the recording target, while the process target
+remains stopped at the chronologically last point of the process execution.
+
+Use the @code{core-file} and @code{exec-file} commands to select a new core
+file or executable target (@pxref{Files, ,Commands to Specify Files}). To
+specify as a target a process that is already running, use the @code{attach}
+command (@pxref{Attach, ,Debugging an Already-running Process}).
@node Target Commands
@section Commands for Managing Targets
@subsection Tracepoints support in @code{gdbserver}
@cindex tracepoints support in @code{gdbserver}
-On some targets, @code{gdbserver} supports tracepoints and fast
-tracepoints.
+On some targets, @code{gdbserver} supports tracepoints, fast
+tracepoints and static tracepoints.
-For fast tracepoints to work, a special library called the
+For fast or static tracepoints to work, a special library called the
@dfn{in-process agent} (IPA), must be loaded in the inferior process.
This library is built and distributed as an integral part of
-@code{gdbserver}.
+@code{gdbserver}. In addition, support for static tracepoints
+requires building the in-process agent library with static tracepoints
+support. At present, the UST (LTTng Userspace Tracer,
+@url{http://lttng.org/ust}) tracing engine is supported. This support
+is automatically available if UST development headers are found in the
+standard include path when @code{gdbserver} is built, or if
+@code{gdbserver} was explicitly configured using @option{--with-ust}
+to point at such headers. You can explicitly disable the support
+using @option{--with-ust=no}.
There are several ways to load the in-process agent in your program:
remote}, you'll find that the program is stopped at the dynamic
loader's entry point, and no shared library has been loaded in the
program's address space yet, including the in-process agent. In that
-case, before being able to use any of the fast tracepoints features,
-you need to let the loader run and load the shared libraries. The
-most simple way to do that is to run the program to the main
-procedure. E.g., if debugging a C or C@t{++} program, start
+case, before being able to use any of the fast or static tracepoints
+features, you need to let the loader run and load the shared
+libraries. The simplest way to do that is to run the program to the
+main procedure. E.g., if debugging a C or C@t{++} program, start
@code{gdbserver} like so:
@smallexample
The in-process tracing agent library should now be loaded into the
process; you can confirm it with the @code{info sharedlibrary}
command, which will list @file{libinproctrace.so} as loaded in the
-process. You are now ready to install fast tracepoints and start
+process. You are now ready to install fast tracepoints, list static
+tracepoint markers, probe static tracepoints markers, and start
tracing.
@node Remote Configuration
@tab @code{qXfer:memory-map:read}
@tab @code{info mem}
+@item @code{read-sdata-object}
+@tab @code{qXfer:sdata:read}
+@tab @code{print $_sdata}
+
@item @code{read-spu-object}
@tab @code{qXfer:spu:read}
@tab @code{info spu}
@node PowerPC Embedded
@subsection PowerPC Embedded
+@cindex DVC register
+@value{GDBN} supports using the DVC (Data Value Compare) register to
+implement in hardware simple hardware watchpoint conditions of the form:
+
+@smallexample
+(@value{GDBP}) watch @var{ADDRESS|VARIABLE} \
+ if @var{ADDRESS|VARIABLE} == @var{CONSTANT EXPRESSION}
+@end smallexample
+
+The DVC register will be automatically used when @value{GDBN} detects
+such pattern in a condition expression, and the created watchpoint uses one
+debug register (either the @code{exact-watchpoints} option is on and the
+variable is scalar, or the variable has a length of one byte). This feature
+is available in native @value{GDBN} running on a Linux kernel version 2.6.34
+or newer.
+
+When running on PowerPC embedded processors, @value{GDBN} automatically uses
+ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on,
+in which case watchpoints using only one debug register are created when
+watching variables of scalar types.
+
+You can create an artificial array to watch an arbitrary memory
+region using one of the following commands (@pxref{Expressions}):
+
+@smallexample
+(@value{GDBP}) watch *((char *) @var{address})@@@var{length}
+(@value{GDBP}) watch @{char[@var{length}]@} @var{address}
+@end smallexample
+
@value{GDBN} provides the following PowerPC-specific commands:
@table @code
registers. By default, @value{GDBN} selects the calling convention
based on the selected architecture and the provided executable file.
+@item set powerpc exact-watchpoints
+@itemx show powerpc exact-watchpoints
+Allow @value{GDBN} to use only one debug register when watching a variable
+of scalar type, thus assuming that the variable is accessed through the
+address of its first byte.
+
@kindex target dink32
@item target dink32 @var{dev}
DINK32 ROM monitor.
Show whether command line editing is enabled.
@end table
-@xref{Command Line Editing}, for more details about the Readline
+@ifset SYSTEM_READLINE
+@xref{Command Line Editing, , , rluserman, GNU Readline Library},
+@end ifset
+@ifclear SYSTEM_READLINE
+@xref{Command Line Editing},
+@end ifclear
+for more details about the Readline
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
history facility.
@value{GDBN} uses the @sc{gnu} History library, a part of the Readline
-package, to provide the history facility. @xref{Using History
-Interactively}, for the detailed description of the History library.
+package, to provide the history facility.
+@ifset SYSTEM_READLINE
+@xref{Using History Interactively, , , history, GNU History Library},
+@end ifset
+@ifclear SYSTEM_READLINE
+@xref{Using History Interactively},
+@end ifclear
+for the detailed description of the History library.
To issue a command to @value{GDBN} without affecting certain aspects of
the state which is seen by users, prefix it with @samp{server }
@end table
History expansion assigns special meaning to the character @kbd{!}.
-@xref{Event Designators}, for more details.
+@ifset SYSTEM_READLINE
+@xref{Event Designators, , , history, GNU History Library},
+@end ifset
+@ifclear SYSTEM_READLINE
+@xref{Event Designators},
+@end ifclear
+for more details.
@cindex history expansion, turn on/off
Since @kbd{!} is also the logical not operator in C, history expansion
for implementing operations such as single-stepping the inferior.
@item show debug infrun
Displays the current state of @value{GDBN} inferior debugging.
+@item set debug jit
+@cindex just-in-time compilation, debugging messages
+Turns on or off debugging messages from JIT debug support.
+@item show debug jit
+Displays the current state of @value{GDBN} JIT debugging.
@item set debug lin-lwp
@cindex @sc{gnu}/Linux LWP debug messages
@cindex Linux lightweight processes
Python programming language}. This feature is available only if
@value{GDBN} was configured using @option{--with-python}.
+@cindex python directory
+Python scripts used by @value{GDBN} should be installed in
+@file{@var{data-directory}/python}, where @var{data-directory} is
+the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
+This directory, known as the @dfn{python directory},
+is automatically added to the Python Search Path in order to allow
+the Python interpreter to locate all scripts installed at this location.
+
@menu
* Python Commands:: Accessing Python from @value{GDBN}.
* Python API:: Accessing @value{GDBN} from Python.
* Auto-loading:: Automatically loading Python code.
+* Python modules:: Python modules provided by @value{GDBN}.
@end menu
@node Python Commands
@menu
* Basic Python:: Basic Python Functions.
-* Exception Handling::
-* Values From Inferior::
+* Exception Handling:: How Python exceptions are translated.
+* Values From Inferior:: Python representation of values.
* Types In Python:: Python representation of types.
* Pretty Printing API:: Pretty-printing values.
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
-* Disabling Pretty-Printers:: Disabling broken printers.
+* Writing a Pretty-Printer:: Writing a Pretty-Printer.
+* Inferiors In Python:: Python representation of inferiors (processes)
+* Threads In Python:: Accessing inferior threads from Python.
* Commands In Python:: Implementing new commands in Python.
* Parameters In Python:: Adding new @value{GDBN} parameters.
* Functions In Python:: Writing new convenience functions.
@value{GDBN} automatically @code{import}s the @code{gdb} module for
use in all scripts evaluated by the @code{python} command.
+@findex gdb.PYTHONDIR
+@defvar PYTHONDIR
+A string containing the python directory (@pxref{Python}).
+@end defvar
+
@findex gdb.execute
-@defun execute command [from_tty]
+@defun execute command [from_tty] [to_string]
Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
If a GDB exception happens while @var{command} runs, it is
translated as described in @ref{Exception Handling,,Exception Handling}.
-If no exceptions occur, this function returns @code{None}.
@var{from_tty} specifies whether @value{GDBN} ought to consider this
command as having originated from the user invoking it interactively.
It must be a boolean value. If omitted, it defaults to @code{False}.
+
+By default, any output produced by @var{command} is sent to
+@value{GDBN}'s standard output. If the @var{to_string} parameter is
+@code{True}, then output will be collected by @code{gdb.execute} and
+returned as a string. The default is @code{False}, in which case the
+return value is @code{None}. If @var{to_string} is @code{True}, the
+@value{GDBN} virtual terminal will be temporarily set to unlimited width
+and height, and its pagination will be disabled; @pxref{Screen Size}.
@end defun
@findex gdb.breakpoints
@samp{print object} is a valid parameter name.
If the named parameter does not exist, this function throws a
-@code{RuntimeError}. Otherwise, the parameter's value is converted to
-a Python value of the appropriate type, and returned.
+@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
+parameter's value is converted to a Python value of the appropriate
+type, and returned.
@end defun
@findex gdb.history
and count backward from the last element (i.e., the most recent element) to
find the value to return. If @var{number} is zero, then @value{GDBN} will
return the most recent element. If the element specified by @var{number}
-doesn't exist in the value history, a @code{RuntimeError} exception will be
+doesn't exist in the value history, a @code{gdb.error} exception will be
raised.
If no exception is raised, the return value is always an instance of
convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
@end defun
+@findex gdb.post_event
+@defun post_event event
+Put @var{event}, a callable object taking no arguments, into
+@value{GDBN}'s internal event queue. This callable will be invoked at
+some later point, during @value{GDBN}'s event processing. Events
+posted using @code{post_event} will be run in the order in which they
+were posted; however, there is no way to know when they will be
+processed relative to other events inside @value{GDBN}.
+
+@value{GDBN} is not thread-safe. If your Python program uses multiple
+threads, you must be careful to only call @value{GDBN}-specific
+functions in the main @value{GDBN} thread. @code{post_event} ensures
+this. For example:
+
+@smallexample
+(@value{GDBP}) python
+>import threading
+>
+>class Writer():
+> def __init__(self, message):
+> self.message = message;
+> def __call__(self):
+> gdb.write(self.message)
+>
+>class MyThread1 (threading.Thread):
+> def run (self):
+> gdb.post_event(Writer("Hello "))
+>
+>class MyThread2 (threading.Thread):
+> def run (self):
+> gdb.post_event(Writer("World\n"))
+>
+>MyThread1().start()
+>MyThread2().start()
+>end
+(@value{GDBP}) Hello World
+@end smallexample
+@end defun
+
@findex gdb.write
@defun write string
Print a string to @value{GDBN}'s paginated standard output stream.
never returned.
@end defun
+@findex gdb.solib_name
+@defun solib_name address
+Return the name of the shared library holding the given @var{address}
+as a string, or @code{None}.
+@end defun
+
+@findex gdb.decode_line
+@defun decode_line @r{[}expression@r{]}
+Return locations of the line specified by @var{expression}, or of the
+current line if no argument was given. This function returns a Python
+tuple containing two elements. The first element contains a string
+holding any unparsed section of @var{expression} (or @code{None} if
+the expression has been fully parsed). The second element contains
+either @code{None} or another tuple that contains all the locations
+that match the expression represented as @code{gdb.Symtab_and_line}
+objects (@pxref{Symbol Tables In Python}). If @var{expression} is
+provided, it is decoded the way that @value{GDBN}'s inbuilt
+@code{break} or @code{edit} commands do (@pxref{Specify Location}).
+@end defun
+
@node Exception Handling
@subsubsection Exception Handling
@cindex python exceptions
NameError: name 'foo' is not defined
@end smallexample
-@value{GDBN} errors that happen in @value{GDBN} commands invoked by Python
-code are converted to Python @code{RuntimeError} exceptions. User
-interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
-prompt) is translated to a Python @code{KeyboardInterrupt}
-exception. If you catch these exceptions in your Python code, your
-exception handler will see @code{RuntimeError} or
-@code{KeyboardInterrupt} as the exception type, the @value{GDBN} error
-message as its value, and the Python call stack backtrace at the
-Python statement closest to where the @value{GDBN} error occured as the
+@value{GDBN} errors that happen in @value{GDBN} commands invoked by
+Python code are converted to Python exceptions. The type of the
+Python exception depends on the error.
+
+@ftable @code
+@item gdb.error
+This is the base class for most exceptions generated by @value{GDBN}.
+It is derived from @code{RuntimeError}, for compatibility with earlier
+versions of @value{GDBN}.
+
+If an error occurring in @value{GDBN} does not fit into some more
+specific category, then the generated exception will have this type.
+
+@item gdb.MemoryError
+This is a subclass of @code{gdb.error} which is thrown when an
+operation tried to access invalid memory in the inferior.
+
+@item KeyboardInterrupt
+User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
+prompt) is translated to a Python @code{KeyboardInterrupt} exception.
+@end ftable
+
+In all cases, your exception handler will see the @value{GDBN} error
+message as its value and the Python call stack backtrace at the Python
+statement closest to where the @value{GDBN} error occured as the
traceback.
@findex gdb.GdbError
Again, @code{bar} will also be a @code{gdb.Value} object.
+A @code{gdb.Value} that represents a function can be executed via
+inferior function call. Any arguments provided to the call must match
+the function's prototype, and must be provided in the order specified
+by that prototype.
+
+For example, @code{some_val} is a @code{gdb.Value} instance
+representing a function that takes two integers as arguments. To
+execute this function, call it like so:
+
+@smallexample
+result = some_val (10,20)
+@end smallexample
+
+Any values returned from a function call will be stored as a
+@code{gdb.Value}.
+
The following attributes are provided:
@table @code
@defivar Value type
The type of this @code{gdb.Value}. The value of this attribute is a
-@code{gdb.Type} object.
+@code{gdb.Type} object (@pxref{Types In Python}).
+@end defivar
+
+@defivar Value dynamic_type
+The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
+type information (@acronym{RTTI}) to determine the dynamic type of the
+value. If this value is of class type, it will return the class in
+which the value is embedded, if any. If this value is of pointer or
+reference to a class type, it will compute the dynamic type of the
+referenced object, and return a pointer or reference to that type,
+respectively. In all other cases, it will return the value's static
+type.
+
+Note that this feature will only work when debugging a C@t{++} program
+that includes @acronym{RTTI} for the object in question. Otherwise,
+it will just return the static type of the value as in @kbd{ptype foo}
+(@pxref{Symbols, ptype}).
@end defivar
@end table
The following methods are provided:
@table @code
+@defmethod Value __init__ @var{val}
+Many Python values can be converted directly to a @code{gdb.Value} via
+this object initializer. Specifically:
+
+@table @asis
+@item Python boolean
+A Python boolean is converted to the boolean type from the current
+language.
+
+@item Python integer
+A Python integer is converted to the C @code{long} type for the
+current architecture.
+
+@item Python long
+A Python long is converted to the C @code{long long} type for the
+current architecture.
+
+@item Python float
+A Python float is converted to the C @code{double} type for the
+current architecture.
+
+@item Python string
+A Python string is converted to a target string, using the current
+target encoding.
+
+@item @code{gdb.Value}
+If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
+
+@item @code{gdb.LazyString}
+If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
+Python}), then the lazy string's @code{value} method is called, and
+its result is used.
+@end table
+@end defmethod
+
@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
value pointed to by @code{foo}.
@end defmethod
+@defmethod Value dynamic_cast type
+Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
+operator were used. Consult a C@t{++} reference for details.
+@end defmethod
+
+@defmethod Value reinterpret_cast type
+Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
+operator were used. Consult a C@t{++} reference for details.
+@end defmethod
+
@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
@end table
@end defmethod
+@defmethod Type array @var{n1} @r{[}@var{n2}@r{]}
+Return a new @code{gdb.Type} object which represents an array of this
+type. If one argument is given, it is the inclusive upper bound of
+the array; in this case the lower bound is zero. If two arguments are
+given, the first argument is the lower bound of the array, and the
+second argument is the upper bound of the array. An array's length
+must not be negative, but the bounds can be.
+@end defmethod
+
@defmethod Type const
Return a new @code{gdb.Type} object which represents a
@code{const}-qualified variant of this type.
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.
+@code{gdb.error} exception (@pxref{Exception Handling}).
@end defmethod
@defmethod Type reference
convenience functions.
@end table
+Further support for types is provided in the @code{gdb.types}
+Python module (@pxref{gdb.types}).
+
@node Pretty Printing API
@subsubsection Pretty Printing API
If the result is not one of these types, an exception is raised.
@end defop
+@value{GDBN} provides a function which can be used to look up the
+default pretty-printer for a @code{gdb.Value}:
+
+@findex gdb.default_visualizer
+@defun default_visualizer value
+This function takes a @code{gdb.Value} object as an argument. If a
+pretty-printer for this value exists, then it is returned. If no such
+printer exists, then this returns @code{None}.
+@end defun
+
@node Selecting Pretty-Printers
@subsubsection Selecting Pretty-Printers
The Python list @code{gdb.pretty_printers} contains an array of
functions or callable objects that have been registered via addition
-as a pretty-printer.
+as a pretty-printer. Printers in this list are called @code{global}
+printers, they're available when debugging all inferiors.
Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
Each @code{gdb.Objfile} also contains a @code{pretty_printers}
attribute.
-A function on one of these lists is passed a single @code{gdb.Value}
+Each function on these lists is passed a single @code{gdb.Value}
argument and should return a pretty-printer object conforming to the
interface definition above (@pxref{Pretty Printing API}). If a function
cannot create a pretty-printer for the value, it should return
@value{GDBN} first checks the @code{pretty_printers} attribute of each
@code{gdb.Objfile} in the current program space and iteratively calls
-each enabled function (@pxref{Disabling Pretty-Printers})
-in the list for that @code{gdb.Objfile} until it receives
-a pretty-printer object.
+each enabled lookup routine in the list for that @code{gdb.Objfile}
+until it receives a pretty-printer object.
If no pretty-printer is found in the objfile lists, @value{GDBN} then
searches the pretty-printer list of the current program space,
calling each enabled function until an object is returned.
and iterated over sequentially until the end of the list, or a printer
object is returned.
+For various reasons a pretty-printer may not work.
+For example, the underlying data structure may have changed and
+the pretty-printer is out of date.
+
+The consequences of a broken pretty-printer are severe enough that
+@value{GDBN} provides support for enabling and disabling individual
+printers. For example, if @code{print frame-arguments} is on,
+a backtrace can become highly illegible if any argument is printed
+with a broken printer.
+
+Pretty-printers are enabled and disabled by attaching an @code{enabled}
+attribute to the registered function or callable object. If this attribute
+is present and its value is @code{False}, the printer is disabled, otherwise
+the printer is enabled.
+
+@node Writing a Pretty-Printer
+@subsubsection Writing a Pretty-Printer
+@cindex writing a pretty-printer
+
+A pretty-printer consists of two parts: a lookup function to detect
+if the type is supported, and the printer itself.
+
Here is an example showing how a @code{std::string} printer might be
-written:
+written. @xref{Pretty Printing API}, for details on the API this class
+must provide.
@smallexample
-class StdStringPrinter:
+class StdStringPrinter(object):
"Print a std::string"
- def __init__ (self, val):
+ def __init__(self, val):
self.val = val
- def to_string (self):
+ def to_string(self):
return self.val['_M_dataplus']['_M_p']
- def display_hint (self):
+ def display_hint(self):
return 'string'
@end smallexample
example above might be written.
@smallexample
-def str_lookup_function (val):
-
+def str_lookup_function(val):
lookup_tag = val.type.tag
- regex = re.compile ("^std::basic_string<char,.*>$")
if lookup_tag == None:
return None
- if regex.match (lookup_tag):
- return StdStringPrinter (val)
-
+ regex = re.compile("^std::basic_string<char,.*>$")
+ if regex.match(lookup_tag):
+ return StdStringPrinter(val)
return None
@end smallexample
this code might appear in @code{gdb.libstdcxx.v6}:
@smallexample
-def register_printers (objfile):
- objfile.pretty_printers.add (str_lookup_function)
+def register_printers(objfile):
+ objfile.pretty_printers.add(str_lookup_function)
@end smallexample
@noindent
@smallexample
import gdb.libstdcxx.v6
-gdb.libstdcxx.v6.register_printers (gdb.current_objfile ())
+gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
@end smallexample
-@node Disabling Pretty-Printers
-@subsubsection Disabling Pretty-Printers
-@cindex disabling pretty-printers
+The previous example illustrates a basic pretty-printer.
+There are a few things that can be improved on.
+The printer doesn't have a name, making it hard to identify in a
+list of installed printers. The lookup function has a name, but
+lookup functions can have arbitrary, even identical, names.
-For various reasons a pretty-printer may not work.
-For example, the underlying data structure may have changed and
-the pretty-printer is out of date.
+Second, the printer only handles one type, whereas a library typically has
+several types. One could install a lookup function for each desired type
+in the library, but one could also have a single lookup function recognize
+several types. The latter is the conventional way this is handled.
+If a pretty-printer can handle multiple data types, then its
+@dfn{subprinters} are the printers for the individual data types.
-The consequences of a broken pretty-printer are severe enough that
-@value{GDBN} provides support for enabling and disabling individual
-printers. For example, if @code{print frame-arguments} is on,
-a backtrace can become highly illegible if any argument is printed
-with a broken printer.
+The @code{gdb.printing} module provides a formal way of solving these
+problems (@pxref{gdb.printing}).
+Here is another example that handles multiple types.
-Pretty-printers are enabled and disabled by attaching an @code{enabled}
-attribute to the registered function or callable object. If this attribute
-is present and its value is @code{False}, the printer is disabled, otherwise
-the printer is enabled.
+These are the types we are going to pretty-print:
+
+@smallexample
+struct foo @{ int a, b; @};
+struct bar @{ struct foo x, y; @};
+@end smallexample
+
+Here are the printers:
+
+@smallexample
+class fooPrinter:
+ """Print a foo object."""
+
+ def __init__(self, val):
+ self.val = val
+
+ def to_string(self):
+ return ("a=<" + str(self.val["a"]) +
+ "> b=<" + str(self.val["b"]) + ">")
+
+class barPrinter:
+ """Print a bar object."""
+
+ def __init__(self, val):
+ self.val = val
+
+ def to_string(self):
+ return ("x=<" + str(self.val["x"]) +
+ "> y=<" + str(self.val["y"]) + ">")
+@end smallexample
+
+This example doesn't need a lookup function, that is handled by the
+@code{gdb.printing} module. Instead a function is provided to build up
+the object that handles the lookup.
+
+@smallexample
+import gdb.printing
+
+def build_pretty_printer():
+ pp = gdb.printing.RegexpCollectionPrettyPrinter(
+ "my_library")
+ pp.add_printer('foo', '^foo$', fooPrinter)
+ pp.add_printer('bar', '^bar$', barPrinter)
+ return pp
+@end smallexample
+
+And here is the autoload support:
+
+@smallexample
+import gdb.printing
+import my_library
+gdb.printing.register_pretty_printer(
+ gdb.current_objfile(),
+ my_library.build_pretty_printer())
+@end smallexample
+
+Finally, when this printer is loaded into @value{GDBN}, here is the
+corresponding output of @samp{info pretty-printer}:
+
+@smallexample
+(gdb) info pretty-printer
+my_library.so:
+ my_library
+ foo
+ bar
+@end smallexample
+
+@node Inferiors In Python
+@subsubsection Inferiors In Python
+@cindex inferiors in python
+
+@findex gdb.Inferior
+Programs which are being run under @value{GDBN} are called inferiors
+(@pxref{Inferiors and Programs}). Python scripts can access
+information about and manipulate inferiors controlled by @value{GDBN}
+via objects of the @code{gdb.Inferior} class.
+
+The following inferior-related functions are available in the @code{gdb}
+module:
+
+@defun inferiors
+Return a tuple containing all inferior objects.
+@end defun
+
+A @code{gdb.Inferior} object has the following attributes:
+
+@table @code
+@defivar Inferior num
+ID of inferior, as assigned by GDB.
+@end defivar
+
+@defivar Inferior pid
+Process ID of the inferior, as assigned by the underlying operating
+system.
+@end defivar
+
+@defivar Inferior was_attached
+Boolean signaling whether the inferior was created using `attach', or
+started by @value{GDBN} itself.
+@end defivar
+@end table
+
+A @code{gdb.Inferior} object has the following methods:
+
+@table @code
+@defmethod Inferior threads
+This method returns a tuple holding all the threads which are valid
+when it is called. If there are no valid threads, the method will
+return an empty tuple.
+@end defmethod
+
+@findex gdb.read_memory
+@defmethod Inferior read_memory address length
+Read @var{length} bytes of memory from the inferior, starting at
+@var{address}. Returns a buffer object, which behaves much like an array
+or a string. It can be modified and given to the @code{gdb.write_memory}
+function.
+@end defmethod
+
+@findex gdb.write_memory
+@defmethod Inferior write_memory address buffer @r{[}length@r{]}
+Write the contents of @var{buffer} to the inferior, starting at
+@var{address}. The @var{buffer} parameter must be a Python object
+which supports the buffer protocol, i.e., a string, an array or the
+object returned from @code{gdb.read_memory}. If given, @var{length}
+determines the number of bytes from @var{buffer} to be written.
+@end defmethod
+
+@findex gdb.search_memory
+@defmethod Inferior search_memory address length pattern
+Search a region of the inferior memory starting at @var{address} with
+the given @var{length} using the search pattern supplied in
+@var{pattern}. The @var{pattern} parameter must be a Python object
+which supports the buffer protocol, i.e., a string, an array or the
+object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
+containing the address where the pattern was found, or @code{None} if
+the pattern could not be found.
+@end defmethod
+@end table
+
+@node Threads In Python
+@subsubsection Threads In Python
+@cindex threads in python
+
+@findex gdb.InferiorThread
+Python scripts can access information about, and manipulate inferior threads
+controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
+
+The following thread-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.selected_thread
+@defun selected_thread
+This function returns the thread object for the selected thread. If there
+is no selected thread, this will return @code{None}.
+@end defun
+
+A @code{gdb.InferiorThread} object has the following attributes:
+
+@table @code
+@defivar InferiorThread num
+ID of the thread, as assigned by GDB.
+@end defivar
+
+@defivar InferiorThread ptid
+ID of the thread, as assigned by the operating system. This attribute is a
+tuple containing three integers. The first is the Process ID (PID); the second
+is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
+Either the LWPID or TID may be 0, which indicates that the operating system
+does not use that identifier.
+@end defivar
+@end table
+
+A @code{gdb.InferiorThread} object has the following methods:
+
+@table @code
+@defmethod InferiorThread switch
+This changes @value{GDBN}'s currently selected thread to the one represented
+by this object.
+@end defmethod
+
+@defmethod InferiorThread is_stopped
+Return a Boolean indicating whether the thread is stopped.
+@end defmethod
+
+@defmethod InferiorThread is_running
+Return a Boolean indicating whether the thread is running.
+@end defmethod
+
+@defmethod InferiorThread is_exited
+Return a Boolean indicating whether the thread is exited.
+@end defmethod
+@end table
@node Commands In Python
@subsubsection Commands In Python
stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
represents a frame in the stack. A @code{gdb.Frame} object is only valid
while its corresponding frame exists in the inferior's stack. If you try
-to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError}
-exception.
+to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
+exception (@pxref{Exception Handling}).
Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
operator, like:
Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
@end defun
+@findex gdb.newest_frame
+@defun newest_frame
+Return the newest frame object for the selected thread.
+@end defun
+
@defun frame_stop_reason_string reason
Return a string explaining the reason why @value{GDBN} stopped unwinding
frames, as expressed by the given @var{reason} code (an integer, see the
@end defmethod
@defmethod Frame type
-Returns the type of the frame. The value can be one of
-@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
-or @code{gdb.SENTINEL_FRAME}.
+Returns the type of the frame. The value can be one of:
+@table @code
+@item gdb.NORMAL_FRAME
+An ordinary stack frame.
+
+@item gdb.DUMMY_FRAME
+A fake stack frame that was created by @value{GDBN} when performing an
+inferior function call.
+
+@item gdb.INLINE_FRAME
+A frame representing an inlined function. The function was inlined
+into a @code{gdb.NORMAL_FRAME} that is older than this one.
+
+@item gdb.SIGTRAMP_FRAME
+A signal trampoline frame. This is the frame created by the OS when
+it calls into a signal handler.
+
+@item gdb.ARCH_FRAME
+A fake stack frame representing a cross-architecture call.
+
+@item gdb.SENTINEL_FRAME
+This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
+newest frame.
+@end table
@end defmethod
@defmethod Frame unwind_stop_reason
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
-@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]}
+@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]} @r{[}internal@r{]}
Create a new breakpoint. @var{spec} is a string naming the
location of the breakpoint, or an expression that defines a
watchpoint. The contents can be any location recognized by the
command. The optional @var{type} denotes the breakpoint to create
from the types defined later in this chapter. This argument can be
either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}. @var{type}
-defaults to @code{BP_BREAKPOINT}. The optional @var{wp_class}
+defaults to @code{BP_BREAKPOINT}. The optional @var{internal} argument
+allows the breakpoint to become invisible to the user. The breakpoint
+will neither be reported when created, nor will it be listed in the
+output from @code{info breakpoints} (but will be listed with the
+@code{maint info breakpoints} command). The optional @var{wp_class}
argument defines the class of watchpoint to create, if @var{type} is
-defined as @code{BP_WATCHPOINT}. If a watchpoint class is not
-provided, it is assumed to be a @var{WP_WRITE} class.
+@code{BP_WATCHPOINT}. If a watchpoint class is not provided, it is
+assumed to be a @var{WP_WRITE} class.
@end defmethod
The available watchpoint types represented by constants are defined in the
inferior leaves the scope of that watchpoint.
@end defmethod
+@defmethod Breakpoint delete
+Permanently deletes the @value{GDBN} breakpoint. This also
+invalidates the Python @code{Breakpoint} object. Any further access
+to this object's attributes or methods will raise an error.
+@end defmethod
+
@defivar Breakpoint enabled
This attribute is @code{True} if the breakpoint is enabled, and
@code{False} otherwise. This attribute is writable.
writable.
@end defivar
+@defivar Breakpoint visible
+This attribute tells whether the breakpoint is visible to the user
+when set, or when the @samp{info breakpoints} command is run. This
+attribute is not writable.
+@end defivar
+
The available types are represented by constants defined in the @code{gdb}
module:
Auto-loading can be enabled or disabled.
@table @code
-@kindex maint set python auto-load
-@item maint set python auto-load [yes|no]
-Enable or disable the Python auto-loading feature.
+@kindex set auto-load-scripts
+@item set auto-load-scripts [yes|no]
+Enable or disable the auto-loading of Python scripts.
-@kindex maint show python auto-load
-@item maint show python auto-load
-Show whether Python auto-loading is enabled or disabled.
+@kindex show auto-load-scripts
+@item show auto-load-scripts
+Show whether auto-loading of Python scripts is enabled or disabled.
@end table
When reading an auto-loaded file, @value{GDBN} sets the
for example, this GCC macro:
@example
-/* Note: The "MS" section flags are to remote duplicates. */
+/* Note: The "MS" section flags are to remove duplicates. */
#define DEFINE_GDB_SCRIPT(script_name) \
asm("\
.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
top of the source tree to the source search path.
@end itemize
+@node Python modules
+@subsection Python modules
+@cindex python modules
+
+@value{GDBN} comes with a module to assist writing Python code.
+
+@menu
+* gdb.printing:: Building and registering pretty-printers.
+* gdb.types:: Utilities for working with types.
+@end menu
+
+@node gdb.printing
+@subsubsection gdb.printing
+@cindex gdb.printing
+
+This module provides a collection of utilities for working with
+pretty-printers.
+
+@table @code
+@item PrettyPrinter (@var{name}, @var{subprinters}=None)
+This class specifies the API that makes @samp{info pretty-printer},
+@samp{enable pretty-printer} and @samp{disable pretty-printer} work.
+Pretty-printers should generally inherit from this class.
+
+@item SubPrettyPrinter (@var{name})
+For printers that handle multiple types, this class specifies the
+corresponding API for the subprinters.
+
+@item RegexpCollectionPrettyPrinter (@var{name})
+Utility class for handling multiple printers, all recognized via
+regular expressions.
+@xref{Writing a Pretty-Printer}, for an example.
+
+@item register_pretty_printer (@var{obj}, @var{printer})
+Register @var{printer} with the pretty-printer list of @var{obj}.
+@end table
+
+@node gdb.types
+@subsubsection gdb.types
+@cindex gdb.types
+
+This module provides a collection of utilities for working with
+@code{gdb.Types} objects.
+
+@table @code
+@item get_basic_type (@var{type})
+Return @var{type} with const and volatile qualifiers stripped,
+and with typedefs and C@t{++} references converted to the underlying type.
+
+C@t{++} example:
+
+@smallexample
+typedef const int const_int;
+const_int foo (3);
+const_int& foo_ref (foo);
+int main () @{ return 0; @}
+@end smallexample
+
+Then in gdb:
+
+@smallexample
+(gdb) start
+(gdb) python import gdb.types
+(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
+(gdb) python print gdb.types.get_basic_type(foo_ref.type)
+int
+@end smallexample
+
+@item has_field (@var{type}, @var{field})
+Return @code{True} if @var{type}, assumed to be a type with fields
+(e.g., a structure or union), has field @var{field}.
+
+@item make_enum_dict (@var{enum_type})
+Return a Python @code{dictionary} type produced from @var{enum_type}.
+@end table
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
@cindex TUI key bindings
The TUI installs several key bindings in the readline keymaps
-(@pxref{Command Line Editing}). The following key bindings
-are installed for both TUI mode and the @value{GDBN} standard mode.
+@ifset SYSTEM_READLINE
+(@pxref{Command Line Editing, , , rluserman, GNU Readline Library}).
+@end ifset
+@ifclear SYSTEM_READLINE
+(@pxref{Command Line Editing}).
+@end ifclear
+The following key bindings are installed for both TUI mode and the
+@value{GDBN} standard mode.
@table @kbd
@kindex C-x C-a
Function name.
@item @var{file}
File name of the source file where the function lives.
+@item @var{fullname}
+The full file name of the source file where the function lives.
@item @var{line}
Line number corresponding to the @code{$pc}.
+@item @var{from}
+The shared library where this function is defined. This is only given
+if the frame's function is not known.
@end table
If invoked without arguments, this command prints a backtrace for the
Return a list of the children of the specified variable object and
create variable objects for them, if they do not already exist. With
-a single argument or if @var{print-values} has a value for of 0 or
+a single argument or if @var{print-values} has a value of 0 or
@code{--no-values}, print only the names of the variables; if
@var{print-values} is 1 or @code{--all-values}, also print their
values; and if it is 2 or @code{--simple-values} print the name and
@subheading The @code{-data-read-memory} Command
@findex -data-read-memory
+This command is deprecated, use @code{-data-read-memory-bytes} instead.
+
@subsubheading Synopsis
@smallexample
(gdb)
@end smallexample
+@subheading The @code{-data-read-memory-bytes} Command
+@findex -data-read-memory-bytes
+
+@subsubheading Synopsis
+
+@smallexample
+ -data-read-memory-bytes [ -o @var{byte-offset} ]
+ @var{address} @var{count}
+@end smallexample
+
+@noindent
+where:
+
+@table @samp
+@item @var{address}
+An expression specifying the address of the first memory word to be
+read. Complex expressions containing embedded white space should be
+quoted using the C convention.
+
+@item @var{count}
+The number of bytes to read. This should be an integer literal.
+
+@item @var{byte-offset}
+The offsets in bytes relative to @var{address} at which to start
+reading. This should be an integer literal. This option is provided
+so that a frontend is not required to first evaluate address and then
+perform address arithmetics itself.
+
+@end table
+
+This command attempts to read all accessible memory regions in the
+specified range. First, all regions marked as unreadable in the memory
+map (if one is defined) will be skipped. @xref{Memory Region
+Attributes}. Second, @value{GDBN} will attempt to read the remaining
+regions. For each one, if reading full region results in an errors,
+@value{GDBN} will try to read a subset of the region.
+
+In general, every single byte in the region may be readable or not,
+and the only way to read every readable byte is to try a read at
+every address, which is not practical. Therefore, @value{GDBN} will
+attempt to read all accessible bytes at either beginning or the end
+of the region, using a binary division scheme. This heuristic works
+well for reading accross a memory map boundary. Note that if a region
+has a readable range that is neither at the beginning or the end,
+@value{GDBN} will not read it.
+
+The result record (@pxref{GDB/MI Result Records}) that is output of
+the command includes a field named @samp{memory} whose content is a
+list of tuples. Each tuple represent a successfully read memory block
+and has the following fields:
+
+@table @code
+@item begin
+The start address of the memory block, as hexadecimal literal.
+
+@item end
+The end address of the memory block, as hexadecimal literal.
+
+@item offset
+The offset of the memory block, as hexadecimal literal, relative to
+the start address passed to @code{-data-read-memory-bytes}.
+
+@item contents
+The contents of the memory block, in hex.
+
+@end table
+
+
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{x}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-data-read-memory-bytes &a 10
+^done,memory=[@{begin="0xbffff154",offset="0x00000000",
+ end="0xbffff15e",
+ contents="01000000020000000300"@}]
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-data-write-memory-bytes} Command
+@findex -data-write-memory-bytes
+
+@subsubheading Synopsis
+
+@smallexample
+ -data-write-memory-bytes @var{address} @var{contents}
+@end smallexample
+
+@noindent
+where:
+
+@table @samp
+@item @var{address}
+An expression specifying the address of the first memory word to be
+read. Complex expressions containing embedded white space should be
+quoted using the C convention.
+
+@item @var{contents}
+The hex-encoded bytes to write.
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+There's no corresponding @value{GDBN} command.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-data-write-memory-bytes &a "aabbccdd"
+^done
+(gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Tracepoint Commands
@section @sc{gdb/mi} Tracepoint Commands
@samp{display_hint} field in the output of @code{-var-list-children}
@item thread-info
Indicates presence of the @code{-thread-info} command.
+@item data-read-memory-bytes
+Indicates presense of the @code{-data-read-memory-bytes} and the
+@code{-data-write-memory-bytes} commands.
@end table
execution, which means that @value{GDBN} will accept further commands
while the target is running.
+@item reverse
+Indicates that the target is capable of reverse execution.
+@xref{Reverse Execution}, for more information.
+
@end table
@subheading The @code{-list-thread-groups} Command
@c inc-hist.texinfo
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
+@ifclear SYSTEM_READLINE
@include rluser.texi
@include inc-hist.texinfo
+@end ifclear
@node Formatting Documentation
determined by the @value{GDBN} internal gdbarch functions
@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
specification of several standard @samp{g} packets is specified below.
+
+When reading registers from a trace frame (@pxref{Analyze Collected
+Data,,Using the Collected Data}), the stub may also return a string of
+literal @samp{x}'s in place of the register data digits, to indicate
+that the corresponding register has not been collected, thus its value
+is unavailable. For example, for an architecture with 4 registers of
+4 bytes each, the following reply indicates to @value{GDBN} that
+registers 0 and 2 have not been collected, while registers 1 and 3
+have been collected, and both have zero value:
+
+@smallexample
+-> @code{g}
+<- @code{xxxxxxxx00000000xxxxxxxx00000000}
+@end smallexample
+
@item E @var{NN}
for an error.
@end table
more thread IDs, separated by commas.
@value{GDBN} will respond to each reply with a request for more thread
ids (using the @samp{qs} form of the query), until the target responds
-with @samp{l} (lower-case el, for @dfn{last}).
+with @samp{l} (lower-case ell, for @dfn{last}).
Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
fields.
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:sdata:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:spu:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
+@item qXfer:sdata:read
+The remote stub understands the @samp{qXfer:sdata:read} packet
+(@pxref{qXfer sdata read}).
+
@item qXfer:spu:read
The remote stub understands the @samp{qXfer:spu:read} packet
(@pxref{qXfer spu read}).
@item QAllow
The remote stub understands the @samp{QAllow} packet.
+@item StaticTracepoint
+@cindex static tracepoints, in remote protocol
+The remote stub supports static tracepoints.
+
@end table
@item qSymbol::
@itemx QTro
@itemx qTStatus
@itemx qTV
+@itemx qTfSTM
+@itemx qTsSTM
+@itemx qTSTMat
@xref{Tracepoint Packets}.
@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:sdata:read::@var{offset},@var{length}
+@anchor{qXfer sdata read}
+
+Read contents of the extra collected static tracepoint marker
+information. The annex part of the generic @samp{qXfer} packet must
+be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint
+Action Lists}.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
@item qXfer:siginfo:read::@var{offset},@var{length}
@anchor{qXfer siginfo read}
Read contents of the extra signal information on the target
these packets follow the syntax of the @code{QTDV} packets that define
trace state variables.
+@item qTfSTM
+@itemx qTsSTM
+These packets request data about static tracepoint markers that exist
+in the target program. @value{GDBN} sends @code{qTfSTM} to get the
+first piece of data, and multiple @code{qTsSTM} to get additional
+pieces. Replies to these packets take the following form:
+
+Reply:
+@table @samp
+@item m @var{address}:@var{id}:@var{extra}
+A single marker
+@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{}
+a comma-separated list of markers
+@item l
+(lower case letter @samp{L}) denotes end of list.
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+@item
+An empty reply indicates that the request is not supported by the
+stub.
+@end table
+
+@var{address} is encoded in hex.
+@var{id} and @var{extra} are strings encoded in hex.
+
+In response to each query, the target will reply with a list of one or
+more markers, separated by commas. @value{GDBN} will respond to each
+reply with a request for more markers (using the @samp{qs} form of the
+query), until the target responds with @samp{l} (lower-case ell, for
+@dfn{last}).
+
+@item qTSTMat:@var{address}
+This packets requests data about static tracepoint markers in the
+target program at @var{address}. Replies to this packet follow the
+syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static
+tracepoint markers.
+
@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
@subsection ARM Features
@cindex target descriptions, ARM features
-The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets.
+The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile
+ARM targets.
It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
@samp{lr}, @samp{pc}, and @samp{cpsr}.
+For M-profile targets (e.g. Cortex-M3), the @samp{org.gnu.gdb.arm.core}
+feature is replaced by @samp{org.gnu.gdb.arm.m-profile}. It should contain
+registers @samp{r0} through @samp{r13}, @samp{sp}, @samp{lr}, @samp{pc},
+and @samp{xpsr}.
+
The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it
should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
@samp{ymm0h} through @samp{ymm7h} for i386
@item
@samp{ymm0h} through @samp{ymm15h} for amd64
-@item
@end itemize
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
projects / binutils-gdb.git / blobdiff