From 14d04965de95b5db8671cfad90e602025f760403 Mon Sep 17 00:00:00 2001 From: Daniel Jacobowitz Date: Wed, 29 Mar 2006 15:40:08 +0000 Subject: Add user documentation (almost entirely written by Jim Blandy). --- gdb/doc/gdb.texinfo | 243 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index ca8d80fe453..adf38a959e1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -23250,6 +23250,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{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 +23262,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 +24816,242 @@ 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. + + +@node Retrieving Self-Descriptions +@section Retrieving Self-Descriptions + +@value{GDBN} retrieves a target's self-description via the remote +protocol using a @code{qPart} request (@pxref{qPart request,, the +@code{qPart} request}) of the form: +@example +qPart:features:read:@var{annex}:@var{offset},@var{length} +@end example +@noindent +where @var{annex} is the string @samp{target.xml}. 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. + +The @samp{target.xml} annex contains an XML document describing the +target's features; its form is described in @ref{Self-Description +Format}. + +Feature descriptions may be split into several annexes, which +@value{GDBN} retrieves and assembles into a complete description. An +annex may use @uref{http://www.w3.org/TR/xinclude/, XML Inclusions} to +incorporate other annexes, much as a C header file refers to other +headers using @code{#include}. @value{GDBN} first retrieves +@samp{target.xml}, and then makes further @code{qPart} requests as +needed to retrieve the annexes referred to by any @code{xi:include} +elements it finds. Naturally, annexes brought in by @code{xi:include} +may use @code{xi:include} themselves. + +To reduce protocol overhead, a target may supply a special annex named +@samp{CHECKSUMS} that provides 160-bit SHA1 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{CHECKSUM} 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 + + + + + + + + + + + + +@end example +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 + + + + @var{feature}@dots{} + @var{feature-set} + +@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 + + @var{reg}@dots{} + +@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 + +@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 readonly +Whether the register is read-only or not; this must be either +@code{yes} or @code{no}. The default is @code{no}. + +@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 + + @var{feature-ref}@dots{} + +@end example +@noindent +where each @var{feature-ref} has the form: +@example + +@end example +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 + +@end example +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 -- cgit v1.2.1