Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney <cagney at gnu dot org>]

>   Also, 9.5 and 9.6 are both prefixed with disclaimers; 9.5 says "This
> section is pretty much obsolete. The functionality described here has
> largely been replaced by pseudo-registers and the mechanisms described [...
> in 9.6 ...] " and refers the reader to 9.6, which says "The way GDB
> manipulates registers is undergoing significant change.  Many of the macros
> and functions refered to in this section are likely to be subject to further
> revision.".  The combined effect of these two sections is to leave the
> reader (well, this one, at any rate) with no idea how you're supposed to
> manipulate registers (or indeed, what a pseudo-register even is, since the
> term is not used nor defined anywhere else in the documentation).  And I
> didn't find that browsing the comments in regcache.h makes up for that.

Like the below?

http://sources.redhat.com/ml/gdb/2002-07/msg00202.html
@node Registers
@chapter Registers

@section Register Spaces

@value{GDBN} internally has two register spaces:

@table @emph
@item cooked
@itemize @bullet
@item
manipulated by core @value{GDBN}
@item
correspond to user level, or abi registers
@end itemize
@item raw
@itemize @bullet
@item
manipulated by target backends
@item
correspond to physical registers
@end itemize
@end table

@subsection Raw Registers

The raw register space, containing @code{NUM_REGS}
@c index NUM_REGS
raw registers, abstracts the instruction set architectures physical
register set. @value{GDBN}'s register cache contains raw registers.
Each raw register is mapped, one-to-one, onto a corresponding physical
register. For instance:

@itemize @bullet

@item
For 64 bit architecture that has 32 general purpose registers, the
register cache, and the raw register space would include space for those
32 registers.

@item
For an architectures that has register banks, the register cache, and
raw register space would contain space for registers from all banks.
The one-to-one relationship between the raw registers and the
architecture's physical registers being preserved.

@item
For a 64 bit architecture that is running in 32 bit mode, the register
cache and raw register space would contain the 64 bit hardware
registers. The raw register space would not include cut down 32 bit
registers.

@item
For an architecture that determines the program-counter by examining the
value of severaal hardware registers, the register cache and raw
register space will contain the separate hardware values. The raw
register space would not include the program-counter.

@item
For an architecture that has memory mapped registers, those registers
are not be part of the register cache or raw register space (there is no
corresponding hardware register).

@end itemize

@emph{Maintainer note: Old architectures, since they didn't know better,
broke all of the above rules, sigh!}

The raw registers are not necessarily directly visible to the user.

@emph{Maintainer note: There should be be a @samp{maint info registers}
command so that the raw register cache is visible.}

@section Cooked Registers

The core of @value{GDBN} manipulates registers in the cooked register
space. Any external or user visible register is mapped onto the cooked
register space, in particular:

@itemize @bullet
@item
registers refered to by debug information
@item
user visible registers (specified by name)
@item
mode dependant registers (e.g., a 64 bit architecture in 32 bit mode may
need to manipulate the 32 bits of 64 bit registers)
@item
memory mapped registers
space.
@item
state dependant registers (e.g., bank registers)
@end itemize

Architecture methods then map the @code{NUM_REGS + NUM_PSEUDO_REGS}
cooked registers onto raw registers or memory. While arbitrary mappings
are possible, the first @code{NUM_REGS} registers should be be mapped
direct to the raw registers. The remaining @code{NUM_PSEUDO_REGS then
having more arbitrary mappings. That is:

@smallexample
cooked: [0..NUM_REGS) [..NUM_REGS+NUM_PSEUDO_REGS)
| / |
| / |
| / |
| / |
raw: RAW REGISTERS MEMORY
@end smallexample

@section The Register Cache

@value{GDBN} stores the target register state in a register cache
(@code{struct regcache}).

The register cache has three separate interfaces:

@itemize @bullet
@item
cooked
@item
raw
@item
target
@end itemize

Core @value{GDBN} manipulates the register cache using the cooked
interfaces:

@deftypefun void regcache_cooked_read (struct regcache *@var{regcache}, 
int @var{regnum}, void *@var{buf})
Read a cooked register value from the register cache (or memory).
@end deftypefun
@deftypefun void regcache_cooked_write (struct regcache *@var{regcache}, 
int @var{regnum}, const void *@var{buf})
Write a cooked register value to the register cache (or memory).
@end deftypefun

These methods then use corresponding architecture methods to map the
cooked registers onto either raw registers or memory:

@deftypefun void gdbarch_cooked_register_read (struct gdbarch 
*@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, void 
*@var{buf})
Read the specified @var{regnum} register value from the @var{regcache}
(or memory for memory mapped registers).
@end deftypefun
@deftypefun void gdbarch_cooked_register_write (struct gdbarch 
*@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const 
void *@var{buf})
Write the specified @var{regnum} register value into the @var{regcache}
(or memory for memory mapped registers).
@end deftypefun

The raw register values being manipulated using:

@deftypefun void regcache_raw_read (struct regcache *@var{regcache}, int 
@var{regnum}, void *@var{buf})
Read a cooked register value from the register cache (or memory).
@end deftypefun
@deftypefun void regcache_raw_write (struct regcache *@var{regcache}, 
int @var{regnum}, const void *@var{buf})
Write a raw register value to the register cache (or memory).
@end deftypefun

When a raw register read or write needs to go through to the target (the
value isn't yet in the cache or a modification needs to be written to
the target) the register cache state is then manipulated by the target
using the methods:

@deftypefun regcache_collect (struct regcache *@var{regcache}, int 
@var{regnum}, void *@var{buf})
@end deftypefun
@deftypefun regcache_supply (struct regcache *@var{regcache}, int 
@var{regnum}, const void *@var{buf})
@end deftypefun