executing the command.
@end table
-If you exit @value{GDBN} or use the @code{run} command while you have an
-attached process, you kill that process. By default, @value{GDBN} asks
-for confirmation if you try to do either of these things; you can
-control whether or not you need to confirm by using the @code{set
-confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
+If you exit @value{GDBN} while you have an attached process, you detach
+that process. If you use the @code{run} command, you kill that process.
+By default, @value{GDBN} asks for confirmation if you try to do either of these
+things; you can control whether or not you need to confirm by using the
+@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
Messages}).
@node Kill Process
Even though the unit size @var{u} is ignored for the formats @samp{s}
and @samp{i}, you might still want to use a count @var{n}; for example,
@samp{3i} specifies that you want to see three machine instructions,
-including any operands. The command @code{disassemble} gives an
-alternative way of inspecting machine instructions; see @ref{Machine
-Code,,Source and Machine Code}.
+including any operands. For convenience, especially when used with
+the @code{display} command, the @samp{i} format also prints branch delay
+slot instructions, if any, beyond the count specified, which immediately
+follow the last instruction that is within the count. The command
+@code{disassemble} gives an alternative way of inspecting machine
+instructions; see @ref{Machine Code,,Source and Machine Code}.
All the defaults for the arguments to @code{x} are designed to make it
easy to continue scanning memory with minimal specifications each time
Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
interrupt the remote program.
+@item set remoteflow on
+@itemx set remoteflow off
+@kindex set remoteflow
+Enable or disable hardware flow control (@code{RTS}/@code{CTS})
+on the serial port used to communicate to the remote target.
+
+@item show remoteflow
+@kindex show remoteflow
+Show the current setting of hardware flow control.
+
@item set remotelogbase @var{base}
Set the base (a.k.a.@: radix) of logging serial protocol
communications to @var{base}. Supported values of @var{base} are:
in @value{GDBN}. You may want to report the problem to the
@value{GDBN} developers.
-The available settings are:
+For each packet @var{name}, the command to enable or disable the
+packet is @code{set remote @var{name}-packet}. The available settings
+are:
-@multitable @columnfractions 0.3 0.2 0.35
+@multitable @columnfractions 0.28 0.32 0.25
@item Command Name
@tab Remote Packet
@tab Related Features
-@item @code{fetch-register-packet}
+@item @code{fetch-register}
@tab @code{p}
@tab @code{info registers}
-@item @code{set-register-packet}
+@item @code{set-register}
@tab @code{P}
@tab @code{set}
-@item @code{binary-download-packet}
+@item @code{binary-download}
@tab @code{X}
@tab @code{load}, @code{set}
-@item @code{read-aux-vector-packet}
+@item @code{read-aux-vector}
@tab @code{qXfer:auxv:read}
@tab @code{info auxv}
-@item @code{symbol-lookup-packet}
+@item @code{symbol-lookup}
@tab @code{qSymbol}
@tab Detecting multiple threads
-@item @code{verbose-resume-packet}
+@item @code{verbose-resume}
@tab @code{vCont}
@tab Stepping or resuming multiple threads
-@item @code{software-breakpoint-packet}
+@item @code{software-breakpoint}
@tab @code{Z0}
@tab @code{break}
-@item @code{hardware-breakpoint-packet}
+@item @code{hardware-breakpoint}
@tab @code{Z1}
@tab @code{hbreak}
-@item @code{write-watchpoint-packet}
+@item @code{write-watchpoint}
@tab @code{Z2}
@tab @code{watch}
-@item @code{read-watchpoint-packet}
+@item @code{read-watchpoint}
@tab @code{Z3}
@tab @code{rwatch}
-@item @code{access-watchpoint-packet}
+@item @code{access-watchpoint}
@tab @code{Z4}
@tab @code{awatch}
-@item @code{get-thread-local-storage-address-packet}
+@item @code{target-features}
+@tab @code{qXfer:features:read}
+@tab @code{set architecture}
+
+@item @code{library-info}
+@tab @code{qXfer:libraries:read}
+@tab @code{info sharedlibrary}
+
+@item @code{memory-map}
+@tab @code{qXfer:memory-map:read}
+@tab @code{info mem}
+
+@item @code{read-spu-object}
+@tab @code{qXfer:spu:read}
+@tab @code{info spu}
+
+@item @code{write-spu-object}
+@tab @code{qXfer:spu:write}
+@tab @code{info spu}
+
+@item @code{get-thread-local-@*storage-address}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
@tab @code{qSupported}
@tab Remote communications parameters
-@item @code{pass-signals-packet}
+@item @code{pass-signals}
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
+* SPU:: Cell Broadband Engine SPU architecture
@end menu
@node i386
@end table
+@node SPU
+@subsection Cell Broadband Engine SPU architecture
+@cindex Cell Broadband Engine
+@cindex SPU
+
+When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
+it provides the following special commands:
+
+@table @code
+@item info spu event
+@kindex info spu
+Display SPU event facility status. Shows current event mask
+and pending event status.
+
+@item info spu signal
+Display SPU signal notification facility status. Shows pending
+signal-control word and signal notification mode of both signal
+notification channels.
+
+@item info spu mailbox
+Display SPU mailbox facility status. Shows all pending entries,
+in order of processing, in each of the SPU Write Outbound,
+SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
+
+@item info spu dma
+Display MFC DMA status. Shows all pending commands in the MFC
+DMA queue. For each entry, opcode, tag, class IDs, effective
+and local store addresses and transfer size are shown.
+
+@item info spu proxydma
+Display MFC Proxy-DMA status. Shows all pending commands in the MFC
+Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
+and local store addresses and transfer size are shown.
+
+@end table
+
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
Interactively}, 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 }. This
+the state which is seen by users, prefix it with @samp{server }
+(@pxref{Server Prefix}). This
means that this command will not affect the command history, nor will it
affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
pressed on a line by itself.
created Emacs buffer.
@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
-Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
+Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two
things:
@itemize @bullet
@item
-All ``terminal'' input and output goes through the Emacs buffer.
-@end itemize
+All ``terminal'' input and output goes through an Emacs buffer, called
+the GUD buffer.
This applies both to @value{GDBN} commands and their output, and to the input
and output done by the program you are debugging.
way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
stop.
-@itemize @bullet
@item
@value{GDBN} displays source code through Emacs.
-@end itemize
Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
source file for that frame and puts an arrow (@samp{=>}) at the
Explicit @value{GDBN} @code{list} or search commands still produce output as
usual, but you probably have no reason to use them from Emacs.
+@end itemize
+
+We call this @dfn{text command mode}. Emacs 22.1, and later, also uses
+a graphical mode, enabled by default, which provides further buffers
+that can control the execution and describe the state of your program.
+@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}.
If you specify an absolute file name when prompted for the @kbd{M-x
gdb} argument, then Emacs sets your current working directory to where
buffer does not display the current source and line of execution.
The initial working directory of @value{GDBN} is printed on the top
-line of the @value{GDBN} I/O buffer and this serves as a default for
-the commands that specify files for @value{GDBN} to operate
-on. @xref{Files, ,Commands to Specify Files}.
+line of the GUD buffer and this serves as a default for the commands
+that specify files for @value{GDBN} to operate on. @xref{Files,
+,Commands to Specify Files}.
By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
need to call @value{GDBN} by a different name (for example, if you
customize the Emacs variable @code{gud-gdb-command-name} to run the
one you want.
-In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
+In the GUD buffer, you can use these special Emacs commands in
addition to the standard Shell mode commands:
@table @kbd
@item C-h m
-Describe the features of Emacs' @value{GDBN} Mode.
+Describe the features of Emacs' GUD Mode.
@item C-c C-s
Execute to another source line, like the @value{GDBN} @code{step} command; also
In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
tells @value{GDBN} to set a breakpoint on the source line point is on.
-If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
-shows a backtrace when the @value{GDBN} I/O buffer is current. Move
-point to any frame in the stack and type @key{RET} to make it become the
-current frame and display the associated source in the source buffer.
-Alternatively, click @kbd{Mouse-2} to make the selected frame become the
-current one.
+In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a
+separate frame which shows a backtrace when the GUD buffer is current.
+Move point to any frame in the stack and type @key{RET} to make it
+become the current frame and display the associated source in the
+source buffer. Alternatively, click @kbd{Mouse-2} to make the
+selected frame become the current one. In graphical mode, the
+speedbar displays watch expressions.
If you accidentally delete the source-display buffer, an easy way to get
it back is to type the command @code{f} in the @value{GDBN} buffer, to
delete lines from the text, the line numbers that @value{GDBN} knows cease
to correspond properly with the code.
-The description given here is for GNU Emacs version 21.3 and a more
-detailed description of its interaction with @value{GDBN} is given in
-the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}).
+A more detailed description of Emacs' interaction with @value{GDBN} is
+given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
+Emacs Manual}).
@c The following dropped because Epoch is nonstandard. Reactivate
@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
@item
The range of values for fields with specified values, e.g.,
-@code{in_scope} (@pxref{-var-update-fields}) may be extended.
+@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?
@subheading The @code{-var-update} Command
@findex -var-update
-@anchor{-var-update}
@subsubheading Synopsis
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
+object names, all existing variable objects are updated, except
+for frozen ones (@pxref{-var-set-frozen}). 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
(gdb)
@end smallexample
-@anchor{-var-update-fields}
+@anchor{-var-update}
The field in_scope may take three values:
@table @code
@subheading The @code{-var-set-frozen} Command
@findex -var-set-frozen
+@anchor{-var-set-frozen}
@subsubheading Synopsis
@smallexample
- -var-set-frozen @var{name} @samp{flag}
+ -var-set-frozen @var{name} @var{flag}
@end smallexample
-Set the frozeness flag on the variable object @var{name}. The
+Set the frozenness flag on the variable object @var{name}. The
@var{flag} parameter should be either @samp{1} to make the variable
-frozen or @samp{0} to make it unfozen. If a variable object is
+frozen or @samp{0} to make it unfrozen. If a variable object is
frozen, then neither itself, nor any of its children, are
-implicitly updated by @code{-var-update} (@pxref{-var-update}) of
+implicitly updated by @code{-var-update} of
a parent variable or by @code{-var-update *}. Only
@code{-var-update} of the variable itself will update its value and
values of its children. After a variable object is unfrozen, it is
@menu
* Annotations Overview:: What annotations are; the general syntax.
+* Server Prefix:: Issuing a command without affecting user state.
* Prompting:: Annotations marking @value{GDBN}'s need for input.
* Errors:: Annotations for error messages.
* Invalidation:: Some annotations describe things now invalid.
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.
+@node Server Prefix
+@section The Server Prefix
+@cindex server prefix
+
+If you prefix a command with @samp{server } then it will not affect
+the command history, nor will it affect @value{GDBN}'s notion of which
+command to repeat if @key{RET} is pressed on a line by itself. This
+means that commands can be run behind a user's back by a front-end in
+a transparent manner.
+
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
@node Prompting
@section Annotation for @value{GDBN} Input
* Interrupts::
* Examples::
* File-I/O Remote Protocol Extension::
+* Library List Format::
* Memory Map Format::
@end menu
recognizes a packet meant for @value{GDBN}.
In the examples below, @samp{->} and @samp{<-} are used to indicate
-transmitted and received data respectfully.
+transmitted and received data, respectively.
@cindex protocol, @value{GDBN} remote serial
@cindex serial protocol, @value{GDBN} remote
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} packet are
-determined by the @value{GDBN} internal macros
-@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
+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.
@item E @var{NN}
for an error.
and other information directly in the stop reply packet, reducing
round-trip latency. Single-step and breakpoint traps are reported
this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
-@enumerate
+
+@itemize @bullet
@item
If @var{n} is a hexadecimal number, it is a register number, and the
corresponding @var{r} gives that register's value. @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
+
@item
If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in
hex.
+
@item
-If @var{n} is @samp{watch}, @samp{rwatch}, or @samp{awatch}, then the
-packet indicates a watchpoint hit, and @var{r} is the data address, in
-hex.
+If @var{n} is a recognized @dfn{stop reason}, it describes a more
+specific event that stopped the target. The currently defined stop
+reasons are listed below. @var{aa} should be @samp{05}, the trap
+signal. At most one stop reason should be present.
+
@item
Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
and go on to the next; this allows us to extend the protocol in the
future.
-@end enumerate
+@end itemize
+
+The currently defined stop reasons are:
+
+@table @samp
+@item watch
+@itemx rwatch
+@itemx awatch
+The packet indicates a watchpoint hit, and @var{r} is the data address, in
+hex.
+
+@cindex shared library events, remote reply
+@item library
+The packet indicates that the loaded libraries have changed.
+@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
+list of loaded libraries. @var{r} is ignored.
+@end table
@item W @var{AA}
The process exited, and @var{AA} is the exit status. This is only
@item qOffsets
@cindex section offsets, remote request
@cindex @samp{qOffsets} packet
-Get section offsets that the target used when re-locating the downloaded
-image. @emph{Note: while a @code{Bss} offset is included in the
-response, @value{GDBN} ignores this and instead applies the @code{Data}
-offset to the @code{Bss} section.}
+Get section offsets that the target used when relocating the downloaded
+image.
Reply:
@table @samp
-@item Text=@var{xxx};Data=@var{yyy};Bss=@var{zzz}
+@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]}
+Relocate the @code{Text} section by @var{xxx} from its original address.
+Relocate the @code{Data} section by @var{yyy} from its original address.
+If the object file format provides segment information (e.g.@: @sc{elf}
+@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire
+segments by the supplied offsets.
+
+@emph{Note: while a @code{Bss} offset may be included in the response,
+@value{GDBN} ignores this and instead applies the @code{Data} offset
+to the @code{Bss} section.}
+
+@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]}
+Relocate the first segment of the object file, which conventionally
+contains program code, to a starting address of @var{xxx}. If
+@samp{DataSeg} is specified, relocate the second segment, which
+conventionally contains modifiable data, to a starting address of
+@var{yyy}. @value{GDBN} will report an error if the object file
+does not contain segment information, or does not contain at least
+as many segments as mentioned in the reply. Extra segments are
+kept at fixed offsets relative to the last relocated segment.
@end table
@item qP @var{mode} @var{threadid}
These are the currently defined stub features and their properties:
-@multitable @columnfractions 0.25 0.2 0.2 0.2
+@multitable @columnfractions 0.35 0.2 0.12 0.2
@c NOTE: The first row should be @headitem, but we do not yet require
@c a new enough version of Texinfo (4.7) to use @headitem.
@item Feature Name
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:libraries:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:memory-map:read}
@tab No
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:spu:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:spu:write}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
+@item qXfer:libraries:read
+The remote stub understands the @samp{qXfer:libraries:read} packet
+(@pxref{qXfer library list read}).
+
@item qXfer:memory-map:read
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
+@item qXfer:spu:read
+The remote stub understands the @samp{qXfer:spu:read} packet
+(@pxref{qXfer spu read}).
+
+@item qXfer:spu:write
+The remote stub understands the @samp{qXfer:spu:write} packet
+(@pxref{qXfer spu write}).
+
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
Read uninterpreted bytes from the target's special data area
identified by the keyword @var{object}. Request @var{length} bytes
starting at @var{offset} bytes into the data. The content and
-encoding of @var{annex} is specific to the object; it can supply
+encoding of @var{annex} is specific to @var{object}; it can supply
additional details about what data to access.
Here are the specific requests of this form defined so far. All
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer library list read}
+Access the target's list of loaded libraries. @xref{Library List Format}.
+The annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+Targets which maintain a list of libraries in the program's memory do
+not need to implement this packet; it is designed for platforms where
+the operating system manages the list of loaded libraries.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:memory-map:read::@var{offset},@var{length}
@anchor{qXfer memory map read}
Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
annex part of the generic @samp{qXfer} packet must be empty
(@pxref{qXfer read}).
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
+@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer spu read}
+Read contents of an @code{spufs} file on the target system. The
+annex specifies which file to read; it must be of the form
+@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
+in the target process, and @var{name} identifes the @code{spufs} file
+in that context to be accessed.
+
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
@cindex write data into object, remote request
Write uninterpreted bytes into the target's special data area
identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @samp{@var{data}@dots{}} is the binary-encoded data
+into the data. @var{data}@dots{} is the binary-encoded data
(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
-is specific to the object; it can supply additional details about what data
+is specific to @var{object}; it can supply additional details about what data
to access.
-No requests of this form are presently in use. This specification
-serves as a placeholder to document the common format that new
-specific request specifications ought to use.
+Here are the specific requests of this form defined so far. All
+@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
+formats, listed below.
+
+@table @samp
+@item qXfer:@var{spu}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@anchor{qXfer spu write}
+Write @var{data} to an @code{spufs} file on the target system. The
+annex specifies which file to write; it must be of the form
+@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
+in the target process, and @var{name} identifes the @code{spufs} file
+in that context to be accessed.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
Reply:
@table @samp
<- @code{T02}
@end smallexample
+@node Library List Format
+@section Library List Format
+@cindex library list format, remote protocol
+
+On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the
+same process as your application to manage libraries. In this case,
+@value{GDBN} can use the loader's symbol table and normal memory
+operations to maintain a list of shared libraries. On other
+platforms, the operating system manages loaded libraries.
+@value{GDBN} can not retrieve the list of currently loaded libraries
+through memory operations, so it uses the @samp{qXfer:libraries:read}
+packet (@pxref{qXfer library list read}) instead. The remote stub
+queries the target's operating system and reports which libraries
+are loaded.
+
+The @samp{qXfer:libraries:read} packet returns an XML document which
+lists loaded libraries and their offsets. Each library has an
+associated name and one or more segment base addresses, which report
+where the library was loaded in memory. The segment bases are start
+addresses, not relocation offsets; they do not depend on the library's
+link-time base addresses.
+
+A simple memory map, with one loaded library relocated by a single
+offset, looks like this:
+
+@smallexample
+<library-list>
+ <library name="/lib/libc.so.6">
+ <segment address="0x10000000"/>
+ </library>
+</library-list>
+@end smallexample
+
+The format of a library list is described by this DTD:
+
+@smallexample
+<!-- library-list: Root element with versioning -->
+<!ELEMENT library-list (library)*>
+<!ATTLIST library-list version CDATA #FIXED "1.0">
+<!ELEMENT library (segment)*>
+<!ATTLIST library name CDATA #REQUIRED>
+<!ELEMENT segment EMPTY>
+<!ATTLIST segment address CDATA #REQUIRED>
+@end smallexample
+
@node Memory Map Format
@section Memory Map Format
@cindex memory map format
Here is a simple target description:
@smallexample
-<target>
+<target version="1.0">
<architecture>i386:x86-64</architecture>
</target>
@end smallexample
@smallexample
<?xml version="1.0"?>
<!DOCTYPE target SYSTEM "gdb-target.dtd">
-<target>
+<target version="1.0">
@r{[}@var{architecture}@r{]}
@r{[}@var{feature}@dots{}@r{]}
</target>
breaks, under the usual common-sense rules. The XML version
declaration and document type declaration can generally be omitted
(@value{GDBN} does not require them), but specifying them may be
-useful for XML validation tools.
+useful for XML validation tools. The @samp{version} attribute for
+@samp{<target>} may also be omitted, but we recommend
+including it; if future versions of @value{GDBN} use an incompatible
+revision of @file{gdb-target.dtd}, they will detect and report
+the version mismatch.
@subsection Inclusion
@cindex target descriptions, inclusion
of recognizing standard features, but @value{GDBN} will only display
registers using the capitalization used in the description.
+@menu
+* ARM Features::
+* M68K Features::
+@end menu
+
+
+@node ARM Features
@subsection ARM Features
@cindex target descriptions, ARM features
@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
@samp{wCSSF}, and @samp{wCASF} registers are optional.
+@subsection MIPS Features
+@cindex target descriptions, MIPS features
+
+The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets.
+It should contain registers @samp{r0} through @samp{r31}, @samp{lo},
+@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending
+on the target.
+
+The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should
+contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause}
+registers. They may be 32-bit or 64-bit depending on the target.
+
+The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though
+it may be optional in a future version of @value{GDBN}. It should
+contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
+@samp{fir}. They may be 32-bit or 64-bit depending on the target.
+
+The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
+contain a single register, @samp{restart}, which is used by the
+Linux kernel to control restartable syscalls.
+
+@node M68K Features
+@subsection M68K Features
+@cindex target descriptions, M68K features
+
+@table @code
+@item @samp{org.gnu.gdb.m68k.core}
+@itemx @samp{org.gnu.gdb.coldfire.core}
+@itemx @samp{org.gnu.gdb.fido.core}
+One of those features must be always present.
+The feature that is present determines which flavor of m86k is
+used. The feature that is present should contain registers
+@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp},
+@samp{sp}, @samp{ps} and @samp{pc}.
+
+@item @samp{org.gnu.gdb.coldfire.fp}
+This feature is optional. If present, it should contain registers
+@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and
+@samp{fpiaddr}.
+@end table
+
@include gpl.texi
@raisesections