<html lang="en">
<head>
<title>Target Description Format - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Target-Descriptions.html#Target-Descriptions" title="Target Descriptions">
<link rel="prev" href="Retrieving-Descriptions.html#Retrieving-Descriptions" title="Retrieving Descriptions">
<link rel="next" href="Predefined-Target-Types.html#Predefined-Target-Types" title="Predefined Target Types">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Target-Description-Format"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Predefined-Target-Types.html#Predefined-Target-Types">Predefined Target Types</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Retrieving-Descriptions.html#Retrieving-Descriptions">Retrieving Descriptions</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Target-Descriptions.html#Target-Descriptions">Target Descriptions</a>
<hr>
</div>

<h3 class="section">G.2 Target Description Format</h3>

<p><a name="index-target-descriptions_002c-XML-format-3642"></a>
A target description annex is an <a href="http://www.w3.org/XML/">XML</a>
document which complies with the Document Type Definition provided in
the <span class="sc">gdb</span> sources in <samp><span class="file">gdb/features/gdb-target.dtd</span></samp>.  This
means you can use generally available tools like <samp><span class="command">xmllint</span></samp> 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.

   <p>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. 
<span class="sc">gdb</span> can use this information to autoconfigure for your
target, or to warn you if you connect to an unsupported target.

   <p>Here is a simple target description:

<pre class="smallexample">     &lt;target version="1.0"&gt;
       &lt;architecture&gt;i386:x86-64&lt;/architecture&gt;
     &lt;/target&gt;
</pre>
   <p class="noindent">This minimal description only says that the target uses
the x86-64 architecture.

   <p>A target description has the following overall form, with [ ] marking
optional elements and <small class="dots">...</small> marking repeatable elements.  The elements
are explained further below.

<pre class="smallexample">     &lt;?xml version="1.0"?&gt;
     &lt;!DOCTYPE target SYSTEM "gdb-target.dtd"&gt;
     &lt;target version="1.0"&gt;
       <span class="roman">[</span><var>architecture</var><span class="roman">]</span>
       <span class="roman">[</span><var>osabi</var><span class="roman">]</span>
       <span class="roman">[</span><var>compatible</var><span class="roman">]</span>
       <span class="roman">[</span><var>feature</var>...<span class="roman">]</span>
     &lt;/target&gt;
</pre>
   <p class="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
(<span class="sc">gdb</span> does not require them), but specifying them may be
useful for XML validation tools.  The &lsquo;<samp><span class="samp">version</span></samp>&rsquo; attribute for
&lsquo;<samp><span class="samp">&lt;target&gt;</span></samp>&rsquo; may also be omitted, but we recommend
including it; if future versions of <span class="sc">gdb</span> use an incompatible
revision of <samp><span class="file">gdb-target.dtd</span></samp>, they will detect and report
the version mismatch.

<h4 class="subsection">G.2.1 Inclusion</h4>

<p><a name="index-target-descriptions_002c-inclusion-3643"></a><a name="index-XInclude-3644"></a><a name="index-g_t_003cxi_003ainclude_003e-3645"></a>
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:

<pre class="smallexample">     &lt;xi:include href="<var>document</var>"/&gt;
</pre>
   <p class="noindent">When <span class="sc">gdb</span> encounters an element of this form, it will retrieve
the named XML <var>document</var>, and replace the inclusion directive with
the contents of that document.  If the current description was read
using &lsquo;<samp><span class="samp">qXfer</span></samp>&rsquo;, then so will be the included document;
<var>document</var> will be interpreted as the name of an annex.  If the
current description was read from a file, <span class="sc">gdb</span> will look for
<var>document</var> as a file in the same directory where it found the
original description.

<h4 class="subsection">G.2.2 Architecture</h4>

<p><a name="index-g_t_003carchitecture_003e-3646"></a>
An &lsquo;<samp><span class="samp">&lt;architecture&gt;</span></samp>&rsquo; element has this form:

<pre class="smallexample">       &lt;architecture&gt;<var>arch</var>&lt;/architecture&gt;
</pre>
   <p><var>arch</var> is one of the architectures from the set accepted by
<code>set architecture</code> (see <a href="Targets.html#Targets">Specifying a Debugging Target</a>).

<h4 class="subsection">G.2.3 OS ABI</h4>

<p><a name="index-g_t_0040code_007b_003cosabi_003e_007d-3647"></a>
This optional field was introduced in <span class="sc">gdb</span> version 7.0. 
Previous versions of <span class="sc">gdb</span> ignore it.

   <p>An &lsquo;<samp><span class="samp">&lt;osabi&gt;</span></samp>&rsquo; element has this form:

<pre class="smallexample">       &lt;osabi&gt;<var>abi-name</var>&lt;/osabi&gt;
</pre>
   <p><var>abi-name</var> is an OS ABI name from the same selection accepted by
