* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
-* TUI:: @value{GDBN} Text User Interface
* Interpreters:: Command Interpreters
+* TUI:: @value{GDBN} Text User Interface
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
-* Annotations:: @value{GDBN}'s annotation interface.
* GDB/MI:: @value{GDBN}'s Machine Interface.
+* Annotations:: @value{GDBN}'s annotation interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Command Line Editing:: Command Line Editing
* Using History Interactively:: Using History Interactively
+* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Installing GDB:: Installing GDB
* Maintenance Commands:: Maintenance Commands
* Remote Protocol:: GDB Remote Serial Protocol
executable file to the inferior using @code{--args}. This option stops
option processing.
@smallexample
-gdb --args gcc -O2 -c foo.c
+@value{GDBP} --args gcc -O2 -c foo.c
@end smallexample
This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
When @value{GDBN} starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
the same as if the arguments were specified by the @samp{-se} and
-@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the
+@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
first argument that does not have an associated option flag as
equivalent to the @samp{-se} option followed by that argument; and the
second argument that does not have an associated option flag, if any, as
@cindex init file name
@cindex @file{.gdbinit}
-The @value{GDBN} init files are normally called @file{.gdbinit}.
-On some configurations of @value{GDBN}, the init file is known by a
-different name (these are typically environments where a specialized
-form of @value{GDBN} may need to coexist with other forms, hence a
-different name for the specialized version's init file). These are the
-environments with special init file names:
-
-@itemize @bullet
@cindex @file{gdb.ini}
-@item
+The @value{GDBN} init files are normally called @file{.gdbinit}.
The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
the limitations of file names imposed by DOS filesystems. The Windows
ports of @value{GDBN} use the standard name, but if they find a
@file{gdb.ini} file, they warn you about that and suggest to rename
the file to the standard name.
-@cindex @file{.vxgdbinit}
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-
-@item
-CISCO 68k: @file{.cisco-gdbinit}
-@end itemize
-
@node Quitting GDB
@section Quitting @value{GDBN}
stack -- Examining the stack
status -- Status inquiries
support -- Support facilities
-tracepoints -- Tracing of program execution without@*
+tracepoints -- Tracing of program execution without
stopping the program
user-defined -- User-defined commands
@c Line break in "show" line falsifies real output, but needed
@c to fit in smallbook page size.
info -- Generic command for showing things
- about the program being debugged
+ about the program being debugged
show -- Generic command for showing things
- about the debugger
+ about the debugger
Type "help" followed by command name for full
documentation.
@smallexample
@c @group
set symbol-reloading -- Set dynamic symbol table reloading
- multiple times in one run
+ multiple times in one run
show symbol-reloading -- Show dynamic symbol table reloading
- multiple times in one run
+ multiple times in one run
@c @end group
@end smallexample
the target system's identification for the thread with a message in the
form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
whose form varies depending on the particular system. For example, on
-LynxOS, you might see
+@sc{gnu}/Linux, you might see
@smallexample
-[New process 35 thread 27]
+[New Thread 46912507313328 (LWP 25582)]
@end smallexample
@noindent
operate. A breakpoint range is either a single breakpoint number, like
@samp{5}, or two such numbers, in increasing order, separated by a
hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
-all breakpoint in that range are operated on.
+all breakpoints in that range are operated on.
@menu
* Set Breaks:: Setting breakpoints
@c underflow problems.
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
-without stack frames. (For example, the @value{GCC} option
+without stack frames. (For example, the @value{NGCC} option
@smallexample
@samp{-fomit-frame-pointer}
@end smallexample
Using the previous example, suppose the @file{foo-1.0} tree has been
moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
-GDB to replace @file{/usr/src} in all source path names with
+@value{GDBN} to replace @file{/usr/src} in all source path names with
@file{/mnt/cross}. The first lookup will then be
@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
the debugger behavior to look at the rewritten location instead. So, if
for any reason a source file that is not relevant to your executable is
located at the original location, a substitution rule is the only
-method available to point GDB at the new location.
+method available to point @value{GDBN} at the new location.
@table @code
@item directory @var{dirname} @dots{}
using the colon-colon (@code{::}) notation:
@cindex colon-colon, context for variables/functions
-@iftex
+@ifnotinfo
@c info cannot cope with a :: index entry, but why deprive hard copy readers?
@cindex @code{::}, context for variables/functions
-@end iftex
+@end ifnotinfo
@smallexample
@var{file}::@var{variable}
@var{function}::@var{variable}
produces debug info in a format that is superior to formats such as
COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
an effective form for debug info. @xref{Debugging Options,,Options
-for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
-@xref{C, , Debugging C++}, for more info about debug info formats
+for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu}
+Compiler Collection (GCC)}.
+@xref{C, , Debugging C++}, for more information about debug info formats
that are best suited to C@t{++} programs.
If you ask to print an object whose contents are unknown to
by the debug information, @value{GDBN} will say @samp{<incomplete
type>}. @xref{Symbols, incomplete type}, for more about this.
+Strings are identified as arrays of @code{char} values without specified
+signedness. Arrays of either @code{signed char} or @code{unsigned char} get
+printed as arrays of 1 byte sized integers. @code{-fsigned-char} or
+@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN}
+defines literal string type @code{"char"} as @code{char} without a sign.
+For program code
+
+@smallexample
+char var0[] = "A";
+signed char var1[] = "A";
+@end smallexample
+
+You get during debugging
+@smallexample
+(gdb) print var0
+$1 = "A"
+(gdb) print var1
+$2 = @{65 'A', 0 '\0'@}
+@end smallexample
+
@node Arrays
@section Artificial arrays
@end table
Note that these are all single-byte character sets. More work inside
-GDB is needed to support multi-byte or variable-width character
+@value{GDBN} is needed to support multi-byte or variable-width character
encodings, like the UTF-8 and UCS-2 encodings of Unicode.
Here is an example of @value{GDBN}'s character set support in action.
@code{ADD} --- but does not expand the invocation of the macro @code{M},
which was introduced by @code{ADD}.
-Once the program is running, GDB uses the macro definitions in force at
-the source line of the current stack frame:
+Once the program is running, @value{GDBN} uses the macro definitions in
+force at the source line of the current stack frame:
@smallexample
(@value{GDBP}) break main
format; if it doesn't work on your system, try the stabs+ debugging
format. You can select those formats explicitly with the @code{g++}
command-line options @option{-gdwarf-2} and @option{-gstabs+}.
-@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
-CC, gcc.info, Using @sc{gnu} CC}.
+@xref{Debugging Options,,Options for Debugging Your Program or GCC,
+gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}.
@menu
* C Operators:: C and C@t{++} operators
attempts to invoke the redefined version instead of using the operator's
predefined meaning.
-@menu
-* C Constants::
-@end menu
-
@node C Constants
@subsubsection C and C@t{++} constants
and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
@end itemize
-@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
-
-* Debugging C::
-@end menu
-
@node C plus plus expressions
@subsubsection C@t{++} expressions
with pointers and a memory allocation function. @xref{Expressions,
,Expressions}.
-@menu
-* Debugging C plus plus::
-@end menu
-
@node Debugging C plus plus
@subsubsection @value{GDBN} features for C@t{++}
* The Print Command with Objective-C::
@end menu
-@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
+@node Method Names in Commands
@subsubsection Method Names in Commands
The following commands have been extended to accept Objective-C method
@item info common @r{[}@var{common-name}@r{]}
This command prints the values contained in the Fortran @code{COMMON}
block whose name is @var{common-name}. With no argument, the names of
-all @code{COMMON} blocks visible at current program location are
+all @code{COMMON} blocks visible at the current program location are
printed.
@end table
@item
The overloading algorithm is much more limited (i.e., less selective)
-than that of real Ada. It makes only limited use of the context in which a subexpression
-appears to resolve its meaning, and it is much looser in its rules for allowing
-type matches. As a result, some function calls will be ambiguous, and the user
-will be asked to choose the proper resolution.
+than that of real Ada. It makes only limited use of the context in
+which a subexpression appears to resolve its meaning, and it is much
+looser in its rules for allowing type matches. As a result, some
+function calls will be ambiguous, and the user will be asked to choose
+the proper resolution.
@item
The @code{new} operator is not implemented.
@itemize @bullet
@item
-If the expression @var{E} is a variable residing in memory
-(typically a local variable or array element) and @var{N} is
-a positive integer, then @code{@var{E}@@@var{N}} displays the values of
-@var{E} and the @var{N}-1 adjacent variables following it in memory as an array.
-In Ada, this operator is generally not necessary, since its prime use
-is in displaying parts of an array, and slicing will usually do this in Ada.
-However, there are occasional uses when debugging programs
-in which certain debugging information has been optimized away.
+If the expression @var{E} is a variable residing in memory (typically
+a local variable or array element) and @var{N} is a positive integer,
+then @code{@var{E}@@@var{N}} displays the values of @var{E} and the
+@var{N}-1 adjacent variables following it in memory as an array. In
+Ada, this operator is generally not necessary, since its prime use is
+in displaying parts of an array, and slicing will usually do this in
+Ada. However, there are occasional uses when debugging programs in
+which certain debugging information has been optimized away.
@item
-@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
-in function or file @var{B}.'' When @var{B} is a file name, you must typically
-surround it in single quotes.
+@code{@var{B}::@var{var}} means ``the variable named @var{var} that
+appears in function or file @var{B}.'' When @var{B} is a file name,
+you must typically surround it in single quotes.
@item
The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
@end itemize
-In addition, @value{GDBN} provides a few other shortcuts and outright additions specific
-to Ada:
+In addition, @value{GDBN} provides a few other shortcuts and outright
+additions specific to Ada:
@itemize @bullet
@item
"One line.["0a"]Next line.["0a"]"
@end smallexample
@noindent
-contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each
-period.
+contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF})
+after each period.
@item
The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
@item
When printing arrays, @value{GDBN} uses positional notation when the
array has a lower bound of 1, and uses a modified named notation otherwise.
-For example, a one-dimensional array of three integers with a lower bound of 3 might print as
+For example, a one-dimensional array of three integers with a lower bound
+of 3 might print as
@smallexample
(3 => 10, 17, 1)
Occasionally it is necessary to change to a different file during a
@value{GDBN} session. Or you may run @value{GDBN} and forget to
specify a file you want to use. Or you are debugging a remote target
-via @code{gdbserver} (@pxref{Server, file}). In these situations the
-@value{GDBN} commands to specify new files are useful.
+via @code{gdbserver} (@pxref{Server, file, Using the gdbserver
+program}). In these situations the @value{GDBN} commands to specify
+new files are useful.
@table @code
@cindex executable file
generated for that environment; you may use either a @sc{gnu} compiler, or
other compilers that adhere to the local conventions.
Best results are usually obtained from @sc{gnu} compilers; for example,
-using @code{@value{GCC}} you can generate debugging information for
+using @code{@value{NGCC}} you can generate debugging information for
optimized code.
For most kinds of object files, with the exception of old SVR3 systems
@end table
+@subsection Monitor commands for @code{gdbserver}
+@cindex monitor commands, for @code{gdbserver}
+
+During a @value{GDBN} session using @code{gdbserver}, you can use the
+@code{monitor} command to send special requests to @code{gdbserver}.
+Here are the available commands; they are only of interest when
+debugging @value{GDBN} or @code{gdbserver}.
+
+@table @code
+@item monitor help
+List the available monitor commands.
+
+@item monitor set debug 0
+@itemx monitor set debug 1
+Disable or enable general debugging messages.
+
+@item monitor set remote-debug 0
+@itemx monitor set remote-debug 1
+Disable or enable specific debugging messages associated with the remote
+protocol (@pxref{Remote Protocol}).
+
+@end table
+
@node Remote configuration
@section Remote configuration
If you do not use the GNU C compiler, you may need other standard
library subroutines as well; this varies from one stub to another,
but in general the stubs are likely to use any of the common library
-subroutines which @code{@value{GCC}} generates as inline code.
+subroutines which @code{@value{NGCC}} generates as inline code.
@node Debug Session
start the program --- either by setting a breakpoint or letting the
program run once to completion. It is also possible to force
@value{GDBN} to load a particular DLL before starting the executable ---
-see the shared library information in @pxref{Files} or the
-@code{dll-symbols} command in @pxref{Cygwin Native}. Currently,
+see the shared library information in @ref{Files}, or the
+@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
explicitly loading symbols from a DLL with no debugging information will
cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
which may adversely affect symbol lookup performance.
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} (see
-@pxref{Symbols}). Here's an example:
+@code{info variables} commands or even @code{maint print msymbols}
+(@pxref{Symbols}). Here's an example:
@smallexample
(@value{GDBP}) info function CreateFileA
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
-* PowerPC: PowerPC
+* PowerPC:: PowerPC
* SH:: Renesas SH
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
-* ST2000:: Tandem ST2000
* Z8000:: Zilog Z8000
* AVR:: Atmel AVR
* CRIS:: CRIS
@end table
@cindex SDS protocol
-The following commands specify to the SDS protocol are supported
+The following commands specific to the SDS protocol are supported
by@value{GDBN}:
@table @code
@value{GDBN} locates
the file by searching the directories listed in the command search
path.
-If the file was compiled with debug information (option "-g"), source
+If the file was compiled with debug information (option @samp{-g}), source
files will be searched as well.
@value{GDBN} locates
the source files by searching the directories listed in the directory search
@end table
-@node ST2000
-@subsection Tandem ST2000
-
-@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
-STDBUG protocol.
-
-To connect your ST2000 to the host system, see the manufacturer's
-manual. Once the ST2000 is physically attached, you can run:
-
-@smallexample
-target st2000 @var{dev} @var{speed}
-@end smallexample
-
-@noindent
-to establish it as your debugging environment. @var{dev} is normally
-the name of a serial device, such as @file{/dev/ttya}, connected to the
-ST2000 via a serial line. You can instead specify @var{dev} as a TCP
-connection (for example, to a serial line attached via a terminal
-concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
-
-The @code{load} and @code{attach} commands are @emph{not} defined for
-this target; you must load your program into the ST2000 as you normally
-would for standalone operation. @value{GDBN} reads debugging information
-(such as symbols) from a separate, debugging version of the program
-available on your host computer.
-@c FIXME!! This is terribly vague; what little content is here is
-@c basically hearsay.
-
-@cindex ST2000 auxiliary commands
-These auxiliary @value{GDBN} commands are available to help you with the ST2000
-environment:
-
-@table @code
-@item st2000 @var{command}
-@kindex st2000 @var{cmd}
-@cindex STDBUG commands (ST2000)
-@cindex commands to STDBUG (ST2000)
-Send a @var{command} to the STDBUG monitor. See the manufacturer's
-manual for available commands.
-
-@item connect
-@cindex connect (to STDBUG)
-Connect the controlling terminal to the STDBUG command monitor. When
-you are done interacting with STDBUG, typing either of two character
-sequences gets you back to the @value{GDBN} command prompt:
-@kbd{@key{RET} ~ .} (Return, followed by tilde and period) or
-@kbd{@key{RET} ~ Ctrl-d} (Return, followed by tilde and control-D).
-@end table
-
@node Z8000
@subsection Zilog Z8000
@item show max-user-call-depth
@itemx set max-user-call-depth
The value of @code{max-user-call-depth} controls how many recursion
-levels are allowed in user-defined commands before GDB suspects an
+levels are allowed in user-defined commands before @value{GDBN} suspects an
infinite recursion and aborts the command.
@end table
@item
New fields may be added to the output of any MI command.
+@item
+The range of values for fields with specified values, e.g.,
+@code{in_scope} (@pxref{-var-update}) may be extended.
+
@c The format of field's content e.g type prefix, may change so parse it
@c at your own risk. Yes, in general?
@item "^connected"
@findex ^connected
-GDB has connected to a remote target.
+@value{GDBN} has connected to a remote target.
@item "^error" "," @var{c-string}
@findex ^error
@item "^exit"
@findex ^exit
-GDB has terminated.
+@value{GDBN} has terminated.
@end table
<- (gdb)
@end smallexample
-@subheading Quitting GDB
+@subheading Quitting @value{GDBN}
-Quitting GDB just prints the result class @samp{^exit}.
+Quitting @value{GDBN} just prints the result class @samp{^exit}.
@smallexample
-> (gdb)
(gdb)
-exec-continue
^running
-^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
+(gdb)
+*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
frame=@{func="main",args=[],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="5"@}
(gdb)
-exec-continue
^running
-^done,reason="watchpoint-trigger",
+(gdb)
+*stopped,reason="watchpoint-trigger",
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
(gdb)
-exec-continue
^running
-^done,reason="watchpoint-scope",wpnum="5",
+(gdb)
+*stopped,reason="watchpoint-scope",wpnum="5",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
(gdb)
-exec-continue
^running
-^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
+(gdb)
+*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
@section @sc{gdb/mi} Program Execution
These are the asynchronous commands which generate the out-of-band
-record @samp{*stopped}. Currently GDB only really executes
+record @samp{*stopped}. Currently @value{GDBN} only really executes
asynchronously with remote targets and this interaction is mimicked in
other cases.
Reevaluate the expressions corresponding to the variable object
@var{name} and all its direct and indirect children, and return the
-list of variable objects whose values have changed. Here,
-``changed'' means that the result of @code{-var-evaluate-expression} before
-and after the @code{-var-update} is different. If @samp{*} is used
-as the variable object names, all existing variable objects are
-updated. The option @var{print-values} determines whether both names
-and values, or just names are printed. The possible values of
-this options are the same as for @code{-var-list-children}
-(@pxref{-var-list-children}). It is recommended to use the
-@samp{--all-values} option, to reduce the number of MI commands needed
-on each program stop.
+list of variable objects whose values have changed; @var{name} must
+be a root variable object. Here, ``changed'' means that the result of
+@code{-var-evaluate-expression} before and after the
+@code{-var-update} is different. If @samp{*} is used as the variable
+object names, all existing variable objects are updated. The option
+@var{print-values} determines whether both names and values, or just
+names are printed. The possible values of this options are the same
+as for @code{-var-list-children} (@pxref{-var-list-children}). It is
+recommended to use the @samp{--all-values} option, to reduce the
+number of MI commands needed on each program stop.
@subsubheading Example
(gdb)
@end smallexample
+@anchor{-var-update}
+The field in_scope may take three values:
+
+@table @code
+@item "true"
+The variable object's current value is valid.
+
+@item "false"
+The variable object does not currently hold a valid value but it may
+hold one in the future if its associated expression comes back into
+scope.
+
+@item "invalid"
+The variable object no longer holds a valid value.
+This can occur when the executable file being debugged has changed,
+either through recompilation or by using the @value{GDBN} @code{file}
+command. The front end should normally choose to delete these variable
+objects.
+@end table
+
+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}.
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Data Manipulation
@section @sc{gdb/mi} Data Manipulation
List the source files for the current executable.
-It will always output the filename, but only when GDB can find the absolute
-file name of a source file, will it output the fullname.
+It will always output the filename, but only when @value{GDBN} can find
+the absolute file name of a source file, will it output the fullname.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
-@example
+@smallexample
-target-disconnect
-@end example
+@end smallexample
Disconnect from the remote target. There's no output and the target is
generally not resumed.
(gdb)
@end smallexample
+@subheading The @code{-enable-timings} Command
+@findex -enable-timings
+
+@subheading Synopsis
+
+@smallexample
+-enable-timings [yes | no]
+@end smallexample
+
+Toggle the printing of the wallclock, user and system times for an MI
+command as a field in its output. This command is to help frontend
+developers optimize the performance of their code. No argument is
+equivalent to @samp{yes}.
+
+@subheading @value{GDBN} Command
+
+No equivalent.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-enable-timings
+^done
+(gdb)
+-break-insert main
+^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x080484ed",func="main",file="myprog.c",
+fullname="/home/nickrob/myprog.c",line="73",times="0"@},
+time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
+(gdb)
+-enable-timings no
+^done
+(gdb)
+-exec-run
+^running
+(gdb)
+*stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
+@{name="argv",value="0xbfb60364"@}],file="myprog.c",
+fullname="/home/nickrob/myprog.c",line="73"@}
+(gdb)
+@end smallexample
+
@node Annotations
@chapter @value{GDBN} Annotations
@item
What compiler (and its version) was used to compile the program you are
debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
-C Compiler''. For GCC, you can say @code{gcc --version} to get this
-information; for other compilers, see the documentation for those
-compilers.
+C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version}
+to get this information; for other compilers, see the documentation for
+those compilers.
@item
The command arguments you gave the compiler to compile your example and
@heading Tools/packages optional for building @value{GDBN}
@table @asis
@item Expat
+@anchor{Expat}
@value{GDBN} can use the Expat XML parsing library. This library may be
included with your operating system distribution; if it is not, you
can get the latest version from @url{http://expat.sourceforge.net}.
standard locations; if it is installed in an unusual path, you can
use the @option{--with-libexpat-prefix} option to specify its location.
-Expat is used currently only used to implement some remote-specific
-features.
+Expat is used for remote protocol memory maps (@pxref{Memory map format})
+and for target descriptions (@pxref{Target Descriptions}).
@end table
savings, and various measures of the hash table size and chain
lengths.
+@kindex maint print target-stack
+@cindex target stack description
+@item maint print target-stack
+A @dfn{target} is an interface between the debugger and a particular
+kind of file or process. Targets can be stacked in @dfn{strata},
+so that more than one target can potentially respond to a request.
+In particular, memory accesses will walk down the stack of targets
+until they find a target that is interested in handling that particular
+address.
+
+This command prints a short description of each layer that was pushed on
+the @dfn{target stack}, starting from the top layer down to the bottom one.
+
@kindex maint print type
@cindex type chain of a data type
@item maint print type @var{expr}
@item maint show-debug-regs
Control whether to show variables that mirror the x86 hardware debug
registers. Use @code{ON} to enable, @code{OFF} to disable. If
-enabled, the debug registers values are shown when GDB inserts or
+enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
triggers a hardware-assisted breakpoint or watchpoint.
separate its components. For example, a template like @samp{foo
@var{bar} @var{baz}} describes a packet beginning with the three ASCII
bytes @samp{foo}, followed by a @var{bar}, followed directly by a
-@var{baz}. GDB does not transmit a space character between the
+@var{baz}. @value{GDBN} does not transmit a space character between the
@samp{foo} and the @var{bar}, or between the @var{bar} and the
@var{baz}.
(@value{GDBP}) continue
<- target requests 'system call X'
target is stopped, @value{GDBN} executes system call
- -> GDB returns result
- ... target continues, GDB returns to wait for the target
+ -> @value{GDBN} returns result
+ ... target continues, @value{GDBN} returns to wait for the target
<- target hits breakpoint and sends a Txx packet
@end smallexample
processor variants it has never seen before --- to the extent that the
descriptions are accurate, and that @value{GDBN} understands them.
+@value{GDBN} must be compiled with Expat support to support XML target
+descriptions. @xref{Expat}.
+
@menu
* Retrieving Descriptions:: How descriptions are fetched from a target.
* Target Description Format:: The contents of a target description.
+* Predefined Target Types:: Standard types available for target
+ descriptions.
+* Standard Target Features:: Features @value{GDBN} knows about.
@end menu
@node Retrieving Descriptions
However, to help people unfamiliar with XML write descriptions for
their targets, we also describe the grammar here.
-At the moment, target descriptions can only provide minimal information
-about the architecture of the remote target. @value{GDBN} can use this
-information to autoconfigure, or to warn you if you connect to an
-unsupported target.
+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
+target, or to warn you if you connect to an unsupported target.
Here is a simple target description:
-@example
+@smallexample
<target>
<architecture>i386:x86-64</architecture>
</target>
-@end example
+@end smallexample
@noindent
This minimal description only says that the target uses
the x86-64 architecture.
-A target description has the overall form:
+A target description has the following overall form, with [ ] marking
+optional elements and @dots{} marking repeatable elements. The elements
+are explained further below.
-@example
+@smallexample
<?xml version="1.0"?>
<!DOCTYPE target SYSTEM "gdb-target.dtd">
<target>
- <architecture>@var{arch name}</architecture>
+ @r{[}@var{architecture}@r{]}
+ @r{[}@var{feature}@dots{}@r{]}
</target>
-@end example
+@end smallexample
@noindent
The description is generally insensitive to whitespace and line
(@value{GDBN} does not require them), but specifying them may be
useful for XML validation tools.
-The content of the @samp{<architecture>} element is an architecture
-name, from the same selection accepted by @code{set architecture}
-(@pxref{Targets, ,Specifying a Debugging Target}).
+@subsection Inclusion
+@cindex target descriptions, inclusion
+@cindex XInclude
+@ifnotinfo
+@cindex <xi:include>
+@end ifnotinfo
+
+It can sometimes be valuable to split a target description up into
+several different annexes, either for organizational purposes, or to
+share files between different possible target descriptions. You can
+divide a description into multiple files by replacing any element of
+the target description with an inclusion directive of the form:
+
+@smallexample
+<xi:include href="@var{document}"/>
+@end smallexample
+
+@noindent
+When @value{GDBN} encounters an element of this form, it will retrieve
+the named XML @var{document}, and replace the inclusion directive with
+the contents of that document. If the current description was read
+using @samp{qXfer}, then so will be the included document;
+@var{document} will be interpreted as the name of an annex. If the
+current description was read from a file, @value{GDBN} will look for
+@var{document} as a file in the same directory where it found the
+original description.
+
+@subsection Architecture
+@cindex <architecture>
+
+An @samp{<architecture>} element has this form:
+
+@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}).
+
+@subsection Features
+@cindex <feature>
+
+Each @samp{<feature>} describes some logical portion of the target
+system. Features are currently used to describe available CPU
+registers and the types of their contents. A @samp{<feature>} element
+has this form:
+
+@smallexample
+<feature name="@var{name}">
+ @r{[}@var{type}@dots{}@r{]}
+ @var{reg}@dots{}
+</feature>
+@end smallexample
+
+@noindent
+Each feature's name should be unique within the description. The name
+of a feature does not matter unless @value{GDBN} has some special
+knowledge of the contents of that feature; if it does, the feature
+should have its standard name. @xref{Standard Target Features}.
+
+@subsection Types
+
+Any register's value is a collection of bits which @value{GDBN} must
+interpret. The default interpretation is a two's complement integer,
+but other types can be requested by name in the register description.
+Some predefined types are provided by @value{GDBN} (@pxref{Predefined
+Target Types}), and the description can define additional composite types.
+
+Each type element must have an @samp{id} attribute, which gives
+a unique (within the containing @samp{<feature>}) name to the type.
+Types must be defined before they are used.
+
+@cindex <vector>
+Some targets offer vector registers, which can be treated as arrays
+of scalar elements. These types are written as @samp{<vector>} elements,
+specifying the array element type, @var{type}, and the number of elements,
+@var{count}:
+
+@smallexample
+<vector id="@var{id}" type="@var{type}" count="@var{count}"/>
+@end smallexample
+
+@cindex <union>
+If a register's value is usefully viewed in multiple ways, define it
+with a union type containing the useful representations. The
+@samp{<union>} element contains one or more @samp{<field>} elements,
+each of which has a @var{name} and a @var{type}:
+
+@smallexample
+<union id="@var{id}">
+ <field name="@var{name}" type="@var{type}"/>
+ @dots{}
+</union>
+@end smallexample
+
+@subsection Registers
+@cindex <reg>
+
+Each register is represented as an element with this form:
+
+@smallexample
+<reg name="@var{name}"
+ bitsize="@var{size}"
+ @r{[}regnum="@var{num}"@r{]}
+ @r{[}save-restore="@var{save-restore}"@r{]}
+ @r{[}type="@var{type}"@r{]}
+ @r{[}group="@var{group}"@r{]}/>
+@end smallexample
+
+@noindent
+The components are as follows:
+
+@table @var
+@item name
+The register's name; it must be unique within the target description.
+
+@item bitsize
+The register's size, in bits.
+
+@item regnum
+The register's number. If omitted, a register's number is one greater
+than that of the previous register (either in the current feature or in
+a preceeding feature); the first register in the target description
+defaults to zero. This register number is used to read or write
+the register; e.g.@: it is used in the remote @code{p} and @code{P}
+packets, and registers appear in the @code{g} and @code{G} packets
+in order of increasing register number.
+
+@item save-restore
+Whether the register should be preserved across inferior function
+calls; this must be either @code{yes} or @code{no}. The default is
+@code{yes}, which is appropriate for most registers except for
+some system control registers; this is not related to the target's
+ABI.
+
+@item type
+The type of the register. @var{type} may be a predefined type, a type
+defined in the current feature, or one of the special types @code{int}
+and @code{float}. @code{int} is an integer type of the correct size
+for @var{bitsize}, and @code{float} is a floating point type (in the
+architecture's normal floating point format) of the correct size for
+@var{bitsize}. The default is @code{int}.
+
+@item group
+The register group to which this register belongs. @var{group} must
+be either @code{general}, @code{float}, or @code{vector}. If no
+@var{group} is specified, @value{GDBN} will not display the register
+in @code{info registers}.
+
+@end table
+
+@node Predefined Target Types
+@section Predefined Target Types
+@cindex target descriptions, predefined types
+
+Type definitions in the self-description can build up composite types
+from basic building blocks, but can not define fundamental types. Instead,
+standard identifiers are provided by @value{GDBN} for the fundamental
+types. The currently supported types are:
+
+@table @code
+
+@item int8
+@itemx int16
+@itemx int32
+@itemx int64
+Signed integer types holding the specified number of bits.
+
+@item uint8
+@itemx uint16
+@itemx uint32
+@itemx uint64
+Unsigned integer types holding the specified number of bits.
+
+@item code_ptr
+@itemx data_ptr
+Pointers to unspecified code and data. The program counter and
+any dedicated return address register may be marked as code
+pointers; printing a code pointer converts it into a symbolic
+address. The stack pointer and any dedicated address registers
+may be marked as data pointers.
+
+@item arm_fpa_ext
+The 12-byte extended precision format used by ARM FPA registers.
+
+@end table
+
+@node Standard Target Features
+@section Standard Target Features
+@cindex target descriptions, standard features
+
+A target description must contain either no registers or all the
+target's registers. If the description contains no registers, then
+@value{GDBN} will assume a default register layout, selected based on
+the architecture. If the description contains any registers, the
+default layout will not be used; the standard registers must be
+described in the target description, in such a way that @value{GDBN}
+can recognize them.
+
+This is accomplished by giving specific names to feature elements
+which contain standard registers. @value{GDBN} will look for features
+with those names and verify that they contain the expected registers;
+if any known feature is missing required registers, or if any required
+feature is missing, @value{GDBN} will reject the target
+description. You can add additional registers to any of the
+standard features --- @value{GDBN} will display them just as if
+they were added to an unrecognized feature.
+
+This section lists the known features and their expected contents.
+Sample XML documents for these features are included in the
+@value{GDBN} source tree, in the directory @file{gdb/features}.
+
+Names recognized by @value{GDBN} should include the name of the
+company or organization which selected the name, and the overall
+architecture to which the feature applies; so e.g.@: the feature
+containing ARM core registers is named @samp{org.gnu.gdb.arm.core}.
+
+The names of registers are not case sensitive for the purpose
+of recognizing standard features, but @value{GDBN} will only display
+registers using the capitalization used in the description.
+
+@subsection ARM Features
+@cindex target descriptions, ARM features
+
+The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets.
+It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
+@samp{lr}, @samp{pc}, and @samp{cpsr}.
+
+The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it
+should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
+
+The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present,
+it should contain at least registers @samp{wR0} through @samp{wR15} and
+@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
+@samp{wCSSF}, and @samp{wCASF} registers are optional.
@include gpl.texi
projects / deliverable / binutils-gdb.git / blobdiff