| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT COMPILER COMPONENTS -- |
| -- -- |
| -- E X P _ D B U G -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 1996-2022, 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 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; |
| 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. |
| |
| -- For Ghost entities, the encoding adds a prefix "___ghost_" to aid the |
| -- detection of leaks of Ignored Ghost entities in the "living" space. |
| -- Ignored Ghost entities and any code associated with them should be |
| -- removed by the compiler in a post-processing pass. As a result, |
| -- object files should not contain any occurrences of this prefix. |
| |
| -- 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 := False; |
| Suffix : String := ""); |
| -- Set Name_Buffer and Name_Len to the external name of the entity. The |
| -- external name is the Interface_Name, if specified, unless the entity |
| -- has an address clause or Has_Suffix is true. |
| -- |
| -- 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. |
| -- - the string "___" followed by Suffix if Has_Suffix is true. |
| -- |
| -- Note that a call to this procedure has no effect if we are not |
| -- generating code, since the necessary information for computing the |
| -- proper external name is not available in this case. |
| |
| -- WARNING: There is a matching C declaration of this subprogram in fe.h |
| |
| ------------------------------------- |
| -- Encoding for translation into C -- |
| ------------------------------------- |
| |
| -- In Modify_Tree_For_C mode we must add encodings to dismabiguate cases |
| -- where Ada block structure cannot be directly translated. These cases |
| -- are as follows: |
| |
| -- a) A loop variable may hide a homonym in an enclosing block |
| -- b) A block-local variable may hide a homonym in an enclosing block |
| |
| -- In C these constructs are not scopes and we must distinguish the names |
| -- explicitly. In the first case we create a qualified name with the suffix |
| -- 'L', in the second case with a suffix 'B'. |
| |
| -------------------------------------------- |
| -- 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). |
| |
| ------------------------ |
| -- 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. |
| |
| ----------------------- |
| -- 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. |
| |
| -------------------- |
| -- 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. |
| |
| ------------------ |
| -- 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 lower or |
| -- upper bound or is a biased type. |
| |
| -- 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. |
| |
| ------------------------------------------------- |
| -- 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. |
| |
| -- WARNING: There is a matching C declaration of this subprogram in fe.h |
| |
| -------------- |
| -- 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 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. |
| |
| ------------------------------------------- |
| -- 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 -- |
| ------------------------------------------------------ |
| |
| function Make_Packed_Array_Impl_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 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 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". The bounds of this |
| -- array will be obtained through dereferences of P_BOUNDS below. |
| |
| -- 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 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. |
| |
| -- 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 fat pointer type. As a |
| -- consequence, when it comes to fat pointer types: |
| |
| -- 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" 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 points into the middle of this structure, |
| -- the type in the debugging information is pointer to structure. |
| |
| -- 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 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 |
| -- 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. |
| |
| ----------------------------- |
| -- 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. |
| |
| -- 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. |
| |
| -- 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. |
| |
| -- 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. |
| |
| -- WARNING: There is a matching C declaration of this subprogram in fe.h |
| |
| --------------------------------- |
| -- 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. |
| |
| -- The characters 'a'..'z' and '0'..'9' are represented as Qc, where 'c' |
| -- stands for the character itself. 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, and the third enumeration literal would be |
| -- named Qb and the value assigned to it would be 2. |
| |
| ----------------------------------------------- |
| -- 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 DWARF (OBSOLETE) -- |
| ----------------------------------------- |
| |
| -- DW_AT_use_GNAT_descriptive_type, encoded with value 0x2301 |
| |
| -- This extension has never been implemented in the compiler. |
| |
| -- 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. |
| |
| end Exp_Dbug; |
