* Makefile.in (arm-tdep.o, eval.o, target-descriptions.o)

	(xml-tdesc.o): Update.
	* xml-support.c: Add a comment.
	(gdb_xml_enums_boolean): New variable.
	(gdb_xml_parse_attr_enum): Use strcasecmp.
	* xml-support.h (gdb_xml_enums_boolean): Declare.
	* xml-tdesc.c (struct tdesc_parsing_data): Record current_feature,
	next_regnum, and current_union.
	(tdesc_start_feature, tdesc_start_reg, tdesc_start_union)
	(tdesc_end_union, tdesc_start_field, tdesc_start_vector)
	(field_attributes, union_children, reg_attributes, union_attributes)
	(vector_attributes, feature_attributes, feature_children): New.
	(target_children): Make static.  Add <feature>.
	(tdesc_elements): Make static.
	* target-descriptions.c (struct tdesc_reg, tdesc_reg_p, type_p)
	(struct tdesc_feature, tdesc_feature_p): New types.
	(struct target_desc): Add features member.
	(struct tdesc_arch_data, tdesc_data): New.
	(target_find_description): Clarify error message.  Warn about
	ignored register descriptions.
	(tdesc_has_registers, tdesc_find_feature, tdesc_feature_name)
	(tdesc_named_type, tdesc_data_init, tdesc_data_alloc)
	(tdesc_data_cleanup, tdesc_numbered_register)
	(tdesc_numbered_register_choices, tdesc_find_register)
	(tdesc_register_name, tdesc_register_type)
	(tdesc_remote_register_number, tdesc_register_reggroup_p)
	(set_tdesc_pseudo_register_name, set_tdesc_pseudo_register_type)
	(set_tdesc_pseudo_register_reggroup_p, tdesc_use_registers)
	(tdesc_free_reg, tdesc_create_reg, tdesc_free_feature)
	(tdesc_create_feature, tdesc_record_type): New.
	(free_target_description): Free features.
	(_initialize_target_descriptions): Initialize tdesc_data.
	* arch-utils.c (default_remote_register_number): New.
	* arch-utils.h (default_remote_register_number): New prototype.
	* target-descriptions.h (set_tdesc_pseudo_register_name)
	(set_tdesc_pseudo_register_type, set_tdesc_pseudo_register_reggroup_p)
	(tdesc_use_registers, tdesc_data_alloc, tdesc_data_cleanup)
	(tdesc_numbered_register, tdesc_numbered_register_choices)
	(tdesc_has_registers, tdesc_find_feature, tdesc_feature_name)
	(tdesc_named_type, tdesc_create_feature, tdesc_record_type)
	(tdesc_create_reg): Declare.
	* gdbarch.sh (remote_register_number): New entry.
	* gdbarch.c, gdbarch.h: Regenerate.
	* remote.c (init_remote_state): Use gdbarch_remote_register_number.
	* features/gdb-target.dtd: Add feature, reg, vector, union, and field.

	* arm-tdep.c (arm_register_aliases): New.
	(arm_register_name_strings): Rename to...
	(arm_register_names): ...this.  Make const.  Delete the old version.
	(current_option, arm_register_byte): Delete.
	(set_disassembly_style): Simplify.  Do not adjust arm_register_names.
	(value_of_arm_user_reg): New.
	(arm_gdbarch_init): Verify any described registers.  Call
	tdesc_use_registers.  Don't use arm_register_byte.  Create aliases
	for standard register names.
	(_initialize_arm_tdep): Do not adjust arm_register_names.
	* user-regs.c (struct user_reg): Add baton member.
	(append_user_reg, user_reg_add_builtin, user_regs_init)
	(user_reg_add, value_of_user_reg): Use a baton for user
	register functions.
	* std-regs.c: Update.
	* user-regs.h (user_reg_read_ftype, user_reg_add_builtin)
	(user_reg_add): Add baton argument.
	* NEWS: Mention target description register support.
	* features/arm-core.xml, features/arm-fpa.xml: New.
	* eval.c (evaluate_subexp_standard): Allow ptype $register
	when the program is not running.

	* gdb.texinfo (-target-disconnect): Use @smallexample.
	(Requirements): Add anchor for Expat.  Update description.
	(Target Descriptions): Mention Expat.
	(Target Description Format): Document new elements.  Use
	@smallexample.
	(Predefined Target Types, Standard Target Features): New sections.
	* doc/gdbint.texinfo (Target Descriptions): New section.

	* gdb.xml/single-reg.xml, gdb.xml/tdesc-regs.exp,
	gdb.xml/core-only.xml, gdb.xml/extra-regs.xml: New files.

