diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index ca8d80fe453..d79933a1511 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -159,6 +159,8 @@ Copyright (C) 1988-2005 Free Software Foundation, Inc. * Maintenance Commands:: Maintenance Commands * Remote Protocol:: GDB Remote Serial Protocol * Agent Expressions:: The GDB Agent Expression Mechanism +* Self-Describing Targets:: How targets can describe themselves to + @value{GDBN} * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation @@ -23250,6 +23252,7 @@ Reply: see @code{remote.c:remote_unpack_thread_info_response()}. @item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length} @cindex read special object, remote request @cindex @samp{qPart} packet +@anchor{the qPart request} Read uninterpreted bytes from the target's special data area identified by the keyword @var{object}. Request @var{length} bytes starting at @var{offset} bytes into the data. The content and @@ -23261,10 +23264,16 @@ Here are the specific requests of this form defined so far. All formats, listed below. @table @samp + @item qPart:auxv:read::@var{offset},@var{length} Access the target's @dfn{auxiliary vector}. @xref{OS Information, auxiliary vector}, and see @ref{Remote configuration, read-aux-vector-packet}. Note @var{annex} must be empty. + +@item qPart:features:read:@var{annex}:@var{offset},@var{length} +Retrieve information describing features the target supports (register +sets, memory regions, and so on). @xref{Self-Describing Targets}. + @end table Reply: @@ -24809,6 +24818,258 @@ host is called: @include agentexpr.texi +@node Self-Describing Targets +@appendix Self-Describing Targets + +One of the challenges of using @value{GDBN} to debug embedded systems +is that there are so many minor variants of each processor +architecture in use. It is common practice for vendors to start with +a standard processor core --- ARM, PowerPC, or MIPS, for example --- +and then make changes to adapt it to a particular market niche. Some +architectures have hundreds of variants, available from dozens of +vendors. This leads to a number of problems: + +@itemize @bullet +@item +With so many different customized processors, it is difficult for +the @value{GDBN} maintainers to keep up with the changes. +@item +Since individual variants may have short lifetimes or limited +audiences, it may not be worthwhile to carry information about every +variant in the @value{GDBN} source tree. +@item +When @value{GDBN} does support the architecture of the embedded system +at hand, the task of finding the correct architecture name to give the +@command{set architecture} command can be error-prone. +@end itemize + +To address these problems, the @value{GDBN} remote protocol allows a +target system to not only identify itself to @value{GDBN}, but to +actually describe its own features. This lets @value{GDBN} support +processor variants it has never seen before --- to the extent that the +descriptions are accurate, and that @value{GDBN} understands them. + +@menu +* Retrieving Self-Descriptions:: How descriptions are fetched from a target. +* Self-Description Format:: The contents of a self-description. +@end menu + +@node Retrieving Self-Descriptions +@section Retrieving Self-Descriptions + +A target can split its self-description into one or more pieces, +called @dfn{annexes}. @value{GDBN} retrieves each annex via the +remote protocol using @code{qPart} requests (@pxref{the qPart +request}) of the form: + +@example +qPart:features:read:@var{annex}:@var{offset},@var{length} +@end example + +@noindent +where @var{annex} is the name of the annex, and the @var{offset} and +@var{length} parameters are the offset into the description and the +number of bytes to transfer, as for other @code{qPart} requests. + +To retrieve a target's self-description, @value{GDBN} first fetches +the annex named @samp{target.xml}. This is an XML document, of the +form described in @ref{Self-Description Format}. Just as C header +files can refer to other header files using @code{#include}, target +description annexes can use @uref{http://www.w3.org/TR/xinclude/, XML +Inclusions} to incorporate other annexes. Starting with +@samp{target.xml}, @value{GDBN} makes further @code{qPart} requests as +needed to resolve all the inclusions and assemble the complete +description. + +To reduce protocol overhead, a target may supply a special annex named +@samp{CHECKSUMS} that provides 160-bit SHA-1@footnote{The SHA-1 hash +function is defined in +@uref{http://www.itl.nist.gov/fipspubs/fip180-1.htm, Federal +Information Processing Standards Publication 180-1}. The GNU +coreutils contain a Free implementation of SHA-1.} checksum values +for the annexes it has available. The @samp{CHECKSUMS} annex contains +a series of newline-terminated lines, each of which contains a +40-digit hexidecimal checksum, two spaces, and the name of an annex +with the given checksum. Here is an example @samp{CHECKSUMS} annex: + +@example +68c94ffc34f8ad2d7bfae3f5a6b996409211c1b1 target.xml +0e8e850b0580fbaaa0872326cb1b8ad6adda9b0d mmu.xml +00f22e5f971ccec05c2acce98caf8cff4343c8cf fpu.xml +@end example + +@value{GDBN} uses these checksums to avoid retrieving a given annex +more than once. When @value{GDBN} retrieves an annex, it caches its +contents locally. Then, each time @value{GDBN} thinks the target +architecture may have changed (say, after making a new remote protocol +connection, or after starting a new child process using the extended +remote protocol), it retrieves the @samp{CHECKSUMS} annex afresh. If +the checksums show that a particular annex's contents are the same on +the target and in @value{GDBN}'s cache, @value{GDBN} avoids fetching +it again. If none of the annexes have changed, @value{GDBN} needs +only retrieve the @samp{CHECKSUMS} annex. + +@samp{CHECKSUMS} need not provide a checksum for every annex +available; if a given annex is not mentioned, @value{GDBN} will try to +retrieve it each time it thinks the target architecture may have +changed. The target need not provide any @samp{CHECKSUMS} annex at +all; this is equivalent to an empty @samp{CHECKSUMS} annex. + + +@node Self-Description Format +@section Self-Description Format + +A target description annex is an @uref{http://www.w3.org/XML/, XML} +document which complies with the Document Type Definition provided in +the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This +means you can use generally available tools like @command{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. + +At the moment, target descriptions can only describe register sets, to +be accessed via the remote protocol @code{g}, @code{G}, @code{p} and +@code{P} requests. We hope to extend the format to include other +kinds of information, like memory maps. + +Here is a simple sample target description: + +@example +<?xml version="1.0"?> +<!DOCTYPE target SYSTEM "gdb-target.dtd"> +<target> + <feature name="bar"> + <reg name="s0" bitsize="32"/> + <reg name="s1" bitsize="32" type="float"/> + </feature> + + <feature-set> + <feature-ref name="bar" base-regnum="1"/> + </feature-set> +</target> +@end example + +@noindent +This describes a simple target feature set which only contains two +registers, named @code{s0} (a 32-bit integer register) and @code{s1} +(a 32-bit floating point register). + +A target description has the overall form: + +@example +<?xml version="1.0"?> +<!DOCTYPE target SYSTEM "gdb-target.dtd"> +<target> + @var{feature}@dots{} + @var{feature-set} +</target> +@end example + +@noindent +The description is generally insensitive to whitespace and line +breaks, under the usual common-sense rules. The ellipsis +(@samp{@dots{}}) after @var{feature} indicates that @var{feature} may +appear zero or more times. + +Each @var{feature} names and describes a single feature of the target; +at the moment, features can only describe register sets. The +@var{feature-set} cites particular features by name, pulling together +a complete description of the target. A @var{feature} has the form: + +@example +<feature name="@var{name}"> + @var{reg}@dots{} +</feature> +@end example + +@noindent +This defines a feature named @var{name}; each feature's name must be +unique across the description. + +Each @var{reg} has the form: + +@example +<reg name="@var{name}" + bitsize="@var{size}" + @r{[}regnum="@var{num}"@r{]} + @r{[}save-restore="@var{save-restore}"@r{]} + @r{[}type="@var{type}"@r{]} + @r{[}group="@var{group}"@r{]}/> +@end example + +@noindent +Items in @r{[}brackets@r{]} are optional. The components are as follows: + +@table @var + +@item name +The register's name; it must be unique within the target description. + +@item bitsize +The register's size, in bits. + +@item regnum +The register's number. If omitted, a register's number is one greater +than that of the previous register; the first register's number +defaults to zero. But also see the @code{feature-ref} element's +@code{base-regnum} attribute, below---these register numbers are relative +to the @code{base-regnum}. + +@item save-restore +Whether the register should be preserved across inferior function +calls; this must be either @code{yes} or @code{no}. The default is +@code{yes}. + +@item type +The type of the register. At the moment, @var{type} must be either +@code{int} or @code{float}. The default is @code{int}. + +@item group +The register group to which this register belongs. At the moment, +@var{group} must be either @code{general}, @code{float}, or +@code{vector}. If no @var{group} is specified, @value{GDBN} will +select a register group based on the register's type. + +@end table + +A @var{feature-set} binds together a set of features to describe +a complete target. There can be only one @var{feature-set} in a +target. Each @var{feature-set} has the form: + +@example +<feature-set> + @var{feature-ref}@dots{} +</feature-set> +@end example + +@noindent +where each @var{feature-ref} has the form: + +@example +<feature-ref name="@var{name}" @r{[}base-regnum="@var{n}"@r{]}/> +@end example + +@noindent +This means that the target includes the feature named @var{name}. If +the @code{base-regnum} is present, that means that registers in the +given feature are numbered starting with @var{n}, until overridden by +an explicit register number. + +It can sometimes be valuable to split a target description up into +several different annexes, either for organizational purposes, or to +allow @value{GDBN} to cache portions of the description that change +rarely. To make this possible, you can replace any feature +description with an inclusion directive of the form: + +@example +<xi:include href="@var{annex}"/> +@end example + +@noindent +When @value{GDBN} encounters an element of this form, it will retrieve +the annex named @var{annex} (or use its cached copy), and replace the +inclusion directive with the contents of that annex. + @include gpl.texi @raisesections |