Add user documentation (almost entirely written by Jim Blandy).

1 files changed, 243 insertions, 0 deletions

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
+<?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
+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{[}readonly="@var{read-only}"@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 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
+<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
+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
+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