3 files changed, 368 insertions, 20 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index b37890e..fd7efe0 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,13 @@
+2007-02-08  Daniel Jacobowitz  <dan@codesourcery.com>
+
+	* gdb.texinfo (-target-disconnect): Use @smallexample.
+	(Requirements): Add anchor for Expat.  Update description.
+	(Target Descriptions): Mention Expat.
+	(Target Description Format): Document new elements.  Use
+	@smallexample.
+	(Predefined Target Types, Standard Target Features): New sections.
+	* doc/gdbint.texinfo (Target Descriptions): New section.
+
 2007-02-07  Daniel Jacobowitz  <dan@codesourcery.com>
 
 	* gdb.texinfo (Target Description Format): Add section on XInclude.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 251ed9e..15c4d7e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21047,9 +21047,9 @@ The corresponding @value{GDBN} command is @samp{detach}.
 
 @subsubheading Synopsis
 
-@example
+@smallexample
  -target-disconnect
-@end example
+@end smallexample
 
 Disconnect from the remote target.  There's no output and the target is
 generally not resumed.
@@ -22222,6 +22222,7 @@ working C90 compiler, e.g.@: GCC.
 @heading Tools/packages optional for building @value{GDBN}
 @table @asis
 @item Expat
+@anchor{Expat}
 @value{GDBN} can use the Expat XML parsing library.  This library may be
 included with your operating system distribution; if it is not, you
 can get the latest version from @url{http://expat.sourceforge.net}.
@@ -22229,8 +22230,8 @@ The @code{configure} script will search for this library in several
 standard locations; if it is installed in an unusual path, you can
 use the @option{--with-libexpat-prefix} option to specify its location.
 
-Expat is used currently only used to implement some remote-specific
-features.
+Expat is used for remote protocol memory maps (@pxref{Memory map format})
+and for target descriptions (@pxref{Target Descriptions}).
 
 @end table
 
@@ -25738,9 +25739,15 @@ 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.
 
+@value{GDBN} must be compiled with Expat support to support XML target
+descriptions.  @xref{Expat}.
+
 @menu
 * Retrieving Descriptions::         How descriptions are fetched from a target.
 * Target Description Format::       The contents of a target description.
+* Predefined Target Types::         Standard types available for target
+                                    descriptions.
+* Standard Target Features::        Features @value{GDBN} knows about.
 @end menu
 
 @node Retrieving Descriptions
@@ -25787,32 +25794,35 @@ 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 provide minimal information
-about the architecture of the remote target.  @value{GDBN} can use this
-information to autoconfigure, or to warn you if you connect to an
-unsupported target.
+Target descriptions can identify the architecture of the remote target
+and (for some architectures) provide information about custom register
+sets.  @value{GDBN} can use this information to autoconfigure for your
+target, or to warn you if you connect to an unsupported target.
 
 Here is a simple target description:
 
-@example
+@smallexample
 <target>
   <architecture>i386:x86-64</architecture>
 </target>
-@end example
+@end smallexample
 
 @noindent
 This minimal description only says that the target uses
 the x86-64 architecture.
 
-A target description has the overall form:
+A target description has the following overall form, with [ ] marking
+optional elements and @dots{} marking repeatable elements.  The elements
+are explained further below.
 
-@example
+@smallexample
 <?xml version="1.0"?>
 <!DOCTYPE target SYSTEM "gdb-target.dtd">
 <target>
-  <architecture>@var{arch name}</architecture>
+  @r{[}@var{architecture}@r{]}
+  @r{[}@var{feature}@dots{}@r{]}
 </target>
-@end example
+@end smallexample
 
 @noindent
 The description is generally insensitive to whitespace and line
@@ -25821,10 +25831,6 @@ declaration and document type declaration can generally be omitted
 (@value{GDBN} does not require them), but specifying them may be
 useful for XML validation tools.
 
-The content of the @samp{<architecture>} element is an architecture
-name, from the same selection accepted by @code{set architecture}
-(@pxref{Targets, ,Specifying a Debugging Target}).
-
 @subsection Inclusion
 @cindex target descriptions, inclusion
 @cindex XInclude
@@ -25838,9 +25844,9 @@ 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:
 
-@example
+@smallexample
 <xi:include href="@var{document}"/>
-@end example
+@end smallexample
 
 @noindent
 When @value{GDBN} encounters an element of this form, it will retrieve
@@ -25852,6 +25858,208 @@ current description was read from a file, @value{GDBN} will look for
 @var{document} as a file in the same directory where it found the
 original description.
 
+@subsection Architecture
+@cindex <architecture>
+
+An @samp{<architecture>} element has this form:
+
+@smallexample
+  <architecture>@var{arch}</architecture>
+@end smallexample
+
+@var{arch} is an architecture name from the same selection
+accepted by @code{set architecture} (@pxref{Targets, ,Specifying a
+Debugging Target}).
+
+@subsection Features
+@cindex <feature>
+
+Each @samp{<feature>} 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{<feature>} element
+has this form:
+
+@smallexample
+<feature name="@var{name}">
+  @r{[}@var{type}@dots{}@r{]}
+  @var{reg}@dots{}
+</feature>
+@end smallexample
+
+@noindent
+Each feature's name should be unique within the description.  The name
+of a feature does not matter unless @value{GDBN} has some special
+knowledge of the contents of that feature; if it does, the feature
+should have its standard name.  @xref{Standard Target Features}.
+
+@subsection Types
+
+Any register's value is a collection of bits which @value{GDBN} 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 @value{GDBN} (@pxref{Predefined
+Target Types}), and the description can define additional composite types.
+
+Each type element must have an @samp{id} attribute, which gives
+a unique (within the containing @samp{<feature>}) name to the type.
+Types must be defined before they are used.
+
+@cindex <vector>
+Some targets offer vector registers, which can be treated as arrays
+of scalar elements.  These types are written as @samp{<vector>} elements,
+specifying the array element type, @var{type}, and the number of elements,
+@var{count}:
+
+@smallexample
+<vector id="@var{id}" type="@var{type}" count="@var{count}"/>
+@end smallexample
+
+@cindex <union>
+If a register's value is usefully viewed in multiple ways, define it
+with a union type containing the useful representations.  The
+@samp{<union>} element contains one or more @samp{<field>} elements,
+each of which has a @var{name} and a @var{type}:
+
+@smallexample
+<union id="@var{id}">
+  <field name="@var{name}" type="@var{type}"/>
+  @dots{}
+</union>
+@end smallexample
+
+@subsection Registers
+@cindex <reg>
+
+Each register is represented as an element with this form:
+
+@smallexample
+<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 smallexample
+
+@noindent
+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 (either in the current feature or in
+a preceeding 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} and @code{P}
+packets, and registers appear in the @code{g} and @code{G} packets
+in order of increasing register number.
+
+@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}, which is appropriate for most registers except for
+some system control registers; this is not related to the target's
+ABI.
+
+@item type
+The type of the register.  @var{type} may be a predefined type, a type
+defined in the current feature, or one of the special types @code{int}
+and @code{float}.  @code{int} is an integer type of the correct size
+for @var{bitsize}, and @code{float} is a floating point type (in the
+architecture's normal floating point format) of the correct size for
+@var{bitsize}.  The default is @code{int}.
+
+@item group
+The register group to which this register belongs.  @var{group} must
+be either @code{general}, @code{float}, or @code{vector}.  If no
+@var{group} is specified, @value{GDBN} will not display the register
+in @code{info registers}.
+
+@end table
+
+@node Predefined Target Types
+@section Predefined Target Types
+@cindex target descriptions, predefined types
+
+Type definitions in the self-description can build up composite types
+from basic building blocks, but can not define fundamental types.  Instead,
+standard identifiers are provided by @value{GDBN} for the fundamental
+types.  The currently supported types are:
+
+@table @code
+
+@item int8
+@itemx int16
+@itemx int32
+@itemx int64
+Signed integer types holding the specified number of bits.
+
+@item uint8
+@itemx uint16
+@itemx uint32
+@itemx uint64
+Unsigned integer types holding the specified number of bits.
+
+@item code_ptr
+@itemx data_ptr
+Pointers to unspecified code and data.  The program counter and
+any dedicated return address register may be marked as code
+pointers; printing a code pointer converts it into a symbolic
+address.  The stack pointer and any dedicated address registers
+may be marked as data pointers.
+
+@item arm_fpa_ext
+The 12-byte extended precision format used by ARM FPA registers.
+
+@end table
+
+@node Standard Target Features
+@section Standard Target Features
+@cindex target descriptions, standard features
+
+A target description must contain either no registers or all the
+target's registers.  If the description contains no registers, then
+@value{GDBN} will assume a default register layout, selected based on
+the architecture.  If the description contains any registers, the
+default layout will not be used; the standard registers must be
+described in the target description, in such a way that @value{GDBN}
+can recognize them.
+
+This is accomplished by giving specific names to feature elements
+which contain standard registers.  @value{GDBN} will look for features
+with those names and verify that they contain the expected registers;
+if any known feature is missing required registers, or if any required
+feature is missing, @value{GDBN} will reject the target
+description.  You can add additional registers to any of the
+standard features --- @value{GDBN} will display them just as if
+they were added to an unrecognized feature.
+
+This section lists the known features and their expected contents.
+Sample XML documents for these features are included in the
+@value{GDBN} source tree, in the directory @file{gdb/features}.
+
+Names recognized by @value{GDBN} should include the name of the
+company or organization which selected the name, and the overall
+architecture to which the feature applies; so e.g.@: the feature
+containing ARM core registers is named @samp{org.gnu.gdb.arm.core}.
+
+@subsection ARM Features
+@cindex target descriptions, ARM features
+
+The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets.
+It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
+@samp{lr}, @samp{pc}, and @samp{cpsr}.
+
+The @samp{org.gnu.gdb.arm.fpa} feature is optional.  If present, it
+should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
+
 
 @include gpl.texi
 
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index c71e1f9..e0017ad 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -80,6 +80,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
 * Language Support::
 * Host Definition::
 * Target Architecture Definition::
+* Target Descriptions::
 * Target Vector Definition::
 * Native Debugging::
 * Support Libraries::
@@ -4512,6 +4513,135 @@ The @file{tm-@var{arch}.h} can be deleted.  @file{@var{arch}.mt} and
 @file{configure.in} updated.
 
 
+@node Target Descriptions
+@chapter Target Descriptions
+@cindex target descriptions
+
+The target architecture definition (@pxref{Target Architecture Definition})
+contains @value{GDBN}'s hard-coded knowledge about an architecture.  For
+some platforms, it is handy to have more flexible knowledge about a specific
+instance of the architecture---for instance, a processor or development board.
+@dfn{Target descriptions} provide a mechanism for the user to tell @value{GDBN}
+more about what their target supports, or for the target to tell @value{GDBN}
+directly.
+
+For details on writing, automatically supplying, and manually selecting
+target descriptions, see @ref{Target Descriptions, , , gdb,
+Debugging with @value{GDBN}}.  This section will cover some related
+topics about the @value{GDBN} internals.
+
+@menu
+* Target Descriptions Implementation::
+* Adding Target Described Register Support::
+@end menu
+
+@node Target Descriptions Implementation
+@section Target Descriptions Implementation
+@cindex target descriptions, implementation
+
+Before @value{GDBN} connects to a new target, or runs a new program on
+an existing target, it discards any existing target description and
+reverts to a default gdbarch.  Then, after connecting, it looks for a
+new target description by calling @code{target_find_description}.
+
+A description may come from a user specified file (XML), the remote
+@samp{qXfer:features:read} packet (also XML), or from any custom
+@code{to_read_description} routine in the target vector.  For instance,
+the remote target supports guessing whether a MIPS target is 32-bit or
+64-bit based on the size of the @samp{g} packet.
+
+If any target description is found, @value{GDBN} creates a new gdbarch
+incorporating the description by calling @code{gdbarch_update_p}.  Any
+@samp{<architecture>} element is handled first, to determine which
+architecture's gdbarch initialization routine is called to create the
+new architecture.  Then the initialization routine is called, and has
+a chance to adjust the constructed architecture based on the contents
+of the target description.  For instance, it can recognize any
+properties set by a @code{to_read_description} routine.  Also
+see @ref{Adding Target Described Register Support}.
+
+@node Adding Target Described Register Support
+@section Adding Target Described Register Support
+@cindex target descriptions, adding register support
+
+Target descriptions can report additional registers specific to an
+instance of the target.  But it takes a little work in the architecture
+specific routines to support this.
+
+A target description must either have no registers or a complete
+set---this avoids complexity in trying to merge standard registers
+with the target defined registers.  It is the architecture's
+responsibility to validate that a description with registers has
+everything it needs.  To keep architecture code simple, the same
+mechanism is used to assign fixed internal register numbers to
+standard registers.
+
+If @code{tdesc_has_registers} returns 1, the description contains
+registers.  The architecture's @code{gdbarch_init} routine should:
+
+@itemize @bullet
+
+@item
+Call @code{tdesc_data_alloc} to allocate storage, early, before
+searching for a matching gdbarch or allocating a new one.
+
+@item
+Use @code{tdesc_find_feature} to locate standard features by name.
+
+@item
+Use @code{tdesc_numbered_register} and @code{tdesc_numbered_register_choices}
+to locate the expected registers in the standard features.
+
+@item
+Return @code{NULL} if a required feature is missing, or if any standard
+feature is missing expected registers.  This will produce a warning that
+the description was incomplete.
+
+@item
+Free the allocated data before returning, unless @code{tdesc_use_registers}
+is called.
+
+@item
+Call @code{set_gdbarch_num_regs} as usual, with a number higher than any
+fixed number passed to @code{tdesc_numbered_register}.
+
+@item
+Call @code{tdesc_use_registers} after creating a new gdbarch, before
+returning it.
+
+@end itemize
+
+After @code{tdesc_use_registers} has been called, the architecture's
+@code{register_name}, @code{register_type}, and @code{register_reggroup_p}
+routines will not be called; that information will be taken from
+the target description.  @code{num_regs} may be increased to account
+for any additional registers in the description.
+
+Pseudo-registers require some extra care:
+
+@itemize @bullet
+
+@item
+Using @code{tdesc_numbered_register} allows the architecture to give
+constant register numbers to standard architectural registers, e.g.@:
+as an @code{enum} in @file{@var{arch}-tdep.h}.  But because
+pseudo-registers are always numbered above @code{num_regs},
+which may be increased by the description, constant numbers
+can not be used for pseudos.  They must be numbered relative to
+@code{num_regs} instead.
+
+@item
+The description will not describe pseudo-registers, so the
+architecture must call @code{set_tdesc_pseudo_register_name},
+@code{set_tdesc_pseudo_register_type}, and
+@code{set_tdesc_pseudo_register_reggroup_p} to supply routines
+describing pseudo registers.  These routines will be passed
+internal register numbers, so the same routines used for the
+gdbarch equivalents are usually suitable.
+
+@end itemize
+
+
 @node Target Vector Definition
 
 @chapter Target Vector Definition