diff options
Diffstat (limited to 'gcc/ada/exp_dbug.ads')
| -rw-r--r-- | gcc/ada/exp_dbug.ads | 411 |
1 files changed, 192 insertions, 219 deletions
diff --git a/gcc/ada/exp_dbug.ads b/gcc/ada/exp_dbug.ads index 1461f6d..09921f0 100644 --- a/gcc/ada/exp_dbug.ads +++ b/gcc/ada/exp_dbug.ads @@ -6,7 +6,7 @@ -- -- -- S p e c -- -- -- --- Copyright (C) 1996-2020, Free Software Foundation, Inc. -- +-- Copyright (C) 1996-2021, Free Software Foundation, Inc. -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -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; |