1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 1996-2007, 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, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, 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 Namet; use Namet;
32 with Types; use Types;
33 with Uintp; use Uintp;
37 -----------------------------------------------------
38 -- Encoding and Qualification of Names of Entities --
39 -----------------------------------------------------
41 -- This section describes how the names of entities are encoded in
42 -- the generated debugging information.
44 -- An entity in Ada has a name of the form X.Y.Z ... E where X,Y,Z
45 -- are the enclosing scopes (not including Standard at the start).
47 -- The encoding of the name follows this basic qualified naming scheme,
48 -- where the encoding of individual entity names is as described in Namet
49 -- (i.e. in particular names present in the original source are folded to
50 -- all lower case, with upper half and wide characters encoded as described
51 -- in Namet). Upper case letters are used only for entities generated by
54 -- There are two cases, global entities, and local entities. In more formal
55 -- terms, local entities are those which have a dynamic enclosing scope,
56 -- and global entities are at the library level, except that we always
57 -- consider procedures to be global entities, even if they are nested
58 -- (that's because at the debugger level a procedure name refers to the
59 -- code, and the code is indeed a global entity, including the case of
60 -- nested procedures.) In addition, we also consider all types to be global
61 -- entities, even if they are defined within a procedure.
63 -- The reason for treating all type names as global entities is that a
64 -- number of our type encodings work by having related type names, and we
65 -- need the full qualification to keep this unique.
67 -- For global entities, the encoded name includes all components of the
68 -- fully expanded name (but omitting Standard at the start). For example,
69 -- if a library level child package P.Q has an embedded package R, and
70 -- there is an entity in this embdded package whose name is S, the encoded
71 -- name will include the components p.q.r.s.
73 -- For local entities, the encoded name only includes the components up to
74 -- the enclosing dynamic scope (other than a block). At run time, such a
75 -- dynamic scope is a subprogram, and the debugging formats know about
76 -- local variables of procedures, so it is not necessary to have full
77 -- qualification for such entities. In particular this means that direct
78 -- local variables of a procedure are not qualified.
80 -- As an example of the local name convention, consider a procedure V.W
81 -- with a local variable X, and a nested block Y containing an entity Z.
82 -- The fully qualified names of the entities X and Z are:
87 -- but since V.W is a subprogram, the encoded names will end up
93 -- The separating dots are translated into double underscores
95 -----------------------------
96 -- Handling of Overloading --
97 -----------------------------
99 -- The above scheme is incomplete for overloaded subprograms, since
100 -- overloading can legitimately result in case of two entities with
101 -- exactly the same fully qualified names. To distinguish between
102 -- entries in a set of overloaded subprograms, the encoded names are
103 -- serialized by adding the suffix:
105 -- __nn (two underscores)
107 -- where nn is a serial number (2 for the second overloaded function,
108 -- 3 for the third, etc.). A suffix of __1 is always omitted (i.e. no
109 -- suffix implies the first instance).
111 -- These names are prefixed by the normal full qualification. So for
112 -- example, the third instance of the subprogram qrs in package yz
113 -- would have the name:
117 -- A more subtle case arises with entities declared within overloaded
118 -- subprograms. If we have two overloaded subprograms, and both declare
119 -- an entity xyz, then the fully expanded name of the two xyz's is the
120 -- same. To distinguish these, we add the same __n suffix at the end of
121 -- the inner entity names.
123 -- In more complex cases, we can have multiple levels of overloading,
124 -- and we must make sure to distinguish which final declarative region
125 -- we are talking about. For this purpose, we use a more complex suffix
126 -- which has the form:
130 -- where the nn values are the homonym numbers as needed for any of the
131 -- qualifying entities, separated by a single underscore. If all the nn
132 -- values are 1, the suffix is omitted, Otherwise the suffix is present
133 -- (including any values of 1). The following example shows how this
136 -- package body Yz is
137 -- procedure Qrs is -- Name is yz__qrs
138 -- procedure Tuv is ... end; -- Name is yz__qrs__tuv
139 -- begin ... end Qrs;
141 -- procedure Qrs (X: Int) is -- Name is yz__qrs__2
142 -- procedure Tuv is ... end; -- Name is yz__qrs__tuv__2_1
143 -- procedure Tuv (X: Int) is -- Name is yz__qrs__tuv__2_2
144 -- begin ... end Tuv;
146 -- procedure Tuv (X: Float) is -- Name is yz__qrs__tuv__2_3
147 -- type m is new float; -- Name is yz__qrs__tuv__m__2_3
148 -- begin ... end Tuv;
149 -- begin ... end Qrs;
156 -- The above rules applied to operator names would result in names with
157 -- quotation marks, which are not typically allowed by assemblers and
158 -- linkers, and even if allowed would be odd and hard to deal with. To
159 -- avoid this problem, operator names are encoded as follows:
181 -- These names are prefixed by the normal full qualification, and
182 -- suffixed by the overloading identification. So for example, the
183 -- second operator "=" defined in package Extra.Messages would have
186 -- extra__messages__Oeq__2
188 ----------------------------------
189 -- Resolving Other Name Clashes --
190 ----------------------------------
192 -- It might be thought that the above scheme is complete, but in Ada 95,
193 -- full qualification is insufficient to uniquely identify an entity in
194 -- the program, even if it is not an overloaded subprogram. There are
195 -- two possible confusions:
199 -- interpretation 1: entity b in body of package a
200 -- interpretation 2: child procedure b of package a
204 -- interpretation 1: entity c in child package a.b
205 -- interpretation 2: entity c in nested package b in body of a
207 -- It is perfectly legal in both cases for both interpretations to be
208 -- valid within a single program. This is a bit of a surprise since
209 -- certainly in Ada 83, full qualification was sufficient, but not in
210 -- Ada 95. The result is that the above scheme can result in duplicate
211 -- names. This would not be so bad if the effect were just restricted
212 -- to debugging information, but in fact in both the above cases, it
213 -- is possible for both symbols to be external names, and so we have
214 -- a real problem of name clashes.
216 -- To deal with this situation, we provide two additional encoding
219 -- First: all library subprogram names are preceded by the string
220 -- _ada_ (which causes no duplications, since normal Ada names can
221 -- never start with an underscore. This not only solves the first
222 -- case of duplication, but also solves another pragmatic problem
223 -- which is that otherwise Ada procedures can generate names that
224 -- clash with existing system function names. Most notably, we can
225 -- have clashes in the case of procedure Main with the C main that
226 -- in some systems is always present.
228 -- Second, for the case where nested packages declared in package
229 -- bodies can cause trouble, we add a suffix which shows which
230 -- entities in the list are body-nested packages, i.e. packages
231 -- whose spec is within a package body. The rules are as follows,
232 -- given a list of names in a qualified name name1.name2....
234 -- If none are body-nested package entities, then there is no suffix
236 -- If at least one is a body-nested package entity, then the suffix
237 -- is X followed by a string of b's and n's (b = body-nested package
238 -- entity, n = not a body-nested package).
240 -- There is one element in this string for each entity in the encoded
241 -- expanded name except the first (the rules are such that the first
242 -- entity of the encoded expanded name can never be a body-nested'
243 -- package. Trailing n's are omitted, as is the last b (there must
244 -- be at least one b, or we would not be generating a suffix at all).
246 -- For example, suppose we have
249 -- pragma Elaborate_Body;
250 -- m1 : integer; -- #1
254 -- package y is m2 : integer; end y; -- #2
256 -- package z is r : integer; end z; -- #3
258 -- m3 : integer; -- #4
262 -- pragma Elaborate_Body;
263 -- m2 : integer; -- #5
266 -- package body x.y is
267 -- m3 : integer; -- #6
268 -- procedure j is -- #7
270 -- z : integer; -- #8
277 -- procedure x.m3 is begin null; end; -- #9
279 -- Then the encodings would be:
281 -- #1. x__m1 (no BNPE's in sight)
282 -- #2. x__y__m2X (y is a BNPE)
283 -- #3. x__y__z__rXb (y is a BNPE, so is z)
284 -- #4. x__m3 (no BNPE's in sight)
285 -- #5. x__y__m2 (no BNPE's in sight)
286 -- #6. x__y__m3 (no BNPE's in signt)
287 -- #7. x__y__j (no BNPE's in sight)
288 -- #8. k__z (no BNPE's, only up to procedure)
289 -- #9 _ada_x__m3 (library level subprogram)
291 -- Note that we have instances here of both kind of potential name
292 -- clashes, and the above examples show how the encodings avoid the
295 -- Lines #4 and #9 both refer to the entity x.m3, but #9 is a library
296 -- level subprogram, so it is preceded by the string _ada_ which acts
297 -- to distinguish it from the package body entity.
299 -- Lines #2 and #5 both refer to the entity x.y.m2, but the first
300 -- instance is inside the body-nested package y, so there is an X
301 -- suffix to distinguish it from the child library entity.
303 -- Note that enumeration literals never need Xb type suffixes, since
304 -- they are never referenced using global external names.
306 ---------------------
307 -- Interface Names --
308 ---------------------
310 -- Note: if an interface name is present, then the external name
311 -- is taken from the specified interface name. Given the current
312 -- limitations of the gcc backend, this means that the debugging
313 -- name is also set to the interface name, but conceptually, it
314 -- would be possible (and indeed desirable) to have the debugging
315 -- information still use the Ada name as qualified above, so we
316 -- still fully qualify the name in the front end.
318 -------------------------------------
319 -- Encodings Related to Task Types --
320 -------------------------------------
322 -- Each task object defined by a single task declaration is associated
323 -- with a prefix that is used to qualify procedures defined in that
327 -- task body TaskObj is
328 -- procedure F1 is ... end;
334 -- The name of subprogram TaskObj.F1 is encoded as p__taskobjTK__f1,
335 -- The body, B, is contained in a subprogram whose name is
338 ------------------------------------------
339 -- Encodings Related to Protected Types --
340 ------------------------------------------
342 -- Each protected type has an associated record type, that describes
343 -- the actual layout of the private data. In addition to the private
344 -- components of the type, the Corresponding_Record_Type includes one
345 -- component of type Protection, which is the actual lock structure.
346 -- The run-time size of the protected type is the size of the corres-
349 -- For a protected type prot, the Corresponding_Record_Type is encoded
352 -- The operations of a protected type are encoded as follows: each
353 -- operation results in two subprograms, a locking one that is called
354 -- from outside of the object, and a non-locking one that is used for
355 -- calls from other operations on the same object. The locking operation
356 -- simply acquires the lock, and then calls the non-locking version.
357 -- The names of all of these have a prefix constructed from the name of
358 -- the type, and a suffix which is P or N, depending on whether this is
359 -- the protected/non-locking version of the operation.
361 -- Operations generated for protected entries follow the same encoding.
362 -- Each entry results in two suprograms: a procedure that holds the
363 -- entry body, and a function that holds the evaluation of the barrier.
364 -- The names of these subprograms include the prefix '_E' or '_B' res-
365 -- pectively. The names also include a numeric suffix to render them
366 -- unique in the presence of overloaded entries.
368 -- Given the declaration:
370 -- protected type Lock is
371 -- function Get return Integer;
372 -- procedure Set (X: Integer);
373 -- entry Update (Val : Integer);
375 -- Value : Integer := 0;
378 -- the following operations are created:
389 -- If the protected type implements at least one interface, the
390 -- following additional operations are created:
396 -- These operations are used to ensure overriding of interface level
397 -- subprograms and proper dispatching on interface class-wide objects.
398 -- The bodies of these operations contain calls to their respective
399 -- protected versions:
401 -- function lock_get return Integer is
406 -- procedure lock_set (X : Integer) is
411 ----------------------------------------------------
412 -- Conversion between Entities and External Names --
413 ----------------------------------------------------
415 No_Dollar_In_Label : constant Boolean := True;
416 -- True iff the target does not allow dollar signs ("$") in external names
417 -- ??? We want to migrate all platforms to use the same convention.
418 -- As a first step, we force this constant to always be True. This
419 -- constant will eventually be deleted after we have verified that
420 -- the migration does not cause any unforseen adverse impact.
421 -- We chose "__" because it is supported on all platforms, which is
422 -- not the case of "$".
424 procedure Get_External_Name
426 Has_Suffix : Boolean);
427 -- Set Name_Buffer and Name_Len to the external name of entity E.
428 -- The external name is the Interface_Name, if specified, unless
429 -- the entity has an address clause or a suffix.
431 -- If the Interface is not present, or not used, the external name
432 -- is the concatenation of:
434 -- - the string "_ada_", if the entity is a library subprogram,
435 -- - the names of any enclosing scopes, each followed by "__",
436 -- or "X_" if the next entity is a subunit)
437 -- - the name of the entity
438 -- - the string "$" (or "__" if target does not allow "$"), followed
439 -- by homonym suffix, if the entity is an overloaded subprogram
440 -- or is defined within an overloaded subprogram.
442 procedure Get_External_Name_With_Suffix
445 -- Set Name_Buffer and Name_Len to the external name of entity E.
446 -- If Suffix is the empty string the external name is as above,
447 -- otherwise the external name is the concatenation of:
449 -- - the string "_ada_", if the entity is a library subprogram,
450 -- - the names of any enclosing scopes, each followed by "__",
451 -- or "X_" if the next entity is a subunit)
452 -- - the name of the entity
453 -- - the string "$" (or "__" if target does not allow "$"), followed
454 -- by homonym suffix, if the entity is an overloaded subprogram
455 -- or is defined within an overloaded subprogram.
456 -- - the string "___" followed by Suffix
458 -- Note that a call to this procedure has no effect if we are not
459 -- generating code, since the necessary information for computing the
460 -- proper encoded name is not available in this case.
462 --------------------------------------------
463 -- Subprograms for Handling Qualification --
464 --------------------------------------------
466 procedure Qualify_Entity_Names (N : Node_Id);
467 -- Given a node N, that represents a block, subprogram body, or package
468 -- body or spec, or protected or task type, sets a fully qualified name
469 -- for the defining entity of given construct, and also sets fully
470 -- qualified names for all enclosed entities of the construct (using
471 -- First_Entity/Next_Entity). Note that the actual modifications of the
472 -- names is postponed till a subsequent call to Qualify_All_Entity_Names.
473 -- Note: this routine does not deal with prepending _ada_ to library
474 -- subprogram names. The reason for this is that we only prepend _ada_
475 -- to the library entity itself, and not to names built from this name.
477 procedure Qualify_All_Entity_Names;
478 -- When Qualify_Entity_Names is called, no actual name changes are made,
479 -- i.e. the actual calls to Qualify_Entity_Name are deferred until a call
480 -- is made to this procedure. The reason for this deferral is that when
481 -- names are changed semantic processing may be affected. By deferring
482 -- the changes till just before gigi is called, we avoid any concerns
483 -- about such effects. Gigi itself does not use the names except for
484 -- output of names for debugging purposes (which is why we are doing
485 -- the name changes in the first place.
487 -- Note: the routines Get_Unqualified_[Decoded]_Name_String in Namet
488 -- are useful to remove qualification from a name qualified by the
489 -- call to Qualify_All_Entity_Names.
491 --------------------------------
492 -- Handling of Numeric Values --
493 --------------------------------
495 -- All numeric values here are encoded as strings of decimal digits.
496 -- Only integer values need to be encoded. A negative value is encoded
497 -- as the corresponding positive value followed by a lower case m for
498 -- minus to indicate that the value is negative (e.g. 2m for -2).
500 -------------------------
501 -- Type Name Encodings --
502 -------------------------
504 -- In the following typ is the name of the type as normally encoded by
505 -- the debugger rules, i.e. a non-qualified name, all in lower case,
506 -- with standard encoding of upper half and wide characters
508 ------------------------
509 -- Encapsulated Types --
510 ------------------------
512 -- In some cases, the compiler encapsulates a type by wrapping it in
513 -- a structure. For example, this is used when a size or alignment
514 -- specification requires a larger type. Consider:
516 -- type y is mod 2 ** 64;
517 -- for y'size use 256;
519 -- In this case the compile generates a structure type y___PAD, which
520 -- has a single field whose name is F. This single field is 64 bits
521 -- long and contains the actual value. This kind of padding is used
522 -- when the logical value to be stored is shorter than the object in
523 -- which it is allocated. For example if a size clause is used to set
524 -- a size of 256 for a signed integer value, then a typical choice is
525 -- to wrap a 64-bit integer in a 256 bit PAD structure.
527 -- A similar encapsulation is done for some packed array types,
528 -- in which case the structure type is y___JM and the field name
529 -- is OBJECT. This is used in the case of a packed array stored
530 -- in modular representation (see section on representation of
531 -- packed array objects). In this case the JM wrapping is used to
532 -- achieve correct positioning of the packed array value (left or
533 -- right justified in its field depending on endianness.
535 -- When the debugger sees an object of a type whose name has a
536 -- suffix of ___PAD or ___JM, the type will be a record containing
537 -- a single field, and the name of that field will be all upper case.
538 -- In this case, it should look inside to get the value of the inner
539 -- field, and neither the outer structure name, nor the field name
540 -- should appear when the value is printed.
542 -- When the debugger sees a record named REP being a field inside
543 -- another record, it should treat the fields inside REP as being
544 -- part of the outer record (this REP field is only present for
545 -- code generation purposes). The REP record should not appear in
546 -- the values printed by the debugger.
548 -----------------------
549 -- Fixed-Point Types --
550 -----------------------
552 -- Fixed-point types are encoded using a suffix that indicates the
553 -- delta and small values. The actual type itself is a normal
557 -- typ___XF_nn_dd_nn_dd
559 -- The first form is used when small = delta. The value of delta (and
560 -- small) is given by the rational nn/dd, where nn and dd are decimal
563 -- The second form is used if the small value is different from the
564 -- delta. In this case, the first nn/dd rational value is for delta,
565 -- and the second value is for small.
567 ------------------------------
568 -- VAX Floating-Point Types --
569 ------------------------------
571 -- Vax floating-point types are represented at run time as integer
572 -- types, which are treated specially by the code generator. Their
573 -- type names are encoded with the following suffix:
579 -- representing the Vax F Float, D Float, and G Float types. The
580 -- debugger must treat these specially. In particular, printing
581 -- these values can be achieved using the debug procedures that
582 -- are provided in package System.Vax_Float_Operations:
584 -- procedure Debug_Output_D (Arg : D);
585 -- procedure Debug_Output_F (Arg : F);
586 -- procedure Debug_Output_G (Arg : G);
588 -- These three procedures take a Vax floating-point argument, and
589 -- output a corresponding decimal representation to standard output
590 -- with no terminating line return.
596 -- Discrete types are coded with a suffix indicating the range in
597 -- the case where one or both of the bounds are discriminants or
600 -- Note: at the current time, we also encode compile time known
601 -- bounds if they do not match the natural machine type bounds,
602 -- but this may be removed in the future, since it is redundant
603 -- for most debugging formats. However, we do not ever need XD
604 -- encoding for enumeration base types, since here it is always
605 -- clear what the bounds are from the total number of enumeration
609 -- typ___XDL_lowerbound
610 -- typ___XDU_upperbound
611 -- typ___XDLU_lowerbound__upperbound
613 -- If a discrete type is a natural machine type (i.e. its bounds
614 -- correspond in a natural manner to its size), then it is left
615 -- unencoded. The above encoding forms are used when there is a
616 -- constrained range that does not correspond to the size or that
617 -- has discriminant references or other compile time known bounds.
619 -- The first form is used if both bounds are dynamic, in which case
620 -- two constant objects are present whose names are typ___L and
621 -- typ___U in the same scope as typ, and the values of these constants
622 -- indicate the bounds. As far as the debugger is concerned, these
623 -- are simply variables that can be accessed like any other variables.
624 -- In the enumeration case, these values correspond to the Enum_Rep
625 -- values for the lower and upper bounds.
627 -- The second form is used if the upper bound is dynamic, but the
628 -- lower bound is either constant or depends on a discriminant of
629 -- the record with which the type is associated. The upper bound
630 -- is stored in a constant object of name typ___U as previously
631 -- described, but the lower bound is encoded directly into the
632 -- name as either a decimal integer, or as the discriminant name.
634 -- The third form is similarly used if the lower bound is dynamic,
635 -- but the upper bound is compile time known or a discriminant
636 -- reference, in which case the lower bound is stored in a constant
637 -- object of name typ___L, and the upper bound is encoded directly
638 -- into the name as either a decimal integer, or as the discriminant
641 -- The fourth form is used if both bounds are discriminant references
642 -- or compile time known values, with the encoding first for the lower
643 -- bound, then for the upper bound, as previously described.
653 -- Is encoded as a subrange of an unsigned base type with lower bound
654 -- 0 and upper bound N. That is, there is no name encoding. We use
655 -- the standard encodings provided by the debugging format. Thus
656 -- we give these types a non-standard interpretation: the standard
657 -- interpretation of our encoding would not, in general, imply that
658 -- arithmetic on type x was to be performed modulo N (especially not
659 -- when N is not a power of 2).
665 -- Only discrete types can be biased, and the fact that they are
666 -- biased is indicated by a suffix of the form:
668 -- typ___XB_lowerbound__upperbound
670 -- Here lowerbound and upperbound are decimal integers, with the
671 -- usual (postfix "m") encoding for negative numbers. Biased
672 -- types are only possible where the bounds are compile time
673 -- known, and the values are represented as unsigned offsets
674 -- from the lower bound given. For example:
676 -- type Q is range 10 .. 15;
679 -- The size clause will force values of type Q in memory to be
680 -- stored in biased form (e.g. 11 will be represented by the
683 ----------------------------------------------
684 -- Record Types with Variable-Length Fields --
685 ----------------------------------------------
687 -- The debugging formats do not fully support these types, and indeed
688 -- some formats simply generate no useful information at all for such
689 -- types. In order to provide information for the debugger, gigi creates
690 -- a parallel type in the same scope with one of the names
695 -- The former name is used for a record and the latter for the union
696 -- that is made for a variant record (see below) if that record or
697 -- union has a field of variable size or if the record or union itself
698 -- has a variable size. These encodings suffix any other encodings that
699 -- that might be suffixed to the type name.
701 -- The idea here is to provide all the needed information to interpret
702 -- objects of the original type in the form of a "fixed up" type, which
703 -- is representable using the normal debugging information.
705 -- There are three cases to be dealt with. First, some fields may have
706 -- variable positions because they appear after variable-length fields.
707 -- To deal with this, we encode *all* the field bit positions of the
708 -- special ___XV type in a non-standard manner.
710 -- The idea is to encode not the position, but rather information
711 -- that allows computing the position of a field from the position
712 -- of the previous field. The algorithm for computing the actual
713 -- positions of all fields and the length of the record is as
714 -- follows. In this description, let P represent the current
715 -- bit position in the record.
717 -- 1. Initialize P to 0
719 -- 2. For each field in the record:
721 -- 2a. If an alignment is given (see below), then round P
722 -- up, if needed, to the next multiple of that alignment.
724 -- 2b. If a bit position is given, then increment P by that
725 -- amount (that is, treat it as an offset from the end of the
726 -- preceding record).
728 -- 2c. Assign P as the actual position of the field
730 -- 2d. Compute the length, L, of the represented field (see below)
731 -- and compute P'=P+L. Unless the field represents a variant part
732 -- (see below and also Variant Record Encoding), set P to P'.
734 -- The alignment, if present, is encoded in the field name of the
735 -- record, which has a suffix:
739 -- where the nn after the XVA indicates the alignment value in storage
740 -- units. This encoding is present only if an alignment is present.
742 -- The size of the record described by an XVE-encoded type (in bits)
743 -- is generally the maximum value attained by P' in step 2d above,
744 -- rounded up according to the record's alignment.
746 -- Second, the variable-length fields themselves are represented by
747 -- replacing the type by a special access type. The designated type
748 -- of this access type is the original variable-length type, and the
749 -- fact that this field has been transformed in this way is signalled
750 -- by encoding the field name as:
754 -- where field is the original field name. If a field is both
755 -- variable-length and also needs an alignment encoding, then the
756 -- encodings are combined using:
760 -- Note: the reason that we change the type is so that the resulting
761 -- type has no variable-length fields. At least some of the formats
762 -- used for debugging information simply cannot tolerate variable-
763 -- length fields, so the encoded information would get lost.
765 -- Third, in the case of a variant record, the special union
766 -- that contains the variants is replaced by a normal C union.
767 -- In this case, the positions are all zero.
769 -- Discriminants appear before any variable-length fields that depend
770 -- on them, with one exception. In some cases, a discriminant
771 -- governing the choice of a variant clause may appear in the list
772 -- of fields of an XVE type after the entry for the variant clause
773 -- itself (this can happen in the presence of a representation clause
774 -- for the record type in the source program). However, when this
775 -- happens, the discriminant's position may be determined by first
776 -- applying the rules described in this section, ignoring the variant
777 -- clause. As a result, discriminants can always be located
778 -- independently of the variable-length fields that depend on them.
780 -- The size of the ___XVE or ___XVU record or union is set to the
781 -- alignment (in bytes) of the original object so that the debugger
782 -- can calculate the size of the original type.
784 -- As an example of this encoding, consider the declarations:
786 -- type Q is array (1 .. V1) of Float; -- alignment 4
787 -- type R is array (1 .. V2) of Long_Float; -- alignment 8
792 -- C : String (1 .. V3);
799 -- The encoded type looks like:
801 -- type anonymousQ is access Q;
802 -- type anonymousR is access R;
804 -- type X___XVE is record
805 -- A : Character; -- position contains 0
806 -- B : Float; -- position contains 24
807 -- C___XVL : access String (1 .. V3); -- position contains 0
808 -- D___XVA4 : Float; -- position contains 0
809 -- E___XVL4 : anonymousQ; -- position contains 0
810 -- F___XVL8 : anonymousR; -- position contains 0
811 -- G : Float; -- position contains 0
814 -- Any bit sizes recorded for fields other than dynamic fields and
815 -- variants are honored as for ordinary records.
819 -- 1) The B field could also have been encoded by using a position
820 -- of zero, and an alignment of 4, but in such a case, the coding by
821 -- position is preferred (since it takes up less space). We have used
822 -- the (illegal) notation access xxx as field types in the example
825 -- 2) The E field does not actually need the alignment indication
826 -- but this may not be detected in this case by the conversion
829 -- 3) Our conventions do not cover all XVE-encoded records in which
830 -- some, but not all, fields have representation clauses. Such
831 -- records may, therefore, be displayed incorrectly by debuggers.
832 -- This situation is not common.
834 -----------------------
835 -- Base Record Types --
836 -----------------------
838 -- Under certain circumstances, debuggers need two descriptions of a
839 -- record type, one that gives the actual details of the base type's
840 -- structure (as described elsewhere in these comments) and one that may
841 -- be used to obtain information about the particular subtype and the
842 -- size of the objects being typed. In such cases the compiler will
843 -- substitute type whose name is typically compiler-generated and
844 -- irrelevant except as a key for obtaining the actual type.
846 -- Specifically, if this name is x, then we produce a record type named
847 -- x___XVS consisting of one field. The name of this field is that of
848 -- the actual type being encoded, which we'll call y (the type of this
849 -- single field is arbitrary). Both x and y may have corresponding
852 -- The size of the objects typed as x should be obtained from the
853 -- structure of x (and x___XVE, if applicable) as for ordinary types
854 -- unless there is a variable named x___XVZ, which, if present, will
855 -- hold the the size (in bits) of x.
857 -- The type x will either be a subtype of y (see also Subtypes of
858 -- Variant Records, below) or will contain no fields at all. The layout,
859 -- types, and positions of these fields will be accurate, if present.
860 -- (Currently, however, the GDB debugger makes no use of x except to
861 -- determine its size).
863 -- Among other uses, XVS types are sometimes used to encode
864 -- unconstrained types. For example, given
866 -- subtype Int is INTEGER range 0..10;
867 -- type T1 (N: Int := 0) is record
868 -- F1: String (1 .. N);
870 -- type AT1 is array (INTEGER range <>) of T1;
872 -- the element type for AT1 might have a type defined as if it had
875 -- type at1___C_PAD is record null; end record;
876 -- for at1___C_PAD'Size use 16 * 8;
878 -- and there would also be
880 -- type at1___C_PAD___XVS is record t1: Integer; end record;
883 -- Had the subtype Int been dynamic:
885 -- subtype Int is INTEGER range 0 .. M; -- M a variable
887 -- Then the compiler would also generate a declaration whose effect
890 -- at1___C_PAD___XVZ: constant Integer := 32 + M * 8 + padding term;
892 -- Not all unconstrained types are so encoded; the XVS convention may be
893 -- unnecessary for unconstrained types of fixed size. However, this
894 -- encoding is always necessary when a subcomponent type (array
895 -- element's type or record field's type) is an unconstrained record
896 -- type some of whose components depend on discriminant values.
902 -- Since there is no way for the debugger to obtain the index subtypes
903 -- for an array type, we produce a type that has the name of the
904 -- array type followed by "___XA" and is a record whose field names
905 -- are the names of the types for the bounds. The types of these
906 -- fields is an integer type which is meaningless.
908 -- To conserve space, we do not produce this type unless one of the
909 -- index types is either an enumeration type, has a variable upper
910 -- bound, has a lower bound different from the constant 1, is a biased
911 -- type, or is wider than "sizetype".
913 -- Given the full encoding of these types (see above description for
914 -- the encoding of discrete types), this means that all necessary
915 -- information for addressing arrays is available. In some debugging
916 -- formats, some or all of the bounds information may be available
917 -- redundantly, particularly in the fixed-point case, but this
918 -- information can in any case be ignored by the debugger.
920 ----------------------------
921 -- Note on Implicit Types --
922 ----------------------------
924 -- The compiler creates implicit type names in many situations where a
925 -- type is present semantically, but no specific name is present. For
928 -- S : Integer range M .. N;
930 -- Here the subtype of S is not integer, but rather an anonymous subtype
931 -- of Integer. Where possible, the compiler generates names for such
932 -- anonymous types that are related to the type from which the subtype
933 -- is obtained as follows:
937 -- where name is the name from which the subtype is obtained, using
938 -- lower case letters and underscores, and suffix starts with an upper
939 -- case letter. For example the name for the above declaration might be:
943 -- If the debugger is asked to give the type of an entity and the type
944 -- has the form T name suffix, it is probably appropriate to just use
945 -- "name" in the response since this is what is meaningful to the
948 -------------------------------------------------
949 -- Subprograms for Handling Encoded Type Names --
950 -------------------------------------------------
952 procedure Get_Encoded_Name (E : Entity_Id);
953 -- If the entity is a typename, store the external name of the entity as in
954 -- Get_External_Name, followed by three underscores plus the type encoding
955 -- in Name_Buffer with the length in Name_Len, and an ASCII.NUL character
956 -- stored following the name. Otherwise set Name_Buffer and Name_Len to
957 -- hold the entity name. Note that a call to this procedure has no effect
958 -- if we are not generating code, since the necessary information for
959 -- computing the proper encoded name is not available in this case.
965 -- Debugging information is generated for exception, object, package,
966 -- and subprogram renaming (generic renamings are not significant, since
967 -- generic templates are not relevant at debugging time).
969 -- Consider a renaming declaration of the form
971 -- x : typ renames y;
973 -- There is one case in which no special debugging information is required,
974 -- namely the case of an object renaming where the back end allocates a
975 -- reference for the renamed variable, and the entity x is this reference.
976 -- The debugger can handle this case without any special processing or
977 -- encoding (it won't know it was a renaming, but that does not matter).
979 -- All other cases of renaming generate a dummy variable for an entity
980 -- whose name is of the form:
982 -- x___XR_... for an object renaming
983 -- x___XRE_... for an exception renaming
984 -- x___XRP_... for a package renaming
986 -- and where the "..." represents a suffix that describes the structure of
987 -- the object name given in the renaming (see details below).
989 -- The name is fully qualified in the usual manner, i.e. qualified in the
990 -- same manner as the entity x would be. In the case of a package renaming
991 -- where x is a child unit, the qualification includes the name of the
992 -- parent unit, to disambiguate child units with the same simple name and
993 -- (of necessity) different parents.
995 -- Note: subprogram renamings are not encoded at the present time
997 -- The suffix of the variable name describing the renamed object is
998 -- defined to use the following encoding:
1000 -- For the simple entity case, where y is just an entity name, the suffix
1005 -- i.e. the suffix has a single field, the first part matching the
1006 -- name y, followed by a "___" separator, ending with sequence XE.
1007 -- The entity name portion is fully qualified in the usual manner.
1008 -- This same naming scheme is followed for all forms of encoded
1009 -- renamings that rename a simple entity.
1011 -- For the object renaming case where y is a selected component or an
1012 -- indexed component, the variable name is suffixed by additional fields
1013 -- that give details of the components. The name starts as above with a
1014 -- y___XE name indicating the outer level object entity. Then a series of
1015 -- selections and indexing operations can be specified as follows:
1017 -- Indexed component
1019 -- A series of subscript values appear in sequence, the number
1020 -- corresponds to the number of dimensions of the array. The
1021 -- subscripts have one of the following two forms:
1025 -- Here nnn is a constant value, encoded as a decimal integer
1026 -- (pos value for enumeration type case). Negative values have
1027 -- a trailing 'm' as usual.
1031 -- Here e is the (unqualified) name of a constant entity in the
1032 -- same scope as the renaming which contains the subscript value.
1036 -- For the slice case, we have two entries. The first is for the
1037 -- lower bound of the slice, and has the form:
1042 -- Specifies the lower bound, using exactly the same encoding as
1043 -- for an XS subscript as described above.
1045 -- Then the upper bound appears in the usual XSnnn/XSe form
1047 -- Selected component
1049 -- For a selected component, we have a single entry
1053 -- Here f is the field name for the selection
1055 -- For an explicit deference (.all), we have a single entry
1059 -- As an example, consider the declarations:
1063 -- m : string (2 .. 5);
1066 -- type r is array (1 .. 10, 1 .. 20) of q;
1070 -- z : string renames g (1,5).m(2 ..3)
1073 -- The generated variable entity would appear as
1075 -- p__z___XR_p__g___XEXS1XS5XRmXL2XS3 : _renaming_type;
1076 -- p__g___XE--------------------outer entity is g
1077 -- XS1-----------------first subscript for g
1078 -- XS5--------------second subscript for g
1079 -- XRm-----------select field m
1080 -- XL2--------lower bound of slice
1081 -- XS3-----upper bound of slice
1083 -- Note that the type of the variable is a special internal type named
1084 -- _renaming_type. This type is an arbitrary type of zero size created
1085 -- in package Standard (see cstand.adb) and is ignored by the debugger.
1087 function Debug_Renaming_Declaration (N : Node_Id) return Node_Id;
1088 -- The argument N is a renaming declaration. The result is a variable
1089 -- declaration as described in the above paragraphs. If N is not a special
1090 -- debug declaration, then Empty is returned.
1092 ---------------------------
1093 -- Packed Array Encoding --
1094 ---------------------------
1096 -- For every packed array, two types are created, and both appear in
1097 -- the debugging output.
1099 -- The original declared array type is a perfectly normal array type,
1100 -- and its index bounds indicate the original bounds of the array.
1102 -- The corresponding packed array type, which may be a modular type, or
1103 -- may be an array of bytes type (see Exp_Pakd for full details). This
1104 -- is the type that is actually used in the generated code and for
1105 -- debugging information for all objects of the packed type.
1107 -- The name of the corresponding packed array type is:
1112 -- ttt is the name of the original declared array
1113 -- nnn is the component size in bits (1-31)
1115 -- When the debugger sees that an object is of a type that is encoded
1116 -- in this manner, it can use the original type to determine the bounds,
1117 -- and the component size to determine the packing details.
1119 -------------------------------------------
1120 -- Packed Array Representation in Memory --
1121 -------------------------------------------
1123 -- Packed arrays are represented in tightly packed form, with no extra
1124 -- bits between components. This is true even when the component size
1125 -- is not a factor of the storage unit size, so that as a result it is
1126 -- possible for components to cross storage unit boundaries.
1128 -- The layout in storage is identical, regardless of whether the
1129 -- implementation type is a modular type or an array-of-bytes type.
1130 -- See Exp_Pakd for details of how these implementation types are used,
1131 -- but for the purpose of the debugger, only the starting address of
1132 -- the object in memory is significant.
1134 -- The following example should show clearly how the packing works in
1135 -- the little-endian and big-endian cases:
1137 -- type B is range 0 .. 7;
1138 -- for B'Size use 3;
1140 -- type BA is array (0 .. 5) of B;
1141 -- pragma Pack (BA);
1143 -- BV : constant BA := (1,2,3,4,5,6);
1145 -- Little endian case
1147 -- BV'Address + 2 BV'Address + 1 BV'Address + 0
1148 -- +-----------------+-----------------+-----------------+
1149 -- | ? ? ? ? ? ? 1 1 | 0 1 0 1 1 0 0 0 | 1 1 0 1 0 0 0 1 |
1150 -- +-----------------+-----------------+-----------------+
1151 -- <---------> <-----> <---> <---> <-----> <---> <--->
1152 -- unused bits BV(5) BV(4) BV(3) BV(2) BV(1) BV(0)
1156 -- BV'Address + 0 BV'Address + 1 BV'Address + 2
1157 -- +-----------------+-----------------+-----------------+
1158 -- | 0 0 1 0 1 0 0 1 | 1 1 0 0 1 0 1 1 | 1 0 ? ? ? ? ? ? |
1159 -- +-----------------+-----------------+-----------------+
1160 -- <---> <---> <-----> <---> <---> <-----> <--------->
1161 -- BV(0) BV(1) BV(2) BV(3) BV(4) BV(5) unused bits
1163 -- Note that if a modular type is used to represent the array, the
1164 -- allocation in memory is not the same as a normal modular type. The
1165 -- difference occurs when the allocated object is larger than the size of
1166 -- the array. For a normal modular type, we extend the value on the left
1169 -- For example, in the normal modular case, if we have a 6-bit modular
1170 -- type, declared as mod 2**6, and we allocate an 8-bit object for this
1171 -- type, then we extend the value with two bits on the most significant
1172 -- end, and in either the little-endian or big-endian case, the value 63 is
1173 -- represented as 00111111 in binary in memory.
1175 -- For a modular type used to represent a packed array, the rule is
1176 -- different. In this case, if we have to extend the value, then we do it
1177 -- with undefined bits (which are not initialized and whose value is
1178 -- irrelevant to any generated code). Furthermore these bits are on the
1179 -- right (least significant bits) in the big-endian case, and on the left
1180 -- (most significant bits) in the little-endian case.
1182 -- For example, if we have a packed boolean array of 6 bits, all set to
1183 -- True, stored in an 8-bit object, then the value in memory in binary is
1184 -- ??111111 in the little-endian case, and 111111?? in the big-endian case.
1186 -- This is done so that the representation of packed arrays does not
1187 -- depend on whether we use a modular representation or array of bytes
1188 -- as previously described. This ensures that we can pass such values by
1189 -- reference in the case where a subprogram has to be able to handle values
1190 -- stored in either form.
1192 -- Note that when we extract the value of such a modular packed array, we
1193 -- expect to retrieve only the relevant bits, so in this same example, when
1194 -- we extract the value we get 111111 in both cases, and the code generated
1195 -- by the front end assumes this although it does not assume that any high
1196 -- order bits are defined.
1198 -- There are opportunities for optimization based on the knowledge that the
1199 -- unused bits are irrelevant for these type of packed arrays. For example
1200 -- if we have two such 6-bit-in-8-bit values and we do an assignment:
1204 -- Then logically, we extract the 6 bits and store only 6 bits in the
1205 -- result, but the back end is free to simply assign the entire 8-bits in
1206 -- this case, since we don't actually care about the undefined bits.
1207 -- However, in the equality case, it is important to ensure that the
1208 -- undefined bits do not participate in an equality test.
1210 -- If a modular packed array value is assigned to a register, then
1211 -- logically it could always be held right justified, to avoid any need to
1212 -- shift, e.g. when doing comparisons. But probably this is a bad choice,
1213 -- as it would mean that an assignment such as a := above would require
1214 -- shifts when one value is in a register and the other value is in memory.
1216 ------------------------------------------------------
1217 -- Subprograms for Handling Packed Array Type Names --
1218 ------------------------------------------------------
1220 function Make_Packed_Array_Type_Name
1224 -- This function is used in Exp_Pakd to create the name that is encoded as
1225 -- described above. The entity Typ provides the name ttt, and the value
1226 -- Csize is the component size that provides the nnn value.
1228 --------------------------------------
1229 -- Pointers to Unconstrained Arrays --
1230 --------------------------------------
1232 -- There are two kinds of pointers to arrays. The debugger can tell which
1233 -- format is in use by the form of the type of the pointer.
1237 -- Fat pointers are represented as a struct with two fields. This
1238 -- struct has two distinguished field names:
1240 -- P_ARRAY is a pointer to the array type. The name of this type is
1241 -- the unconstrained type followed by "___XUA". This array will have
1242 -- bounds which are the discriminants, and hence are unparsable, but
1243 -- will give the number of subscripts and the component type.
1245 -- P_BOUNDS is a pointer to a struct, the name of whose type is the
1246 -- unconstrained array name followed by "___XUB" and which has
1247 -- fields of the form
1249 -- LBn (n a decimal integer) lower bound of n'th dimension
1250 -- UBn (n a decimal integer) upper bound of n'th dimension
1252 -- The bounds may be any integral type. In the case of an enumeration
1253 -- type, Enum_Rep values are used.
1255 -- For a given unconstrained array type, the compiler will generate one
1256 -- fat-pointer type whose name is "arr___XUP", where "arr" is the name
1257 -- of the array type, and use it to represent the array type itself in
1258 -- the debugging information.
1259 -- For each pointer to this unconstrained array type, the compiler will
1260 -- generate a typedef that points to the above "arr___XUP" fat-pointer
1261 -- type. As a consequence, when it comes to fat-pointer types:
1263 -- 1. The type name is given by the typedef
1265 -- 2. If the debugger is asked to output the type, the appropriate
1266 -- form is "access arr", except if the type name is "arr___XUP"
1267 -- for which it is the array definition.
1271 -- The value of a thin pointer is a pointer to the second field of a
1272 -- structure with two fields. The name of this structure's type is
1273 -- "arr___XUT", where "arr" is the name of the unconstrained array
1274 -- type. Even though it actually points into middle of this structure,
1275 -- the thin pointer's type in debugging information is
1276 -- pointer-to-arr___XUT.
1278 -- The first field of arr___XUT is named BOUNDS, and has a type named
1279 -- arr___XUB, with the structure described for such types in fat
1280 -- pointers, as described above.
1282 -- The second field of arr___XUT is named ARRAY, and contains the
1283 -- actual array. Because this array has a dynamic size, determined by
1284 -- the BOUNDS field that precedes it, all of the information about
1285 -- arr___XUT is encoded in a parallel type named arr___XUT___XVE, with
1286 -- fields BOUNDS and ARRAY___XVL. As for previously described ___XVE
1287 -- types, ARRAY___XVL has a pointer-to-array type. However, the array
1288 -- type in this case is named arr___XUA and only its element type is
1289 -- meaningful, just as described for fat pointers.
1291 --------------------------------------
1292 -- Tagged Types and Type Extensions --
1293 --------------------------------------
1295 -- A type C derived from a tagged type P has a field named "_parent" of
1296 -- type P that contains its inherited fields. The type of this field is
1297 -- usually P (encoded as usual if it has a dynamic size), but may be a more
1298 -- distant ancestor, if P is a null extension of that type.
1300 -- The type tag of a tagged type is a field named _tag, of type void*. If
1301 -- the type is derived from another tagged type, its _tag field is found in
1302 -- its _parent field.
1304 -----------------------------
1305 -- Variant Record Encoding --
1306 -----------------------------
1308 -- The variant part of a variant record is encoded as a single field in the
1309 -- enclosing record, whose name is:
1313 -- where discrim is the unqualified name of the variant. This field name is
1314 -- built by gigi (not by code in this unit). For Unchecked_Union record,
1315 -- this discriminant will not appear in the record, and the debugger must
1316 -- proceed accordingly (basically it can treat this case as it would a C
1319 -- The type corresponding to this field has a name that is obtained by
1320 -- concatenating the type name with the above string and is similar to a C
1321 -- union, in which each member of the union corresponds to one variant.
1322 -- However, unlike a C union, the size of the type may be variable even if
1323 -- each of the components are fixed size, since it includes a computation
1324 -- of which variant is present. In that case, it will be encoded as above
1325 -- and a type with the suffix "___XVN___XVU" will be present.
1327 -- The name of the union member is encoded to indicate the choices, and
1328 -- is a string given by the following grammar:
1330 -- union_name ::= {choice} | others_choice
1331 -- choice ::= simple_choice | range_choice
1332 -- simple_choice ::= S number
1333 -- range_choice ::= R number T number
1334 -- number ::= {decimal_digit} [m]
1335 -- others_choice ::= O (upper case letter O)
1337 -- The m in a number indicates a negative value. As an example of this
1338 -- encoding scheme, the choice 1 .. 4 | 7 | -10 would be represented by
1342 -- In the case of enumeration values, the values used are the actual
1343 -- representation values in the case where an enumeration type has an
1344 -- enumeration representation spec (i.e. they are values that correspond
1345 -- to the use of the Enum_Rep attribute).
1347 -- The type of the inner record is given by the name of the union type (as
1348 -- above) concatenated with the above string. Since that type may itself be
1349 -- variable-sized, it may also be encoded as above with a new type with a
1350 -- further suffix of "___XVU".
1352 -- As an example, consider:
1354 -- type Var (Disc : Boolean := True) is record
1369 -- In this case, the type var is represented as a struct with three fields,
1370 -- the first two are "disc" and "m", representing the values of these
1371 -- record components.
1373 -- The third field is a union of two types, with field names S1 and O. S1
1374 -- is a struct with fields "r" and "s", and O is a struct with fields "t".
1376 ------------------------------------------------
1377 -- Subprograms for Handling Variant Encodings --
1378 ------------------------------------------------
1380 procedure Get_Variant_Encoding (V : Node_Id);
1381 -- This procedure is called by Gigi with V being the variant node. The
1382 -- corresponding encoding string is returned in Name_Buffer with the length
1383 -- of the string in Name_Len, and an ASCII.NUL character stored following
1386 ---------------------------------
1387 -- Subtypes of Variant Records --
1388 ---------------------------------
1390 -- A subtype of a variant record is represented by a type in which the
1391 -- union field from the base type is replaced by one of the possible
1392 -- values. For example, if we have:
1394 -- type Var (Disc : Boolean := True) is record
1409 -- V3 : Var (False);
1411 -- Here V2, for example, is represented with a subtype whose name is
1412 -- something like TvarS3b, which is a struct with three fields. The first
1413 -- two fields are "disc" and "m" as for the base type, and the third field
1414 -- is S1, which contains the fields "r" and "s".
1416 -- The debugger should simply ignore structs with names of the form
1417 -- corresponding to variants, and consider the fields inside as belonging
1418 -- to the containing record.
1420 -------------------------------------------
1421 -- Character literals in Character Types --
1422 -------------------------------------------
1424 -- Character types are enumeration types at least one of whose enumeration
1425 -- literals is a character literal. Enumeration literals are usually simply
1426 -- represented using their identifier names. If the enumeration literal is
1427 -- a character literal, the name aencoded as described in the following
1430 -- A name QUhh, where each 'h' is a lower-case hexadecimal digit, stands
1431 -- for a character whose Unicode encoding is hh, and QWhhhh likewise stands
1432 -- for a wide character whose encoding is hhhh. The representation values
1433 -- are encoded as for ordinary enumeration literals (and have no necessary
1434 -- relationship to the values encoded in the names).
1436 -- For example, given the type declaration
1438 -- type x is (A, 'C', B);
1440 -- the second enumeration literal would be named QU43 and the value
1441 -- assigned to it would be 1.
1443 -----------------------------------------------
1444 -- Secondary Dispatch tables of tagged types --
1445 -----------------------------------------------
1447 procedure Get_Secondary_DT_External_Name
1449 Ancestor_Typ : Entity_Id;
1450 Suffix_Index : Int);
1451 -- Set Name_Buffer and Name_Len to the external name of one secondary
1452 -- dispatch table of Typ. If the interface has been inherited from some
1453 -- ancestor then Ancestor_Typ is such node (in this case the secondary DT
1454 -- is needed to handle overriden primitives); if there is no such ancestor
1455 -- then Ancestor_Typ is equal to Typ.
1457 -- Internal rule followed for the generation of the external name:
1459 -- Case 1. If the secondary dispatch has not been inherited from some
1460 -- ancestor of Typ then the external name is composed as
1462 -- External_Name (Typ) + Suffix_Number + 'P'
1464 -- Case 2. if the secondary dispatch table has been inherited from some
1465 -- ancestor then the external name is composed as follows:
1466 -- External_Name (Typ) + '_' + External_Name (Ancestor_Typ)
1467 -- + Suffix_Number + 'P'
1469 -- Note: We have to use the external names (instead of simply their names)
1470 -- to protect the frontend against programs that give the same name to all
1471 -- the interfaces and use the expanded name to reference them. The
1472 -- Suffix_Number is used to differentiate all the secondary dispatch
1473 -- tables of a given type.
1477 -- package Pkg1 is | package Pkg2 is | package Pkg3 is
1478 -- type Typ is | type Typ is | type Typ is
1479 -- interface; | interface; | interface;
1480 -- end Pkg1; | end Pkg; | end Pkg3;
1482 -- with Pkg1, Pkg2, Pkg3;
1483 -- package Case_1 is
1484 -- type Typ is new Pkg1.Typ and Pkg2.Typ and Pkg3.Typ with ...
1488 -- package Case_2 is
1489 -- type Typ is new Case_1.Typ with ...
1492 -- These are the external names generated for Case_1.Typ (note that
1493 -- Pkg1.Typ is associated with the Primary Dispatch Table, because it
1494 -- is the the parent of this type, and hence no external name is
1495 -- generated for it).
1496 -- case_1__typ0P (associated with Pkg2.Typ)
1497 -- case_1__typ1P (associated with Pkg3.Typ)
1499 -- These are the external names generated for Case_2.Typ:
1500 -- case_2__typ_case_1__typ0P
1501 -- case_2__typ_case_1__typ1P
1503 ----------------------------
1504 -- Effect of Optimization --
1505 ----------------------------
1507 -- If the program is compiled with optimization on (e.g. -O1 switch
1508 -- specified), then there may be variations in the output from the above
1509 -- specification. In particular, objects may disappear from the output.
1510 -- This includes not only constants and variables that the program declares
1511 -- at the source level, but also the x___L and x___U constants created to
1512 -- describe the lower and upper bounds of subtypes with dynamic bounds.
1513 -- This means for example, that array bounds may disappear if optimization
1514 -- is turned on. The debugger is expected to recognize that these constants
1515 -- are missing and deal as best as it can with the limited information
1518 ---------------------------------
1519 -- GNAT Extensions to DWARF2/3 --
1520 ---------------------------------
1522 -- If the compiler switch "-gdwarf+" is specified, GNAT Vendor extensions
1523 -- to DWARF2/3 are generated, with the following variations from the above
1526 -- Change in the contents of the DW_AT_name attribute.
1527 -- The operators are represented in their natural form. (Ie, the addition
1528 -- operator is written as "+" instead of "Oadd").
1529 -- The component separation string is "." instead of "__"
1531 -- Introduction of DW_AT_GNAT_encoding, encoded with value 0x2301.
1532 -- Any debugging information entry representing a program entity, named
1533 -- or implicit, may have a DW_AT_GNAT_encoding attribute. The value of
1534 -- this attribute is a string representing the suffix internally added
1535 -- by GNAT for various purposes, mainly for representing debug
1536 -- information compatible with other formats.
1538 -- If a debugging information entry has multiple encodings, all of them
1539 -- will be listed in DW_AT_GNAT_encoding. The separator for this list
1542 -- Introduction of DW_AT_GNAT_descriptive_type, encoded with value 0x2302
1543 -- Any debugging information entry representing a type may have a
1544 -- DW_AT_GNAT_descriptive_type attribute whose value is a reference,
1545 -- pointing to a debugging information entry representing another type
1546 -- associated to the type.
1548 -- Modification of the contents of the DW_AT_producer string.
1549 -- When emitting full GNAT Vendor extensions to DWARF2/3, "-gdwarf+"
1550 -- is appended to the DW_AT_producer string.
1552 -- When emitting only DW_AT_GNAT_descriptive_type, "-gdwarf+-" is
1553 -- appended to the DW_AT_producer string.