This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
[rfa:doco] Update *CONVERT* documentation
- From: Andrew Cagney <ac131313 at redhat dot com>
- To: gdb-patches at sources dot redhat dot com
- Date: Fri, 13 Jun 2003 15:11:37 -0400
- Subject: [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