From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 1431 invoked by alias); 20 Jul 2002 00:31:40 -0000 Mailing-List: contact gdb-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sources.redhat.com Received: (qmail 1424 invoked from network); 20 Jul 2002 00:31:38 -0000 Received: from unknown (HELO localhost.redhat.com) (216.138.202.10) by sources.redhat.com with SMTP; 20 Jul 2002 00:31:38 -0000 Received: from ges.redhat.com (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id 48A1B3DE1 for ; Fri, 19 Jul 2002 20:31:37 -0400 (EDT) Message-ID: <3D38AF69.7020902@ges.redhat.com> Date: Fri, 19 Jul 2002 17:31:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-US; rv:1.0.0) Gecko/20020708 X-Accept-Language: en-us, en MIME-Version: 1.0 To: gdb@sources.redhat.com Subject: WIP: Register doco Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-SW-Source: 2002-07/txt/msg00202.txt.bz2 Hello, Below is just the starting of a chapter describing GDB's registers and the register cache. I've not even shown it to makeinfo (so for the moment I'd ignore texinfo errors :-). I'm interested in comments and even suggestions for things that need to be expanded. Andrew @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