2.3.5. Specifying the Register Architecture

GDB considers registers to be a set with members numbered linearly from 0 upwards. The first part of that set corresponds to real physical registers, the second part to any "pseudo-registers". Pseudo-registers have no independent physical existence, but are useful representations of information within the architecture. For example the OpenRISC 1000 architecture has up to 32 general purpose registers, which are typically represented as 32-bit (or 64-bit) integers. However it could be convenient to define a set of pseudo-registers, to show the GPRs represented as floating point registers.

For any architecture, the implementer will decide on a mapping from hardware to GDB register numbers. The registers corresponding to real hardware are referred to as raw registers, the remaining registers are pseudo-registers. The total register set (raw and pseudo) is called the cooked register set.

2.3.5.1. struct gdbarch Functions Specifying the Register Architecture

These functions specify the number and type of registers in the architecture.

read_pc and write_pc. Functions to read the program counter. The default value is NULL (no function available). However, if the program counter is just an ordinary register, it can be specified in struct gdbarch instead (see pc_regnum below) and it will be read or written using the standard routines to access registers. Thus this function need only be specified if the program counter is not an ordinary register.
pseudo_register_read and pseudo_register_write. These functions should be defined if there are any pseudo-registers (see Section 2.2.2 and Section 2.3.5.3 for more information on pseudo-registers). The default value is NULL.
num_regs and num_pseudo_regs. These define the number of real and pseudo-registers. They default to -1 (undefined) and should always be explicitly defined.
sp_regnum, pc_regnum, ps_regnum and fp0_regnum. These specify the register holding the stack pointer, program counter, processor status and first floating point register. All except the first floating-point register (which defaults to 0) default to -1 (not defined). They may be real or pseudo-registers. sp_regnum must always be defined. If pc_regnum is not defined, then the functions read_pc and write_pc (see above) must be defined. If ps_regnum is not defined, then the $ps variable will not be available to the GDB user. fp0_regnum is not needed unless the target offers support for floating point.

2.3.5.2. struct gdbarch Functions Giving Register Information

These functions return information about registers.

register_name. This function should convert a register number (raw or pseudo) to a register name (as a C char *). This is used both to determine the name of a register for output and to work out the meaning of any register names used as input. For example with the OpenRISC 1000, GDB registers 0-31 are the General Purpose Registers, register 32 is the program counter and register 33 is the supervision register, which map to the strings "gpr00" through "gpr31", "pc" and "sr" respectively. This means that the GDB command print $gpr5 should print the value of the OR1K general purpose register 5. The default value for this function is NULL. It should always be defined.
Historically, GDB always had a concept of a frame pointer register, which could be accessed via the GDB variable, $fp. That concept is now deprecated, recognizing that not all architectures have a frame pointer. However if an architecture does have a frame pointer register, and defines a register or pseudo-register with the name "fp", then that register will be used as the value of the $fp variable.
register_type. Given a register number, this function identifies the type of data it may be holding, specified as a struct type. GDB allows creation of arbitrary types, but a number of built in types are provided (builtin_type_void, builtin_type_int32 etc), together with functions to derive types from these. Typically the program counter will have a type of "pointer to function" (it points to code), the frame pointer and stack pointer will have types of "pointer to void" (they point to data on the stack) and all other integer registers will have a type of 32-bit integer or 64-bit integer. This information guides the formatting when displaying out register information. The default value is NULL meaning no information is available to guide formatting when displaying registers.
print_registers_info. Define this function to print out one or all of the registers for the GDB info registers command. The default value is the function default_print_registers_info which uses the type information (see register_type above) to determine how each register should be printed. Define this function for fuller control over how the registers are displayed.
print_float_info and print_vector_info. Define this function to provide output for the GDB info float and info vector commands respectively. The default value is NULL (not defined), meaning no information will be provided. Define each function if the target supports floating point or vector operations respectively.
register_reggroup_p. GDB groups registers into different categories (general, vector, floating point etc). This function given a register and group returns 1 (true) if the register is in the group and 0 otherwise. The default value is the function default_register_reggroup_p which will do a reasonable job based on the type of the register (see the function register_type above), with groups for general purpose registers, floating point registers, vector registers and raw (i.e not pseudo) registers.

2.3.5.3. Register Caching

Caching of registers is used, so that the target does not need to be accessed and reanalyzed multiple times for each register in circumstances where the register value cannot have changed.

GDB provides struct regcache, associated with a particular struct gdbarch to hold the cached values of the raw registers. A set of functions is provided to access both the raw registers (with raw in their name) and the full set of cooked registers (with cooked in their name). Functions are provided to ensure the register cache is kept synchronized with the values of the actual registers in the target.

Accessing registers through the struct regcache routines will ensure that the appropriate struct gdbarch functions are called when necessary to access the underlying target architecture. In general users should use the "cooked" functions, since these will map to the "raw" functions automatically as appropriate.

The two key functions are regcache_cooked_read and regcache_cooked_write which read or write a register to or from a byte buffer (type gdb_byte *). For convenience the wrapper functions regcache_cooked_read_signed, regcache_cooked_read_unsigned, regcache_cooked_write_signed and regcache_cooked_write_unsigned are provided, which read or write the value and convert to or from a value as appropriate.