Adding target described 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. The relevant functions are described in target-descriptions.h.
There is a level of indirection in the target description mechanism. The server specifies numbers to be used for registers (explicitly or implicitly) in its XML description. The GDB client also specifies numbers to be used to refer to individual registers. The calls to tdesc_numbered_register then serve to map the two numberings together, connecting them via the name of the register. GDB client register numbers are thereafter automatically mapped to server XML register numbers.
Note. For a new architecture it would be convenient to just accept the numbering used by the server and use arch_dwarf2_reg_to_regnum to map to register numbers in DWARF debug information. However the target description mechanism currently offers no such introspection functionality.
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 tdesc_has_registers returns 1, the description contains registers. The architecture's gdbarch_init routine should:
Call tdesc_data_alloc to allocate storage, early, before searching for a matching gdbarch or allocating a new one.
Use tdesc_find_feature to locate standard features by name.
Use tdesc_numbered_register and tdesc_numbered_register_choices to locate the expected registers in the standard features.
Return 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.
Free the allocated data before returning, unless tdesc_use_registers is called.
Call set_gdbarch_num_regs as usual, with a number higher than any fixed number passed to tdesc_numbered_register.
Call tdesc_use_registers after creating a new gdbarch, before returning it.
After tdesc_use_registers has been called, the architecture's register_name, register_type, and register_reggroup_p routines will not be called; that information will be taken from the target description. num_regs may be increased to account for any additional registers in the description.
Pseudo-registers require some extra care:
Using tdesc_numbered_register allows the architecture to give constant register numbers to standard architectural registers, e.g. as an enum in arch-tdep.h. But because pseudo-registers are always numbered above num_regs, which may be increased by the description, constant numbers can not be used for pseudos. They must be numbered relative to num_regs instead.
The description will not describe pseudo-registers, so the architecture must call set_tdesc_pseudo_register_name, set_tdesc_pseudo_register_type, and 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.
There is a side-effect of this if a key register (such as PC or SP) is a pseudo-register. It may be necessary to call some architecture definition functions, such as set_gdbarch_pc_regnum and set_gdbarch_sp_regnum after tdesc_use_registers, since only then will the numbering of pseudo-registers be known.
To get GDB to request remote targets to send target descriptions for an architecture, the architecture initialization function __initialize_arch_tdep () should call register_remote_support_xml ("arch") as described in remote.h. This will cause xmlRegisters to be added to the qSupported packet sent to the target.
The need for a default target description
It is tempting to always rely on the remote target providing the register description. However at startup, GDB will not be connected to a target, so will need some default way of describing registers. There are three ways to do this.
Only use the functions in target-descriptions.h if the architecture has a target description with registers (i.e. tdesc_has_registers () returns true. Otherwise set data to default values. The downside of this is that the tdesc functions to type and name registers are not usable.
Manually create a default target description in C, using allocate_target_description (), set_tdesc_architecture (), tdesc_create_feature (), tdesc_create_reg () etc. This allows all the target description functions to be used, as though a remote target had sent all the details, but is a little tedious.
Create and XML target description and use the GDB tools to automatically generate a C function creating a target description structure. The XML file should be created in the GDB features subdirectory with the name arch.xml. Running make will then create .c and .h files, as well as a register format file in the GDB regformats subdirectory. The details of how to do this are in comments at the top of the Makefile in the features subdirectory. This does require xsltproc to be installed and an implementation of GDB built for all-targets.