diff options
Diffstat (limited to 'gcc-4.8.3/gcc/ada/exp_dbug.ads')
| -rw-r--r-- | gcc-4.8.3/gcc/ada/exp_dbug.ads | 1602 |
1 files changed, 1602 insertions, 0 deletions
diff --git a/gcc-4.8.3/gcc/ada/exp_dbug.ads b/gcc-4.8.3/gcc/ada/exp_dbug.ads new file mode 100644 index 000000000..86099f66f --- /dev/null +++ b/gcc-4.8.3/gcc/ada/exp_dbug.ads @@ -0,0 +1,1602 @@ +------------------------------------------------------------------------------ +-- -- +-- GNAT COMPILER COMPONENTS -- +-- -- +-- E X P _ D B U G -- +-- -- +-- S p e c -- +-- -- +-- Copyright (C) 1996-2012, 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- -- +-- ware Foundation; either version 3, or (at your option) any later ver- -- +-- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- +-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- +-- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -- +-- for more details. You should have received a copy of the GNU General -- +-- Public License distributed with GNAT; see file COPYING3. If not, go to -- +-- http://www.gnu.org/licenses for a complete copy of the license. -- +-- -- +-- GNAT was originally developed by the GNAT team at New York University. -- +-- Extensive contributions were provided by Ada Core Technologies Inc. -- +-- -- +------------------------------------------------------------------------------ + +-- 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. + +with Namet; use Namet; +with Types; use Types; +with Uintp; use Uintp; + +package Exp_Dbug is + + ----------------------------------------------------- + -- Encoding and Qualification of Names of Entities -- + ----------------------------------------------------- + + -- This section describes how the names of entities are encoded in the + -- generated debugging information. + + -- An entity in Ada has a name of the form X.Y.Z ... E where X,Y,Z are the + -- enclosing scopes (not including Standard at the start). + + -- The encoding of the name follows this basic qualified naming scheme, + -- where the encoding of individual entity names is as described in Namet + -- (i.e. in particular names present in the original source are folded to + -- all lower case, with upper half and wide characters encoded as described + -- in Namet). Upper case letters are used only for entities generated by + -- the compiler. + + -- There are two cases, global entities, and local entities. In more formal + -- terms, local entities are those which have a dynamic enclosing scope, + -- and global entities are at the library level, except that we always + -- consider procedures to be global entities, even if they are nested + -- (that's because at the debugger level a procedure name refers to the + -- code, and the code is indeed a global entity, including the case of + -- nested procedures.) In addition, we also consider all types to be global + -- entities, even if they are defined within a procedure. + + -- The reason for treating all type names as global entities is that a + -- number of our type encodings work by having related type names, and we + -- need the full qualification to keep this unique. + + -- For global entities, the encoded name includes all components of the + -- fully expanded name (but omitting Standard at the start). For example, + -- if a library level child package P.Q has an embedded package R, and + -- there is an entity in this embedded package whose name is S, the encoded + -- name will include the components p.q.r.s. + + -- For local entities, the encoded name only includes the components up to + -- the enclosing dynamic scope (other than a block). At run time, such a + -- dynamic scope is a subprogram, and the debugging formats know about + -- local variables of procedures, so it is not necessary to have full + -- qualification for such entities. In particular this means that direct + -- local variables of a procedure are not qualified. + + -- As an example of the local name convention, consider a procedure V.W + -- with a local variable X, and a nested block Y containing an entity Z. + -- The fully qualified names of the entities X and Z are: + + -- V.W.X + -- V.W.Y.Z + + -- but since V.W is a subprogram, the encoded names will end up + -- encoding only + + -- x + -- y.z + + -- The separating dots are translated into double underscores + + ----------------------------- + -- Handling of Overloading -- + ----------------------------- + + -- The above scheme is incomplete for overloaded subprograms, since + -- overloading can legitimately result in case of two entities with + -- exactly the same fully qualified names. To distinguish between + -- entries in a set of overloaded subprograms, the encoded names are + -- serialized by adding the suffix: + + -- __nn (two underscores) + + -- where nn is a serial number (2 for the second overloaded function, + -- 3 for the third, etc.). A suffix of __1 is always omitted (i.e. no + -- suffix implies the first instance). + + -- These names are prefixed by the normal full qualification. So for + -- example, the third instance of the subprogram qrs in package yz + -- would have the name: + + -- yz__qrs__3 + + -- A more subtle case arises with entities declared within overloaded + -- subprograms. If we have two overloaded subprograms, and both declare + -- an entity xyz, then the fully expanded name of the two xyz's is the + -- same. To distinguish these, we add the same __n suffix at the end of + -- the inner entity names. + + -- In more complex cases, we can have multiple levels of overloading, + -- and we must make sure to distinguish which final declarative region + -- we are talking about. For this purpose, we use a more complex suffix + -- which has the form: + + -- __nn_nn_nn ... + + -- where the nn values are the homonym numbers as needed for any of the + -- qualifying entities, separated by a single underscore. If all the nn + -- values are 1, the suffix is omitted, Otherwise the suffix is present + -- (including any values of 1). The following example shows how this + -- suffixing works. + + -- package body Yz is + -- procedure Qrs is -- Name is yz__qrs + -- procedure Tuv is ... end; -- Name is yz__qrs__tuv + -- begin ... end Qrs; + + -- procedure Qrs (X: Int) is -- Name is yz__qrs__2 + -- procedure Tuv is ... end; -- Name is yz__qrs__tuv__2_1 + -- procedure Tuv (X: Int) is -- Name is yz__qrs__tuv__2_2 + -- begin ... end Tuv; + + -- procedure Tuv (X: Float) is -- Name is yz__qrs__tuv__2_3 + -- type m is new float; -- Name is yz__qrs__tuv__m__2_3 + -- begin ... end Tuv; + -- begin ... end Qrs; + -- end Yz; + + -------------------- + -- Operator Names -- + -------------------- + + -- The above rules applied to operator names would result in names with + -- quotation marks, which are not typically allowed by assemblers and + -- linkers, and even if allowed would be odd and hard to deal with. To + -- avoid this problem, operator names are encoded as follows: + + -- Oabs abs + -- Oand and + -- Omod mod + -- Onot not + -- Oor or + -- Orem rem + -- Oxor xor + -- Oeq = + -- One /= + -- Olt < + -- Ole <= + -- Ogt > + -- Oge >= + -- Oadd + + -- Osubtract - + -- Oconcat & + -- Omultiply * + -- Odivide / + -- Oexpon ** + + -- These names are prefixed by the normal full qualification, and + -- suffixed by the overloading identification. So for example, the + -- second operator "=" defined in package Extra.Messages would have + -- the name: + + -- extra__messages__Oeq__2 + + ---------------------------------- + -- Resolving Other Name Clashes -- + ---------------------------------- + + -- It might be thought that the above scheme is complete, but in Ada 95, + -- full qualification is insufficient to uniquely identify an entity in + -- the program, even if it is not an overloaded subprogram. There are + -- two possible confusions: + + -- a.b + + -- interpretation 1: entity b in body of package a + -- interpretation 2: child procedure b of package a + + -- a.b.c + + -- interpretation 1: entity c in child package a.b + -- interpretation 2: entity c in nested package b in body of a + + -- It is perfectly legal in both cases for both interpretations to be + -- valid within a single program. This is a bit of a surprise since + -- certainly in Ada 83, full qualification was sufficient, but not in + -- Ada 95. The result is that the above scheme can result in duplicate + -- names. This would not be so bad if the effect were just restricted + -- to debugging information, but in fact in both the above cases, it + -- is possible for both symbols to be external names, and so we have + -- a real problem of name clashes. + + -- To deal with this situation, we provide two additional encoding + -- rules for names: + + -- First: all library subprogram names are preceded by the string + -- _ada_ (which causes no duplications, since normal Ada names can + -- never start with an underscore. This not only solves the first + -- case of duplication, but also solves another pragmatic problem + -- which is that otherwise Ada procedures can generate names that + -- clash with existing system function names. Most notably, we can + -- have clashes in the case of procedure Main with the C main that + -- in some systems is always present. + + -- Second, for the case where nested packages declared in package + -- bodies can cause trouble, we add a suffix which shows which + -- entities in the list are body-nested packages, i.e. packages + -- whose spec is within a package body. The rules are as follows, + -- given a list of names in a qualified name name1.name2.... + + -- If none are body-nested package entities, then there is no suffix + + -- If at least one is a body-nested package entity, then the suffix + -- is X followed by a string of b's and n's (b = body-nested package + -- entity, n = not a body-nested package). + + -- There is one element in this string for each entity in the encoded + -- expanded name except the first (the rules are such that the first + -- entity of the encoded expanded name can never be a body-nested' + -- package. Trailing n's are omitted, as is the last b (there must + -- be at least one b, or we would not be generating a suffix at all). + + -- For example, suppose we have + + -- package x is + -- pragma Elaborate_Body; + -- m1 : integer; -- #1 + -- end x; + + -- package body x is + -- package y is m2 : integer; end y; -- #2 + -- package body y is + -- package z is r : integer; end z; -- #3 + -- end; + -- m3 : integer; -- #4 + -- end x; + + -- package x.y is + -- pragma Elaborate_Body; + -- m2 : integer; -- #5 + -- end x.y; + + -- package body x.y is + -- m3 : integer; -- #6 + -- procedure j is -- #7 + -- package k is + -- z : integer; -- #8 + -- end k; + -- begin + -- null; + -- end j; + -- end x.y; + + -- procedure x.m3 is begin null; end; -- #9 + + -- Then the encodings would be: + + -- #1. x__m1 (no BNPE's in sight) + -- #2. x__y__m2X (y is a BNPE) + -- #3. x__y__z__rXb (y is a BNPE, so is z) + -- #4. x__m3 (no BNPE's in sight) + -- #5. x__y__m2 (no BNPE's in sight) + -- #6. x__y__m3 (no BNPE's in signt) + -- #7. x__y__j (no BNPE's in sight) + -- #8. k__z (no BNPE's, only up to procedure) + -- #9 _ada_x__m3 (library level subprogram) + + -- Note that we have instances here of both kind of potential name + -- clashes, and the above examples show how the encodings avoid the + -- clash as follows: + + -- Lines #4 and #9 both refer to the entity x.m3, but #9 is a library + -- level subprogram, so it is preceded by the string _ada_ which acts + -- to distinguish it from the package body entity. + + -- Lines #2 and #5 both refer to the entity x.y.m2, but the first + -- instance is inside the body-nested package y, so there is an X + -- suffix to distinguish it from the child library entity. + + -- Note that enumeration literals never need Xb type suffixes, since + -- they are never referenced using global external names. + + --------------------- + -- Interface Names -- + --------------------- + + -- Note: if an interface name is present, then the external name is + -- taken from the specified interface name. Given current limitations of + -- the gcc backend, this means that the debugging name is also set to + -- the interface name, but conceptually, it would be possible (and + -- indeed desirable) to have the debugging information still use the Ada + -- name as qualified above, so we still fully qualify the name in the + -- front end. + + ------------------------------------- + -- Encodings Related to Task Types -- + ------------------------------------- + + -- Each task object defined by a single task declaration is associated + -- with a prefix that is used to qualify procedures defined in that + -- task. Given + -- + -- package body P is + -- task body TaskObj is + -- procedure F1 is ... end; + -- begin + -- B; + -- end TaskObj; + -- end P; + -- + -- The name of subprogram TaskObj.F1 is encoded as p__taskobjTK__f1. + -- The body, B, is contained in a subprogram whose name is + -- p__taskobjTKB. + + ------------------------------------------ + -- Encodings Related to Protected Types -- + ------------------------------------------ + + -- Each protected type has an associated record type, that describes + -- the actual layout of the private data. In addition to the private + -- components of the type, the Corresponding_Record_Type includes one + -- component of type Protection, which is the actual lock structure. + -- The run-time size of the protected type is the size of the corres- + -- ponding record. + + -- For a protected type prot, the Corresponding_Record_Type is encoded + -- as protV. + + -- The operations of a protected type are encoded as follows: each + -- operation results in two subprograms, a locking one that is called + -- from outside of the object, and a non-locking one that is used for + -- calls from other operations on the same object. The locking operation + -- simply acquires the lock, and then calls the non-locking version. + -- The names of all of these have a prefix constructed from the name of + -- the type, and a suffix which is P or N, depending on whether this is + -- the protected/non-locking version of the operation. + + -- Operations generated for protected entries follow the same encoding. + -- Each entry results in two subprograms: a procedure that holds the + -- entry body, and a function that holds the evaluation of the barrier. + -- The names of these subprograms include the prefix '_E' or '_B' res- + -- pectively. The names also include a numeric suffix to render them + -- unique in the presence of overloaded entries. + + -- Given the declaration: + + -- protected type Lock is + -- function Get return Integer; + -- procedure Set (X: Integer); + -- entry Update (Val : Integer); + -- private + -- Value : Integer := 0; + -- end Lock; + + -- the following operations are created: + + -- lock_getN + -- lock_getP, + + -- lock_setN + -- lock_setP + + -- lock_update_E1s + -- lock_udpate_B2s + + -- If the protected type implements at least one interface, the + -- following additional operations are created: + + -- lock_get + + -- lock_set + + -- These operations are used to ensure overriding of interface level + -- subprograms and proper dispatching on interface class-wide objects. + -- The bodies of these operations contain calls to their respective + -- protected versions: + + -- function lock_get return Integer is + -- begin + -- return lock_getP; + -- end lock_get; + + -- procedure lock_set (X : Integer) is + -- begin + -- lock_setP (X); + -- end lock_set; + + ---------------------------------------------------- + -- Conversion between Entities and External Names -- + ---------------------------------------------------- + + procedure Get_External_Name + (Entity : Entity_Id; + Has_Suffix : Boolean); + -- Set Name_Buffer and Name_Len to the external name of entity E. The + -- external name is the Interface_Name, if specified, unless the entity + -- has an address clause or a suffix. + -- + -- If the Interface is not present, or not used, the external name is the + -- concatenation of: + -- + -- - the string "_ada_", if the entity is a library subprogram, + -- - the names of any enclosing scopes, each followed by "__", + -- or "X_" if the next entity is a subunit) + -- - the name of the entity + -- - the string "$" (or "__" if target does not allow "$"), followed + -- by homonym suffix, if the entity is an overloaded subprogram + -- or is defined within an overloaded subprogram. + + procedure Get_External_Name_With_Suffix + (Entity : Entity_Id; + Suffix : String); + -- Set Name_Buffer and Name_Len to the external name of entity E. If + -- Suffix is the empty string the external name is as above, otherwise + -- the external name is the concatenation of: + -- + -- - the string "_ada_", if the entity is a library subprogram, + -- - the names of any enclosing scopes, each followed by "__", + -- or "X_" if the next entity is a subunit) + -- - the name of the entity + -- - the string "$" (or "__" if target does not allow "$"), followed + -- by homonym suffix, if the entity is an overloaded subprogram + -- or is defined within an overloaded subprogram. + -- - the string "___" followed by Suffix + -- + -- Note that a call to this procedure has no effect if we are not + -- generating code, since the necessary information for computing the + -- proper encoded name is not available in this case. + + -------------------------------------------- + -- Subprograms for Handling Qualification -- + -------------------------------------------- + + procedure Qualify_Entity_Names (N : Node_Id); + -- Given a node N, that represents a block, subprogram body, or package + -- body or spec, or protected or task type, sets a fully qualified name + -- for the defining entity of given construct, and also sets fully + -- qualified names for all enclosed entities of the construct (using + -- First_Entity/Next_Entity). Note that the actual modifications of the + -- names is postponed till a subsequent call to Qualify_All_Entity_Names. + -- Note: this routine does not deal with prepending _ada_ to library + -- subprogram names. The reason for this is that we only prepend _ada_ + -- to the library entity itself, and not to names built from this name. + + procedure Qualify_All_Entity_Names; + -- When Qualify_Entity_Names is called, no actual name changes are made, + -- i.e. the actual calls to Qualify_Entity_Name are deferred until a call + -- is made to this procedure. The reason for this deferral is that when + -- names are changed semantic processing may be affected. By deferring + -- the changes till just before gigi is called, we avoid any concerns + -- about such effects. Gigi itself does not use the names except for + -- output of names for debugging purposes (which is why we are doing + -- the name changes in the first place. + + -- Note: the routines Get_Unqualified_[Decoded]_Name_String in Namet are + -- useful to remove qualification from a name qualified by the call to + -- Qualify_All_Entity_Names. + + -------------------------------- + -- Handling of Numeric Values -- + -------------------------------- + + -- All numeric values here are encoded as strings of decimal digits. Only + -- integer values need to be encoded. A negative value is encoded as the + -- 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 -- + ------------------------- + + -- 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. + + ----------------------- + -- Fixed-Point Types -- + ----------------------- + + -- Fixed-point types are encoded using a suffix that indicates the + -- delta and small values. The actual type itself is a normal integer + -- type. + + -- typ___XF_nn_dd + -- typ___XF_nn_dd_nn_dd + + -- The first form is used when small = delta. The value of delta (and + -- small) is given by the rational nn/dd, where nn and dd are decimal + -- integers. + -- + -- The second form is used if the small value is different from the + -- delta. In this case, the first nn/dd rational value is for delta, + -- and the second value is for small. + + ------------------------------ + -- VAX Floating-Point Types -- + ------------------------------ + + -- Vax floating-point types are represented at run time as integer + -- types, which are treated specially by the code generator. Their + -- type names are encoded with the following suffix: + + -- typ___XFF + -- typ___XFD + -- typ___XFG + + -- representing the Vax F Float, D Float, and G Float types. The + -- debugger must treat these specially. In particular, printing these + -- values can be achieved using the debug procedures that are provided + -- in package System.Vax_Float_Operations: + + -- procedure Debug_Output_D (Arg : D); + -- procedure Debug_Output_F (Arg : F); + -- procedure Debug_Output_G (Arg : G); + + -- These three procedures take a Vax floating-point argument, and + -- output a corresponding decimal representation to standard output + -- with no terminating line return. + + -------------------- + -- Discrete Types -- + -------------------- + + -- Discrete types are coded with a suffix indicating the range in the + -- case where one or both of the bounds are discriminants or variable. + + -- Note: at the current time, we also encode compile time known bounds + -- if they do not match the natural machine type bounds, but this may + -- be removed in the future, since it is redundant for most debugging + -- formats. However, we do not ever need XD encoding for enumeration + -- base types, since here it is always clear what the bounds are from + -- the total number of enumeration literals. + + -- typ___XD + -- typ___XDL_lowerbound + -- typ___XDU_upperbound + -- typ___XDLU_lowerbound__upperbound + + -- If a discrete type is a natural machine type (i.e. its bounds + -- correspond in a natural manner to its size), then it is left + -- unencoded. The above encoding forms are used when there is a + -- constrained range that does not correspond to the size or that + -- has discriminant references or other compile time known bounds. + + -- The first form is used if both bounds are dynamic, in which case two + -- constant objects are present whose names are typ___L and typ___U in + -- the same scope as typ, and the values of these constants indicate + -- the bounds. As far as the debugger is concerned, these are simply + -- variables that can be accessed like any other variables. In the + -- enumeration case, these values correspond to the Enum_Rep values for + -- the lower and upper bounds. + + -- The second form is used if the upper bound is dynamic, but the lower + -- bound is either constant or depends on a discriminant of the record + -- with which the type is associated. The upper bound is stored in a + -- constant object of name typ___U as previously described, but the + -- lower bound is encoded directly into the name as either a decimal + -- integer, or as the discriminant name. + + -- The third form is similarly used if the lower bound is dynamic, but + -- the upper bound is compile time known or a discriminant reference, + -- in which case the lower bound is stored in a constant object of name + -- typ___L, and the upper bound is encoded directly into the name as + -- either a decimal integer, or as the discriminant name. + + -- The fourth form is used if both bounds are discriminant references + -- 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 -- + ------------------ + + -- Only discrete types can be biased, and the fact that they are biased + -- is indicated by a suffix of the form: + + -- typ___XB_lowerbound__upperbound + + -- Here lowerbound and upperbound are decimal integers, with the usual + -- (postfix "m") encoding for negative numbers. Biased types are only + -- possible where the bounds are compile time known, and the values are + -- represented as unsigned offsets from the lower bound given. For + -- example: + + -- type Q is range 10 .. 15; + -- for Q'size use 3; + + -- The size clause will force values of type Q in memory to be stored + -- in biased form (e.g. 11 will be represented by the bit pattern 001). + + ---------------------------------------------- + -- Record Types with Variable-Length Fields -- + ---------------------------------------------- + + -- The debugging formats do not fully support these types, and indeed + -- some formats simply generate no useful information at all for such + -- types. In order to provide information for the debugger, gigi creates + -- a parallel type in the same scope with one of the names + + -- type___XVE + -- type___XVU + + -- The former name is used for a record and the latter for the union + -- that is made for a variant record (see below) if that record or union + -- has a field of variable size or if the record or union itself has a + -- variable size. These encodings suffix any other encodings that that + -- might be suffixed to the type name. + + -- The idea here is to provide all the needed information to interpret + -- objects of the original type in the form of a "fixed up" type, which + -- is representable using the normal debugging information. + + -- There are three cases to be dealt with. First, some fields may have + -- variable positions because they appear after variable-length fields. + -- To deal with this, we encode *all* the field bit positions of the + -- special ___XV type in a non-standard manner. + + -- The idea is to encode not the position, but rather information that + -- allows computing the position of a field from the position of the + -- previous field. The algorithm for computing the actual positions of + -- all fields and the length of the record is as follows. In this + -- description, let P represent the current bit position in the record. + + -- 1. Initialize P to 0 + + -- 2. For each field in the record: + + -- 2a. If an alignment is given (see below), then round P up, if + -- needed, to the next multiple of that alignment. + + -- 2b. If a bit position is given, then increment P by that amount + -- (that is, treat it as an offset from the end of the preceding + -- record). + + -- 2c. Assign P as the actual position of the field + + -- 2d. Compute the length, L, of the represented field (see below) + -- and compute P'=P+L. Unless the field represents a variant part + -- (see below and also Variant Record Encoding), set P to P'. + + -- The alignment, if present, is encoded in the field name of the + -- record, which has a suffix: + + -- fieldname___XVAnn + + -- where the nn after the XVA indicates the alignment value in storage + -- units. This encoding is present only if an alignment is present. + + -- The size of the record described by an XVE-encoded type (in bits) is + -- generally the maximum value attained by P' in step 2d above, rounded + -- up according to the record's alignment. + + -- Second, the variable-length fields themselves are represented by + -- replacing the type by a special access type. The designated type of + -- this access type is the original variable-length type, and the fact + -- that this field has been transformed in this way is signalled by + -- encoding the field name as: + + -- field___XVL + + -- where field is the original field name. If a field is both + -- variable-length and also needs an alignment encoding, then the + -- encodings are combined using: + + -- field___XVLnn + + -- Note: the reason that we change the type is so that the resulting + -- type has no variable-length fields. At least some of the formats used + -- for debugging information simply cannot tolerate variable- length + -- fields, so the encoded information would get lost. + + -- Third, in the case of a variant record, the special union that + -- contains the variants is replaced by a normal C union. In this case, + -- the positions are all zero. + + -- Discriminants appear before any variable-length fields that depend on + -- them, with one exception. In some cases, a discriminant governing the + -- choice of a variant clause may appear in the list of fields of an XVE + -- type after the entry for the variant clause itself (this can happen + -- in the presence of a representation clause for the record type in the + -- source program). However, when this happens, the discriminant's + -- position may be determined by first applying the rules described in + -- this section, ignoring the variant clause. As a result, discriminants + -- can always be located independently of the variable-length fields + -- that depend on them. + + -- The size of the ___XVE or ___XVU record or union is set to the + -- alignment (in bytes) of the original object so that the debugger + -- can calculate the size of the original type. + + -- As an example of this encoding, consider the declarations: + + -- type Q is array (1 .. V1) of Float; -- alignment 4 + -- type R is array (1 .. V2) of Long_Float; -- alignment 8 + + -- type X is record + -- A : Character; + -- B : Float; + -- C : String (1 .. V3); + -- D : Float; + -- E : Q; + -- F : R; + -- G : Float; + -- end record; + + -- The encoded type looks like: + + -- type anonymousQ is access Q; + -- type anonymousR is access R; + + -- type X___XVE is record + -- A : Character; -- position contains 0 + -- B : Float; -- position contains 24 + -- C___XVL : access String (1 .. V3); -- position contains 0 + -- D___XVA4 : Float; -- position contains 0 + -- E___XVL4 : anonymousQ; -- position contains 0 + -- F___XVL8 : anonymousR; -- position contains 0 + -- G : Float; -- position contains 0 + -- end record; + + -- Any bit sizes recorded for fields other than dynamic fields and + -- variants are honored as for ordinary records. + + -- Notes: + + -- 1) The B field could also have been encoded by using a position of + -- zero and an alignment of 4, but in such a case the coding by position + -- is preferred (since it takes up less space). We have used the + -- (illegal) notation access xxx as field types in the example above. + + -- 2) The E field does not actually need the alignment indication but + -- this may not be detected in this case by the conversion routines. + + -- 3) Our conventions do not cover all XVE-encoded records in which + -- some, but not all, fields have representation clauses. Such records + -- may, therefore, be displayed incorrectly by debuggers. This situation + -- is not common. + + ----------------------- + -- Base Record Types -- + ----------------------- + + -- Under certain circumstances, debuggers need two descriptions of a + -- record type, one that gives the actual details of the base type's + -- structure (as described elsewhere in these comments) and one that may + -- be used to obtain information about the particular subtype and the + -- size of the objects being typed. In such cases the compiler will + -- substitute type whose name is typically compiler-generated and + -- irrelevant except as a key for obtaining the actual type. + + -- Specifically, if this name is x, then we produce a record type named + -- x___XVS consisting of one field. The name of this field is that of + -- the actual type being encoded, which we'll call y. The type of this + -- single field can be either an arbitrary non-reference type, e.g. an + -- integer type, or a reference type; in the latter case, the referenced + -- type is also the actual type being encoded y. Both x and y may have + -- corresponding ___XVE types. + + -- The size of the objects typed as x should be obtained from the + -- structure of x (and x___XVE, if applicable) as for ordinary types + -- unless there is a variable named x___XVZ, which, if present, will + -- hold the size (in bytes) of x. In this latter case, the size of the + -- x___XVS type will not be a constant but a reference to x___XVZ. + + -- The type x will either be a subtype of y (see also Subtypes of + -- Variant Records, below) or will contain a single field of type y, + -- or no fields at all. The layout, types, and positions of these + -- fields will be accurate, if present. (Currently, however, the GDB + -- debugger makes no use of x except to determine its size). + + -- Among other uses, XVS types are used to encode unconstrained types. + -- For example, given: + -- + -- subtype Int is INTEGER range 0..10; + -- type T1 (N: Int := 0) is record + -- F1: String (1 .. N); + -- end record; + -- type AT1 is array (INTEGER range <>) of T1; + -- + -- the element type for AT1 might have a type defined as if it had + -- been written: + -- + -- type at1___PAD is record F : T1; end record; + -- for at1___PAD'Size use 16 * 8; + -- + -- and there would also be: + -- + -- type at1___PAD___XVS is record t1: reft1; end record; + -- type t1 is ... + -- type reft1 is <reference to t1> + -- + -- Had the subtype Int been dynamic: + -- + -- subtype Int is INTEGER range 0 .. M; -- M a variable + -- + -- Then the compiler would also generate a declaration whose effect + -- would be + -- + -- at1___PAD___XVZ: constant Integer := 32 + M * 8 + padding term; + -- + -- Not all unconstrained types are so encoded; the XVS convention may be + -- unnecessary for unconstrained types of fixed size. However, this + -- encoding is always necessary when a subcomponent type (array + -- element's type or record field's type) is an unconstrained record + -- type some of whose components depend on discriminant values. + + ----------------- + -- Array Types -- + ----------------- + + -- Since there is no way for the debugger to obtain the index subtypes + -- for an array type, we produce a type that has the name of the array + -- type followed by "___XA" and is a record type whose field types are + -- the respective types for the bounds (and whose field names are the + -- names of these types). + + -- To conserve space, we do not produce this type unless one of the + -- index types is either an enumeration type, has a variable upper + -- bound, has a lower bound different from the constant 1, is a biased + -- type, or is wider than "sizetype". + + -- Given the full encoding of these types (see above description for + -- the encoding of discrete types), this means that all necessary + -- information for addressing arrays is available. In some debugging + -- formats, some or all of the bounds information may be available + -- 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 -- + ------------------------------------------------- + + procedure Get_Encoded_Name (E : Entity_Id); + -- If the entity is a typename, store the external name of the entity as in + -- Get_External_Name, followed by three underscores plus the type encoding + -- in Name_Buffer with the length in Name_Len, and an ASCII.NUL character + -- stored following the name. Otherwise set Name_Buffer and Name_Len to + -- hold the entity name. Note that a call to this procedure has no effect + -- if we are not generating code, since the necessary information for + -- computing the proper encoded name is not available in this case. + + -------------- + -- Renaming -- + -------------- + + -- Debugging information is generated for exception, object, package, and + -- subprogram renaming (generic renamings are not significant, since + -- generic templates are not relevant at debugging time). + + -- Consider a renaming declaration of the form + + -- x : typ renames y; + + -- There is one case in which no special debugging information is required, + -- namely the case of an object renaming where the back end allocates a + -- reference for the renamed variable, and the entity x is this reference. + -- The debugger can handle this case without any special processing or + -- encoding (it won't know it was a renaming, but that does not matter). + + -- All other cases of renaming generate a dummy variable for an entity + -- whose name is of the form: + + -- x___XR_... for an object renaming + -- x___XRE_... for an exception renaming + -- x___XRP_... for a package renaming + + -- and where the "..." represents a suffix that describes the structure of + -- the object name given in the renaming (see details below). + + -- The name is fully qualified in the usual manner, i.e. qualified in the + -- same manner as the entity x would be. In the case of a package renaming + -- where x is a child unit, the qualification includes the name of the + -- parent unit, to disambiguate child units with the same simple name and + -- (of necessity) different parents. + + -- Note: subprogram renamings are not encoded at the present time + + -- The suffix of the variable name describing the renamed object is defined + -- to use the following encoding: + + -- For the simple entity case, where y is just an entity name, the suffix + -- is of the form: + + -- y___XE + + -- i.e. the suffix has a single field, the first part matching the + -- name y, followed by a "___" separator, ending with sequence XE. + -- The entity name portion is fully qualified in the usual manner. + -- This same naming scheme is followed for all forms of encoded + -- renamings that rename a simple entity. + + -- For the object renaming case where y is a selected component or an + -- indexed component, the variable name is suffixed by additional fields + -- that give details of the components. The name starts as above with a + -- y___XE name indicating the outer level object entity. Then a series of + -- selections and indexing operations can be specified as follows: + + -- Indexed component + + -- A series of subscript values appear in sequence, the number + -- corresponds to the number of dimensions of the array. The + -- subscripts have one of the following two forms: + + -- XSnnn + + -- Here nnn is a constant value, encoded as a decimal integer + -- (pos value for enumeration type case). Negative values have + -- a trailing 'm' as usual. + + -- XSe + + -- Here e is the (unqualified) name of a constant entity in the + -- same scope as the renaming which contains the subscript value. + + -- Slice + + -- For the slice case, we have two entries. The first is for the + -- lower bound of the slice, and has the form: + + -- XLnnn + -- XLe + + -- Specifies the lower bound, using exactly the same encoding as + -- for an XS subscript as described above. + + -- Then the upper bound appears in the usual XSnnn/XSe form + + -- Selected component + + -- For a selected component, we have a single entry + + -- XRf + + -- Here f is the field name for the selection + + -- For an explicit dereference (.all), we have a single entry + + -- XA + + -- As an example, consider the declarations: + + -- package p is + -- type q is record + -- m : string (2 .. 5); + -- end record; + -- + -- type r is array (1 .. 10, 1 .. 20) of q; + -- + -- g : r; + -- + -- z : string renames g (1,5).m(2 ..3) + -- end p; + + -- The generated variable entity would appear as + + -- p__z___XR_p__g___XEXS1XS5XRmXL2XS3 : _renaming_type; + -- p__g___XE--------------------outer entity is g + -- XS1-----------------first subscript for g + -- XS5--------------second subscript for g + -- XRm-----------select field m + -- XL2--------lower bound of slice + -- XS3-----upper bound of slice + + -- Note that the type of the variable is a special internal type named + -- _renaming_type. This type is an arbitrary type of zero size created + -- in package Standard (see cstand.adb) and is ignored by the debugger. + + function Debug_Renaming_Declaration (N : Node_Id) return Node_Id; + -- The argument N is a renaming declaration. The result is a variable + -- declaration as described in the above paragraphs. If N is not a special + -- 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) + + -- 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 -- + ------------------------------------------- + + -- Packed arrays are represented in tightly packed form, with no extra bits + -- between components. This is true even when the component size is not a + -- factor of the storage unit size, so that as a result it is possible for + -- components to cross storage unit boundaries. + + -- The layout in storage is identical, regardless of whether the + -- implementation type is a modular type or an array-of-bytes type. See + -- Exp_Pakd for details of how these implementation types are used, but for + -- the purpose of the debugger, only the starting address of the object in + -- memory is significant. + + -- The following example should show clearly how the packing works in + -- the little-endian and big-endian cases: + + -- type B is range 0 .. 7; + -- for B'Size use 3; + + -- type BA is array (0 .. 5) of B; + -- pragma Pack (BA); + + -- BV : constant BA := (1,2,3,4,5,6); + + -- Little endian case + + -- BV'Address + 2 BV'Address + 1 BV'Address + 0 + -- +-----------------+-----------------+-----------------+ + -- | ? ? ? ? ? ? 1 1 | 0 1 0 1 1 0 0 0 | 1 1 0 1 0 0 0 1 | + -- +-----------------+-----------------+-----------------+ + -- <---------> <-----> <---> <---> <-----> <---> <---> + -- unused bits BV(5) BV(4) BV(3) BV(2) BV(1) BV(0) + -- + -- Big endian case + -- + -- BV'Address + 0 BV'Address + 1 BV'Address + 2 + -- +-----------------+-----------------+-----------------+ + -- | 0 0 1 0 1 0 0 1 | 1 1 0 0 1 0 1 1 | 1 0 ? ? ? ? ? ? | + -- +-----------------+-----------------+-----------------+ + -- <---> <---> <-----> <---> <---> <-----> <---------> + -- BV(0) BV(1) BV(2) BV(3) BV(4) BV(5) unused bits + + -- Note that if a modular type is used to represent the array, the + -- allocation in memory is not the same as a normal modular type. The + -- difference occurs when the allocated object is larger than the size of + -- the array. For a normal modular type, we extend the value on the left + -- with zeroes. + + -- For example, in the normal modular case, if we have a 6-bit modular + -- type, declared as mod 2**6, and we allocate an 8-bit object for this + -- type, then we extend the value with two bits on the most significant + -- end, and in either the little-endian or big-endian case, the value 63 + -- is represented as 00111111 in binary in memory. + + -- For a modular type used to represent a packed array, the rule is + -- different. In this case, if we have to extend the value, then we do it + -- with undefined bits (which are not initialized and whose value is + -- irrelevant to any generated code). Furthermore these bits are on the + -- right (least significant bits) in the big-endian case, and on the left + -- (most significant bits) in the little-endian case. + + -- For example, if we have a packed boolean array of 6 bits, all set to + -- True, stored in an 8-bit object, then the value in memory in binary is + -- ??111111 in the little-endian case, and 111111?? in the big-endian case. + + -- This is done so that the representation of packed arrays does not + -- depend on whether we use a modular representation or array of bytes + -- as previously described. This ensures that we can pass such values by + -- reference in the case where a subprogram has to be able to handle values + -- stored in either form. + + -- Note that when we extract the value of such a modular packed array, we + -- expect to retrieve only the relevant bits, so in this same example, when + -- we extract the value we get 111111 in both cases, and the code generated + -- by the front end assumes this although it does not assume that any high + -- order bits are defined. + + -- There are opportunities for optimization based on the knowledge that the + -- unused bits are irrelevant for these type of packed arrays. For example + -- if we have two such 6-bit-in-8-bit values and we do an assignment: + + -- a := b; + + -- Then logically, we extract the 6 bits and store only 6 bits in the + -- result, but the back end is free to simply assign the entire 8-bits in + -- this case, since we don't actually care about the undefined bits. + -- However, in the equality case, it is important to ensure that the + -- undefined bits do not participate in an equality test. + + -- If a modular packed array value is assigned to a register then logically + -- it could always be held right justified, to avoid any need to shift, + -- e.g. when doing comparisons. But probably this is a bad choice, as it + -- 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. + + ------------------------------------------------------ + -- Subprograms for Handling Packed Array Type Names -- + ------------------------------------------------------ + + function Make_Packed_Array_Type_Name + (Typ : Entity_Id; + Csize : Uint) + return Name_Id; + -- This function is used in Exp_Pakd to create the name that is encoded as + -- described above. The entity Typ provides the name ttt, and the value + -- Csize is the component size that provides the nnn value. + + -------------------------------------- + -- 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. + + -- Fat Pointers + + -- Fat pointers are represented as a struct with two fields. This + -- struct 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. + + -- 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 + + -- 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. + + -- 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 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: + + -- 1. The type name is given by the typedef + + -- 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. + + -- Thin Pointers + + -- 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. + + -- 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 second field of arr___XUT 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 + -- fields BOUNDS and ARRAY___XVL. As for previously described ___XVE + -- types, ARRAY___XVL has a pointer-to-array type. However, the array + -- 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 -- + ----------------------------- + + -- The variant part of a variant record is encoded as a single field in the + -- enclosing record, whose name is: + + -- discrim___XVN + + -- where discrim is the unqualified name of the variant. This field name is + -- built by gigi (not by code in this unit). For Unchecked_Union record, + -- this discriminant will not appear in the record (see Unchecked Unions, + -- below). + + -- The type corresponding to this field has a name that is obtained by + -- concatenating the type name with the above string and is similar to a C + -- 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. + + -- The name of the union member is encoded to indicate the choices, and + -- is a string given by the following grammar: + + -- member_name ::= {choice} | others_choice + -- choice ::= simple_choice | range_choice + -- simple_choice ::= S number + -- range_choice ::= R number T number + -- number ::= {decimal_digit} [m] + -- others_choice ::= O (upper case letter O) + + -- The m in a number indicates a negative value. As an example of this + -- encoding scheme, the choice 1 .. 4 | 7 | -10 would be represented by + + -- R1T4S7S10m + + -- In the case of enumeration values, the values used are the actual + -- representation values in the case where an enumeration type has an + -- enumeration representation spec (i.e. they are values that correspond + -- 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". + + -- As an example, consider: + + -- type Var (Disc : Boolean := True) is record + -- M : Integer; + + -- case Disc is + -- when True => + -- R : Integer; + -- S : Integer; + + -- when False => + -- T : Integer; + -- end case; + -- end record; + + -- V1 : Var; + + -- In this case, the type var is represented as a struct with three fields. + -- The first two are "disc" and "m", representing the values of these + -- record components. The third field is a union of two types, with field + -- names S1 and O. S1 is a struct with fields "r" and "s", and O is a + -- struct with field "t". + + ---------------------- + -- Unchecked Unions -- + ---------------------- + + -- The encoding for variant records changes somewhat under the influence + -- of a "pragma Unchecked_Union" clause: + + -- 1. The discriminant will not be present in the record, although its + -- name is still used in the encodings. + -- 2. Variants containing a single component named "x" of type "T" may + -- 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. + + -- For example, the type Var in the preceding section, if followed by + -- "pragma Unchecked_Union (Var);" may be encoded as a struct with two + -- fields. The first is "m". The second field is a union of two types, + -- with field names S1 and "t". As before, S1 is a struct with fields + -- "r" and "s". "t" is a field of type Integer. + + ------------------------------------------------ + -- Subprograms for Handling Variant Encodings -- + ------------------------------------------------ + + procedure Get_Variant_Encoding (V : Node_Id); + -- This procedure is called by Gigi with V being the variant node. The + -- corresponding encoding string is returned in Name_Buffer with the length + -- of the string in Name_Len, and an ASCII.NUL character stored following + -- the name. + + --------------------------------- + -- Subtypes of Variant Records -- + --------------------------------- + + -- A subtype of a variant record is represented by a type in which the + -- union field from the base type is replaced by one of the possible + -- values. For example, if we have: + + -- type Var (Disc : Boolean := True) is record + -- M : Integer; + + -- case Disc is + -- when True => + -- R : Integer; + -- S : Integer; + + -- when False => + -- T : Integer; + -- end case; + + -- end record; + -- V1 : Var; + -- V2 : Var (True); + -- V3 : Var (False); + + -- Here V2, for example, is represented with a subtype whose name is + -- something like TvarS3b, which is a struct with three fields. The first + -- two fields are "disc" and "m" as for the base type, and the third field + -- is S1, which contains the fields "r" and "s". + + -- The debugger should simply ignore structs with names of the form + -- corresponding to variants, and consider the fields inside as belonging + -- to the containing record. + + ----------------------------------------------- + -- Extra renamings for subprogram instances -- + ----------------------------------------------- + + procedure Build_Subprogram_Instance_Renamings + (N : Node_Id; + Wrapper : Entity_Id); + -- The debugger has difficulties in recovering the value of actuals of an + -- elementary type, from within the body of a subprogram instantiation. + -- This is because such actuals generate an object declaration that is + -- placed within the wrapper package of the instance, and the entity in + -- these declarations is encoded in a complex way that GDB does not handle + -- well. These new renaming declarations appear within the body of the + -- subprogram, and are redundant from a visibility point of view, but They + -- should have no measurable performance impact, and require no special + -- decoding in the debugger. + + ------------------------------------------- + -- Character literals in Character Types -- + ------------------------------------------- + + -- Character types are enumeration types at least one of whose enumeration + -- literals is a character literal. Enumeration literals are usually simply + -- represented using their identifier names. If the enumeration literal is + -- a character literal, the name is encoded as described in the following + -- paragraph. + + -- A name QUhh, where each 'h' is a lower-case hexadecimal digit, stands + -- for a character whose Unicode encoding is hh, and QWhhhh likewise stands + -- for a wide character whose encoding is hhhh. The representation values + -- are encoded as for ordinary enumeration literals (and have no necessary + -- relationship to the values encoded in the names). + + -- For example, given the type declaration + + -- type x is (A, 'C', B); + + -- the second enumeration literal would be named QU43 and the value + -- assigned to it would be 1. + + ----------------------------------------------- + -- Secondary Dispatch tables of tagged types -- + ----------------------------------------------- + + procedure Get_Secondary_DT_External_Name + (Typ : Entity_Id; + Ancestor_Typ : Entity_Id; + Suffix_Index : Int); + -- Set Name_Buffer and Name_Len to the external name of one secondary + -- dispatch table of Typ. If the interface has been inherited from some + -- ancestor then Ancestor_Typ is such node (in this case the secondary DT + -- is needed to handle overridden primitives); if there is no such ancestor + -- then Ancestor_Typ is equal to Typ. + -- + -- Internal rule followed for the generation of the external name: + -- + -- Case 1. If the secondary dispatch has not been inherited from some + -- ancestor of Typ then the external name is composed as + -- follows: + -- External_Name (Typ) + Suffix_Number + 'P' + -- + -- Case 2. if the secondary dispatch table has been inherited from some + -- ancestor then the external name is composed as follows: + -- External_Name (Typ) + '_' + External_Name (Ancestor_Typ) + -- + Suffix_Number + 'P' + -- + -- Note: We have to use the external names (instead of simply their names) + -- to protect the frontend against programs that give the same name to all + -- the interfaces and use the expanded name to reference them. The + -- Suffix_Number is used to differentiate all the secondary dispatch + -- tables of a given type. + -- + -- Examples: + -- + -- package Pkg1 is | package Pkg2 is | package Pkg3 is + -- type Typ is | type Typ is | type Typ is + -- interface; | interface; | interface; + -- end Pkg1; | end Pkg; | end Pkg3; + -- + -- with Pkg1, Pkg2, Pkg3; + -- package Case_1 is + -- type Typ is new Pkg1.Typ and Pkg2.Typ and Pkg3.Typ with ... + -- end Case_1; + -- + -- with Case_1; + -- package Case_2 is + -- type Typ is new Case_1.Typ with ... + -- end Case_2; + -- + -- These are the external names generated for Case_1.Typ (note that + -- Pkg1.Typ is associated with the Primary Dispatch Table, because it + -- is the parent of this type, and hence no external name is + -- generated for it). + -- case_1__typ0P (associated with Pkg2.Typ) + -- case_1__typ1P (associated with Pkg3.Typ) + -- + -- These are the external names generated for Case_2.Typ: + -- case_2__typ_case_1__typ0P + -- case_2__typ_case_1__typ1P + + ---------------------------- + -- Effect of Optimization -- + ---------------------------- + + -- If the program is compiled with optimization on (e.g. -O1 switch + -- specified), then there may be variations in the output from the above + -- specification. In particular, objects may disappear from the output. + -- This includes not only constants and variables that the program declares + -- at the source level, but also the x___L and x___U constants created to + -- describe the lower and upper bounds of subtypes with dynamic bounds. + -- This means for example, that array bounds may disappear if optimization + -- is turned on. The debugger is expected to recognize that these constants + -- 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 "__" + + -- 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 + + -- 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; |