OpenE2K/gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[Ada] Update internal documentation of debugging information

Browse Source 
gcc/ada/

	* exp_dbug.ads: Update documentation of various items.
This commit is contained in:
Eric Botcazou 2021-06-08 13:24:46 +02:00 committed by Pierre-Marie de Rodat
parent 81956c08f7
commit d80c733187
1 changed files with 191 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

409
gcc/ada/exp_dbug.ads
View File

@ -23,9 +23,11 @@
-- --
------------------------------------------------------------------------------
-- Expand routines for generation of special declarations used by the
-- debugger. In accordance with the Dwarf 2.2 specification, certain
-- type names are encoded to provide information to the debugger.
-- Expand routines for the generation of special declarations used by the
-- debugger. In accordance with the DWARF specification, certain type names
-- may also be encoded to provide additional information to the debugger, but
-- this practice is being deprecated and some encodings described below are no
-- longer generated by default (they are marked OBSOLETE).
with Namet; use Namet;
with Types; use Types;
@ -496,53 +498,104 @@ package Exp_Dbug is
-- corresponding positive value followed by a lower case m for minus to
-- indicate that the value is negative (e.g. 2m for -2).
-------------------------
-- Type Name Encodings --
-------------------------
------------------------
-- Encapsulated Types --
------------------------
-- In some cases, the compiler may encapsulate a type by wrapping it in a
-- record. For example, this is used when a size or alignment specification
-- requires a larger type. Consider:
-- type x is mod 2 ** 64;
-- for x'size use 256;
-- In this case, the compiler generates a record type x___PAD, which has
-- a single field whose name is F. This single field is 64-bit long and
-- contains the actual value. This kind of padding is used when the logical
-- value to be stored is shorter than the object in which it is allocated.
-- A similar encapsulation is done for some packed array types, in which
-- case the record type is x___JM and the field name is OBJECT. This is
-- used in the case of a packed array stored using modular representation
-- (see the section on representation of packed array objects). In this
-- case the wrapping is used to achieve correct positioning of the packed
-- array value (left/right justified in its field depending on endianness).
-- When the debugger sees an object of a type whose name has a suffix of
-- ___PAD or ___JM, the type will be a record containing a single field,
-- and the name of that field will be all upper case. In this case, it
-- should look inside to get the value of the inner field, and neither
-- the outer structure name, nor the field name should appear when the
-- value is printed.
-- Similarly, when the debugger sees a record named REP being the type of
-- a field inside another record type, it should treat the fields inside
-- REP as being part of the outer record (this REP field is only present
-- for code generation purposes). The REP record should not appear in the
-- values printed by the debugger.
--------------------
-- Implicit Types --
--------------------
-- The compiler creates implicit type names in many situations where a
-- type is present semantically, but no specific name is present. For
-- example:
-- S : Integer range M .. N;
-- Here the subtype of S is not integer, but rather an anonymous subtype
-- of Integer. Where possible, the compiler generates names for such
-- anonymous types that are related to the type from which the subtype
-- is obtained as follows:
-- T name suffix
-- where name is the name from which the subtype is obtained, using
-- lower case letters and underscores, and suffix starts with an upper
-- case letter. For example the name for the above declaration might be:
-- TintegerS4b
-- If the debugger is asked to give the type of an entity and the type
-- has the form T name suffix, it is probably appropriate to just use
-- "name" in the response since this is what is meaningful to the
-- programmer.
-------------------
-- Modular Types --
-------------------
-- A type declared
-- type x is mod N;
-- is encoded as a subrange of an unsigned base type with lower bound zero
-- and upper bound N - 1. Thus we give these types a somewhat nonstandard
-- interpretation: the standard interpretation would not, in general, imply
-- that arithmetic operations on type x are performed modulo N (especially
-- not when N is not a power of 2).
--------------------------------------
-- Tagged Types and Type Extensions --
--------------------------------------
-- A type D derived from a tagged type P has a field named "_parent" of
-- type P that contains its inherited fields. The type of this field is
-- usually P, but may be a more distant ancestor, if P is a null extension
-- of that type.
-- The type tag of a tagged type is a field named "_tag" of a pointer type.
-- If the type is derived from another tagged type, its _tag field is found
-- in its _parent field.
------------------------------------
-- Type Name Encodings (OBSOLETE) --
------------------------------------
-- In the following typ is the name of the type as normally encoded by the
-- debugger rules, i.e. a non-qualified name, all in lower case, with
-- standard encoding of upper half and wide characters
------------------------
-- Encapsulated Types --
------------------------
-- In some cases, the compiler encapsulates a type by wrapping it in a
-- structure. For example, this is used when a size or alignment
-- specification requires a larger type. Consider:
-- type y is mod 2 ** 64;
-- for y'size use 256;
-- In this case the compile generates a structure type y___PAD, which
-- has a single field whose name is F. This single field is 64 bits
-- long and contains the actual value. This kind of padding is used
-- when the logical value to be stored is shorter than the object in
-- which it is allocated. For example if a size clause is used to set
-- a size of 256 for a signed integer value, then a typical choice is
-- to wrap a 64-bit integer in a 256 bit PAD structure.
-- A similar encapsulation is done for some packed array types, in which
-- case the structure type is y___JM and the field name is OBJECT.
-- This is used in the case of a packed array stored using modular
-- representation (see section on representation of packed array
-- objects). In this case the JM wrapping is used to achieve correct
-- positioning of the packed array value (left or right justified in its
-- field depending on endianness.
-- When the debugger sees an object of a type whose name has a suffix of
-- ___PAD or ___JM, the type will be a record containing a single field,
-- and the name of that field will be all upper case. In this case, it
-- should look inside to get the value of the inner field, and neither
-- the outer structure name, nor the field name should appear when the
-- value is printed.
-- When the debugger sees a record named REP being a field inside
-- another record, it should treat the fields inside REP as being part
-- of the outer record (this REP field is only present for code
-- generation purposes). The REP record should not appear in the values
-- printed by the debugger.
-- standard encoding of upper half and wide characters.
-----------------------
-- Fixed-Point Types --
@ -613,22 +666,6 @@ package Exp_Dbug is
-- or compile time known values, with the encoding first for the lower
-- bound, then for the upper bound, as previously described.
-------------------
-- Modular Types --
-------------------
-- A type declared
-- type x is mod N;
-- Is encoded as a subrange of an unsigned base type with lower bound
-- zero and upper bound N. That is, there is no name encoding. We use
-- the standard encodings provided by the debugging format. Thus we
-- give these types a non-standard interpretation: the standard
-- interpretation of our encoding would not, in general, imply that
-- arithmetic on type x was to be performed modulo N (especially not
-- when N is not a power of 2).
------------------
-- Biased Types --
------------------
@ -887,34 +924,6 @@ package Exp_Dbug is
-- redundantly, particularly in the fixed-point case, but this
-- information can in any case be ignored by the debugger.
----------------------------
-- Note on Implicit Types --
----------------------------
-- The compiler creates implicit type names in many situations where a
-- type is present semantically, but no specific name is present. For
-- example:
-- S : Integer range M .. N;
-- Here the subtype of S is not integer, but rather an anonymous subtype
-- of Integer. Where possible, the compiler generates names for such
-- anonymous types that are related to the type from which the subtype
-- is obtained as follows:
-- T name suffix
-- where name is the name from which the subtype is obtained, using
-- lower case letters and underscores, and suffix starts with an upper
-- case letter. For example the name for the above declaration might be:
-- TintegerS4b
-- If the debugger is asked to give the type of an entity and the type
-- has the form T name suffix, it is probably appropriate to just use
-- "name" in the response since this is what is meaningful to the
-- programmer.
-------------------------------------------------
-- Subprograms for Handling Encoded Type Names --
-------------------------------------------------
@ -1062,51 +1071,6 @@ package Exp_Dbug is
-- debug declaration, then Empty is returned. This function also takes care
-- of setting Materialize_Entity on the renamed entity where required.
---------------------------
-- Packed Array Encoding --
---------------------------
-- For every constrained packed array, two types are created, and both
-- appear in the debugging output:
-- The original declared array type is a perfectly normal array type, and
-- its index bounds indicate the original bounds of the array.
-- The corresponding packed array type, which may be a modular type, or
-- may be an array of bytes type (see Exp_Pakd for full details). This is
-- the type that is actually used in the generated code and for debugging
-- information for all objects of the packed type.
-- The name of the corresponding packed array type is:
-- ttt___XPnnn
-- where
-- ttt is the name of the original declared array
-- nnn is the component size in bits (1-31)
-- Note that if the packed array is not bit-packed, the name will simply
-- be tttP.
-- When the debugger sees that an object is of a type that is encoded in
-- this manner, it can use the original type to determine the bounds and
-- the component type, and the component size to determine the packing
-- details.
-- For an unconstrained packed array, the corresponding packed array type
-- is neither used in the generated code nor for debugging information,
-- only the original type is used. In order to convey the packing in the
-- debugging information, the compiler generates the associated fat- and
-- thin-pointer types (see the Pointers to Unconstrained Array section
-- below) using the name of the corresponding packed array type as the
-- base name, i.e. ttt___XPnnn___XUP and ttt___XPnnn___XUT respectively.
-- When the debugger sees that an object is of a type that is encoded in
-- this manner, it can use the type of the fields to determine the bounds
-- and the component type, and the component size to determine the packing
-- details.
-------------------------------------------
-- Packed Array Representation in Memory --
-------------------------------------------
@ -1204,6 +1168,51 @@ package Exp_Dbug is
-- would mean that an assignment such as a := above would require shifts
-- when one value is in a register and the other value is in memory.
-------------------------------------------
-- Packed Array Name Encoding (OBSOLETE) --
-------------------------------------------
-- For every constrained packed array, two types are created, and both
-- appear in the debugging output:
-- The original declared array type is a perfectly normal array type, and
-- its index bounds indicate the original bounds of the array.
-- The corresponding packed array type, which may be a modular type, or
-- may be an array of bytes type (see Exp_Pakd for full details). This is
-- the type that is actually used in the generated code and for debugging
-- information for all objects of the packed type.
-- The name of the corresponding packed array type is:
-- ttt___XPnnn
-- where
-- ttt is the name of the original declared array
-- nnn is the component size in bits (1-31)
-- Note that if the packed array is not bit-packed, the name will simply
-- be tttP.
-- When the debugger sees that an object is of a type that is encoded in
-- this manner, it can use the original type to determine the bounds and
-- the component type, and the component size to determine the packing
-- details.
-- For an unconstrained packed array, the corresponding packed array type
-- is neither used in the generated code nor for debugging information,
-- only the original type is used. In order to convey the packing in the
-- debugging information, the compiler generates the associated fat- and
-- thin-pointer types (see the Pointers to Unconstrained Array section
-- below) using the name of the corresponding packed array type as the
-- base name, i.e. ttt___XPnnn___XUP and ttt___XPnnn___XUT respectively.
-- When the debugger sees that an object is of a type that is encoded in
-- this manner, it can use the type of the fields to determine the bounds
-- and the component type, and the component size to determine the packing
-- details.
------------------------------------------------------
-- Subprograms for Handling Packed Array Type Names --
------------------------------------------------------
@ -1219,58 +1228,67 @@ package Exp_Dbug is
-- Pointers to Unconstrained Arrays --
--------------------------------------
-- There are two kinds of pointers to arrays. The debugger can tell which
-- format is in use by the form of the type of the pointer.
-- There are two kinds of pointer to unconstrained arrays. The debugger can
-- tell which format is in use by the form of the type of the pointer.
-- Fat Pointers
-- Fat pointers are represented as a struct with two fields. This
-- struct has two distinguished field names:
-- Fat pointers are represented as a structure with two fields. This
-- structure has two distinguished field names:
-- P_ARRAY is a pointer to the array type. The name of this type is
-- the unconstrained type followed by "___XUA". This array will have
-- bounds which are the discriminants, and hence are unparsable, but
-- will give the number of subscripts and the component type.
-- the unconstrained type followed by "___XUA". The bounds of this
-- array will be obtained through dereferences of P_BOUNDS below.
-- P_BOUNDS is a pointer to a struct, the name of whose type is the
-- unconstrained array name followed by "___XUB" and which has
-- fields of the form
-- P_BOUNDS is a pointer to a structure. The name of this type is
-- the unconstrained array name followed by "___XUB" and it has
-- fields of the form:
-- LBn (n a decimal integer) lower bound of n'th dimension
-- UBn (n a decimal integer) upper bound of n'th dimension
-- The bounds may be any integral type. In the case of an enumeration
-- type, Enum_Rep values are used.
-- The bounds may be of any integral type. In the case of enumeration
-- types, Enum_Rep values are used.
-- For a given unconstrained array type, the compiler will generate one
-- fat-pointer type whose name is "arr___XUP", where "arr" is the name
-- of the array type, and use it to represent the array type itself in
-- the debugging information.
-- For a given unconstrained array type, the compiler will generate a
-- fat pointer type whose name is the name of the array type, and use
-- it to represent the array type itself in the debugging information.
-- This name was historically followed by "___XUP" (OBSOLETE).
-- For each pointer to this unconstrained array type, the compiler will
-- generate a typedef that points to the above "arr___XUP" fat-pointer
-- type. As a consequence, when it comes to fat-pointer types:
-- generate a typedef that points to the above fat pointer type. As a
-- consequence, when it comes to fat pointer types:
-- 1. The type name is given by the typedef
-- 1. The type name is given by the typedef, if any
-- 2. If the debugger is asked to output the type, the appropriate
-- form is "access arr", except if the type name is "arr___XUP"
-- for which it is the array definition.
-- form is "access arr" if there is the typedef, otherwise it is
-- the array definition.
-- Thin Pointers
-- The value of a thin pointer is a pointer to the second field of a
-- structure with two fields. The first field of the structure is of
-- the type ___XUB described for fat pointer types above. The second
-- field of the structure contains the actual array.
-- Thin pointers are represented as a regular pointer to array in the
-- debugging information. The bounds of this array will be the contents
-- of the first field above obtained through (shifted) dereferences.
-- Thin Pointers (OBSOLETE)
-- The value of a thin pointer is a pointer to the second field of a
-- structure with two fields. The name of this structure's type is
-- "arr___XUT", where "arr" is the name of the unconstrained array
-- type. Even though it actually points into middle of this structure,
-- the thin pointer's type in debugging information is
-- pointer-to-arr___XUT.
-- type. Even though it points into the middle of this structure,
-- the type in the debugging information is pointer to structure.
-- The first field of arr___XUT is named BOUNDS, and has a type named
-- arr___XUB, with the structure described for such types in fat
-- pointers, as described above.
-- The first field of the structure is named BOUNDS and is of the type
-- ___XUB described for fat pointer types above.
-- The second field of arr___XUT is named ARRAY, and contains the
-- The second field of the structure is named ARRAY, and contains the
-- actual array. Because this array has a dynamic size, determined by
-- the BOUNDS field that precedes it, all of the information about
-- arr___XUT is encoded in a parallel type named arr___XUT___XVE, with
@ -1279,19 +1297,6 @@ package Exp_Dbug is
-- type in this case is named arr___XUA and only its element type is
-- meaningful, just as described for fat pointers.
--------------------------------------
-- Tagged Types and Type Extensions --
--------------------------------------
-- A type C derived from a tagged type P has a field named "_parent" of
-- type P that contains its inherited fields. The type of this field is
-- usually P (encoded as usual if it has a dynamic size), but may be a more
-- distant ancestor, if P is a null extension of that type.
-- The type tag of a tagged type is a field named _tag, of type void*. If
-- the type is derived from another tagged type, its _tag field is found in
-- its _parent field.
-----------------------------
-- Variant Record Encoding --
-----------------------------
@ -1311,8 +1316,7 @@ package Exp_Dbug is
-- union, in which each member of the union corresponds to one variant.
-- However, unlike a C union, the size of the type may be variable even if
-- each of the components are fixed size, since it includes a computation
-- of which variant is present. In that case, it will be encoded as above
-- and a type with the suffix "___XVN___XVU" will be present.
-- of which variant is present.
-- The name of the union member is encoded to indicate the choices, and
-- is a string given by the following grammar:
@ -1335,9 +1339,7 @@ package Exp_Dbug is
-- to the use of the Enum_Rep attribute).
-- The type of the inner record is given by the name of the union type (as
-- above) concatenated with the above string. Since that type may itself be
-- variable-sized, it may also be encoded as above with a new type with a
-- further suffix of "___XVU".
-- above) concatenated with the above string.
-- As an example, consider:
@ -1375,9 +1377,7 @@ package Exp_Dbug is
-- be encoded, as in ordinary C unions, as a single field of the
-- enclosing union type named "x" of type "T", dispensing with the
-- enclosing struct. In this case, of course, the discriminant values
-- corresponding to the variant are unavailable. As for normal
-- variants, the field name "x" may be suffixed with ___XVL if it
-- has dynamic size.
-- corresponding to the variant are unavailable.
-- For example, the type Var in the preceding section, if followed by
-- "pragma Unchecked_Union (Var);" may be encoded as a struct with two
@ -1549,46 +1549,19 @@ package Exp_Dbug is
-- are missing and deal as best as it can with the limited information
-- available.
---------------------------------
-- GNAT Extensions to DWARF2/3 --
---------------------------------
-----------------------------------------
-- GNAT Extensions to DWARF (OBSOLETE) --
-----------------------------------------
-- If the compiler switch "-gdwarf+" is specified, GNAT Vendor extensions
-- to DWARF2/3 are generated, with the following variations from the above
-- specification.
-- DW_AT_use_GNAT_descriptive_type, encoded with value 0x2301
-- Change in the contents of the DW_AT_name attribute
-- This extension has never been implemented in the compiler.
-- The operators are represented in their natural form. (for example,
-- the addition operator is written as "+" instead of "Oadd"). The
-- component separator is "." instead of "__"
-- Introduction of DW_AT_GNAT_encoding, encoded with value 0x2301
-- Any debugging information entry representing a program entity, named
-- or implicit, may have a DW_AT_GNAT_encoding attribute. The value of
-- this attribute is a string representing the suffix internally added
-- by GNAT for various purposes, mainly for representing debug
-- information compatible with other formats. In particular this is
-- useful for IDEs which need to filter out information internal to
-- GNAT from their graphical interfaces.
-- If a debugging information entry has multiple encodings, all of them
-- will be listed in DW_AT_GNAT_encoding using the list separator ':'.
-- Introduction of DW_AT_GNAT_descriptive_type, encoded with value 0x2302
-- DW_AT_GNAT_descriptive_type, encoded with value 0x2302
-- Any debugging information entry representing a type may have a
-- DW_AT_GNAT_descriptive_type attribute whose value is a reference,
-- pointing to a debugging information entry representing another type
-- associated to the type.
-- Modification of the contents of the DW_AT_producer string
-- When emitting full GNAT Vendor extensions to DWARF2/3, "-gdwarf+"
-- is appended to the DW_AT_producer string.
--
-- When emitting only DW_AT_GNAT_descriptive_type, "-gdwarf+-" is
-- appended to the DW_AT_producer string.
end Exp_Dbug;