327 lines
17 KiB
HTML
327 lines
17 KiB
HTML
<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: <a rel="next" accesskey="n" href="Predefined-Target-Types.html#Predefined-Target-Types">Predefined Target Types</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="Retrieving-Descriptions.html#Retrieving-Descriptions">Retrieving Descriptions</a>,
|
|
Up: <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"> <target version="1.0">
|
|
<architecture>i386:x86-64</architecture>
|
|
</target>
|
|
</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"> <?xml version="1.0"?>
|
|
<!DOCTYPE target SYSTEM "gdb-target.dtd">
|
|
<target version="1.0">
|
|
<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>
|
|
</target>
|
|
</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 ‘<samp><span class="samp">version</span></samp>’ attribute for
|
|
‘<samp><span class="samp"><target></span></samp>’ 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"> <xi:include href="<var>document</var>"/>
|
|
</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 ‘<samp><span class="samp">qXfer</span></samp>’, 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 ‘<samp><span class="samp"><architecture></span></samp>’ element has this form:
|
|
|
|
<pre class="smallexample"> <architecture><var>arch</var></architecture>
|
|
</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 ‘<samp><span class="samp"><osabi></span></samp>’ element has this form:
|
|
|
|
<pre class="smallexample"> <osabi><var>abi-name</var></osabi>
|
|
</pre>
|
|
<p><var>abi-name</var> is an OS ABI name from the same selection accepted by
|
|
<code>set 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 ‘<samp><span class="samp"><compatible></span></samp>’ element has this form:
|
|
|
|
<pre class="smallexample"> <compatible><var>arch</var></compatible>
|
|
</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 ‘<samp><span class="samp"><compatible></span></samp>’ element is used to specify that the target
|
|
is able to run binaries in some other than the main target architecture
|
|
given by the ‘<samp><span class="samp"><architecture></span></samp>’ 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 ‘<samp><span class="samp"><compatible></span></samp>’ is as follows:
|
|
|
|
<pre class="smallexample"> <architecture>powerpc:common</architecture>
|
|
<compatible>spu</compatible>
|
|
</pre>
|
|
<h4 class="subsection">G.2.5 Features</h4>
|
|
|
|
<p><a name="index-g_t_003cfeature_003e-3649"></a>
|
|
Each ‘<samp><span class="samp"><feature></span></samp>’ 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><span class="samp"><feature></span></samp>’ element
|
|
has this form:
|
|
|
|
<pre class="smallexample"> <feature name="<var>name</var>">
|
|
<span class="roman">[</span><var>type</var>...<span class="roman">]</span>
|
|
<var>reg</var>...
|
|
</feature>
|
|
</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 ‘<samp><span class="samp">id</span></samp>’ attribute, which gives
|
|
a unique (within the containing ‘<samp><span class="samp"><feature></span></samp>’) 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 ‘<samp><span class="samp"><vector></span></samp>’ elements,
|
|
specifying the array element type, <var>type</var>, and the number of elements,
|
|
<var>count</var>:
|
|
|
|
<pre class="smallexample"> <vector id="<var>id</var>" type="<var>type</var>" count="<var>count</var>"/>
|
|
</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
|
|
‘<samp><span class="samp"><union></span></samp>’ element contains one or more ‘<samp><span class="samp"><field></span></samp>’ elements,
|
|
each of which has a <var>name</var> and a <var>type</var>:
|
|
|
|
<pre class="smallexample"> <union id="<var>id</var>">
|
|
<field name="<var>name</var>" type="<var>type</var>"/>
|
|
...
|
|
</union>
|
|
</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"> <struct id="<var>id</var>">
|
|
<field name="<var>name</var>" type="<var>type</var>"/>
|
|
...
|
|
</struct>
|
|
</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"> <struct id="<var>id</var>" size="<var>size</var>">
|
|
<field name="<var>name</var>" start="<var>start</var>" end="<var>end</var>" type="<var>type</var>"/>
|
|
...
|
|
</struct>
|
|
</pre>
|
|
<pre class="smallexample"> <flags id="<var>id</var>" size="<var>size</var>">
|
|
<field name="<var>name</var>" start="<var>start</var>" end="<var>end</var>" type="<var>type</var>"/>
|
|
...
|
|
</flags>
|
|
</pre>
|
|
<p>The <var>name</var> value is required.
|
|
Bitfield values may be named with the empty string, ‘<samp><span class="samp">""</span></samp>’,
|
|
in which case the field is “filler” and its value is not printed.
|
|
Not all bits need to be specified, so “filler” 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 ‘<samp><span class="samp">flags</span></samp>’ have these advantages over
|
|
defining them with ‘<samp><span class="samp">struct</span></samp>’:
|
|
|
|
<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 ‘<samp><span class="samp">struct</span></samp>’ have one advantage over
|
|
defining them with ‘<samp><span class="samp">flags</span></samp>’:
|
|
|
|
<ul>
|
|
<li>One can fetch individual fields like in ‘<samp><span class="samp">C</span></samp>’.
|
|
|
|
<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"> <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>/>
|
|
</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>
|
|
|