* 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
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
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
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
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
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
@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
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
@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
@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?
(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",
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
@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
@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
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