+@node Target Descriptions
+@appendix Target Descriptions
+@cindex target descriptions
+
+@strong{Warning:} target descriptions are still under active development,
+and the contents and format may change between @value{GDBN} releases.
+The format is expected to stabilize in the future.
+
+One of the challenges of using @value{GDBN} to debug embedded systems
+is that there are so many minor variants of each processor
+architecture in use. It is common practice for vendors to start with
+a standard processor core --- ARM, PowerPC, or MIPS, for example ---
+and then make changes to adapt it to a particular market niche. Some
+architectures have hundreds of variants, available from dozens of
+vendors. This leads to a number of problems:
+
+@itemize @bullet
+@item
+With so many different customized processors, it is difficult for
+the @value{GDBN} maintainers to keep up with the changes.
+@item
+Since individual variants may have short lifetimes or limited
+audiences, it may not be worthwhile to carry information about every
+variant in the @value{GDBN} source tree.
+@item
+When @value{GDBN} does support the architecture of the embedded system
+at hand, the task of finding the correct architecture name to give the
+@command{set architecture} command can be error-prone.
+@end itemize
+
+To address these problems, the @value{GDBN} remote protocol allows a
+target system to not only identify itself to @value{GDBN}, but to
+actually describe its own features. This lets @value{GDBN} support
+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
+@section Retrieving Descriptions
+
+Target descriptions can be read from the target automatically, or
+specified by the user manually. The default behavior is to read the
+description from the target. @value{GDBN} retrieves it via the remote
+protocol using @samp{qXfer} requests (@pxref{General Query Packets,
+qXfer}). The @var{annex} in the @samp{qXfer} packet will be
+@samp{target.xml}. The contents of the @samp{target.xml} annex are an
+XML document, of the form described in @ref{Target Description
+Format}.
+
+Alternatively, you can specify a file to read for the target description.
+If a file is set, the target will not be queried. The commands to
+specify a file are:
+
+@table @code
+@cindex set tdesc filename
+@item set tdesc filename @var{path}
+Read the target description from @var{path}.
+
+@cindex unset tdesc filename
+@item unset tdesc filename
+Do not read the XML target description from a file. @value{GDBN}
+will use the description supplied by the current target.
+
+@cindex show tdesc filename
+@item show tdesc filename
+Show the filename to read for a target description, if any.
+@end table
+
+
+@node Target Description Format
+@section Target Description Format
+@cindex target descriptions, XML format
+
+A target description annex is an @uref{http://www.w3.org/XML/, XML}
+document which complies with the Document Type Definition provided in
+the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This
+means you can use generally available tools like @command{xmllint} to
+check that your feature descriptions are well-formed and valid.
+However, to help people unfamiliar with XML write descriptions for
+their targets, we also describe the grammar here.
+
+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:
+
+@smallexample
+<target version="1.0">
+ <architecture>i386:x86-64</architecture>
+</target>
+@end smallexample
+
+@noindent
+This minimal description only says that the target uses
+the x86-64 architecture.
+
+A target description has the following overall form, with [ ] marking
+optional elements and @dots{} marking repeatable elements. The elements
+are explained further below.
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE target SYSTEM "gdb-target.dtd">
+<target version="1.0">
+ @r{[}@var{architecture}@r{]}
+ @r{[}@var{feature}@dots{}@r{]}
+</target>
+@end smallexample
+
+@noindent
+The description is generally insensitive to whitespace and line
+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. 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
+@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 ieee_single
+Single precision IEEE floating point.
+
+@item ieee_double
+Double precision IEEE floating point.
+
+@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.
+
+@menu
+* ARM Features::
+* M68K Features::
+@end menu
+
+
+@node ARM Features
+@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.
+
+@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
+