RFA: document raw/virtual stuff

[Jim Blandy <jimb at zwingli dot cygnus dot com>]

Please check for accuracy and clarity.

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

	* gdbint.texinfo (Using Different Target and Host 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/04 21:46:54
***************
*** 1153,1158 ****
--- 1153,1256 ----
  
  GDB can handle big-endian, little-endian, and bi-endian architectures.
  
+ @section Using Different Target and Host Data Representations
+ 
+ When cross-debugging, it is sometimes necessary for GDB to use an
+ internal representation for some values which is different from the
+ representation used on the target.  For certain types, the format used
+ in a @code{struct value} object may differ from the value's format on
+ the target.
+ 
+ In GDB's terminology, the @dfn{raw} representation is the one used on
+ the target, and the @dfn{virtual} representation is the one used 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 floating-point type.  If we're
+ running GDB on a host that doesn't support 80-bit floats, we will
+ convert those values to the largest floating-point type available on the
+ host.  Thus, the x86 80-bit floating-point type is the @dfn{raw}
+ representation, and the host's largest floating-point type is the
+ @dfn{virtual} representation.  (This is not a great example; GDB ought
+ to emulate the target's floating-point arithmetic in software, rather
+ than performing a possibly lossy conversion to a host floating-point
+ type.)
+ 
+ @item
+ The D10V architecture has 16-bit addresses, and separate code and data
+ address spaces.  The raw representation is thus a straight 16-bit value.
+ GDB's virtual representation for D10V pointers is actually 32 bits long,
+ and uses the upper bits to indicate whether the pointer refers to code
+ space or data space.  These extra upper bits allow GDB to correctly
+ dereference pointers of either type.
+ 
+ @end itemize
+ 
+ In general, the raw representation is determined by 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.  
+ 
+ At present, GDB can only convert between raw and virtual formats when
+ reading and writing machine registers.  GDB is unable to operate on
+ values that appear in memory in raw format, when the raw format is not
+ identical to the virtual format.  There's no particular reason to
+ restrict conversions to register values; it's just a quirk of history.
+ 
+ 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 the register's
+ raw type; types only matter for @code{struct value} objects, so they
+ only apply to virtual representations.
+ @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 ****
--- 1681,1710 ----
  
  @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