<code>set&nbsp;osabi</code><!-- /@w --> (see <a href="ABI.html#ABI">Configuring the Current ABI</a>).

<h4 class="subsection">G.2.4 Compatible Architecture</h4>

<p><a name="index-g_t_0040code_007b_003ccompatible_003e_007d-3648"></a>
This optional field was introduced in <span class="sc">gdb</span> version 7.0. 
Previous versions of <span class="sc">gdb</span> ignore it.

   <p>A &lsquo;<samp><span class="samp">&lt;compatible&gt;</span></samp>&rsquo; element has this form:

<pre class="smallexample">       &lt;compatible&gt;<var>arch</var>&lt;/compatible&gt;
</pre>
   <p><var>arch</var> is one of the architectures from the set accepted by
<code>set architecture</code> (see <a href="Targets.html#Targets">Specifying a Debugging Target</a>).

   <p>A &lsquo;<samp><span class="samp">&lt;compatible&gt;</span></samp>&rsquo; element is used to specify that the target
is able to run binaries in some other than the main target architecture
given by the &lsquo;<samp><span class="samp">&lt;architecture&gt;</span></samp>&rsquo; element.  For example, on the
Cell Broadband Engine, the main architecture is <code>powerpc:common</code>
or <code>powerpc:common64</code>, but the system is able to run binaries
in the <code>spu</code> architecture as well.  The way to describe this
capability with &lsquo;<samp><span class="samp">&lt;compatible&gt;</span></samp>&rsquo; is as follows:

<pre class="smallexample">       &lt;architecture&gt;powerpc:common&lt;/architecture&gt;
       &lt;compatible&gt;spu&lt;/compatible&gt;
</pre>
   <h4 class="subsection">G.2.5 Features</h4>

<p><a name="index-g_t_003cfeature_003e-3649"></a>
Each &lsquo;<samp><span class="samp">&lt;feature&gt;</span></samp>&rsquo; describes some logical portion of the target
system.  Features are currently used to describe available CPU
registers and the types of their contents.  A &lsquo;<samp><span class="samp">&lt;feature&gt;</span></samp>&rsquo; element
has this form:

<pre class="smallexample">     &lt;feature name="<var>name</var>"&gt;
       <span class="roman">[</span><var>type</var>...<span class="roman">]</span>
       <var>reg</var>...
     &lt;/feature&gt;
</pre>
   <p class="noindent">Each feature's name should be unique within the description.  The name
of a feature does not matter unless <span class="sc">gdb</span> has some special
knowledge of the contents of that feature; if it does, the feature
should have its standard name.  See <a href="Standard-Target-Features.html#Standard-Target-Features">Standard Target Features</a>.

<h4 class="subsection">G.2.6 Types</h4>

<p>Any register's value is a collection of bits which <span class="sc">gdb</span> 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 <span class="sc">gdb</span> (see <a href="Predefined-Target-Types.html#Predefined-Target-Types">Predefined Target Types</a>), and the description can define additional composite
and enum types.

   <p>Each type element must have an &lsquo;<samp><span class="samp">id</span></samp>&rsquo; attribute, which gives
a unique (within the containing &lsquo;<samp><span class="samp">&lt;feature&gt;</span></samp>&rsquo;) name to the type. 
Types must be defined before they are used.

   <p><a name="index-g_t_003cvector_003e-3650"></a>Some targets offer vector registers, which can be treated as arrays
of scalar elements.  These types are written as &lsquo;<samp><span class="samp">&lt;vector&gt;</span></samp>&rsquo; elements,
specifying the array element type, <var>type</var>, and the number of elements,
<var>count</var>:

<pre class="smallexample">     &lt;vector id="<var>id</var>" type="<var>type</var>" count="<var>count</var>"/&gt;
</pre>
   <p><a name="index-g_t_003cunion_003e-3651"></a>If a register's value is usefully viewed in multiple ways, define it
with a union type containing the useful representations.  The
&lsquo;<samp><span class="samp">&lt;union&gt;</span></samp>&rsquo; element contains one or more &lsquo;<samp><span class="samp">&lt;field&gt;</span></samp>&rsquo; elements,
each of which has a <var>name</var> and a <var>type</var>:

<pre class="smallexample">     &lt;union id="<var>id</var>"&gt;
       &lt;field name="<var>name</var>" type="<var>type</var>"/&gt;
       ...
     &lt;/union&gt;
</pre>
   <p><a name="index-g_t_003cstruct_003e-3652"></a><a name="index-g_t_003cflags_003e-3653"></a>If a register's value is composed from several separate values, define
it with either a structure type or a flags type. 
A flags type may only contain bitfields. 
A structure type may either contain only bitfields or contain no bitfields. 
If the value contains only bitfields, its total size in bytes must be
specified.

   <p>Non-bitfield values have a <var>name</var> and <var>type</var>.

