gdb.info: Target Description Format

Target Descriptions

Predefined Target Types

Retrieving Descriptions

Back to Software Index

G.2 Target Description Format
=============================

A target description annex is an XML (http://www.w3.org/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.  They can also identify the OS ABI of the remote target.
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]
       [OSABI]
       [COMPATIBLE]
       [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.

G.2.1 Inclusion
---------------

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.

G.2.2 Architecture
------------------

An '<architecture>' element has this form:

       <architecture>ARCH</architecture>

   ARCH is one of the architectures from the set accepted by 'set
architecture' (Note: Specifying a Debugging Target.).

G.2.3 OS ABI
------------

This optional field was introduced in GDB version 7.0.  Previous
versions of GDB ignore it.

   An '<osabi>' element has this form:

       <osabi>ABI-NAME</osabi>

   ABI-NAME is an OS ABI name from the same selection accepted by 'set osabi'
(Note: Configuring the Current ABI.).

G.2.4 Compatible Architecture
-----------------------------

This optional field was introduced in GDB version 7.0.  Previous
versions of GDB ignore it.

   A '<compatible>' element has this form:

       <compatible>ARCH</compatible>

   ARCH is one of the architectures from the set accepted by 'set
architecture' (Note: Specifying a Debugging Target.).

   A '<compatible>' element is used to specify that the target is able
to run binaries in some other than the main target architecture given by
the '<architecture>' element.  For example, on the Cell Broadband
Engine, the main architecture is 'powerpc:common' or 'powerpc:common64',
but the system is able to run binaries in the 'spu' architecture as
well.  The way to describe this capability with '<compatible>' is as
follows:

       <architecture>powerpc:common</architecture>
       <compatible>spu</compatible>

G.2.5 Features
--------------

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.  Note: Standard Target Features.

G.2.6 Types
-----------

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 (Note: 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>

   If a register's value is composed from several separate values,
define it with a structure type.  There are two forms of the '<struct>'
element; a '<struct>' element must either contain only bitfields or
contain no bitfields.  If the structure contains only bitfields, its
total size in bytes must be specified, each bitfield must have an
explicit start and end, and bitfields are automatically assigned an
integer type.  The field's START should be less than or equal to its
END, and zero represents the least significant bit.

     <struct id="ID" size="SIZE">
       <field name="NAME" start="START" end="END"/>
       ...
     </struct>

   If the structure contains no bitfields, then each field has an
explicit type, and no implicit padding is added.

     <struct id="ID">
       <field name="NAME" type="TYPE"/>
       ...
     </struct>

   If a register's value is a series of single-bit flags, define it with
a flags type.  The '<flags>' element has an explicit SIZE and contains
one or more '<field>' elements.  Each field has a NAME, a START, and an
END.  Only single-bit flags are supported.

     <flags id="ID" size="SIZE">
       <field name="NAME" start="START" end="END"/>
       ...
     </flags>

G.2.7 Registers
---------------

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:

NAME
     The register's name; it must be unique within the target
     description.

BITSIZE
     The register's size, in bits.

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 preceding 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 'p'
     and 'P' packets, and registers appear in the 'g' and 'G' packets in
     order of increasing register number.

SAVE-RESTORE
     Whether the register should be preserved across inferior function
     calls; this must be either '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.

TYPE
     The type of the register.  It may be a predefined type, a type
     defined in the current feature, or one of the special types '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'.

GROUP
     The register group to which this register belongs.  It must be
     either 'general', 'float', or 'vector'.  If no GROUP is specified,
     GDB will not display the register in 'info registers'.