|
1 \." |
|
2 \." the following line may be removed if the ff ligature works on your machine |
|
3 .lg 0 |
|
4 \." set up heading formats |
|
5 .ds HF 3 3 3 3 3 2 2 |
|
6 .ds HP +2 +2 +1 +0 +0 |
|
7 .nr Hs 5 |
|
8 .nr Hb 5 |
|
9 \." ============================================== |
|
10 \." Put current date in the following at each rev |
|
11 .ds vE rev 1.18, 31 March 2005 |
|
12 \." ============================================== |
|
13 \." ============================================== |
|
14 .ds | | |
|
15 .ds ~ ~ |
|
16 .ds ' ' |
|
17 .if t .ds Cw \&\f(CW |
|
18 .if n .ds Cw \fB |
|
19 .de Cf \" Place every other arg in Cw font, beginning with first |
|
20 .if \\n(.$=1 \&\*(Cw\\$1\fP |
|
21 .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2 |
|
22 .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP |
|
23 .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4 |
|
24 .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP |
|
25 .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6 |
|
26 .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP |
|
27 .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8 |
|
28 .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\ |
|
29 *(Cw |
|
30 .. |
|
31 .nr Cl 4 |
|
32 .SA 1 |
|
33 .TL |
|
34 MIPS Extensions to DWARF Version 2.0 |
|
35 .AF "" |
|
36 .AU "Silicon Graphics Computer Systems" |
|
37 .PF "'\*(vE'- \\\\nP -''" |
|
38 .AS 1 |
|
39 This document describes the MIPS/Silicon Graphics extensions |
|
40 to the "DWARF Information Format" (version 2.0.0 dated July 27, 1993). |
|
41 DWARF3 draft 8 (or draft 9) is out as of 2005, and |
|
42 is mentioned below where applicable. |
|
43 MIPS/IRIX compilers emit DWARF2 (with extensions). |
|
44 .P |
|
45 Rather than alter the base documents to describe the extensions |
|
46 we provide this separate document. |
|
47 .P |
|
48 The extensions documented here are subject to change. |
|
49 .P |
|
50 It also describes known bugs resulting in incorrect dwarf usage. |
|
51 .P |
|
52 \*(vE |
|
53 |
|
54 .AE |
|
55 .MT 4 |
|
56 |
|
57 .H 1 "INTRODUCTION" |
|
58 .P |
|
59 This |
|
60 document describes MIPS extensions |
|
61 to the DWARF debugging information format. |
|
62 The extensions documented here are subject to change at |
|
63 any time. |
|
64 .H 1 "64 BIT DWARF" |
|
65 .P |
|
66 The DWARF2 spec has no provision for 64 bit offsets. |
|
67 SGI-IRIX/MIPS Elf64 objects contain DWARF 2 with all offsets |
|
68 (and addresses) as 64bit values. |
|
69 This non-standard extension was adopted in 1992. |
|
70 Nothing in the dwarf itself identifies the dwarf as 64bit. |
|
71 This extension 64bit-offset dwarf cannot be mixed with 32bit-offset dwarf |
|
72 in a single object or executable, and SGI-IRIX/MIPS compilers |
|
73 and tools do not mix the sizes. |
|
74 .P |
|
75 In 2001 DWARF3 adopted a very different 64bit-offset |
|
76 format which can be mixed usefully with 32bit-offset DWARF2 or DWARF3. |
|
77 It is not very likely SGI-IRIX/MIPS compilers will switch to the |
|
78 now-standard |
|
79 DWARF3 64bit-offset scheme, but such a switch is theoretically |
|
80 possible and would be a good idea. |
|
81 .P |
|
82 SGI-IRIX/MIPS Elf32 objects |
|
83 contain DWARF2 with all offsets (and addresses) 32 bits. |
|
84 .H 1 "How much symbol information is emitted" |
|
85 The following standard DWARF V2 sections may be emitted: |
|
86 .AL |
|
87 .LI |
|
88 Section .debug_abbrev |
|
89 contains |
|
90 abbreviations supporting the .debug_info section. |
|
91 .LI |
|
92 Section .debug_info |
|
93 contains |
|
94 Debug Information Entries (DIEs). |
|
95 .LI |
|
96 Section .debug_frame |
|
97 contains |
|
98 stack frame descriptions. |
|
99 .LI |
|
100 Section .debug_line |
|
101 contains |
|
102 line number information. |
|
103 .LI |
|
104 Section .debug_aranges |
|
105 contains |
|
106 address range descriptions. |
|
107 .LI |
|
108 Section .debug_pubnames |
|
109 contains |
|
110 names of global functions and data. |
|
111 .P |
|
112 The following |
|
113 are MIPS extensions. |
|
114 Theses were created to allow debuggers to |
|
115 know names without having to look at |
|
116 the .debug_info section. |
|
117 .LI |
|
118 Section .debug_weaknames |
|
119 is a MIPS extension |
|
120 containing .debug_pubnames-like entries describing weak |
|
121 symbols. |
|
122 .LI |
|
123 Section .debug_funcnames |
|
124 is a MIPS extension |
|
125 containing .debug_pubnames-like entries describing file-static |
|
126 functions (C static functions). |
|
127 The gcc extension of nested subprograms (like Pascal) |
|
128 adds non-global non-static functions. These should be treated like |
|
129 static functions and gcc should add such to this section |
|
130 so that IRIX libexc(3C) will work correctly. |
|
131 Similarly, Ada functions which are non-global should be here too |
|
132 so that libexc(3C) can work. |
|
133 Putting it another way, every function (other than inline code) |
|
134 belongs either in .debug_pubnames or in .debug_funcnames |
|
135 or else libexc(3C) cannot find the function name. |
|
136 .LI |
|
137 Section .debug_varnames |
|
138 is a MIPS extension |
|
139 containing .debug_pubnames-like entries describing file-static |
|
140 data symbols (C static variables). |
|
141 .LI |
|
142 Section .debug_typenames |
|
143 is a MIPS extension |
|
144 containing .debug_pubnames-like entries describing file-level |
|
145 types. |
|
146 .P |
|
147 The following are not currently emitted. |
|
148 .LI |
|
149 Section .debug_macinfo |
|
150 Macro information is not currently emitted. |
|
151 .LI |
|
152 Section .debug_loc |
|
153 Location lists are not currently emitted. |
|
154 .LI |
|
155 Section .debug_str |
|
156 The string section is not currently emitted. |
|
157 .LE |
|
158 .H 2 "Overview of information emitted" |
|
159 We emit debug information in 3 flavors. |
|
160 We mention C here. |
|
161 The situation is essentially identical for f77, f90, and C++. |
|
162 .AL |
|
163 .LI |
|
164 "default C" |
|
165 We emit line information and DIEs for each subprogram. |
|
166 But no local symbols and no type information. |
|
167 Frame information is output. |
|
168 The DW_AT_producer string has the optimization level: for example |
|
169 "-O2". |
|
170 We put so much in the DW_AT_producer that the string |
|
171 is a significant user of space in .debug_info -- |
|
172 this is perhaps a poor use of space. |
|
173 When optimizing the IRIX CC/cc option -DEBUG:optimize_space |
|
174 eliminates such wasted space. |
|
175 Debuggers only currently use the lack of -g |
|
176 of DW_AT_producer |
|
177 as a hint as to how a 'step' command should be interpreted, and |
|
178 the rest of the string is not used for anything (unless |
|
179 a human looks at it for some reason), so if space-on-disk |
|
180 is an issue, it is quite appropriate to use -DEBUG:optimize_space |
|
181 and save disk space. |
|
182 Every function definition (not inline instances though) is mentioned |
|
183 in either .debug_pubnames or .debug_funcnames. |
|
184 This is crucial to allow libexc(3C) stack-traceback to work and |
|
185 show function names (for all languages). |
|
186 .LI |
|
187 "C with full symbols" |
|
188 All possible info is emitted. |
|
189 DW_AT_producer string has all options that might be of interest, |
|
190 which includes -D's, -U's, and the -g option. |
|
191 These options look like they came from the command line. |
|
192 We put so much in the DW_AT_producer that the string |
|
193 is a significant user of space in .debug_info. |
|
194 this is perhaps a poor use of space. |
|
195 Debuggers only currently use the -g |
|
196 of DW_AT_producer |
|
197 as a hint as to how a 'step' command should be interpreted, and |
|
198 the rest of the string is not used for anything (unless |
|
199 a human looks at it for some reason). |
|
200 Every function definition (not inline instances though) is mentioned |
|
201 in either .debug_pubnames or .debug_funcnames. |
|
202 This is crucial to allow libexc(3C) stack-traceback to work and |
|
203 show function names (for all languages). |
|
204 .LI |
|
205 "Assembler (-g, non -g are the same)" |
|
206 Frame information is output. |
|
207 No type information is emitted, but DIEs are prepared |
|
208 for globals. |
|
209 .LE |
|
210 .H 2 "Detecting 'full symbols' (-g)" |
|
211 The debugger depends on the existence of |
|
212 the DW_AT_producer string to determine if the |
|
213 compilation unit has full symbols or not. |
|
214 It looks for -g or -g[123] and accepts these as |
|
215 full symbols but an absent -g or a present -g0 |
|
216 is taken to mean that only basic symbols are defined and there |
|
217 are no local symbols and no type information. |
|
218 .P |
|
219 In various contexts the debugger will think the program is |
|
220 stripped or 'was not compiled with -g' unless the -g |
|
221 is in the DW_AT_producer string. |
|
222 .H 2 "DWARF and strip(1)" |
|
223 The DWARF section ".debug_frame" is marked SHF_MIPS_NOSTRIP |
|
224 and is not stripped by the strip(1) program. |
|
225 This is because the section is needed for doing |
|
226 stack back traces (essential for C++ |
|
227 and Ada exception handling). |
|
228 .P |
|
229 All .debug_* sections are marked with elf type |
|
230 SHT_MIPS_DWARF. |
|
231 Applications needing to access the various DWARF sections |
|
232 must use the section name to discriminate between them. |
|
233 |
|
234 .H 2 "Evaluating location expressions" |
|
235 When the debugger evaluates location expressions, it does so |
|
236 in 2 stages. In stage one it simply looks for the trivial |
|
237 location expressions and treats those as special cases. |
|
238 .P |
|
239 If the location expression is not trivial, it enters stage two. |
|
240 In this case it uses a stack to evaluate the expression. |
|
241 .P |
|
242 If the application is a 32-bit application, it does the operations |
|
243 on 32-bit values (address size values). Even though registers |
|
244 can be 64 bits in a 32-bit program all evaluations are done in |
|
245 32-bit quantities, so an attempt to calculate a 32-bit quantity |
|
246 by taking the difference of 2 64-bit register values will not |
|
247 work. The notion is that the stack machine is, by the dwarf |
|
248 definition, working in address size units. |
|
249 .P |
|
250 These values are then expanded to 64-bit values (addresses or |
|
251 offsets). This extension does not involve sign-extension. |
|
252 .P |
|
253 If the application is a 64-bit application, then the stack |
|
254 values are all 64 bits and all operations are done on 64 bits. |
|
255 .H 3 "The fbreg location op" |
|
256 Compilers shipped with IRIX 6.0 and 6.1 |
|
257 do not emit the fbreg location expression |
|
258 and never emit the DW_AT_frame_base attribute that it |
|
259 depends on. |
|
260 However, this changes |
|
261 with release 6.2 and these are now emitted routinely. |
|
262 |
|
263 .H 1 "Frame Information" |
|
264 .H 2 "Initial Instructions" |
|
265 The DWARF V2 spec |
|
266 provides for "initial instructions" in each CIE (page 61, |
|
267 section 6.4.1). |
|
268 However, it does not say whether there are default |
|
269 values for each column (register). |
|
270 .P |
|
271 Rather than force every CIE to have a long list |
|
272 of bytes to initialize all 32 integer registers, |
|
273 we define that the default values of all registers |
|
274 (as returned by libdwarf in the frame interface) |
|
275 are 'same value'. |
|
276 This is a good choice for many non-register-windows |
|
277 implementations. |
|
278 .H 2 "Augmentation string in debug_frame" |
|
279 The augmentation string we use in shipped compilers (up thru |
|
280 irix6.2) is the empty string. |
|
281 IRIX6.2 and later has an augmentation string |
|
282 the empty string ("") |
|
283 or "z" or "mti v1" |
|
284 where the "v1" is a version number (version 1). |
|
285 .P |
|
286 We do not believe that "mti v1" was emitted as the |
|
287 augmentation string in any shipped compiler. |
|
288 .P |
|
289 .H 3 "CIE processing based on augmentation string:" |
|
290 If the augmentation string begins with 'z', then it is followed |
|
291 immediately by a unsigned_leb_128 number giving the code alignment factor. |
|
292 Next is a signed_leb_128 number giving the data alignment factor. |
|
293 Next is a unsigned byte giving the number of the return address register. |
|
294 Next is an unsigned_leb_128 number giving the length of the 'augmentation' |
|
295 fields (the length of augmentation bytes, not |
|
296 including the unsigned_leb_128 length itself). |
|
297 As of release 6.2, the length of the CIE augmentation fields is 0. |
|
298 What this means is that it is possible to add new |
|
299 augmentations, z1, z2, etc and yet an old consumer to |
|
300 understand the entire CIE as it can bypass the |
|
301 augmentation it does not understand because the |
|
302 length of the augmentation fields is present. |
|
303 Presuming of course that all augmentation fields are |
|
304 simply additional information, |
|
305 not some 'changing of the meaning of |
|
306 an existing field'. |
|
307 Currently there is no CIE data in the augmentation for things |
|
308 beginning with 'z'. |
|
309 .P |
|
310 If the augmentation string is "mti v1" or "" then it is followed |
|
311 immediately by a unsigned_leb_128 number giving the code alignment factor. |
|
312 Next is a signed_leb_128 number giving the data alignment factor. |
|
313 Next is a unsigned byte giving the number of the return address register. |
|
314 .P |
|
315 If the augmentation string is something else, then the |
|
316 code alignment factor is assumed to be 4 and the data alignment |
|
317 factor is assumed to be -1 and the return |
|
318 address register is assumed to be 31. Arbitrarily. |
|
319 The library (libdwarf) assumes it does not understand the rest of the CIE. |
|
320 .P |
|
321 .H 3 "FDE processing based on augmentation" |
|
322 If the CIE augmentation string |
|
323 for an fde begins with 'z' |
|
324 then the next FDE field after the address_range field |
|
325 is an |
|
326 unsigned_leb_128 number giving the length of the 'augmentation' |
|
327 fields, and those fields follow immediately. |
|
328 |
|
329 .H 4 "FDE augmentation fields" |
|
330 .P |
|
331 If the CIE augmentation string is "mti v1" or "" |
|
332 then the FDE is exactly as described in the Dwarf Document section 6.4.1. |
|
333 .P |
|
334 Else, if the CIE augmentation string begins with "z" |
|
335 then the next field after the FDE augmentation length field |
|
336 is a Dwarf_Sword size offset into |
|
337 exception tables. |
|
338 If the CIE augmentation string does not begin with "z" |
|
339 (and is neither "mti v1" nor "") |
|
340 the FDE augmentation fields are skipped (not understood). |
|
341 Note that libdwarf actually (as of MIPSpro7.3 and earlier) |
|
342 only tests that the initial character of the augmentation |
|
343 string is 'z', and ignores the rest of the string, if any. |
|
344 So in reality the test is for a _prefix_ of 'z'. |
|
345 .P |
|
346 If the CIE augmentation string neither starts with 'z' nor is "" |
|
347 nor is "mti v1" then libdwarf (incorrectly) assumes that the |
|
348 table defining instructions start next. |
|
349 Processing (in libdwarf) will be incorrect. |
|
350 .H 2 "Stack Pointer recovery from debug_frame" |
|
351 There is no identifiable means in |
|
352 DWARF2 to say that the stack register is |
|
353 recovered by any particular operation. |
|
354 A 'register rule' works if the caller's |
|
355 stack pointer was copied to another |
|
356 register. |
|
357 An 'offset(N)' rule works if the caller's |
|
358 stack pointer was stored on the stack. |
|
359 However if the stack pointer is |
|
360 some register value plus/minus some offset, |
|
361 there is no means to say this in an FDE. |
|
362 For MIPS/IRIX, the recovered stack pointer |
|
363 of the next frame up the stack (towards main()) |
|
364 is simply the CFA value of the current |
|
365 frame, and the CFA value is |
|
366 precisely a register (value of a register) |
|
367 or a register plus offset (value of a register |
|
368 plus offset). This is a software convention. |
|
369 .H 1 "egcs dwarf extensions (egcs-1.1.2 extensions)" |
|
370 This and following egcs sections describe |
|
371 the extensions currently shown in egcs dwarf2. |
|
372 Note that egcs has chosen to adopt tag and |
|
373 attribute naming as if their choices were |
|
374 standard dwarf, not as if they were extensions. |
|
375 However, they are properly numbered as extensions. |
|
376 |
|
377 .H 2 "DW_TAG_format_label 0x4101" |
|
378 For FORTRAN 77, Fortran 90. |
|
379 Details of use not defined in egcs source, so |
|
380 unclear if used. |
|
381 .H 2 "DW_TAG_function_template 0x4102" |
|
382 For C++. |
|
383 Details of use not defined in egcs source, so |
|
384 unclear if used. |
|
385 .H 2 "DW_TAG_class_template 0x4103" |
|
386 For C++. |
|
387 Details of use not defined in egcs source, so |
|
388 unclear if used. |
|
389 .H 2 "DW_AT_sf_names 0x2101" |
|
390 Apparently only output in DWARF1, not DWARF2. |
|
391 .H 2 "DW_AT_src_info 0x2102" |
|
392 Apparently only output in DWARF1, not DWARF2. |
|
393 .H 2 "DW_AT_mac_info 0x2103" |
|
394 Apparently only output in DWARF1, not DWARF2. |
|
395 .H 2 "DW_AT_src_coords 0x2104" |
|
396 Apparently only output in DWARF1, not DWARF2. |
|
397 .H 2 "DW_AT_body_begin 0x2105" |
|
398 Apparently only output in DWARF1, not DWARF2. |
|
399 .H 2 "DW_AT_body_end 0x2106" |
|
400 Apparently only output in DWARF1, not DWARF2. |
|
401 |
|
402 .H 1 "egcs .eh_frame (non-sgi) (egcs-1.1.2 extensions)" |
|
403 egcs-1.1.2 (and earlier egcs) |
|
404 emits by default a section named .eh_frame |
|
405 for ia32 (and possibly other platforms) which |
|
406 is nearly identical to .debug_frame in format and content. |
|
407 This section is used for helping handle C++ exceptions. |
|
408 .P |
|
409 Because after linking there are sometimes zero-ed out bytes |
|
410 at the end of the eh_frame section, the reader code in |
|
411 dwarf_frame.c considers a zero cie/fde length as an indication |
|
412 that it is the end of the section. |
|
413 .P |
|
414 .H 2 "CIE_id 0" |
|
415 The section is an ALLOCATED section in an executable, and |
|
416 is therefore mapped into memory at run time. |
|
417 The CIE_pointer (aka CIE_id, section 6.4.1 |
|
418 of the DWARF2 document) is the field that |
|
419 distinguishes a CIE from an FDE. |
|
420 The designers of the egcs .eh_frame section |
|
421 decided to make the CIE_id |
|
422 be 0 as the CIE_pointer definition is |
|
423 .in +2 |
|
424 the number of bytes from the CIE-pointer in the FDE back to the |
|
425 applicable CIE. |
|
426 .in -2 |
|
427 In a dwarf .debug_frame section, the CIE_pointer is the |
|
428 offset in .debug_frame of the CIE for this fde, and |
|
429 since an offset can be zero of some CIE, the CIE_id |
|
430 cannot be 0, but must be all 1 bits . |
|
431 Note that the dwarf2.0 spec does specify the value of CIE_id |
|
432 as 0xffffffff |
|
433 (see section 7.23 of v2.0.0), |
|
434 though earlier versions of this extensions document |
|
435 incorrectly said it was not specified in the dwarf |
|
436 document. |
|
437 .H 2 "augmentation eh" |
|
438 The augmentation string in each CIE is "eh" |
|
439 which, with its following NUL character, aligns |
|
440 the following word to a 32bit boundary. |
|
441 Following the augmentation string is a 32bit |
|
442 word with the address of the __EXCEPTION_TABLE__, |
|
443 part of the exception handling data for egcs. |
|
444 .H 2 "DW_CFA_GNU_window_save 0x2d" |
|
445 This is effectively a flag for architectures with |
|
446 register windows, and tells the unwinder code that |
|
447 it must look to a previous frame for the |
|
448 correct register window set. |
|
449 As of this writing, egcs gcc/frame.c |
|
450 indicates this is for SPARC register windows. |
|
451 .H 2 "DW_CFA_GNU_args_size 0x2e" |
|
452 DW_CFA_GNU_args_size has a single uleb128 argument |
|
453 which is the size, in bytes, of the function's stack |
|
454 at that point in the function. |
|
455 .H 2 "__EXCEPTION_TABLE__" |
|
456 A series of 3 32bit word entries by default: |
|
457 0 word: low pc address |
|
458 1 word: high pc address |
|
459 2 word: pointer to exception handler code |
|
460 The end of the table is |
|
461 signaled by 2 words of -1 (not 3 words!). |
|
462 .H 1 "Interpretations of the DWARF V2 spec" |
|
463 .H 2 "template TAG spellings" |
|
464 The DWARF V2 spec spells two attributes in two ways. |
|
465 DW_TAG_template_type_param |
|
466 (listed in Figure 1, page 7) |
|
467 is spelled DW_TAG_template_type_parameter |
|
468 in the body of the document (section 3.3.7, page 28). |
|
469 We have adopted the spelling |
|
470 DW_TAG_template_type_param. |
|
471 .P |
|
472 DW_TAG_template_value_param |
|
473 (listed in Figure 1, page 7) |
|
474 is spelled DW_TAG_template_value_parameter |
|
475 in the body of the document (section 3.3.7, page 28). |
|
476 We have adopted the spelling |
|
477 DW_TAG_template_value_parameter. |
|
478 .P |
|
479 We recognize that the choices adopted are neither consistently |
|
480 the longer nor the shorter name. |
|
481 This inconsistency was an accident. |
|
482 .H 2 DW_FORM_ref_addr confusing |
|
483 Section 7.5.4, Attribute Encodings, describes |
|
484 DW_FORM_ref_addr. |
|
485 The description says the reference is the size of an address |
|
486 on the target architecture. |
|
487 This is surely a mistake, because on a 16bit-pointer-architecture |
|
488 it would mean that the reference could not exceed |
|
489 16 bits, which makes only |
|
490 a limited amount of sense as the reference is from one |
|
491 part of the dwarf to another, and could (in theory) |
|
492 be *on the disk* and not limited to what fits in memory. |
|
493 Since MIPS is 32 bit pointers (at the smallest) |
|
494 the restriction is not a problem for MIPS/SGI. |
|
495 The 32bit pointer ABIs are limited to 32 bit section sizes |
|
496 anyway (as a result of implementation details). |
|
497 And the 64bit pointer ABIs currently have the same limit |
|
498 as a result of how the compilers and tools are built |
|
499 (this has not proven to be a limit in practice, so far). |
|
500 .P |
|
501 This has been clarified in the DWARF3 spec and the IRIX use |
|
502 of DW_FORM_ref_addr being an offset is correct. |
|
503 .H 2 "Section .debug_macinfo in a debugger" |
|
504 It seems quite difficult, in general, to |
|
505 tie specific text(code) addresses to points in the |
|
506 stream of macro information for a particular compilation unit. |
|
507 So it's been difficult to see how to design a consumer |
|
508 interface to libdwarf for macro information. |
|
509 .P |
|
510 The best (simple to implement, easy for a debugger user to |
|
511 understand) candidate seems to be that |
|
512 the debugger asks for macros of a given name in a compilation |
|
513 unit, and the debugger responds with *all* the macros of that name. |
|
514 .H 3 "only a single choice exists" |
|
515 If there is exactly one, that is usable in expressions, if the |
|
516 debugger is able to evaluate such. |
|
517 .H 3 "multiple macros with same name". |
|
518 If there are multiple macros with the same name |
|
519 in a compilation unit, |
|
520 the debugger (and the debugger user and the application |
|
521 programmer) have |
|
522 a problem: confusion is quite possible. |
|
523 If the macros are simple the |
|
524 debugger user can simply substitute by hand in an expression. |
|
525 If the macros are complicated hand substitution will be |
|
526 impractical, and the debugger will have to identify the |
|
527 choices and let the debugger user choose an interpretation. |
|
528 .H 2 "Section 6.1.2 Lookup by address problem" |
|
529 Each entry is a beginning-address followed by a length. |
|
530 And the distinguished entry 0,0 is used to denote |
|
531 the end of a range of entries. |
|
532 .P |
|
533 This means that one must be careful not to emit a zero length, |
|
534 as in a .o (object file) the beginning address of |
|
535 a normal entry might be 0 (it is a section offset after all), |
|
536 and the resulting 0,0 would be taken as end-of-range, not |
|
537 as a valid entry. |
|
538 A dwarf dumper would have trouble with such data |
|
539 in an object file. |
|
540 .P |
|
541 In an a.out or shared object (dynamic shared object, DSO) |
|
542 no text will be at address zero so in such this problem does |
|
543 not arise. |
|
544 .H 2 "Section 5.10 Subrange Type Entries problem" |
|
545 It is specified that DW_AT_upper_bound (and lower bound) |
|
546 must be signed entries if there is no object type |
|
547 info to specify the bound type (Sec 5.10, end of section). |
|
548 One cannot tell (with some |
|
549 dwarf constant types) what the signedness is from the |
|
550 form itself (like DW_FORM_data1), so it is necessary |
|
551 to determine the object and type according to the rules |
|
552 in 5.10 and then if all that fails, the type is signed. |
|
553 It's a bit complicated and earlier versions of mips_extensions |
|
554 incorrectly said signedness was not defined. |
|
555 .H 2 "Section 5.5.6 Class Template Instantiations problem" |
|
556 Lots of room for implementor to canonicalize |
|
557 template declarations. Ie various folks won't agree. |
|
558 This is not serious since a given compiler |
|
559 will be consistent with itself and debuggers |
|
560 will have to cope! |
|
561 .H 2 "Section 2.4.3.4 # 11. operator spelling" |
|
562 DW_OP_add should be DW_OP_plus (page 14) |
|
563 (this mistake just one place on the page). |
|
564 .H 2 "No clear specification of C++ static funcs" |
|
565 There is no clear way to tell if a C++ member function |
|
566 is a static member or a non-static member function. |
|
567 (dwarf2read.c in gdb 4.18, for example, has this observation) |
|
568 .H 2 "Misspelling of DW_AT_const_value" |
|
569 Twice in appendix 1, DW_AT_const_value is misspelled |
|
570 as DW_AT_constant_value. |
|
571 .H 2 "Mistake in Atribute Encodings" |
|
572 Section 7.5.4, "Attribute Encodings" |
|
573 has a brief discussion of "constant" |
|
574 which says there are 6 forms of constants. |
|
575 It is incorrect in that it fails to mention (or count) |
|
576 the block forms, which are clearly allowed by |
|
577 section 4.1 "Data Object Entries" (see entry number 9 in |
|
578 the numbered list, on constants). |
|
579 .H 2 "DW_OP_bregx" |
|
580 The description of DW_OP_bregx in 2.4.3.2 (Register Based |
|
581 Addressing) is slightly misleading, in that it |
|
582 lists the offset first. |
|
583 As section 7.7.1 (Location Expression) |
|
584 makes clear, in the encoding the register number |
|
585 comes first. |
|
586 .H 1 "MIPS attributes" |
|
587 .H 2 "DW_AT_MIPS_fde" |
|
588 This extension to Dwarf appears only on subprogram TAGs and has as |
|
589 its value the offset, in the .debug_frame section, of the fde which |
|
590 describes the frame of this function. It is an optimization of |
|
591 sorts to have this present. |
|
592 |
|
593 .H 2 "DW_CFA_MIPS_advance_loc8 0x1d" |
|
594 This obvious extension to dwarf line tables enables encoding of 8 byte |
|
595 advance_loc values (for cases when such must be relocatable, |
|
596 and thus must be full length). Applicable only to 64-bit objects. |
|
597 |
|
598 .H 2 "DW_TAG_MIPS_loop 0x4081" |
|
599 For future use. Not currently emitted. |
|
600 Places to be emitted and attributes that this might own |
|
601 not finalized. |
|
602 |
|
603 .H 2 "DW_AT_MIPS_loop_begin 0x2002" |
|
604 For future use. Not currently emitted. |
|
605 Attribute form and content not finalized. |
|
606 |
|
607 .H 2 "DW_AT_MIPS_tail_loop_begin 0x2003" |
|
608 For future use. Not currently emitted. |
|
609 Attribute form and content not finalized. |
|
610 |
|
611 .H 2 "DW_AT_MIPS_epilog_begin 0x2004" |
|
612 For future use. Not currently emitted. |
|
613 Attribute form and content not finalized. |
|
614 |
|
615 .H 2 "DW_AT_MIPS_loop_unroll_factor 0x2005" |
|
616 For future use. Not currently emitted. |
|
617 Attribute form and content not finalized. |
|
618 |
|
619 .H 2 "DW_AT_MIPS_software_pipeline_depth 0x2006" |
|
620 For future use. Not currently emitted. |
|
621 Attribute form and content not finalized. |
|
622 .H 2 "DW_AT_MIPS_linkage_name 0x2007" |
|
623 The rules for mangling C++ names are not part of the |
|
624 C++ standard and are different for different versions |
|
625 of C++. With this extension, the compiler emits |
|
626 both the DW_AT_name for things with mangled names |
|
627 (recall that DW_AT_name is NOT the mangled form) |
|
628 and also emits DW_AT_MIPS_linkage_name whose value |
|
629 is the mangled name. |
|
630 .P |
|
631 This makes looking for the mangled name in other linker |
|
632 information straightforward. |
|
633 It also is passed (by the debugger) to the |
|
634 libmangle routines to generate names to present to the |
|
635 debugger user. |
|
636 .H 2 "DW_AT_MIPS_stride 0x2008" |
|
637 F90 allows assumed shape arguments and pointers to describe |
|
638 non-contiguous memory. A (runtime) descriptor contains address, |
|
639 bounds and stride information - rank and element size is known |
|
640 during compilation. The extent in each dimension is given by the |
|
641 bounds in a DW_TAG_subrange_type, but the stride cannot be |
|
642 represented in conventional dwarf. DW_AT_MIPS_stride was added as |
|
643 an attribute of a DW_TAG_subrange_type to describe the |
|
644 location of the stride. |
|
645 Used in the MIPSpro 7.2 (7.2.1 etc) compilers. |
|
646 .P |
|
647 If the stride is constant (ie: can be inferred from the type in the |
|
648 usual manner) DW_AT_MIPS_stride is absent. |
|
649 .P |
|
650 If DW_AT_MIPS_stride is present, the attribute contains a reference |
|
651 to a DIE which describes the location holding the stride, and the |
|
652 DW_AT_stride_size field of DW_TAG_array_type is ignored if |
|
653 present. The value of the stride is the number of |
|
654 4 byte words between |
|
655 elements along that axis. |
|
656 .P |
|
657 This applies to |
|
658 .nf |
|
659 a) Intrinsic types whose size is greater |
|
660 or equal to 4bytes ie: real*4,integer*8 |
|
661 complex etc, but not character types. |
|
662 |
|
663 b) Derived types (ie: structs) of any size, |
|
664 unless all components are of type character. |
|
665 .fi |
|
666 |
|
667 .H 2 "DW_AT_MIPS_abstract_name 0x2009" |
|
668 This attribute only appears in a DA_TAG_inlined_subroutine DIE. |
|
669 The value of this attribute is a string. |
|
670 When IPA inlines a routine and the abstract origin is |
|
671 in another compilation unit, there is a problem with putting |
|
672 in a reference, since the ordering and timing of the |
|
673 creation of references is unpredicatable with reference to |
|
674 the DIE and compilation unit the reference refers to. |
|
675 .P |
|
676 Since there may be NO ordering of the compilation units that |
|
677 allows a correct reference to be done without some kind of patching, |
|
678 and since even getting the information from one place to another |
|
679 is a problem, the compiler simply passes the problem on to the debugger. |
|
680 .P |
|
681 The debugger must match the DW_AT_MIPS_abstract_name |
|
682 in the concrete |
|
683 inlined instance DIE |
|
684 with the DW_AT_MIPS_abstract_name |
|
685 in the abstract inlined subroutine DIE. |
|
686 .P |
|
687 A dwarf-consumer-centric view of this and other inline |
|
688 issues could be expressed as follows: |
|
689 .nf |
|
690 If DW_TAG_subprogram |
|
691 If has DW_AT_inline is abstract instance root |
|
692 If has DW_AT_abstract_origin, is out-of-line instance |
|
693 of function (need abstract origin for some data) |
|
694 (abstract root in same CU (conceptually anywhere |
|
695 a ref can reach, but reaching outside of CU is |
|
696 a problem for ipa: see DW_AT_MIPS_abstract_name)) |
|
697 If has DW_AT_MIPS_abstract_name is abstract instance |
|
698 root( must have DW_AT_inline) and this name is used to |
|
699 match with the abstract root |
|
700 |
|
701 If DW_TAG_inline_subroutine |
|
702 Is concrete inlined subprogram instance. |
|
703 If has DW_AT_abstract_origin, it is a CU-local inline. |
|
704 If it has DW_AT_MIPS_abstract_name it is an |
|
705 inline whose abstract root is in another file (CU). |
|
706 .fi |
|
707 |
|
708 .H 2 "DW_AT_MIPS_clone_origin 0x200a" |
|
709 This attribute appears only in a cloned subroutine. |
|
710 The procedure is cloned from the same compilation unit. |
|
711 The value of this attribute is a reference to |
|
712 the original routine in this compilation unit. |
|
713 .P |
|
714 The 'original' routine means the routine which has all the |
|
715 original code. The cloned routines will always have |
|
716 been 'specialized' by IPA. |
|
717 A routine with DW_AT_MIPS_clone_origin |
|
718 will also have the DW_CC_nocall value of the DW_AT_calling_convention |
|
719 attribute. |
|
720 |
|
721 .H 2 "DW_AT_MIPS_has_inlines 0x200b" |
|
722 This attribute may appear in a DW_TAG_subprogram DIE. |
|
723 If present and it has the value True, then the subprogram |
|
724 has inlined functions somewhere in the body. |
|
725 .P |
|
726 By default, at startup, the debugger may not look for |
|
727 inlined functions in scopes inside the outer function. |
|
728 .P |
|
729 This is a hint to the debugger to look for the inlined functions |
|
730 so the debugger can set breakpoints on these in case the user |
|
731 requests 'stop in foo' and foo is inlined. |
|
732 .H 2 "DW_AT_MIPS_stride_byte 0x200c" |
|
733 Created for f90 pointer and assumed shape |
|
734 arrays. |
|
735 Used in the MIPSpro 7.2 (7.2.1 etc) compilers. |
|
736 A variant of DW_AT_MIPS_stride. |
|
737 This stride is interpreted as a byte count. |
|
738 Used for integer*1 and character arrays |
|
739 and arrays of derived type |
|
740 whose components are all character. |
|
741 .H 2 "DW_AT_MIPS_stride_elem 0x200d" |
|
742 Created for f90 pointer and assumed shape |
|
743 arrays. |
|
744 Used in the MIPSpro 7.2 (7.2.1 etc) compilers. |
|
745 A variant of DW_AT_MIPS_stride. |
|
746 This stride is interpreted as a byte-pair (2 byte) count. |
|
747 Used for integer*2 arrays. |
|
748 .H 2 "DW_AT_MIPS_ptr_dopetype 0x200e" |
|
749 See following. |
|
750 .H 2 "DW_AT_MIPS_allocatable_dopetype 0x200f" |
|
751 See following. |
|
752 .H 2 "DW_AT_MIPS_assumed_shape_dopetype 0x2010" |
|
753 DW_AT_MIPS_assumed_shape_dopetype, DW_AT_MIPS_allocatable_dopetype, |
|
754 and DW_AT_MIPS_ptr_dopetype have an attribute value |
|
755 which is a reference to a Fortran 90 Dope Vector. |
|
756 These attributes are introduced in MIPSpro7.3. |
|
757 They only apply to f90 arrays (where they are |
|
758 needed to describe arrays never properly described |
|
759 before in debug information). |
|
760 C, C++, f77, and most f90 arrays continue to be described |
|
761 in standard dwarf. |
|
762 .P |
|
763 The distinction between these three attributes is the f90 syntax |
|
764 distinction: keywords 'pointer' and 'allocatable' with the absence |
|
765 of these keywords on an assumed shape array being the third case. |
|
766 .P |
|
767 A "Dope Vector" is a struct (C struct) which describes |
|
768 a dynamically-allocatable array. |
|
769 In objects with full debugging the C struct will be |
|
770 in the dwarf information (of the f90 object, represented like C). |
|
771 A debugger will use the link to find the main struct DopeVector |
|
772 and will use that information to decode the dope vector. |
|
773 At the outer allocatable/assumed-shape/pointer |
|
774 the DW_AT_location points at the dope vector (so debugger |
|
775 calculations use that as a base). |
|
776 .H 2 "Overview of debugger use of dope vectors" |
|
777 Fundamentally, we build two distinct |
|
778 representations of the arrays and pointers. |
|
779 One, in dwarf, represents the statically-representable |
|
780 information (the types and |
|
781 variable/type-names, without type size information). |
|
782 The other, using dope vectors in memory, represents |
|
783 the run-time data of sizes. |
|
784 A debugger must process the two representations |
|
785 in parallel (and merge them) to deal with user expressions in |
|
786 a debugger. |
|
787 .H 2 "Example f90 code for use in explanation" |
|
788 [Note |
|
789 We want dwarf output with *exactly* |
|
790 this little (arbitrary) example. |
|
791 Not yet available. |
|
792 end Note] |
|
793 Consider the following code. |
|
794 .nf |
|
795 type array_ptr |
|
796 real :: myvar |
|
797 real, dimension (:), pointer :: ap |
|
798 end type array_ptr |
|
799 |
|
800 type (array_ptr), allocatable, dimension (:) :: arrays |
|
801 |
|
802 allocate (arrays(20)) |
|
803 do i = 1,20 |
|
804 allocate (arrays(i)%ap(i)) |
|
805 end do |
|
806 .fi |
|
807 arrays is an allocatable array (1 dimension) whose size is |
|
808 not known at compile time (it has |
|
809 a Dope Vector). At run time, the |
|
810 allocate statement creats 20 array_ptr dope vectors |
|
811 and marks the base arrays dopevector as allocated. |
|
812 The myvar variable is just there to add complexity to |
|
813 the example :-) |
|
814 .nf |
|
815 In the loop, arrays(1)%ap(1) |
|
816 is allocated as a single element array of reals. |
|
817 In the loop, arrays(2)%ap(2) |
|
818 is allocated as an array of two reals. |
|
819 ... |
|
820 In the loop, arrays(20)%ap(20) |
|
821 is allocated as an array of twenty reals. |
|
822 .fi |
|
823 .H 2 "the problem with standard dwarf and this example" |
|
824 .sp |
|
825 In dwarf, there is no way to find the array bounds of arrays(3)%ap, |
|
826 for example, (which are 1:3 in f90 syntax) |
|
827 since any location expression in an ap array lower bound |
|
828 attribute cannot involve the 3 (the 3 is known at debug time and |
|
829 does not appear in the running binary, so no way for the |
|
830 location expression to get to it). |
|
831 And of course the 3 must actually index across the array of |
|
832 dope vectors in 'arrays' in our implementation, but that is less of |
|
833 a problem than the problem with the '3'. |
|
834 .sp |
|
835 Plus dwarf has no way to find the 'allocated' flag in the |
|
836 dope vector (so the debugger can know when the allocate is done |
|
837 for a particular arrays(j)%ap). |
|
838 .sp |
|
839 Consequently, the calculation of array bounds and indices |
|
840 for these dynamically created f90 arrays |
|
841 is now pushed of into the debugger, which must know the |
|
842 field names and usages of the dope vector C structure and |
|
843 use the field offsets etc to find data arrays. |
|
844 C, C++, f77, and most f90 arrays continue to be described |
|
845 in standard dwarf. |
|
846 At the outer allocatable/assumed-shape/pointer |
|
847 the DW_AT_location points at the dope vector (so debugger |
|
848 calculations use that as a base). |
|
849 .P |
|
850 It would have been nice to design a dwarf extension |
|
851 to handle the above problems, but |
|
852 the methods considered to date were not |
|
853 any more consistent with standard dwarf than |
|
854 this dope vector centric approach: essentially just |
|
855 as much work in the debugger appeared necessary either way. |
|
856 A better (more dwarf-ish) |
|
857 design would be welcome information. |
|
858 |
|
859 .H 2 "A simplified sketch of the dwarf information" |
|
860 [Note: |
|
861 Needs to be written. |
|
862 end Note] |
|
863 |
|
864 .H 2 "A simplified sketch of the dope vector information" |
|
865 [Note: |
|
866 This one is simplified. |
|
867 Details left out that should be here. Amplify. |
|
868 end Note] |
|
869 This is an overly simplified version of a dope vector, |
|
870 presented as an initial hint. |
|
871 Full details presented later. |
|
872 .nf |
|
873 struct simplified{ |
|
874 void *base; // pointer to the data this describes |
|
875 long el_len; |
|
876 int assoc:1 |
|
877 int ptr_alloc:1 |
|
878 int num_dims:3; |
|
879 struct dims_s { |
|
880 long lb; |
|
881 long ext; |
|
882 long str_m; |
|
883 } dims[7]; |
|
884 }; |
|
885 .fi |
|
886 Only 'num_dims' elements of dims[] are actually used. |
|
887 |
|
888 .H 2 "The dwarf information" |
|
889 |
|
890 Here is dwarf information from the compiler for |
|
891 the example above, as printed by dwarfdump(1) |
|
892 .nf |
|
893 [Note: |
|
894 The following may not be the test. |
|
895 Having field names with '.' in the name is |
|
896 not such a good idea, as it conflicts with the |
|
897 use of '.' in dbx extended naming. |
|
898 Something else, like _$, would be much easier |
|
899 to work with in dbx (customers won't care about this, |
|
900 for the most part, |
|
901 but folks working on dbx will, and in those |
|
902 rare circumstances when a customer cares, |
|
903 the '.' will be a real problem in dbx.). |
|
904 Note that to print something about .base., in dbx one |
|
905 would have to do |
|
906 whatis `.base.` |
|
907 where that is the grave accent, or back-quote I am using. |
|
908 With extended naming one do |
|
909 whatis `.dope.`.`.base.` |
|
910 which is hard to type and hard to read. |
|
911 end Note] |
|
912 |
|
913 <2>< 388> DW_TAG_array_type |
|
914 DW_AT_name .base. |
|
915 DW_AT_type <815> |
|
916 DW_AT_declaration yes(1) |
|
917 <3>< 401> DW_TAG_subrange_type |
|
918 DW_AT_lower_bound 0 |
|
919 DW_AT_upper_bound 0 |
|
920 <2>< 405> DW_TAG_pointer_type |
|
921 DW_AT_type <388> |
|
922 DW_AT_byte_size 4 |
|
923 DW_AT_address_class 0 |
|
924 <2>< 412> DW_TAG_structure_type |
|
925 DW_AT_name .flds. |
|
926 DW_AT_byte_size 28 |
|
927 <3>< 421> DW_TAG_member |
|
928 DW_AT_name el_len |
|
929 DW_AT_type <815> |
|
930 DW_AT_data_member_location DW_OP_consts 0 |
|
931 <3>< 436> DW_TAG_member |
|
932 DW_AT_name assoc |
|
933 DW_AT_type <841> |
|
934 DW_AT_byte_size 0 |
|
935 DW_AT_bit_offset 0 |
|
936 DW_AT_bit_size 1 |
|
937 DW_AT_data_member_location DW_OP_consts 4 |
|
938 <3>< 453> DW_TAG_member |
|
939 DW_AT_name ptr_alloc |
|
940 DW_AT_type <841> |
|
941 DW_AT_byte_size 0 |
|
942 DW_AT_bit_offset 1 |
|
943 DW_AT_bit_size 1 |
|
944 DW_AT_data_member_location DW_OP_consts 4 |
|
945 <3>< 474> DW_TAG_member |
|
946 DW_AT_name p_or_a |
|
947 DW_AT_type <841> |
|
948 DW_AT_byte_size 0 |
|
949 DW_AT_bit_offset 2 |
|
950 DW_AT_bit_size 2 |
|
951 DW_AT_data_member_location DW_OP_consts 4 |
|
952 <3>< 492> DW_TAG_member |
|
953 DW_AT_name a_contig |
|
954 DW_AT_type <841> |
|
955 DW_AT_byte_size 0 |
|
956 DW_AT_bit_offset 4 |
|
957 DW_AT_bit_size 1 |
|
958 DW_AT_data_member_location DW_OP_consts 4 |
|
959 <3>< 532> DW_TAG_member |
|
960 DW_AT_name num_dims |
|
961 DW_AT_type <841> |
|
962 DW_AT_byte_size 0 |
|
963 DW_AT_bit_offset 29 |
|
964 DW_AT_bit_size 3 |
|
965 DW_AT_data_member_location DW_OP_consts 8 |
|
966 <3>< 572> DW_TAG_member |
|
967 DW_AT_name type_code |
|
968 DW_AT_type <841> |
|
969 DW_AT_byte_size 0 |
|
970 DW_AT_bit_offset 0 |
|
971 DW_AT_bit_size 32 |
|
972 DW_AT_data_member_location DW_OP_consts 16 |
|
973 <3>< 593> DW_TAG_member |
|
974 DW_AT_name orig_base |
|
975 DW_AT_type <841> |
|
976 DW_AT_data_member_location DW_OP_consts 20 |
|
977 <3>< 611> DW_TAG_member |
|
978 DW_AT_name orig_size |
|
979 DW_AT_type <815> |
|
980 DW_AT_data_member_location DW_OP_consts 24 |
|
981 <2>< 630> DW_TAG_structure_type |
|
982 DW_AT_name .dope_bnd. |
|
983 DW_AT_byte_size 12 |
|
984 <3>< 643> DW_TAG_member |
|
985 DW_AT_name lb |
|
986 DW_AT_type <815> |
|
987 DW_AT_data_member_location DW_OP_consts 0 |
|
988 <3>< 654> DW_TAG_member |
|
989 DW_AT_name ext |
|
990 DW_AT_type <815> |
|
991 DW_AT_data_member_location DW_OP_consts 4 |
|
992 <3>< 666> DW_TAG_member |
|
993 DW_AT_name str_m |
|
994 DW_AT_type <815> |
|
995 DW_AT_data_member_location DW_OP_consts 8 |
|
996 <2>< 681> DW_TAG_array_type |
|
997 DW_AT_name .dims. |
|
998 DW_AT_type <630> |
|
999 DW_AT_declaration yes(1) |
|
1000 <3>< 694> DW_TAG_subrange_type |
|
1001 DW_AT_lower_bound 0 |
|
1002 DW_AT_upper_bound 0 |
|
1003 <2>< 698> DW_TAG_structure_type |
|
1004 DW_AT_name .dope. |
|
1005 DW_AT_byte_size 44 |
|
1006 <3>< 707> DW_TAG_member |
|
1007 DW_AT_name base |
|
1008 DW_AT_type <405> |
|
1009 DW_AT_data_member_location DW_OP_consts 0 |
|
1010 <3>< 720> DW_TAG_member |
|
1011 DW_AT_name .flds |
|
1012 DW_AT_type <412> |
|
1013 DW_AT_data_member_location DW_OP_consts 4 |
|
1014 <3>< 734> DW_TAG_member |
|
1015 DW_AT_name .dims. |
|
1016 DW_AT_type <681> |
|
1017 DW_AT_data_member_location DW_OP_consts 32 |
|
1018 <2>< 750> DW_TAG_variable |
|
1019 DW_AT_type <815> |
|
1020 DW_AT_location DW_OP_fbreg -32 |
|
1021 DW_AT_artificial yes(1) |
|
1022 <2>< 759> DW_TAG_variable |
|
1023 DW_AT_type <815> |
|
1024 DW_AT_location DW_OP_fbreg -28 |
|
1025 DW_AT_artificial yes(1) |
|
1026 <2>< 768> DW_TAG_variable |
|
1027 DW_AT_type <815> |
|
1028 DW_AT_location DW_OP_fbreg -24 |
|
1029 DW_AT_artificial yes(1) |
|
1030 <2>< 777> DW_TAG_array_type |
|
1031 DW_AT_type <815> |
|
1032 DW_AT_declaration yes(1) |
|
1033 <3>< 783> DW_TAG_subrange_type |
|
1034 DW_AT_lower_bound <750> |
|
1035 DW_AT_count <759> |
|
1036 DW_AT_MIPS_stride <768> |
|
1037 <2>< 797> DW_TAG_variable |
|
1038 DW_AT_decl_file 1 |
|
1039 DW_AT_decl_line 1 |
|
1040 DW_AT_name ARRAY |
|
1041 DW_AT_type <698> |
|
1042 DW_AT_location DW_OP_fbreg -64 DW_OP_deref |
|
1043 <1>< 815> DW_TAG_base_type |
|
1044 DW_AT_name INTEGER_4 |
|
1045 DW_AT_encoding DW_ATE_signed |
|
1046 DW_AT_byte_size 4 |
|
1047 <1>< 828> DW_TAG_base_type |
|
1048 DW_AT_name INTEGER_8 |
|
1049 DW_AT_encoding DW_ATE_signed |
|
1050 DW_AT_byte_size 8 |
|
1051 <1>< 841> DW_TAG_base_type |
|
1052 DW_AT_name INTEGER*4 |
|
1053 DW_AT_encoding DW_ATE_unsigned |
|
1054 DW_AT_byte_size 4 |
|
1055 <1>< 854> DW_TAG_base_type |
|
1056 DW_AT_name INTEGER*8 |
|
1057 DW_AT_encoding DW_ATE_unsigned |
|
1058 DW_AT_byte_size 8 |
|
1059 |
|
1060 .fi |
|
1061 .H 2 "The dope vector structure details" |
|
1062 A dope vector is the following C struct, "dopevec.h". |
|
1063 Not all the fields are of use to a debugger. |
|
1064 It may be that not all fields will show up |
|
1065 in the f90 dwarf (since not all are of interest to debuggers). |
|
1066 .nf |
|
1067 [Note: |
|
1068 Need details on the use of each field. |
|
1069 And need to know which are really 32 bits and which |
|
1070 are 32 or 64. |
|
1071 end Note] |
|
1072 The following |
|
1073 struct |
|
1074 is a representation of all the dope vector fields. |
|
1075 It suppresses irrelevant detail and may not |
|
1076 exactly match the layout in memory (a debugger must |
|
1077 examine the dwarf to find the fields, not |
|
1078 compile this structure into the debugger!). |
|
1079 .nf |
|
1080 struct .dope. { |
|
1081 void *base; // pointer to data |
|
1082 struct .flds. { |
|
1083 long el_len; // length of element in bytes? |
|
1084 unsigned int assoc:1; //means? |
|
1085 unsigned int ptr_alloc:1; //means? |
|
1086 unsigned int p_or_a:2; //means? |
|
1087 unsigned int a_contig:1; // means? |
|
1088 unsigned int num_dims: 3; // 0 thru 7 |
|
1089 unsigned int type_code:32; //values? |
|
1090 unsigned int orig_base; //void *? means? |
|
1091 long orig_size; // means? |
|
1092 } .flds; |
|
1093 |
|
1094 struct .dope_bnd. { |
|
1095 long lb ; // lower bound |
|
1096 long ext ; // means? |
|
1097 long str_m; // means? |
|
1098 } .dims[7]; |
|
1099 } |
|
1100 .fi |
|
1101 |
|
1102 .H 2 "DW_AT_MIPS_assumed_size 0x2011" |
|
1103 This flag was invented to deal with f90 arrays. |
|
1104 For example: |
|
1105 |
|
1106 .nf |
|
1107 pointer (rptr, axx(1)) |
|
1108 pointer (iptr, ita(*)) |
|
1109 rptr = malloc (100*8) |
|
1110 iptr = malloc (100*4) |
|
1111 .fi |
|
1112 |
|
1113 This flag attribute has the value 'yes' (true, on) if and only if |
|
1114 the size is unbounded, as iptr is. |
|
1115 Both may show an explicit upper bound of 1 in the dwarf, |
|
1116 but this flag notifies the debugger that there is explicitly |
|
1117 no user-provided size. |
|
1118 |
|
1119 So if a user asks for a printout of the rptr allocated |
|
1120 array, the default will be of a single entry (as |
|
1121 there is a user slice bound in the source). |
|
1122 In contrast, there is no explicit upper bound on the iptr |
|
1123 (ita) array so the default slice will use the current bound |
|
1124 (a value calculated from the malloc size, see the dope vector). |
|
1125 |
|
1126 Given explicit requests, more of rptr(axx) can me shown |
|
1127 than the default. |
|
1128 |
|
1129 .H 1 "Line information and Source Position" |
|
1130 DWARF does not define the meaning of the term 'source statement'. |
|
1131 Nor does it define any way to find the first user-written |
|
1132 executable code in a function. |
|
1133 .P |
|
1134 It does define that a source statement has a file name, |
|
1135 a line number, and a column position (see Sec 6.2, Line Number |
|
1136 Information of the Dwarf Version 2 document). |
|
1137 We will call those 3 source coordinates a 'source position' |
|
1138 in this document. We'll try not to accidentally call the |
|
1139 source position a 'line number' since that is ambiguous |
|
1140 as to what it means. |
|
1141 |
|
1142 .H 2 "Definition of Statement" |
|
1143 .P |
|
1144 A function prolog is a statement. |
|
1145 .P |
|
1146 A C, C++, Pascal, or Fortran statement is a statement. |
|
1147 .P |
|
1148 Each initialized local variable in C,C++ is a statement |
|
1149 in that its initialization generates a source position. |
|
1150 This means that |
|
1151 x =3, y=4; |
|
1152 is two statements. |
|
1153 .P |
|
1154 For C, C++: |
|
1155 The 3 parts a,b,c in for(a;b;c) {d;} are individual statements. |
|
1156 The condition portion of a while() and do {} while() is |
|
1157 a statement. (of course d; can be any number of statements) |
|
1158 .P |
|
1159 For Fortran, the controlling expression of a DO loop is a statement. |
|
1160 Is a 'continue' statement in Fortran a DWARF statement? |
|
1161 .P |
|
1162 Each function return, whether user coded or generated by the |
|
1163 compiler, is a statement. This is so one can step over (in |
|
1164 a debugger) the final user-coded statement |
|
1165 (exclusive of the return statement if any) in a function |
|
1166 wile not leaving the function scope. |
|
1167 .P |
|
1168 |
|
1169 .H 2 "Finding The First User Code in a Function" |
|
1170 |
|
1171 .nf |
|
1172 Consider: |
|
1173 int func(int a) |
|
1174 { /* source position 1 */ |
|
1175 float b = a; /* source position 2 */ |
|
1176 int x; |
|
1177 x = b + 2; /* source position 3 */ |
|
1178 } /* source position 4 */ |
|
1179 .fi |
|
1180 .P |
|
1181 The DIE for a function gives the address range of the function, |
|
1182 including function prolog(s) and epilog(s) |
|
1183 .P |
|
1184 Since there is no scope block for the outer user scope of a |
|
1185 function (and thus no beginning address range for the outer |
|
1186 user scope: the DWARF committee explicitly rejected the idea |
|
1187 of having a user scope block) |
|
1188 it is necessary to use the source position information to find |
|
1189 the first user-executable statement. |
|
1190 .P |
|
1191 This means that the user code for a function must be presumed |
|
1192 to begin at the code location of the second source position in |
|
1193 the function address range. |
|
1194 .P |
|
1195 If a function has exactly one source position, the function |
|
1196 presumably consists solely of a return. |
|
1197 .P |
|
1198 If a function has exactly two source positions, the function |
|
1199 may consist of a function prolog and a return or a single user |
|
1200 statement and a return (there may be no prolog code needed in a |
|
1201 leaf function). In this case, there is no way to be sure which |
|
1202 is the first source position of user code, so the rule is to |
|
1203 presume that the first address is user code. |
|
1204 .P |
|
1205 If a function consists of 3 or more source positions, one |
|
1206 should assume that the first source position is function prolog and |
|
1207 the second is the first user executable code. |
|
1208 |
|
1209 .H 2 "Using debug_frame Information to find first user statement" |
|
1210 In addition to the line information, the debug_frame information |
|
1211 can be |
|
1212 useful in determining the first user source line. |
|
1213 .P |
|
1214 Given that a function has more than 1 source position, |
|
1215 Find the code location of the second source position, then |
|
1216 examine the debug_frame information to determine if the Canonical |
|
1217 Frame Address (cfa) is updated before the second source position |
|
1218 code location. |
|
1219 If the cfa is updated, then one can be pretty sure that the |
|
1220 code for the first source position is function prolog code. |
|
1221 .P |
|
1222 Similarly, if the cfa is restored in the code for |
|
1223 a source position, the source position is likely to |
|
1224 represent a function exit block. |
|
1225 |
|
1226 .H 2 "Debugger Use Of Source Position" |
|
1227 Command line debuggers, such as dbx and gdb, will ordinarily |
|
1228 want to consider multiple statements on one line to be a single |
|
1229 statement: doing otherwise is distressing to users since it |
|
1230 causes a 'step' command to appear to have no effect. |
|
1231 .P |
|
1232 An exception for command line debuggers is in determining the |
|
1233 first user statement: as detailed above, there one wants to |
|
1234 consider the full source position and will want to consider |
|
1235 the function return a separate statement. It is difficult to |
|
1236 make the function return a separate statement 'step' reliably |
|
1237 however if a function is coded all on one line or if the last |
|
1238 line of user code before the return is on the same line as the |
|
1239 return. |
|
1240 .P |
|
1241 A graphical debugger has none of these problems if it simply |
|
1242 highlights the portion of the line being executed. In that |
|
1243 case, stepping will appear natural even stepping within a |
|
1244 line. |
|
1245 .H 1 "Known Bugs" |
|
1246 Up through at least MIPSpro7.2.1 |
|
1247 the compiler has been emitting form DW_FORM_DATA1,2, or 4 |
|
1248 for DW_AT_const_value in DW_TAG_enumerator. |
|
1249 And dwarfdump and debuggers have read this with dwarf_formudata() |
|
1250 or form_sdata() and gotten some values incorrect. |
|
1251 For example, a value of 128 was printed by debuggers as a negative value. |
|
1252 Since dwarfdump and the compilers were not written to use the |
|
1253 value the same way, their output differed. |
|
1254 For negative enumerator values the compiler has been emitting 32bit values |
|
1255 in a DW_FORM_DATA4. |
|
1256 The compiler should probably be emitting a DW_FORM_sdata for |
|
1257 enumerator values. |
|
1258 And consumers of enumerator values should then call form_sdata(). |
|
1259 However, right now, debuggers should call form_udata() and only if |
|
1260 it fails, call form_sdata(). |
|
1261 Anything else will break backward compatibility with |
|
1262 the objects produced earlier. |
|
1263 .SK |
|
1264 .S |
|
1265 .TC 1 1 4 |
|
1266 .CS |