Next: Predefined Target Types, Previous: Retrieving Descriptions, Up: Target Descriptions
A target description annex is an XML document which complies with the Document Type Definition provided in the gdb sources in gdb/features/gdb-target.dtd. This means you can use generally available tools like 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. gdb 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:
<target version="1.0"> <architecture>i386:x86-64</architecture> </target>
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 ... marking repeatable elements. The elements are explained further below.
<?xml version="1.0"?> <!DOCTYPE target SYSTEM "gdb-target.dtd"> <target version="1.0"> [architecture] [feature...] </target>
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 (gdb does not require them), but specifying them may be useful for XML validation tools. The `version' attribute for `<target>' may also be omitted, but we recommend including it; if future versions of gdb use an incompatible revision of gdb-target.dtd, they will detect and report the version mismatch.
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:
<xi:include href="document"/>
When gdb encounters an element of this form, it will retrieve the named XML document, and replace the inclusion directive with the contents of that document. If the current description was read using `qXfer', then so will be the included document; document will be interpreted as the name of an annex. If the current description was read from a file, gdb will look for document as a file in the same directory where it found the original description.
An `<architecture>' element has this form:
<architecture>arch</architecture>
arch is an architecture name from the same selection
accepted by set architecture
(see Specifying a Debugging Target).
Each `<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 `<feature>' element has this form:
<feature name="name"> [type...] reg... </feature>
Each feature's name should be unique within the description. The name of a feature does not matter unless gdb has some special knowledge of the contents of that feature; if it does, the feature should have its standard name. See Standard Target Features.
Any register's value is a collection of bits which gdb 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 gdb (see Predefined Target Types), and the description can define additional composite types.
Each type element must have an `id' attribute, which gives a unique (within the containing `<feature>') name to the type. Types must be defined before they are used.
Some targets offer vector registers, which can be treated as arrays of scalar elements. These types are written as `<vector>' elements, specifying the array element type, type, and the number of elements, count:
<vector id="id" type="type" count="count"/>
If a register's value is usefully viewed in multiple ways, define it with a union type containing the useful representations. The `<union>' element contains one or more `<field>' elements, each of which has a name and a type:
<union id="id"> <field name="name" type="type"/> ... </union>
Each register is represented as an element with this form:
<reg name="name" bitsize="size" [regnum="num"] [save-restore="save-restore"] [type="type"] [group="group"]/>
The components are as follows:
p
and P
packets, and registers appear in the g
and G
packets
in order of increasing register number.
yes
or no
. The default is
yes
, which is appropriate for most registers except for
some system control registers; this is not related to the target's
ABI.
int
and float
. int
is an integer type of the correct size
for bitsize, and float
is a floating point type (in the
architecture's normal floating point format) of the correct size for
bitsize. The default is int
.
general
, float
, or vector
. If no
group is specified, gdb will not display the register
in info registers
.