| <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> |
| |