<pre class="smallexample">     &lt;struct id="<var>id</var>"&gt;
       &lt;field name="<var>name</var>" type="<var>type</var>"/&gt;
       ...
     &lt;/struct&gt;
</pre>
   <p>Both <var>name</var> and <var>type</var> values are required. 
No implicit padding is added.

   <p>Bitfield values have a <var>name</var>, <var>start</var>, <var>end</var> and <var>type</var>.

<pre class="smallexample">     &lt;struct id="<var>id</var>" size="<var>size</var>"&gt;
       &lt;field name="<var>name</var>" start="<var>start</var>" end="<var>end</var>" type="<var>type</var>"/&gt;
       ...
     &lt;/struct&gt;
</pre>
   <pre class="smallexample">     &lt;flags id="<var>id</var>" size="<var>size</var>"&gt;
       &lt;field name="<var>name</var>" start="<var>start</var>" end="<var>end</var>" type="<var>type</var>"/&gt;
       ...
     &lt;/flags&gt;
</pre>
   <p>The <var>name</var> value is required. 
Bitfield values may be named with the empty string, &lsquo;<samp><span class="samp">""</span></samp>&rsquo;,
in which case the field is &ldquo;filler&rdquo; and its value is not printed. 
Not all bits need to be specified, so &ldquo;filler&rdquo; fields are optional.

   <p>The <var>start</var> and <var>end</var> values are required, and <var>type</var>
is optional. 
The field's <var>start</var> must be less than or equal to its <var>end</var>,
and zero represents the least significant bit.

   <p>The default value of <var>type</var> is <code>bool</code> for single bit fields,
and an unsigned integer otherwise.

   <p>Which to choose?  Structures or flags?

   <p>Registers defined with &lsquo;<samp><span class="samp">flags</span></samp>&rsquo; have these advantages over
defining them with &lsquo;<samp><span class="samp">struct</span></samp>&rsquo;:

     <ul>
<li>Arithmetic may be performed on them as if they were integers. 
<li>They are printed in a more readable fashion. 
</ul>

   <p>Registers defined with &lsquo;<samp><span class="samp">struct</span></samp>&rsquo; have one advantage over
defining them with &lsquo;<samp><span class="samp">flags</span></samp>&rsquo;:

     <ul>
<li>One can fetch individual fields like in &lsquo;<samp><span class="samp">C</span></samp>&rsquo;.

     <pre class="smallexample">          (gdb) print $my_struct_reg.field3
          $1 = 42
</pre>
     </ul>

<h4 class="subsection">G.2.7 Registers</h4>

<p><a name="index-g_t_003creg_003e-3654"></a>
Each register is represented as an element with this form:

<pre class="smallexample">     &lt;reg name="<var>name</var>"
          bitsize="<var>size</var>"
          <span class="roman">[</span>regnum="<var>num</var>"<span class="roman">]</span>
          <span class="roman">[</span>save-restore="<var>save-restore</var>"<span class="roman">]</span>
          <span class="roman">[</span>type="<var>type</var>"<span class="roman">]</span>
          <span class="roman">[</span>group="<var>group</var>"<span class="roman">]</span>/&gt;
</pre>
   <p class="noindent">The components are as follows:

     <dl>
<dt><var>name</var><dd>The register's name; it must be unique within the target description.

     <br><dt><var>bitsize</var><dd>The register's size, in bits.

     <br><dt><var>regnum</var><dd>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 <code>p</code> and <code>P</code>
packets, and registers appear in the <code>g</code> and <code>G</code> packets
in order of increasing register number.

     <br><dt><var>save-restore</var><dd>Whether the register should be preserved across inferior function
calls; this must be either <code>yes</code> or <code>no</code>.  The default is
<code>yes</code>, which is appropriate for most registers except for
some system control registers; this is not related to the target's
ABI.

     <br><dt><var>type</var><dd>The type of the register.  It may be a predefined type, a type
defined in the current feature, or one of the special types <code>int</code>
and <code>float</code>.  <code>int</code> is an integer type of the correct size
for <var>bitsize</var>, and <code>float</code> is a floating point type (in the
architecture's normal floating point format) of the correct size for
<var>bitsize</var>.  The default is <code>int</code>.

     <br><dt><var>group</var><dd>The register group to which this register belongs.  It can be one of the
standard register groups <code>general</code>, <code>float</code>, <code>vector</code> or an
arbitrary string.  Group names should be limited to alphanumeric characters. 
If a group name is made up of multiple words the words may be separated by
hyphens; e.g. <code>special-group</code> or <code>ultra-special-group</code>.  If no
<var>group</var> is specified, <span class="sc">gdb</span> will not display the register in
<code>info registers</code>.

   </dl>

   </body></html>