RFA: document raw/virtual stuff

Jim Blandy jimb@zwingli.cygnus.com
Wed Apr 5 12:58:00 GMT 2000


> I think this isn't right for the reasons mentioned in my other mail.
> Different target and host data representions aren't the issue here.

Yes, it's different memory and register representations.  Thanks for
clarifying that.  Here's a revised patch.

2000-04-05  Jim Blandy  <jimb@redhat.com>

	* gdbint.texinfo (Using Different Register and Memory Data
	Representations): New section.
	(REGISTER_CONVERTIBLE, REGISTER_RAW_SIZE, REGISTER_VIRTUAL_SIZE,
 	REGISTER_VIRTUAL_TYPE, REGISTER_CONVERT_TO_VIRTUAL,
 	REGISTER_CONVERT_TO_RAW): Document.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.4
diff -c -c -b -F'^(' -r1.4 gdbint.texinfo
*** gdbint.texinfo	2000/03/23 23:50:51	1.4
--- gdbint.texinfo	2000/04/05 19:56:42
***************
*** 1153,1158 ****
--- 1153,1244 ----
  
  GDB can handle big-endian, little-endian, and bi-endian architectures.
  
+ @section Using Different Register and Memory Data Representations
+ 
+ Some architectures use one representation for a value when it lives in a
+ register, but use a different representation when it lives in memory.
+ In GDB's terminology, the @dfn{raw} representation is the one used in
+ the target registers, and the @dfn{virtual} representation is the one
+ used in memory, and within GDB @code{struct value} objects.
+ 
+ For almost all data types on almost all architectures, the virtual and
+ raw representations are identical, and no special handling is needed.
+ However, they do occasionally differ.  For example:
+ 
+ @itemize @bullet
+ 
+ @item
+ The x86 architecture supports an 80-bit long double type.  However, when
+ we store those values in memory, they occupy twelve bytes: the
+ floating-point number occupies the first ten, and the final two bytes
+ are unused.  This keeps the values aligned on four-byte boundaries,
+ allowing more efficient access.  Thus, the x86 80-bit floating-point
+ type is the raw representation, and the twelve-byte loosely-packed
+ arrangement is the virtual representation.
+ 
+ @item
+ Some 64-bit MIPS targets present 32-bit registers to GDB as 64-bit
+ registers, with garbage in their upper bits.  GDB ignores the top 32
+ bits.  Thus, the 64-bit form, with garbage in the upper 32 bits, is the
+ raw representation, and the trimmed 32-bit representation is the
+ virtual representation.
+ 
+ @end itemize
+ 
+ In general, the raw representation is determined by the architecture, or
+ GDB's interface to the architecture, while the virtual representation
+ can be chosen for GDB's convenience.  GDB's register file,
+ @code{registers}, holds the register contents in raw format, and the GDB
+ remote protocol transmits register values in raw format.
+ 
+ Your architecture may define the following macros to request raw /
+ virtual conversions:
+ 
+ @deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
+ Return non-zero if register number @var{reg}'s value needs different raw
+ and virtual formats.
+ @end deftypefn
+ 
+ @deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg})
+ The size of register number @var{reg}'s raw value.  This is the number
+ of bytes the register will occupy in @code{registers}, or in a GDB
+ remote protocol packet.
+ @end deftypefn
+ 
+ @deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg})
+ The size of register number @var{reg}'s value, in its virtual format.
+ This is the size a @code{struct value}'s buffer will have, holding that
+ register's value.
+ @end deftypefn
+ 
+ @deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg})
+ This is the type of the virtual representation of register number
+ @var{reg}.  Note that there is no need for a macro giving a type for the
+ register's raw form; once the register's value has been obtained, GDB
+ always uses the virtual form.
+ @end deftypefn
+ 
+ @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
+ Convert the value of register number @var{reg} to @var{type}, which
+ should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}.  The buffer
+ at @var{from} holds the register's value in raw format; the macro should
+ convert the value to virtual format, and place it at @var{to}.
+ 
+ Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
+ their @var{reg} and @var{type} arguments in different orders.
+ @end deftypefn
+ 
+ @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
+ Convert the value of register number @var{reg} to @var{type}, which
+ should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}.  The buffer
+ at @var{from} holds the register's value in raw format; the macro should
+ convert the value to virtual format, and place it at @var{to}.
+ 
+ Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
+ their @var{reg} and @var{type} arguments in different orders.
+ @end deftypefn
+ 
+ 
  @section Frame Interpretation
  
  @section Inferior Call Setup
***************
*** 1583,1588 ****
--- 1669,1698 ----
  
  @item NO_HIF_SUPPORT
  (Specific to the a29k.)
+ 
+ @item REGISTER_CONVERTIBLE (@var{reg})
+ Return non-zero if @var{reg} uses different raw and virtual formats.
+ @xref{Using Different Target and Host Data Representations}.
+ 
+ @item REGISTER_RAW_SIZE (@var{reg})
+ Return the raw size of @var{reg}.
+ @xref{Using Different Target and Host Data Representations}.
+ 
+ @item REGISTER_VIRTUAL_SIZE (@var{reg})
+ Return the virtual size of @var{reg}.
+ @xref{Using Different Target and Host Data Representations}.
+ 
+ @item REGISTER_VIRTUAL_TYPE (@var{reg})
+ Return the virtual type of @var{reg}.
+ @xref{Using Different Target and Host Data Representations}.
+ 
+ @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
+ Convert the value of register @var{reg} from its raw form to its virtual
+ form.  @xref{Using Different Target and Host Data Representations}.
+ 
+ @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
+ Convert the value of register @var{reg} from its virtual form to its raw
+ form.  @xref{Using Different Target and Host Data Representations}.
  
  @item SOFTWARE_SINGLE_STEP_P
  Define this as 1 if the target does not have a hardware single-step


More information about the Gdb-patches mailing list