public inbox for gcc-cvs@sourceware.org
help / color / mirror / Atom feed
* [gcc r12-2198] [Ada] Update internal documentation of debugging information
@ 2021-07-09 12:38 Pierre-Marie de Rodat
0 siblings, 0 replies; only message in thread
From: Pierre-Marie de Rodat @ 2021-07-09 12:38 UTC (permalink / raw)
To: gcc-cvs
https://gcc.gnu.org/g:d80c73318785edec642b04dfe00db2e61503bf20
commit r12-2198-gd80c73318785edec642b04dfe00db2e61503bf20
Author: Eric Botcazou <ebotcazou@adacore.com>
Date: Tue Jun 8 13:24:46 2021 +0200
[Ada] Update internal documentation of debugging information
gcc/ada/
* exp_dbug.ads: Update documentation of various items.
Diff:
---
gcc/ada/exp_dbug.ads | 409 ++++++++++++++++++++++++---------------------------
1 file changed, 191 insertions(+), 218 deletions(-)
diff --git a/gcc/ada/exp_dbug.ads b/gcc/ada/exp_dbug.ads
index 5e1bc91adcc..09921f0e42d 100644
--- a/gcc/ada/exp_dbug.ads
+++ b/gcc/ada/exp_dbug.ads
@@ -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 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.
- -- 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.
+ -- 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 --
- ---------------------------------
-
- -- If the compiler switch "-gdwarf+" is specified, GNAT Vendor extensions
- -- to DWARF2/3 are generated, with the following variations from the above
- -- specification.
-
- -- Change in the contents of the DW_AT_name attribute
-
- -- 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 "__"
+ -----------------------------------------
+ -- GNAT Extensions to DWARF (OBSOLETE) --
+ -----------------------------------------
- -- Introduction of DW_AT_GNAT_encoding, encoded with value 0x2301
+ -- DW_AT_use_GNAT_descriptive_type, 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.
+ -- This extension has never been implemented in the compiler.
- -- 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;
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2021-07-09 12:38 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-09 12:38 [gcc r12-2198] [Ada] Update internal documentation of debugging information Pierre-Marie de Rodat
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).