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