File : exp_dbug.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- E X P _ D B U G --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1996-2016, Free Software Foundation, Inc. --
10 -- --
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 3, 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 COPYING3. If not, go to --
19 -- http://www.gnu.org/licenses for a complete copy of the license. --
20 -- --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
23 -- --
24 ------------------------------------------------------------------------------
25
26 -- Expand routines for generation of special declarations used by the
27 -- debugger. In accordance with the Dwarf 2.2 specification, certain
28 -- type names are encoded to provide information to the debugger.
29
30 with Namet; use Namet;
31 with Types; use Types;
32 with Uintp; use Uintp;
33
34 package Exp_Dbug is
35
36 -----------------------------------------------------
37 -- Encoding and Qualification of Names of Entities --
38 -----------------------------------------------------
39
40 -- This section describes how the names of entities are encoded in the
41 -- generated debugging information.
42
43 -- An entity in Ada has a name of the form X.Y.Z ... E where X,Y,Z are the
44 -- enclosing scopes (not including Standard at the start).
45
46 -- The encoding of the name follows this basic qualified naming scheme,
47 -- where the encoding of individual entity names is as described in Namet
48 -- (i.e. in particular names present in the original source are folded to
49 -- all lower case, with upper half and wide characters encoded as described
50 -- in Namet). Upper case letters are used only for entities generated by
51 -- the compiler.
52
53 -- There are two cases, global entities, and local entities. In more formal
54 -- terms, local entities are those which have a dynamic enclosing scope,
55 -- and global entities are at the library level, except that we always
56 -- consider procedures to be global entities, even if they are nested
57 -- (that's because at the debugger level a procedure name refers to the
58 -- code, and the code is indeed a global entity, including the case of
59 -- nested procedures.) In addition, we also consider all types to be global
60 -- entities, even if they are defined within a procedure.
61
62 -- The reason for treating all type names as global entities is that a
63 -- number of our type encodings work by having related type names, and we
64 -- need the full qualification to keep this unique.
65
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 embedded package whose name is S, the encoded
70 -- name will include the components p.q.r.s.
71
72 -- For local entities, the encoded name only includes the components up to
73 -- the enclosing dynamic scope (other than a block). At run time, such a
74 -- dynamic scope is a subprogram, and the debugging formats know about
75 -- local variables of procedures, so it is not necessary to have full
76 -- qualification for such entities. In particular this means that direct
77 -- local variables of a procedure are not qualified.
78
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 Z.
81 -- The fully qualified names of the entities X and Z are:
82
83 -- V.W.X
84 -- V.W.Y.Z
85
86 -- but since V.W is a subprogram, the encoded names will end up
87 -- encoding only
88
89 -- x
90 -- y.z
91
92 -- The separating dots are translated into double underscores
93
94 -----------------------------
95 -- Handling of Overloading --
96 -----------------------------
97
98 -- The above scheme is incomplete for overloaded subprograms, since
99 -- overloading can legitimately result in case of two entities with
100 -- exactly the same fully qualified names. To distinguish between
101 -- entries in a set of overloaded subprograms, the encoded names are
102 -- serialized by adding the suffix:
103
104 -- __nn (two underscores)
105
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).
109
110 -- These names are prefixed by the normal full qualification. So for
111 -- example, the third instance of the subprogram qrs in package yz
112 -- would have the name:
113
114 -- yz__qrs__3
115
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.
121
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:
126
127 -- __nn_nn_nn ...
128
129 -- where the nn values are the homonym numbers as needed for any of the
130 -- qualifying entities, separated by a single underscore. If all the nn
131 -- values are 1, the suffix is omitted, Otherwise the suffix is present
132 -- (including any values of 1). The following example shows how this
133 -- suffixing works.
134
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;
139
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;
144
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;
149 -- end Yz;
150
151 --------------------
152 -- Operator Names --
153 --------------------
154
155 -- The above rules applied to operator names would result in names with
156 -- quotation marks, which are not typically allowed by assemblers and
157 -- linkers, and even if allowed would be odd and hard to deal with. To
158 -- avoid this problem, operator names are encoded as follows:
159
160 -- Oabs abs
161 -- Oand and
162 -- Omod mod
163 -- Onot not
164 -- Oor or
165 -- Orem rem
166 -- Oxor xor
167 -- Oeq =
168 -- One /=
169 -- Olt <
170 -- Ole <=
171 -- Ogt >
172 -- Oge >=
173 -- Oadd +
174 -- Osubtract -
175 -- Oconcat &
176 -- Omultiply *
177 -- Odivide /
178 -- Oexpon **
179
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 have
183 -- the name:
184
185 -- extra__messages__Oeq__2
186
187 ----------------------------------
188 -- Resolving Other Name Clashes --
189 ----------------------------------
190
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 in
193 -- the program, even if it is not an overloaded subprogram. There are
194 -- two possible confusions:
195
196 -- a.b
197
198 -- interpretation 1: entity b in body of package a
199 -- interpretation 2: child procedure b of package a
200
201 -- a.b.c
202
203 -- interpretation 1: entity c in child package a.b
204 -- interpretation 2: entity c in nested package b in body of a
205
206 -- It is perfectly legal in both cases for both interpretations to be
207 -- 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.
214
215 -- To deal with this situation, we provide two additional encoding
216 -- rules for names:
217
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.
226
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....
232
233 -- If none are body-nested package entities, then there is no suffix
234
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).
238
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).
244
245 -- For example, suppose we have
246
247 -- package x is
248 -- pragma Elaborate_Body;
249 -- m1 : integer; -- #1
250 -- end x;
251
252 -- package body x is
253 -- package y is m2 : integer; end y; -- #2
254 -- package body y is
255 -- package z is r : integer; end z; -- #3
256 -- end;
257 -- m3 : integer; -- #4
258 -- end x;
259
260 -- package x.y is
261 -- pragma Elaborate_Body;
262 -- m2 : integer; -- #5
263 -- end x.y;
264
265 -- package body x.y is
266 -- m3 : integer; -- #6
267 -- procedure j is -- #7
268 -- package k is
269 -- z : integer; -- #8
270 -- end k;
271 -- begin
272 -- null;
273 -- end j;
274 -- end x.y;
275
276 -- procedure x.m3 is begin null; end; -- #9
277
278 -- Then the encodings would be:
279
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)
289
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
292 -- clash as follows:
293
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.
297
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.
301
302 -- Note that enumeration literals never need Xb type suffixes, since
303 -- they are never referenced using global external names.
304
305 ---------------------
306 -- Interface Names --
307 ---------------------
308
309 -- Note: if an interface name is present, then the external name is
310 -- taken from the specified interface name. Given current limitations of
311 -- the gcc backend, this means that the debugging name is also set to
312 -- the interface name, but conceptually, it would be possible (and
313 -- indeed desirable) to have the debugging information still use the Ada
314 -- name as qualified above, so we still fully qualify the name in the
315 -- front end.
316
317 -------------------------------------
318 -- Encodings Related to Task Types --
319 -------------------------------------
320
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
323 -- task. Given
324 --
325 -- package body P is
326 -- task body TaskObj is
327 -- procedure F1 is ... end;
328 -- begin
329 -- B;
330 -- end TaskObj;
331 -- end P;
332 --
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
335 -- p__taskobjTKB.
336
337 ------------------------------------------
338 -- Encodings Related to Protected Types --
339 ------------------------------------------
340
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-
346 -- ponding record.
347
348 -- For a protected type prot, the Corresponding_Record_Type is encoded
349 -- as protV.
350
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.
359
360 -- Operations generated for protected entries follow the same encoding.
361 -- Each entry results in two subprograms: 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.
366
367 -- Given the declaration:
368
369 -- protected type Lock is
370 -- function Get return Integer;
371 -- procedure Set (X: Integer);
372 -- entry Update (Val : Integer);
373 -- private
374 -- Value : Integer := 0;
375 -- end Lock;
376
377 -- the following operations are created:
378
379 -- lock_getN
380 -- lock_getP,
381
382 -- lock_setN
383 -- lock_setP
384
385 -- lock_update_E1s
386 -- lock_udpate_B2s
387
388 -- If the protected type implements at least one interface, the
389 -- following additional operations are created:
390
391 -- lock_get
392
393 -- lock_set
394
395 -- These operations are used to ensure overriding of interface level
396 -- subprograms and proper dispatching on interface class-wide objects.
397 -- The bodies of these operations contain calls to their respective
398 -- protected versions:
399
400 -- function lock_get return Integer is
401 -- begin
402 -- return lock_getP;
403 -- end lock_get;
404
405 -- procedure lock_set (X : Integer) is
406 -- begin
407 -- lock_setP (X);
408 -- end lock_set;
409
410 ----------------------------------------------------
411 -- Conversion between Entities and External Names --
412 ----------------------------------------------------
413
414 procedure Get_External_Name
415 (Entity : Entity_Id;
416 Has_Suffix : Boolean := False;
417 Suffix : String := "");
418 -- Set Name_Buffer and Name_Len to the external name of the entity. The
419 -- external name is the Interface_Name, if specified, unless the entity
420 -- has an address clause or Has_Suffix is true.
421 --
422 -- If the Interface is not present, or not used, the external name is the
423 -- concatenation of:
424 --
425 -- - the string "_ada_", if the entity is a library subprogram,
426 -- - the names of any enclosing scopes, each followed by "__",
427 -- or "X_" if the next entity is a subunit)
428 -- - the name of the entity
429 -- - the string "$" (or "__" if target does not allow "$"), followed
430 -- by homonym suffix, if the entity is an overloaded subprogram
431 -- or is defined within an overloaded subprogram.
432 -- - the string "___" followed by Suffix if Has_Suffix is true.
433 --
434 -- Note that a call to this procedure has no effect if we are not
435 -- generating code, since the necessary information for computing the
436 -- proper external name is not available in this case.
437
438 -------------------------------------
439 -- Encoding for translation into C --
440 -------------------------------------
441
442 -- In Modify_Tree_For_C mode we must add encodings to dismabiguate cases
443 -- where Ada block structure cannot be directly translated. These cases
444 -- are as follows:
445
446 -- a) A loop variable may hide a homonym in an enclosing block
447 -- b) A block-local variable may hide a homonym in an enclosing block
448
449 -- In C these constructs are not scopes and we must distinguish the names
450 -- explicitly. In the first case we create a qualified name with the suffix
451 -- 'L', in the second case with a suffix 'B'.
452
453 --------------------------------------------
454 -- Subprograms for Handling Qualification --
455 --------------------------------------------
456
457 procedure Qualify_Entity_Names (N : Node_Id);
458 -- Given a node N, that represents a block, subprogram body, or package
459 -- body or spec, or protected or task type, sets a fully qualified name
460 -- for the defining entity of given construct, and also sets fully
461 -- qualified names for all enclosed entities of the construct (using
462 -- First_Entity/Next_Entity). Note that the actual modifications of the
463 -- names is postponed till a subsequent call to Qualify_All_Entity_Names.
464 -- Note: this routine does not deal with prepending _ada_ to library
465 -- subprogram names. The reason for this is that we only prepend _ada_
466 -- to the library entity itself, and not to names built from this name.
467
468 procedure Qualify_All_Entity_Names;
469 -- When Qualify_Entity_Names is called, no actual name changes are made,
470 -- i.e. the actual calls to Qualify_Entity_Name are deferred until a call
471 -- is made to this procedure. The reason for this deferral is that when
472 -- names are changed semantic processing may be affected. By deferring
473 -- the changes till just before gigi is called, we avoid any concerns
474 -- about such effects. Gigi itself does not use the names except for
475 -- output of names for debugging purposes (which is why we are doing
476 -- the name changes in the first place.
477
478 -- Note: the routines Get_Unqualified_[Decoded]_Name_String in Namet are
479 -- useful to remove qualification from a name qualified by the call to
480 -- Qualify_All_Entity_Names.
481
482 --------------------------------
483 -- Handling of Numeric Values --
484 --------------------------------
485
486 -- All numeric values here are encoded as strings of decimal digits. Only
487 -- integer values need to be encoded. A negative value is encoded as the
488 -- corresponding positive value followed by a lower case m for minus to
489 -- indicate that the value is negative (e.g. 2m for -2).
490
491 -------------------------
492 -- Type Name Encodings --
493 -------------------------
494
495 -- In the following typ is the name of the type as normally encoded by the
496 -- debugger rules, i.e. a non-qualified name, all in lower case, with
497 -- standard encoding of upper half and wide characters
498
499 ------------------------
500 -- Encapsulated Types --
501 ------------------------
502
503 -- In some cases, the compiler encapsulates a type by wrapping it in a
504 -- structure. For example, this is used when a size or alignment
505 -- specification requires a larger type. Consider:
506
507 -- type y is mod 2 ** 64;
508 -- for y'size use 256;
509
510 -- In this case the compile generates a structure type y___PAD, which
511 -- has a single field whose name is F. This single field is 64 bits
512 -- long and contains the actual value. This kind of padding is used
513 -- when the logical value to be stored is shorter than the object in
514 -- which it is allocated. For example if a size clause is used to set
515 -- a size of 256 for a signed integer value, then a typical choice is
516 -- to wrap a 64-bit integer in a 256 bit PAD structure.
517
518 -- A similar encapsulation is done for some packed array types, in which
519 -- case the structure type is y___JM and the field name is OBJECT.
520 -- This is used in the case of a packed array stored using modular
521 -- representation (see section on representation of packed array
522 -- objects). In this case the JM wrapping is used to achieve correct
523 -- positioning of the packed array value (left or right justified in its
524 -- field depending on endianness.
525
526 -- When the debugger sees an object of a type whose name has a suffix of
527 -- ___PAD or ___JM, the type will be a record containing a single field,
528 -- and the name of that field will be all upper case. In this case, it
529 -- should look inside to get the value of the inner field, and neither
530 -- the outer structure name, nor the field name should appear when the
531 -- value is printed.
532
533 -- When the debugger sees a record named REP being a field inside
534 -- another record, it should treat the fields inside REP as being part
535 -- of the outer record (this REP field is only present for code
536 -- generation purposes). The REP record should not appear in the values
537 -- printed by the debugger.
538
539 -----------------------
540 -- Fixed-Point Types --
541 -----------------------
542
543 -- Fixed-point types are encoded using a suffix that indicates the
544 -- delta and small values. The actual type itself is a normal integer
545 -- type.
546
547 -- typ___XF_nn_dd
548 -- typ___XF_nn_dd_nn_dd
549
550 -- The first form is used when small = delta. The value of delta (and
551 -- small) is given by the rational nn/dd, where nn and dd are decimal
552 -- integers.
553 --
554 -- The second form is used if the small value is different from the
555 -- delta. In this case, the first nn/dd rational value is for delta,
556 -- and the second value is for small.
557
558 --------------------
559 -- Discrete Types --
560 --------------------
561
562 -- Discrete types are coded with a suffix indicating the range in the
563 -- case where one or both of the bounds are discriminants or variable.
564
565 -- Note: at the current time, we also encode compile time known bounds
566 -- if they do not match the natural machine type bounds, but this may
567 -- be removed in the future, since it is redundant for most debugging
568 -- formats. However, we do not ever need XD encoding for enumeration
569 -- base types, since here it is always clear what the bounds are from
570 -- the total number of enumeration literals.
571
572 -- typ___XD
573 -- typ___XDL_lowerbound
574 -- typ___XDU_upperbound
575 -- typ___XDLU_lowerbound__upperbound
576
577 -- If a discrete type is a natural machine type (i.e. its bounds
578 -- correspond in a natural manner to its size), then it is left
579 -- unencoded. The above encoding forms are used when there is a
580 -- constrained range that does not correspond to the size or that
581 -- has discriminant references or other compile time known bounds.
582
583 -- The first form is used if both bounds are dynamic, in which case two
584 -- constant objects are present whose names are typ___L and typ___U in
585 -- the same scope as typ, and the values of these constants indicate
586 -- the bounds. As far as the debugger is concerned, these are simply
587 -- variables that can be accessed like any other variables. In the
588 -- enumeration case, these values correspond to the Enum_Rep values for
589 -- the lower and upper bounds.
590
591 -- The second form is used if the upper bound is dynamic, but the lower
592 -- bound is either constant or depends on a discriminant of the record
593 -- with which the type is associated. The upper bound is stored in a
594 -- constant object of name typ___U as previously described, but the
595 -- lower bound is encoded directly into the name as either a decimal
596 -- integer, or as the discriminant name.
597
598 -- The third form is similarly used if the lower bound is dynamic, but
599 -- the upper bound is compile time known or a discriminant reference,
600 -- in which case the lower bound is stored in a constant object of name
601 -- typ___L, and the upper bound is encoded directly into the name as
602 -- either a decimal integer, or as the discriminant name.
603
604 -- The fourth form is used if both bounds are discriminant references
605 -- or compile time known values, with the encoding first for the lower
606 -- bound, then for the upper bound, as previously described.
607
608 -------------------
609 -- Modular Types --
610 -------------------
611
612 -- A type declared
613
614 -- type x is mod N;
615
616 -- Is encoded as a subrange of an unsigned base type with lower bound
617 -- zero and upper bound N. That is, there is no name encoding. We use
618 -- the standard encodings provided by the debugging format. Thus we
619 -- give these types a non-standard interpretation: the standard
620 -- interpretation of our encoding would not, in general, imply that
621 -- arithmetic on type x was to be performed modulo N (especially not
622 -- when N is not a power of 2).
623
624 ------------------
625 -- Biased Types --
626 ------------------
627
628 -- Only discrete types can be biased, and the fact that they are biased
629 -- is indicated by a suffix of the form:
630
631 -- typ___XB_lowerbound__upperbound
632
633 -- Here lowerbound and upperbound are decimal integers, with the usual
634 -- (postfix "m") encoding for negative numbers. Biased types are only
635 -- possible where the bounds are compile time known, and the values are
636 -- represented as unsigned offsets from the lower bound given. For
637 -- example:
638
639 -- type Q is range 10 .. 15;
640 -- for Q'size use 3;
641
642 -- The size clause will force values of type Q in memory to be stored
643 -- in biased form (e.g. 11 will be represented by the bit pattern 001).
644
645 ----------------------------------------------
646 -- Record Types with Variable-Length Fields --
647 ----------------------------------------------
648
649 -- The debugging formats do not fully support these types, and indeed
650 -- some formats simply generate no useful information at all for such
651 -- types. In order to provide information for the debugger, gigi creates
652 -- a parallel type in the same scope with one of the names
653
654 -- type___XVE
655 -- type___XVU
656
657 -- The former name is used for a record and the latter for the union
658 -- that is made for a variant record (see below) if that record or union
659 -- has a field of variable size or if the record or union itself has a
660 -- variable size. These encodings suffix any other encodings that that
661 -- might be suffixed to the type name.
662
663 -- The idea here is to provide all the needed information to interpret
664 -- objects of the original type in the form of a "fixed up" type, which
665 -- is representable using the normal debugging information.
666
667 -- There are three cases to be dealt with. First, some fields may have
668 -- variable positions because they appear after variable-length fields.
669 -- To deal with this, we encode *all* the field bit positions of the
670 -- special ___XV type in a non-standard manner.
671
672 -- The idea is to encode not the position, but rather information that
673 -- allows computing the position of a field from the position of the
674 -- previous field. The algorithm for computing the actual positions of
675 -- all fields and the length of the record is as follows. In this
676 -- description, let P represent the current bit position in the record.
677
678 -- 1. Initialize P to 0
679
680 -- 2. For each field in the record:
681
682 -- 2a. If an alignment is given (see below), then round P up, if
683 -- needed, to the next multiple of that alignment.
684
685 -- 2b. If a bit position is given, then increment P by that amount
686 -- (that is, treat it as an offset from the end of the preceding
687 -- record).
688
689 -- 2c. Assign P as the actual position of the field
690
691 -- 2d. Compute the length, L, of the represented field (see below)
692 -- and compute P'=P+L. Unless the field represents a variant part
693 -- (see below and also Variant Record Encoding), set P to P'.
694
695 -- The alignment, if present, is encoded in the field name of the
696 -- record, which has a suffix:
697
698 -- fieldname___XVAnn
699
700 -- where the nn after the XVA indicates the alignment value in storage
701 -- units. This encoding is present only if an alignment is present.
702
703 -- The size of the record described by an XVE-encoded type (in bits) is
704 -- generally the maximum value attained by P' in step 2d above, rounded
705 -- up according to the record's alignment.
706
707 -- Second, the variable-length fields themselves are represented by
708 -- replacing the type by a special access type. The designated type of
709 -- this access type is the original variable-length type, and the fact
710 -- that this field has been transformed in this way is signalled by
711 -- encoding the field name as:
712
713 -- field___XVL
714
715 -- where field is the original field name. If a field is both
716 -- variable-length and also needs an alignment encoding, then the
717 -- encodings are combined using:
718
719 -- field___XVLnn
720
721 -- Note: the reason that we change the type is so that the resulting
722 -- type has no variable-length fields. At least some of the formats used
723 -- for debugging information simply cannot tolerate variable- length
724 -- fields, so the encoded information would get lost.
725
726 -- Third, in the case of a variant record, the special union that
727 -- contains the variants is replaced by a normal C union. In this case,
728 -- the positions are all zero.
729
730 -- Discriminants appear before any variable-length fields that depend on
731 -- them, with one exception. In some cases, a discriminant governing the
732 -- choice of a variant clause may appear in the list of fields of an XVE
733 -- type after the entry for the variant clause itself (this can happen
734 -- in the presence of a representation clause for the record type in the
735 -- source program). However, when this happens, the discriminant's
736 -- position may be determined by first applying the rules described in
737 -- this section, ignoring the variant clause. As a result, discriminants
738 -- can always be located independently of the variable-length fields
739 -- that depend on them.
740
741 -- The size of the ___XVE or ___XVU record or union is set to the
742 -- alignment (in bytes) of the original object so that the debugger
743 -- can calculate the size of the original type.
744
745 -- As an example of this encoding, consider the declarations:
746
747 -- type Q is array (1 .. V1) of Float; -- alignment 4
748 -- type R is array (1 .. V2) of Long_Float; -- alignment 8
749
750 -- type X is record
751 -- A : Character;
752 -- B : Float;
753 -- C : String (1 .. V3);
754 -- D : Float;
755 -- E : Q;
756 -- F : R;
757 -- G : Float;
758 -- end record;
759
760 -- The encoded type looks like:
761
762 -- type anonymousQ is access Q;
763 -- type anonymousR is access R;
764
765 -- type X___XVE is record
766 -- A : Character; -- position contains 0
767 -- B : Float; -- position contains 24
768 -- C___XVL : access String (1 .. V3); -- position contains 0
769 -- D___XVA4 : Float; -- position contains 0
770 -- E___XVL4 : anonymousQ; -- position contains 0
771 -- F___XVL8 : anonymousR; -- position contains 0
772 -- G : Float; -- position contains 0
773 -- end record;
774
775 -- Any bit sizes recorded for fields other than dynamic fields and
776 -- variants are honored as for ordinary records.
777
778 -- Notes:
779
780 -- 1) The B field could also have been encoded by using a position of
781 -- zero and an alignment of 4, but in such a case the coding by position
782 -- is preferred (since it takes up less space). We have used the
783 -- (illegal) notation access xxx as field types in the example above.
784
785 -- 2) The E field does not actually need the alignment indication but
786 -- this may not be detected in this case by the conversion routines.
787
788 -- 3) Our conventions do not cover all XVE-encoded records in which
789 -- some, but not all, fields have representation clauses. Such records
790 -- may, therefore, be displayed incorrectly by debuggers. This situation
791 -- is not common.
792
793 -----------------------
794 -- Base Record Types --
795 -----------------------
796
797 -- Under certain circumstances, debuggers need two descriptions of a
798 -- record type, one that gives the actual details of the base type's
799 -- structure (as described elsewhere in these comments) and one that may
800 -- be used to obtain information about the particular subtype and the
801 -- size of the objects being typed. In such cases the compiler will
802 -- substitute type whose name is typically compiler-generated and
803 -- irrelevant except as a key for obtaining the actual type.
804
805 -- Specifically, if this name is x, then we produce a record type named
806 -- x___XVS consisting of one field. The name of this field is that of
807 -- the actual type being encoded, which we'll call y. The type of this
808 -- single field can be either an arbitrary non-reference type, e.g. an
809 -- integer type, or a reference type; in the latter case, the referenced
810 -- type is also the actual type being encoded y. Both x and y may have
811 -- corresponding ___XVE types.
812
813 -- The size of the objects typed as x should be obtained from the
814 -- structure of x (and x___XVE, if applicable) as for ordinary types
815 -- unless there is a variable named x___XVZ, which, if present, will
816 -- hold the size (in bytes) of x. In this latter case, the size of the
817 -- x___XVS type will not be a constant but a reference to x___XVZ.
818
819 -- The type x will either be a subtype of y (see also Subtypes of
820 -- Variant Records, below) or will contain a single field of type y,
821 -- or no fields at all. The layout, types, and positions of these
822 -- fields will be accurate, if present. (Currently, however, the GDB
823 -- debugger makes no use of x except to determine its size).
824
825 -- Among other uses, XVS types are used to encode unconstrained types.
826 -- For example, given:
827 --
828 -- subtype Int is INTEGER range 0..10;
829 -- type T1 (N: Int := 0) is record
830 -- F1: String (1 .. N);
831 -- end record;
832 -- type AT1 is array (INTEGER range <>) of T1;
833 --
834 -- the element type for AT1 might have a type defined as if it had
835 -- been written:
836 --
837 -- type at1___PAD is record F : T1; end record;
838 -- for at1___PAD'Size use 16 * 8;
839 --
840 -- and there would also be:
841 --
842 -- type at1___PAD___XVS is record t1: reft1; end record;
843 -- type t1 is ...
844 -- type reft1 is <reference to t1>
845 --
846 -- Had the subtype Int been dynamic:
847 --
848 -- subtype Int is INTEGER range 0 .. M; -- M a variable
849 --
850 -- Then the compiler would also generate a declaration whose effect
851 -- would be
852 --
853 -- at1___PAD___XVZ: constant Integer := 32 + M * 8 + padding term;
854 --
855 -- Not all unconstrained types are so encoded; the XVS convention may be
856 -- unnecessary for unconstrained types of fixed size. However, this
857 -- encoding is always necessary when a subcomponent type (array
858 -- element's type or record field's type) is an unconstrained record
859 -- type some of whose components depend on discriminant values.
860
861 -----------------
862 -- Array Types --
863 -----------------
864
865 -- Since there is no way for the debugger to obtain the index subtypes
866 -- for an array type, we produce a type that has the name of the array
867 -- type followed by "___XA" and is a record type whose field types are
868 -- the respective types for the bounds (and whose field names are the
869 -- names of these types).
870
871 -- To conserve space, we do not produce this type unless one of the
872 -- index types is either an enumeration type, has a variable lower or
873 -- upper bound or is a biased type.
874
875 -- Given the full encoding of these types (see above description for
876 -- the encoding of discrete types), this means that all necessary
877 -- information for addressing arrays is available. In some debugging
878 -- formats, some or all of the bounds information may be available
879 -- redundantly, particularly in the fixed-point case, but this
880 -- information can in any case be ignored by the debugger.
881
882 ----------------------------
883 -- Note on Implicit Types --
884 ----------------------------
885
886 -- The compiler creates implicit type names in many situations where a
887 -- type is present semantically, but no specific name is present. For
888 -- example:
889
890 -- S : Integer range M .. N;
891
892 -- Here the subtype of S is not integer, but rather an anonymous subtype
893 -- of Integer. Where possible, the compiler generates names for such
894 -- anonymous types that are related to the type from which the subtype
895 -- is obtained as follows:
896
897 -- T name suffix
898
899 -- where name is the name from which the subtype is obtained, using
900 -- lower case letters and underscores, and suffix starts with an upper
901 -- case letter. For example the name for the above declaration might be:
902
903 -- TintegerS4b
904
905 -- If the debugger is asked to give the type of an entity and the type
906 -- has the form T name suffix, it is probably appropriate to just use
907 -- "name" in the response since this is what is meaningful to the
908 -- programmer.
909
910 -------------------------------------------------
911 -- Subprograms for Handling Encoded Type Names --
912 -------------------------------------------------
913
914 procedure Get_Encoded_Name (E : Entity_Id);
915 -- If the entity is a typename, store the external name of the entity as in
916 -- Get_External_Name, followed by three underscores plus the type encoding
917 -- in Name_Buffer with the length in Name_Len, and an ASCII.NUL character
918 -- stored following the name. Otherwise set Name_Buffer and Name_Len to
919 -- hold the entity name. Note that a call to this procedure has no effect
920 -- if we are not generating code, since the necessary information for
921 -- computing the proper encoded name is not available in this case.
922
923 --------------
924 -- Renaming --
925 --------------
926
927 -- Debugging information is generated for exception, object, package, and
928 -- subprogram renaming (generic renamings are not significant, since
929 -- generic templates are not relevant at debugging time).
930
931 -- Consider a renaming declaration of the form
932
933 -- x : typ renames y;
934
935 -- There is one case in which no special debugging information is required,
936 -- namely the case of an object renaming where the back end allocates a
937 -- reference for the renamed variable, and the entity x is this reference.
938 -- The debugger can handle this case without any special processing or
939 -- encoding (it won't know it was a renaming, but that does not matter).
940
941 -- All other cases of renaming generate a dummy variable for an entity
942 -- whose name is of the form:
943
944 -- x___XR_... for an object renaming
945 -- x___XRE_... for an exception renaming
946 -- x___XRP_... for a package renaming
947
948 -- and where the "..." represents a suffix that describes the structure of
949 -- the object name given in the renaming (see details below).
950
951 -- The name is fully qualified in the usual manner, i.e. qualified in the
952 -- same manner as the entity x would be. In the case of a package renaming
953 -- where x is a child unit, the qualification includes the name of the
954 -- parent unit, to disambiguate child units with the same simple name and
955 -- (of necessity) different parents.
956
957 -- Note: subprogram renamings are not encoded at the present time
958
959 -- The suffix of the variable name describing the renamed object is defined
960 -- to use the following encoding:
961
962 -- For the simple entity case, where y is just an entity name, the suffix
963 -- is of the form:
964
965 -- y___XE
966
967 -- i.e. the suffix has a single field, the first part matching the
968 -- name y, followed by a "___" separator, ending with sequence XE.
969 -- The entity name portion is fully qualified in the usual manner.
970 -- This same naming scheme is followed for all forms of encoded
971 -- renamings that rename a simple entity.
972
973 -- For the object renaming case where y is a selected component or an
974 -- indexed component, the variable name is suffixed by additional fields
975 -- that give details of the components. The name starts as above with a
976 -- y___XE name indicating the outer level object entity. Then a series of
977 -- selections and indexing operations can be specified as follows:
978
979 -- Indexed component
980
981 -- A series of subscript values appear in sequence, the number
982 -- corresponds to the number of dimensions of the array. The
983 -- subscripts have one of the following two forms:
984
985 -- XSnnn
986
987 -- Here nnn is a constant value, encoded as a decimal integer
988 -- (pos value for enumeration type case). Negative values have
989 -- a trailing 'm' as usual.
990
991 -- XSe
992
993 -- Here e is the (unqualified) name of a constant entity in the
994 -- same scope as the renaming which contains the subscript value.
995
996 -- Slice
997
998 -- For the slice case, we have two entries. The first is for the
999 -- lower bound of the slice, and has the form:
1000
1001 -- XLnnn
1002 -- XLe
1003
1004 -- Specifies the lower bound, using exactly the same encoding as
1005 -- for an XS subscript as described above.
1006
1007 -- Then the upper bound appears in the usual XSnnn/XSe form
1008
1009 -- Selected component
1010
1011 -- For a selected component, we have a single entry
1012
1013 -- XRf
1014
1015 -- Here f is the field name for the selection
1016
1017 -- For an explicit dereference (.all), we have a single entry
1018
1019 -- XA
1020
1021 -- As an example, consider the declarations:
1022
1023 -- package p is
1024 -- type q is record
1025 -- m : string (2 .. 5);
1026 -- end record;
1027 --
1028 -- type r is array (1 .. 10, 1 .. 20) of q;
1029 --
1030 -- g : r;
1031 --
1032 -- z : string renames g (1,5).m(2 ..3)
1033 -- end p;
1034
1035 -- The generated variable entity would appear as
1036
1037 -- p__z___XR_p__g___XEXS1XS5XRmXL2XS3 : _renaming_type;
1038 -- p__g___XE--------------------outer entity is g
1039 -- XS1-----------------first subscript for g
1040 -- XS5--------------second subscript for g
1041 -- XRm-----------select field m
1042 -- XL2--------lower bound of slice
1043 -- XS3-----upper bound of slice
1044
1045 -- Note that the type of the variable is a special internal type named
1046 -- _renaming_type. This type is an arbitrary type of zero size created
1047 -- in package Standard (see cstand.adb) and is ignored by the debugger.
1048
1049 function Debug_Renaming_Declaration (N : Node_Id) return Node_Id;
1050 -- The argument N is a renaming declaration. The result is a variable
1051 -- declaration as described in the above paragraphs. If N is not a special
1052 -- debug declaration, then Empty is returned. This function also takes care
1053 -- of setting Materialize_Entity on the renamed entity where required.
1054
1055 ---------------------------
1056 -- Packed Array Encoding --
1057 ---------------------------
1058
1059 -- For every constrained packed array, two types are created, and both
1060 -- appear in the debugging output:
1061
1062 -- The original declared array type is a perfectly normal array type, and
1063 -- its index bounds indicate the original bounds of the array.
1064
1065 -- The corresponding packed array type, which may be a modular type, or
1066 -- may be an array of bytes type (see Exp_Pakd for full details). This is
1067 -- the type that is actually used in the generated code and for debugging
1068 -- information for all objects of the packed type.
1069
1070 -- The name of the corresponding packed array type is:
1071
1072 -- ttt___XPnnn
1073
1074 -- where
1075
1076 -- ttt is the name of the original declared array
1077 -- nnn is the component size in bits (1-31)
1078
1079 -- Note that if the packed array is not bit-packed, the name will simply
1080 -- be tttP.
1081
1082 -- When the debugger sees that an object is of a type that is encoded in
1083 -- this manner, it can use the original type to determine the bounds and
1084 -- the component type, and the component size to determine the packing
1085 -- details.
1086
1087 -- For an unconstrained packed array, the corresponding packed array type
1088 -- is neither used in the generated code nor for debugging information,
1089 -- only the original type is used. In order to convey the packing in the
1090 -- debugging information, the compiler generates the associated fat- and
1091 -- thin-pointer types (see the Pointers to Unconstrained Array section
1092 -- below) using the name of the corresponding packed array type as the
1093 -- base name, i.e. ttt___XPnnn___XUP and ttt___XPnnn___XUT respectively.
1094
1095 -- When the debugger sees that an object is of a type that is encoded in
1096 -- this manner, it can use the type of the fields to determine the bounds
1097 -- and the component type, and the component size to determine the packing
1098 -- details.
1099
1100 -------------------------------------------
1101 -- Packed Array Representation in Memory --
1102 -------------------------------------------
1103
1104 -- Packed arrays are represented in tightly packed form, with no extra bits
1105 -- between components. This is true even when the component size is not a
1106 -- factor of the storage unit size, so that as a result it is possible for
1107 -- components to cross storage unit boundaries.
1108
1109 -- The layout in storage is identical, regardless of whether the
1110 -- implementation type is a modular type or an array-of-bytes type. See
1111 -- Exp_Pakd for details of how these implementation types are used, but for
1112 -- the purpose of the debugger, only the starting address of the object in
1113 -- memory is significant.
1114
1115 -- The following example should show clearly how the packing works in
1116 -- the little-endian and big-endian cases:
1117
1118 -- type B is range 0 .. 7;
1119 -- for B'Size use 3;
1120
1121 -- type BA is array (0 .. 5) of B;
1122 -- pragma Pack (BA);
1123
1124 -- BV : constant BA := (1,2,3,4,5,6);
1125
1126 -- Little endian case
1127
1128 -- BV'Address + 2 BV'Address + 1 BV'Address + 0
1129 -- +-----------------+-----------------+-----------------+
1130 -- | ? ? ? ? ? ? 1 1 | 0 1 0 1 1 0 0 0 | 1 1 0 1 0 0 0 1 |
1131 -- +-----------------+-----------------+-----------------+
1132 -- <---------> <-----> <---> <---> <-----> <---> <--->
1133 -- unused bits BV(5) BV(4) BV(3) BV(2) BV(1) BV(0)
1134 --
1135 -- Big endian case
1136 --
1137 -- BV'Address + 0 BV'Address + 1 BV'Address + 2
1138 -- +-----------------+-----------------+-----------------+
1139 -- | 0 0 1 0 1 0 0 1 | 1 1 0 0 1 0 1 1 | 1 0 ? ? ? ? ? ? |
1140 -- +-----------------+-----------------+-----------------+
1141 -- <---> <---> <-----> <---> <---> <-----> <--------->
1142 -- BV(0) BV(1) BV(2) BV(3) BV(4) BV(5) unused bits
1143
1144 -- Note that if a modular type is used to represent the array, the
1145 -- allocation in memory is not the same as a normal modular type. The
1146 -- difference occurs when the allocated object is larger than the size of
1147 -- the array. For a normal modular type, we extend the value on the left
1148 -- with zeroes.
1149
1150 -- For example, in the normal modular case, if we have a 6-bit modular
1151 -- type, declared as mod 2**6, and we allocate an 8-bit object for this
1152 -- type, then we extend the value with two bits on the most significant
1153 -- end, and in either the little-endian or big-endian case, the value 63
1154 -- is represented as 00111111 in binary in memory.
1155
1156 -- For a modular type used to represent a packed array, the rule is
1157 -- different. In this case, if we have to extend the value, then we do it
1158 -- with undefined bits (which are not initialized and whose value is
1159 -- irrelevant to any generated code). Furthermore these bits are on the
1160 -- right (least significant bits) in the big-endian case, and on the left
1161 -- (most significant bits) in the little-endian case.
1162
1163 -- For example, if we have a packed boolean array of 6 bits, all set to
1164 -- True, stored in an 8-bit object, then the value in memory in binary is
1165 -- ??111111 in the little-endian case, and 111111?? in the big-endian case.
1166
1167 -- This is done so that the representation of packed arrays does not
1168 -- depend on whether we use a modular representation or array of bytes
1169 -- as previously described. This ensures that we can pass such values by
1170 -- reference in the case where a subprogram has to be able to handle values
1171 -- stored in either form.
1172
1173 -- Note that when we extract the value of such a modular packed array, we
1174 -- expect to retrieve only the relevant bits, so in this same example, when
1175 -- we extract the value we get 111111 in both cases, and the code generated
1176 -- by the front end assumes this although it does not assume that any high
1177 -- order bits are defined.
1178
1179 -- There are opportunities for optimization based on the knowledge that the
1180 -- unused bits are irrelevant for these type of packed arrays. For example
1181 -- if we have two such 6-bit-in-8-bit values and we do an assignment:
1182
1183 -- a := b;
1184
1185 -- Then logically, we extract the 6 bits and store only 6 bits in the
1186 -- result, but the back end is free to simply assign the entire 8-bits in
1187 -- this case, since we don't actually care about the undefined bits.
1188 -- However, in the equality case, it is important to ensure that the
1189 -- undefined bits do not participate in an equality test.
1190
1191 -- If a modular packed array value is assigned to a register then logically
1192 -- it could always be held right justified, to avoid any need to shift,
1193 -- e.g. when doing comparisons. But probably this is a bad choice, as it
1194 -- would mean that an assignment such as a := above would require shifts
1195 -- when one value is in a register and the other value is in memory.
1196
1197 ------------------------------------------------------
1198 -- Subprograms for Handling Packed Array Type Names --
1199 ------------------------------------------------------
1200
1201 function Make_Packed_Array_Impl_Type_Name
1202 (Typ : Entity_Id;
1203 Csize : Uint) return Name_Id;
1204 -- This function is used in Exp_Pakd to create the name that is encoded as
1205 -- described above. The entity Typ provides the name ttt, and the value
1206 -- Csize is the component size that provides the nnn value.
1207
1208 --------------------------------------
1209 -- Pointers to Unconstrained Arrays --
1210 --------------------------------------
1211
1212 -- There are two kinds of pointers to arrays. The debugger can tell which
1213 -- format is in use by the form of the type of the pointer.
1214
1215 -- Fat Pointers
1216
1217 -- Fat pointers are represented as a struct with two fields. This
1218 -- struct has two distinguished field names:
1219
1220 -- P_ARRAY is a pointer to the array type. The name of this type is
1221 -- the unconstrained type followed by "___XUA". This array will have
1222 -- bounds which are the discriminants, and hence are unparsable, but
1223 -- will give the number of subscripts and the component type.
1224
1225 -- P_BOUNDS is a pointer to a struct, the name of whose type is the
1226 -- unconstrained array name followed by "___XUB" and which has
1227 -- fields of the form
1228
1229 -- LBn (n a decimal integer) lower bound of n'th dimension
1230 -- UBn (n a decimal integer) upper bound of n'th dimension
1231
1232 -- The bounds may be any integral type. In the case of an enumeration
1233 -- type, Enum_Rep values are used.
1234
1235 -- For a given unconstrained array type, the compiler will generate one
1236 -- fat-pointer type whose name is "arr___XUP", where "arr" is the name
1237 -- of the array type, and use it to represent the array type itself in
1238 -- the debugging information.
1239
1240 -- For each pointer to this unconstrained array type, the compiler will
1241 -- generate a typedef that points to the above "arr___XUP" fat-pointer
1242 -- type. As a consequence, when it comes to fat-pointer types:
1243
1244 -- 1. The type name is given by the typedef
1245
1246 -- 2. If the debugger is asked to output the type, the appropriate
1247 -- form is "access arr", except if the type name is "arr___XUP"
1248 -- for which it is the array definition.
1249
1250 -- Thin Pointers
1251
1252 -- The value of a thin pointer is a pointer to the second field of a
1253 -- structure with two fields. The name of this structure's type is
1254 -- "arr___XUT", where "arr" is the name of the unconstrained array
1255 -- type. Even though it actually points into middle of this structure,
1256 -- the thin pointer's type in debugging information is
1257 -- pointer-to-arr___XUT.
1258
1259 -- The first field of arr___XUT is named BOUNDS, and has a type named
1260 -- arr___XUB, with the structure described for such types in fat
1261 -- pointers, as described above.
1262
1263 -- The second field of arr___XUT is named ARRAY, and contains the
1264 -- actual array. Because this array has a dynamic size, determined by
1265 -- the BOUNDS field that precedes it, all of the information about
1266 -- arr___XUT is encoded in a parallel type named arr___XUT___XVE, with
1267 -- fields BOUNDS and ARRAY___XVL. As for previously described ___XVE
1268 -- types, ARRAY___XVL has a pointer-to-array type. However, the array
1269 -- type in this case is named arr___XUA and only its element type is
1270 -- meaningful, just as described for fat pointers.
1271
1272 --------------------------------------
1273 -- Tagged Types and Type Extensions --
1274 --------------------------------------
1275
1276 -- A type C derived from a tagged type P has a field named "_parent" of
1277 -- type P that contains its inherited fields. The type of this field is
1278 -- usually P (encoded as usual if it has a dynamic size), but may be a more
1279 -- distant ancestor, if P is a null extension of that type.
1280
1281 -- The type tag of a tagged type is a field named _tag, of type void*. If
1282 -- the type is derived from another tagged type, its _tag field is found in
1283 -- its _parent field.
1284
1285 -----------------------------
1286 -- Variant Record Encoding --
1287 -----------------------------
1288
1289 -- The variant part of a variant record is encoded as a single field in the
1290 -- enclosing record, whose name is:
1291
1292 -- discrim___XVN
1293
1294 -- where discrim is the unqualified name of the variant. This field name is
1295 -- built by gigi (not by code in this unit). For Unchecked_Union record,
1296 -- this discriminant will not appear in the record (see Unchecked Unions,
1297 -- below).
1298
1299 -- The type corresponding to this field has a name that is obtained by
1300 -- concatenating the type name with the above string and is similar to a C
1301 -- union, in which each member of the union corresponds to one variant.
1302 -- However, unlike a C union, the size of the type may be variable even if
1303 -- each of the components are fixed size, since it includes a computation
1304 -- of which variant is present. In that case, it will be encoded as above
1305 -- and a type with the suffix "___XVN___XVU" will be present.
1306
1307 -- The name of the union member is encoded to indicate the choices, and
1308 -- is a string given by the following grammar:
1309
1310 -- member_name ::= {choice} | others_choice
1311 -- choice ::= simple_choice | range_choice
1312 -- simple_choice ::= S number
1313 -- range_choice ::= R number T number
1314 -- number ::= {decimal_digit} [m]
1315 -- others_choice ::= O (upper case letter O)
1316
1317 -- The m in a number indicates a negative value. As an example of this
1318 -- encoding scheme, the choice 1 .. 4 | 7 | -10 would be represented by
1319
1320 -- R1T4S7S10m
1321
1322 -- In the case of enumeration values, the values used are the actual
1323 -- representation values in the case where an enumeration type has an
1324 -- enumeration representation spec (i.e. they are values that correspond
1325 -- to the use of the Enum_Rep attribute).
1326
1327 -- The type of the inner record is given by the name of the union type (as
1328 -- above) concatenated with the above string. Since that type may itself be
1329 -- variable-sized, it may also be encoded as above with a new type with a
1330 -- further suffix of "___XVU".
1331
1332 -- As an example, consider:
1333
1334 -- type Var (Disc : Boolean := True) is record
1335 -- M : Integer;
1336
1337 -- case Disc is
1338 -- when True =>
1339 -- R : Integer;
1340 -- S : Integer;
1341
1342 -- when False =>
1343 -- T : Integer;
1344 -- end case;
1345 -- end record;
1346
1347 -- V1 : Var;
1348
1349 -- In this case, the type var is represented as a struct with three fields.
1350 -- The first two are "disc" and "m", representing the values of these
1351 -- record components. The third field is a union of two types, with field
1352 -- names S1 and O. S1 is a struct with fields "r" and "s", and O is a
1353 -- struct with field "t".
1354
1355 ----------------------
1356 -- Unchecked Unions --
1357 ----------------------
1358
1359 -- The encoding for variant records changes somewhat under the influence
1360 -- of a "pragma Unchecked_Union" clause:
1361
1362 -- 1. The discriminant will not be present in the record, although its
1363 -- name is still used in the encodings.
1364 -- 2. Variants containing a single component named "x" of type "T" may
1365 -- be encoded, as in ordinary C unions, as a single field of the
1366 -- enclosing union type named "x" of type "T", dispensing with the
1367 -- enclosing struct. In this case, of course, the discriminant values
1368 -- corresponding to the variant are unavailable. As for normal
1369 -- variants, the field name "x" may be suffixed with ___XVL if it
1370 -- has dynamic size.
1371
1372 -- For example, the type Var in the preceding section, if followed by
1373 -- "pragma Unchecked_Union (Var);" may be encoded as a struct with two
1374 -- fields. The first is "m". The second field is a union of two types,
1375 -- with field names S1 and "t". As before, S1 is a struct with fields
1376 -- "r" and "s". "t" is a field of type Integer.
1377
1378 ------------------------------------------------
1379 -- Subprograms for Handling Variant Encodings --
1380 ------------------------------------------------
1381
1382 procedure Get_Variant_Encoding (V : Node_Id);
1383 -- This procedure is called by Gigi with V being the variant node. The
1384 -- corresponding encoding string is returned in Name_Buffer with the length
1385 -- of the string in Name_Len, and an ASCII.NUL character stored following
1386 -- the name.
1387
1388 ---------------------------------
1389 -- Subtypes of Variant Records --
1390 ---------------------------------
1391
1392 -- A subtype of a variant record is represented by a type in which the
1393 -- union field from the base type is replaced by one of the possible
1394 -- values. For example, if we have:
1395
1396 -- type Var (Disc : Boolean := True) is record
1397 -- M : Integer;
1398
1399 -- case Disc is
1400 -- when True =>
1401 -- R : Integer;
1402 -- S : Integer;
1403
1404 -- when False =>
1405 -- T : Integer;
1406 -- end case;
1407
1408 -- end record;
1409 -- V1 : Var;
1410 -- V2 : Var (True);
1411 -- V3 : Var (False);
1412
1413 -- Here V2, for example, is represented with a subtype whose name is
1414 -- something like TvarS3b, which is a struct with three fields. The first
1415 -- two fields are "disc" and "m" as for the base type, and the third field
1416 -- is S1, which contains the fields "r" and "s".
1417
1418 -- The debugger should simply ignore structs with names of the form
1419 -- corresponding to variants, and consider the fields inside as belonging
1420 -- to the containing record.
1421
1422 -----------------------------------------------
1423 -- Extra renamings for subprogram instances --
1424 -----------------------------------------------
1425
1426 procedure Build_Subprogram_Instance_Renamings
1427 (N : Node_Id;
1428 Wrapper : Entity_Id);
1429 -- The debugger has difficulties in recovering the value of actuals of an
1430 -- elementary type, from within the body of a subprogram instantiation.
1431 -- This is because such actuals generate an object declaration that is
1432 -- placed within the wrapper package of the instance, and the entity in
1433 -- these declarations is encoded in a complex way that GDB does not handle
1434 -- well. These new renaming declarations appear within the body of the
1435 -- subprogram, and are redundant from a visibility point of view, but They
1436 -- should have no measurable performance impact, and require no special
1437 -- decoding in the debugger.
1438
1439 -------------------------------------------
1440 -- Character literals in Character Types --
1441 -------------------------------------------
1442
1443 -- Character types are enumeration types at least one of whose enumeration
1444 -- literals is a character literal. Enumeration literals are usually simply
1445 -- represented using their identifier names. If the enumeration literal is
1446 -- a character literal, the name is encoded as described in the following
1447 -- paragraph.
1448
1449 -- A name QUhh, where each 'h' is a lower-case hexadecimal digit, stands
1450 -- for a character whose Unicode encoding is hh, and QWhhhh likewise stands
1451 -- for a wide character whose encoding is hhhh. The representation values
1452 -- are encoded as for ordinary enumeration literals (and have no necessary
1453 -- relationship to the values encoded in the names).
1454
1455 -- For example, given the type declaration
1456
1457 -- type x is (A, 'C', B);
1458
1459 -- the second enumeration literal would be named QU43 and the value
1460 -- assigned to it would be 1.
1461
1462 -----------------------------------------------
1463 -- Secondary Dispatch tables of tagged types --
1464 -----------------------------------------------
1465
1466 procedure Get_Secondary_DT_External_Name
1467 (Typ : Entity_Id;
1468 Ancestor_Typ : Entity_Id;
1469 Suffix_Index : Int);
1470 -- Set Name_Buffer and Name_Len to the external name of one secondary
1471 -- dispatch table of Typ. If the interface has been inherited from some
1472 -- ancestor then Ancestor_Typ is such node (in this case the secondary DT
1473 -- is needed to handle overridden primitives); if there is no such ancestor
1474 -- then Ancestor_Typ is equal to Typ.
1475 --
1476 -- Internal rule followed for the generation of the external name:
1477 --
1478 -- Case 1. If the secondary dispatch has not been inherited from some
1479 -- ancestor of Typ then the external name is composed as
1480 -- follows:
1481 -- External_Name (Typ) + Suffix_Number + 'P'
1482 --
1483 -- Case 2. if the secondary dispatch table has been inherited from some
1484 -- ancestor then the external name is composed as follows:
1485 -- External_Name (Typ) + '_' + External_Name (Ancestor_Typ)
1486 -- + Suffix_Number + 'P'
1487 --
1488 -- Note: We have to use the external names (instead of simply their names)
1489 -- to protect the frontend against programs that give the same name to all
1490 -- the interfaces and use the expanded name to reference them. The
1491 -- Suffix_Number is used to differentiate all the secondary dispatch
1492 -- tables of a given type.
1493 --
1494 -- Examples:
1495 --
1496 -- package Pkg1 is | package Pkg2 is | package Pkg3 is
1497 -- type Typ is | type Typ is | type Typ is
1498 -- interface; | interface; | interface;
1499 -- end Pkg1; | end Pkg; | end Pkg3;
1500 --
1501 -- with Pkg1, Pkg2, Pkg3;
1502 -- package Case_1 is
1503 -- type Typ is new Pkg1.Typ and Pkg2.Typ and Pkg3.Typ with ...
1504 -- end Case_1;
1505 --
1506 -- with Case_1;
1507 -- package Case_2 is
1508 -- type Typ is new Case_1.Typ with ...
1509 -- end Case_2;
1510 --
1511 -- These are the external names generated for Case_1.Typ (note that
1512 -- Pkg1.Typ is associated with the Primary Dispatch Table, because it
1513 -- is the parent of this type, and hence no external name is
1514 -- generated for it).
1515 -- case_1__typ0P (associated with Pkg2.Typ)
1516 -- case_1__typ1P (associated with Pkg3.Typ)
1517 --
1518 -- These are the external names generated for Case_2.Typ:
1519 -- case_2__typ_case_1__typ0P
1520 -- case_2__typ_case_1__typ1P
1521
1522 ----------------------------
1523 -- Effect of Optimization --
1524 ----------------------------
1525
1526 -- If the program is compiled with optimization on (e.g. -O1 switch
1527 -- specified), then there may be variations in the output from the above
1528 -- specification. In particular, objects may disappear from the output.
1529 -- This includes not only constants and variables that the program declares
1530 -- at the source level, but also the x___L and x___U constants created to
1531 -- describe the lower and upper bounds of subtypes with dynamic bounds.
1532 -- This means for example, that array bounds may disappear if optimization
1533 -- is turned on. The debugger is expected to recognize that these constants
1534 -- are missing and deal as best as it can with the limited information
1535 -- available.
1536
1537 ---------------------------------
1538 -- GNAT Extensions to DWARF2/3 --
1539 ---------------------------------
1540
1541 -- If the compiler switch "-gdwarf+" is specified, GNAT Vendor extensions
1542 -- to DWARF2/3 are generated, with the following variations from the above
1543 -- specification.
1544
1545 -- Change in the contents of the DW_AT_name attribute
1546
1547 -- The operators are represented in their natural form. (for example,
1548 -- the addition operator is written as "+" instead of "Oadd"). The
1549 -- component separator is "." instead of "__"
1550
1551 -- Introduction of DW_AT_GNAT_encoding, encoded with value 0x2301
1552
1553 -- Any debugging information entry representing a program entity, named
1554 -- or implicit, may have a DW_AT_GNAT_encoding attribute. The value of
1555 -- this attribute is a string representing the suffix internally added
1556 -- by GNAT for various purposes, mainly for representing debug
1557 -- information compatible with other formats. In particular this is
1558 -- useful for IDEs which need to filter out information internal to
1559 -- GNAT from their graphical interfaces.
1560
1561 -- If a debugging information entry has multiple encodings, all of them
1562 -- will be listed in DW_AT_GNAT_encoding using the list separator ':'.
1563
1564 -- Introduction of DW_AT_GNAT_descriptive_type, encoded with value 0x2302
1565
1566 -- Any debugging information entry representing a type may have a
1567 -- DW_AT_GNAT_descriptive_type attribute whose value is a reference,
1568 -- pointing to a debugging information entry representing another type
1569 -- associated to the type.
1570
1571 -- Modification of the contents of the DW_AT_producer string
1572
1573 -- When emitting full GNAT Vendor extensions to DWARF2/3, "-gdwarf+"
1574 -- is appended to the DW_AT_producer string.
1575 --
1576 -- When emitting only DW_AT_GNAT_descriptive_type, "-gdwarf+-" is
1577 -- appended to the DW_AT_producer string.
1578
1579 end Exp_Dbug;