This is the mail archive of the gdb-patches@sources.redhat.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[rfa:doco] Update *CONVERT* documentation


Hello,

Attached is a patch to update anything to do with *CONVERT* or *TYPE* so that it [hopefully] reflects current reality.

- any thing deprecated is documented as such (and cross referenced to the replacement)
- the old Raw and Virtual chapter is deleted (it's no longer relevant)
- the new methods are updated to match my most recent patch


ok?
Andrew
2003-06-13  Andrew Cagney  <cagney@redhat.com>

	* gdbint.texinfo (Target Architecture Definition): Delete section
	"Raw and Virtual Register Representations".  Revise section "Using
	Different Register and Memory Data Representations".  Delete
	references to REGISTER_CONVERT_TO_TYPE and
	REGISTER_CONVERT_FROM_TYPE.  Deprecate REGISTER_RAW_SIZE,
	REGISTER_CONVERTIBLE, REGISTER_CONVERT_TO_VIRTUAL,
	REGISTER_CONVERT_TO_RAW, REGISTER_VIRTUAL_SIZE, and
	REGISTER_VIRTUAL_TYPE adding cross references to register_type.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.150
diff -u -r1.150 gdbint.texinfo
--- gdbint.texinfo	9 Jun 2003 02:10:35 -0000	1.150
+++ gdbint.texinfo	13 Jun 2003 19:06:06 -0000
@@ -2709,114 +2709,6 @@
 @end smallexample
 
 
-@section Raw and Virtual Register Representations
-@cindex raw register representation
-@cindex virtual register representation
-@cindex representations, raw and virtual registers
-
-@emph{Maintainer note: This section is pretty much obsolete.  The
-functionality described here has largely been replaced by
-pseudo-registers and the mechanisms described in @ref{Target
-Architecture Definition, , Using Different Register and Memory Data
-Representations}.  See also @uref{http://www.gnu.org/software/gdb/bugs/,
-Bug Tracking Database} and
-@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more
-up-to-date information.}
-
-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 @value{GDBN}'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 @value{GDBN} @code{struct value} objects.
-
-@emph{Maintainer note: Notice that the same mechanism is being used to
-both convert a register to a @code{struct value} and alternative
-register forms.}
-
-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 @code{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 @value{GDBN} as 64-bit
-registers, with garbage in their upper bits.  @value{GDBN} 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
-@value{GDBN}'s interface to the architecture, while the virtual representation
-can be chosen for @value{GDBN}'s convenience.  @value{GDBN}'s register file,
-@code{registers}, holds the register contents in raw format, and the
-@value{GDBN} remote protocol transmits register values in raw format.
-
-Your architecture may define the following macros to request
-conversions between the raw and virtual format:
-
-@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.
-
-You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
-unless this macro returns a non-zero value for that register.
-@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 @value{GDBN}
-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, @value{GDBN}
-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 @code{REGISTER_CONVERT_TO_VIRTUAL} and
-@code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
-arguments in different orders.
-
-You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
-for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
-value.
-@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 Using Different Register and Memory Data Representations
 @cindex register representation
 @cindex memory representation
@@ -2824,13 +2716,6 @@
 @cindex register data formats, converting
 @cindex @code{struct value}, converting register contents to
 
-@emph{Maintainer's note: 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.  See
-@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and
-@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for
-further information.  cagney/2002-05-06.}
-
 Some architectures can represent a data object in a register using a
 form that is different to the objects more normal memory representation.
 For example:
@@ -2859,40 +2744,31 @@
 following macros to request conversions between the register and memory
 representations of a data type:
 
-@deftypefn {Target Macro} int CONVERT_REGISTER_P (int @var{reg})
-Return non-zero if the representation of a data value stored in this
-register may be different to the representation of that same data value
-when stored in memory.
+@deftypefn {Target Macro} int CONVERT_REGISTER_P (int @var{regnum}, struct type *@var{type})
+Return non-zero if the representation of a @var{type} data value stored
+in registers starting with @var{regnum} is different to the
+representation of that same data value when stored in memory.
 
 When non-zero, the macros @code{REGISTER_TO_VALUE} and
 @code{VALUE_TO_REGISTER} are used to perform any necessary conversion.
 @end deftypefn
 
-@deftypefn {Target Macro} void REGISTER_TO_VALUE (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
-Convert the value of register number @var{reg} to a data object of type
-@var{type}.  The buffer at @var{from} holds the register's value in raw
-format; the converted value should be placed in the buffer at @var{to}.
-
-Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take
-their @var{reg} and @var{type} arguments in different orders.
+@deftypefn {Target Macro} void REGISTER_TO_VALUE (struct frame_info *@var{frame}, int @var{regnum}, struct type *@var{type}, void *@var{to})
+Convert the contents of @var{frame}'s registers, starting with
+@var{regnum}, to a data object of type @var{type}.  The converted value
+is stored in the buffer at @var{to}.
 
-You should only use @code{REGISTER_TO_VALUE} with registers for which
-the @code{CONVERT_REGISTER_P} macro returns a non-zero value.
+@code{REGISTER_TO_VALUE} should only be used with registers for which
+@code{CONVERT_REGISTER_P} returns a non-zero value.
 @end deftypefn
 
-@deftypefn {Target Macro} void VALUE_TO_REGISTER (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
-Convert a data value of type @var{type} to register number @var{reg}'
-raw format.
+@deftypefn {Target Macro} void VALUE_TO_REGISTER (struct frame_info *@var{frame}, int @var{regnum}, const void *@var{from})
+Convert the contents of the buffer at @var{from} into @var{frame}'s
+register representation.  The converted value is stored in @var{frame}'s
+registers starting with @var{regnum}.
 
-Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take
-their @var{reg} and @var{type} arguments in different orders.
-
-You should only use @code{VALUE_TO_REGISTER} with registers for which
-the @code{CONVERT_REGISTER_P} macro returns a non-zero value.
-@end deftypefn
-
-@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf})
-See @file{mips-tdep.c}.  It does not do what you want.
+@code{VALUE_TO_REGISTER} should only be used with registers for which
+@code{CONVERT_REGISTER_P} returns a non-zero value.
 @end deftypefn
 
 
@@ -3485,22 +3361,22 @@
 address the pointer refers to.
 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
 
-@item REGISTER_CONVERTIBLE (@var{reg})
-@findex REGISTER_CONVERTIBLE
-Return non-zero if @var{reg} uses different raw and virtual formats.
-@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+@item DEPRECATED_REGISTER_CONVERTIBLE (@var{reg})
+@findex DEPRECATED_REGISTER_CONVERTIBLE
+Return non-zero if @var{reg} is represnted using different raw and
+virtual types.  This method is no longer needed, a register has only one
+type
 
-@item REGISTER_TO_VALUE(@var{regnum}, @var{type}, @var{from}, @var{to})
+@item REGISTER_TO_VALUE(@var{frame}, @var{regnum}, @var{type}, @var{to})
 @findex REGISTER_TO_VALUE
 Convert the raw contents of register @var{regnum} into a value of type
-@var{type}.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@var{type}.  @xref{Target Architecture Definition, , Using Different
+Register and Memory Data Representations}.
 
-@item REGISTER_RAW_SIZE (@var{reg})
-@findex REGISTER_RAW_SIZE
-Return the raw size of @var{reg}; defaults to the size of the register's
-virtual type.
-@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+@item DEPRECATED_REGISTER_RAW_SIZE (@var{reg})
+@findex DEPRECATED_REGISTER_RAW_SIZE
+Return the raw size of @var{reg}.  This is no longer needed, the
+register's size is now computed from its type.  @xref{register_type}.
 
 @item register_reggroup_p (@var{gdbarch}, @var{regnum}, @var{reggroup})
 @findex register_reggroup_p
@@ -3524,35 +3400,32 @@
 Any register with a valid name.
 @end table
 
-@item REGISTER_VIRTUAL_SIZE (@var{reg})
-@findex REGISTER_VIRTUAL_SIZE
-Return the virtual size of @var{reg}; defaults to the size of the
-register's virtual type.
-Return the virtual size of @var{reg}.
-@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
-
-@item REGISTER_VIRTUAL_TYPE (@var{reg})
-@findex REGISTER_VIRTUAL_TYPE
-Return the virtual type of @var{reg}.
-@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg})
+@findex DEPRECATED_REGISTER_VIRTUAL_SIZE
+Return the virtual size of @var{reg}.  This is no longer needed, a
+register's size is computed from its type.  @xref{register_type}.
+
+@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})
+@findex DEPRECATED_REGISTER_VIRTUAL_TYPE
+Return the virtual type of @var{reg}.  @xref{register_type}, for the
+replacement.
 
