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