2003-06-13 Andrew Cagney * 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