-@item struct type *register_type (@var{gdbarch}, @var{reg})
+@item struct type *register_type (@var{gdbarch}, @var{regnum})
 @findex register_type
-If defined, return the type of register @var{reg}.  This function
-superseeds @code{REGISTER_VIRTUAL_TYPE}.  @xref{Target Architecture
-Definition, , Raw and Virtual Register Representations}.
+@anchor{register_type} eturns the type that represents the register
+@var{regnum}.  This function superseeds @code{REGISTER_VIRTUAL_TYPE}.
 
-@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
-@findex REGISTER_CONVERT_TO_VIRTUAL
+@item DEPRECATED_REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
+@findex DEPRECATED_REGISTER_CONVERT_TO_VIRTUAL
 Convert the value of register @var{reg} from its raw form to its virtual
-form.
-@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+form.  This method is no longer needed, registers have only one type.
+@xref{register_type}.
 
-@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
-@findex REGISTER_CONVERT_TO_RAW
+@item DEPRECATED_REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
+@findex DEPRECATED_REGISTER_CONVERT_TO_RAW
 Convert the value of register @var{reg} from its virtual form to its raw
-form.
-@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+form.  This method is no longer needed, registers have only one type.
+@xref{register_type}.
 
 @item RETURN_VALUE_ON_STACK(@var{type})
 @findex RETURN_VALUE_ON_STACK
@@ -3956,11 +3829,11 @@
 for systems where GCC is known to use different calling convention than
 other compilers.
 
-@item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to})
+@item VALUE_TO_REGISTER(@var{frame}, @var{regnum}, @var{type}, @var{from})
 @findex VALUE_TO_REGISTER
 Convert a value of type @var{type} into the raw contents of register
-@var{regnum}'s.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@var{regnum}'s.  @xref{Target Architecture Definition, , Using Different
+Register and Memory Data Representations}.
 
 @item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
 @findex VARIABLES_INSIDE_BLOCK

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]