1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 1996-2005 Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- GNAT was originally developed by the GNAT team at New York University. --
23 -- Extensive contributions were provided by Ada Core Technologies Inc. --
25 ------------------------------------------------------------------------------
27 -- Expand routines for generation of special declarations used by the
28 -- debugger. In accordance with the Dwarf 2.2 specification, certain
29 -- type names are encoded to provide information to the debugger.
31 with Types; use Types;
32 with Uintp; use Uintp;
36 -----------------------------------------------------
37 -- Encoding and Qualification of Names of Entities --
38 -----------------------------------------------------
40 -- This section describes how the names of entities are encoded in
41 -- the generated debugging information.
43 -- An entity in Ada has a name of the form X.Y.Z ... E where X,Y,Z
44 -- are the enclosing scopes (not including Standard at the start).
46 -- The encoding of the name follows this basic qualified naming scheme,
47 -- where the encoding of individual entity names is as described in
48 -- Namet (i.e. in particular names present in the original source are
49 -- folded to all lower case, with upper half and wide characters encoded
50 -- as described in Namet). Upper case letters are used only for entities
51 -- generated by the compiler.
53 -- There are two cases, global entities, and local entities. In more
54 -- formal terms, local entities are those which have a dynamic enclosing
55 -- scope, and global entities are at the library level, except that we
56 -- always consider procedures to be global entities, even if they are
57 -- nested (that's because at the debugger level a procedure name refers
58 -- to the code, and the code is indeed a global entity, including the
59 -- case of nested procedures.) In addition, we also consider all types
60 -- to be global entities, even if they are defined within a procedure.
62 -- The reason for treating all type names as global entities is that
63 -- a number of our type encodings work by having related type names,
64 -- and we need the full qualification to keep this unique.
66 -- For global entities, the encoded name includes all components of the
67 -- fully expanded name (but omitting Standard at the start). For example,
68 -- if a library level child package P.Q has an embedded package R, and
69 -- there is an entity in this embdded package whose name is S, the encoded
70 -- name will include the components p.q.r.s.
72 -- For local entities, the encoded name only includes the components
73 -- up to the enclosing dynamic scope (other than a block). At run time,
74 -- such a dynamic scope is a subprogram, and the debugging formats know
75 -- about local variables of procedures, so it is not necessary to have
76 -- full qualification for such entities. In particular this means that
77 -- direct local variables of a procedure are not qualified.
79 -- As an example of the local name convention, consider a procedure V.W
80 -- with a local variable X, and a nested block Y containing an entity
81 -- Z. The fully qualified names of the entities X and Z are:
86 -- but since V.W is a subprogram, the encoded names will end up
92 -- The separating dots are translated into double underscores.
94 -----------------------------
95 -- Handling of Overloading --
96 -----------------------------
98 -- The above scheme is incomplete with respect to overloaded
99 -- subprograms, since overloading can legitimately result in a
100 -- case of two entities with exactly the same fully qualified names.
101 -- To distinguish between entries in a set of overloaded subprograms,
102 -- the encoded names are serialized by adding the suffix:
104 -- __nn (two underscores)
106 -- where nn is a serial number (2 for the second overloaded function,
107 -- 3 for the third, etc.). A suffix of __1 is always omitted (i.e. no
108 -- suffix implies the first instance).
110 -- These names are prefixed by the normal full qualification. So
111 -- for example, the third instance of the subprogram qrs in package
112 -- yz would have the name:
116 -- A more subtle case arises with entities declared within overloaded
117 -- subprograms. If we have two overloaded subprograms, and both declare
118 -- an entity xyz, then the fully expanded name of the two xyz's is the
119 -- same. To distinguish these, we add the same __n suffix at the end of
120 -- the inner entity names.
122 -- In more complex cases, we can have multiple levels of overloading,
123 -- and we must make sure to distinguish which final declarative region
124 -- we are talking about. For this purpose, we use a more complex suffix
125 -- which has the form:
129 -- where the nn values are the homonym numbers as needed for any of
130 -- the qualifying entities, separated by a single underscore. If all
131 -- the nn values are 1, the suffix is omitted, Otherwise the suffix
132 -- is present (including any values of 1). The following example
133 -- shows how this suffixing works.
135 -- package body Yz is
136 -- procedure Qrs is -- Name is yz__qrs
137 -- procedure Tuv is ... end; -- Name is yz__qrs__tuv
138 -- begin ... end Qrs;
140 -- procedure Qrs (X: Int) is -- Name is yz__qrs__2
141 -- procedure Tuv is ... end; -- Name is yz__qrs__tuv__2_1
142 -- procedure Tuv (X: Int) is -- Name is yz__qrs__tuv__2_2
143 -- begin ... end Tuv;
145 -- procedure Tuv (X: Float) is -- Name is yz__qrs__tuv__2_3
146 -- type m is new float; -- Name is yz__qrs__tuv__m__2_3
147 -- begin ... end Tuv;
148 -- begin ... end Qrs;
155 -- The above rules applied to operator names would result in names
156 -- with quotation marks, which are not typically allowed by assemblers
157 -- and linkers, and even if allowed would be odd and hard to deal with.
158 -- To avoid this problem, operator names are encoded as follows:
180 -- These names are prefixed by the normal full qualification, and
181 -- suffixed by the overloading identification. So for example, the
182 -- second operator "=" defined in package Extra.Messages would
185 -- extra__messages__Oeq__2
187 ----------------------------------
188 -- Resolving Other Name Clashes --
189 ----------------------------------
191 -- It might be thought that the above scheme is complete, but in Ada 95,
192 -- full qualification is insufficient to uniquely identify an entity
193 -- in the program, even if it is not an overloaded subprogram. There
194 -- are two possible confusions:
198 -- interpretation 1: entity b in body of package a
199 -- interpretation 2: child procedure b of package a
203 -- interpretation 1: entity c in child package a.b
204 -- interpretation 2: entity c in nested package b in body of a
206 -- It is perfectly legal in both cases for both interpretations to
207 -- be valid within a single program. This is a bit of a surprise since
208 -- certainly in Ada 83, full qualification was sufficient, but not in
209 -- Ada 95. The result is that the above scheme can result in duplicate
210 -- names. This would not be so bad if the effect were just restricted
211 -- to debugging information, but in fact in both the above cases, it
212 -- is possible for both symbols to be external names, and so we have
213 -- a real problem of name clashes.
215 -- To deal with this situation, we provide two additional encoding
218 -- First: all library subprogram names are preceded by the string
219 -- _ada_ (which causes no duplications, since normal Ada names can
220 -- never start with an underscore. This not only solves the first
221 -- case of duplication, but also solves another pragmatic problem
222 -- which is that otherwise Ada procedures can generate names that
223 -- clash with existing system function names. Most notably, we can
224 -- have clashes in the case of procedure Main with the C main that
225 -- in some systems is always present.
227 -- Second, for the case where nested packages declared in package
228 -- bodies can cause trouble, we add a suffix which shows which
229 -- entities in the list are body-nested packages, i.e. packages
230 -- whose spec is within a package body. The rules are as follows,
231 -- given a list of names in a qualified name name1.name2....
233 -- If none are body-nested package entities, then there is no suffix
235 -- If at least one is a body-nested package entity, then the suffix
236 -- is X followed by a string of b's and n's (b = body-nested package
237 -- entity, n = not a body-nested package).
239 -- There is one element in this string for each entity in the encoded
240 -- expanded name except the first (the rules are such that the first
241 -- entity of the encoded expanded name can never be a body-nested'
242 -- package. Trailing n's are omitted, as is the last b (there must
243 -- be at least one b, or we would not be generating a suffix at all).
245 -- For example, suppose we have
248 -- pragma Elaborate_Body;
249 -- m1 : integer; -- #1
253 -- package y is m2 : integer; end y; -- #2
255 -- package z is r : integer; end z; -- #3
257 -- m3 : integer; -- #4
261 -- pragma Elaborate_Body;
262 -- m2 : integer; -- #5
265 -- package body x.y is
266 -- m3 : integer; -- #6
267 -- procedure j is -- #7
269 -- z : integer; -- #8
276 -- procedure x.m3 is begin null; end; -- #9
278 -- Then the encodings would be:
280 -- #1. x__m1 (no BNPE's in sight)
281 -- #2. x__y__m2X (y is a BNPE)
282 -- #3. x__y__z__rXb (y is a BNPE, so is z)
283 -- #4. x__m3 (no BNPE's in sight)
284 -- #5. x__y__m2 (no BNPE's in sight)
285 -- #6. x__y__m3 (no BNPE's in signt)
286 -- #7. x__y__j (no BNPE's in sight)
287 -- #8. k__z (no BNPE's, only up to procedure)
288 -- #9 _ada_x__m3 (library level subprogram)
290 -- Note that we have instances here of both kind of potential name
291 -- clashes, and the above examples show how the encodings avoid the
294 -- Lines #4 and #9 both refer to the entity x.m3, but #9 is a library
295 -- level subprogram, so it is preceded by the string _ada_ which acts
296 -- to distinguish it from the package body entity.
298 -- Lines #2 and #5 both refer to the entity x.y.m2, but the first
299 -- instance is inside the body-nested package y, so there is an X
300 -- suffix to distinguish it from the child library entity.
302 -- Note that enumeration literals never need Xb type suffixes, since
303 -- they are never referenced using global external names.
305 ---------------------
306 -- Interface Names --
307 ---------------------
309 -- Note: if an interface name is present, then the external name
310 -- is taken from the specified interface name. Given the current
311 -- limitations of the gcc backend, this means that the debugging
312 -- name is also set to the interface name, but conceptually, it
313 -- would be possible (and indeed desirable) to have the debugging
314 -- information still use the Ada name as qualified above, so we
315 -- still fully qualify the name in the front end.
317 -------------------------------------
318 -- Encodings Related to Task Types --
319 -------------------------------------
321 -- Each task object defined by a single task declaration is associated
322 -- with a prefix that is used to qualify procedures defined in that
326 -- task body TaskObj is
327 -- procedure F1 is ... end;
333 -- The name of subprogram TaskObj.F1 is encoded as p__taskobjTK__f1,
334 -- The body, B, is contained in a subprogram whose name is
337 ------------------------------------------
338 -- Encodings Related to Protected Types --
339 ------------------------------------------
341 -- Each protected type has an associated record type, that describes
342 -- the actual layout of the private data. In addition to the private
343 -- components of the type, the Corresponding_Record_Type includes one
344 -- component of type Protection, which is the actual lock structure.
345 -- The run-time size of the protected type is the size of the corres-
348 -- For a protected type prot, the Corresponding_Record_Type is encoded
351 -- The operations of a protected type are encoded as follows: each
352 -- operation results in two subprograms, a locking one that is called
353 -- from outside of the object, and a non-locking one that is used for
354 -- calls from other operations on the same object. The locking operation
355 -- simply acquires the lock, and then calls the non-locking version.
356 -- The names of all of these have a prefix constructed from the name of
357 -- the type, and a suffix which is P or N, depending on whether this is
358 -- the protected/non-locking version of the operation.
360 -- Operations generated for protected entries follow the same encoding.
361 -- Each entry results in two suprograms: a procedure that holds the
362 -- entry body, and a function that holds the evaluation of the barrier.
363 -- The names of these subprograms include the prefix 'E' or 'B' res-
364 -- pectively. The names also include a numeric suffix to render them
365 -- unique in the presence of overloaded entries.
367 -- Given the declaration:
369 -- protected type Lock is
370 -- function Get return Integer;
371 -- procedure Set (X: Integer);
372 -- entry Update (Val : Integer);
374 -- Value : Integer := 0;
377 -- the following operations are created:
388 ----------------------------------------------------
389 -- Conversion between Entities and External Names --
390 ----------------------------------------------------
392 No_Dollar_In_Label : constant Boolean := True;
393 -- True iff the target does not allow dollar signs ("$") in external names
394 -- ??? We want to migrate all platforms to use the same convention.
395 -- As a first step, we force this constant to always be True. This
396 -- constant will eventually be deleted after we have verified that
397 -- the migration does not cause any unforseen adverse impact.
398 -- We chose "__" because it is supported on all platforms, which is
399 -- not the case of "$".
401 procedure Get_External_Name
403 Has_Suffix : Boolean);
404 -- Set Name_Buffer and Name_Len to the external name of entity E.
405 -- The external name is the Interface_Name, if specified, unless
406 -- the entity has an address clause or a suffix.
408 -- If the Interface is not present, or not used, the external name
409 -- is the concatenation of:
411 -- - the string "_ada_", if the entity is a library subprogram,
412 -- - the names of any enclosing scopes, each followed by "__",
413 -- or "X_" if the next entity is a subunit)
414 -- - the name of the entity
415 -- - the string "$" (or "__" if target does not allow "$"), followed
416 -- by homonym suffix, if the entity is an overloaded subprogram
417 -- or is defined within an overloaded subprogram.
419 procedure Get_External_Name_With_Suffix
422 -- Set Name_Buffer and Name_Len to the external name of entity E.
423 -- If Suffix is the empty string the external name is as above,
424 -- otherwise the external name is the concatenation of:
426 -- - the string "_ada_", if the entity is a library subprogram,
427 -- - the names of any enclosing scopes, each followed by "__",
428 -- or "X_" if the next entity is a subunit)
429 -- - the name of the entity
430 -- - the string "$" (or "__" if target does not allow "$"), followed
431 -- by homonym suffix, if the entity is an overloaded subprogram
432 -- or is defined within an overloaded subprogram.
433 -- - the string "___" followed by Suffix
435 -- Note that a call to this procedure has no effect if we are not
436 -- generating code, since the necessary information for computing the
437 -- proper encoded name is not available in this case.
439 --------------------------------------------
440 -- Subprograms for Handling Qualification --
441 --------------------------------------------
443 procedure Qualify_Entity_Names (N : Node_Id);
444 -- Given a node N, that represents a block, subprogram body, or package
445 -- body or spec, or protected or task type, sets a fully qualified name
446 -- for the defining entity of given construct, and also sets fully
447 -- qualified names for all enclosed entities of the construct (using
448 -- First_Entity/Next_Entity). Note that the actual modifications of the
449 -- names is postponed till a subsequent call to Qualify_All_Entity_Names.
450 -- Note: this routine does not deal with prepending _ada_ to library
451 -- subprogram names. The reason for this is that we only prepend _ada_
452 -- to the library entity itself, and not to names built from this name.
454 procedure Qualify_All_Entity_Names;
455 -- When Qualify_Entity_Names is called, no actual name changes are made,
456 -- i.e. the actual calls to Qualify_Entity_Name are deferred until a call
457 -- is made to this procedure. The reason for this deferral is that when
458 -- names are changed semantic processing may be affected. By deferring
459 -- the changes till just before gigi is called, we avoid any concerns
460 -- about such effects. Gigi itself does not use the names except for
461 -- output of names for debugging purposes (which is why we are doing
462 -- the name changes in the first place.
464 -- Note: the routines Get_Unqualified_[Decoded]_Name_String in Namet
465 -- are useful to remove qualification from a name qualified by the
466 -- call to Qualify_All_Entity_Names.
468 --------------------------------
469 -- Handling of Numeric Values --
470 --------------------------------
472 -- All numeric values here are encoded as strings of decimal digits.
473 -- Only integer values need to be encoded. A negative value is encoded
474 -- as the corresponding positive value followed by a lower case m for
475 -- minus to indicate that the value is negative (e.g. 2m for -2).
477 -------------------------
478 -- Type Name Encodings --
479 -------------------------
481 -- In the following typ is the name of the type as normally encoded by
482 -- the debugger rules, i.e. a non-qualified name, all in lower case,
483 -- with standard encoding of upper half and wide characters
485 ------------------------
486 -- Encapsulated Types --
487 ------------------------
489 -- In some cases, the compiler encapsulates a type by wrapping it in
490 -- a structure. For example, this is used when a size or alignment
491 -- specification requires a larger type. Consider:
493 -- type y is mod 2 ** 64;
494 -- for y'size use 256;
496 -- In this case the compile generates a structure type y___PAD, which
497 -- has a single field whose name is F. This single field is 64 bits
498 -- long and contains the actual value. This kind of padding is used
499 -- when the logical value to be stored is shorter than the object in
500 -- which it is allocated. For example if a size clause is used to set
501 -- a size of 256 for a signed integer value, then a typical choice is
502 -- to wrap a 64-bit integer in a 256 bit PAD structure.
504 -- A similar encapsulation is done for some packed array types,
505 -- in which case the structure type is y___JM and the field name
506 -- is OBJECT. This is used in the case of a packed array stored
507 -- in modular representation (see section on representation of
508 -- packed array objects). In this case the JM wrapping is used to
509 -- achieve correct positioning of the packed array value (left or
510 -- right justified in its field depending on endianness.
512 -- When the debugger sees an object of a type whose name has a
513 -- suffix of ___PAD or ___JM, the type will be a record containing
514 -- a single field, and the name of that field will be all upper case.
515 -- In this case, it should look inside to get the value of the inner
516 -- field, and neither the outer structure name, nor the field name
517 -- should appear when the value is printed.
519 -----------------------
520 -- Fixed-Point Types --
521 -----------------------
523 -- Fixed-point types are encoded using a suffix that indicates the
524 -- delta and small values. The actual type itself is a normal
528 -- typ___XF_nn_dd_nn_dd
530 -- The first form is used when small = delta. The value of delta (and
531 -- small) is given by the rational nn/dd, where nn and dd are decimal
534 -- The second form is used if the small value is different from the
535 -- delta. In this case, the first nn/dd rational value is for delta,
536 -- and the second value is for small.
538 ------------------------------
539 -- VAX Floating-Point Types --
540 ------------------------------
542 -- Vax floating-point types are represented at run time as integer
543 -- types, which are treated specially by the code generator. Their
544 -- type names are encoded with the following suffix:
550 -- representing the Vax F Float, D Float, and G Float types. The
551 -- debugger must treat these specially. In particular, printing
552 -- these values can be achieved using the debug procedures that
553 -- are provided in package System.Vax_Float_Operations:
555 -- procedure Debug_Output_D (Arg : D);
556 -- procedure Debug_Output_F (Arg : F);
557 -- procedure Debug_Output_G (Arg : G);
559 -- These three procedures take a Vax floating-point argument, and
560 -- output a corresponding decimal representation to standard output
561 -- with no terminating line return.
567 -- Discrete types are coded with a suffix indicating the range in
568 -- the case where one or both of the bounds are discriminants or
571 -- Note: at the current time, we also encode compile time known
572 -- bounds if they do not match the natural machine type bounds,
573 -- but this may be removed in the future, since it is redundant
574 -- for most debugging formats. However, we do not ever need XD
575 -- encoding for enumeration base types, since here it is always
576 -- clear what the bounds are from the total number of enumeration
577 -- literals, and of course we do not need to encode the dummy XR
578 -- types generated for renamings.
581 -- typ___XDL_lowerbound
582 -- typ___XDU_upperbound
583 -- typ___XDLU_lowerbound__upperbound
585 -- If a discrete type is a natural machine type (i.e. its bounds
586 -- correspond in a natural manner to its size), then it is left
587 -- unencoded. The above encoding forms are used when there is a
588 -- constrained range that does not correspond to the size or that
589 -- has discriminant references or other compile time known bounds.
591 -- The first form is used if both bounds are dynamic, in which case
592 -- two constant objects are present whose names are typ___L and
593 -- typ___U in the same scope as typ, and the values of these constants
594 -- indicate the bounds. As far as the debugger is concerned, these
595 -- are simply variables that can be accessed like any other variables.
596 -- In the enumeration case, these values correspond to the Enum_Rep
597 -- values for the lower and upper bounds.
599 -- The second form is used if the upper bound is dynamic, but the
600 -- lower bound is either constant or depends on a discriminant of
601 -- the record with which the type is associated. The upper bound
602 -- is stored in a constant object of name typ___U as previously
603 -- described, but the lower bound is encoded directly into the
604 -- name as either a decimal integer, or as the discriminant name.
606 -- The third form is similarly used if the lower bound is dynamic,
607 -- but the upper bound is compile time known or a discriminant
608 -- reference, in which case the lower bound is stored in a constant
609 -- object of name typ___L, and the upper bound is encoded directly
610 -- into the name as either a decimal integer, or as the discriminant
613 -- The fourth form is used if both bounds are discriminant references
614 -- or compile time known values, with the encoding first for the lower
615 -- bound, then for the upper bound, as previously described.
625 -- Is encoded as a subrange of an unsigned base type with lower bound
626 -- 0 and upper bound N. That is, there is no name encoding. We use
627 -- the standard encodings provided by the debugging format. Thus
628 -- we give these types a non-standard interpretation: the standard
629 -- interpretation of our encoding would not, in general, imply that
630 -- arithmetic on type x was to be performed modulo N (especially not
631 -- when N is not a power of 2).
637 -- Only discrete types can be biased, and the fact that they are
638 -- biased is indicated by a suffix of the form:
640 -- typ___XB_lowerbound__upperbound
642 -- Here lowerbound and upperbound are decimal integers, with the
643 -- usual (postfix "m") encoding for negative numbers. Biased
644 -- types are only possible where the bounds are compile time
645 -- known, and the values are represented as unsigned offsets
646 -- from the lower bound given. For example:
648 -- type Q is range 10 .. 15;
651 -- The size clause will force values of type Q in memory to be
652 -- stored in biased form (e.g. 11 will be represented by the
655 ----------------------------------------------
656 -- Record Types with Variable-Length Fields --
657 ----------------------------------------------
659 -- The debugging formats do not fully support these types, and indeed
660 -- some formats simply generate no useful information at all for such
661 -- types. In order to provide information for the debugger, gigi creates
662 -- a parallel type in the same scope with one of the names
667 -- The former name is used for a record and the latter for the union
668 -- that is made for a variant record (see below) if that record or
669 -- union has a field of variable size or if the record or union itself
670 -- has a variable size. These encodings suffix any other encodings that
671 -- that might be suffixed to the type name.
673 -- The idea here is to provide all the needed information to interpret
674 -- objects of the original type in the form of a "fixed up" type, which
675 -- is representable using the normal debugging information.
677 -- There are three cases to be dealt with. First, some fields may have
678 -- variable positions because they appear after variable-length fields.
679 -- To deal with this, we encode *all* the field bit positions of the
680 -- special ___XV type in a non-standard manner.
682 -- The idea is to encode not the position, but rather information
683 -- that allows computing the position of a field from the position
684 -- of the previous field. The algorithm for computing the actual
685 -- positions of all fields and the length of the record is as
686 -- follows. In this description, let P represent the current
687 -- bit position in the record.
689 -- 1. Initialize P to 0.
691 -- 2. For each field in the record,
693 -- 2a. If an alignment is given (see below), then round P
694 -- up, if needed, to the next multiple of that alignment.
696 -- 2b. If a bit position is given, then increment P by that
697 -- amount (that is, treat it as an offset from the end of the
698 -- preceding record).
700 -- 2c. Assign P as the actual position of the field.
702 -- 2d. Compute the length, L, of the represented field (see below)
703 -- and compute P'=P+L. Unless the field represents a variant part
704 -- (see below and also Variant Record Encoding), set P to P'.
706 -- The alignment, if present, is encoded in the field name of the
707 -- record, which has a suffix:
711 -- where the nn after the XVA indicates the alignment value in storage
712 -- units. This encoding is present only if an alignment is present.
714 -- The size of the record described by an XVE-encoded type (in bits)
715 -- is generally the maximum value attained by P' in step 2d above,
716 -- rounded up according to the record's alignment.
718 -- Second, the variable-length fields themselves are represented by
719 -- replacing the type by a special access type. The designated type
720 -- of this access type is the original variable-length type, and the
721 -- fact that this field has been transformed in this way is signalled
722 -- by encoding the field name as:
726 -- where field is the original field name. If a field is both
727 -- variable-length and also needs an alignment encoding, then the
728 -- encodings are combined using:
732 -- Note: the reason that we change the type is so that the resulting
733 -- type has no variable-length fields. At least some of the formats
734 -- used for debugging information simply cannot tolerate variable-
735 -- length fields, so the encoded information would get lost.
737 -- Third, in the case of a variant record, the special union
738 -- that contains the variants is replaced by a normal C union.
739 -- In this case, the positions are all zero.
741 -- Discriminants appear before any variable-length fields that depend
742 -- on them, with one exception. In some cases, a discriminant
743 -- governing the choice of a variant clause may appear in the list
744 -- of fields of an XVE type after the entry for the variant clause
745 -- itself (this can happen in the presence of a representation clause
746 -- for the record type in the source program). However, when this
747 -- happens, the discriminant's position may be determined by first
748 -- applying the rules described in this section, ignoring the variant
749 -- clause. As a result, discriminants can always be located
750 -- independently of the variable-length fields that depend on them.
752 -- The size of the ___XVE or ___XVU record or union is set to the
753 -- alignment (in bytes) of the original object so that the debugger
754 -- can calculate the size of the original type.
756 -- As an example of this encoding, consider the declarations:
758 -- type Q is array (1 .. V1) of Float; -- alignment 4
759 -- type R is array (1 .. V2) of Long_Float; -- alignment 8
764 -- C : String (1 .. V3);
771 -- The encoded type looks like:
773 -- type anonymousQ is access Q;
774 -- type anonymousR is access R;
776 -- type X___XVE is record
777 -- A : Character; -- position contains 0
778 -- B : Float; -- position contains 24
779 -- C___XVL : access String (1 .. V3); -- position contains 0
780 -- D___XVA4 : Float; -- position contains 0
781 -- E___XVL4 : anonymousQ; -- position contains 0
782 -- F___XVL8 : anonymousR; -- position contains 0
783 -- G : Float; -- position contains 0
786 -- Any bit sizes recorded for fields other than dynamic fields and
787 -- variants are honored as for ordinary records.
791 -- 1) The B field could also have been encoded by using a position
792 -- of zero, and an alignment of 4, but in such a case, the coding by
793 -- position is preferred (since it takes up less space). We have used
794 -- the (illegal) notation access xxx as field types in the example
797 -- 2) The E field does not actually need the alignment indication
798 -- but this may not be detected in this case by the conversion
801 -- 3) Our conventions do not cover all XVE-encoded records in which
802 -- some, but not all, fields have representation clauses. Such
803 -- records may, therefore, be displayed incorrectly by debuggers.
804 -- This situation is not common.
806 -----------------------
807 -- Base Record Types --
808 -----------------------
810 -- Under certain circumstances, debuggers need two descriptions
811 -- of a record type, one that gives the actual details of the
812 -- base type's structure (as described elsewhere in these
813 -- comments) and one that may be used to obtain information
814 -- about the particular subtype and the size of the objects
815 -- being typed. In such cases the compiler will substitute a
816 -- type whose name is typically compiler-generated and
817 -- irrelevant except as a key for obtaining the actual type.
818 -- Specifically, if this name is x, then we produce a record
819 -- type named x___XVS consisting of one field. The name of
820 -- this field is that of the actual type being encoded, which
821 -- we'll call y (the type of this single field is arbitrary).
822 -- Both x and y may have corresponding ___XVE types.
824 -- The size of the objects typed as x should be obtained from
825 -- the structure of x (and x___XVE, if applicable) as for
826 -- ordinary types unless there is a variable named x___XVZ, which,
827 -- if present, will hold the the size (in bits) of x.
829 -- The type x will either be a subtype of y (see also Subtypes
830 -- of Variant Records, below) or will contain no fields at
831 -- all. The layout, types, and positions of these fields will
832 -- be accurate, if present. (Currently, however, the GDB
833 -- debugger makes no use of x except to determine its size).
835 -- Among other uses, XVS types are sometimes used to encode
836 -- unconstrained types. For example, given
838 -- subtype Int is INTEGER range 0..10;
839 -- type T1 (N: Int := 0) is record
840 -- F1: String (1 .. N);
842 -- type AT1 is array (INTEGER range <>) of T1;
844 -- the element type for AT1 might have a type defined as if it had
847 -- type at1___C_PAD is record null; end record;
848 -- for at1___C_PAD'Size use 16 * 8;
850 -- and there would also be
852 -- type at1___C_PAD___XVS is record t1: Integer; end record;
855 -- Had the subtype Int been dynamic:
857 -- subtype Int is INTEGER range 0 .. M; -- M a variable
859 -- Then the compiler would also generate a declaration whose effect
862 -- at1___C_PAD___XVZ: constant Integer := 32 + M * 8 + padding term;
864 -- Not all unconstrained types are so encoded; the XVS
865 -- convention may be unnecessary for unconstrained types of
866 -- fixed size. However, this encoding is always necessary when
867 -- a subcomponent type (array element's type or record field's
868 -- type) is an unconstrained record type some of whose
869 -- components depend on discriminant values.
875 -- Since there is no way for the debugger to obtain the index subtypes
876 -- for an array type, we produce a type that has the name of the
877 -- array type followed by "___XA" and is a record whose field names
878 -- are the names of the types for the bounds. The types of these
879 -- fields is an integer type which is meaningless.
881 -- To conserve space, we do not produce this type unless one of
882 -- the index types is either an enumeration type, has a variable
883 -- upper bound, has a lower bound different from the constant 1,
884 -- is a biased type, or is wider than "sizetype".
886 -- Given the full encoding of these types (see above description for
887 -- the encoding of discrete types), this means that all necessary
888 -- information for addressing arrays is available. In some
889 -- debugging formats, some or all of the bounds information may
890 -- be available redundantly, particularly in the fixed-point case,
891 -- but this information can in any case be ignored by the debugger.
893 ----------------------------
894 -- Note on Implicit Types --
895 ----------------------------
897 -- The compiler creates implicit type names in many situations where
898 -- a type is present semantically, but no specific name is present.
901 -- S : Integer range M .. N;
903 -- Here the subtype of S is not integer, but rather an anonymous
904 -- subtype of Integer. Where possible, the compiler generates names
905 -- for such anonymous types that are related to the type from which
906 -- the subtype is obtained as follows:
910 -- where name is the name from which the subtype is obtained, using
911 -- lower case letters and underscores, and suffix starts with an upper
912 -- case letter. For example, the name for the above declaration of S
917 -- If the debugger is asked to give the type of an entity and the type
918 -- has the form T name suffix, it is probably appropriate to just use
919 -- "name" in the response since this is what is meaningful to the
922 -------------------------------------------------
923 -- Subprograms for Handling Encoded Type Names --
924 -------------------------------------------------
926 procedure Get_Encoded_Name (E : Entity_Id);
927 -- If the entity is a typename, store the external name of the entity as in
928 -- Get_External_Name, followed by three underscores plus the type encoding
929 -- in Name_Buffer with the length in Name_Len, and an ASCII.NUL character
930 -- stored following the name. Otherwise set Name_Buffer and Name_Len to
931 -- hold the entity name. Note that a call to this procedure has no effect
932 -- if we are not generating code, since the necessary information for
933 -- computing the proper encoded name is not available in this case.
939 -- Debugging information is generated for exception, object, package,
940 -- and subprogram renaming (generic renamings are not significant, since
941 -- generic templates are not relevant at debugging time).
943 -- Consider a renaming declaration of the form
947 -- There is one case in which no special debugging information is required,
948 -- namely the case of an object renaming where the backend allocates a
949 -- reference for the renamed variable, and the entity x is this reference.
950 -- The debugger can handle this case without any special processing or
951 -- encoding (it won't know it was a renaming, but that does not matter).
953 -- All other cases of renaming generate a dummy type definition for
954 -- an entity whose name is:
956 -- x___XR for an object renaming
957 -- x___XRE for an exception renaming
958 -- x___XRP for a package renaming
960 -- The name is fully qualified in the usual manner, i.e. qualified in
961 -- the same manner as the entity x would be. In the case of a package
962 -- renaming where x is a child unit, the qualification includes the
963 -- name of the parent unit, to disambiguate child units with the same
964 -- simple name and (of necessity) different parents.
966 -- Note: subprogram renamings are not encoded at the present time.
968 -- The type is an enumeration type with a single enumeration literal
969 -- that is an identifier which describes the renamed variable.
971 -- For the simple entity case, where y is an entity name,
972 -- the enumeration is of the form:
976 -- i.e. the enumeration type has a single field, whose name
977 -- matches the name y, with the XE suffix. The entity for this
978 -- enumeration literal is fully qualified in the usual manner.
979 -- All subprogram, exception, and package renamings fall into
980 -- this category, as well as simple object renamings.
982 -- For the object renaming case where y is a selected component or an
983 -- indexed component, the literal name is suffixed by additional fields
984 -- that give details of the components. The name starts as above with
985 -- a y___XE entity indicating the outer level variable. Then a series
986 -- of selections and indexing operations can be specified as follows:
990 -- A series of subscript values appear in sequence, the number
991 -- corresponds to the number of dimensions of the array. The
992 -- subscripts have one of the following two forms:
996 -- Here nnn is a constant value, encoded as a decimal
997 -- integer (pos value for enumeration type case). Negative
998 -- values have a trailing 'm' as usual.
1002 -- Here e is the (unqualified) name of a constant entity in
1003 -- the same scope as the renaming which contains the subscript
1008 -- For the slice case, we have two entries. The first is for
1009 -- the lower bound of the slice, and has the form
1014 -- Specifies the lower bound, using exactly the same encoding
1015 -- as for an XS subscript as described above.
1017 -- Then the upper bound appears in the usual XSnnn/XSe form
1019 -- Selected component
1021 -- For a selected component, we have a single entry
1025 -- Here f is the field name for the selection
1027 -- For an explicit deference (.all), we have a single entry
1031 -- As an example, consider the declarations:
1035 -- m : string (2 .. 5);
1038 -- type r is array (1 .. 10, 1 .. 20) of q;
1042 -- z : string renames g (1,5).m(2 ..3)
1045 -- The generated type definition would appear as
1047 -- type p__z___XR is
1048 -- (p__g___XEXS1XS5XRmXL2XS3);
1049 -- p__g___XE--------------------outer entity is g
1050 -- XS1-----------------first subscript for g
1051 -- XS5--------------second subscript for g
1052 -- XRm-----------select field m
1053 -- XL2--------lower bound of slice
1054 -- XS3-----upper bound of slice
1056 function Debug_Renaming_Declaration (N : Node_Id) return Node_Id;
1057 -- The argument N is a renaming declaration. The result is a type
1058 -- declaration as described in the above paragraphs. If not special
1059 -- debug declaration, than Empty is returned.
1061 ---------------------------
1062 -- Packed Array Encoding --
1063 ---------------------------
1065 -- For every packed array, two types are created, and both appear in
1066 -- the debugging output.
1068 -- The original declared array type is a perfectly normal array type,
1069 -- and its index bounds indicate the original bounds of the array.
1071 -- The corresponding packed array type, which may be a modular type, or
1072 -- may be an array of bytes type (see Exp_Pakd for full details). This
1073 -- is the type that is actually used in the generated code and for
1074 -- debugging information for all objects of the packed type.
1076 -- The name of the corresponding packed array type is:
1081 -- ttt is the name of the original declared array
1082 -- nnn is the component size in bits (1-31)
1084 -- When the debugger sees that an object is of a type that is encoded
1085 -- in this manner, it can use the original type to determine the bounds,
1086 -- and the component size to determine the packing details.
1088 -------------------------------------------
1089 -- Packed Array Representation in Memory --
1090 -------------------------------------------
1092 -- Packed arrays are represented in tightly packed form, with no extra
1093 -- bits between components. This is true even when the component size
1094 -- is not a factor of the storage unit size, so that as a result it is
1095 -- possible for components to cross storage unit boundaries.
1097 -- The layout in storage is identical, regardless of whether the
1098 -- implementation type is a modular type or an array-of-bytes type.
1099 -- See Exp_Pakd for details of how these implementation types are used,
1100 -- but for the purpose of the debugger, only the starting address of
1101 -- the object in memory is significant.
1103 -- The following example should show clearly how the packing works in
1104 -- the little-endian and big-endian cases:
1106 -- type B is range 0 .. 7;
1107 -- for B'Size use 3;
1109 -- type BA is array (0 .. 5) of B;
1110 -- pragma Pack (BA);
1112 -- BV : constant BA := (1,2,3,4,5,6);
1114 -- Little endian case
1116 -- BV'Address + 2 BV'Address + 1 BV'Address + 0
1117 -- +-----------------+-----------------+-----------------+
1118 -- | ? ? ? ? ? ? 1 1 | 0 1 0 1 1 0 0 0 | 1 1 0 1 0 0 0 1 |
1119 -- +-----------------+-----------------+-----------------+
1120 -- <---------> <-----> <---> <---> <-----> <---> <--->
1121 -- unused bits BV(5) BV(4) BV(3) BV(2) BV(1) BV(0)
1125 -- BV'Address + 0 BV'Address + 1 BV'Address + 2
1126 -- +-----------------+-----------------+-----------------+
1127 -- | 0 0 1 0 1 0 0 1 | 1 1 0 0 1 0 1 1 | 1 0 ? ? ? ? ? ? |
1128 -- +-----------------+-----------------+-----------------+
1129 -- <---> <---> <-----> <---> <---> <-----> <--------->
1130 -- BV(0) BV(1) BV(2) BV(3) BV(4) BV(5) unused bits
1132 -- Note that if a modular type is used to represent the array, the
1133 -- allocation in memory is not the same as a normal modular type.
1134 -- The difference occurs when the allocated object is larger than
1135 -- the size of the array. For a normal modular type, we extend the
1136 -- value on the left with zeroes.
1138 -- For example, in the normal modular case, if we have a 6-bit
1139 -- modular type, declared as mod 2**6, and we allocate an 8-bit
1140 -- object for this type, then we extend the value with two bits
1141 -- on the most significant end, and in either the little-endian
1142 -- or big-endian case, the value 63 is represented as 00111111
1143 -- in binary in memory.
1145 -- For a modular type used to represent a packed array, the rule is
1146 -- different. In this case, if we have to extend the value, then we
1147 -- do it with undefined bits (which are not initialized and whose value
1148 -- is irrelevant to any generated code). Furthermore these bits are on
1149 -- the right (least significant bits) in the big-endian case, and on the
1150 -- left (most significant bits) in the little-endian case.
1152 -- For example, if we have a packed boolean array of 6 bits, all set
1153 -- to True, stored in an 8-bit object, then the value in memory in
1154 -- binary is ??111111 in the little-endian case, and 111111?? in the
1157 -- This is done so that the representation of packed arrays does not
1158 -- depend on whether we use a modular representation or array of bytes
1159 -- as previously described. This ensures that we can pass such values
1160 -- by reference in the case where a subprogram has to be able to handle
1161 -- values stored in either form.
1163 -- Note that when we extract the value of such a modular packed array,
1164 -- we expect to retrieve only the relevant bits, so in this same example,
1165 -- when we extract the value, we get 111111 in both cases, and the code
1166 -- generated by the front end assumes this, although it does not assume
1167 -- that any high order bits are defined.
1169 -- There are opportunities for optimization based on the knowledge that
1170 -- the unused bits are irrelevant for these type of packed arrays. For
1171 -- example if we have two such 6-bit-in-8-bit values and we do an
1176 -- Then logically, we extract the 6 bits and store only 6 bits in the
1177 -- result, but the back end is free to simply assign the entire 8-bits
1178 -- in this case, since we don't actually care about the undefined bits.
1179 -- However, in the equality case, it is important to ensure that the
1180 -- undefined bits do not participate in an equality test.
1182 -- If a modular packed array value is assigned to a register, then
1183 -- logically it could always be held right justified, to avoid any
1184 -- need to shift, e.g. when doing comparisons. But probably this is
1185 -- a bad choice, as it would mean that an assignment such as a := b
1186 -- above would require shifts when one value is in a register and the
1187 -- other value is in memory.
1189 ------------------------------------------------------
1190 -- Subprograms for Handling Packed Array Type Names --
1191 ------------------------------------------------------
1193 function Make_Packed_Array_Type_Name
1197 -- This function is used in Exp_Pakd to create the name that is encoded
1198 -- as described above. The entity Typ provides the name ttt, and the
1199 -- value Csize is the component size that provides the nnn value.
1201 --------------------------------------
1202 -- Pointers to Unconstrained Arrays --
1203 --------------------------------------
1205 -- There are two kinds of pointers to arrays. The debugger can tell
1206 -- which format is in use by the form of the type of the pointer.
1210 -- Fat pointers are represented as a struct with two fields. This
1211 -- struct has two distinguished field names:
1213 -- P_ARRAY is a pointer to the array type. The name of this
1214 -- type is the unconstrained type followed by "___XUA". This
1215 -- array will have bounds which are the discriminants, and
1216 -- hence are unparsable, but will give the number of
1217 -- subscripts and the component type.
1219 -- P_BOUNDS is a pointer to a struct, the name of whose type is the
1220 -- unconstrained array name followed by "___XUB" and which has
1221 -- fields of the form
1223 -- LBn (n a decimal integer) lower bound of n'th dimension
1224 -- UBn (n a decimal integer) upper bound of n'th dimension
1226 -- The bounds may be any integral type. In the case of an
1227 -- enumeration type, Enum_Rep values are used.
1229 -- The debugging information will sometimes reference an anonymous
1230 -- fat pointer type. Such types are given the name xxx___XUP, where
1231 -- xxx is the name of the designated type. If the debugger is asked
1232 -- to output such a type name, the appropriate form is "access xxx".
1236 -- The value of a thin pointer is a pointer to the second field
1237 -- of a structure with two fields. The name of this structure's
1238 -- type is "arr___XUT", where "arr" is the name of the
1239 -- unconstrained array type. Even though it actually points into
1240 -- middle of this structure, the thin pointer's type in debugging
1241 -- information is pointer-to-arr___XUT.
1243 -- The first field of arr___XUT is named BOUNDS, and has a type
1244 -- named arr___XUB, with the structure described for such types
1245 -- in fat pointers, as described above.
1247 -- The second field of arr___XUT is named ARRAY, and contains
1248 -- the actual array. Because this array has a dynamic size,
1249 -- determined by the BOUNDS field that precedes it, all of the
1250 -- information about arr___XUT is encoded in a parallel type named
1251 -- arr___XUT___XVE, with fields BOUNDS and ARRAY___XVL. As for
1252 -- previously described ___XVE types, ARRAY___XVL has
1253 -- a pointer-to-array type. However, the array type in this case
1254 -- is named arr___XUA and only its element type is meaningful,
1255 -- just as described for fat pointers.
1257 --------------------------------------
1258 -- Tagged Types and Type Extensions --
1259 --------------------------------------
1261 -- A type C derived from a tagged type P has a field named "_parent"
1262 -- of type P that contains its inherited fields. The type of this
1263 -- field is usually P (encoded as usual if it has a dynamic size),
1264 -- but may be a more distant ancestor, if P is a null extension of
1267 -- The type tag of a tagged type is a field named _tag, of type void*.
1268 -- If the type is derived from another tagged type, its _tag field is
1269 -- found in its _parent field.
1271 -----------------------------
1272 -- Variant Record Encoding --
1273 -----------------------------
1275 -- The variant part of a variant record is encoded as a single field
1276 -- in the enclosing record, whose name is:
1280 -- where discrim is the unqualified name of the variant. This field name
1281 -- is built by gigi (not by code in this unit). In the case of an
1282 -- Unchecked_Union record, this discriminant will not appear in the
1283 -- record, and the debugger must proceed accordingly (basically it
1284 -- can treat this case as it would a C union).
1286 -- The type corresponding to this field has a name that is obtained
1287 -- by concatenating the type name with the above string and is similar
1288 -- to a C union, in which each member of the union corresponds to one
1289 -- variant. However, unlike a C union, the size of the type may be
1290 -- variable even if each of the components are fixed size, since it
1291 -- includes a computation of which variant is present. In that case,
1292 -- it will be encoded as above and a type with the suffix "___XVN___XVU"
1295 -- The name of the union member is encoded to indicate the choices, and
1296 -- is a string given by the following grammar:
1298 -- union_name ::= {choice} | others_choice
1299 -- choice ::= simple_choice | range_choice
1300 -- simple_choice ::= S number
1301 -- range_choice ::= R number T number
1302 -- number ::= {decimal_digit} [m]
1303 -- others_choice ::= O (upper case letter O)
1305 -- The m in a number indicates a negative value. As an example of this
1306 -- encoding scheme, the choice 1 .. 4 | 7 | -10 would be represented by
1310 -- In the case of enumeration values, the values used are the
1311 -- actual representation values in the case where an enumeration type
1312 -- has an enumeration representation spec (i.e. they are values that
1313 -- correspond to the use of the Enum_Rep attribute).
1315 -- The type of the inner record is given by the name of the union
1316 -- type (as above) concatenated with the above string. Since that
1317 -- type may itself be variable-sized, it may also be encoded as above
1318 -- with a new type with a further suffix of "___XVU".
1320 -- As an example, consider:
1322 -- type Var (Disc : Boolean := True) is record
1337 -- In this case, the type var is represented as a struct with three
1338 -- fields, the first two are "disc" and "m", representing the values
1339 -- of these record components.
1341 -- The third field is a union of two types, with field names S1 and O.
1342 -- S1 is a struct with fields "r" and "s", and O is a struct with
1345 ------------------------------------------------
1346 -- Subprograms for Handling Variant Encodings --
1347 ------------------------------------------------
1349 procedure Get_Variant_Encoding (V : Node_Id);
1350 -- This procedure is called by Gigi with V being the variant node.
1351 -- The corresponding encoding string is returned in Name_Buffer with
1352 -- the length of the string in Name_Len, and an ASCII.NUL character
1353 -- stored following the name.
1355 ---------------------------------
1356 -- Subtypes of Variant Records --
1357 ---------------------------------
1359 -- A subtype of a variant record is represented by a type in which the
1360 -- union field from the base type is replaced by one of the possible
1361 -- values. For example, if we have:
1363 -- type Var (Disc : Boolean := True) is record
1378 -- V3 : Var (False);
1380 -- Here V2 for example is represented with a subtype whose name is
1381 -- something like TvarS3b, which is a struct with three fields. The
1382 -- first two fields are "disc" and "m" as for the base type, and
1383 -- the third field is S1, which contains the fields "r" and "s".
1385 -- The debugger should simply ignore structs with names of the form
1386 -- corresponding to variants, and consider the fields inside as
1387 -- belonging to the containing record.
1389 -------------------------------------------
1390 -- Character literals in Character Types --
1391 -------------------------------------------
1393 -- Character types are enumeration types at least one of whose
1394 -- enumeration literals is a character literal. Enumeration literals
1395 -- are usually simply represented using their identifier names. In
1396 -- the case where an enumeration literal is a character literal, the
1397 -- name aencoded as described in the following paragraph.
1399 -- A name QUhh, where each 'h' is a lower-case hexadecimal digit,
1400 -- stands for a character whose Unicode encoding is hh, and
1401 -- QWhhhh likewise stands for a wide character whose encoding
1402 -- is hhhh. The representation values are encoded as for ordinary
1403 -- enumeration literals (and have no necessary relationship to the
1404 -- values encoded in the names).
1406 -- For example, given the type declaration
1408 -- type x is (A, 'C', B);
1410 -- the second enumeration literal would be named QU43 and the
1411 -- value assigned to it would be 1.
1413 ----------------------------
1414 -- Effect of Optimization --
1415 ----------------------------
1417 -- If the program is compiled with optimization on (e.g. -O1 switch
1418 -- specified), then there may be variations in the output from the
1419 -- above specification. In particular, objects may disappear from
1420 -- the output. This includes not only constants and variables that
1421 -- the program declares at the source level, but also the x___L and
1422 -- x___U constants created to describe the lower and upper bounds of
1423 -- subtypes with dynamic bounds. This means for example, that array
1424 -- bounds may disappear if optimization is turned on. The debugger
1425 -- is expected to recognize that these constants are missing and
1426 -- deal as best as it can with the limited information available.