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

1 files changed, 131 insertions, 1 deletions

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index e96e2f17ec6..e9fcd0dda98 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -39,7 +39,7 @@ Free Documentation License''.
 @page
 @tex
 \def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
-\xdef\manvers{\$Revision: 1.252 $}  % For use in headers, footers too
+\xdef\manvers{\$Revision: 1.253 $}  % For use in headers, footers too
 {\parskip=0pt
 \hfill Cygnus Solutions\par
 \hfill \manvers\par
@@ -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