|
1 '\"#ident "%W%" |
|
2 '\" $Source: /plroot/cmplrs.src/v7.4.5m/.RCS/PL/libdwarf/RCS/dwarf.v2.mm,v $ |
|
3 '\" |
|
4 '\" $Revision: 1.2 $ |
|
5 '\" |
|
6 '\" DESCRIPTION |
|
7 '\" |
|
8 '\" Requirements for |
|
9 '\" |
|
10 '\" COMPILATION |
|
11 '\" |
|
12 '\" pic file.mm | tbl | troff -mm |
|
13 '\" |
|
14 '\" local mileage may vary |
|
15 '\" |
|
16 '\" AUTHOR |
|
17 '\" |
|
18 '\" UNIX International Programming Languages SIG |
|
19 '\" |
|
20 '\" COPYRIGHT |
|
21 '\" |
|
22 '\" Copyright (c) 1992,1993, UNIX International |
|
23 '\" |
|
24 '\" Permission to use, copy, modify, and distribute this documentation for |
|
25 '\" any purpose and without fee is hereby granted, provided that the above |
|
26 '\" copyright notice appears in all copies and that both that copyright |
|
27 '\" notice and this permission notice appear in supporting documentation, |
|
28 '\" and that the name UNIX International not be used in advertising or |
|
29 '\" publicity pertaining to distribution of the software without specific, |
|
30 '\" written prior permission. UNIX International makes no representations |
|
31 '\" about the suitability of this documentation for any purpose. It is |
|
32 '\" provided "as is" without express or implied warranty. |
|
33 '\" |
|
34 '\" UNIX INTERNATIONAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS |
|
35 '\" DOCUMENTATION, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND |
|
36 '\" FITNESS. IN NO EVENT SHALL UNIX INTERNATIONAL BE LIABLE FOR ANY |
|
37 '\" SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER |
|
38 '\" RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF |
|
39 '\" CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN |
|
40 '\" CONNECTION WITH THE USE OR PERFORMANCE OF THIS DOCUMENTATION. |
|
41 '\" |
|
42 '\" NOTICE: |
|
43 '\" |
|
44 '\" UNIX International is making this documentation available as a |
|
45 '\" reference point for the industry. While UNIX International believes |
|
46 '\" that this specification is well defined in this first release of the |
|
47 '\" document, minor changes may be made prior to products meeting this |
|
48 '\" specification being made available from UNIX System Laboratories or |
|
49 '\" UNIX International members. |
|
50 '\" |
|
51 '\" $Log$ |
|
52 '\" Revision 1.1 1994/05/18 18:50:42 davea |
|
53 '\" Initial revision |
|
54 '\" |
|
55 '\" |
|
56 '\" Abbrevs for funny typeset words |
|
57 .pl-0.25i |
|
58 .ds aX U\s-2NIX\s+2 |
|
59 .ds iX \*(aX International |
|
60 .ds uL \s-2AT&T\ USL\s+2 |
|
61 '\" |
|
62 '\" uI should be set to 1 if the publication and copyright page is needed. |
|
63 .nr uI 1 |
|
64 '\" |
|
65 '\" Make the appropriate replacements in this section! |
|
66 '\" |
|
67 '\" Set the ND date to the current date. |
|
68 '\" tT is the formal document title |
|
69 '\" tP is the name of the Project (if appropriate) |
|
70 '\" tD is the short document title |
|
71 '\" tE is the work group name (may be the same as the project name) |
|
72 .ds tT DWARF Debugging Information Format |
|
73 .ds tP |
|
74 '\" Document name (i.e., without project name) |
|
75 .ds tD DWARF Debugging Information Format |
|
76 .ds tE Programming Languages SIG |
|
77 '\" |
|
78 '\" Define headers and footers macro |
|
79 '\" |
|
80 .ds fA Revision: 2.0.0 |
|
81 '\" |
|
82 '\" fB null to remove page numbers on cover page |
|
83 .ds fB |
|
84 .ds fC July 27, 1993 |
|
85 .ds fE Industry Review Draft |
|
86 .ds fF \*(tD |
|
87 .PH "''''" |
|
88 .PF "''\*(fE''" |
|
89 .tr ~ |
|
90 .SA 1 |
|
91 .S 10 |
|
92 .nr Ej 1 |
|
93 .nr Hs 5 |
|
94 .nr Hu 1 |
|
95 .nr Hb 5 |
|
96 .ds HP +2 +2 +1 +0 +0 +0 +0 |
|
97 .ds HF 3 3 3 3 3 1 1 |
|
98 .if n .ds HF 1 1 1 1 1 1 1 1 |
|
99 '\" |
|
100 '\" First page, print title and authors |
|
101 '\" |
|
102 .S +4 |
|
103 .DS C |
|
104 |
|
105 |
|
106 |
|
107 |
|
108 |
|
109 |
|
110 \fB\*(tT |
|
111 |
|
112 \s-2\*(tP\s+2\fP |
|
113 |
|
114 .DE |
|
115 .S |
|
116 .sp 3i |
|
117 \*(iX |
|
118 .br |
|
119 \*(tE |
|
120 .br |
|
121 \*(fA (\*(fC) |
|
122 .SK |
|
123 .if \n(uI\{ |
|
124 .DS C |
|
125 .in -.25i |
|
126 .B "Published by:" |
|
127 .R |
|
128 |
|
129 \*(iX |
|
130 Waterview Corporate Center |
|
131 20 Waterview Boulevard |
|
132 Parsippany, NJ 07054 |
|
133 |
|
134 for further information, contact: |
|
135 Vice President of Marketing |
|
136 |
|
137 Phone: +1 201-263-8400 |
|
138 Fax: +1 201-263-8401 |
|
139 .DE |
|
140 .P |
|
141 Copyright \(co 1992, 1993 \*(iX, Inc. |
|
142 .P |
|
143 Permission to use, copy, modify, and distribute this |
|
144 documentation for any purpose and without fee is hereby granted, provided |
|
145 that the above copyright notice appears in all copies and that both that |
|
146 copyright notice and this permission notice appear in supporting |
|
147 documentation, and that the name \*(iX not be used in |
|
148 advertising or publicity pertaining to distribution of the software |
|
149 without specific, written prior permission. \*(iX makes |
|
150 no representations about the suitability of this documentation for any |
|
151 purpose. It is provided "as is" without express or implied warranty. |
|
152 .P |
|
153 UNIX INTERNATIONAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION, |
|
154 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO |
|
155 EVENT SHALL UNIX INTERNATIONAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR |
|
156 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF |
|
157 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR |
|
158 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
|
159 PERFORMANCE OF THIS DOCUMENTATION. |
|
160 .sp 2l |
|
161 .if \n(uI\{ |
|
162 NOTICE: |
|
163 .P |
|
164 \*(iX is making this documentation available as a |
|
165 reference point for the industry. |
|
166 While \*(iX believes that this specification is well |
|
167 defined in this first release of the document, |
|
168 minor changes may be made prior to products meeting this specification |
|
169 being made available from \*(aX System Laboratories or \*(iX members. |
|
170 .sp 1l \} |
|
171 Trademarks: |
|
172 .P |
|
173 Intel386 is a trademark of Intel Corporation. |
|
174 .br |
|
175 \*(aX\(rg is a registered trademark of \*(aX System Laboratories |
|
176 in the United States and other countries. |
|
177 .br |
|
178 .OH "'''\s10\\\\*(tE\s0'" |
|
179 .EH "'\s10\\\\*(tD\s0'''" |
|
180 .SK |
|
181 '\".VM 0 2 |
|
182 .PF "''\s10\\\\*(fE\s0''" |
|
183 .OF "'\s10\\\\*(fA'\\\\*(fB'\\\\*(fC\s0'" |
|
184 .EF "'\s10\\\\*(fA'\\\\*(fB'\\\\*(fC\s0'" |
|
185 '\" ----------------------------------------------------------------------- |
|
186 '\". |
|
187 '\" Reset page numbers |
|
188 '\" |
|
189 .nr P 1 |
|
190 .nr % 1 |
|
191 '\" |
|
192 '\" Define headers and footers |
|
193 '\" |
|
194 .FH |
|
195 '\" Turn on the page numbering in the footers |
|
196 .ds fB Page % |
|
197 '\" |
|
198 '\" MACROEND |
|
199 '\" |
|
200 .if n .fp 2 R |
|
201 .if n .fp 3 R |
|
202 .tr ~ |
|
203 \fR |
|
204 .S 11 |
|
205 .SA 1 |
|
206 .tr ~ |
|
207 .OP |
|
208 .ds | | |
|
209 .ds ~ ~ |
|
210 .ds ' ' |
|
211 .if t .ds Cw \&\f(CW |
|
212 .if n .ds Cw \fB |
|
213 .de Cf \" Place every other arg in Cw font, beginning with first |
|
214 .if \\n(.$=1 \&\*(Cw\\$1\fP |
|
215 .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2 |
|
216 .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP |
|
217 .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4 |
|
218 .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP |
|
219 .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6 |
|
220 .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP |
|
221 .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8 |
|
222 .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\*(Cw |
|
223 .. |
|
224 '\" macros used by index generating tool |
|
225 .deIX |
|
226 .ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 \\n% |
|
227 .el \\!.ix \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 |
|
228 .. |
|
229 .deix |
|
230 .ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 \\n% |
|
231 .el \\!.ix \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 |
|
232 .. |
|
233 .ta .5i +.5i +.5i +.5i +.5i +.5i +.5i +.5i |
|
234 .HU "FOREWORD" |
|
235 This document specifies the second generation of symbolic debugging |
|
236 information based on the DWARF format that |
|
237 has been developed by the \*(iX |
|
238 Programming Languages Special Interest Group (SIG). |
|
239 It is being circulated for industry review. |
|
240 The first version of the DWARF specification was published |
|
241 by \*(iX in January, 1992. The current version adds significant |
|
242 new functionality, but its main thrust is to achieve a much |
|
243 denser encoding of the DWARF information. Because of the new |
|
244 encoding, DWARF Version 2 is not binary compatible with |
|
245 DWARF Version 1. |
|
246 .P |
|
247 At this point, the SIG believes that this document sufficiently |
|
248 supports the debugging needs of C, C++, FORTRAN 77, |
|
249 Fortran90, Modula2 and Pascal, and we have |
|
250 released it for public comment. We will accept comments on this |
|
251 document until September 30, 1994. Comments may be directed via email |
|
252 to the SIG mailing list (plsig@ui.org). If you are unable |
|
253 to send email, paper mail, FAX, or machine readable copy |
|
254 on \*(aX, MS-DOS, or Macintosh compatible media can be |
|
255 sent to \*(iX at the address listed below, |
|
256 and will be forwarded to the SIG. |
|
257 .SP |
|
258 .SP |
|
259 .SP |
|
260 .in +20 |
|
261 UNIX International |
|
262 .br |
|
263 Waterview Corporate Center |
|
264 .br |
|
265 20 Waterview Boulevard |
|
266 .br |
|
267 Parsippany, NJ 07054 |
|
268 .br |
|
269 Phone: +1 201-263-8400 |
|
270 .br |
|
271 Fax: +1 201-263-8401 |
|
272 .br |
|
273 .in -20 |
|
274 .nr H1 0 |
|
275 .OP |
|
276 .H 1 "INTRODUCTION" |
|
277 \fR |
|
278 This document defines the format for the information generated by |
|
279 compilers, assemblers and linkage editors that is necessary for symbolic, |
|
280 source-level debugging. The debugging information format does not favor the |
|
281 design of any compiler or debugger. Instead, the goal is to create a method of |
|
282 communicating an accurate picture of the source program to any debugger in a |
|
283 form that is economically extensible to different languages while retaining |
|
284 backward compatibility. |
|
285 .P |
|
286 The design of the debugging information format is open-ended, allowing for the |
|
287 addition of new debugging information to accommodate new languages or |
|
288 debugger capabilities while remaining compatible with other languages or |
|
289 different debuggers. |
|
290 .H 2 "Purpose and Scope" |
|
291 The debugging information format described in this document is designed to |
|
292 meet the symbolic, source-level debugging needs of |
|
293 different languages in a unified fashion by |
|
294 requiring language independent debugging information whenever possible. |
|
295 .IX C++ %caa |
|
296 .IX virtual functions |
|
297 .IX Fortran |
|
298 Individual needs, such as C++ virtual functions or Fortran common blocks are |
|
299 accommodated by creating attributes that are used only for those |
|
300 languages. The \*(iX \*(tE believes |
|
301 that this document sufficiently covers the |
|
302 .IX languages |
|
303 debugging information needs of C, C++, FORTRAN77, Fortran90, |
|
304 Modula2 and Pascal. |
|
305 .IX C %c |
|
306 .IX Modula2 |
|
307 .IX Pascal |
|
308 .IX FORTRAN77 |
|
309 .IX Fortran90 |
|
310 .P |
|
311 This document describes DWARF Version 2, the second generation of debugging |
|
312 .IX Version 2 |
|
313 information based on the DWARF format. While DWARF Version 2 provides |
|
314 new debugging information not available in Version 1, the primary focus |
|
315 of the changes for Version 2 is the representation of the information, |
|
316 rather than the information content itself. The basic structure of |
|
317 the Version 2 format remains as in Version 1: the debugging information |
|
318 is represented as a series of debugging information entries, each containing |
|
319 one or more attributes (name/value pairs). |
|
320 .IX debugging information entries |
|
321 .IX attributes |
|
322 The Version 2 representation, however, |
|
323 is much more compact than the Version 1 representation. |
|
324 .IX Version 1 |
|
325 In some cases, this greater density has been achieved at the expense |
|
326 of additional complexity or greater difficulty in producing and processing |
|
327 the DWARF information. We believe that the reduction in I/O and in |
|
328 memory paging should more than make up for any increase in processing time. |
|
329 .P |
|
330 Because the representation of information has changed from Version 1 to |
|
331 Version 2, Version 2 DWARF information is not binary compatible |
|
332 .IX compatibility |
|
333 with Version 1 information. To make it easier for consumers to |
|
334 support both Version 1 and Version 2 DWARF information, the Version |
|
335 2 information has been moved to a different object file section, |
|
336 .Cf .debug_info . |
|
337 .IX \f(CW.debug_info\fP %debugai |
|
338 .P |
|
339 The intended audience for this document are the developers of |
|
340 both producers and consumers of debugging information, typically |
|
341 language compilers, debuggers and other tools that need to interpret |
|
342 a binary program in terms of its original source. |
|
343 .H 2 "Overview" |
|
344 There are two major pieces to the description of the DWARF format in |
|
345 this document. The first piece is the informational content |
|
346 of the debugging entries. The second piece |
|
347 is the way the debugging information is encoded and |
|
348 represented in an object file. |
|
349 .P |
|
350 The informational content is described in sections two |
|
351 through six. |
|
352 Section two describes the overall structure of |
|
353 the information and attributes that are common to many or all of |
|
354 the different debugging information entries. |
|
355 Sections three, four and five describe the specific debugging |
|
356 information entries and how they communicate the |
|
357 necessary information about the source program to a debugger. |
|
358 Section six describes debugging information contained |
|
359 outside of the debugging information entries, themselves. |
|
360 The encoding of the DWARF information is |
|
361 presented in section seven. |
|
362 .P |
|
363 Section eight describes some future directions for the DWARF |
|
364 specification. |
|
365 .P |
|
366 In the following sections, text in normal font describes required aspects |
|
367 of the DWARF format. Text in \fIitalics\fP is explanatory or supplementary |
|
368 material, and not part of the format definition itself. |
|
369 .H 2 "Vendor Extensibility" |
|
370 .IX vendor extensions |
|
371 This document does not attempt to cover all interesting languages or even |
|
372 to cover all of the interesting debugging information needs for its primary |
|
373 target languages (C, C++, FORTRAN77, Fortran90, Modula2, Pascal). |
|
374 Therefore the document provides |
|
375 vendors a way to define their own debugging information tags, attributes, |
|
376 base type encodings, location operations, language names, |
|
377 calling conventions and call frame instructions |
|
378 by reserving a portion of the name space and valid values |
|
379 for these constructs for vendor specific additions. Future versions |
|
380 of this document will not use names or values reserved for vendor specific |
|
381 additions. All names and values not reserved for vendor additions, however, |
|
382 are reserved for future versions of this document. See section 7 for |
|
383 details. |
|
384 .H 2 "Changes from Version 1" |
|
385 The following is a list of the major changes made to the DWARF Debugging |
|
386 Information Format since Version 1 of the format was published (January |
|
387 .IX Version 1 |
|
388 20, 1992). The list is not meant to be exhaustive. |
|
389 .BL |
|
390 .LI |
|
391 Debugging information entries have been moved from the |
|
392 .Cf .debug |
|
393 .IX \f(CW.debug\fP %debugaaa |
|
394 to the |
|
395 .Cf .debug_info |
|
396 .IX \f(CW.debug_info\fP %debugai |
|
397 section of an object file. |
|
398 .LI |
|
399 .IX tags |
|
400 .IX attributes, names |
|
401 .IX attributes, forms |
|
402 The tag, attribute names and attribute forms encodings have been moved |
|
403 out of the debugging information itself to a separate abbreviations table. |
|
404 .IX abbreviations table |
|
405 .LI |
|
406 Explicit sibling pointers have been made optional. Each |
|
407 .IX debugging information entries, siblings |
|
408 entry now specifies (through the abbreviations table) whether |
|
409 or not it has children. |
|
410 .IX debugging information entries, child entries |
|
411 .LI |
|
412 New more compact attribute forms have been added, including a variable |
|
413 length constant data form. Attribute values may now have any |
|
414 .IX variable length data |
|
415 .IX attributes, forms |
|
416 .IX attributes, values |
|
417 form within a given class of forms. |
|
418 .LI |
|
419 Location descriptions have been replaced by a new, more compact |
|
420 and more expressive format. |
|
421 .IX locations, descriptions |
|
422 There is now a way of expressing multiple locations for an object |
|
423 whose location changes during its lifetime. |
|
424 .IX locations, lists |
|
425 .LI |
|
426 There is a new format for line number information |
|
427 that provides information |
|
428 for code contributed to a compilation unit from an included file. |
|
429 Line number information is now in the |
|
430 .IX line number information |
|
431 .Cf .debug_line |
|
432 .IX \f(CW.debug_line\fP %debugali |
|
433 section of an object file. |
|
434 .LI |
|
435 The representation of the type of a declaration has been |
|
436 reworked. |
|
437 .IX declarations, types of |
|
438 .LI |
|
439 A new section provides an encoding for pre-processor macro information. |
|
440 .IX macro information |
|
441 .IX pre-processor |
|
442 .LI |
|
443 Debugging information entries now provide for the representation |
|
444 of non-defining declarations of objects, functions or types. |
|
445 .IX declarations, non-defining |
|
446 .LI |
|
447 More complete support for Modula2 and Pascal has been added. |
|
448 .LI |
|
449 There is now a way of describing locations for segmented address spaces. |
|
450 .IX segmented address space |
|
451 .IX address space, segmented |
|
452 .LI |
|
453 A new section provides an encoding for information about call |
|
454 frame activations. |
|
455 .IX call frame information |
|
456 .IX activations |
|
457 .LI |
|
458 The representation of enumeration and array types has been |
|
459 .IX enumerations |
|
460 .IX arrays |
|
461 reworked so that DWARF presents only a single way of |
|
462 representing lists of items. |
|
463 .LI |
|
464 Support has been added for C++ templates and exceptions. |
|
465 .IX C++ %caa |
|
466 .IX templates |
|
467 .IX exceptions |
|
468 .LE |
|
469 .OP |
|
470 .H 1 "GENERAL DESCRIPTION" |
|
471 .H 2 "The Debugging Information Entry" |
|
472 DWARF uses a series of debugging information entries to define a |
|
473 .IX debugging information entries |
|
474 low-level representation of a source program. Each debugging |
|
475 information entry is described by an identifying tag and |
|
476 contains a series of attributes. |
|
477 The tag specifies the class to which an entry |
|
478 belongs, and the attributes define the specific characteristics |
|
479 of the entry. |
|
480 .P |
|
481 .nr aX \n(Fg+1 |
|
482 The set of required tag names is listed in Figure \n(aX. |
|
483 .IX tags |
|
484 The debugging information entries they identify are described in sections three, four and five. |
|
485 .P |
|
486 The debugging information entries in DWARF Version 2 are intended |
|
487 to exist in the |
|
488 .Cf .debug_info |
|
489 section of an object file. |
|
490 .IX \f(CW.debug_info\fP %debugai |
|
491 .DF |
|
492 .TS |
|
493 center box; |
|
494 lf(CW) lf(CW) |
|
495 . |
|
496 DW_TAG_access_declaration DW_TAG_array_type |
|
497 DW_TAG_base_type DW_TAG_catch_block |
|
498 DW_TAG_class_type DW_TAG_common_block |
|
499 DW_TAG_common_inclusion DW_TAG_compile_unit |
|
500 DW_TAG_const_type DW_TAG_constant |
|
501 DW_TAG_entry_point DW_TAG_enumeration_type |
|
502 DW_TAG_enumerator DW_TAG_file_type |
|
503 DW_TAG_formal_parameter DW_TAG_friend |
|
504 DW_TAG_imported_declaration DW_TAG_inheritance |
|
505 DW_TAG_inlined_subroutine DW_TAG_label |
|
506 DW_TAG_lexical_block DW_TAG_member |
|
507 DW_TAG_module DW_TAG_namelist |
|
508 DW_TAG_namelist_item DW_TAG_packed_type |
|
509 DW_TAG_pointer_type DW_TAG_ptr_to_member_type |
|
510 DW_TAG_reference_type DW_TAG_set_type |
|
511 DW_TAG_string_type DW_TAG_structure_type |
|
512 DW_TAG_subprogram DW_TAG_subrange_type |
|
513 DW_TAG_subroutine_type DW_TAG_template_type_param |
|
514 DW_TAG_template_value_param DW_TAG_thrown_type |
|
515 DW_TAG_try_block DW_TAG_typedef |
|
516 DW_TAG_union_type DW_TAG_unspecified_parameters |
|
517 DW_TAG_variable DW_TAG_variant |
|
518 DW_TAG_variant_part DW_TAG_volatile_type |
|
519 DW_TAG_with_stmt |
|
520 .TE |
|
521 .FG "Tag names" |
|
522 .DE |
|
523 .H 2 "Attribute Types" |
|
524 Each attribute value is characterized by an attribute name. |
|
525 .IX attributes |
|
526 .IX attributes, names |
|
527 The set of attribute names is |
|
528 .nr aX \n(Fg+1 |
|
529 listed in Figure \n(aX. |
|
530 .DF |
|
531 .TS |
|
532 center box; |
|
533 lf(CW) lf(CW) |
|
534 . |
|
535 DW_AT_abstract_origin DW_AT_accessibility |
|
536 DW_AT_address_class DW_AT_artificial |
|
537 DW_AT_base_types DW_AT_bit_offset |
|
538 DW_AT_bit_size DW_AT_byte_size |
|
539 DW_AT_calling_convention DW_AT_common_reference |
|
540 DW_AT_comp_dir DW_AT_const_value |
|
541 DW_AT_containing_type DW_AT_count |
|
542 DW_AT_data_member_location DW_AT_decl_column |
|
543 DW_AT_decl_file DW_AT_decl_line |
|
544 DW_AT_declaration DW_AT_default_value |
|
545 DW_AT_discr DW_AT_discr_list |
|
546 DW_AT_discr_value DW_AT_encoding |
|
547 DW_AT_external DW_AT_frame_base |
|
548 DW_AT_friend DW_AT_high_pc |
|
549 DW_AT_identifier_case DW_AT_import |
|
550 DW_AT_inline DW_AT_is_optional |
|
551 DW_AT_language DW_AT_location |
|
552 DW_AT_low_pc DW_AT_lower_bound |
|
553 DW_AT_macro_info DW_AT_name |
|
554 DW_AT_namelist_item DW_AT_ordering |
|
555 DW_AT_priority DW_AT_producer |
|
556 DW_AT_prototyped DW_AT_return_addr |
|
557 DW_AT_segment DW_AT_sibling |
|
558 DW_AT_specification DW_AT_start_scope |
|
559 DW_AT_static_link DW_AT_stmt_list |
|
560 DW_AT_stride_size DW_AT_string_length |
|
561 DW_AT_type DW_AT_upper_bound |
|
562 DW_AT_use_location DW_AT_variable_parameter |
|
563 DW_AT_virtuality DW_AT_visibility |
|
564 DW_AT_vtable_elem_location |
|
565 .TE |
|
566 .FG "Attribute names" |
|
567 .DE |
|
568 .P |
|
569 The permissible values for an attribute belong to one or more classes |
|
570 .IX attributes, values |
|
571 .IX attributes, forms |
|
572 of attribute value forms. Each form class may be represented in one or more |
|
573 ways. For instance, some attribute values consist of a single piece |
|
574 of constant data. ``Constant data'' is the class of attribute value |
|
575 that those attributes may have. There are several representations |
|
576 of constant data, however (one, two, four, eight bytes and variable |
|
577 length data). The particular representation for any given instance |
|
578 of an attribute is encoded along with the attribute name as part |
|
579 of the information that guides the interpretation of a debugging |
|
580 information entry. Attribute value forms may belong |
|
581 to one of the following classes. |
|
582 .VL 18 |
|
583 .LI address |
|
584 .IX attributes, addresses |
|
585 Refers to some location in the address space of the described program. |
|
586 .LI block |
|
587 .IX attributes, blocks |
|
588 An arbitrary number of uninterpreted bytes of data. |
|
589 .LI constant |
|
590 .IX attributes, constants |
|
591 One, two, four or eight bytes of uninterpreted data, or data encoded |
|
592 in the variable length format known as LEB128 (see section 7.6). |
|
593 .IX variable length data |
|
594 .IX LEB128 |
|
595 .LI flag |
|
596 .IX attributes, flags |
|
597 A small constant that indicates the presence or absence of an attribute. |
|
598 .LI reference |
|
599 .IX attributes, references |
|
600 Refers to some member of the set of debugging information entries that describe |
|
601 the program. There are two types of reference. The first is an |
|
602 offset relative to the beginning of the compilation unit in |
|
603 which the reference occurs and must refer to an entry within |
|
604 that same compilation unit. The second type of reference |
|
605 is the address of any debugging information entry within |
|
606 the same executable or shared object; it may refer to an entry |
|
607 in a different compilation unit from the unit containing the |
|
608 reference. |
|
609 .LI string |
|
610 .IX attributes, strings |
|
611 A null-terminated sequence of zero or more (non-null) bytes. |
|
612 Data in this form are generally printable strings. Strings |
|
613 may be represented directly in the debugging information entry |
|
614 or as an offset in a separate string table. |
|
615 .LE |
|
616 .P |
|
617 There are no limitations on the ordering of attributes within a debugging |
|
618 .IX attributes, ordering |
|
619 information entry, but to prevent ambiguity, |
|
620 no more than one attribute with a given name may appear in any debugging |
|
621 information entry. |
|
622 .H 2 "Relationship of Debugging Information Entries" |
|
623 .I |
|
624 A variety of needs can be met by permitting a single debugging |
|
625 information entry to ``own'' an arbitrary number of other debugging |
|
626 entries and by permitting the same debugging information entry to be |
|
627 one of many owned by another debugging information entry. |
|
628 This makes it possible to describe, for example, |
|
629 the static block structure within |
|
630 a source file, show the members of a structure, union, or class, and associate |
|
631 declarations with source files or source files with shared objects. |
|
632 .P |
|
633 .R |
|
634 The ownership relation |
|
635 of debugging information entries is achieved naturally |
|
636 .IX debugging information entries |
|
637 because the debugging information is represented as a tree. |
|
638 The nodes of the tree are the debugging information entries |
|
639 themselves. The child entries of any node are exactly those |
|
640 .IX debugging information entries, child entries |
|
641 debugging information entries owned by that node.\*F |
|
642 .FS |
|
643 While the ownership relation of the debugging information |
|
644 entries is represented as a tree, other relations among |
|
645 the entries exist, for example, a pointer from an entry |
|
646 representing a variable to another entry representing |
|
647 the type of that variable. If all such relations are |
|
648 taken into account, the debugging entries form a graph, |
|
649 not a tree. |
|
650 .FE |
|
651 .P |
|
652 The tree itself is represented by flattening it in prefix |
|
653 order. Each debugging information entry |
|
654 is defined either to have child entries or not to have child entries |
|
655 (see section 7.5.3). |
|
656 If an entry is defined not to have children, the next physically |
|
657 succeeding entry is the sibling of the prior entry. If an entry |
|
658 .IX debugging information entries, siblings |
|
659 is defined to have children, the next physically succeeding entry |
|
660 is the first child of the prior entry. Additional children of the parent |
|
661 entry are represented as siblings of the first child. A chain |
|
662 of sibling entries is terminated by a null entry. |
|
663 .IX debugging information entries, null entries |
|
664 .P |
|
665 In cases where a producer of debugging information |
|
666 feels that it will be important for consumers of that information |
|
667 to quickly scan chains of sibling entries, ignoring the children |
|
668 of individual siblings, that producer may attach an |
|
669 .Cf AT_sibling |
|
670 attribute to any debugging information entry. The value of |
|
671 this attribute is a reference to the sibling entry of the |
|
672 entry to which the attribute is attached. |
|
673 .H 2 "Location Descriptions" |
|
674 .I |
|
675 The debugging information must provide consumers a way to find the location |
|
676 of program variables, determine the bounds of dynamic arrays and strings |
|
677 and possibly to find the base address of a subroutine's stack frame or |
|
678 the return address of a subroutine. Furthermore, to meet the needs |
|
679 of recent computer architectures and optimization techniques, the debugging |
|
680 information must be able to describe the location of an object |
|
681 whose location changes over the object's lifetime. |
|
682 .P |
|
683 .R |
|
684 Information about the location of program objects is provided by |
|
685 location descriptions. Location |
|
686 .IX locations, descriptions |
|
687 descriptions can be either of two forms: |
|
688 .AL |
|
689 .LI |
|
690 \fILocation expressions\fP which are a language independent representation of |
|
691 addressing rules |
|
692 .IX locations, expressions |
|
693 of arbitrary complexity built from a few basic |
|
694 building blocks, or \fIoperations\fP. They are sufficient for describing |
|
695 the location of any object as long as its lifetime is either static |
|
696 or the same as the lexical block that owns it, and it does not move throughout |
|
697 its lifetime. |
|
698 .LI |
|
699 \fILocation lists\fP which are used to describe objects that |
|
700 .IX locations, lists |
|
701 have a limited lifetime or change their location throughout their |
|
702 lifetime. Location lists are more completely described below. |
|
703 .LE |
|
704 .P |
|
705 The two forms are distinguished in a context sensitive manner. As the value |
|
706 of an attribute, a location expression is |
|
707 encoded as a block and a location list is encoded as a constant offset into |
|
708 a location list table. |
|
709 .P |
|
710 .I |
|
711 Note: The Version 1 concept of "location descriptions" was replaced in Version 2 |
|
712 with this new abstraction because it is denser and more descriptive. |
|
713 .IX Version 1 |
|
714 .IX Version 2 |
|
715 .R |
|
716 .H 3 "Location Expressions" |
|
717 A location expression consists of zero or more location operations. |
|
718 .IX locations, expressions |
|
719 An expression with zero operations |
|
720 is used to denote an object that is |
|
721 present in the source code but not present in the object code |
|
722 (perhaps because of optimization). |
|
723 .IX optimized code |
|
724 The location operations fall into two categories, register names and |
|
725 addressing operations. Register names always appear alone and indicate |
|
726 that the referred object is contained inside a particular |
|
727 register. Addressing operations are memory address computation |
|
728 rules. All location operations are encoded as a stream of opcodes that |
|
729 are each followed by zero or more literal operands. The number of operands |
|
730 is determined by the opcode. |
|
731 .H 3 "Register Name Operators" |
|
732 .IX locations, register name operators |
|
733 The following operations can be used to name a register. |
|
734 .P |
|
735 .I |
|
736 Note that the |
|
737 register number represents a DWARF specific mapping of numbers onto |
|
738 the actual registers of a given architecture. |
|
739 The mapping should be chosen to gain optimal density and |
|
740 should be shared by all users of a given architecture. |
|
741 The \*(tE recommends |
|
742 that this mapping be defined by the ABI\*F |
|
743 .IX ABI |
|
744 .FS |
|
745 \fISystem V Application Binary Interface\fP, consisting of the generic |
|
746 interface and processor supplements for each target architecture. |
|
747 .FE |
|
748 authoring committee for each |
|
749 architecture. |
|
750 .R |
|
751 .AL |
|
752 .LI |
|
753 .Cf DW_OP_reg0 , " DW_OP_reg1" ", ..., " DW_OP_reg31 |
|
754 .br |
|
755 The |
|
756 \f(CWDW_OP_reg\fP\fIn\fP |
|
757 operations encode the names of up to 32 registers, numbered from |
|
758 0 through 31, inclusive. The object addressed is in register \fIn\fP. |
|
759 .LI |
|
760 .Cf DW_OP_regx |
|
761 .br |
|
762 The |
|
763 .Cf DW_OP_regx |
|
764 operation has a single unsigned LEB128 literal operand that encodes the |
|
765 name of a register. |
|
766 .LE |
|
767 .H 3 "Addressing Operations" |
|
768 .IX locations, stack |
|
769 Each addressing operation represents a postfix operation on a simple stack |
|
770 machine. Each element of the stack is the size of an |
|
771 address on the target machine. |
|
772 The value on the top of the stack after |
|
773 ``executing'' the location expression is taken to be the result (the address |
|
774 of the object, or the value of the array bound, or the length of a |
|
775 dynamic string). In the case of locations used for structure members, |
|
776 .IX members, locations |
|
777 the computation assumes that the base address of the containing structure |
|
778 has been pushed on the stack before evaluation of the addressing operation. |
|
779 .R |
|
780 .H 4 "Literal Encodings" |
|
781 .IX locations, literal encodings |
|
782 The following operations all push a value onto the addressing stack. |
|
783 .AL |
|
784 .LI |
|
785 .Cf DW_OP_lit0 , " DW_OP_lit1" ", ..., " DW_OP_lit31 |
|
786 .br |
|
787 The |
|
788 \f(CWDW_OP_lit\fP\fIn\fP operations encode the unsigned |
|
789 literal values from 0 through 31, inclusive. |
|
790 .LI |
|
791 .Cf DW_OP_addr |
|
792 .br |
|
793 The |
|
794 .Cf DW_OP_addr |
|
795 operation has a single operand that encodes a |
|
796 machine address and whose size is the size of an address on the |
|
797 target machine. |
|
798 .LI |
|
799 .Cf DW_OP_const1u |
|
800 .br |
|
801 The single operand of the |
|
802 .Cf DW_OP_const1u |
|
803 operation provides a 1-byte unsigned integer constant. |
|
804 .LI |
|
805 .Cf DW_OP_const1s |
|
806 .br |
|
807 The single operand of the |
|
808 .Cf DW_OP_const1s |
|
809 operation provides a |
|
810 1-byte signed integer constant. |
|
811 .LI |
|
812 .Cf DW_OP_const2u |
|
813 .br |
|
814 The single operand of the |
|
815 .Cf DW_OP_const2u |
|
816 operation provides a |
|
817 2-byte unsigned integer constant. |
|
818 .LI |
|
819 .Cf DW_OP_const2s |
|
820 .br |
|
821 The single operand of the |
|
822 .Cf DW_OP_const2s |
|
823 operation provides a |
|
824 2-byte signed integer constant. |
|
825 .LI |
|
826 .Cf DW_OP_const4u |
|
827 .br |
|
828 The single operand of the |
|
829 .Cf DW_OP_const4u |
|
830 operation provides a |
|
831 4-byte unsigned integer constant. |
|
832 .LI |
|
833 .Cf DW_OP_const4s |
|
834 .br |
|
835 The single operand of the |
|
836 .Cf DW_OP_const4s |
|
837 operation provides a |
|
838 4-byte signed integer constant. |
|
839 .LI |
|
840 .Cf DW_OP_const8u |
|
841 .br |
|
842 The single operand of the |
|
843 .Cf DW_OP_const8u |
|
844 operation provides an |
|
845 8-byte unsigned integer constant. |
|
846 .LI |
|
847 .Cf DW_OP_const8s |
|
848 .br |
|
849 The single operand of the |
|
850 .Cf DW_OP_const8s |
|
851 operation provides an |
|
852 8-byte signed integer constant. |
|
853 .LI |
|
854 .Cf DW_OP_constu |
|
855 .br |
|
856 The single operand of the |
|
857 .Cf DW_OP_constu |
|
858 operation provides an |
|
859 unsigned LEB128 integer constant. |
|
860 .LI |
|
861 .Cf DW_OP_consts |
|
862 .br |
|
863 The single operand of the |
|
864 .Cf DW_OP_consts |
|
865 operation provides a |
|
866 signed LEB128 integer constant. |
|
867 .LE |
|
868 .H 4 "Register Based Addressing" |
|
869 .IX locations, register based addressing |
|
870 The following operations push a value onto the stack that |
|
871 is the result of adding the contents of a register with |
|
872 a given signed offset. |
|
873 .AL |
|
874 .LI |
|
875 .Cf DW_OP_fbreg |
|
876 .br |
|
877 The |
|
878 \f(CWDW_OP_fbreg\fP |
|
879 operation provides a signed LEB128 offset from the address specified |
|
880 by the location descriptor in the |
|
881 .Cf DW_AT_frame_base |
|
882 attribute of the current |
|
883 .IX subroutines, frame base |
|
884 function. \fI(This is typically a "stack pointer" register |
|
885 plus or minus some |
|
886 offset. On more sophisticated systems it might be a location list that |
|
887 adjusts the offset according to changes in the stack pointer as |
|
888 the PC changes.)\fP |
|
889 .LI |
|
890 .Cf DW_OP_breg0 , " DW_OP_breg1" ", ..., " DW_OP_breg31 |
|
891 .br |
|
892 The single operand of the |
|
893 \f(CWDW_OP_breg\fP\fIn\fP |
|
894 operations provides a signed LEB128 offset from the specified register. |
|
895 .LI |
|
896 .Cf DW_OP_bregx |
|
897 .br |
|
898 The |
|
899 .Cf DW_OP_bregx |
|
900 operation has two operands: a signed LEB128 offset from the specified register |
|
901 which is defined with an unsigned LEB128 number. |
|
902 .LE |
|
903 .H 4 "Stack Operations" |
|
904 .IX locations, stack |
|
905 The following operations |
|
906 manipulate the ``location stack.'' |
|
907 Location operations that index the location stack assume that |
|
908 the top of the stack (most recently added entry) has index 0. |
|
909 .AL |
|
910 .LI |
|
911 .Cf DW_OP_dup |
|
912 .br |
|
913 The |
|
914 .Cf DW_OP_dup |
|
915 operation duplicates the value at the top of the location stack. |
|
916 .LI |
|
917 .Cf DW_OP_drop |
|
918 .br |
|
919 The |
|
920 .Cf DW_OP_drop |
|
921 operation pops the value at the top of the stack. |
|
922 .LI |
|
923 .Cf DW_OP_pick |
|
924 .br |
|
925 The single operand of the |
|
926 .Cf DW_OP_pick |
|
927 operation provides a 1-byte index. The stack entry with the specified index |
|
928 (0 through 255, inclusive) is pushed on the stack. |
|
929 .LI |
|
930 .Cf DW_OP_over |
|
931 .br |
|
932 The |
|
933 .Cf DW_OP_over |
|
934 operation duplicates the entry currently second in the stack |
|
935 at the top of the stack. This is equivalent to an |
|
936 .Cf DW_OP_pick |
|
937 operation, with index 1. |
|
938 .LI |
|
939 .Cf DW_OP_swap |
|
940 .br |
|
941 The |
|
942 .Cf DW_OP_swap |
|
943 operation swaps the top two stack entries. The entry at |
|
944 the top of the stack becomes the second stack entry, and |
|
945 the second entry becomes the top of the stack. |
|
946 .LI |
|
947 .Cf DW_OP_rot |
|
948 .br |
|
949 The |
|
950 .Cf DW_OP_rot |
|
951 operation rotates the first three stack entries. The entry at |
|
952 the top of the stack becomes the third stack entry, the second entry |
|
953 becomes the top of the stack, and the third entry becomes the second |
|
954 entry. |
|
955 .LI |
|
956 .Cf DW_OP_deref |
|
957 .br |
|
958 The |
|
959 .Cf DW_OP_deref |
|
960 operation pops the top stack entry and treats it as an address. |
|
961 The value retrieved from that address is pushed. The size of the |
|
962 data retrieved from the dereferenced address is the size of an address |
|
963 on the target machine. |
|
964 .LI |
|
965 .Cf DW_OP_deref_size |
|
966 .br |
|
967 The |
|
968 .Cf DW_OP_deref_size |
|
969 operation behaves like the |
|
970 .Cf DW_OP_deref |
|
971 operation: it |
|
972 pops the top stack entry and treats it as an address. |
|
973 The value retrieved from that address is pushed. |
|
974 In the |
|
975 .Cf DW_OP_deref_size |
|
976 operation, however, |
|
977 the size in bytes of the |
|
978 data retrieved from the dereferenced address is specified by the |
|
979 single operand. This operand is a 1-byte unsigned integral constant |
|
980 whose value may not be larger than the size of an address on |
|
981 the target machine. The data retrieved is zero extended to the size |
|
982 of an address on the target machine before being pushed on |
|
983 the expression stack. |
|
984 .LI |
|
985 .Cf DW_OP_xderef |
|
986 .br |
|
987 The |
|
988 .Cf DW_OP_xderef |
|
989 .IX address space, multiple |
|
990 operation provides an extended dereference mechanism. The entry at the |
|
991 top of the stack is treated as an address. The second stack entry |
|
992 is treated as an ``address space identifier'' for those architectures |
|
993 that support multiple address spaces. The top two stack elements |
|
994 are popped, a data item is retrieved through an implementation-defined |
|
995 address calculation and pushed as the new stack top. The size of the |
|
996 data retrieved from the dereferenced address is the size of an address |
|
997 on the target machine. |
|
998 .LI |
|
999 .Cf DW_OP_xderef_size |
|
1000 .br |
|
1001 The |
|
1002 .Cf DW_OP_xderef_size |
|
1003 operation behaves like the |
|
1004 .Cf DW_OP_xderef |
|
1005 operation: the entry at the |
|
1006 top of the stack is treated as an address. The second stack entry |
|
1007 is treated as an ``address space identifier'' for those architectures |
|
1008 that support multiple address spaces. The top two stack elements |
|
1009 are popped, a data item is retrieved through an implementation-defined |
|
1010 address calculation and pushed as the new stack top. |
|
1011 In the |
|
1012 .Cf DW_OP_xderef_size |
|
1013 operation, however, |
|
1014 the size in bytes of the |
|
1015 data retrieved from the dereferenced address is specified by the |
|
1016 single operand. This operand is a 1-byte unsigned integral constant |
|
1017 whose value may not be larger than the size of an address on |
|
1018 the target machine. The data retrieved is zero extended to the size |
|
1019 of an address on the target machine before being pushed on |
|
1020 the expression stack. |
|
1021 .LE |
|
1022 .H 4 "Arithmetic and Logical Operations" |
|
1023 .IX locations, arithmetic operations |
|
1024 .IX locations, logical operations |
|
1025 The following provide arithmetic and logical operations. |
|
1026 The arithmetic operations perform ``addressing arithmetic,'' |
|
1027 that is, unsigned arithmetic that wraps on an address-sized |
|
1028 boundary. The operations do not cause an exception on overflow. |
|
1029 .AL |
|
1030 .LI |
|
1031 .Cf DW_OP_abs |
|
1032 .br |
|
1033 The |
|
1034 .Cf DW_OP_abs |
|
1035 operation pops the top stack entry and pushes its absolute value. |
|
1036 .LI |
|
1037 .Cf DW_OP_and |
|
1038 .br |
|
1039 The |
|
1040 .Cf DW_OP_and |
|
1041 operation pops the top two stack values, performs a bitwise \fIand\fP |
|
1042 operation on the two, and pushes the result. |
|
1043 .LI |
|
1044 .Cf DW_OP_div |
|
1045 .br |
|
1046 The |
|
1047 .Cf DW_OP_div |
|
1048 operation pops the top two stack values, divides the former second entry |
|
1049 by the former top of the stack |
|
1050 using signed division, |
|
1051 and pushes the result. |
|
1052 .LI |
|
1053 .Cf DW_OP_minus |
|
1054 .br |
|
1055 The |
|
1056 .Cf DW_OP_minus |
|
1057 operation pops the top two stack values, subtracts the former top of the stack |
|
1058 from the former second entry, and pushes the result. |
|
1059 .LI |
|
1060 .Cf DW_OP_mod |
|
1061 .br |
|
1062 The |
|
1063 .Cf DW_OP_mod |
|
1064 operation pops the top two stack values and pushes the result of the |
|
1065 calculation: former second stack entry modulo the former top of the |
|
1066 stack. |
|
1067 .LI |
|
1068 .Cf DW_OP_mul |
|
1069 .br |
|
1070 The |
|
1071 .Cf DW_OP_mul |
|
1072 operation pops the top two stack entries, multiplies them together, |
|
1073 and pushes the result. |
|
1074 .LI |
|
1075 .Cf DW_OP_neg |
|
1076 .br |
|
1077 The |
|
1078 .Cf DW_OP_neg |
|
1079 operation pops the top stack entry, and pushes its negation. |
|
1080 .LI |
|
1081 .Cf DW_OP_not |
|
1082 .br |
|
1083 The |
|
1084 .Cf DW_OP_not |
|
1085 operation pops the top stack entry, and pushes its bitwise complement. |
|
1086 .LI |
|
1087 .Cf DW_OP_or |
|
1088 .br |
|
1089 The |
|
1090 .Cf DW_OP_or |
|
1091 operation pops the top two stack entries, performs a bitwise \fIor\fP |
|
1092 operation on the two, and pushes the result. |
|
1093 .LI |
|
1094 .Cf DW_OP_plus |
|
1095 .br |
|
1096 The |
|
1097 .Cf DW_OP_plus |
|
1098 operation pops the top two stack entries, adds them together, |
|
1099 and pushes the result. |
|
1100 .LI |
|
1101 .Cf DW_OP_plus_uconst |
|
1102 .br |
|
1103 The |
|
1104 .Cf DW_OP_plus_uconst |
|
1105 operation pops the top stack entry, adds it to the unsigned LEB128 |
|
1106 constant operand and pushes the result. |
|
1107 .I |
|
1108 This operation is supplied specifically to be able to encode more field |
|
1109 offsets in two bytes than can be done with "\f(CWDW_OP_lit\fP\fIn\fP\f(CW DW_OP_add\fP". |
|
1110 .R |
|
1111 .LI |
|
1112 .Cf DW_OP_shl |
|
1113 .br |
|
1114 The |
|
1115 .Cf DW_OP_shl |
|
1116 operation pops the top two stack entries, shifts the former second |
|
1117 entry left by the number of bits specified by the former top of |
|
1118 the stack, and pushes the result. |
|
1119 .LI |
|
1120 .Cf DW_OP_shr |
|
1121 .br |
|
1122 The |
|
1123 .Cf DW_OP_shr |
|
1124 operation pops the top two stack entries, shifts the former second |
|
1125 entry right (logically) by the number of bits specified by the former top of |
|
1126 the stack, and pushes the result. |
|
1127 .LI |
|
1128 .Cf DW_OP_shra |
|
1129 .br |
|
1130 The |
|
1131 .Cf DW_OP_shra |
|
1132 operation pops the top two stack entries, shifts the former second |
|
1133 entry right (arithmetically) by the number of bits specified by the former top of |
|
1134 the stack, and pushes the result. |
|
1135 .LI |
|
1136 .Cf DW_OP_xor |
|
1137 .br |
|
1138 The |
|
1139 .Cf DW_OP_xor |
|
1140 operation pops the top two stack entries, performs the logical |
|
1141 \fIexclusive-or\fP operation on the two, and pushes the result. |
|
1142 .LE |
|
1143 .H 4 "Control Flow Operations" |
|
1144 .IX locations, control flow operations |
|
1145 The following operations provide simple control of the flow of a location |
|
1146 expression. |
|
1147 .AL |
|
1148 .LI |
|
1149 Relational operators |
|
1150 .br |
|
1151 The six relational operators each pops the top two stack values, |
|
1152 compares the former top of the stack with the former second entry, |
|
1153 and pushes the constant value 1 onto the stack if the result of the |
|
1154 operation is true or the constant value 0 if the result of the operation |
|
1155 is false. The comparisons are done as signed operations. The six |
|
1156 operators are |
|
1157 .Cf DW_OP_le |
|
1158 (less than or equal to), |
|
1159 .Cf DW_OP_ge |
|
1160 (greater than or equal to), |
|
1161 .Cf DW_OP_eq |
|
1162 (equal to), |
|
1163 .Cf DW_OP_lt |
|
1164 (less than), |
|
1165 .Cf DW_OP_gt |
|
1166 (greater than) and |
|
1167 .Cf DW_OP_ne |
|
1168 (not equal to). |
|
1169 .LI |
|
1170 .Cf DW_OP_skip |
|
1171 .br |
|
1172 .Cf DW_OP_skip |
|
1173 is an unconditional branch. Its |
|
1174 single operand is a 2-byte signed integer constant. |
|
1175 The 2-byte constant is the number of bytes of the location |
|
1176 expression to skip from the current operation, beginning after the |
|
1177 2-byte constant. |
|
1178 .LI |
|
1179 .Cf DW_OP_bra |
|
1180 .br |
|
1181 .Cf DW_OP_bra |
|
1182 is a conditional branch. Its |
|
1183 single operand is a 2-byte signed integer constant. |
|
1184 This operation pops the top of stack. If the value |
|
1185 popped is not the constant 0, the 2-byte constant operand is the number |
|
1186 of bytes of the location |
|
1187 expression to skip from the current operation, beginning after the |
|
1188 2-byte constant. |
|
1189 .LE |
|
1190 .H 4 "Special Operations" |
|
1191 .IX locations, special operations |
|
1192 There are two special operations currently defined: |
|
1193 .AL |
|
1194 .LI |
|
1195 .Cf DW_OP_piece |
|
1196 .br |
|
1197 .I |
|
1198 Many compilers store a single variable in sets of registers, or store |
|
1199 a variable partially in memory and partially in registers. |
|
1200 .Cf DW_OP_piece |
|
1201 provides a way of describing how large a part of a variable |
|
1202 a particular addressing expression refers to. |
|
1203 .R |
|
1204 .P |
|
1205 .Cf DW_OP_piece |
|
1206 takes a single argument which is an unsigned LEB128 number. The number |
|
1207 describes the size in bytes of the piece of the object referenced |
|
1208 by the addressing expression whose result is at the top of |
|
1209 the stack. |
|
1210 .LI |
|
1211 .Cf DW_OP_nop |
|
1212 .br |
|
1213 The |
|
1214 .Cf DW_OP_nop |
|
1215 operation is a place holder. It has no effect on the location stack or |
|
1216 any of its values. |
|
1217 .LE |
|
1218 .H 3 "Sample Stack Operations" |
|
1219 .IX locations, examples |
|
1220 .I |
|
1221 The stack operations defined in section 2.4.3.3 are fairly |
|
1222 .IX locations, stack |
|
1223 conventional, but the following examples illustrate their behavior |
|
1224 graphically. |
|
1225 .R |
|
1226 .DS |
|
1227 .TS |
|
1228 box expand center tab(;); |
|
1229 l s l l s |
|
1230 lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) |
|
1231 . |
|
1232 Before;Operation;After; |
|
1233 _ |
|
1234 0;17;DW_OP_dup;0;17 |
|
1235 1;29;;1;17 |
|
1236 2;1000;;2;29 |
|
1237 ;;;3;1000 |
|
1238 _ |
|
1239 0;17;DW_OP_drop;0;29 |
|
1240 1;29;;1;1000 |
|
1241 2;1000;;;; |
|
1242 _ |
|
1243 0;17;DW_OP_pick 2;0;1000 |
|
1244 1;29;;1;17 |
|
1245 2;1000;;2;29 |
|
1246 ;;;3;1000 |
|
1247 _ |
|
1248 0;17;DW_OP_over;0;29 |
|
1249 1;29;;1;17 |
|
1250 2;1000;;2;29 |
|
1251 ;;;3;1000 |
|
1252 _ |
|
1253 0;17;DW_OP_swap;0;29 |
|
1254 1;29;;1;17 |
|
1255 2;1000;;2;1000 |
|
1256 _ |
|
1257 0;17;DW_OP_rot;0;29 |
|
1258 1;29;;1;1000 |
|
1259 2;1000;;2;17 |
|
1260 .TE |
|
1261 .DE |
|
1262 .H 3 "Example Location Expressions" |
|
1263 .I |
|
1264 .IX locations, examples |
|
1265 The addressing expression represented by a location expression, |
|
1266 if evaluated, generates the |
|
1267 runtime address of the value of a symbol except where the |
|
1268 .Cf DW_OP_reg n, |
|
1269 or |
|
1270 .Cf DW_OP_regx |
|
1271 operations are used. |
|
1272 .P |
|
1273 Here are some examples of how location operations are used to form location |
|
1274 expressions: |
|
1275 .R |
|
1276 .DS |
|
1277 \f(CWDW_OP_reg3\fI |
|
1278 The value is in register 3. |
|
1279 |
|
1280 \f(CWDW_OP_regx 54\fI |
|
1281 The value is in register 54. |
|
1282 |
|
1283 \f(CWDW_OP_addr 0x80d0045c\fI |
|
1284 The value of a static variable is |
|
1285 at machine address 0x80d0045c. |
|
1286 |
|
1287 \f(CWDW_OP_breg11 44\fI |
|
1288 Add 44 to the value in |
|
1289 register 11 to get the address of an |
|
1290 automatic variable instance. |
|
1291 |
|
1292 \f(CWDW_OP_fbreg -50\fI |
|
1293 Given an \f(CWDW_AT_frame_base\fI value of |
|
1294 "\f(CWOPBREG31 64\fI," this example |
|
1295 computes the address of a local variable |
|
1296 that is -50 bytes from a logical frame |
|
1297 pointer that is computed by adding |
|
1298 64 to the current stack pointer (register 31). |
|
1299 |
|
1300 \f(CWDW_OP_bregx 54 32 DW_OP_deref\fI |
|
1301 A call-by-reference parameter |
|
1302 whose address is in the |
|
1303 word 32 bytes from where register |
|
1304 54 points. |
|
1305 |
|
1306 \f(CWDW_OP_plus_uconst 4\fI |
|
1307 A structure member is four bytes |
|
1308 from the start of the structure |
|
1309 instance. The base address is |
|
1310 assumed to be already on the stack. |
|
1311 |
|
1312 \f(CWDW_OP_reg3 DW_OP_piece 4 DW_OP_reg10 DW_OP_piece 2\fI |
|
1313 A variable whose first four bytes reside |
|
1314 in register 3 and whose next two bytes |
|
1315 reside in register 10.\fR |
|
1316 .DE |
|
1317 .H 3 "Location Lists" |
|
1318 .IX locations, lists |
|
1319 Location lists are used in place of location expressions whenever |
|
1320 the object whose location is being described can change location |
|
1321 during its lifetime. Location lists are contained in a separate |
|
1322 object file section called |
|
1323 .Cf .debug_loc. |
|
1324 .IX \f(CW.debug_loc\fP %debugalo |
|
1325 A location list is indicated by a location |
|
1326 attribute whose value is represented as a |
|
1327 constant offset from the beginning of the |
|
1328 .Cf .debug_loc |
|
1329 section to the first byte of the list for the object in question. |
|
1330 .P |
|
1331 Each entry in a location list consists of: |
|
1332 .AL |
|
1333 .LI |
|
1334 A beginning address. This address is relative to the base address |
|
1335 of the compilation unit referencing this location list. It marks |
|
1336 the beginning of the address range over which the location is valid. |
|
1337 .LI |
|
1338 An ending address, again relative to the base address |
|
1339 of the compilation unit referencing this location list. It marks |
|
1340 the first address past the end of the address range over |
|
1341 which the location is valid. |
|
1342 .LI |
|
1343 A location expression describing the location of the object over the |
|
1344 range specified by the beginning and end addresses. |
|
1345 .LE |
|
1346 .P |
|
1347 Address ranges may overlap. When they do, they describe a situation |
|
1348 in which an object exists simultaneously in more than one place. |
|
1349 If all of the address ranges |
|
1350 in a given location list do not collectively cover the entire |
|
1351 range over which the object in question is defined, it is assumed |
|
1352 that the object is not available for the portion of the range that is not |
|
1353 covered. |
|
1354 .IX optimized code |
|
1355 .P |
|
1356 The end of any given location list is marked by a 0 for the beginning |
|
1357 address and a 0 for the end address; no location description is present. |
|
1358 A location list containing |
|
1359 only such a 0 entry describes an object that exists in the source |
|
1360 code but not in the executable program. |
|
1361 .H 2 "Types of Declarations" |
|
1362 .IX declarations, types of |
|
1363 Any debugging information entry describing a declaration that |
|
1364 has a type has a |
|
1365 .Cf DW_AT_type |
|
1366 attribute, whose value is a reference to another debugging |
|
1367 information entry. The entry referenced may describe |
|
1368 .IX base types |
|
1369 .IX types, base |
|
1370 a base type, that is, a type that is not defined in terms |
|
1371 .IX user-defined types |
|
1372 .IX types, user-defined |
|
1373 of other data types, or it may describe a user-defined type, |
|
1374 such as an array, structure or enumeration. Alternatively, |
|
1375 the entry referenced may describe a type modifier: constant, |
|
1376 packed, pointer, reference or volatile, which in turn will reference |
|
1377 another entry describing a type or type modifier (using a |
|
1378 .IX type modifiers |
|
1379 .IX types, modifiers |
|
1380 .IX types, packed |
|
1381 .IX types, constant |
|
1382 .IX types, pointer |
|
1383 .IX types, reference |
|
1384 .IX types, volatile |
|
1385 .Cf DW_AT_type |
|
1386 attribute of its own). See section 5 for descriptions of |
|
1387 the entries describing base types, user-defined types and |
|
1388 type modifiers. |
|
1389 .H 2 "Accessibility of Declarations" |
|
1390 .I |
|
1391 .IX accessibility |
|
1392 .IX declarations, accessibility |
|
1393 Some languages, notably C++ and Ada, have the concept of |
|
1394 .IX C++ %caa |
|
1395 the accessibility of an object or of some other program entity. |
|
1396 The accessibility specifies which classes of other program objects |
|
1397 are permitted access to the object in question. |
|
1398 .R |
|
1399 .P |
|
1400 The accessibility of a declaration is represented by a |
|
1401 .Cf DW_AT_accessibility |
|
1402 attribute, whose value is a constant drawn from the set of codes |
|
1403 .nr aX \n(Fg+1 |
|
1404 listed in Figure \n(aX. |
|
1405 .DF |
|
1406 .TS |
|
1407 box center; |
|
1408 lf(CW) |
|
1409 . |
|
1410 DW_ACCESS_public |
|
1411 DW_ACCESS_private |
|
1412 DW_ACCESS_protected |
|
1413 .TE |
|
1414 .FG "Accessibility codes" |
|
1415 .DE |
|
1416 .H 2 "Visibility of Declarations" |
|
1417 .I |
|
1418 .IX Modula2 |
|
1419 .IX visibility |
|
1420 .IX declarations, visibility |
|
1421 Modula2 has the concept of the visibility of a declaration. |
|
1422 The visibility specifies which declarations are to be visible outside |
|
1423 of the module in which they are declared. |
|
1424 .R |
|
1425 .P |
|
1426 The visibility of a declaration is represented by a |
|
1427 .Cf DW_AT_visibility |
|
1428 attribute, whose value is a constant drawn from the set of codes |
|
1429 .nr aX \n(Fg+1 |
|
1430 listed in Figure \n(aX. |
|
1431 .DF |
|
1432 .TS |
|
1433 box center; |
|
1434 lf(CW) |
|
1435 . |
|
1436 DW_VIS_local |
|
1437 DW_VIS_exported |
|
1438 DW_VIS_qualified |
|
1439 .TE |
|
1440 .FG "Visibility codes" |
|
1441 .DE |
|
1442 .H 2 "Virtuality of Declarations" |
|
1443 .I |
|
1444 .IX C++ %caa |
|
1445 .IX virtuality |
|
1446 .IX virtual functions |
|
1447 C++ provides for virtual and pure virtual structure or class |
|
1448 member functions and for virtual base classes. |
|
1449 .P |
|
1450 .R |
|
1451 The virtuality of a declaration is represented by a |
|
1452 .Cf DW_AT_virtuality |
|
1453 attribute, whose value is a constant drawn from the set of codes |
|
1454 .nr aX \n(Fg+1 |
|
1455 listed in Figure \n(aX. |
|
1456 .DF |
|
1457 .TS |
|
1458 box center; |
|
1459 lf(CW) |
|
1460 . |
|
1461 DW_VIRTUALITY_none |
|
1462 DW_VIRTUALITY_virtual |
|
1463 DW_VIRTUALITY_pure_virtual |
|
1464 .TE |
|
1465 .FG "Virtuality codes" |
|
1466 .DE |
|
1467 .H 2 "Artificial Entries" |
|
1468 .I |
|
1469 .IX artificial entries |
|
1470 A compiler may wish to generate debugging information entries |
|
1471 for objects or types that were not actually declared |
|
1472 in the source of the application. An example is a formal parameter |
|
1473 entry to represent the hidden |
|
1474 .Cf this |
|
1475 parameter that most C++ implementations pass as the first argument |
|
1476 to non-static member functions. |
|
1477 .R |
|
1478 .P |
|
1479 Any debugging information entry representing the declaration of an |
|
1480 object or type artificially generated by a compiler and |
|
1481 not explicitly declared by the source program may have a |
|
1482 .Cf DW_AT_artificial |
|
1483 attribute. The value of this attribute is a flag. |
|
1484 .H 2 "Target-Specific Addressing Information" |
|
1485 .I |
|
1486 .IX segmented address space |
|
1487 .IX address space, segmented |
|
1488 In some systems, addresses are specified as offsets within a given |
|
1489 segment rather than as locations within a single flat address space. |
|
1490 .R |
|
1491 .P |
|
1492 Any debugging information entry that contains a description of the |
|
1493 location of an object or subroutine may have a |
|
1494 .Cf DW_AT_segment |
|
1495 attribute, whose value is a location description. The description |
|
1496 evaluates to the segment value of the item being described. If |
|
1497 the entry containing the |
|
1498 .Cf DW_AT_segment |
|
1499 attribute has a |
|
1500 .Cf DW_AT_low_pc |
|
1501 or |
|
1502 .Cf DW_AT_high_pc |
|
1503 attribute, or a location description that evaluates to an address, |
|
1504 .IX locations, descriptions |
|
1505 .IX addresses, offset portion |
|
1506 then those values represent the offset portion of the address |
|
1507 within the segment specified by |
|
1508 .Cf DW_AT_segment . |
|
1509 .P |
|
1510 If an entry has no |
|
1511 .Cf DW_AT_segment |
|
1512 attribute, it inherits the segment value from its parent entry. |
|
1513 If none of the entries in the chain of parents for this entry |
|
1514 back to its containing compilation unit entry have |
|
1515 .Cf DW_AT_segment |
|
1516 attributes, then the entry is assumed to exist within a flat |
|
1517 address space. Similarly, if the entry has a |
|
1518 .IX flat address space |
|
1519 .IX address space, flat |
|
1520 .Cf DW_AT_segment |
|
1521 attribute containing an empty location description, that entry |
|
1522 is assumed to exist within a flat address space. |
|
1523 .P |
|
1524 .I |
|
1525 Some systems support different classes of addresses. The address |
|
1526 class may affect the way a pointer is dereferenced or the way |
|
1527 a subroutine is called. |
|
1528 .P |
|
1529 .R |
|
1530 Any debugging information entry representing a pointer or reference |
|
1531 type or a subroutine or subroutine type may have a |
|
1532 .IX types, pointer |
|
1533 .IX types, reference |
|
1534 .IX subroutines |
|
1535 .IX subroutines, types |
|
1536 .Cf DW_AT_address_class |
|
1537 .IX addresses, class |
|
1538 attribute, whose value is a constant. The set of permissible |
|
1539 values is specific to each target architecture. The value |
|
1540 .Cf DW_ADDR_none , |
|
1541 however, is common to all encodings, and means that no address class |
|
1542 has been specified. |
|
1543 .P |
|
1544 .I |
|
1545 For example, the Intel386\(tm processor might use the following |
|
1546 values: |
|
1547 .R |
|
1548 .DF |
|
1549 .TS |
|
1550 box center; |
|
1551 l l l |
|
1552 lf(CW) lf(CW) l |
|
1553 . |
|
1554 Name Value Meaning |
|
1555 _ |
|
1556 DW_ADDR_none 0 no class specified |
|
1557 DW_ADDR_near16 1 16-bit offset, no segment |
|
1558 DW_ADDR_far16 2 16-bit offset, 16-bit segment |
|
1559 DW_ADDR_huge16 3 16-bit offset, 16-bit segment |
|
1560 DW_ADDR_near32 4 32-bit offset, no segment |
|
1561 DW_ADDR_far32 5 32-bit offset, 16-bit segment |
|
1562 .TE |
|
1563 .FG "Example address class codes" |
|
1564 .DE |
|
1565 .H 2 "Non-Defining Declarations" |
|
1566 .IX declarations, non-defining |
|
1567 .IX declarations, defining |
|
1568 A debugging information entry representing a program object or type |
|
1569 typically represents the defining declaration of that object or type. In |
|
1570 certain contexts, however, a debugger might need information about a |
|
1571 declaration of a subroutine, object or type that is not also a |
|
1572 definition to evaluate an expression correctly. |
|
1573 .P |
|
1574 .I |
|
1575 As an example, consider the following fragment of C code: |
|
1576 .DS |
|
1577 \f(CWvoid myfunc() |
|
1578 { |
|
1579 int x; |
|
1580 { |
|
1581 extern float x; |
|
1582 g(x); |
|
1583 } |
|
1584 }\fP |
|
1585 .DE |
|
1586 .P |
|
1587 ANSI-C scoping rules require that the value of the variable \f(CWx\fP |
|
1588 passed to the function \f(CWg\fP is the value of the global variable |
|
1589 \f(CWx\fP rather than of the local version. |
|
1590 .R |
|
1591 .P |
|
1592 Debugging information entries that represent non-defining declarations |
|
1593 of a program object or type have a |
|
1594 .Cf DW_AT_declaration |
|
1595 attribute, whose value is a flag. |
|
1596 .H 2 "Declaration Coordinates" |
|
1597 .I |
|
1598 It is sometimes useful in a debugger to be able to associate a declaration |
|
1599 with its occurrence in the program source. |
|
1600 .P |
|
1601 .R |
|
1602 .IX declarations, coordinates |
|
1603 Any debugging information entry representing the declaration of |
|
1604 an object, module, subprogram or type may have |
|
1605 .Cf DW_AT_decl_file , |
|
1606 .Cf DW_AT_decl_line |
|
1607 and |
|
1608 .Cf DW_AT_decl_column |
|
1609 attributes, each of whose value is a constant. |
|
1610 .P |
|
1611 The value of the |
|
1612 .Cf DW_AT_decl_file |
|
1613 attribute corresponds |
|
1614 to a file number from the statement information table for the compilation |
|
1615 .IX line number information |
|
1616 unit containing this debugging information entry and represents the |
|
1617 source file in which the declaration appeared (see section 6.2). |
|
1618 .IX source, files |
|
1619 The value 0 indicates that no source file has been specified. |
|
1620 .P |
|
1621 The value of the |
|
1622 .Cf DW_AT_decl_line |
|
1623 attribute represents the source line number at which the first |
|
1624 .IX source, lines |
|
1625 character of the identifier of the declared object appears. |
|
1626 The value 0 indicates that no source line has been specified. |
|
1627 .P |
|
1628 The value of the |
|
1629 .Cf DW_AT_decl_column |
|
1630 attribute represents the source column number at which the first |
|
1631 .IX source, columns |
|
1632 character of the identifier of the declared object appears. |
|
1633 The value 0 indicates that no column has been specified. |
|
1634 .H 2 "Identifier Names" |
|
1635 .IX identifiers, names |
|
1636 Any debugging information entry representing a program entity that |
|
1637 has been given a name may have a |
|
1638 .Cf DW_AT_name |
|
1639 attribute, whose value is a string representing the name as it appears |
|
1640 in the source program. A debugging information entry containing |
|
1641 no name attribute, or containing a name attribute whose value consists |
|
1642 of a name containing a single null byte, |
|
1643 represents a program entity for which no name was given in the source. |
|
1644 .I |
|
1645 .P |
|
1646 Note that since the names of program objects |
|
1647 described by DWARF are the names as they appear in the source program, |
|
1648 implementations of language translators that use some form of mangled |
|
1649 name (as do many implementations of C++) should use the unmangled |
|
1650 .IX C++ %caa |
|
1651 form of the name in the DWARF |
|
1652 .Cf DW_AT_name |
|
1653 attribute, including the keyword |
|
1654 .Cf operator , |
|
1655 if present. Sequences of multiple whitespace characters may be compressed. |
|
1656 .R |
|
1657 .OP |
|
1658 .H 1 "PROGRAM SCOPE ENTRIES" |
|
1659 This section describes debugging information entries that relate |
|
1660 to different levels of program scope: compilation unit, module, |
|
1661 subprogram, and so on. These entries may be thought of as |
|
1662 bounded by ranges of text addresses within the program. |
|
1663 .H 2 "Compilation Unit Entries" |
|
1664 An object file may be derived from one or more compilation units. Each |
|
1665 such compilation unit will be described by a debugging information |
|
1666 entry with the tag \f(CWDW_TAG_compile_unit\fP. |
|
1667 .I |
|
1668 .P |
|
1669 A compilation unit typically represents the text and data contributed |
|
1670 .IX compilation units |
|
1671 to an executable by a single relocatable object file. It may |
|
1672 be derived from several source files, including pre-processed ``include |
|
1673 files.'' |
|
1674 .R |
|
1675 .P |
|
1676 The compilation unit entry may have the following attributes: |
|
1677 .AL |
|
1678 .LI |
|
1679 A |
|
1680 .Cf DW_AT_low_pc |
|
1681 attribute whose value is the |
|
1682 relocated address of the first machine instruction generated for that |
|
1683 compilation unit. |
|
1684 .LI |
|
1685 A |
|
1686 .Cf DW_AT_high_pc |
|
1687 attribute whose value is the |
|
1688 relocated address of the first location |
|
1689 past the last machine instruction generated for that compilation unit. |
|
1690 .P |
|
1691 .I |
|
1692 The address may be beyond the last valid instruction in the executable, |
|
1693 of course, for this and other similar attributes. |
|
1694 .R |
|
1695 .P |
|
1696 The presence of low and high pc attributes in a compilation unit entry |
|
1697 imply that the code generated for that compilation unit is |
|
1698 contiguous and exists totally within the boundaries specified |
|
1699 by those two attributes. If that is not the case, no low |
|
1700 and high pc attributes should be produced. |
|
1701 .IX address space, contiguous |
|
1702 .LI |
|
1703 A |
|
1704 .Cf DW_AT_name |
|
1705 attribute whose value is a |
|
1706 null-terminated string containing the full or relative path name of |
|
1707 the primary source file from which the compilation unit was derived. |
|
1708 .IX source, files |
|
1709 .LI |
|
1710 A |
|
1711 .Cf DW_AT_language |
|
1712 attribute whose constant value is |
|
1713 .IX languages |
|
1714 a code indicating the source language of the compilation unit. |
|
1715 .nr aX \n(Fg+1 |
|
1716 The set of language names and their meanings are |
|
1717 given in Figure \n(aX. |
|
1718 .DF |
|
1719 .TS |
|
1720 box center; |
|
1721 lf(CW) lf(R) |
|
1722 . |
|
1723 DW_LANG_C Non-ANSI C, such as K&R |
|
1724 DW_LANG_C89 ISO/ANSI C |
|
1725 DW_LANG_C_plus_plus C++ |
|
1726 DW_LANG_Fortran77 FORTRAN77 |
|
1727 DW_LANG_Fortran90 Fortran90 |
|
1728 DW_LANG_Modula2 Modula2 |
|
1729 DW_LANG_Pascal83 ISO/ANSI Pascal |
|
1730 .TE |
|
1731 .FG "Language names" |
|
1732 .DE |
|
1733 .LI |
|
1734 A |
|
1735 .Cf DW_AT_stmt_list |
|
1736 attribute whose value is a reference to |
|
1737 line number information for this compilation unit. |
|
1738 .IX line number information |
|
1739 .P |
|
1740 This information is placed in a separate object file section from the debugging |
|
1741 information entries themselves. The value of the statement list attribute |
|
1742 is the offset in the \f(CW.debug_line\fP section of the first byte of the |
|
1743 line number information for this compilation unit. See section 6.2. |
|
1744 .LI |
|
1745 A |
|
1746 .Cf DW_AT_macro_info |
|
1747 attribute whose value is a reference to the macro information for this |
|
1748 compilation unit. |
|
1749 .IX macro information |
|
1750 .P |
|
1751 This information is placed in a separate object file section from the debugging |
|
1752 information entries themselves. The value of the macro information attribute |
|
1753 is the offset in the \f(CW.debug_macinfo\fP section of the first byte of the |
|
1754 macro information for this compilation unit. See section 6.3. |
|
1755 .LI |
|
1756 A |
|
1757 .Cf DW_AT_comp_dir |
|
1758 attribute whose value is a null-terminated string containing |
|
1759 the current working directory of the compilation command that |
|
1760 produced this compilation unit in whatever form makes sense |
|
1761 for the host system. |
|
1762 .P |
|
1763 .I |
|
1764 The suggested form for the value of the \f(CWDW_AT_comp_dir\fP |
|
1765 attribute on \*(aX systems is ``hostname\f(CW:\fPpathname''. If no |
|
1766 hostname is available, the suggested form is ``\f(CW:\fPpathname''. |
|
1767 .R |
|
1768 .LI |
|
1769 A |
|
1770 .Cf DW_AT_producer |
|
1771 attribute whose value is a null-terminated string containing information |
|
1772 about the compiler that produced the compilation unit. The |
|
1773 actual contents of the string will be specific to each producer, |
|
1774 but should begin with the name of the compiler vendor or some |
|
1775 other identifying character sequence that should avoid |
|
1776 confusion with other producer values. |
|
1777 .LI |
|
1778 A |
|
1779 .Cf DW_AT_identifier_case |
|
1780 .IX identifiers, case |
|
1781 attribute whose constant value is a code describing the treatment of |
|
1782 identifiers within this compilation unit. The set of identifier case |
|
1783 .nr aX \n(Fg+1 |
|
1784 codes is given in Figure \n(aX. |
|
1785 .DF |
|
1786 .TS |
|
1787 box center; |
|
1788 lf(CW) |
|
1789 . |
|
1790 DW_ID_case_sensitive |
|
1791 DW_ID_up_case |
|
1792 DW_ID_down_case |
|
1793 DW_ID_case_insensitive |
|
1794 .TE |
|
1795 .FG "Identifier case codes" |
|
1796 .DE |
|
1797 .P |
|
1798 .Cf DW_ID_case_sensitive |
|
1799 is the default for all compilation units that do not have this attribute. |
|
1800 It indicates that names given as the values of |
|
1801 .Cf DW_AT_name |
|
1802 attributes in debugging information entries for the compilation unit |
|
1803 reflect the names as they appear in the source program. |
|
1804 The debugger should be sensitive to the case of identifier names |
|
1805 when doing identifier lookups. |
|
1806 .P |
|
1807 .Cf DW_ID_up_case |
|
1808 means that the producer of the debugging information for this compilation |
|
1809 unit converted all source names to upper case. The values of the |
|
1810 name attributes may not reflect the names as they appear in the source |
|
1811 program. The debugger should convert all names to upper case |
|
1812 when doing lookups. |
|
1813 .P |
|
1814 .Cf DW_ID_down_case |
|
1815 means that the producer of the debugging information for this compilation |
|
1816 unit converted all source names to lower case. The values of the |
|
1817 name attributes may not reflect the names as they appear in the source |
|
1818 program. The debugger should convert all names to lower case when |
|
1819 doing lookups. |
|
1820 .P |
|
1821 .Cf DW_ID_case_insensitive |
|
1822 means that the values of the name attributes reflect the names |
|
1823 as they appear in the source program but that a case insensitive |
|
1824 lookup should be used to access those names. |
|
1825 .LI |
|
1826 A |
|
1827 .Cf DW_AT_base_types |
|
1828 .IX base types |
|
1829 .IX types, base |
|
1830 attribute whose value is a reference. This attribute points to |
|
1831 a debugging information entry representing another compilation |
|
1832 unit. It may be used to specify the compilation unit containing |
|
1833 the base type entries used by entries in the current compilation |
|
1834 unit (see section 5.1). |
|
1835 .P |
|
1836 .I |
|
1837 This attribute provides a consumer a way to find the definition |
|
1838 of base types for a compilation unit that does not itself |
|
1839 contain such definitions. This allows a consumer, for example, |
|
1840 to interpret a type conversion to a base type correctly. |
|
1841 .R |
|
1842 .LE |
|
1843 .R |
|
1844 .P |
|
1845 A compilation unit entry |
|
1846 owns debugging information entries that represent the declarations made in |
|
1847 the corresponding compilation unit. |
|
1848 .H 2 "Module Entries" |
|
1849 .I |
|
1850 Several languages have the concept of a ``module.'' |
|
1851 .IX modules |
|
1852 .P |
|
1853 .R |
|
1854 A module is |
|
1855 represented by a debugging information entry with the tag |
|
1856 .Cf DW_TAG_module . |
|
1857 Module entries may own other debugging information entries describing |
|
1858 program entities whose declaration scopes end at the end of the module |
|
1859 itself. |
|
1860 .P |
|
1861 If the module has a name, the module entry has a |
|
1862 .Cf DW_AT_name |
|
1863 attribute whose |
|
1864 value is a null-terminated string containing the module name as it appears |
|
1865 in the source program. |
|
1866 .P |
|
1867 If the module contains initialization code, the module entry |
|
1868 has a |
|
1869 .Cf DW_AT_low_pc |
|
1870 attribute whose value is the |
|
1871 relocated address of the first machine instruction generated for that |
|
1872 initialization code. It also has a |
|
1873 .Cf DW_AT_high_pc |
|
1874 attribute whose value is |
|
1875 the relocated address of the first location past the last machine |
|
1876 instruction generated for the initialization code. |
|
1877 .P |
|
1878 If the module has been assigned a priority, it may have a |
|
1879 .Cf DW_AT_priority |
|
1880 attribute. The value of this attribute is a reference to another |
|
1881 .IX modules, priority |
|
1882 debugging information entry describing a variable with a constant |
|
1883 value. The value of this variable is the actual constant |
|
1884 value of the module's priority, represented as it would be on the |
|
1885 target architecture. |
|
1886 .P |
|
1887 .I |
|
1888 .IX Modula2 |
|
1889 .IX modules, definition |
|
1890 A Modula2 definition module may be represented by a module entry |
|
1891 containing a |
|
1892 .Cf DW_AT_declaration |
|
1893 attribute. |
|
1894 .R |
|
1895 .H 2 "Subroutine and Entry Point Entries" |
|
1896 .IX subroutines |
|
1897 .IX entry points |
|
1898 The following tags exist to describe debugging information |
|
1899 entries for subroutines and entry points: |
|
1900 .VL 30 |
|
1901 .LI \f(CWDW_TAG_subprogram\fP |
|
1902 A global or file static subroutine or function. |
|
1903 .LI \f(CWDW_TAG_inlined_subroutine\fP |
|
1904 A particular inlined instance of a subroutine or function. |
|
1905 .LI \f(CWDW_TAG_entry_point\fP |
|
1906 A Fortran entry point. |
|
1907 .LE |
|
1908 .H 3 "General Subroutine and Entry Point Information" |
|
1909 The subroutine or entry point entry has a |
|
1910 .Cf DW_AT_name |
|
1911 attribute |
|
1912 whose value is a null-terminated string containing the subroutine or entry |
|
1913 point name as it appears in the source program. |
|
1914 .P |
|
1915 If the name of the subroutine described by an entry with the tag |
|
1916 .Cf DW_TAG_subprogram |
|
1917 is visible outside of its containing compilation unit, that |
|
1918 entry has a |
|
1919 .Cf DW_AT_external |
|
1920 attribute, whose value is a flag. |
|
1921 .IX declarations, external |
|
1922 .I |
|
1923 .P |
|
1924 .IX members, functions |
|
1925 .IX subroutines, members |
|
1926 Additional attributes for functions that are members of a class or |
|
1927 structure are described in section 5.5.5. |
|
1928 .P |
|
1929 A common debugger feature is to allow the debugger user to call a |
|
1930 subroutine within the subject program. In certain cases, however, |
|
1931 the generated code for a subroutine will not obey the standard calling |
|
1932 conventions for the target architecture and will therefore not |
|
1933 .IX calling conventions |
|
1934 be safe to call from within a debugger. |
|
1935 .R |
|
1936 .P |
|
1937 A subroutine entry may contain a |
|
1938 .Cf DW_AT_calling_convention |
|
1939 attribute, whose value is a constant. If this attribute is not |
|
1940 present, or its value is the constant |
|
1941 .Cf DW_CC_normal , |
|
1942 then the subroutine may be safely called by obeying the ``standard'' |
|
1943 calling conventions of the target architecture. If the value of |
|
1944 the calling convention attribute is the constant |
|
1945 .Cf DW_CC_nocall , |
|
1946 the subroutine does not obey standard calling conventions, and it |
|
1947 may not be safe for the debugger to call this subroutine. |
|
1948 .P |
|
1949 If the semantics of the language of the compilation unit |
|
1950 containing the subroutine entry distinguishes between ordinary subroutines |
|
1951 .IX main programs |
|
1952 and subroutines that can serve as the ``main program,'' that is, subroutines |
|
1953 that cannot be called directly following the ordinary calling conventions, |
|
1954 then the debugging information entry for such a subroutine may have a |
|
1955 calling convention attribute whose value is the constant |
|
1956 .Cf DW_CC_program . |
|
1957 .P |
|
1958 .I |
|
1959 The |
|
1960 .Cf DW_CC_program |
|
1961 value is intended to support Fortran main programs. |
|
1962 It is not intended as a way of finding the entry address for the program. |
|
1963 .R |
|
1964 .H 3 "Subroutine and Entry Point Return Types" |
|
1965 .IX subroutines, return types |
|
1966 .IX entry points, return types |
|
1967 If the subroutine or entry point is a function that returns a value, then |
|
1968 its debugging information entry has a |
|
1969 .Cf DW_AT_type |
|
1970 attribute to denote the type returned by that function. |
|
1971 .P |
|
1972 .I |
|
1973 Debugging information entries for C |
|
1974 .Cf void |
|
1975 .IX C %c |
|
1976 functions should not have an attribute for the return type. |
|
1977 .P |
|
1978 In ANSI-C there is a difference between the types of functions |
|
1979 declared using function prototype style declarations and those |
|
1980 declared using non-prototype declarations. |
|
1981 .IX subroutines, prototypes |
|
1982 .P |
|
1983 .R |
|
1984 A subroutine entry |
|
1985 declared with a function prototype style declaration may have a |
|
1986 .Cf DW_AT_prototyped |
|
1987 attribute, whose value is a flag. |
|
1988 .H 3 "Subroutine and Entry Point Locations" |
|
1989 .IX subroutines, locations |
|
1990 .IX entry points, locations |
|
1991 A subroutine entry has a |
|
1992 .Cf DW_AT_low_pc |
|
1993 attribute whose value is the relocated address of the first machine instruction |
|
1994 generated for the subroutine. |
|
1995 It also has a |
|
1996 .Cf DW_AT_high_pc |
|
1997 attribute whose value is the relocated address of the |
|
1998 first location past the last machine instruction generated |
|
1999 for the subroutine. |
|
2000 .P |
|
2001 .I |
|
2002 Note that for the low and high pc attributes to have meaning, DWARF |
|
2003 makes the assumption that the code for a single subroutine is allocated |
|
2004 in a single contiguous block of memory. |
|
2005 .IX address space, contiguous |
|
2006 .R |
|
2007 .P |
|
2008 An entry point has a |
|
2009 .Cf DW_AT_low_pc |
|
2010 attribute whose value is the relocated address of the first machine instruction |
|
2011 generated for the entry point. |
|
2012 .P |
|
2013 Subroutines and entry points may also have |
|
2014 .Cf DW_AT_segment |
|
2015 and |
|
2016 .Cf DW_AT_address_class |
|
2017 .IX segmented address space |
|
2018 .IX address space, segmented |
|
2019 .IX addresses, class |
|
2020 attributes, as appropriate, to specify which segments the code |
|
2021 for the subroutine resides in and the addressing mode to be used |
|
2022 in calling that subroutine. |
|
2023 .P |
|
2024 A subroutine entry representing a subroutine declaration |
|
2025 that is not also a definition does not have low and high pc attributes. |
|
2026 .IX declarations, non-defining |
|
2027 .H 3 "Declarations Owned by Subroutines and Entry Points" |
|
2028 .IX subroutines, declarations owned by |
|
2029 .IX entry points, declarations owned by |
|
2030 The declarations enclosed by a subroutine or entry point |
|
2031 are represented by debugging information entries that are |
|
2032 owned by the subroutine or entry point entry. |
|
2033 Entries representing the formal parameters of the subroutine or |
|
2034 entry point appear in |
|
2035 the same order as the corresponding declarations in the source program. |
|
2036 .IX attributes, ordering |
|
2037 .IX parameters, formal |
|
2038 .P |
|
2039 .I |
|
2040 There is no ordering requirement on entries for declarations that are |
|
2041 children of subroutine or entry point entries but that do not represent |
|
2042 formal parameters. The formal parameter entries may be interspersed |
|
2043 with other entries used by formal parameter entries, such as type entries. |
|
2044 .R |
|
2045 .P |
|
2046 The unspecified parameters of a variable parameter list |
|
2047 .IX parameters, unspecified |
|
2048 are represented by a debugging information entry with the tag |
|
2049 .Cf DW_TAG_unspecified_parameters . |
|
2050 .P |
|
2051 The entry for a subroutine or entry point that includes a Fortran |
|
2052 .IX Fortran |
|
2053 .IX common blocks |
|
2054 common block has a child entry with the tag |
|
2055 .Cf DW_TAG_common_inclusion . |
|
2056 The common inclusion entry has a |
|
2057 .Cf DW_AT_common_reference |
|
2058 attribute whose value is a reference to the debugging entry for |
|
2059 the common block being included (see section 4.2). |
|
2060 .H 3 "Low-Level Information" |
|
2061 A subroutine or entry point entry may have a |
|
2062 .Cf DW_AT_return_addr |
|
2063 .IX subroutines, return addresses |
|
2064 attribute, whose value is a location description. |
|
2065 The location calculated is the place where the return address for |
|
2066 the subroutine or entry point is stored. |
|
2067 .P |
|
2068 A subroutine or entry point entry may also have a |
|
2069 .Cf DW_AT_frame_base |
|
2070 .IX subroutines, frame base |
|
2071 attribute, whose value is a location description that |
|
2072 computes the ``frame base'' for the subroutine or entry point. |
|
2073 .P |
|
2074 .I |
|
2075 The frame base for a procedure is typically an address fixed |
|
2076 relative to the first unit of storage allocated for the procedure's |
|
2077 stack frame. The |
|
2078 .Cf DW_AT_frame_base |
|
2079 attribute can be used in several ways: |
|
2080 .AL |
|
2081 .LI |
|
2082 In procedures that need location lists to locate local variables, the |
|
2083 .Cf DW_AT_frame_base |
|
2084 can hold the needed location list, while all variables' |
|
2085 location descriptions can be simpler location expressions involving the frame |
|
2086 base. |
|
2087 .LI |
|
2088 It can be used as a key in resolving "up-level" addressing with nested |
|
2089 routines. (See |
|
2090 .Cf DW_AT_static_link , |
|
2091 below) |
|
2092 .LE |
|
2093 .P |
|
2094 Some languages support nested subroutines. In such languages, it is possible |
|
2095 .IX subroutines, nested |
|
2096 to reference the local variables of an outer subroutine from within |
|
2097 an inner subroutine. The |
|
2098 .Cf DW_AT_static_link |
|
2099 and |
|
2100 .Cf DW_AT_frame_base |
|
2101 attributes allow debuggers to support this same kind of referencing. |
|
2102 .R |
|
2103 .P |
|
2104 If a subroutine or entry point is nested, it may have a |
|
2105 .Cf DW_AT_static_link |
|
2106 attribute, whose value is a location description that |
|
2107 computes the frame base of the relevant instance of the subroutine |
|
2108 that immediately encloses the subroutine or entry point. |
|
2109 .P |
|
2110 In the context of supporting nested subroutines, the |
|
2111 .Cf DW_AT_frame_base |
|
2112 attribute value should obey the following constraints: |
|
2113 .AL |
|
2114 .LI |
|
2115 It should compute a value that does not change during the life of the procedure, |
|
2116 and |
|
2117 .LI |
|
2118 The computed value should be unique among instances of the same subroutine. |
|
2119 (For typical |
|
2120 .Cf DW_AT_frame_base |
|
2121 use, this means that a recursive |
|
2122 subroutine's stack frame must have non-zero size.) |
|
2123 .LE |
|
2124 .P |
|
2125 .I |
|
2126 If a debugger is attempting to resolve an up-level reference to a variable, it |
|
2127 uses the nesting structure of DWARF to determine which subroutine is the lexical |
|
2128 parent and the |
|
2129 .Cf DW_AT_static_link |
|
2130 value to identify the appropriate active frame |
|
2131 of the parent. It can then attempt to find the reference within the context |
|
2132 of the parent. |
|
2133 .R |
|
2134 .H 3 "Types Thrown by Exceptions" |
|
2135 .I |
|
2136 In C++ a subroutine may declare a set of types for which |
|
2137 .IX C++ %caa |
|
2138 .IX exceptions |
|
2139 that subroutine may generate or ``throw'' an exception. |
|
2140 .P |
|
2141 .R |
|
2142 If a subroutine explicitly declares that it may throw an |
|
2143 exception for one or more types, each such type is |
|
2144 represented by a debugging information entry with the tag |
|
2145 .Cf DW_TAG_thrown_type . |
|
2146 Each such entry is a child of the entry representing the |
|
2147 subroutine that may throw this type. All thrown type entries |
|
2148 should follow all entries representing the formal parameters |
|
2149 of the subroutine and precede all entries representing the |
|
2150 local variables or lexical blocks contained in the subroutine. |
|
2151 Each thrown type entry contains a |
|
2152 .Cf DW_AT_type |
|
2153 attribute, whose value is a reference to an entry describing |
|
2154 the type of the exception that may be thrown. |
|
2155 .H 3 "Function Template Instantiations" |
|
2156 .I |
|
2157 .IX C++ %caa |
|
2158 .IX templates |
|
2159 In C++ a function template is a generic |
|
2160 definition of a function that |
|
2161 is instantiated differently when called with values |
|
2162 of different types. DWARF does not represent the generic |
|
2163 template definition, but does represent each instantiation. |
|
2164 .R |
|
2165 .P |
|
2166 A template instantiation is represented by a debugging information |
|
2167 entry with the tag |
|
2168 .Cf DW_TAG_subprogram . |
|
2169 With three exceptions, |
|
2170 such an entry will contain the same attributes and have the same |
|
2171 types of child entries as would an entry for a subroutine |
|
2172 defined explicitly |
|
2173 using the instantiation types. The exceptions are: |
|
2174 .AL |
|
2175 .LI |
|
2176 Each formal parameterized type declaration appearing in the |
|
2177 template definition is represented by a debugging information entry |
|
2178 with the tag |
|
2179 .Cf DW_TAG_template_type_parameter . |
|
2180 Each such entry has a |
|
2181 .Cf DW_AT_name |
|
2182 attribute, whose value is a null-terminated |
|
2183 string containing the name of the formal type parameter as it |
|
2184 appears in the source program. The template type parameter |
|
2185 entry also has a |
|
2186 .Cf DW_AT_type |
|
2187 attribute describing the actual type by |
|
2188 which the formal is replaced for this instantiation. |
|
2189 All template type parameter entries should appear before |
|
2190 the entries describing the instantiated formal parameters |
|
2191 to the function. |
|
2192 .LI |
|
2193 .IX compilation units |
|
2194 If the compiler has generated a special compilation unit |
|
2195 to hold the template instantiation and that compilation unit |
|
2196 has a different name |
|
2197 from the compilation unit containing the template definition, |
|
2198 the name attribute for the debugging entry representing |
|
2199 that compilation unit should be empty or omitted. |
|
2200 .LI |
|
2201 .IX declarations, coordinates |
|
2202 If the subprogram entry representing the template instantiation |
|
2203 or any of its child entries |
|
2204 contain declaration coordinate attributes, those attributes |
|
2205 should refer to the source for the template definition, not |
|
2206 to any source generated artificially by the compiler for this |
|
2207 instantiation. |
|
2208 .LE |
|
2209 .H 3 "Inline Subroutines" |
|
2210 .IX subroutines, inline |
|
2211 A declaration or a definition of an inlinable subroutine |
|
2212 is represented by a debugging information entry with the tag |
|
2213 .Cf DW_TAG_subprogram . |
|
2214 The entry for a subroutine that is explicitly declared |
|
2215 to be available for inline expansion or that was expanded inline |
|
2216 implicitly by the compiler has a |
|
2217 .Cf DW_AT_inline |
|
2218 attribute whose value is a constant. The set of values |
|
2219 for the |
|
2220 .Cf DW_AT_inline |
|
2221 .nr aX \n(Fg+1 |
|
2222 attribute is given in Figure \n(aX. |
|
2223 .DF |
|
2224 .TS |
|
2225 box center; |
|
2226 l l |
|
2227 lf(CW) l |
|
2228 . |
|
2229 Name Meaning |
|
2230 _ |
|
2231 DW_INL_not_inlined Not declared inline nor inlined by the compiler |
|
2232 DW_INL_inlined Not declared inline but inlined by the compiler |
|
2233 DW_INL_declared_not_inlined Declared inline but not inlined by the compiler |
|
2234 DW_INL_declared_inlined Declared inline and inlined by the compiler |
|
2235 .TE |
|
2236 .FG "Inline codes" |
|
2237 .DE |
|
2238 .H 4 "Abstract Instances" |
|
2239 For the remainder of this discussion, |
|
2240 any debugging information entry that is owned (either directly or |
|
2241 indirectly) by a debugging information entry that contains the |
|
2242 .Cf DW_AT_inline |
|
2243 attribute will be referred to as an ``abstract instance entry.'' |
|
2244 Any subroutine entry that contains a |
|
2245 .Cf DW_AT_inline |
|
2246 attribute will be known as an ``abstract instance root.'' |
|
2247 Any set of abstract instance entries that are all children (either directly |
|
2248 or indirectly) of some abstract instance root, together with the root itself, |
|
2249 will be known as an ``abstract instance tree.'' |
|
2250 .P |
|
2251 A debugging information entry that is a member of an abstract instance |
|
2252 tree should not contain a |
|
2253 .Cf DW_AT_high_pc , |
|
2254 .Cf DW_AT_low_pc , |
|
2255 .Cf DW_AT_location , |
|
2256 .Cf DW_AT_return_addr , |
|
2257 .Cf DW_AT_start_scope , |
|
2258 or |
|
2259 .Cf DW_AT_segment |
|
2260 attribute. |
|
2261 .P |
|
2262 .I |
|
2263 It would not make sense to put these attributes |
|
2264 into abstract instance entries since |
|
2265 such entries do not represent actual (concrete) instances and thus |
|
2266 do not actually exist at run-time. |
|
2267 .P |
|
2268 .R |
|
2269 The rules for the relative location of entries belonging to abstract instance |
|
2270 trees are exactly |
|
2271 the same as for other similar types of entries that are not abstract. |
|
2272 Specifically, the rule that requires that an entry representing a |
|
2273 declaration be a direct child of the entry representing the scope of |
|
2274 the declaration applies equally to both abstract and |
|
2275 non-abstract entries. Also, the ordering rules for formal parameter entries, |
|
2276 member entries, and so on, all apply regardless of whether or not a given entry |
|
2277 is abstract. |
|
2278 .H 4 "Concrete Inlined Instances" |
|
2279 .IX subroutines, inlined |
|
2280 Each inline expansion of an inlinable subroutine is represented |
|
2281 by a debugging information entry with the tag |
|
2282 .Cf DW_TAG_inlined_subroutine . |
|
2283 Each such entry should be a direct child of the entry that represents the |
|
2284 scope within which the inlining occurs. |
|
2285 .P |
|
2286 Each inlined subroutine entry contains a |
|
2287 .Cf DW_AT_low_pc |
|
2288 attribute, representing the address of the first |
|
2289 instruction associated with the given inline |
|
2290 expansion. Each inlined subroutine entry also contains a |
|
2291 .Cf DW_AT_high_pc |
|
2292 attribute, representing the |
|
2293 address of the first location past the last instruction associated with |
|
2294 the inline expansion. |
|
2295 .P |
|
2296 For the remainder of this discussion, |
|
2297 any debugging information entry that is owned (either directly or indirectly) |
|
2298 by a debugging information entry with the tag |
|
2299 .Cf DW_TAG_inlined_subroutine |
|
2300 will be referred to as a ``concrete inlined instance entry.'' |
|
2301 Any entry that has the tag |
|
2302 .Cf DW_TAG_inlined_subroutine |
|
2303 will be known as |
|
2304 a ``concrete inlined instance root.'' |
|
2305 Any set of concrete inlined instance entries that are all children (either |
|
2306 directly or indirectly) of some concrete inlined instance root, together |
|
2307 with the root itself, will be known as a ``concrete inlined instance |
|
2308 tree.'' |
|
2309 .P |
|
2310 Each concrete inlined instance tree is uniquely associated with one (and |
|
2311 only one) abstract instance tree. |
|
2312 .P |
|
2313 .I |
|
2314 Note, however, that the reverse is not true. Any given abstract instance |
|
2315 tree may be associated with several different concrete inlined instance |
|
2316 trees, or may even be associated with zero concrete inlined instance |
|
2317 trees. |
|
2318 .P |
|
2319 .R |
|
2320 Also, each separate entry within a given concrete inlined instance tree is |
|
2321 uniquely associated with one particular entry in the associated abstract |
|
2322 instance tree. In other words, there is a one-to-one mapping from entries |
|
2323 in a given concrete inlined instance tree to the entries in the associated |
|
2324 abstract instance tree. |
|
2325 .P |
|
2326 .I |
|
2327 Note, however, that the reverse is not true. A given abstract instance |
|
2328 tree that is associated with a given concrete inlined instance tree |
|
2329 may (and quite probably will) contain more entries than the associated |
|
2330 concrete inlined instance tree (see below). |
|
2331 .R |
|
2332 .P |
|
2333 Concrete inlined instance entries do not have most of the attributes (except |
|
2334 for |
|
2335 .Cf DW_AT_low_pc , |
|
2336 .Cf DW_AT_high_pc , |
|
2337 .Cf DW_AT_location , |
|
2338 .Cf DW_AT_return_addr , |
|
2339 .Cf DW_AT_start_scope |
|
2340 and |
|
2341 .Cf DW_AT_segment ) |
|
2342 that such entries |
|
2343 would otherwise normally have. In place of these omitted attributes, |
|
2344 each concrete inlined instance entry has a |
|
2345 .Cf DW_AT_abstract_origin |
|
2346 attribute that |
|
2347 may be used to obtain the missing information (indirectly) from |
|
2348 the associated abstract instance entry. The value of the abstract |
|
2349 origin attribute is a reference to the associated abstract instance entry. |
|
2350 .P |
|
2351 For each pair of entries that are associated via a |
|
2352 .Cf DW_AT_abstract_origin |
|
2353 attribute, both members of the pair will have the same tag. So, for |
|
2354 example, an entry with the tag |
|
2355 .Cf DW_TAG_local_variable |
|
2356 can only be associated |
|
2357 with another entry that also has the tag |
|
2358 .Cf DW_TAG_local_variable. |
|
2359 The only exception to this rule is that the root of a concrete |
|
2360 instance tree (which must always have the tag |
|
2361 .Cf DW_TAG_inlined_subroutine ) |
|
2362 can only be associated with the root of its associated abstract |
|
2363 instance tree (which must have the tag |
|
2364 .Cf DW_TAG_subprogram ). |
|
2365 .P |
|
2366 In general, the structure and content of any given concrete |
|
2367 instance tree will be directly analogous to the structure and content |
|
2368 of its associated abstract instance tree. |
|
2369 There are two exceptions to this general rule however. |
|
2370 .AL |
|
2371 .LI |
|
2372 .IX anonymous types |
|
2373 No entries representing anonymous types are ever made a part |
|
2374 of any concrete instance inlined tree. |
|
2375 .LI |
|
2376 .IX members |
|
2377 No entries representing members of structure, union or class |
|
2378 types are ever made a part of any concrete inlined instance tree. |
|
2379 .LE |
|
2380 .P |
|
2381 .I |
|
2382 Entries that represent members and anonymous types are omitted from concrete |
|
2383 inlined instance trees because they would simply be redundant duplicates of |
|
2384 the corresponding entries in the associated abstract instance trees. If |
|
2385 any entry within a concrete inlined instance tree needs to refer to an |
|
2386 anonymous type that was declared within the scope of the |
|
2387 relevant inline function, the reference should simply refer to the abstract |
|
2388 instance entry for the given anonymous type. |
|
2389 .R |
|
2390 .P |
|
2391 .IX declarations, coordinates |
|
2392 If an entry within a concrete inlined instance tree contains |
|
2393 attributes describing the declaration coordinates of |
|
2394 that entry, |
|
2395 then those attributes should refer to the file, line and column |
|
2396 of the original declaration of the subroutine, not to the |
|
2397 point at which it was inlined. |
|
2398 .H 4 "Out-of-Line Instances of Inline Subroutines" |
|
2399 .IX subroutines, out-of-line |
|
2400 Under some conditions, compilers may need to generate concrete executable |
|
2401 instances of inline subroutines other than at points where those subroutines |
|
2402 are actually called. For the remainder of this discussion, |
|
2403 such concrete instances of inline subroutines will |
|
2404 be referred to as ``concrete out-of-line instances.'' |
|
2405 .P |
|
2406 .I |
|
2407 In C++, for example, taking the address of a function declared to be inline |
|
2408 can necessitate the generation of a concrete out-of-line |
|
2409 instance of the given function. |
|
2410 .P |
|
2411 .R |
|
2412 The DWARF representation of a concrete out-of-line instance of an inline |
|
2413 subroutine is essentially the same as for a concrete inlined instance of |
|
2414 that subroutine (as described in the preceding section). The representation |
|
2415 of such a concrete out-of-line instance makes use of |
|
2416 .Cf DW_AT_abstract_origin |
|
2417 attributes in exactly the same way as they are used for a concrete inlined |
|
2418 instance (that is, as references to corresponding entries |
|
2419 within the associated |
|
2420 abstract instance tree) and, as for concrete instance trees, the |
|
2421 entries for anonymous types and for all members are omitted. |
|
2422 .P |
|
2423 The differences between the DWARF representation of a concrete out-of-line |
|
2424 instance of a given subroutine and the representation of a concrete inlined |
|
2425 instance of that same subroutine are as follows: |
|
2426 .AL |
|
2427 .LI |
|
2428 The root entry for a concrete out-of-line instance of a given |
|
2429 inline subroutine has the same tag as does its associated |
|
2430 (abstract) inline subroutine entry (that is, it does not have the |
|
2431 tag |
|
2432 .Cf DW_TAG_inlined_subroutine ). |
|
2433 .LI |
|
2434 The root entry for a concrete out-of-line instance tree is |
|
2435 always directly owned by the same parent entry that |
|
2436 also owns the root entry of the associated abstract instance. |
|
2437 .LE |
|
2438 .H 2 "Lexical Block Entries" |
|
2439 .I |
|
2440 .IX lexical blocks |
|
2441 A lexical block is a bracketed sequence of source statements that may |
|
2442 contain any number of declarations. In some languages (C and C++) |
|
2443 blocks can be nested within other blocks to any depth. |
|
2444 .P |
|
2445 .R |
|
2446 A lexical block is represented by a debugging information entry |
|
2447 with the tag |
|
2448 .Cf DW_TAG_lexical_block . |
|
2449 .P |
|
2450 The lexical block entry has a |
|
2451 .Cf DW_AT_low_pc |
|
2452 attribute whose value is the |
|
2453 relocated address of the first machine instruction generated for the lexical |
|
2454 block. |
|
2455 The lexical block entry also has a |
|
2456 .Cf DW_AT_high_pc |
|
2457 attribute whose value is the |
|
2458 relocated address of the first location |
|
2459 past the last machine instruction generated for the lexical block. |
|
2460 .P |
|
2461 If a name has been given to the lexical block in the source program, |
|
2462 then the corresponding lexical block entry has a |
|
2463 .Cf DW_AT_name |
|
2464 attribute |
|
2465 whose value is a null-terminated string containing the name of the |
|
2466 lexical block as it appears in the source program. |
|
2467 .P |
|
2468 .I |
|
2469 This is not the |
|
2470 same as a C or C++ label (see below). |
|
2471 .R |
|
2472 .P |
|
2473 The lexical block entry owns debugging information entries that |
|
2474 describe the declarations within that lexical block. |
|
2475 There is one such debugging information entry for each local declaration |
|
2476 of an identifier or inner lexical block. |
|
2477 .H 2 "Label Entries" |
|
2478 .I |
|
2479 .IX labels |
|
2480 A label is a way of identifying a source statement. A labeled statement |
|
2481 is usually the target of one or more ``go to'' statements. |
|
2482 .P |
|
2483 .R |
|
2484 A label is represented by a debugging information entry |
|
2485 with the tag |
|
2486 .Cf DW_TAG_label . |
|
2487 The entry for a label should be owned by |
|
2488 the debugging information entry representing the scope within which the name |
|
2489 of the label could be legally referenced within the source program. |
|
2490 .P |
|
2491 The label entry has a |
|
2492 .Cf DW_AT_low_pc |
|
2493 attribute whose value is the |
|
2494 relocated address of the first machine instruction generated for the |
|
2495 statement identified by the label in the source program. |
|
2496 The label entry also has a |
|
2497 .Cf DW_AT_name |
|
2498 attribute |
|
2499 whose value is a null-terminated string containing the name of the |
|
2500 label as it appears in the source program. |
|
2501 .H 2 "With Statement Entries" |
|
2502 .I |
|
2503 .IX with statements |
|
2504 .IX Pascal |
|
2505 .IX Modula2 |
|
2506 Both Pascal and Modula support the concept of a ``with'' statement. |
|
2507 The with statement specifies a sequence of executable statements |
|
2508 within which the fields of a record variable may be referenced, unqualified |
|
2509 by the name of the record variable. |
|
2510 .P |
|
2511 .R |
|
2512 A with statement is represented by a debugging information entry with |
|
2513 the tag |
|
2514 .Cf DW_TAG_with_stmt . |
|
2515 A with statement entry has a |
|
2516 .Cf DW_AT_low_pc |
|
2517 attribute whose value is the relocated |
|
2518 address of the first machine instruction generated for the body of |
|
2519 the with statement. A with statement entry also has a |
|
2520 .Cf DW_AT_high_pc |
|
2521 attribute whose value is the relocated |
|
2522 address of the first location after the last machine instruction generated for the body of |
|
2523 the statement. |
|
2524 .P |
|
2525 The with statement entry has a |
|
2526 .Cf DW_AT_type |
|
2527 attribute, denoting |
|
2528 the type of record whose fields may be referenced without full qualification |
|
2529 within the body of the statement. It also has a |
|
2530 .Cf DW_AT_location |
|
2531 attribute, describing how to find the base address |
|
2532 of the record object referenced within the body of the with statement. |
|
2533 .H 2 "Try and Catch Block Entries" |
|
2534 .I |
|
2535 .IX C++ %caa |
|
2536 .IX exceptions |
|
2537 .IX try blocks |
|
2538 .IX catch blocks |
|
2539 In C++ a lexical block may be designated as a ``catch block.'' |
|
2540 A catch block is an exception handler that handles exceptions |
|
2541 thrown by an immediately preceding ``try block.'' A catch block |
|
2542 designates the type of the exception that it can handle. |
|
2543 .R |
|
2544 .P |
|
2545 A try block is represented by a debugging information entry |
|
2546 with the tag |
|
2547 .Cf DW_TAG_try_block . |
|
2548 A catch block is represented by a debugging information entry |
|
2549 with the tag |
|
2550 .Cf DW_TAG_catch_block . |
|
2551 Both try and catch block entries contain a |
|
2552 .Cf DW_AT_low_pc |
|
2553 attribute whose value is the |
|
2554 relocated address of the first machine instruction generated for that |
|
2555 block. These entries also contain a |
|
2556 .Cf DW_AT_high_pc |
|
2557 attribute whose value is the |
|
2558 relocated address of the first location |
|
2559 past the last machine instruction generated for that block. |
|
2560 .P |
|
2561 Catch block entries have at least one child entry, |
|
2562 an entry representing the type of exception accepted |
|
2563 by that catch block. This child entry will have one of the tags |
|
2564 .Cf DW_TAG_formal_parameter |
|
2565 or |
|
2566 .Cf DW_TAG_unspecified_parameters , |
|
2567 .IX parameters, formal |
|
2568 .IX parameters, unspecified |
|
2569 and will have the same form as other parameter entries. |
|
2570 .P |
|
2571 The first sibling of each try block entry will be a catch block |
|
2572 entry. |
|
2573 .OP |
|
2574 .H 1 "DATA OBJECT AND OBJECT LIST ENTRIES" |
|
2575 This section presents the debugging information entries that |
|
2576 describe individual data objects: variables, parameters and |
|
2577 constants, and lists of those objects that may be grouped |
|
2578 in a single declaration, such as a common block. |
|
2579 .H 2 "Data Object Entries" |
|
2580 .IX variables |
|
2581 .IX parameters, formal |
|
2582 .IX constants |
|
2583 Program variables, formal parameters and constants are represented |
|
2584 by debugging information entries with the tags |
|
2585 .Cf DW_TAG_variable , |
|
2586 .Cf DW_TAG_formal_parameter |
|
2587 and |
|
2588 .Cf DW_TAG_constant , |
|
2589 respectively. |
|
2590 .P |
|
2591 .I |
|
2592 The tag |
|
2593 .Cf DW_TAG_constant |
|
2594 is used for languages that distinguish between variables |
|
2595 that may have constant value and true named constants. |
|
2596 .R |
|
2597 .P |
|
2598 The debugging information entry for a program variable, formal |
|
2599 parameter or constant may have the following attributes: |
|
2600 .AL |
|
2601 .LI |
|
2602 A |
|
2603 .Cf DW_AT_name |
|
2604 attribute whose value is a null-terminated |
|
2605 string containing the data object name as it appears in the source program. |
|
2606 .P |
|
2607 .IX anonymous unions |
|
2608 .IX unions, anonymous |
|
2609 .IX C++ %caa |
|
2610 If a variable entry describes a C++ anonymous union, the name |
|
2611 attribute is omitted or consists of a single zero byte. |
|
2612 .LI |
|
2613 If the name of a variable is visible outside of its enclosing |
|
2614 compilation unit, the variable entry has a |
|
2615 .Cf DW_AT_external |
|
2616 .IX declarations, external |
|
2617 attribute, whose value is a flag. |
|
2618 .I |
|
2619 .P |
|
2620 .IX members, static data |
|
2621 The definitions of C++ static data members |
|
2622 of structures or classes are represented by variable entries flagged |
|
2623 as external. |
|
2624 .IX C %c |
|
2625 .IX C++ %caa |
|
2626 Both file static and local variables in C and C++ are represented |
|
2627 by non-external variable entries. |
|
2628 .R |
|
2629 .LI |
|
2630 A |
|
2631 .Cf DW_AT_location |
|
2632 attribute, whose value describes the location of a variable or parameter |
|
2633 at run-time. |
|
2634 .P |
|
2635 .IX declarations, non-defining |
|
2636 A data object entry representing a non-defining declaration of the object |
|
2637 will not have a location attribute, and will have the |
|
2638 .Cf DW_AT_declaration |
|
2639 attribute. |
|
2640 .P |
|
2641 In a variable entry representing the definition of the variable |
|
2642 (that is, with no |
|
2643 .Cf DW_AT_declaration |
|
2644 attribute) |
|
2645 if no location attribute is present, or if |
|
2646 the location attribute is present but describes |
|
2647 a null entry (as described in section 2.4), the variable |
|
2648 is assumed to exist in the source code but not in the executable |
|
2649 program (but see number 9, below). |
|
2650 .IX optimized code |
|
2651 .P |
|
2652 The location of a variable may be further specified with a |
|
2653 .Cf DW_AT_segment |
|
2654 attribute, if appropriate. |
|
2655 .IX segmented address space |
|
2656 .IX address space, segmented |
|
2657 .LI |
|
2658 A |
|
2659 .Cf DW_AT_type |
|
2660 attribute describing the type of the variable, constant or formal |
|
2661 parameter. |
|
2662 .LI |
|
2663 .IX members, static data |
|
2664 .IX declarations, defining |
|
2665 If the variable entry represents the defining declaration for a C++ static |
|
2666 data member of a structure, class or union, the entry has a |
|
2667 .Cf DW_AT_specification |
|
2668 attribute, whose value is a reference to the debugging information |
|
2669 entry representing the declaration of this data member. The |
|
2670 referenced entry will be a child of some class, structure or |
|
2671 union type entry. |
|
2672 .IX classes |
|
2673 .IX structures |
|
2674 .IX unions |
|
2675 .P |
|
2676 Variable entries containing the |
|
2677 .Cf DW_AT_specification |
|
2678 attribute do not need to duplicate information provided by the |
|
2679 declaration entry referenced by the specification attribute. |
|
2680 In particular, such variable entries do not need to contain |
|
2681 attributes for the name or type of the data member whose |
|
2682 definition they represent. |
|
2683 .LI |
|
2684 .I |
|
2685 Some languages distinguish between parameters whose value in the |
|
2686 calling function can be modified by the callee (variable parameters), |
|
2687 and parameters whose value in the calling function cannot be modified |
|
2688 by the callee (constant parameters). |
|
2689 .P |
|
2690 .R |
|
2691 If a formal parameter entry represents a parameter whose value |
|
2692 in the calling function may be modified by the callee, that entry |
|
2693 may have a |
|
2694 .Cf DW_AT_variable_parameter |
|
2695 attribute, whose value is a flag. The absence of this attribute |
|
2696 implies that the parameter's value in the calling function cannot |
|
2697 be modified by the callee. |
|
2698 .IX parameters, variable |
|
2699 .LI |
|
2700 .I |
|
2701 Fortran90 has the concept of an optional parameter. |
|
2702 .IX Fortran90 |
|
2703 .P |
|
2704 .R |
|
2705 .IX parameters, optional |
|
2706 If a parameter entry represents an optional parameter, it has a |
|
2707 .Cf DW_AT_is_optional |
|
2708 attribute, whose value is a flag. |
|
2709 .LI |
|
2710 .IX parameters, default value |
|
2711 A formal parameter entry describing a formal parameter that has a default |
|
2712 value may have a |
|
2713 .Cf DW_AT_default_value |
|
2714 attribute. The value of this attribute is a reference to the |
|
2715 debugging information entry for a variable or subroutine. The |
|
2716 default value of the parameter is the value of the variable (which |
|
2717 may be constant) or the value returned by the subroutine. If the |
|
2718 value of the |
|
2719 .Cf DW_AT_default_value |
|
2720 attribute is 0, it means that no default value has been specified. |
|
2721 .LI |
|
2722 .IX constants |
|
2723 An entry describing a variable whose value is constant |
|
2724 and not represented by an object in the address space of the program, |
|
2725 or an entry describing a named constant, |
|
2726 does not have a location attribute. Such entries have a |
|
2727 .Cf DW_AT_const_value |
|
2728 attribute, whose value may be a string or any of the constant |
|
2729 data or data block forms, as appropriate for the representation |
|
2730 of the variable's value. The value of this attribute is the actual |
|
2731 constant value of the variable, represented as it would be |
|
2732 on the target architecture. |
|
2733 .LI |
|
2734 .IX scope |
|
2735 .IX declarations, scope |
|
2736 If the scope of an object begins sometime after the low pc value |
|
2737 for the scope most closely enclosing the object, the |
|
2738 object entry may have a |
|
2739 .Cf DW_AT_start_scope |
|
2740 attribute. The value of this attribute is the offset in bytes of the beginning |
|
2741 of the scope for the object from the low pc value of the debugging |
|
2742 information entry that defines its scope. |
|
2743 .P |
|
2744 .I |
|
2745 The scope of a variable may begin somewhere in the middle of a lexical |
|
2746 block in a language that allows executable code in a |
|
2747 block before a variable declaration, or where one declaration |
|
2748 containing initialization code may change the scope of a subsequent |
|
2749 declaration. For example, in the following C code: |
|
2750 .DS |
|
2751 \f(CWfloat x = 99.99; |
|
2752 |
|
2753 int myfunc() |
|
2754 { |
|
2755 float f = x; |
|
2756 float x = 88.99; |
|
2757 |
|
2758 return 0; |
|
2759 }\fP |
|
2760 .DE |
|
2761 .P |
|
2762 ANSI-C scoping rules require that the value of the variable \f(CWx\fP |
|
2763 assigned to the variable \f(CWf\fP in the initialization sequence |
|
2764 is the value of the global variable \f(CWx\fP, rather than the local \f(CWx\fP, |
|
2765 because the scope of the local variable \f(CWx\fP only starts after the full |
|
2766 declarator for the local \f(CWx\fP. |
|
2767 .R |
|
2768 .LE |
|
2769 .P |
|
2770 .H 2 "Common Block Entries" |
|
2771 .IX common blocks |
|
2772 .IX Fortran |
|
2773 A Fortran common block may be described by a debugging information |
|
2774 entry with the tag |
|
2775 .Cf DW_TAG_common_block . |
|
2776 The common block entry has a |
|
2777 .Cf DW_AT_name |
|
2778 attribute whose value is a null-terminated |
|
2779 string containing the common block name as it appears in the source program. |
|
2780 It also has a |
|
2781 .Cf DW_AT_location |
|
2782 attribute whose value describes the location of the beginning of the |
|
2783 common block. The common block entry owns debugging information |
|
2784 entries describing the variables contained within the common block. |
|
2785 .H 2 "Imported Declaration Entries" |
|
2786 .I |
|
2787 .IX declarations, imported |
|
2788 .IX imports |
|
2789 Some languages support the concept of importing into a given |
|
2790 module declarations made in a different module. |
|
2791 .R |
|
2792 .P |
|
2793 An imported declaration is represented by a debugging information |
|
2794 entry with the tag |
|
2795 .Cf DW_TAG_imported_declaration . |
|
2796 The entry for the imported declaration has a |
|
2797 .Cf DW_AT_name |
|
2798 attribute whose value |
|
2799 is a null-terminated string containing the name of the entity |
|
2800 whose declaration is being imported as it appears in the source |
|
2801 program. The imported declaration entry also has a |
|
2802 .Cf DW_AT_import |
|
2803 attribute, whose value is a reference to the debugging information |
|
2804 entry representing the declaration that is being imported. |
|
2805 .H 2 "Namelist Entries" |
|
2806 .I |
|
2807 .IX namelists |
|
2808 .IX Fortran90 |
|
2809 At least one language, Fortran90, has the concept of a namelist. |
|
2810 A namelist is an ordered list of the names of some set of declared objects. |
|
2811 The namelist object itself may be used as a replacement for the |
|
2812 list of names in various contexts. |
|
2813 .R |
|
2814 .P |
|
2815 A namelist is represented by a debugging information entry with |
|
2816 the tag |
|
2817 .Cf DW_TAG_namelist . |
|
2818 If the namelist itself has a name, the namelist entry has a |
|
2819 .Cf DW_AT_name |
|
2820 attribute, whose value is a null-terminated string containing the namelist's |
|
2821 name as it appears in the source program. |
|
2822 .P |
|
2823 Each name that is part of the namelist is represented by a debugging |
|
2824 information entry with the tag |
|
2825 .Cf DW_TAG_namelist_item . |
|
2826 Each such entry is a child of the namelist entry, and all of |
|
2827 the namelist item entries for a given namelist are ordered as were |
|
2828 the list of names they correspond to in the source program. |
|
2829 .P |
|
2830 Each namelist item entry contains a |
|
2831 .Cf DW_AT_namelist_item |
|
2832 attribute whose value is a reference to the debugging information |
|
2833 entry representing the declaration of the item whose name |
|
2834 appears in the namelist. |
|
2835 .OP |
|
2836 .H 1 "TYPE ENTRIES" |
|
2837 This section presents the debugging information entries |
|
2838 that describe program types: base types, modified types |
|
2839 and user-defined types. |
|
2840 .P |
|
2841 If the scope of the declaration of a named type begins sometime after |
|
2842 .IX scope |
|
2843 .IX declarations, scope |
|
2844 the low pc value |
|
2845 for the scope most closely enclosing the declaration, the |
|
2846 declaration may have a |
|
2847 .Cf DW_AT_start_scope |
|
2848 attribute. The value of this attribute is the offset in bytes of the beginning |
|
2849 of the scope for the declaration from the low pc value of the debugging |
|
2850 information entry that defines its scope. |
|
2851 .H 2 "Base Type Entries" |
|
2852 .I |
|
2853 .IX base types |
|
2854 .IX types, base |
|
2855 A base type is a data type that is not defined in terms of |
|
2856 other data types. Each programming language has a set of |
|
2857 base types that are considered to be built into that language. |
|
2858 .R |
|
2859 .P |
|
2860 A base type is represented by a debugging information entry |
|
2861 with the tag |
|
2862 .Cf DW_TAG_base_type . |
|
2863 A base type entry has a |
|
2864 .Cf DW_AT_name |
|
2865 attribute whose value is a null-terminated |
|
2866 string describing the name of the base type as recognized by |
|
2867 the programming language of the compilation unit containing |
|
2868 the base type entry. |
|
2869 .P |
|
2870 A base type entry also has a |
|
2871 .Cf DW_AT_encoding |
|
2872 attribute describing how the base type is encoded and is |
|
2873 to be interpreted. The value of this attribute is a constant. |
|
2874 The set of values and their meanings for the |
|
2875 .Cf DW_AT_encoding |
|
2876 .nr aX \n(Fg+1 |
|
2877 attribute is given in Figure \n(aX. |
|
2878 .DF |
|
2879 .TS |
|
2880 box center; |
|
2881 l l |
|
2882 lf(CW) l |
|
2883 . |
|
2884 Name Meaning |
|
2885 _ |
|
2886 DW_ATE_address linear machine address |
|
2887 DW_ATE_boolean true or false |
|
2888 DW_ATE_complex_float complex floating-point number |
|
2889 DW_ATE_float floating-point number |
|
2890 DW_ATE_signed signed binary integer |
|
2891 DW_ATE_signed_char signed character |
|
2892 DW_ATE_unsigned unsigned binary integer |
|
2893 DW_ATE_unsigned_char unsigned character |
|
2894 .TE |
|
2895 .FG "Encoding attribute values" |
|
2896 .DE |
|
2897 .P |
|
2898 All encodings assume the representation that is ``normal'' for |
|
2899 the target architecture. |
|
2900 .P |
|
2901 A base type entry has a |
|
2902 .Cf DW_AT_byte_size |
|
2903 attribute, whose value is a constant, |
|
2904 describing the size in bytes of the storage |
|
2905 unit used to represent an object of the given type. |
|
2906 .P |
|
2907 If the value of an object of the given type does not |
|
2908 fully occupy the storage unit described by the byte size attribute, |
|
2909 the base type entry may have a |
|
2910 .Cf DW_AT_bit_size |
|
2911 attribute and a |
|
2912 .Cf DW_AT_bit_offset |
|
2913 attribute, both of whose values are constants. |
|
2914 The bit size attribute describes the actual size in bits used |
|
2915 to represent a value of the given type. The bit offset |
|
2916 attribute describes the offset in bits of the high order |
|
2917 bit of a value of the given type from the high order bit |
|
2918 of the storage unit used to contain that value. |
|
2919 .I |
|
2920 .P |
|
2921 For example, the C type |
|
2922 .Cf int |
|
2923 on a machine that uses 32-bit integers would be |
|
2924 represented by a base type entry with a name |
|
2925 attribute whose value was ``\f(CWint\fP,'' an |
|
2926 encoding attribute whose value was |
|
2927 .Cf DW_ATE_signed |
|
2928 and a byte size attribute whose value was |
|
2929 .Cf 4 . |
|
2930 .R |
|
2931 .H 2 "Type Modifier Entries" |
|
2932 .IX type modifiers |
|
2933 .IX types, modifiers |
|
2934 A base or user-defined type may be modified in different |
|
2935 ways in different languages. A type modifier is represented |
|
2936 in DWARF by a debugging information entry with one of the |
|
2937 .nr aX \n(Fg+1 |
|
2938 tags given in Figure \n(aX. |
|
2939 .DF |
|
2940 .TS |
|
2941 box center; |
|
2942 l l |
|
2943 lf(CW) l |
|
2944 . |
|
2945 Tag Meaning |
|
2946 _ |
|
2947 DW_TAG_const_type C or C++ const qualified type |
|
2948 DW_TAG_packed_type Pascal packed type |
|
2949 DW_TAG_pointer_type The address of the object whose type is being modified |
|
2950 DW_TAG_reference_type A C++ reference to the object whose type is being modified |
|
2951 DW_TAG_volatile_type C or C++ volatile qualified type |
|
2952 .TE |
|
2953 .FG "Type modifier tags" |
|
2954 .DE |
|
2955 .P |
|
2956 .IX types, constant |
|
2957 .IX types, packed |
|
2958 .IX types, volatile |
|
2959 .IX types, pointer |
|
2960 .IX types, reference |
|
2961 Each of the type modifier entries has a |
|
2962 .Cf DW_AT_type |
|
2963 attribute, whose value is a reference to a debugging information |
|
2964 entry describing a base type, a user-defined type or another type |
|
2965 modifier. |
|
2966 .P |
|
2967 A modified type entry describing a pointer or reference type |
|
2968 may have a |
|
2969 .IX addresses, class |
|
2970 .Cf DW_AT_address_class |
|
2971 attribute |
|
2972 to describe how objects having the given pointer or reference type |
|
2973 ought to be dereferenced. |
|
2974 .P |
|
2975 When multiple type modifiers are chained together to modify |
|
2976 a base or user-defined type, they are ordered as if part of |
|
2977 a right-associative expression involving the base or user-defined |
|
2978 type. |
|
2979 .I |
|
2980 .P |
|
2981 As examples of how type modifiers are ordered, take the following |
|
2982 C declarations: |
|
2983 .R |
|
2984 .DS |
|
2985 .ta .5i +.5i +.5i +.5i +.5i +.5i +.5i +.5i |
|
2986 \f(CWconst char * volatile p;\fP |
|
2987 \fIwhich represents a volatile pointer to a constant character.\fP |
|
2988 \fIThis is encoded in DWARF as:\fP |
|
2989 \f(CWDW_TAG_volatile_type \(-> |
|
2990 DW_TAG_pointer_type \(-> |
|
2991 DW_TAG_const_type \(-> |
|
2992 DW_TAG_base_type\fP |
|
2993 |
|
2994 \f(CWvolatile char * const p;\fP |
|
2995 \fIon the other hand, represents a constant pointer |
|
2996 to a volatile character.\fP |
|
2997 \fIThis is encoded as:\fP |
|
2998 \f(CWDW_TAG_const_type \(-> |
|
2999 DW_TAG_pointer_type \(-> |
|
3000 DW_TAG_volatile_type \(-> |
|
3001 DW_TAG_base_type\fP |
|
3002 |
|
3003 .DE |
|
3004 .R |
|
3005 .H 2 "Typedef Entries" |
|
3006 .IX typedefs |
|
3007 Any arbitrary type named via a typedef is represented |
|
3008 by a debugging information entry with the tag |
|
3009 .Cf DW_TAG_typedef . |
|
3010 The typedef entry has a |
|
3011 .Cf DW_AT_name |
|
3012 attribute whose value is a null-terminated |
|
3013 string containing the name of the typedef as it appears in the |
|
3014 source program. |
|
3015 The typedef entry also contains a |
|
3016 .Cf DW_AT_type |
|
3017 attribute. |
|
3018 .P |
|
3019 If the debugging information entry for a typedef represents a |
|
3020 declaration of the type that is not also a definition, |
|
3021 it does not contain a type attribute. |
|
3022 .IX declarations, non-defining |
|
3023 .H 2 "Array Type Entries" |
|
3024 .I |
|
3025 .IX arrays |
|
3026 Many languages share the concept of an ``array,'' which is a |
|
3027 table of components of identical type. |
|
3028 .P |
|
3029 .R |
|
3030 An array type is represented by a debugging information entry with |
|
3031 the tag |
|
3032 .Cf DW_TAG_array_type . |
|
3033 .P |
|
3034 If a name has been given to the array type in the source program, then the |
|
3035 corresponding array type entry has a |
|
3036 .Cf DW_AT_name |
|
3037 attribute whose value is a |
|
3038 null-terminated string containing the array type name as it appears in the |
|
3039 source program. |
|
3040 .P |
|
3041 .IX arrays, ordering |
|
3042 The array type entry describing a multidimensional array may have a |
|
3043 .Cf DW_AT_ordering |
|
3044 attribute whose constant value is interpreted to mean either |
|
3045 row-major or column-major ordering of array elements. |
|
3046 The set of values and their meanings for the ordering attribute |
|
3047 .nr aX \n(Fg+1 |
|
3048 are listed in Figure \n(aX. |
|
3049 If no ordering attribute is present, the default ordering for |
|
3050 the source language (which is indicated by the |
|
3051 .Cf DW_AT_language |
|
3052 attribute of the enclosing compilation unit entry) |
|
3053 is assumed. |
|
3054 .DF |
|
3055 .TS |
|
3056 box center; |
|
3057 lf(CW) |
|
3058 . |
|
3059 DW_ORD_col_major |
|
3060 DW_ORD_row_major |
|
3061 .TE |
|
3062 .FG "Array ordering" |
|
3063 .DE |
|
3064 .P |
|
3065 The ordering attribute may optionally appear on one-dimensional arrays; it |
|
3066 will be ignored. |
|
3067 .P |
|
3068 An array type entry has a |
|
3069 .Cf DW_AT_type |
|
3070 attribute describing the type |
|
3071 of each element of the array. |
|
3072 .P |
|
3073 .IX arrays, stride |
|
3074 If the amount of storage allocated to hold each element of an object of |
|
3075 the given array type is different from the amount of storage that is normally |
|
3076 allocated to hold an individual object of the indicated element type, then |
|
3077 the array type entry has a |
|
3078 .Cf DW_AT_stride_size |
|
3079 attribute, whose constant value |
|
3080 represents the size in bits of each element of the array. |
|
3081 .P |
|
3082 If the size of the entire array can be determined statically at compile |
|
3083 time, the array type entry may have a |
|
3084 .Cf DW_AT_byte_size |
|
3085 attribute, whose constant value represents the total size in bytes of an |
|
3086 instance of the array type. |
|
3087 .P |
|
3088 .I |
|
3089 Note that if the size of the array can be determined statically at |
|
3090 compile time, this value can usually be computed by multiplying |
|
3091 the number of array elements by the size of each element. |
|
3092 .P |
|
3093 .R |
|
3094 Each array dimension is described by a debugging information |
|
3095 entry with either the tag |
|
3096 .IX subranges |
|
3097 .IX enumerations |
|
3098 .IX arrays, dimensions |
|
3099 .Cf DW_TAG_subrange_type |
|
3100 or the tag |
|
3101 .Cf DW_TAG_enumeration_type . |
|
3102 These entries are children of the array type entry and are |
|
3103 ordered to reflect the appearance of the dimensions in the source |
|
3104 program (i.e. leftmost dimension first, next to leftmost second, |
|
3105 and so on). |
|
3106 .P |
|
3107 .I |
|
3108 .IX C %c |
|
3109 In languages, such as ANSI-C, in which there is no concept of a |
|
3110 ``multidimensional array,'' |
|
3111 an array of arrays may be represented by a debugging information entry |
|
3112 for a multidimensional array. |
|
3113 .R |
|
3114 .H 2 "Structure, Union, and Class Type Entries" |
|
3115 .I |
|
3116 The languages C, C++, and Pascal, among others, |
|
3117 allow the programmer to define types that |
|
3118 are collections of related components. In C and C++, these collections are |
|
3119 called ``structures.'' In Pascal, they are called ``records.'' The components |
|
3120 may be of different types. The components are called ``members'' in C and |
|
3121 C++, and ``fields'' in Pascal. |
|
3122 .P |
|
3123 .IX structures |
|
3124 .IX classes |
|
3125 .IX unions |
|
3126 .IX records |
|
3127 .IX C %c |
|
3128 .IX C++ %caa |
|
3129 .IX Pascal |
|
3130 The components of these collections each exist in their own space in |
|
3131 computer memory. The components of a C or C++ ``union'' all coexist in |
|
3132 the same memory. |
|
3133 .P |
|
3134 Pascal and other languages have a ``discriminated union,'' also called a |
|
3135 .IX variants |
|
3136 .IX discriminated unions |
|
3137 ``variant record.'' Here, selection of a number of alternative substructures |
|
3138 (``variants'') is based on the value of a component that is not part of any of |
|
3139 those substructures (the ``discriminant''). |
|
3140 .P |
|
3141 Among the languages discussed in this document, |
|
3142 the ``class'' concept is unique to C++. A class is similar to a structure. |
|
3143 A C++ class or structure may have ``member functions'' which are subroutines |
|
3144 that are within the scope of a class or structure. |
|
3145 .R |
|
3146 .H 3 "General Structure Description" |
|
3147 Structure, union, and class types are represented by |
|
3148 debugging information entries with the tags |
|
3149 .Cf DW_TAG_structure_type , |
|
3150 .Cf DW_TAG_union_type |
|
3151 and |
|
3152 .Cf DW_TAG_class_type , |
|
3153 respectively. |
|
3154 If a name has been given to the structure, union, or class in the source |
|
3155 program, then the corresponding structure type, union type, or class type |
|
3156 entry has a |
|
3157 .Cf DW_AT_name |
|
3158 attribute whose value is a null-terminated string |
|
3159 containing the type name as it appears in the source program. |
|
3160 .P |
|
3161 If the size of an instance of the |
|
3162 structure type, union type, or class type entry can be determined |
|
3163 statically at compile time, the entry has a |
|
3164 .Cf DW_AT_byte_size |
|
3165 attribute whose constant value is the number of bytes required to |
|
3166 hold an instance of the structure, union, or class, and any padding bytes. |
|
3167 .I |
|
3168 .P |
|
3169 .IX structures, incomplete |
|
3170 .IX classes, incomplete |
|
3171 .IX unions, incomplete |
|
3172 For C and C++, an incomplete structure, union or class type is represented |
|
3173 by a structure, union or class entry that does not have |
|
3174 a byte size attribute and that has a |
|
3175 .Cf DW_AT_declaration |
|
3176 attribute. |
|
3177 .R |
|
3178 .P |
|
3179 The members of a structure, union, or class are represented by |
|
3180 debugging information entries that are owned by the corresponding |
|
3181 structure type, union type, or class type entry and appear in the same |
|
3182 order as the corresponding declarations in the source program. |
|
3183 .P |
|
3184 .I |
|
3185 .IX declarations, defining |
|
3186 .IX members, static data |
|
3187 .IX members, data |
|
3188 .IX members, functions |
|
3189 Data member declarations occurring within the declaration of a structure, |
|
3190 union or class type are considered to be ``definitions'' of those members, |
|
3191 with the exception of C++ ``static'' data members, whose definitions |
|
3192 appear outside of the declaration of the enclosing structure, union |
|
3193 or class type. Function member declarations appearing within a structure, |
|
3194 union or class type declaration are definitions only if the body |
|
3195 of the function also appears within the type declaration. |
|
3196 .R |
|
3197 .P |
|
3198 .IX declarations, non-defining |
|
3199 If the definition for a given member of the structure, union or class |
|
3200 does not appear within the body of the declaration, that member |
|
3201 also has a debugging information entry describing its definition. |
|
3202 That entry will have a |
|
3203 .Cf DW_AT_specification |
|
3204 attribute referencing |
|
3205 the debugging entry owned by the |
|
3206 body of the structure, union or class debugging entry and representing |
|
3207 a non-defining declaration of the data or function member. The |
|
3208 referenced entry will |
|
3209 not have information about the location of that member (low and high |
|
3210 pc attributes for function members, location descriptions for data |
|
3211 members) and will have a |
|
3212 .Cf DW_AT_declaration |
|
3213 attribute. |
|
3214 .H 3 "Derived Classes and Structures" |
|
3215 .IX classes, derived |
|
3216 .IX structures, derived |
|
3217 .IX inheritance |
|
3218 The class type or structure type entry that describes a derived class |
|
3219 or structure owns debugging information entries describing each of |
|
3220 the classes or structures it is derived from, ordered as they were |
|
3221 in the source program. Each such entry has the tag |
|
3222 .Cf DW_TAG_inheritance . |
|
3223 .P |
|
3224 An inheritance entry has a |
|
3225 .Cf DW_AT_type |
|
3226 attribute whose |
|
3227 value is a reference to the debugging information entry describing |
|
3228 the structure or class from which the parent structure or class |
|
3229 of the inheritance entry is derived. It also has a |
|
3230 .Cf DW_AT_data_member_location |
|
3231 attribute, whose value is a location description describing |
|
3232 the location of the beginning of |
|
3233 the data members contributed to the entire class by this |
|
3234 subobject relative to the beginning address of the data members of the |
|
3235 entire class. |
|
3236 .P |
|
3237 .IX accessibility |
|
3238 .IX virtuality |
|
3239 .IX classes, virtual base |
|
3240 An inheritance entry may have a |
|
3241 .Cf DW_AT_accessibility |
|
3242 attribute. |
|
3243 If no accessibility attribute is present, |
|
3244 private access is assumed. |
|
3245 If the structure or class referenced by the inheritance entry serves |
|
3246 as a virtual base class, the inheritance entry has a |
|
3247 .Cf DW_AT_virtuality |
|
3248 attribute. |
|
3249 .P |
|
3250 .I |
|
3251 In C++, a derived class may contain access declarations that |
|
3252 change the accessibility of individual class members from |
|
3253 the overall accessibility specified by the inheritance declaration. |
|
3254 A single access declaration may refer to a set of overloaded |
|
3255 names. |
|
3256 .R |
|
3257 .P |
|
3258 If a derived class or structure contains access declarations, |
|
3259 .IX access declarations |
|
3260 .IX C++ %caa |
|
3261 each such declaration may be represented by a debugging information |
|
3262 entry with the tag |
|
3263 .Cf DW_TAG_access_declaration . |
|
3264 Each such entry is a child of the structure or class type entry. |
|
3265 .P |
|
3266 An access declaration entry has a |
|
3267 .Cf DW_AT_name |
|
3268 attribute, whose value |
|
3269 is a null-terminated string representing the name used in the |
|
3270 declaration in the source program, including any class or structure |
|
3271 qualifiers. |
|
3272 .P |
|
3273 An access declaration entry also has a |
|
3274 .Cf DW_AT_accessibility |
|
3275 attribute |
|
3276 describing the declared accessibility of the named entities. |
|
3277 .H 3 "Friends" |
|
3278 .IX friends |
|
3279 .IX classes, friends |
|
3280 Each ``friend'' declared by |
|
3281 a structure, union or class type may be represented by |
|
3282 a debugging information entry that is a child of the structure, |
|
3283 union or class type entry; the friend entry has the tag |
|
3284 .Cf DW_TAG_friend. |
|
3285 .P |
|
3286 A friend entry has a |
|
3287 .Cf DW_AT_friend |
|
3288 attribute, whose value is a reference to the debugging information |
|
3289 entry describing the declaration of the friend. |
|
3290 .H 3 "Structure Data Member Entries" |
|
3291 .IX members, data |
|
3292 A data member (as opposed to a member function) is represented by |
|
3293 a debugging information entry with the tag |
|
3294 .Cf DW_TAG_member . |
|
3295 The member entry for a named member has a |
|
3296 .Cf DW_AT_name |
|
3297 attribute |
|
3298 whose value is a null-terminated string containing the member name |
|
3299 as it appears in the source program. If the member entry describes |
|
3300 a C++ anonymous union, the name attribute is omitted or consists |
|
3301 of a single zero byte. |
|
3302 .IX unions, anonymous |
|
3303 .IX anonymous unions |
|
3304 .P |
|
3305 The structure data member entry has a |
|
3306 .Cf DW_AT_type |
|
3307 attribute |
|
3308 to denote the type of that member. |
|
3309 .P |
|
3310 If the member entry is defined in the structure or class body, it has a |
|
3311 .Cf DW_AT_data_member_location |
|
3312 attribute whose value is a location |
|
3313 description that describes the location of that |
|
3314 member relative to the base address of the structure, union, or class that |
|
3315 most closely encloses the corresponding member declaration. |
|
3316 .I |
|
3317 .P |
|
3318 .IX locations, expressions |
|
3319 .IX locations, descriptions |
|
3320 The addressing expression represented by the location |
|
3321 description for a structure data member expects the base address |
|
3322 of the structure data member to be on the expression stack |
|
3323 before being evaluated. |
|
3324 .P |
|
3325 .IX unions |
|
3326 The location description for a data member of a union may be omitted, |
|
3327 since all data members of a union begin at the same address. |
|
3328 .R |
|
3329 .P |
|
3330 .IX bit fields |
|
3331 .IX members, bit fields |
|
3332 If the member entry describes a bit field, then that entry has the following |
|
3333 attributes: |
|
3334 .AL |
|
3335 .LI |
|
3336 A |
|
3337 .Cf DW_AT_byte_size |
|
3338 attribute whose constant value is the number of bytes that |
|
3339 contain an instance of the bit field and any padding bits. |
|
3340 .P |
|
3341 .I |
|
3342 The byte size attribute may be omitted if the size of the object containing |
|
3343 the bit field can be inferred from the type attribute of the data |
|
3344 member containing the bit field. |
|
3345 .R |
|
3346 .LI |
|
3347 A |
|
3348 .Cf DW_AT_bit_offset |
|
3349 attribute whose constant value is the number of bits |
|
3350 to the left of the leftmost (most significant) bit of the bit field value. |
|
3351 .LI |
|
3352 A |
|
3353 .Cf DW_AT_bit_size |
|
3354 attribute whose constant value is the number of bits occupied |
|
3355 by the bit field value. |
|
3356 .LE |
|
3357 .P |
|
3358 The location description for a bit field calculates the address of |
|
3359 an anonymous object containing the bit field. The address is |
|
3360 relative to the structure, union, or class that |
|
3361 most closely encloses the bit field declaration. The number |
|
3362 of bytes in this anonymous object is the value of the byte |
|
3363 size attribute of the bit field. The offset (in bits) |
|
3364 from the most significant bit of the |
|
3365 anonymous object to the most significant bit of the bit field is the |
|
3366 value of the bit offset attribute. |
|
3367 .I |
|
3368 .P |
|
3369 For example, take one possible representation of the following |
|
3370 structure definition in both big and little endian byte orders: |
|
3371 .DS |
|
3372 \f(CW |
|
3373 struct S { |
|
3374 int j:5; |
|
3375 int k:6; |
|
3376 int m:5; |
|
3377 int n:8; |
|
3378 };\fP |
|
3379 .DE |
|
3380 .P |
|
3381 In both cases, the location descriptions for the debugging information |
|
3382 entries for \f(CWj\fP, \f(CWk\fP, \f(CWm\fP and \f(CWn\fP |
|
3383 describe the address of |
|
3384 the same 32-bit word that contains all three members. |
|
3385 (In the big-endian case, |
|
3386 the location description addresses the most significant byte, in |
|
3387 the little-endian case, the least significant). |
|
3388 The following diagram shows the structure layout and lists the bit |
|
3389 offsets for each case. The offsets |
|
3390 are from the most significant bit of the object addressed by the location |
|
3391 description. |
|
3392 .PS |
|
3393 bitht = .3 |
|
3394 boxht = bitht |
|
3395 bitwid = .11 |
|
3396 nibwid = .75 * bitwid |
|
3397 bytewid = 8 * bitwid |
|
3398 boxwid = bytewid |
|
3399 define nibble X # nibble(len, "label", hi-left, hi-right, lo-left, lo-right, any) |
|
3400 N: box width $1*nibwid $2 $7 |
|
3401 { if $3 >= 0 then % "\s-4\|$3\s0" at N.w + (0,bitht/3) ljust % |
|
3402 } # curly on separate line for pic bug |
|
3403 { if $4 >= 0 then % "\s-4\|$4\s0" at N.e + (0,bitht/3) rjust % |
|
3404 } |
|
3405 { if $5 >= 0 then % "\s-4\|$5\s0" at N.w - (0,bitht/3) ljust % |
|
3406 } |
|
3407 { if $6 >= 0 then % "\s-4$6\|\s0" at N.e - (0,bitht/3) rjust % |
|
3408 } |
|
3409 X |
|
3410 define tbox X # tbox(width,"label", any) |
|
3411 T: box width $1*nibwid ht 1/6 $3 invis |
|
3412 { $2 at T.w ljust |
|
3413 } |
|
3414 X |
|
3415 .PE |
|
3416 .DS |
|
3417 .PS |
|
3418 down |
|
3419 H: tbox(20,"Bit Offsets:") |
|
3420 tbox(20,"\f(CW j:0\fP") |
|
3421 tbox(20,"\f(CW k:5\fP") |
|
3422 tbox(20,"\f(CW m:11\fP") |
|
3423 tbox(20,"\f(CW n:16\fP") |
|
3424 right |
|
3425 H: tbox(32, "Big-Endian", with .w at H.e) |
|
3426 H: nibble(5,"\f(CWj\fP",0,-1,31,-1,with .nw at H.sw) |
|
3427 H: nibble(6,"\f(CWk\fP",-1,-1,26,-1) |
|
3428 H: nibble(5,"\f(CWm\fP",-1,-1,20,-1) |
|
3429 H: nibble(8,"\f(CWn\fP",-1,-1,15,-1) |
|
3430 H: nibble(8,"\fIpad\fP",-1,-1,7,0) |
|
3431 .PE |
|
3432 .DE |
|
3433 .DS |
|
3434 .PS |
|
3435 down |
|
3436 H: tbox(20,"Bit Offsets:") |
|
3437 tbox(20,"\f(CW j:27\fP") |
|
3438 tbox(20,"\f(CW k:21\fP") |
|
3439 tbox(20,"\f(CW m:16\fP") |
|
3440 tbox(20,"\f(CW n:8\fP") |
|
3441 right |
|
3442 H: tbox(32, "Little-Endian", with .w at H.e) |
|
3443 H: nibble(8,"\f2pad\fP",-1,-1,31,-1, with .nw at H.sw) |
|
3444 H: nibble(8,"\f(CWn\fP",-1,-1,23,-1) |
|
3445 H: nibble(5,"\f(CWm\fP",-1,-1,15,-1) |
|
3446 H: nibble(6,"\f(CWk\fP",-1,-1,10,-1) |
|
3447 H: nibble(5,"\f(CWj\fP",-1,0,4,0) |
|
3448 .PE |
|
3449 .DE |
|
3450 .R |
|
3451 .H 3 "Structure Member Function Entries" |
|
3452 .IX subroutines, members |
|
3453 .IX members, functions |
|
3454 .IX members, locations |
|
3455 A member function is represented in the debugging information by a |
|
3456 debugging information entry with the tag |
|
3457 .Cf DW_TAG_subprogram . |
|
3458 The member function entry may contain the same attributes and follows |
|
3459 the same rules as non-member global subroutine entries (see section 3.3). |
|
3460 .P |
|
3461 .IX virtuality |
|
3462 .IX virtual functions |
|
3463 If the member function entry describes a virtual function, then that entry |
|
3464 has a |
|
3465 .Cf DW_AT_virtuality |
|
3466 attribute. |
|
3467 .P |
|
3468 An entry for a virtual function also has a |
|
3469 .Cf DW_AT_vtable_elem_location |
|
3470 attribute whose value contains a location |
|
3471 description yielding the address of the slot for the function |
|
3472 within the virtual function table for the enclosing class or structure. |
|
3473 .P |
|
3474 .IX declarations, defining |
|
3475 If a subroutine entry represents the defining declaration |
|
3476 of a member function and that definition appears outside |
|
3477 of the body of the enclosing class or structure declaration, |
|
3478 the subroutine entry has a |
|
3479 .Cf DW_AT_specification |
|
3480 attribute, whose value is a reference to the debugging information |
|
3481 entry representing the declaration of this function member. The |
|
3482 referenced entry will be a child of some class or structure |
|
3483 type entry. |
|
3484 .P |
|
3485 Subroutine entries containing the |
|
3486 .Cf DW_AT_specification |
|
3487 attribute do not need to duplicate information provided by the |
|
3488 declaration entry referenced by the specification attribute. |
|
3489 In particular, such entries do not need to contain |
|
3490 attributes for the name or return type of the function member whose |
|
3491 definition they represent. |
|
3492 .H 3 "Class Template Instantiations" |
|
3493 .I |
|
3494 .IX C++ %caa |
|
3495 .IX templates |
|
3496 In C++ a class template is a generic |
|
3497 definition of a class type that |
|
3498 is instantiated differently when an instance of the class |
|
3499 is declared or defined. The generic description of the class |
|
3500 may include both parameterized types and parameterized constant |
|
3501 values. DWARF does not represent the generic |
|
3502 template definition, but does represent each instantiation. |
|
3503 .R |
|
3504 .P |
|
3505 A class template instantiation is represented by a debugging information |
|
3506 with the tag |
|
3507 .Cf DW_TAG_class_type . |
|
3508 With four exceptions, |
|
3509 such an entry will contain the same attributes and have the same |
|
3510 types of child entries as would an entry for a class type defined |
|
3511 explicitly using the instantiation types and values. |
|
3512 The exceptions are: |
|
3513 .AL |
|
3514 .LI |
|
3515 Each formal parameterized type declaration appearing in the |
|
3516 template definition is represented by a debugging information entry |
|
3517 with the tag |
|
3518 .Cf DW_TAG_template_type_parameter . |
|
3519 Each such entry has a |
|
3520 .Cf DW_AT_name |
|
3521 attribute, whose value is a null-terminated |
|
3522 string containing the name of the formal type parameter as it |
|
3523 appears in the source program. The template type parameter |
|
3524 entry also has a |
|
3525 .Cf DW_AT_type |
|
3526 attribute describing the actual type by |
|
3527 which the formal is replaced for this instantiation. |
|
3528 .LI |
|
3529 Each formal parameterized value declaration appearing |
|
3530 in the templated definition is represented by a debugging information |
|
3531 entry with the tag |
|
3532 .Cf DW_TAG_template_value_parameter . |
|
3533 Each such entry has a |
|
3534 .Cf DW_AT_name |
|
3535 attribute, whose value is a null-terminated |
|
3536 string containing the name of the formal value parameter as it |
|
3537 appears in the source program. The template value parameter |
|
3538 entry also has a |
|
3539 .Cf DW_AT_type |
|
3540 attribute describing the type of the parameterized |
|
3541 value. Finally, the template value parameter entry has a |
|
3542 .Cf DW_AT_const_value |
|
3543 attribute, whose value is the actual constant value of the value |
|
3544 parameter for this instantiation as represented on the target |
|
3545 architecture. |
|
3546 .LI |
|
3547 .IX compilation units |
|
3548 If the compiler has generated a special compilation unit |
|
3549 to hold the template instantiation and that compilation unit |
|
3550 has a different name |
|
3551 from the compilation unit containing the template definition, |
|
3552 the name attribute for the debugging entry representing |
|
3553 that compilation unit should be empty or omitted. |
|
3554 .LI |
|
3555 .IX declarations, coordinates |
|
3556 If the class type entry representing the template instantiation |
|
3557 or any of its child entries |
|
3558 contain declaration coordinate attributes, those attributes |
|
3559 should refer to the source for the template definition, not |
|
3560 to any source generated artificially by the compiler. |
|
3561 .LE |
|
3562 .H 3 "Variant Entries" |
|
3563 .IX variants |
|
3564 .IX discriminated unions |
|
3565 A variant part of a structure is represented by a debugging |
|
3566 information entry with the tag |
|
3567 .Cf DW_TAG_variant_part |
|
3568 and is owned by the corresponding structure type |
|
3569 entry. |
|
3570 .P |
|
3571 .IX discriminants |
|
3572 If the variant part has a discriminant, the discriminant is represented |
|
3573 by a separate debugging information entry which is a child of |
|
3574 the variant part entry. This entry has the form of a structure data member |
|
3575 entry. |
|
3576 The variant part entry will have a |
|
3577 .Cf DW_AT_discr |
|
3578 attribute whose value is a |
|
3579 reference to the member entry for the discriminant. |
|
3580 .P |
|
3581 If the variant part |
|
3582 does not have a discriminant (tag field), the variant part entry has a |
|
3583 .Cf DW_AT_type |
|
3584 attribute to represent the tag type. |
|
3585 .P |
|
3586 Each variant of a particular variant part is represented by a debugging |
|
3587 information entry with the tag |
|
3588 .Cf DW_TAG_variant |
|
3589 and is a child of the variant part entry. The value that selects a |
|
3590 given variant may be represented in one of three ways. The |
|
3591 variant entry may have a |
|
3592 .Cf DW_AT_discr_value |
|
3593 attribute whose value represents a single case label. |
|
3594 The value of this attribute |
|
3595 is encoded as an LEB128 number. The number is signed if the tag |
|
3596 type for the variant part containing this variant is |
|
3597 a signed type. The number is unsigned if the tag type is an unsigned type. |
|
3598 .P |
|
3599 Alternatively, the variant entry may contain a |
|
3600 .Cf DW_AT_discr_list |
|
3601 attribute, whose value represents a list of discriminant values. |
|
3602 This list is represented by any of the block forms and may contain |
|
3603 a mixture of case labels and label ranges. Each item on the list |
|
3604 is prefixed with a discriminant value descriptor that determines whether |
|
3605 the list item represents a single label or a label range. |
|
3606 A single case label is represented as an LEB128 |
|
3607 number as defined above |
|
3608 for the |
|
3609 .Cf DW_AT_discr_value |
|
3610 attribute. A label range is represented by two LEB128 numbers, |
|
3611 the low value of the range followed by the high value. Both values |
|
3612 follow the rules for signedness just described. |
|
3613 The discriminant value descriptor is a constant that may have |
|
3614 .nr aX \n(Fg+1 |
|
3615 one of the values given in Figure \n(aX. |
|
3616 .DF |
|
3617 .TS |
|
3618 center box; |
|
3619 lf(CW) |
|
3620 . |
|
3621 DW_DSC_label |
|
3622 DW_DSC_range |
|
3623 .TE |
|
3624 .FG "Discriminant descriptor values" |
|
3625 .DE |
|
3626 .P |
|
3627 If a variant entry has neither a |
|
3628 .Cf DW_AT_discr_value |
|
3629 attribute nor a |
|
3630 .Cf DW_AT_discr_list |
|
3631 attribute, or if it has a |
|
3632 .Cf DW_AT_discr_list |
|
3633 attribute with 0 size, the variant is a default variant. |
|
3634 .P |
|
3635 The components selected by a particular variant are represented |
|
3636 by debugging information entries owned by the corresponding variant |
|
3637 entry and appear in the same order as the corresponding declarations in |
|
3638 the source program. |
|
3639 .H 2 "Enumeration Type Entries" |
|
3640 .I |
|
3641 .IX enumerations |
|
3642 An ``enumeration type'' is a scalar that can assume one of a fixed number of |
|
3643 symbolic values. |
|
3644 .P |
|
3645 .R |
|
3646 An enumeration type is represented by a debugging information entry |
|
3647 with the tag |
|
3648 .Cf DW_TAG_enumeration_type . |
|
3649 .P |
|
3650 If a name has been given to the enumeration type in the source program, |
|
3651 then the corresponding enumeration type entry has a |
|
3652 .Cf DW_AT_name |
|
3653 attribute |
|
3654 whose value is a null-terminated string containing the enumeration type |
|
3655 name as it appears in the source program. |
|
3656 These entries also have a |
|
3657 .Cf DW_AT_byte_size |
|
3658 attribute whose |
|
3659 constant value is the number of bytes required to hold an |
|
3660 instance of the enumeration. |
|
3661 .P |
|
3662 Each enumeration literal is represented by a debugging information |
|
3663 entry with the tag |
|
3664 .Cf DW_TAG_enumerator . |
|
3665 Each such entry is a child of the enumeration type entry, and |
|
3666 the enumerator entries appear in the same order as the declarations of |
|
3667 the enumeration literals in the source program. |
|
3668 .P |
|
3669 Each enumerator entry has a |
|
3670 .Cf DW_AT_name |
|
3671 attribute, whose value is |
|
3672 a null-terminated string containing the name of the enumeration |
|
3673 literal as it appears in the source program. Each enumerator |
|
3674 entry also has a |
|
3675 .Cf DW_AT_const_value |
|
3676 attribute, whose value is the actual numeric value of the enumerator |
|
3677 as represented on the target system. |
|
3678 .H 2 "Subroutine Type Entries" |
|
3679 .I |
|
3680 .IX subroutines, types |
|
3681 It is possible in C to declare pointers to subroutines that return a value |
|
3682 of a specific type. In both ANSI C and C++, it is possible to declare |
|
3683 pointers to subroutines that not only return a value of a specific type, |
|
3684 but accept only arguments of specific types. The type of such pointers |
|
3685 would be described with a ``pointer to'' modifier applied to a user-defined |
|
3686 type. |
|
3687 .R |
|
3688 .P |
|
3689 A subroutine type is represented by a debugging information entry |
|
3690 with the tag |
|
3691 .Cf DW_TAG_subroutine_type . |
|
3692 If a name has been given to the subroutine type in the source program, |
|
3693 then the corresponding subroutine type entry has a |
|
3694 .Cf DW_AT_name |
|
3695 attribute |
|
3696 whose value is a null-terminated string containing the subroutine type |
|
3697 name as it appears in the source program. |
|
3698 .P |
|
3699 .IX subroutines, return types |
|
3700 If the subroutine type describes a function that returns a value, then |
|
3701 the subroutine type entry has a |
|
3702 .Cf DW_AT_type |
|
3703 attribute |
|
3704 to denote the type returned by the subroutine. |
|
3705 If the types of the arguments are necessary to describe the subroutine type, |
|
3706 then the corresponding subroutine type entry owns debugging |
|
3707 information entries that describe the arguments. |
|
3708 These debugging information entries appear in the order |
|
3709 that the corresponding argument types appear in the source program. |
|
3710 .P |
|
3711 .I |
|
3712 .IX C %c |
|
3713 .IX subroutines, prototypes |
|
3714 In ANSI-C there is a difference between the types of functions |
|
3715 declared using function prototype style declarations and those |
|
3716 declared using non-prototype declarations. |
|
3717 .P |
|
3718 .R |
|
3719 A subroutine entry |
|
3720 declared with a function prototype style declaration may have a |
|
3721 .Cf DW_AT_prototyped |
|
3722 attribute, whose value is a flag. |
|
3723 .P |
|
3724 Each debugging information entry |
|
3725 owned by a subroutine type entry has a tag whose value has one of |
|
3726 two possible interpretations. |
|
3727 .AL |
|
3728 .LI |
|
3729 .IX parameters, formal |
|
3730 Each debugging information entry that is owned by a subroutine type entry and |
|
3731 that defines a single argument of a specific type has the tag |
|
3732 .Cf DW_TAG_formal_parameter . |
|
3733 .P |
|
3734 The formal parameter entry has a type attribute |
|
3735 to denote the type of the corresponding formal parameter. |
|
3736 .LI |
|
3737 The unspecified parameters of a variable parameter list are represented by a |
|
3738 debugging information entry owned by the subroutine type entry with the tag |
|
3739 .Cf DW_TAG_unspecified_parameters . |
|
3740 .IX parameters, unspecified |
|
3741 .LE |
|
3742 .H 2 "String Type Entries" |
|
3743 .I |
|
3744 .IX string types |
|
3745 .IX Fortran |
|
3746 A ``string'' is a sequence of characters that have specific semantics and |
|
3747 operations that separate them from arrays of characters. |
|
3748 Fortran is one of |
|
3749 the languages that has a string type. |
|
3750 .R |
|
3751 .P |
|
3752 A string type is represented by a debugging information entry |
|
3753 with the tag |
|
3754 .Cf DW_TAG_string_type . |
|
3755 If a name has been given to the string type in the source program, |
|
3756 then the corresponding string type entry has a |
|
3757 .Cf DW_AT_name |
|
3758 attribute |
|
3759 whose value is a null-terminated string containing the string type |
|
3760 name as it appears in the source program. |
|
3761 .P |
|
3762 The string type entry may have a |
|
3763 .Cf DW_AT_string_length |
|
3764 attribute whose value is a location description |
|
3765 yielding the location where the length of the string |
|
3766 is stored in the program. The string type entry may also have a |
|
3767 .Cf DW_AT_byte_size |
|
3768 attribute, whose constant value is the size in bytes of the data |
|
3769 to be retrieved from the location referenced by the string length |
|
3770 attribute. If no byte size attribute is present, the size of the |
|
3771 data to be retrieved is the same as the size of an address on |
|
3772 the target machine. |
|
3773 .P |
|
3774 If no string length attribute is present, the string type entry may have |
|
3775 a |
|
3776 .Cf DW_AT_byte_size |
|
3777 attribute, whose constant value is the length in bytes of |
|
3778 the string. |
|
3779 .H 2 "Set Entries" |
|
3780 .I |
|
3781 Pascal provides the concept of a ``set,'' which represents a group of |
|
3782 values of ordinal type. |
|
3783 .P |
|
3784 .R |
|
3785 .IX Pascal |
|
3786 .IX set types |
|
3787 A set is represented by a debugging information entry |
|
3788 with the tag |
|
3789 .Cf DW_TAG_set_type . |
|
3790 If a name has been given to the set type, |
|
3791 then the set type entry has a |
|
3792 .Cf DW_AT_name |
|
3793 attribute |
|
3794 whose value is a null-terminated string containing the set type name |
|
3795 as it appears in the source program. |
|
3796 .P |
|
3797 The set type entry has a |
|
3798 .Cf DW_AT_type |
|
3799 attribute to denote the type |
|
3800 of an element of the set. |
|
3801 .P |
|
3802 If the amount of storage allocated to hold each element of an object of |
|
3803 the given set type is different from the amount of storage that is normally |
|
3804 allocated to hold an individual object of the indicated element type, then |
|
3805 the set type entry has a |
|
3806 .Cf DW_AT_byte_size |
|
3807 attribute, whose constant value |
|
3808 represents the size in bytes of an instance of the set type. |
|
3809 .H 2 "Subrange Type Entries" |
|
3810 .I |
|
3811 Several languages support the concept of a ``subrange'' type object. |
|
3812 These objects can represent a subset of the values that an |
|
3813 object of the basis type for the subrange can represent. |
|
3814 Subrange type entries may also be used to represent the bounds |
|
3815 of array dimensions. |
|
3816 .R |
|
3817 .P |
|
3818 .IX subranges |
|
3819 A subrange type is represented by a debugging information entry |
|
3820 with the tag |
|
3821 .Cf DW_TAG_subrange_type . |
|
3822 If a name has been given to the subrange type, |
|
3823 then the subrange type entry has a |
|
3824 .Cf DW_AT_name |
|
3825 attribute |
|
3826 whose value is a null-terminated string containing the subrange type name |
|
3827 as it appears in the source program. |
|
3828 .P |
|
3829 The subrange entry may have a |
|
3830 .Cf DW_AT_type |
|
3831 attribute to describe |
|
3832 the type of object of whose values this subrange is a subset. |
|
3833 .P |
|
3834 If the amount of storage allocated to hold each element of an object of |
|
3835 the given subrange type is different from the amount of storage that is normally |
|
3836 allocated to hold an individual object of the indicated element type, then |
|
3837 the subrange type entry has a |
|
3838 .Cf DW_AT_byte_size |
|
3839 attribute, whose constant value |
|
3840 represents the size in bytes of each element of the subrange type. |
|
3841 .P |
|
3842 The subrange entry may have the attributes |
|
3843 .Cf DW_AT_lower_bound |
|
3844 and |
|
3845 .Cf DW_AT_upper_bound |
|
3846 to describe, respectively, the lower and upper bound values |
|
3847 of the subrange. |
|
3848 The |
|
3849 .Cf DW_AT_upper_bound |
|
3850 attribute may be replaced by a |
|
3851 .Cf DW_AT_count |
|
3852 attribute, whose value describes the number of elements in |
|
3853 the subrange rather than the value of the last element. |
|
3854 If a bound or count value is described by a constant |
|
3855 not represented in the program's address space and can |
|
3856 be represented by one of the constant attribute forms, then the value |
|
3857 of the lower or upper bound or count attribute may be one of the constant |
|
3858 types. Otherwise, the value of the lower or upper bound or count |
|
3859 attribute is a reference to a debugging information entry describing |
|
3860 an object containing the bound value or itself describing a constant |
|
3861 value. |
|
3862 .P |
|
3863 If either the lower or upper bound or count values are missing, the |
|
3864 bound value is assumed to be a language-dependent default |
|
3865 constant. |
|
3866 .P |
|
3867 .I |
|
3868 .IX C %c |
|
3869 .IX C++ %caa |
|
3870 .IX Fortran |
|
3871 The default lower bound value for C or C++ is 0. For Fortran, |
|
3872 it is 1. No other default values are currently defined by DWARF. |
|
3873 .R |
|
3874 .P |
|
3875 If the subrange entry has no type attribute describing the basis |
|
3876 type, the basis type is assumed to be the same as the object |
|
3877 described by the lower bound attribute (if it references an object). |
|
3878 If there is no lower bound attribute, or it does not reference |
|
3879 an object, the basis type is the type of the upper bound or count |
|
3880 attribute |
|
3881 (if it references an object). If there is no upper bound or count attribute |
|
3882 or it does not reference an object, the type is assumed to be |
|
3883 the same type, in the source language |
|
3884 of the compilation unit containing the subrange entry, |
|
3885 as a signed integer with the same size |
|
3886 as an address on the target machine. |
|
3887 .H 2 "Pointer to Member Type Entries" |
|
3888 .I |
|
3889 In C++, a pointer to a data or function member of a class or |
|
3890 structure is a unique type. |
|
3891 .P |
|
3892 .R |
|
3893 .IX C++ %caa |
|
3894 .IX members, pointers to |
|
3895 .IX pointers to members |
|
3896 A debugging information entry |
|
3897 representing the type of an object that is a pointer to a structure |
|
3898 or class member has the tag |
|
3899 .Cf DW_TAG_ptr_to_member_type . |
|
3900 .P |
|
3901 If the pointer to member type has a name, the pointer to member entry |
|
3902 has a |
|
3903 .Cf DW_AT_name |
|
3904 attribute, whose value is a null-terminated string |
|
3905 containing the type name as it appears in the source program. |
|
3906 .P |
|
3907 The pointer to member entry has a |
|
3908 .Cf DW_AT_type |
|
3909 attribute to describe |
|
3910 the type of the class or structure member to which objects |
|
3911 of this type may point. |
|
3912 .P |
|
3913 The pointer to member entry also has a |
|
3914 .Cf DW_AT_containing_type |
|
3915 attribute, whose value is a reference to a debugging information |
|
3916 entry for the class or structure to whose members objects of |
|
3917 this type may point. |
|
3918 .P |
|
3919 Finally, the pointer to member entry has a |
|
3920 .Cf DW_AT_use_location |
|
3921 attribute whose value is a location description that computes |
|
3922 the address of the member of the class or structure to which the |
|
3923 pointer to member type entry can point. |
|
3924 .P |
|
3925 .I |
|
3926 The method used to find the address of a given member |
|
3927 of a class or structure is common to any instance of that |
|
3928 class or structure and to any instance of the pointer or |
|
3929 member type. The method is thus associated |
|
3930 with the type entry, rather than with each instance of the type. |
|
3931 .P |
|
3932 The |
|
3933 .Cf DW_AT_use_location |
|
3934 expression, however, cannot be used on its own, but must |
|
3935 be used in conjunction with the location expressions for |
|
3936 a particular object of the given pointer to member type |
|
3937 and for a particular structure or class instance. The |
|
3938 .Cf DW_AT_use_location |
|
3939 attribute expects two values to be pushed onto the location expression |
|
3940 stack before the |
|
3941 .Cf DW_AT_use_location |
|
3942 expression is evaluated. The first value pushed should be |
|
3943 the value of the pointer to member object itself. |
|
3944 The second value pushed should be the base address of the entire |
|
3945 structure or union instance containing the member whose |
|
3946 address is being calculated. |
|
3947 .P |
|
3948 So, for an expression like |
|
3949 .DS |
|
3950 \f(CWobject.*mbr_ptr\fP |
|
3951 .DE |
|
3952 where \f(CWmbr_ptr\fP has some pointer to member type, |
|
3953 a debugger should: |
|
3954 .AL |
|
3955 .LI |
|
3956 Push the value of |
|
3957 .Cf mbr_ptr |
|
3958 onto the location expression stack. |
|
3959 .LI |
|
3960 Push the base address of |
|
3961 .Cf object |
|
3962 onto the location expression stack. |
|
3963 .LI |
|
3964 Evaluate the |
|
3965 .Cf DW_AT_use_location |
|
3966 expression for the type of |
|
3967 .Cf mbr_ptr . |
|
3968 .LE |
|
3969 .R |
|
3970 .H 2 "File Type Entries" |
|
3971 .I |
|
3972 Some languages, such as Pascal, provide a first class data type |
|
3973 to represent files. |
|
3974 .R |
|
3975 .P |
|
3976 .IX Pascal |
|
3977 .IX file types |
|
3978 A file type is represented by a debugging information entry |
|
3979 with the tag |
|
3980 .Cf DW_TAG_file_type. |
|
3981 If the file type has a name, the file type entry |
|
3982 has a |
|
3983 .Cf DW_AT_name |
|
3984 attribute, whose value is a null-terminated string |
|
3985 containing the type name as it appears in the source program. |
|
3986 .P |
|
3987 The file type entry has a |
|
3988 .Cf DW_AT_type |
|
3989 attribute describing the type |
|
3990 of the objects contained in the file. |
|
3991 .P |
|
3992 The file type entry also has a |
|
3993 .Cf DW_AT_byte_size |
|
3994 attribute, whose value |
|
3995 is a constant representing the size in bytes of an instance |
|
3996 of this file type. |
|
3997 .OP |
|
3998 .H 1 "OTHER DEBUGGING INFORMATION" |
|
3999 This section describes debugging information that |
|
4000 is not represented in the form of debugging information |
|
4001 entries and is not contained within the |
|
4002 .Cf .debug_info |
|
4003 section. |
|
4004 .H 2 "Accelerated Access" |
|
4005 .I |
|
4006 .IX accelerated access |
|
4007 A debugger frequently needs to find the debugging information for |
|
4008 a program object defined outside of the compilation unit |
|
4009 where the debugged program is currently stopped. Sometimes |
|
4010 it will know only the name of the object; sometimes only the address. |
|
4011 To find the debugging information |
|
4012 associated with a global object by name, using the DWARF debugging information |
|
4013 entries alone, a debugger would need |
|
4014 to run through all entries at the highest scope within each |
|
4015 compilation unit. For lookup by address, for a subroutine, |
|
4016 a debugger can use the low and high pc attributes |
|
4017 of the compilation unit entries to quickly narrow down the search, |
|
4018 but these attributes only cover |
|
4019 the range of addresses for the text associated with a compilation |
|
4020 unit entry. To find the debugging information associated with a |
|
4021 data object, an exhaustive search would be needed. |
|
4022 Furthermore, any search through debugging information entries for |
|
4023 different compilation units within a large program |
|
4024 would potentially require the access of many memory pages, |
|
4025 probably hurting debugger performance. |
|
4026 .R |
|
4027 .P |
|
4028 To make lookups of program objects by name or by address faster, |
|
4029 a producer of DWARF information may provide two different types |
|
4030 of tables containing information about the debugging information |
|
4031 entries owned by a particular compilation unit entry in a more condensed |
|
4032 format. |
|
4033 .H 3 "Lookup by Name" |
|
4034 .IX lookup, by name |
|
4035 For lookup by name, a table is maintained in a separate |
|
4036 object file section called |
|
4037 .Cf .debug_pubnames . |
|
4038 .IX \f(CW.debug_pubnames\fP %debugap |
|
4039 The table consists of sets of variable length entries, each |
|
4040 set describing the names of global objects whose definitions |
|
4041 or declarations are represented by debugging information entries |
|
4042 owned by a single compilation unit. Each set begins |
|
4043 with a header containing four values: the total length of the entries |
|
4044 for that set, not including the length field itself, a version number, |
|
4045 the offset from the beginning of the |
|
4046 .Cf .debug_info |
|
4047 .IX \f(CW.debug_info\fP %debugai |
|
4048 section of the compilation unit entry referenced by the set and |
|
4049 the size in bytes of the contents of the |
|
4050 .Cf .debug_info |
|
4051 section generated to represent that compilation unit. This |
|
4052 header is followed by a variable number of offset/name pairs. |
|
4053 Each pair consists of the offset from the beginning of the compilation |
|
4054 unit entry corresponding to the current set to the |
|
4055 debugging information entry for |
|
4056 the given object, followed by a null-terminated character |
|
4057 string representing the name of the object as given by |
|
4058 the |
|
4059 .Cf DW_AT_name |
|
4060 attribute of the referenced debugging entry. |
|
4061 Each set of names is terminated by zero. |
|
4062 .P |
|
4063 .IX C++ %caa |
|
4064 .IX members, static data |
|
4065 In the case of the name of a static data member or function member |
|
4066 of a C++ structure, class or union, the name presented |
|
4067 in the |
|
4068 .Cf .debug_pubnames |
|
4069 section is not the simple name given by the |
|
4070 .Cf DW_AT_name |
|
4071 attribute of the referenced debugging entry, but rather |
|
4072 the fully class qualified name of the data or function member. |
|
4073 .IX identifiers, names |
|
4074 .H 3 "Lookup by Address" |
|
4075 .IX lookup, by address |
|
4076 For lookup by address, a table is maintained in a separate |
|
4077 object file section called |
|
4078 .Cf .debug_aranges . |
|
4079 .IX \f(CW.debug_aranges\fP %debugaar |
|
4080 The table consists of sets of variable length entries, each |
|
4081 set describing the portion of the program's address space that |
|
4082 is covered by a single compilation unit. Each set begins |
|
4083 with a header containing five values: |
|
4084 .AL |
|
4085 .LI |
|
4086 The total length of the entries |
|
4087 for that set, not including the length field itself. |
|
4088 .LI |
|
4089 A version number. |
|
4090 .LI |
|
4091 The offset from the beginning of the |
|
4092 .Cf .debug_info |
|
4093 .IX \f(CW.debug_info\fP %debugai |
|
4094 section of the compilation unit entry referenced by the set. |
|
4095 .LI |
|
4096 The size in bytes of an address on the target architecture. For |
|
4097 segmented addressing, this is the size of the offset portion of the |
|
4098 .IX addresses, offset portion |
|
4099 .IX addresses, size of |
|
4100 address. |
|
4101 .LI |
|
4102 .IX address space, segmented |
|
4103 .IX segmented address space |
|
4104 The size in bytes of a segment descriptor on the target architecture. |
|
4105 If the target system uses a flat address space, this value is 0. |
|
4106 .LE |
|
4107 .P |
|
4108 This |
|
4109 header is followed by a variable number of address |
|
4110 range descriptors. Each descriptor is a pair consisting of |
|
4111 the beginning address |
|
4112 of a range of text or data covered by some entry owned |
|
4113 by the corresponding compilation unit entry, followed by the length |
|
4114 of that range. A particular set is terminated by an entry consisting |
|
4115 of two zeroes. By scanning the table, a debugger can quickly |
|
4116 decide which compilation unit to look in to find the debugging information |
|
4117 for an object that has a given address. |
|
4118 .H 2 "Line Number Information" |
|
4119 .I |
|
4120 .IX line number information |
|
4121 A source-level debugger will need to know how to associate statements in |
|
4122 the source files with the corresponding machine instruction addresses in |
|
4123 the executable object or the shared objects used by that executable |
|
4124 object. Such an association would make it possible for the debugger user |
|
4125 to specify machine instruction addresses in terms of source statements. |
|
4126 This would be done by specifying the line number and the source file |
|
4127 containing the statement. The debugger can also use this information to |
|
4128 display locations in terms of the source files and to single step from |
|
4129 statement to statement. |
|
4130 .R |
|
4131 .P |
|
4132 As mentioned in section 3.1, above, |
|
4133 the line number information generated for a compilation unit |
|
4134 is represented in the \f(CW.debug_line\fP section of an object file and is |
|
4135 referenced by a corresponding compilation unit debugging information entry |
|
4136 in the \f(CW.debug_info\fP section. |
|
4137 .IX \f(CW.debug_info\fP %debugai |
|
4138 .IX \f(CW.debug_line\fP %debugali |
|
4139 .I |
|
4140 .P |
|
4141 If space were not a consideration, the information |
|
4142 provided in the |
|
4143 .Cf .debug_line |
|
4144 section could be represented as a large matrix, |
|
4145 with one row for each instruction in the emitted |
|
4146 object code. The matrix would have columns for: |
|
4147 .DL |
|
4148 .LI |
|
4149 the source file name |
|
4150 .LI |
|
4151 the source line number |
|
4152 .LI |
|
4153 the source column number |
|
4154 .LI |
|
4155 whether this instruction is the beginning of a source statement |
|
4156 .LI |
|
4157 whether this instruction is the beginning of a basic block. |
|
4158 .LE |
|
4159 .P |
|
4160 Such a matrix, however, would be impractically large. We shrink it with |
|
4161 two techniques. First, we delete from the matrix each row whose file, |
|
4162 line and source column information is identical with that of its predecessors. |
|
4163 Second, we design a byte-coded language for a state machine and store a stream |
|
4164 of bytes in the object file instead of the matrix. This language can be |
|
4165 much more compact than the matrix. When a consumer of the statement |
|
4166 information executes, it must ``run'' the state machine to generate |
|
4167 the matrix for each compilation unit it is interested in. The concept |
|
4168 of an encoded matrix also leaves room for expansion. In the future, |
|
4169 columns can be added to the matrix to encode other things that are |
|
4170 related to individual instruction addresses. |
|
4171 .R |
|
4172 .H 3 "Definitions" |
|
4173 .IX line number information, definitions |
|
4174 The following terms are used in the description of the line number information |
|
4175 format: |
|
4176 .VL 20 |
|
4177 .LI "state machine" |
|
4178 The hypothetical machine used by a consumer of the line number information |
|
4179 to expand the byte-coded instruction stream into a |
|
4180 matrix of line number information. |
|
4181 .LI "statement program" |
|
4182 A series of byte-coded line number information instructions representing one |
|
4183 compilation unit. |
|
4184 .LI "basic block" |
|
4185 A sequence of instructions that is entered only at the first instruction |
|
4186 and exited only at the last instruction. We define a procedure invocation |
|
4187 to be an exit from a basic block. |
|
4188 .LI "sequence" |
|
4189 A series of contiguous target machine instructions. One compilation |
|
4190 unit may emit multiple sequences (that is, not all instructions within |
|
4191 a compilation unit are assumed to be contiguous). |
|
4192 .LI "sbyte" |
|
4193 Small signed integer. |
|
4194 .LI "ubyte" |
|
4195 Small unsigned integer. |
|
4196 .LI "uhalf" |
|
4197 Medium unsigned integer. |
|
4198 .LI "sword" |
|
4199 Large signed integer. |
|
4200 .LI "uword" |
|
4201 Large unsigned integer. |
|
4202 .LI "LEB128" |
|
4203 .IX LEB128 |
|
4204 Variable length signed and unsigned data. See section 7.6. |
|
4205 .LE |
|
4206 .H 3 "State Machine Registers" |
|
4207 .IX line number information, state machine registers |
|
4208 The statement information state machine has the following registers: |
|
4209 .VL 20 |
|
4210 .LI "\f(CWaddress\fP" |
|
4211 The program-counter value corresponding to a machine instruction generated |
|
4212 by the compiler. |
|
4213 .LI "\f(CWfile\fP" |
|
4214 An unsigned integer indicating the identity of the source file corresponding |
|
4215 to a machine instruction. |
|
4216 .IX source, files |
|
4217 .LI "\f(CWline\fP" |
|
4218 .IX source, lines |
|
4219 An unsigned integer indicating a source line number. Lines are numbered |
|
4220 beginning at 1. The compiler may emit the value 0 in cases where an |
|
4221 instruction cannot be attributed to any source line. |
|
4222 .LI "\f(CWcolumn\fP" |
|
4223 .IX source, columns |
|
4224 An unsigned integer indicating a column number within a source line. |
|
4225 Columns are numbered beginning at 1. The value 0 is reserved to indicate |
|
4226 that a statement begins at the ``left edge'' of the line. |
|
4227 .LI "\f(CWis_stmt\fP" |
|
4228 A boolean indicating that the current instruction is the beginning of a |
|
4229 statement. |
|
4230 .LI "\f(CWbasic_block\fP" |
|
4231 A boolean indicating that the current instruction is the beginning of |
|
4232 a basic block. |
|
4233 .LI "\f(CWend_sequence\fP" |
|
4234 A boolean indicating that the current address is that of the first |
|
4235 byte after the end of a sequence of target machine instructions. |
|
4236 .LE |
|
4237 .P |
|
4238 At the beginning of each sequence within a statement program, the |
|
4239 state of the registers is: |
|
4240 .DS |
|
4241 .TS |
|
4242 ; |
|
4243 lf(CW) l. |
|
4244 address 0 |
|
4245 file 1 |
|
4246 line 1 |
|
4247 column 0 |
|
4248 is_stmt determined by \f(CWdefault_is_stmt\fP in the statement program prologue |
|
4249 basic_block ``false'' |
|
4250 end_sequence ``false'' |
|
4251 .TE |
|
4252 .DE |
|
4253 .H 3 "Statement Program Instructions" |
|
4254 The state machine instructions in a statement program belong to one |
|
4255 of three categories: |
|
4256 .VL 20 |
|
4257 .LI "special opcodes" |
|
4258 .IX line number information, special opcodes |
|
4259 These have a ubyte opcode field and no arguments. |
|
4260 Most of the instructions in a statement program are special opcodes. |
|
4261 .LI "standard opcodes" |
|
4262 .IX line number information, standard opcodes |
|
4263 These have a ubyte opcode field which may be followed by zero or more |
|
4264 LEB128 arguments (except for |
|
4265 .Cf DW_LNS_fixed_advance_pc , |
|
4266 see below). |
|
4267 The opcode implies the number of arguments and their |
|
4268 meanings, but the statement program prologue also specifies the number |
|
4269 of arguments for each standard opcode. |
|
4270 .LI "extended opcodes" |
|
4271 .IX line number information, extended opcodes |
|
4272 These have a multiple byte format. The first byte is zero; |
|
4273 the next bytes are an unsigned LEB128 integer giving the number of bytes |
|
4274 in the instruction itself (does not include the first zero byte or the size). |
|
4275 The remaining bytes are the instruction itself. |
|
4276 .LE |
|
4277 .H 3 "The Statement Program Prologue" |
|
4278 .IX line number information, prologue |
|
4279 The optimal encoding of line number information depends to a certain |
|
4280 degree upon the architecture of the target machine. The statement program |
|
4281 prologue provides information used by consumers in decoding the statement |
|
4282 program instructions for a particular compilation unit and also provides |
|
4283 information used throughout the rest of the statement program. The statement |
|
4284 program for each compilation unit begins with a prologue containing the |
|
4285 following fields in order: |
|
4286 .AL |
|
4287 .LI |
|
4288 .Cf total_length |
|
4289 (uword) |
|
4290 .br |
|
4291 The size in bytes of the statement information for this compilation unit |
|
4292 (not including the |
|
4293 .Cf total_length |
|
4294 field itself). |
|
4295 .LI |
|
4296 .Cf version |
|
4297 (uhalf) |
|
4298 .br |
|
4299 Version identifier for the statement information format. |
|
4300 .LI |
|
4301 .Cf prologue_length |
|
4302 (uword) |
|
4303 .br |
|
4304 The number of bytes following the |
|
4305 .Cf prologue_length |
|
4306 field to the beginning of the first byte of the statement program itself. |
|
4307 .LI |
|
4308 .Cf minimum_instruction_length |
|
4309 (ubyte) |
|
4310 .br |
|
4311 The size in bytes of the smallest target machine instruction. Statement |
|
4312 program opcodes that alter the |
|
4313 .Cf address |
|
4314 register first multiply their operands by this value. |
|
4315 .LI |
|
4316 .Cf default_is_stmt |
|
4317 (ubyte) |
|
4318 .br |
|
4319 The initial value of the |
|
4320 .Cf is_stmt |
|
4321 register. |
|
4322 .P |
|
4323 .I |
|
4324 A simple code generator |
|
4325 that emits machine instructions in the order implied by the source program |
|
4326 would set this to ``true,'' and every entry in the matrix would represent |
|
4327 a statement boundary. A pipeline scheduling code generator would set |
|
4328 this to ``false'' and emit a specific statement program opcode for each |
|
4329 instruction that represented a statement boundary. |
|
4330 .R |
|
4331 .LI |
|
4332 .Cf line_base |
|
4333 (sbyte) |
|
4334 .br |
|
4335 This parameter affects the meaning of the special opcodes. See below. |
|
4336 .LI |
|
4337 .Cf line_range |
|
4338 (ubyte) |
|
4339 .br |
|
4340 This parameter affects the meaning of the special opcodes. See below. |
|
4341 .LI |
|
4342 .Cf opcode_base |
|
4343 (ubyte) |
|
4344 .br |
|
4345 The number assigned to the first special opcode. |
|
4346 .LI |
|
4347 .Cf standard_opcode_lengths |
|
4348 (array of ubyte) |
|
4349 .br |
|
4350 This array specifies the number of LEB128 operands for each of |
|
4351 the standard opcodes. The first element of the array corresponds |
|
4352 to the opcode whose value is 1, and the last element corresponds |
|
4353 to the opcode whose value is |
|
4354 .Cf "opcode_base - 1" . |
|
4355 By increasing |
|
4356 .Cf opcode_base , |
|
4357 and adding elements to this array, new standard opcodes |
|
4358 can be added, while allowing consumers who do not know about these |
|
4359 new opcodes to be able to skip them. |
|
4360 .LI |
|
4361 .Cf include_directories |
|
4362 (sequence of path names) |
|
4363 .br |
|
4364 The sequence contains an entry for each path that was searched |
|
4365 for included source files in this compilation. (The paths include |
|
4366 those directories specified explicitly by the user for the compiler |
|
4367 to search and those the compiler searches without explicit direction). |
|
4368 Each path entry is either a full |
|
4369 path name or is relative to the current directory of the compilation. |
|
4370 The current directory of the compilation is understood to be the first entry |
|
4371 and is not explicitly represented. |
|
4372 Each entry is a null-terminated |
|
4373 string containing a full path name. The last entry is followed by |
|
4374 a single null byte. |
|
4375 .LI |
|
4376 .Cf file_names |
|
4377 (sequence of file entries) |
|
4378 .br |
|
4379 .IX source, files |
|
4380 The sequence contains an entry for each source file that contributed |
|
4381 to the statement information for this compilation unit or is |
|
4382 used in other contexts, such as in a declaration coordinate |
|
4383 or a macro file inclusion. Each entry |
|
4384 has a null-terminated string containing the file name, |
|
4385 an unsigned LEB128 number representing the directory index of the |
|
4386 directory in which the file was found, |
|
4387 an unsigned LEB128 number representing the time of last modification for |
|
4388 the file and an unsigned LEB128 number representing the length in |
|
4389 bytes of the file. A compiler may choose to emit LEB128(0) for the |
|
4390 time and length fields to indicate that this information is not |
|
4391 available. The last entry is followed by a single null byte. |
|
4392 .P |
|
4393 The directory index represents an entry in the |
|
4394 .Cf include_directories |
|
4395 section. The index is LEB128(0) if the file was found in |
|
4396 the current directory of the compilation, LEB128(1) if it was |
|
4397 found in the first directory in the |
|
4398 .Cf include_directories |
|
4399 section, and so on. The directory index is ignored for file names |
|
4400 that represent full path names. |
|
4401 .P |
|
4402 The statement program assigns numbers to each of the file entries |
|
4403 in order, beginning with 1, and uses those numbers instead of file |
|
4404 names in the |
|
4405 .Cf file |
|
4406 register. |
|
4407 .P |
|
4408 A compiler may generate a single null byte for the file names field |
|
4409 and define file names using the extended opcode |
|
4410 .Cf DEFINE_FILE . |
|
4411 .LE |
|
4412 .H 3 "The Statement Program" |
|
4413 As stated before, the goal of a statement program is to build a |
|
4414 matrix representing |
|
4415 one compilation unit, which may have produced multiple sequences of |
|
4416 target-machine instructions. Within a sequence, addresses may only increase. |
|
4417 (Line numbers may decrease in cases of pipeline scheduling.) |
|
4418 .H 4 "Special Opcodes" |
|
4419 .IX line number information, special opcodes |
|
4420 Each 1-byte special opcode has the following effect on the state machine: |
|
4421 .AL |
|
4422 .LI |
|
4423 Add a signed integer to the |
|
4424 .Cf line |
|
4425 register. |
|
4426 .LI |
|
4427 Multiply an unsigned integer by the |
|
4428 .Cf minimum_instruction_length |
|
4429 field of the statement program prologue and |
|
4430 add the result to the |
|
4431 .Cf address |
|
4432 register. |
|
4433 .LI |
|
4434 Append a row to the matrix using the current values of the state machine |
|
4435 registers. |
|
4436 .LI |
|
4437 Set the |
|
4438 .Cf basic_block |
|
4439 register to ``false.'' |
|
4440 .LE |
|
4441 .P |
|
4442 All of the special opcodes do those same four things; |
|
4443 they differ from one another |
|
4444 only in what values they add to the |
|
4445 .Cf line |
|
4446 and |
|
4447 .Cf address |
|
4448 registers. |
|
4449 .P |
|
4450 .I |
|
4451 Instead of assigning a fixed meaning to each special opcode, the statement |
|
4452 program uses several |
|
4453 parameters in the prologue to configure the instruction set. There are two |
|
4454 reasons for this. |
|
4455 First, although the opcode space available for special opcodes now |
|
4456 ranges from 10 through 255, the lower bound may increase if one adds new |
|
4457 standard opcodes. Thus, the |
|
4458 .Cf opcode_base |
|
4459 field of the statement program |
|
4460 prologue gives the value of the first special opcode. |
|
4461 Second, the best choice of special-opcode meanings depends on the target |
|
4462 architecture. For example, for a RISC machine where the compiler-generated code |
|
4463 interleaves instructions from different lines to schedule the pipeline, |
|
4464 it is important to be able to add a negative value to the |
|
4465 .Cf line |
|
4466 register |
|
4467 to express the fact that a later instruction may have been emitted for an |
|
4468 earlier source line. For a machine where pipeline scheduling never occurs, |
|
4469 it is advantageous to trade away the ability to decrease the |
|
4470 .Cf line |
|
4471 register |
|
4472 (a standard opcode provides an alternate way to decrease the line number) in |
|
4473 return for the ability to add larger positive values to the |
|
4474 .Cf address |
|
4475 register. To permit this variety of strategies, the statement program prologue |
|
4476 defines a |
|
4477 .Cf line_base |
|
4478 field that specifies the minimum value which a special opcode can add |
|
4479 to the |
|
4480 .Cf line |
|
4481 register and a |
|
4482 .Cf line_range |
|
4483 field that defines the range of |
|
4484 values it can add to the |
|
4485 .Cf line |
|
4486 register. |
|
4487 .R |
|
4488 .P |
|
4489 A special opcode value is chosen based on the amount that needs to |
|
4490 be added to the |
|
4491 .Cf line |
|
4492 and |
|
4493 .Cf address |
|
4494 registers. The maximum line increment |
|
4495 for a special opcode is the value of the |
|
4496 .Cf line_base |
|
4497 field in the |
|
4498 prologue, plus the value of the |
|
4499 .Cf line_range |
|
4500 field, minus 1 |
|
4501 (\f(CWline base + line range - 1\fP). If the desired line increment |
|
4502 is greater than the maximum line increment, a standard opcode |
|
4503 must be used instead of a special opcode. |
|
4504 The ``address advance'' is calculated by dividing the desired address |
|
4505 increment by the |
|
4506 .Cf minimum_instruction_length |
|
4507 field from the |
|
4508 prologue. The special opcode is then calculated using the following |
|
4509 formula: |
|
4510 .br |
|
4511 \f(CWopcode = (desired line increment - line_base) + |
|
4512 .br |
|
4513 (line_range * address advance) + opcode_base\fP |
|
4514 .br |
|
4515 If the resulting opcode is greater than 255, a standard opcode |
|
4516 must be used instead. |
|
4517 .P |
|
4518 To decode a special opcode, subtract the |
|
4519 .Cf opcode_base |
|
4520 from |
|
4521 the opcode itself. The amount to increment the |
|
4522 .Cf address |
|
4523 register is |
|
4524 the adjusted opcode divided by the |
|
4525 .Cf line_range . |
|
4526 The amount to |
|
4527 increment the |
|
4528 .Cf line |
|
4529 register is the |
|
4530 .Cf line_base |
|
4531 plus the result |
|
4532 of the adjusted opcode modulo the |
|
4533 .Cf line_range . |
|
4534 That is, |
|
4535 .br |
|
4536 \f(CWline increment = line_base + (adjusted opcode % line_range)\fP |
|
4537 .br |
|
4538 .P |
|
4539 .I |
|
4540 As an example, suppose that the |
|
4541 .Cf opcode_base |
|
4542 is 16, |
|
4543 .Cf line_base |
|
4544 is -1 and |
|
4545 .Cf line_range |
|
4546 is 4. |
|
4547 This means that we can use a special opcode whenever two successive |
|
4548 rows in the matrix have source line numbers differing by any value within |
|
4549 the range [-1, 2] (and, because of the limited number of opcodes available, |
|
4550 when the difference between addresses is within the range [0, 59]). |
|
4551 .P |
|
4552 The opcode mapping would be: |
|
4553 .R |
|
4554 .DS |
|
4555 .TS |
|
4556 box center; |
|
4557 l l l |
|
4558 nf(CW) nf(CW) nf(CW) |
|
4559 . |
|
4560 Opcode Line advance Address advance |
|
4561 _ |
|
4562 16 -1 0 |
|
4563 17 0 0 |
|
4564 18 1 0 |
|
4565 19 2 0 |
|
4566 20 -1 1 |
|
4567 21 0 1 |
|
4568 22 1 1 |
|
4569 23 2 1 |
|
4570 ... ... ... |
|
4571 253 0 59 |
|
4572 254 1 59 |
|
4573 255 2 59 |
|
4574 .TE |
|
4575 .DE |
|
4576 .P |
|
4577 There is no requirement that the expression \f(CW255 - line_base + 1\fP be an |
|
4578 integral multiple of |
|
4579 .Cf line_range . |
|
4580 .H 4 "Standard Opcodes" |
|
4581 .IX line number information, standard opcodes |
|
4582 There are currently 9 standard ubyte opcodes. In the future |
|
4583 additional ubyte opcodes may be defined by setting the |
|
4584 .Cf opcode_base |
|
4585 field in the statement program |
|
4586 prologue to a value greater than 10. |
|
4587 .AL |
|
4588 .LI |
|
4589 .Cf DW_LNS_copy |
|
4590 .br |
|
4591 Takes no arguments. Append a row to the matrix using the current values of |
|
4592 the state-machine registers. Then set the |
|
4593 .Cf basic_block |
|
4594 register to ``false.'' |
|
4595 .LI |
|
4596 .Cf DW_LNS_advance_pc |
|
4597 .br |
|
4598 Takes a single unsigned LEB128 operand, |
|
4599 multiplies it by the |
|
4600 .Cf minimum_instruction_length |
|
4601 field of the prologue, and adds the result to the |
|
4602 .Cf address |
|
4603 register of the state machine. |
|
4604 .LI |
|
4605 .Cf DW_LNS_advance_line |
|
4606 .br |
|
4607 Takes a single signed LEB128 operand and adds |
|
4608 that value to the |
|
4609 .Cf line |
|
4610 register of the state machine. |
|
4611 .LI |
|
4612 .Cf DW_LNS_set_file |
|
4613 .br |
|
4614 Takes a single unsigned LEB128 operand and stores |
|
4615 it in the |
|
4616 .Cf file |
|
4617 register of the state machine. |
|
4618 .LI |
|
4619 .Cf DW_LNS_set_column |
|
4620 .br |
|
4621 Takes a single unsigned LEB128 operand and stores |
|
4622 it in the |
|
4623 .Cf column |
|
4624 register of the state machine. |
|
4625 .LI |
|
4626 .Cf DW_LNS_negate_stmt |
|
4627 .br |
|
4628 Takes no arguments. |
|
4629 Set the |
|
4630 .Cf is_stmt |
|
4631 register of the state machine to the |
|
4632 logical negation of its current value. |
|
4633 .LI |
|
4634 .Cf DW_LNS_set_basic_block |
|
4635 .br |
|
4636 Takes no arguments. Set the |
|
4637 .Cf basic_block |
|
4638 register of the state machine to ``true.'' |
|
4639 .LI |
|
4640 .Cf DW_LNS_const_add_pc |
|
4641 .br |
|
4642 Takes no arguments. |
|
4643 Add to the |
|
4644 .Cf address |
|
4645 register of the state machine the |
|
4646 address increment value corresponding to special |
|
4647 opcode 255. |
|
4648 .P |
|
4649 .I |
|
4650 The motivation for |
|
4651 .Cf DW_LNS_const_add_pc |
|
4652 is this: when the statement program needs |
|
4653 to advance the address by a small amount, it can use a single special |
|
4654 opcode, which occupies a single byte. When it needs to advance the |
|
4655 address by up to twice the range of the last special opcode, it can use |
|
4656 .Cf DW_LNS_const_add_pc |
|
4657 followed by a special opcode, for a total of two bytes. |
|
4658 Only if it needs to advance the address by more than twice that range |
|
4659 will it need to use both |
|
4660 .Cf DW_LNS_advance_pc |
|
4661 and a special opcode, requiring three or more bytes. |
|
4662 .R |
|
4663 .LI |
|
4664 .Cf DW_LNS_fixed_advance_pc |
|
4665 .br |
|
4666 Takes a single uhalf operand. Add to the |
|
4667 .Cf address |
|
4668 register of the state machine the value of the (unencoded) operand. |
|
4669 This is the only extended opcode that takes an argument that is not |
|
4670 a variable length number. |
|
4671 .P |
|
4672 .I |
|
4673 The motivation for |
|
4674 .Cf DW_LNS_fixed_advance_pc |
|
4675 is this: existing assemblers cannot emit |
|
4676 .Cf DW_LNS_advance_pc |
|
4677 or special opcodes because they cannot encode LEB128 numbers |
|
4678 or judge when the computation of a special opcode overflows and requires |
|
4679 the use of |
|
4680 .Cf DW_LNS_advance_pc . |
|
4681 Such assemblers, however, can use |
|
4682 .Cf DW_LNS_fixed_advance_pc |
|
4683 instead, sacrificing compression. |
|
4684 .R |
|
4685 .LE |
|
4686 .H 4 "Extended Opcodes" |
|
4687 .IX line number information, extended opcodes |
|
4688 There are three extended opcodes currently defined. The first byte |
|
4689 following the length field of the encoding for each contains a sub-opcode. |
|
4690 .AL |
|
4691 .LI |
|
4692 \f(CWDW_LNE_end_sequence\fP |
|
4693 .br |
|
4694 Set the |
|
4695 .Cf end_sequence |
|
4696 register of the state machine |
|
4697 to ``true'' and append a row to the matrix using the |
|
4698 current values of the state-machine registers. Then |
|
4699 reset the registers to the initial values specified |
|
4700 above. |
|
4701 .P |
|
4702 Every statement program sequence must end with a |
|
4703 .Cf DW_LNE_end_sequence |
|
4704 instruction which creates a |
|
4705 row whose address is that of the byte after the last target machine instruction |
|
4706 of the sequence. |
|
4707 .LI |
|
4708 \f(CWDW_LNE_set_address\fP |
|
4709 .br |
|
4710 Takes a single relocatable address as an operand. The size of the |
|
4711 operand is the size appropriate to hold an address on the target machine. |
|
4712 Set the |
|
4713 .Cf address |
|
4714 register to the value given by the |
|
4715 relocatable address. |
|
4716 .P |
|
4717 .I |
|
4718 All of the other statement program opcodes that affect the |
|
4719 .Cf address |
|
4720 register add a delta to it. |
|
4721 This instruction stores a relocatable value into it instead. |
|
4722 .R |
|
4723 .LI |
|
4724 \f(CWDW_LNE_define_file\fP |
|
4725 .br |
|
4726 .IX source, files |
|
4727 Takes 4 arguments. The first is a null terminated string containing a |
|
4728 source file name. The second is an |
|
4729 unsigned LEB128 number representing the directory index of the |
|
4730 directory in which the file was found. |
|
4731 The third is an unsigned LEB128 number representing |
|
4732 the time of last modification of the file. The fourth is an unsigned |
|
4733 LEB128 number representing the length in bytes of the file. |
|
4734 The time and length fields may contain LEB128(0) if the information is |
|
4735 not available. |
|
4736 .P |
|
4737 The directory index represents an entry in the |
|
4738 .Cf include_directories |
|
4739 section of the statement program prologue. |
|
4740 The index is LEB128(0) if the file was found in |
|
4741 the current directory of the compilation, LEB128(1) if it was |
|
4742 found in the first directory in the |
|
4743 .Cf include_directories |
|
4744 section, and so on. The directory index is ignored for file names |
|
4745 that represent full path names. |
|
4746 .P |
|
4747 The files are numbered, starting at 1, |
|
4748 in the order in which they appear; the names in the prologue |
|
4749 come before names defined by the |
|
4750 .Cf DW_LNE_define_file |
|
4751 instruction. |
|
4752 These numbers are used in the the |
|
4753 .Cf file |
|
4754 register of the state machine. |
|
4755 .LE |
|
4756 .P |
|
4757 .I |
|
4758 Appendix 3 gives some sample statement programs. |
|
4759 .R |
|
4760 .H 2 "Macro Information" |
|
4761 .I |
|
4762 .IX macro information |
|
4763 .IX pre-processor |
|
4764 .IX C %c |
|
4765 .IX C++ %caa |
|
4766 Some languages, such as C and C++, provide a way to replace text |
|
4767 in the source program with macros defined either in the source |
|
4768 file itself, or in another file included by the source file. |
|
4769 Because these macros are not themselves defined in the target |
|
4770 language, it is difficult to represent their definitions |
|
4771 using the standard language constructs of DWARF. The debugging |
|
4772 information therefore reflects the state of the source after |
|
4773 the macro definition has been expanded, rather than as the |
|
4774 programmer wrote it. |
|
4775 The macro information table provides a way of preserving the original |
|
4776 source in the debugging information. |
|
4777 .R |
|
4778 .P |
|
4779 As described in section 3.1, the macro information for a given |
|
4780 compilation unit is represented in the |
|
4781 .Cf .debug_macinfo |
|
4782 .IX \f(CW.debug_macinfo\fP %debugam |
|
4783 section of an object file. The macro information for each compilation |
|
4784 unit is represented as a series of ``macinfo'' entries. Each |
|
4785 macinfo entry consists of a ``type code'' and up to two additional |
|
4786 operands. The series of entries for a given compilation unit |
|
4787 ends with an entry containing a type code of 0. |
|
4788 .H 3 "Macinfo Types" |
|
4789 The valid macinfo types are as follows: |
|
4790 .VL 30 |
|
4791 .LI \f(CWDW_MACINFO_define\fP |
|
4792 A macro definition. |
|
4793 .LI \f(CWDW_MACINFO_undef\fP |
|
4794 A macro un-definition. |
|
4795 .LI \f(CWDW_MACINFO_start_file\fP |
|
4796 The start of a new source file inclusion. |
|
4797 .LI \f(CWDW_MACINFO_end_file\fP |
|
4798 The end of the current source file inclusion. |
|
4799 .LI \f(CWDW_MACINFO_vendor_ext\fP |
|
4800 Vendor specific macro information directives that do not fit |
|
4801 into one of the standard categories. |
|
4802 .LE |
|
4803 .H 4 "Define and Undefine Entries" |
|
4804 .IX macro information, define and undefine entries |
|
4805 All |
|
4806 .Cf DW_MACINFO_define |
|
4807 and |
|
4808 .Cf DW_MACINFO_undef |
|
4809 entries have two operands. |
|
4810 The first operand encodes the line number of the source line |
|
4811 .IX source, lines |
|
4812 on which the relevant defining or undefining |
|
4813 pre-processor directives appeared. |
|
4814 .P |
|
4815 The second operand consists of a null-terminated character string. |
|
4816 In the case of a |
|
4817 .Cf DW_MACINFO_undef |
|
4818 entry, the value of this |
|
4819 string will be simply the name of the pre-processor |
|
4820 symbol which was undefined at the indicated source line. |
|
4821 .P |
|
4822 In the case of a |
|
4823 .Cf DW_MACINFO_define |
|
4824 entry, the value of this |
|
4825 string will be the name of the pre-processor symbol |
|
4826 that was defined at the indicated source line, |
|
4827 followed immediately by the macro formal parameter |
|
4828 list including the surrounding parentheses (in the |
|
4829 case of a function-like macro) followed by the |
|
4830 definition string for the macro. If there is no |
|
4831 formal parameter list, then the name of the defined |
|
4832 macro is followed directly by its definition string. |
|
4833 .P |
|
4834 In the case of a function-like macro definition, no |
|
4835 whitespace characters should appear between the |
|
4836 name of the defined macro and the following left |
|
4837 parenthesis. Also, no whitespace characters should |
|
4838 appear between successive formal parameters in the |
|
4839 formal parameter list. (Successive formal parameters |
|
4840 should, however, be separated by commas.) Also, exactly |
|
4841 one space character |
|
4842 should separate the right parenthesis which terminates |
|
4843 the formal parameter list and the following definition |
|
4844 string. |
|
4845 .P |
|
4846 In the case of a ``normal'' (i.e. non-function-like) |
|
4847 macro definition, exactly one space character |
|
4848 should separate the name of the defined macro from the following definition |
|
4849 text. |
|
4850 .H 4 "Start File Entries" |
|
4851 .IX macro information, start file entries |
|
4852 Each |
|
4853 .Cf DW_MACINFO_start_file |
|
4854 entry also has two operands. The first operand |
|
4855 encodes the line number of the |
|
4856 source line on which the inclusion pre-processor |
|
4857 directive occurred. |
|
4858 .P |
|
4859 .IX source, files |
|
4860 The second operand encodes a |
|
4861 source file name index. This index corresponds to a file |
|
4862 number in the statement information table for the relevant |
|
4863 compilation unit. This index |
|
4864 indicates (indirectly) the name of the file |
|
4865 which is being included by the inclusion directive on |
|
4866 the indicated source line. |
|
4867 .H 4 "End File Entries" |
|
4868 .IX macro information, end file entries |
|
4869 A |
|
4870 .Cf DW_MACINFO_end_file |
|
4871 entry has no operands. The presence of the entry marks the end of |
|
4872 the current source file inclusion. |
|
4873 .H 4 "Vendor Extension Entries" |
|
4874 .IX macro information, vendor extensions |
|
4875 .IX vendor extensions |
|
4876 A |
|
4877 .Cf DW_MACINFO_vendor_ext |
|
4878 entry has two operands. |
|
4879 The first is a constant. The second is a null-terminated |
|
4880 character string. |
|
4881 The meaning and/or significance of these operands is |
|
4882 intentionally left undefined by this specification. |
|
4883 .P |
|
4884 A consumer must be able to totally ignore all |
|
4885 .Cf DW_MACINFO_vendor_ext |
|
4886 entries that it does not understand. |
|
4887 .H 3 "Base Source Entries" |
|
4888 .IX macro information, base source entries |
|
4889 In addition to producing a matched pair of |
|
4890 .Cf DW_MACINFO_start_file |
|
4891 and |
|
4892 .Cf DW_MACINFO_end_file |
|
4893 entries for |
|
4894 each inclusion directive actually processed during |
|
4895 compilation, a producer should generate such a matched |
|
4896 pair also for the ``base'' source file submitted to the |
|
4897 compiler for compilation. If the base source file |
|
4898 .IX source, files |
|
4899 for a compilation is submitted to the compiler via |
|
4900 some means other than via a named disk file (e.g. via |
|
4901 the standard input \fIstream\fP on a UNIX system) then the |
|
4902 compiler should still produce this matched pair of |
|
4903 .Cf DW_MACINFO_start_file |
|
4904 and |
|
4905 .Cf DW_MACINFO_end_file |
|
4906 entries for |
|
4907 the base source file, however, the file name indicated |
|
4908 (indirectly) by the |
|
4909 .Cf DW_MACINFO_start_file |
|
4910 entry of the |
|
4911 pair should reference a statement information file name entry consisting |
|
4912 of a null string. |
|
4913 .H 3 "Macinfo Entries for Command Line Options" |
|
4914 .IX macro information, command line options |
|
4915 In addition to producing |
|
4916 .Cf DW_MACINFO_define |
|
4917 and |
|
4918 .Cf DW_MACINFO_undef |
|
4919 entries for each of the define and |
|
4920 undefine directives processed during compilation, the |
|
4921 DWARF producer should generate a |
|
4922 .Cf DW_MACINFO_define |
|
4923 or |
|
4924 .Cf DW_MACINFO_undef |
|
4925 entry for each pre-processor symbol |
|
4926 which is defined or undefined by some |
|
4927 means other than via a define or undefine directive |
|
4928 within the compiled source text. In particular, |
|
4929 pre-processor symbol definitions and un-definitions |
|
4930 which occur as a result of command line options |
|
4931 (when invoking the compiler) should be represented by |
|
4932 their own |
|
4933 .Cf DW_MACINFO_define |
|
4934 and |
|
4935 .Cf DW_MACINFO_undef |
|
4936 entries. |
|
4937 .P |
|
4938 All such |
|
4939 .Cf DW_MACINFO_define |
|
4940 and |
|
4941 .Cf DW_MACINFO_undef |
|
4942 entries representing compilation options should appear |
|
4943 before the first |
|
4944 .Cf DW_MACINFO_start_file |
|
4945 entry for that compilation unit and should encode the value |
|
4946 0 in their line number operands. |
|
4947 .H 3 " General Rules and Restrictions" |
|
4948 .IX line number information, general rules |
|
4949 All macinfo entries within a |
|
4950 .Cf .debug_macinfo |
|
4951 section for a given compilation unit should appear in the same order |
|
4952 in which the directives were processed by the compiler. |
|
4953 .P |
|
4954 All macinfo entries representing command line options |
|
4955 should appear in the same order as the relevant command |
|
4956 line options were given to the compiler. In the case |
|
4957 where the compiler itself implicitly supplies one or |
|
4958 more macro definitions or un-definitions in addition |
|
4959 to those which may be specified on the command line, |
|
4960 macinfo entries should also be produced for these |
|
4961 implicit definitions and un-definitions, and |
|
4962 these entries should also appear in the proper order |
|
4963 relative to each other and to any definitions or |
|
4964 undefinitions given explicitly by the user on the |
|
4965 command line. |
|
4966 .H 2 "Call Frame Information" |
|
4967 .IX call frame information |
|
4968 .IX activations |
|
4969 .I |
|
4970 Debuggers often need to be able to view and modify the state of any |
|
4971 subroutine activation that is on the call stack. An activation |
|
4972 consists of: |
|
4973 .BL |
|
4974 .LI |
|
4975 A code location that is within the subroutine. This location is |
|
4976 either the place where the program stopped when the debugger got |
|
4977 control (e.g. a breakpoint), or is a place where a subroutine |
|
4978 made a call or was interrupted by an asynchronous event (e.g. a |
|
4979 signal). |
|
4980 .LI |
|
4981 An area of memory that is allocated on a stack called a ``call |
|
4982 frame.'' The call frame is identified by an address on the |
|
4983 stack. We refer to this address as the Canonical Frame Address or CFA. |
|
4984 .LI |
|
4985 A set of registers that are in use by the subroutine at the code |
|
4986 location. |
|
4987 .LE |
|
4988 .P |
|
4989 Typically, a set of registers are designated to be preserved across a |
|
4990 call. If a callee wishes to use such a register, it saves the value |
|
4991 that the register had at entry time in its call frame and restores it |
|
4992 on exit. The code that allocates space on the call frame stack and |
|
4993 performs the save operation is called the subroutine's prologue, and the |
|
4994 code that performs the restore operation and deallocates the frame is |
|
4995 called its epilogue. Typically, the prologue code is physically at the |
|
4996 beginning of a subroutine and the epilogue code is at the end. |
|
4997 .P |
|
4998 To be able to view or modify an activation that is not on the top of |
|
4999 the call frame stack, the debugger must ``virtually unwind'' the stack of |
|
5000 activations until it finds the activation of interest. |
|
5001 A debugger unwinds a |
|
5002 stack in steps. Starting with the current activation it restores any |
|
5003 registers that were preserved by the current activation and computes the |
|
5004 predecessor's CFA and code location. This has the logical effect of |
|
5005 returning from the current subroutine to its predecessor. We say that |
|
5006 the debugger virtually unwinds the stack because it preserves enough |
|
5007 information to be able to ``rewind'' the stack back to the state it was |
|
5008 in before it attempted to unwind it. |
|
5009 .P |
|
5010 The unwinding operation needs to know where registers are saved and how |
|
5011 to compute the predecessor's CFA and code location. When considering |
|
5012 an architecture-independent way of encoding this information one has to |
|
5013 consider a number of special things. |
|
5014 .BL |
|
5015 .LI |
|
5016 Prologue and epilogue code is not always in distinct blocks at the |
|
5017 beginning and end of a subroutine. It is common to duplicate the |
|
5018 epilogue code at the site of each return from the code. Sometimes |
|
5019 a compiler breaks up the register save/unsave operations and moves |
|
5020 them into the body of the subroutine to just where they are needed. |
|
5021 .LI |
|
5022 Compilers use different ways to manage the call frame. Sometimes |
|
5023 they use a frame pointer register, sometimes not. |
|
5024 .LI |
|
5025 The algorithm to compute the CFA changes as you progress through |
|
5026 the prologue and epilogue code. (By definition, the CFA value |
|
5027 does not change.) |
|
5028 .LI |
|
5029 Some subroutines have no call frame. |
|
5030 .LI |
|
5031 Sometimes a register is saved in another register that by |
|
5032 convention does not need to be saved. |
|
5033 .LI |
|
5034 Some architectures have special instructions that |
|
5035 perform some or all of the register management in one instruction, |
|
5036 leaving special information on the stack that indicates how |
|
5037 registers are saved. |
|
5038 .LI |
|
5039 Some architectures treat return address values |
|
5040 specially. For example, in one architecture, |
|
5041 the call instruction guarantees that the low order two |
|
5042 bits will be zero and the return instruction ignores those bits. |
|
5043 This leaves two bits of storage that are available to other uses |
|
5044 that must be treated specially. |
|
5045 .LE |
|
5046 .R |
|
5047 .H 3 "Structure of Call Frame Information" |
|
5048 .IX call frame information, structure |
|
5049 DWARF supports virtual unwinding by defining an architecture independent |
|
5050 basis for recording how procedures save and restore registers throughout |
|
5051 their lifetimes. This basis must be augmented on some machines with |
|
5052 specific information that is defined by either an architecture specific |
|
5053 ABI authoring committee, a hardware vendor, or a compiler producer. |
|
5054 .IX ABI |
|
5055 .IX vendor extensions |
|
5056 The body defining a specific augmentation is referred to |
|
5057 below as the ``augmenter.'' |
|
5058 .P |
|
5059 Abstractly, this mechanism describes a very large table that has the |
|
5060 following structure: |
|
5061 .TS |
|
5062 center; |
|
5063 l l l l l l |
|
5064 l s s s s s. |
|
5065 LOC CFA R0 R1 ... RN |
|
5066 L0 |
|
5067 L1 |
|
5068 \... |
|
5069 LN |
|
5070 .TE |
|
5071 .P |
|
5072 The first column indicates an address for every location that contains |
|
5073 code in a program. (In shared objects, this is an object-relative |
|
5074 offset.) The remaining columns contain virtual unwinding rules that are |
|
5075 associated with the indicated location. The first column of the rules |
|
5076 defines the CFA rule which is a register and a signed offset that are |
|
5077 added together to compute the CFA value. |
|
5078 .P |
|
5079 The remaining columns are labeled by register number. This includes |
|
5080 some registers that have special designation on some architectures such |
|
5081 as the PC and the stack pointer register. (The actual mapping of |
|
5082 registers for a particular architecture is performed by the augmenter.) |
|
5083 The register columns contain rules that describe |
|
5084 whether a given register has been saved and the rule to find |
|
5085 the value for the register in the previous frame. |
|
5086 .P |
|
5087 The register rules are: |
|
5088 .IX call frame information, register rules |
|
5089 .VL 20 |
|
5090 .LI "undefined" |
|
5091 A register that has this rule has no value in the |
|
5092 previous frame. (By convention, it is not preserved by a callee.) |
|
5093 .LI "same value" |
|
5094 This register has not been modified from the |
|
5095 previous frame. (By convention, it is preserved by the callee, |
|
5096 but the callee has not modified it.) |
|
5097 .LI "offset(N)" |
|
5098 The previous value of this register is saved at the address CFA+N where |
|
5099 CFA is the current CFA value and N is a signed offset. |
|
5100 .LI "register(R)" |
|
5101 The previous value of this register is stored in |
|
5102 another register numbered R. |
|
5103 .LI "architectural" |
|
5104 The rule is defined externally to this specification by the augmenter. |
|
5105 .LE |
|
5106 .P |
|
5107 .I |
|
5108 This table would be extremely large if actually constructed as |
|
5109 described. Most of the entries at any point in the table are identical |
|
5110 to the ones above them. The whole table can be represented quite |
|
5111 compactly by recording just the differences starting at the beginning |
|
5112 address of each subroutine in the program. |
|
5113 .R |
|
5114 .P |
|
5115 The virtual unwind information is encoded in a self-contained section |
|
5116 called |
|
5117 .Cf .debug_frame . |
|
5118 .IX \f(CW.debug_frame\fP %debugaf |
|
5119 Entries in a |
|
5120 .Cf .debug_frame |
|
5121 section are aligned on |
|
5122 .IX call frame information, Common Information Entry |
|
5123 an addressing unit boundary and come in two forms: A Common Information |
|
5124 Entry (CIE) and a Frame Description Entry (FDE). |
|
5125 Sizes of data objects used in the encoding of the |
|
5126 .Cf .debug_frame |
|
5127 section are described in terms of the same data definitions |
|
5128 used for the line number information (see section 6.2.1). |
|
5129 .P |
|
5130 A Common Information Entry holds information that is shared among many |
|
5131 Frame Descriptors. There is at least one CIE in every non-empty |
|
5132 .Cf .debug_frame |
|
5133 section. A CIE contains the following fields, in order: |
|
5134 .AL |
|
5135 .LI |
|
5136 \f(CWlength\fP |
|
5137 .br |
|
5138 A uword constant that gives the number of bytes of the CIE |
|
5139 structure, not including the length field, itself |
|
5140 (length mod <addressing unit size> == 0). |
|
5141 .LI |
|
5142 \f(CWCIE_id\fP |
|
5143 .br |
|
5144 A uword constant that is used to distinguish CIEs |
|
5145 from FDEs. |
|
5146 .LI |
|
5147 \f(CWversion\fP |
|
5148 .br |
|
5149 A ubyte version number. This number is specific to the call frame |
|
5150 information and is independent of the DWARF version number. |
|
5151 .LI |
|
5152 \f(CWaugmentation\fP |
|
5153 .br |
|
5154 A null terminated string that identifies the |
|
5155 augmentation to this CIE or to the FDEs that use |
|
5156 it. If a reader encounters an augmentation string that is |
|
5157 unexpected, then only the following fields can be read: |
|
5158 CIE: |
|
5159 .Cf length , |
|
5160 .Cf CIE_id , |
|
5161 .Cf version , |
|
5162 .Cf augmentation ; |
|
5163 FDE: |
|
5164 .Cf length , |
|
5165 .Cf CIE_pointer , |
|
5166 .Cf initial_location , |
|
5167 .Cf address_range . |
|
5168 If there is no augmentation, this value is a zero byte. |
|
5169 .LI |
|
5170 \f(CWcode_alignment_factor\fP |
|
5171 .br |
|
5172 An unsigned LEB128 constant that is factored out |
|
5173 of all advance location instructions (see below). |
|
5174 .LI |
|
5175 \f(CWdata_alignment_factor\fP |
|
5176 .br |
|
5177 A signed LEB128 constant that is factored out |
|
5178 of all offset instructions (see below.) |
|
5179 .LI |
|
5180 \f(CWreturn_address_register\fP |
|
5181 .br |
|
5182 A ubyte constant that indicates |
|
5183 which column in the rule table represents the return address |
|
5184 of the function. Note that this column might not correspond |
|
5185 to an actual machine register. |
|
5186 .LI |
|
5187 \f(CWinitial_instructions\fP |
|
5188 .br |
|
5189 A sequence of rules that are interpreted to |
|
5190 create the initial setting of each column in the table. |
|
5191 .LI |
|
5192 \f(CWpadding\fP |
|
5193 .br |
|
5194 Enough |
|
5195 .Cf DW_CFA_nop |
|
5196 instructions to make the size of this entry |
|
5197 match the |
|
5198 .Cf length |
|
5199 value above. |
|
5200 .LE |
|
5201 .P |
|
5202 An FDE contains the following fields, in order: |
|
5203 .IX call frame information, Frame Description Entry |
|
5204 .AL |
|
5205 .LI |
|
5206 \f(CWlength\fP |
|
5207 .br |
|
5208 A uword constant that gives the number of bytes of the header |
|
5209 and instruction stream for this function (not including the length |
|
5210 field itself) (length mod <addressing unit size> == 0). |
|
5211 .LI |
|
5212 \f(CWCIE_pointer\fP |
|
5213 .br |
|
5214 A uword constant offset into the |
|
5215 .Cf .debug_frame |
|
5216 section that denotes the CIE that is associated with this FDE. |
|
5217 .LI |
|
5218 \f(CWinitial_location\fP |
|
5219 An addressing-unit sized constant indicating |
|
5220 the address of the first location associated with this table entry. |
|
5221 .LI |
|
5222 \f(CWaddress_range\fP |
|
5223 .br |
|
5224 An addressing unit sized constant indicating the |
|
5225 number of bytes of program instructions described by this entry. |
|
5226 .LI |
|
5227 \f(CWinstructions\fP |
|
5228 .br |
|
5229 A sequence of table defining instructions that are |
|
5230 described below. |
|
5231 .LE |
|
5232 .H 3 "Call Frame Instructions" |
|
5233 .IX call frame information, instructions |
|
5234 Each call frame instruction is defined to |
|
5235 take 0 or more operands. Some of the operands may be |
|
5236 encoded as part of the opcode (see section 7.23). |
|
5237 The instructions are as follows: |
|
5238 .AL |
|
5239 .LI |
|
5240 .Cf DW_CFA_advance_loc |
|
5241 takes a single argument that represents a constant delta. |
|
5242 The required action is to |
|
5243 create a new table row with a location value that |
|
5244 is computed by taking the current entry's location value and |
|
5245 adding (delta * \f(CWcode_alignment_factor\fP). All other values in the |
|
5246 new row are initially identical to the current row. |
|
5247 .LI |
|
5248 .Cf DW_CFA_offset |
|
5249 takes two arguments: |
|
5250 an unsigned LEB128 constant representing a factored offset |
|
5251 and a register number. The required action is |
|
5252 to change the rule for the register indicated by the register |
|
5253 number to be an offset(N) rule with a value of |
|
5254 (N = factored offset * \f(CWdata_alignment_factor\fP). |
|
5255 .LI |
|
5256 .Cf DW_CFA_restore |
|
5257 takes a single argument that represents a register number. |
|
5258 The required action is |
|
5259 to change the rule for the indicated register |
|
5260 to the rule assigned it by the \f(CWinitial_instructions\fP in the CIE. |
|
5261 .LI |
|
5262 .Cf DW_CFA_set_loc |
|
5263 takes a single argument that represents an address. |
|
5264 The required action is to create a new table row |
|
5265 using the specified address as the location. |
|
5266 All other values in the |
|
5267 new row are initially identical to the current row. |
|
5268 The new location value should always be greater than the current |
|
5269 one. |
|
5270 .LI |
|
5271 .Cf DW_CFA_advance_loc1 |
|
5272 takes a single ubyte argument that represents a constant delta. |
|
5273 This instruction is identical to |
|
5274 .Cf DW_CFA_advance_loc |
|
5275 except for the encoding and size of the delta argument. |
|
5276 .LI |
|
5277 .Cf DW_CFA_advance_loc2 |
|
5278 takes a single uhalf argument that represents a constant delta. |
|
5279 This instruction is identical to |
|
5280 .Cf DW_CFA_advance_loc |
|
5281 except for the encoding and size of the delta argument. |
|
5282 .LI |
|
5283 .Cf DW_CFA_advance_loc4 |
|
5284 takes a single uword argument that represents a constant delta. |
|
5285 This instruction is identical to |
|
5286 .Cf DW_CFA_advance_loc |
|
5287 except for the encoding and size of the delta argument. |
|
5288 .LI |
|
5289 .Cf DW_CFA_offset_extended |
|
5290 takes two unsigned LEB128 arguments representing a register number |
|
5291 and a factored offset. |
|
5292 This instruction is identical to |
|
5293 .Cf DW_CFA_offset |
|
5294 except for the encoding and size of the register argument. |
|
5295 .LI |
|
5296 .Cf DW_CFA_restore_extended |
|
5297 takes a single unsigned LEB128 argument that represents a register number. |
|
5298 This instruction is identical to |
|
5299 .Cf DW_CFA_restore |
|
5300 except for the encoding and size of the register argument. |
|
5301 .LI |
|
5302 .Cf DW_CFA_undefined |
|
5303 takes a single unsigned LEB128 argument that represents a register number. |
|
5304 The required action is to set the rule for the specified register |
|
5305 to ``undefined.'' |
|
5306 .LI |
|
5307 .Cf DW_CFA_same_value |
|
5308 takes a single unsigned LEB128 argument that represents a register number. |
|
5309 The required action is to set the rule for the specified register |
|
5310 to ``same value.'' |
|
5311 .LI |
|
5312 .Cf DW_CFA_register |
|
5313 takes two unsigned LEB128 arguments representing register numbers. |
|
5314 The required action is to set the rule for the first register |
|
5315 to be the second register. |
|
5316 .LI |
|
5317 \f(CWDW_CFA_remember_state\fP |
|
5318 .LI |
|
5319 \f(CWDW_CFA_restore_state\fP |
|
5320 .br |
|
5321 These instructions define a stack of information. Encountering the |
|
5322 .Cf DW_CFA_remember_state |
|
5323 instruction means to save the rules for every register |
|
5324 on the current row on the stack. Encountering the |
|
5325 .Cf DW_CFA_restore_state |
|
5326 instruction means to pop the set of rules |
|
5327 off the stack and place them in the current row. |
|
5328 .I |
|
5329 (This |
|
5330 operation is useful for compilers that move epilogue |
|
5331 code into the body of a function.) |
|
5332 .R |
|
5333 .LI |
|
5334 .Cf DW_CFA_def_cfa |
|
5335 takes two unsigned LEB128 arguments representing a |
|
5336 register number and an offset. |
|
5337 The required action is to define the current CFA rule |
|
5338 to use the provided register and offset. |
|
5339 .LI |
|
5340 .Cf DW_CFA_def_cfa_register |
|
5341 takes a single unsigned LEB128 argument representing a register |
|
5342 number. The required action is to define the current CFA |
|
5343 rule to use the provided register (but to keep the old offset). |
|
5344 .LI |
|
5345 .Cf DW_CFA_def_cfa_offset |
|
5346 takes a single unsigned LEB128 argument representing an offset. |
|
5347 The required action is to define the current CFA |
|
5348 rule to use the provided offset (but to keep the old register). |
|
5349 .LI |
|
5350 .Cf DW_CFA_nop |
|
5351 has no arguments and no required actions. It is used as padding |
|
5352 to make the FDE an appropriate size. |
|
5353 .LE |
|
5354 .H 3 "Call Frame Instruction Usage" |
|
5355 .IX call frame information, usage |
|
5356 .I |
|
5357 To determine the virtual unwind rule set for a given location (L1), one |
|
5358 searches through the FDE headers looking at the |
|
5359 .Cf initial_location |
|
5360 and |
|
5361 .Cf address_range |
|
5362 values to see if L1 is contained in the FDE. If so, then: |
|
5363 .AL |
|
5364 .LI |
|
5365 Initialize a register set by reading the |
|
5366 .Cf initial_instructions |
|
5367 field of the associated CIE. |
|
5368 .LI |
|
5369 Read and process the FDE's instruction sequence until a |
|
5370 .Cf DW_CFA_advance_loc , |
|
5371 .Cf DW_CFA_set_loc , |
|
5372 or the end of the instruction stream is |
|
5373 encountered. |
|
5374 .LI |
|
5375 If a |
|
5376 .Cf DW_CFA_advance_loc |
|
5377 or |
|
5378 .Cf DW_CFA_set_loc |
|
5379 instruction was encountered, then |
|
5380 compute a new location value (L2). If L1 >= L2 then process the |
|
5381 instruction and go back to step 2. |
|
5382 .LI |
|
5383 The end of the instruction stream can be thought of as a |
|
5384 .br |
|
5385 \f(CWDW_CFA_set_loc( initial_location + address_range )\fP |
|
5386 .br |
|
5387 instruction. |
|
5388 Unless the FDE is ill-formed, L1 should be less than L2 at this point. |
|
5389 .LE |
|
5390 .P |
|
5391 The rules in the register set now apply to location L1. |
|
5392 .P |
|
5393 For an example, see Appendix 5. |
|
5394 .R |
|
5395 .OP |
|
5396 .H 1 "DATA REPRESENTATION" |
|
5397 This section describes the binary representation of the debugging |
|
5398 information entry itself, of the |
|
5399 attribute types and of other fundamental elements described above. |
|
5400 .H 2 "Vendor Extensibility" |
|
5401 .IX vendor extensions |
|
5402 To reserve a portion of the DWARF name space and ranges of |
|
5403 enumeration values for use for vendor specific extensions, |
|
5404 .IX tags |
|
5405 .IX types, base |
|
5406 .IX base types |
|
5407 .IX locations, expressions |
|
5408 .IX calling conventions |
|
5409 .IX call frame information |
|
5410 special labels are reserved for tag names, attribute names, |
|
5411 base type encodings, location operations, language names, |
|
5412 calling conventions and call frame instructions. |
|
5413 The labels denoting the beginning and end of the reserved value |
|
5414 range for vendor specific extensions consist of the appropriate prefix ( |
|
5415 .Cf DW_TAG , |
|
5416 .Cf DW_AT , |
|
5417 .Cf DW_ATE , |
|
5418 .Cf DW_OP , |
|
5419 .Cf DW_LANG , |
|
5420 .CF DW_CC |
|
5421 or |
|
5422 .Cf DW_CFA |
|
5423 respectively) followed by |
|
5424 .Cf _lo_user |
|
5425 or |
|
5426 .Cf _hi_user . |
|
5427 For example, for entry tags, the special labels are |
|
5428 .Cf DW_TAG_lo_user |
|
5429 and |
|
5430 .Cf DW_TAG_hi_user . |
|
5431 Values in the range between \fIprefix\fP\f(CW_lo_user\fP and |
|
5432 \fIprefix\fP\f(CW_hi_user\fP |
|
5433 inclusive, are reserved for vendor specific extensions. |
|
5434 Vendors may use values in this range without |
|
5435 conflicting with current or future system-defined values. |
|
5436 All other values are reserved for use by the system. |
|
5437 .P |
|
5438 Vendor defined tags, attributes, base type encodings, location atoms, |
|
5439 language names, calling conventions and call frame instructions, |
|
5440 conventionally use the form |
|
5441 \fIprefix\f(CW_\fIvendor_id\f(CW_\fIname\fR, where \fIvendor_id\fP is some |
|
5442 identifying character sequence chosen so as to avoid conflicts with other |
|
5443 vendors. |
|
5444 .P |
|
5445 .IX compatibility |
|
5446 To ensure that extensions added by one vendor may be safely ignored |
|
5447 by consumers that do not understand those extensions, |
|
5448 the following rules should be followed: |
|
5449 .AL |
|
5450 .LI |
|
5451 New attributes should be added in such a way that a debugger may recognize |
|
5452 the format of a new attribute value without knowing the content of that |
|
5453 attribute value. |
|
5454 .LI |
|
5455 The semantics of any new attributes should not alter the semantics of |
|
5456 previously existing attributes. |
|
5457 .LI |
|
5458 The semantics of any new tags |
|
5459 should not conflict with the semantics of previously existing tags. |
|
5460 .LE |
|
5461 .H 2 "Reserved Error Values" |
|
5462 .IX error values |
|
5463 As a convenience for consumers of DWARF information, |
|
5464 the value 0 is reserved in the encodings for attribute names, attribute |
|
5465 forms, base type encodings, location operations, languages, |
|
5466 statement program opcodes, macro information entries and tag names |
|
5467 to represent an error condition or unknown value. DWARF does |
|
5468 not specify names for these reserved values, since they do not |
|
5469 represent valid encodings for the given type and should not appear |
|
5470 in DWARF debugging information. |
|
5471 .H 2 "Executable Objects and Shared Objects" |
|
5472 The relocated addresses in the debugging information for an executable |
|
5473 object are virtual addresses and the relocated addresses in the |
|
5474 debugging information for a shared object are offsets relative to |
|
5475 the start of the lowest segment used by that shared object. |
|
5476 .P |
|
5477 .I |
|
5478 This requirement makes the debugging information for shared objects |
|
5479 position independent. |
|
5480 Virtual addresses in a shared object may be calculated by adding the |
|
5481 offset to the base address at which the object was attached. |
|
5482 This offset is available in the run-time linker's data structures. |
|
5483 .H 2 "File Constraints" |
|
5484 All debugging information entries in a relocatable object file, |
|
5485 executable object or shared |
|
5486 object are required to be physically contiguous. |
|
5487 .H 2 "Format of Debugging Information" |
|
5488 .IX Version 2 |
|
5489 For each compilation unit compiled with a DWARF Version 2 producer, |
|
5490 .IX compilation units |
|
5491 .IX compilation units, header |
|
5492 a contribution is made to the |
|
5493 .Cf .debug_info |
|
5494 .IX \f(CW.debug_info\fP %debugai |
|
5495 section of the object file. Each such contribution consists of |
|
5496 a compilation unit header followed by a series of debugging information |
|
5497 entries. Unlike the information encoding for DWARF Version 1, Version 2 |
|
5498 .IX Version 1 |
|
5499 debugging information entries do not themselves contain the debugging |
|
5500 information entry tag or the attribute name and form encodings for |
|
5501 each attribute. Instead, each debugging information entry begins with |
|
5502 a code that represents an entry in a separate abbreviations table. |
|
5503 This code is followed directly by a series of attribute values. |
|
5504 The appropriate entry in the abbreviations table guides the interpretation |
|
5505 of the information contained directly in the |
|
5506 .Cf .debug_info |
|
5507 section. Each compilation unit is associated with a particular |
|
5508 abbreviation table, but multiple compilation units may share |
|
5509 the same table. |
|
5510 .IX abbreviations table |
|
5511 .I |
|
5512 .P |
|
5513 This encoding was based on the observation that typical DWARF producers |
|
5514 produce a very limited number of different types of debugging information |
|
5515 entries. By extracting the common information from those entries |
|
5516 into a separate table, we are able to compress the generated information. |
|
5517 .R |
|
5518 .H 3 "Compilation Unit Header" |
|
5519 .IX compilation units, header |
|
5520 The header for the series of debugging information entries contributed |
|
5521 by a single compilation unit consists of the following information: |
|
5522 .AL |
|
5523 .LI |
|
5524 A 4-byte unsigned integer representing the length of the |
|
5525 .Cf .debug_info |
|
5526 contribution for that compilation unit, not including the length field itself. |
|
5527 .LI |
|
5528 A 2-byte unsigned integer representing the version of the DWARF information |
|
5529 for that compilation unit. For DWARF Version 2, the value in this field is 2. |
|
5530 .IX Version 2 |
|
5531 .LI |
|
5532 A 4-byte unsigned offset into the |
|
5533 .Cf .debug_abbrev |
|
5534 .IX \f(CW.debug_abbrev\fP %debugaab |
|
5535 section. This offset associates the compilation unit with a particular |
|
5536 set of debugging information entry abbreviations. |
|
5537 .LI |
|
5538 .IX segmented address space |
|
5539 .IX address space, segmented |
|
5540 .IX addresses, size of |
|
5541 A 1-byte unsigned integer representing the size in bytes of an address |
|
5542 on the target architecture. If the system uses segmented addressing, |
|
5543 this value represents the size of the offset portion of an address. |
|
5544 .IX addresses, offset portion |
|
5545 .LE |
|
5546 .P |
|
5547 .I |
|
5548 The compilation unit header does not replace the |
|
5549 .Cf DW_TAG_compile_unit |
|
5550 debugging information entry. It is additional information that |
|
5551 is represented outside the standard DWARF tag/attributes format. |
|
5552 .R |
|
5553 .H 3 "Debugging Information Entry" |
|
5554 Each debugging information entry begins with an unsigned LEB128 |
|
5555 .IX debugging information entries |
|
5556 number containing the abbreviation code for the entry. |
|
5557 This code represents an entry within the abbreviation table associated |
|
5558 with the compilation unit containing this entry. The abbreviation |
|
5559 .IX abbreviations table |
|
5560 code is followed by a series of attribute values. |
|
5561 .IX attributes, values |
|
5562 .P |
|
5563 On some architectures, there are alignment constraints on section boundaries. |
|
5564 To make it easier to pad debugging information sections to satisfy |
|
5565 such constraints, the abbreviation code 0 is reserved. Debugging |
|
5566 information entries consisting of only the 0 abbreviation code are considered |
|
5567 null entries. |
|
5568 .IX debugging information entries, null entries |
|
5569 .H 3 "Abbreviation Tables" |
|
5570 .IX abbreviations table |
|
5571 The abbreviation tables for all compilation units are contained in |
|
5572 a separate object file section called |
|
5573 .Cf .debug_abbrev . |
|
5574 .IX \f(CW.debug_abbrev\fP %debugaab |
|
5575 As mentioned before, multiple compilation units may share the same |
|
5576 abbreviation table. |
|
5577 .P |
|
5578 The abbreviation table for a single compilation |
|
5579 unit consists of a series of abbreviation declarations. |
|
5580 Each declaration specifies the tag and attributes for a particular |
|
5581 .IX tags |
|
5582 .IX attributes |
|
5583 form of debugging information entry. Each declaration begins with |
|
5584 an unsigned LEB128 number representing the abbreviation code itself. |
|
5585 It is this code that appears at the beginning of a debugging information |
|
5586 entry in the |
|
5587 .Cf .debug_info |
|
5588 section. As described above, the abbreviation code 0 is reserved for null |
|
5589 debugging information entries. |
|
5590 The abbreviation code is followed by another unsigned LEB128 |
|
5591 number that encodes the entry's tag. |
|
5592 .IX tags |
|
5593 .nr aX \n(Fg+1 |
|
5594 .nr bX \n(Fg+2 |
|
5595 The encodings for the tag names are given in Figures \n(aX |
|
5596 and \n(bX. |
|
5597 .DF |
|
5598 .TS |
|
5599 box center; |
|
5600 l l |
|
5601 lf(CW) lf(CW) |
|
5602 . |
|
5603 Tag name Value |
|
5604 _ |
|
5605 DW_TAG_array_type 0x01 |
|
5606 DW_TAG_class_type 0x02 |
|
5607 DW_TAG_entry_point 0x03 |
|
5608 DW_TAG_enumeration_type 0x04 |
|
5609 DW_TAG_formal_parameter 0x05 |
|
5610 DW_TAG_imported_declaration 0x08 |
|
5611 DW_TAG_label 0x0a |
|
5612 DW_TAG_lexical_block 0x0b |
|
5613 DW_TAG_member 0x0d |
|
5614 DW_TAG_pointer_type 0x0f |
|
5615 DW_TAG_reference_type 0x10 |
|
5616 DW_TAG_compile_unit 0x11 |
|
5617 DW_TAG_string_type 0x12 |
|
5618 DW_TAG_structure_type 0x13 |
|
5619 DW_TAG_subroutine_type 0x15 |
|
5620 DW_TAG_typedef 0x16 |
|
5621 DW_TAG_union_type 0x17 |
|
5622 DW_TAG_unspecified_parameters 0x18 |
|
5623 DW_TAG_variant 0x19 |
|
5624 DW_TAG_common_block 0x1a |
|
5625 DW_TAG_common_inclusion 0x1b |
|
5626 DW_TAG_inheritance 0x1c |
|
5627 DW_TAG_inlined_subroutine 0x1d |
|
5628 DW_TAG_module 0x1e |
|
5629 DW_TAG_ptr_to_member_type 0x1f |
|
5630 DW_TAG_set_type 0x20 |
|
5631 DW_TAG_subrange_type 0x21 |
|
5632 DW_TAG_with_stmt 0x22 |
|
5633 DW_TAG_access_declaration 0x23 |
|
5634 DW_TAG_base_type 0x24 |
|
5635 DW_TAG_catch_block 0x25 |
|
5636 DW_TAG_const_type 0x26 |
|
5637 DW_TAG_constant 0x27 |
|
5638 DW_TAG_enumerator 0x28 |
|
5639 DW_TAG_file_type 0x29 |
|
5640 .TE |
|
5641 .FG "Tag encodings (part 1)" |
|
5642 .DE |
|
5643 .DF |
|
5644 .TS |
|
5645 box center; |
|
5646 l l |
|
5647 lf(CW) lf(CW) |
|
5648 . |
|
5649 Tag name Value |
|
5650 _ |
|
5651 DW_TAG_friend 0x2a |
|
5652 DW_TAG_namelist 0x2b |
|
5653 DW_TAG_namelist_item 0x2c |
|
5654 DW_TAG_packed_type 0x2d |
|
5655 DW_TAG_subprogram 0x2e |
|
5656 DW_TAG_template_type_param 0x2f |
|
5657 DW_TAG_template_value_param 0x30 |
|
5658 DW_TAG_thrown_type 0x31 |
|
5659 DW_TAG_try_block 0x32 |
|
5660 DW_TAG_variant_part 0x33 |
|
5661 DW_TAG_variable 0x34 |
|
5662 DW_TAG_volatile_type 0x35 |
|
5663 DW_TAG_lo_user 0x4080 |
|
5664 DW_TAG_hi_user 0xffff |
|
5665 .TE |
|
5666 .FG "Tag encodings (part 2)" |
|
5667 .DE |
|
5668 .P |
|
5669 Following the tag encoding is a 1-byte value that determines |
|
5670 whether a debugging information entry using this abbreviation |
|
5671 has child entries or not. If the value is |
|
5672 .Cf DW_CHILDREN_yes , |
|
5673 the next physically succeeding entry of any debugging information |
|
5674 entry using this abbreviation is the first child of the prior entry. |
|
5675 If the 1-byte value following the abbreviation's tag encoding |
|
5676 is |
|
5677 .Cf DW_CHILDREN_no , |
|
5678 the next physically succeeding entry of any debugging information entry |
|
5679 using this abbreviation is a sibling of the prior entry. (Either |
|
5680 the first child or sibling entries may be null entries). |
|
5681 .IX debugging information entries, siblings |
|
5682 .IX debugging information entries, child entries |
|
5683 .IX debugging information entries, null entries |
|
5684 .nr aX \n(Fg+1 |
|
5685 The encodings for the child determination byte are given in Figure \n(aX. |
|
5686 (As mentioned in section 2.3, each chain of sibling entries is |
|
5687 terminated by a null entry). |
|
5688 .IX debugging information entries, null entries |
|
5689 .DF |
|
5690 .TS |
|
5691 box center; |
|
5692 l l |
|
5693 lf(CW) lf(CW) |
|
5694 . |
|
5695 Child determination name Value |
|
5696 _ |
|
5697 DW_CHILDREN_no 0 |
|
5698 DW_CHILDREN_yes 1 |
|
5699 .TE |
|
5700 .FG "Child determination encodings" |
|
5701 .DE |
|
5702 .P |
|
5703 Finally, the child encoding is followed by a series of attribute specifications. |
|
5704 .IX attributes |
|
5705 Each attribute specification consists of two parts. The first part |
|
5706 is an unsigned LEB128 number representing the attribute's name. |
|
5707 .IX attributes, names |
|
5708 The second part is an unsigned LEB128 number representing the |
|
5709 attribute's form. The series of attribute specifications ends |
|
5710 .IX attributes, forms |
|
5711 with an entry containing 0 for the name and 0 for the form. |
|
5712 .P |
|
5713 The attribute form |
|
5714 .Cf DW_FORM_indirect |
|
5715 is a special case. For attributes with this form, the attribute value |
|
5716 itself in the |
|
5717 .Cf .debug_info |
|
5718 section begins with an unsigned LEB128 number that represents its form. |
|
5719 This allows producers to choose forms for particular attributes dynamically, |
|
5720 without having to add a new entry to the abbreviation table. |
|
5721 .P |
|
5722 The abbreviations for a given compilation unit end with an entry |
|
5723 consisting of a 0 byte for the abbreviation code. |
|
5724 .I |
|
5725 .P |
|
5726 See Appendix 2 for a depiction of the organization |
|
5727 of the debugging information. |
|
5728 .R |
|
5729 .H 3 "Attribute Encodings" |
|
5730 .nr aX \n(Fg+1 |
|
5731 .nr bX \n(Fg+2 |
|
5732 The encodings for the attribute names are given in Figures \n(aX |
|
5733 and \n(bX. |
|
5734 .DF |
|
5735 .TS |
|
5736 box center; |
|
5737 l l l |
|
5738 lf(CW) lf(CW) l |
|
5739 . |
|
5740 Attribute name Value Classes |
|
5741 _ |
|
5742 DW_AT_sibling 0x01 reference |
|
5743 DW_AT_location 0x02 block, constant |
|
5744 DW_AT_name 0x03 string |
|
5745 DW_AT_ordering 0x09 constant |
|
5746 DW_AT_byte_size 0x0b constant |
|
5747 DW_AT_bit_offset 0x0c constant |
|
5748 DW_AT_bit_size 0x0d constant |
|
5749 DW_AT_stmt_list 0x10 constant |
|
5750 DW_AT_low_pc 0x11 address |
|
5751 DW_AT_high_pc 0x12 address |
|
5752 DW_AT_language 0x13 constant |
|
5753 DW_AT_discr 0x15 reference |
|
5754 DW_AT_discr_value 0x16 constant |
|
5755 DW_AT_visibility 0x17 constant |
|
5756 DW_AT_import 0x18 reference |
|
5757 DW_AT_string_length 0x19 block, constant |
|
5758 DW_AT_common_reference 0x1a reference |
|
5759 DW_AT_comp_dir 0x1b string |
|
5760 DW_AT_const_value 0x1c string, constant, block |
|
5761 DW_AT_containing_type 0x1d reference |
|
5762 DW_AT_default_value 0x1e reference |
|
5763 DW_AT_inline 0x20 constant |
|
5764 DW_AT_is_optional 0x21 flag |
|
5765 DW_AT_lower_bound 0x22 constant, reference |
|
5766 DW_AT_producer 0x25 string |
|
5767 DW_AT_prototyped 0x27 flag |
|
5768 DW_AT_return_addr 0x2a block, constant |
|
5769 DW_AT_start_scope 0x2c constant |
|
5770 DW_AT_stride_size 0x2e constant |
|
5771 DW_AT_upper_bound 0x2f constant, reference |
|
5772 .TE |
|
5773 .FG "Attribute encodings, part 1" |
|
5774 .DE |
|
5775 .DF |
|
5776 .TS |
|
5777 box center; |
|
5778 l l l |
|
5779 lf(CW) lf(CW) l |
|
5780 . |
|
5781 Attribute name Value Classes |
|
5782 _ |
|
5783 DW_AT_abstract_origin 0x31 reference |
|
5784 DW_AT_accessibility 0x32 constant |
|
5785 DW_AT_address_class 0x33 constant |
|
5786 DW_AT_artificial 0x34 flag |
|
5787 DW_AT_base_types 0x35 reference |
|
5788 DW_AT_calling_convention 0x36 constant |
|
5789 DW_AT_count 0x37 constant, reference |
|
5790 DW_AT_data_member_location 0x38 block, reference |
|
5791 DW_AT_decl_column 0x39 constant |
|
5792 DW_AT_decl_file 0x3a constant |
|
5793 DW_AT_decl_line 0x3b constant |
|
5794 DW_AT_declaration 0x3c flag |
|
5795 DW_AT_discr_list 0x3d block |
|
5796 DW_AT_encoding 0x3e constant |
|
5797 DW_AT_external 0x3f flag |
|
5798 DW_AT_frame_base 0x40 block, constant |
|
5799 DW_AT_friend 0x41 reference |
|
5800 DW_AT_identifier_case 0x42 constant |
|
5801 DW_AT_macro_info 0x43 constant |
|
5802 DW_AT_namelist_item 0x44 block |
|
5803 DW_AT_priority 0x45 reference |
|
5804 DW_AT_segment 0x46 block, constant |
|
5805 DW_AT_specification 0x47 reference |
|
5806 DW_AT_static_link 0x48 block, constant |
|
5807 DW_AT_type 0x49 reference |
|
5808 DW_AT_use_location 0x4a block, constant |
|
5809 DW_AT_variable_parameter 0x4b flag |
|
5810 DW_AT_virtuality 0x4c constant |
|
5811 DW_AT_vtable_elem_location 0x4d block, reference |
|
5812 DW_AT_lo_user 0x2000 \(em |
|
5813 DW_AT_hi_user 0x3fff \(em |
|
5814 .TE |
|
5815 .FG "Attribute encodings, part 2" |
|
5816 .DE |
|
5817 .P |
|
5818 .IX attributes, forms |
|
5819 The attribute form governs how the value of the attribute is encoded. |
|
5820 The possible forms may belong to one of the following |
|
5821 form classes: |
|
5822 .VL 18 |
|
5823 .LI address |
|
5824 .IX attributes, addresses |
|
5825 Represented as an object of appropriate size to hold an |
|
5826 address on the target machine (\f(CWDW_FORM_addr\fP). |
|
5827 This address is relocatable in |
|
5828 a relocatable object file and is relocated in an |
|
5829 executable file or shared object. |
|
5830 .LI "block" |
|
5831 .IX attributes, blocks |
|
5832 Blocks come in four forms. The first consists of a 1-byte length |
|
5833 followed by 0 to 255 contiguous information bytes (\f(CWDW_FORM_block1\fP). |
|
5834 The second consists of a 2-byte length |
|
5835 followed by 0 to 65,535 contiguous information bytes (\f(CWDW_FORM_block2\fP). |
|
5836 The third consists of a 4-byte length |
|
5837 followed by 0 to 4,294,967,295 contiguous information bytes (\f(CWDW_FORM_block4\fP). |
|
5838 The fourth consists of an unsigned LEB128 length followed by the number |
|
5839 of bytes specified by the length (\f(CWDW_FORM_block\fP). |
|
5840 In all forms, the length is the number of information bytes that follow. |
|
5841 The information bytes may contain any mixture of relocated (or |
|
5842 relocatable) addresses, references to other debugging information entries or |
|
5843 data bytes. |
|
5844 .LI "constant" |
|
5845 .IX attributes, constants |
|
5846 There are six forms of constants: |
|
5847 one, two, four and eight byte values (respectively, |
|
5848 .Cf DW_FORM_data1 , |
|
5849 .Cf DW_FORM_data2 , |
|
5850 .Cf DW_FORM_data4 , |
|
5851 and |
|
5852 .Cf DW_FORM_data8 ). |
|
5853 .IX variable length data |
|
5854 .IX LEB128 |
|
5855 There are also variable length constant data forms encoded |
|
5856 using LEB128 numbers (see below). Both signed (\f(CWDW_FORM_sdata\fP) |
|
5857 and unsigned (\f(CWDW_FORM_udata\fP) variable length constants are available. |
|
5858 .LI flag |
|
5859 .IX attributes, flags |
|
5860 A flag is represented as a single byte of data (\f(CWDW_FORM_flag\fP). |
|
5861 If the flag has value zero, it indicates the absence of the attribute. |
|
5862 If the flag has a non-zero value, it indicates the presence of |
|
5863 the attribute. |
|
5864 .LI reference |
|
5865 .IX attributes, references |
|
5866 There are two types of reference. The first is an |
|
5867 offset relative to the first byte of the compilation unit header |
|
5868 for the compilation unit containing the reference. |
|
5869 The offset must refer to an entry within |
|
5870 that same compilation unit. There are five forms for this |
|
5871 type of reference: |
|
5872 one, two, four and eight byte offsets (respectively, |
|
5873 .Cf DW_FORM_ref1 , |
|
5874 .Cf DW_FORM_ref2 , |
|
5875 .Cf DW_FORM_ref4 , |
|
5876 and |
|
5877 .Cf DW_FORM_ref8 ). |
|
5878 There are is also an unsigned variable length offset encoded |
|
5879 using LEB128 numbers (\f(CWDW_FORM_ref_udata\fP). |
|
5880 .P |
|
5881 The second type of reference |
|
5882 is the address of any debugging information entry within |
|
5883 the same executable or shared object; it may refer to an entry |
|
5884 in a different compilation unit from the unit containing the |
|
5885 reference. This type of reference (\f(CWDW_FORM_ref_addr\fP) is the |
|
5886 size of an address on the target architecture; it is relocatable |
|
5887 in a relocatable object file and relocated in an executable file |
|
5888 or shared object. |
|
5889 .P |
|
5890 .I |
|
5891 The use of compilation unit relative references will reduce |
|
5892 the number of link-time relocations and so speed up linking. |
|
5893 .P |
|
5894 The use of address-type references allows for the commonization |
|
5895 of information, such as types, across compilation units. |
|
5896 .R |
|
5897 .LI string |
|
5898 .IX attributes, strings |
|
5899 A string is a sequence of contiguous non-null bytes followed by one null |
|
5900 byte. A string may be represented immediately in the debugging information |
|
5901 entry itself (\f(CWDW_FORM_string\fP), or may be represented as a 4-byte offset |
|
5902 into a string table contained in the |
|
5903 .Cf .debug_str |
|
5904 .IX \f(CW.debug_str\fP %debugas |
|
5905 .IX string table |
|
5906 section of the object file (\f(CWDW_FORM_strp\fP). |
|
5907 .LE |
|
5908 .P |
|
5909 .nr aX \n(Fg+1 |
|
5910 The form encodings are listed in Figure \n(aX. |
|
5911 .DF |
|
5912 .TS |
|
5913 box center; |
|
5914 l l l |
|
5915 lf(CW) lf(CW) l |
|
5916 . |
|
5917 Form name Value Class |
|
5918 _ |
|
5919 DW_FORM_addr 0x01 address |
|
5920 DW_FORM_block2 0x03 block |
|
5921 DW_FORM_block4 0x04 block |
|
5922 DW_FORM_data2 0x05 constant |
|
5923 DW_FORM_data4 0x06 constant |
|
5924 DW_FORM_data8 0x07 constant |
|
5925 DW_FORM_string 0x08 string |
|
5926 DW_FORM_block 0x09 block |
|
5927 DW_FORM_block1 0x0a block |
|
5928 DW_FORM_data1 0x0b constant |
|
5929 DW_FORM_flag 0x0c flag |
|
5930 DW_FORM_sdata 0x0d constant |
|
5931 DW_FORM_strp 0x0e string |
|
5932 DW_FORM_udata 0x0f constant |
|
5933 DW_FORM_ref_addr 0x10 reference |
|
5934 DW_FORM_ref1 0x11 reference |
|
5935 DW_FORM_ref2 0x12 reference |
|
5936 DW_FORM_ref4 0x13 reference |
|
5937 DW_FORM_ref8 0x14 reference |
|
5938 DW_FORM_ref_udata 0x15 reference |
|
5939 DW_FORM_indirect 0x16 (see section 7.5.3) |
|
5940 .TE |
|
5941 .FG "Attribute form encodings" |
|
5942 .DE |
|
5943 .H 2 "Variable Length Data" |
|
5944 .IX variable length data |
|
5945 .IX LEB128 |
|
5946 The special constant data forms |
|
5947 .Cf DW_FORM_sdata |
|
5948 and |
|
5949 .Cf DW_FORM_udata |
|
5950 are encoded using ``Little Endian Base 128'' (LEB128) |
|
5951 numbers. LEB128 is a scheme for encoding integers densely that |
|
5952 exploits the assumption that most integers are small in magnitude. |
|
5953 (This encoding is equally suitable whether the target machine |
|
5954 architecture represents data in big-endian or little-endian order. |
|
5955 It is ``little endian'' only in the sense that it avoids using space |
|
5956 to represent the ``big'' end of an unsigned integer, when the big |
|
5957 end is all zeroes or sign extension bits). |
|
5958 .P |
|
5959 .Cf DW_FORM_udata |
|
5960 (unsigned LEB128) numbers are encoded as follows: |
|
5961 start at the |
|
5962 low order end of an unsigned integer and chop it into 7-bit chunks. |
|
5963 Place each chunk into the low order 7 bits of a byte. Typically, |
|
5964 several of the high order bytes will be zero; discard them. Emit the |
|
5965 remaining bytes in a stream, starting with the low order byte; |
|
5966 set the high order bit on each byte except the last emitted byte. |
|
5967 The high bit of zero on the last byte indicates to the decoder |
|
5968 that it has encountered the last byte. |
|
5969 .P |
|
5970 The integer zero is a special case, consisting of a single zero byte. |
|
5971 .P |
|
5972 .I |
|
5973 .nr aX \n(Fg+1 |
|
5974 Figure \n(aX gives some examples of |
|
5975 .Cf DW_FORM_udata |
|
5976 numbers. The |
|
5977 .Cf 0x80 |
|
5978 in each case is the high order bit of the byte, indicating that |
|
5979 an additional byte follows: |
|
5980 .R |
|
5981 .DF |
|
5982 .TS |
|
5983 box center; |
|
5984 l l l |
|
5985 nf(CW) lf(CW) lf(CW) |
|
5986 . |
|
5987 Number First byte Second byte |
|
5988 _ |
|
5989 2 2 \(em |
|
5990 127 127 \(em |
|
5991 128 0+0x80 1 |
|
5992 129 1+0x80 1 |
|
5993 130 2+0x80 1 |
|
5994 12857 57+0x80 100 |
|
5995 .TE |
|
5996 .FG "Examples of unsigned LEB128 encodings" |
|
5997 .DE |
|
5998 .P |
|
5999 The encoding for |
|
6000 .Cf DW_FORM_sdata |
|
6001 (signed, 2s complement LEB128) numbers is similar, except that the |
|
6002 criterion for discarding high order bytes is not whether they are |
|
6003 zero, but whether they consist entirely of sign extension bits. |
|
6004 Consider the 32-bit integer |
|
6005 .Cf -2 . |
|
6006 The three high level bytes of the number are sign extension, thus LEB128 |
|
6007 would represent it as a single byte containing the low order 7 bits, |
|
6008 with the high order bit cleared to indicate the end of the byte |
|
6009 stream. Note that there is nothing within the LEB128 representation |
|
6010 that indicates whether an encoded number is signed or unsigned. |
|
6011 The decoder must know what type of number to expect. |
|
6012 .P |
|
6013 .I |
|
6014 .nr aX \n(Fg+1 |
|
6015 Figure \n(aX gives some examples of |
|
6016 .Cf DW_FORM_sdata |
|
6017 numbers. |
|
6018 .R |
|
6019 .P |
|
6020 .I |
|
6021 Appendix 4 gives algorithms for encoding and decoding these forms. |
|
6022 .R |
|
6023 .DF |
|
6024 .TS |
|
6025 box center; |
|
6026 l l l |
|
6027 nf(CW) lf(CW) lf(CW) |
|
6028 . |
|
6029 Number First byte Second byte |
|
6030 _ |
|
6031 2 2 \(em |
|
6032 -2 0x7e \(em |
|
6033 127 127+0x80 0 |
|
6034 -127 1+0x80 0x7f |
|
6035 128 0+0x80 1 |
|
6036 -128 0+0x80 0x7f |
|
6037 129 1+0x80 1 |
|
6038 -129 0x7f+0x80 0x7e |
|
6039 .TE |
|
6040 .FG "Examples of signed LEB128 encodings" |
|
6041 .DE |
|
6042 .H 2 "Location Descriptions" |
|
6043 .H 3 "Location Expressions" |
|
6044 .IX locations, descriptions |
|
6045 .IX locations, expressions |
|
6046 A location expression is stored in a block of contiguous bytes. |
|
6047 The bytes form a set of operations. |
|
6048 Each location operation has a 1-byte code |
|
6049 that identifies that operation. Operations can be followed |
|
6050 by one or more bytes of additional data. All operations in a |
|
6051 location expression are concatenated from left to right. |
|
6052 The encodings for the operations in a location expression |
|
6053 .IX locations, expressions |
|
6054 .nr aX \n(Fg+1 |
|
6055 .nr bX \n(Fg+2 |
|
6056 are described in Figures \n(aX and \n(bX. |
|
6057 .DS |
|
6058 .TS |
|
6059 center box; |
|
6060 l l l l |
|
6061 lf(CW) lf(CW) l l |
|
6062 . |
|
6063 Operation Code No. of Operands Notes |
|
6064 _ |
|
6065 DW_OP_addr 0x03 1 constant address (size target specific) |
|
6066 DW_OP_deref 0x06 0 |
|
6067 DW_OP_const1u 0x08 1 1-byte constant |
|
6068 DW_OP_const1s 0x09 1 1-byte constant |
|
6069 DW_OP_const2u 0x0a 1 2-byte constant |
|
6070 DW_OP_const2s 0x0b 1 2-byte constant |
|
6071 DW_OP_const4u 0x0c 1 4-byte constant |
|
6072 DW_OP_const4s 0x0d 1 4-byte constant |
|
6073 DW_OP_const8u 0x0e 1 8-byte constant |
|
6074 DW_OP_const8s 0x0f 1 8-byte constant |
|
6075 DW_OP_constu 0x10 1 ULEB128 constant |
|
6076 DW_OP_consts 0x11 1 SLEB128 constant |
|
6077 DW_OP_dup 0x12 0 |
|
6078 DW_OP_drop 0x13 0 |
|
6079 DW_OP_over 0x14 0 |
|
6080 DW_OP_pick 0x15 1 1-byte stack index |
|
6081 DW_OP_swap 0x16 0 |
|
6082 DW_OP_rot 0x17 0 |
|
6083 DW_OP_xderef 0x18 0 |
|
6084 DW_OP_abs 0x19 0 |
|
6085 DW_OP_and 0x1a 0 |
|
6086 DW_OP_div 0x1b 0 |
|
6087 DW_OP_minus 0x1c 0 |
|
6088 DW_OP_mod 0x1d 0 |
|
6089 DW_OP_mul 0x1e 0 |
|
6090 DW_OP_neg 0x1f 0 |
|
6091 DW_OP_not 0x20 0 |
|
6092 DW_OP_or 0x21 0 |
|
6093 DW_OP_plus 0x22 0 |
|
6094 DW_OP_plus_uconst 0x23 1 ULEB128 addend |
|
6095 DW_OP_shl 0x24 0 |
|
6096 DW_OP_shr 0x25 0 |
|
6097 DW_OP_shra 0x26 0 |
|
6098 .TE |
|
6099 .FG "Location operation encodings, part 1" |
|
6100 .DE |
|
6101 .DS |
|
6102 .TS |
|
6103 center box; |
|
6104 l l l l |
|
6105 lf(CW) lf(CW) l l |
|
6106 . |
|
6107 Operation Code No. of Operands Notes |
|
6108 _ |
|
6109 DW_OP_xor 0x27 0 |
|
6110 DW_OP_skip 0x2f 1 signed 2-byte constant |
|
6111 DW_OP_bra 0x28 1 signed 2-byte constant |
|
6112 DW_OP_eq 0x29 0 |
|
6113 DW_OP_ge 0x2a 0 |
|
6114 DW_OP_gt 0x2b 0 |
|
6115 DW_OP_le 0x2c 0 |
|
6116 DW_OP_lt 0x2d 0 |
|
6117 DW_OP_ne 0x2e 0 |
|
6118 DW_OP_lit0 0x30 0 literals 0..31 = (DW_OP_LIT0|literal) |
|
6119 DW_OP_lit1 0x31 0 |
|
6120 \.\.\. |
|
6121 DW_OP_lit31 0x4f 0 |
|
6122 DW_OP_reg0 0x50 0 reg 0..31 = (DW_OP_REG0|regnum) |
|
6123 DW_OP_reg1 0x51 0 |
|
6124 \.\.\. |
|
6125 DW_OP_reg31 0x6f 0 |
|
6126 DW_OP_breg0 0x70 1 SLEB128 offset |
|
6127 DW_OP_breg1 0x71 1 base reg 0..31 = (DW_OP_BREG0|regnum) |
|
6128 \.\.\. |
|
6129 DW_OP_breg31 0x8f 1 |
|
6130 DW_OP_regx 0x90 1 ULEB128 register |
|
6131 DW_OP_fbreg 0x91 1 SLEB128 offset |
|
6132 DW_OP_bregx 0x92 2 ULEB128 register followed by SLEB128 offset |
|
6133 DW_OP_piece 0x93 1 ULEB128 size of piece addressed |
|
6134 DW_OP_deref_size 0x94 1 1-byte size of data retrieved |
|
6135 DW_OP_xderef_size 0x95 1 1-byte size of data retrieved |
|
6136 DW_OP_nop 0x96 0 |
|
6137 DW_OP_lo_user 0xe0 |
|
6138 DW_OP_hi_user 0xff |
|
6139 .TE |
|
6140 .FG "Location operation encodings, part 2" |
|
6141 .DE |
|
6142 .H 3 "Location Lists" |
|
6143 .IX locations, lists |
|
6144 Each entry in a location list consists of two relative addresses |
|
6145 followed by a 2-byte length, followed by a block of contiguous |
|
6146 bytes. The length specifies the number of bytes in the block |
|
6147 that follows. The two addresses are the same size as used by |
|
6148 .Cf DW_FORM_addr |
|
6149 on the target machine. |
|
6150 .H 2 "Base Type Encodings" |
|
6151 .nr aX \n(Fg+1 |
|
6152 .IX base types |
|
6153 .IX types, base |
|
6154 The values of the constants used in the |
|
6155 .Cf DW_AT_encoding |
|
6156 attribute are given in Figure \n(aX. |
|
6157 .DF |
|
6158 .TS |
|
6159 box center; |
|
6160 l l |
|
6161 lf(CW) lf(CW) |
|
6162 . |
|
6163 Base type encoding name Value |
|
6164 _ |
|
6165 DW_ATE_address 0x1 |
|
6166 DW_ATE_boolean 0x2 |
|
6167 DW_ATE_complex_float 0x3 |
|
6168 DW_ATE_float 0x4 |
|
6169 DW_ATE_signed 0x5 |
|
6170 DW_ATE_signed_char 0x6 |
|
6171 DW_ATE_unsigned 0x7 |
|
6172 DW_ATE_unsigned_char 0x8 |
|
6173 DW_ATE_lo_user 0x80 |
|
6174 DW_ATE_hi_user 0xff |
|
6175 .TE |
|
6176 .FG "Base type encoding values" |
|
6177 .DE |
|
6178 .H 2 "Accessibility Codes" |
|
6179 .nr aX \n(Fg+1 |
|
6180 .IX accessibility |
|
6181 .IX declarations, accessibility |
|
6182 The encodings of the constants used in the |
|
6183 .Cf DW_AT_accessibility |
|
6184 attribute are given in Figure \n(aX. |
|
6185 .DF |
|
6186 .TS |
|
6187 box center; |
|
6188 l l |
|
6189 lf(CW) lf(CW) |
|
6190 . |
|
6191 Accessibility code name Value |
|
6192 _ |
|
6193 DW_ACCESS_public 1 |
|
6194 DW_ACCESS_protected 2 |
|
6195 DW_ACCESS_private 3 |
|
6196 .TE |
|
6197 .FG "Accessibility encodings" |
|
6198 .DE |
|
6199 .H 2 "Visibility Codes" |
|
6200 .nr aX \n(Fg+1 |
|
6201 The encodings of the constants used in the |
|
6202 .Cf DW_AT_visibility |
|
6203 .IX visibility |
|
6204 .IX declarations, visibility |
|
6205 attribute are given in Figure \n(aX. |
|
6206 .DF |
|
6207 .TS |
|
6208 box center; |
|
6209 l l |
|
6210 lf(CW) lf(CW) |
|
6211 . |
|
6212 Visibility code name Value |
|
6213 _ |
|
6214 DW_VIS_local 1 |
|
6215 DW_VIS_exported 2 |
|
6216 DW_VIS_qualified 3 |
|
6217 .TE |
|
6218 .FG "Visibility encodings" |
|
6219 .DE |
|
6220 .H 2 "Virtuality Codes" |
|
6221 .nr aX \n(Fg+1 |
|
6222 .IX virtuality |
|
6223 The encodings of the constants used in the |
|
6224 .Cf DW_AT_virtuality |
|
6225 attribute are given in Figure \n(aX. |
|
6226 .DF |
|
6227 .TS |
|
6228 box center; |
|
6229 l l |
|
6230 lf(CW) lf(CW) |
|
6231 . |
|
6232 Virtuality code name Value |
|
6233 _ |
|
6234 DW_VIRTUALITY_none 0 |
|
6235 DW_VIRTUALITY_virtual 1 |
|
6236 DW_VIRTUALITY_pure_virtual 2 |
|
6237 .TE |
|
6238 .FG "Virtuality encodings" |
|
6239 .DE |
|
6240 .H 2 "Source Languages" |
|
6241 .nr aX \n(Fg+1 |
|
6242 .IX languages |
|
6243 The encodings for source languages are given in Figure \n(aX. |
|
6244 Names marked with \(dg and their associated |
|
6245 values are reserved, but the languages |
|
6246 they represent are not supported in DWARF Version 2. |
|
6247 .DF |
|
6248 .TS |
|
6249 box center; |
|
6250 l l |
|
6251 lf(CW) lf(CW) |
|
6252 . |
|
6253 Language name Value |
|
6254 _ |
|
6255 DW_LANG_C89 0x0001 |
|
6256 DW_LANG_C 0x0002 |
|
6257 DW_LANG_Ada83\(dg 0x0003 |
|
6258 DW_LANG_C_plus_plus 0x0004 |
|
6259 DW_LANG_Cobol74\(dg 0x0005 |
|
6260 DW_LANG_Cobol85\(dg 0x0006 |
|
6261 DW_LANG_Fortran77 0x0007 |
|
6262 DW_LANG_Fortran90 0x0008 |
|
6263 DW_LANG_Pascal83 0x0009 |
|
6264 DW_LANG_Modula2 0x000a |
|
6265 DW_LANG_lo_user 0x8000 |
|
6266 DW_LANG_hi_user 0xffff |
|
6267 .TE |
|
6268 .FG "Language encodings" |
|
6269 .DE |
|
6270 .H 2 "Address Class Encodings" |
|
6271 .IX addresses, class |
|
6272 The value of the common address class encoding |
|
6273 .Cf DW_ADDR_none |
|
6274 is 0. |
|
6275 .H 2 "Identifier Case" |
|
6276 .IX identifiers, case |
|
6277 The encodings of the constants used in the |
|
6278 .Cf DW_AT_identifier_case |
|
6279 .nr aX \n(Fg+1 |
|
6280 attribute are given in Figure \n(aX. |
|
6281 .DF |
|
6282 .TS |
|
6283 box center; |
|
6284 l l |
|
6285 lf(CW) lf(CW) |
|
6286 . |
|
6287 Identifier Case Name Value |
|
6288 _ |
|
6289 DW_ID_case_sensitive 0 |
|
6290 DW_ID_up_case 1 |
|
6291 DW_ID_down_case 2 |
|
6292 DW_ID_case_insensitive 3 |
|
6293 .TE |
|
6294 .FG "Identifier case encodings" |
|
6295 .DE |
|
6296 .H 2 "Calling Convention Encodings" |
|
6297 .IX calling conventions |
|
6298 The encodings for the values of the |
|
6299 .Cf DW_AT_calling_convention |
|
6300 .nr aX \n(Fg+1 |
|
6301 attribute are given in Figure \n(aX. |
|
6302 .DF |
|
6303 .TS |
|
6304 box center; |
|
6305 l l |
|
6306 lf(CW) lf(CW) |
|
6307 . |
|
6308 Calling Convention Name Value |
|
6309 _ |
|
6310 DW_CC_normal 0x1 |
|
6311 DW_CC_program 0x2 |
|
6312 DW_CC_nocall 0x3 |
|
6313 DW_CC_lo_user 0x40 |
|
6314 DW_CC_hi_user 0xff |
|
6315 .TE |
|
6316 .FG "Calling convention encodings" |
|
6317 .DE |
|
6318 .H 2 "Inline Codes" |
|
6319 .IX subroutines, inline |
|
6320 The encodings of the constants used in the |
|
6321 .Cf DW_AT_inline |
|
6322 .nr aX \n(Fg+1 |
|
6323 attribute are given in Figure \n(aX. |
|
6324 .DF |
|
6325 .TS |
|
6326 box center; |
|
6327 l l |
|
6328 lf(CW) lf(CW) |
|
6329 . |
|
6330 Inline Code Name Value |
|
6331 _ |
|
6332 DW_INL_not_inlined 0 |
|
6333 DW_INL_inlined 1 |
|
6334 DW_INL_declared_not_inlined 2 |
|
6335 DW_INL_declared_inlined 3 |
|
6336 .TE |
|
6337 .FG "Inline encodings" |
|
6338 .DE |
|
6339 .H 2 "Array Ordering" |
|
6340 .IX arrays, ordering |
|
6341 The encodings for the values of the order attributes of arrays |
|
6342 .nr aX \n(Fg+1 |
|
6343 is given in Figure \n(aX. |
|
6344 .DF |
|
6345 .TS |
|
6346 box center; |
|
6347 l l |
|
6348 lf(CW) lf(CW) |
|
6349 . |
|
6350 Ordering name Value |
|
6351 _ |
|
6352 DW_ORD_row_major 0 |
|
6353 DW_ORD_col_major 1 |
|
6354 .TE |
|
6355 .FG "Ordering encodings" |
|
6356 .DE |
|
6357 .H 2 "Discriminant Lists" |
|
6358 .IX variants |
|
6359 .IX discriminated unions |
|
6360 .IX discriminants |
|
6361 The descriptors used in the |
|
6362 .Cf DW_AT_dicsr_list |
|
6363 attribute are encoded as 1-byte constants. |
|
6364 .nr aX \n(Fg+1 |
|
6365 The defined values are presented in Figure \n(aX. |
|
6366 .DF |
|
6367 .TS |
|
6368 box center; |
|
6369 l l |
|
6370 lf(CW) lf(CW) |
|
6371 . |
|
6372 Descriptor Name Value |
|
6373 _ |
|
6374 DW_DSC_label 0 |
|
6375 DW_DSC_range 1 |
|
6376 .TE |
|
6377 .FG "Discriminant descriptor encodings" |
|
6378 .DE |
|
6379 .H 2 "Name Lookup Table" |
|
6380 .IX lookup, by name |
|
6381 Each set of entries in the table of global names contained in the |
|
6382 .Cf .debug_pubnames |
|
6383 .IX \f(CW.debug_pubnames\fP %debugap |
|
6384 section begins with a header consisting of: a 4-byte length containing |
|
6385 the length of the set of entries for this compilation unit, not including |
|
6386 the length field itself; a 2-byte version identifier containing |
|
6387 the value 2 for DWARF Version 2; a 4-byte offset into the |
|
6388 .Cf .debug_info |
|
6389 section; and a 4-byte length containing the size in bytes |
|
6390 of the contents of the |
|
6391 .Cf .debug_info |
|
6392 section generated to represent this compilation unit. |
|
6393 This header is followed by a series of tuples. |
|
6394 Each tuple consists of a 4-byte offset |
|
6395 followed by a string of non-null bytes terminated by one null byte. |
|
6396 Each set is terminated by a 4-byte word containing the value 0. |
|
6397 .H 2 "Address Range Table" |
|
6398 .IX lookup, by address |
|
6399 Each set of entries in the table of address ranges contained in the |
|
6400 .Cf .debug_aranges |
|
6401 .IX \f(CW.debug_aranges\fP %debugaar |
|
6402 section begins with a header consisting of: a 4-byte length containing |
|
6403 the length of the set of entries for this compilation unit, not including |
|
6404 the length field itself; a 2-byte version identifier containing |
|
6405 the value 2 for DWARF Version 2; a 4-byte offset into the |
|
6406 .Cf .debug_info |
|
6407 section; a 1-byte unsigned integer containing the size in bytes of an |
|
6408 address (or the offset portion of an address for segmented addressing) |
|
6409 .IX addresses, offset portion |
|
6410 .IX addresses, size of |
|
6411 on the target system; and a 1-byte unsigned integer containing the |
|
6412 size in bytes of a segment descriptor on the target system. |
|
6413 This header is followed by a series of tuples. |
|
6414 Each tuple consists of an address and a length, each |
|
6415 in the size appropriate for an address on the target architecture. |
|
6416 The first tuple following the header in each set begins at |
|
6417 an offset that is a multiple of the size of a single tuple |
|
6418 (that is, twice the size of an address). The header is |
|
6419 padded, if necessary, to the appropriate boundary. |
|
6420 Each set of tuples is terminated by a 0 for the address and 0 for the length. |
|
6421 .H 2 "Line Number Information" |
|
6422 .IX line number information |
|
6423 .IX line number information, definitions |
|
6424 The sizes of the integers used in the line number and |
|
6425 call frame information sections are as follows: |
|
6426 .VL 15 |
|
6427 .LI "sbyte" |
|
6428 Signed 1-byte value. |
|
6429 .LI "ubyte" |
|
6430 Unsigned 1-byte value. |
|
6431 .LI "uhalf" |
|
6432 Unsigned 2-byte value. |
|
6433 .LI "sword" |
|
6434 Signed 4-byte value. |
|
6435 .LI "uword" |
|
6436 Unsigned 4-byte value. |
|
6437 .LI |
|
6438 .LE |
|
6439 .P |
|
6440 .IX Version 2 |
|
6441 The version number in the statement program prologue is 2 for |
|
6442 DWARF Version 2. |
|
6443 The boolean values ``true'' and ``false'' used by the statement |
|
6444 information program are encoded as a single byte containing the |
|
6445 value 0 for ``false,'' and a non-zero value for ``true.'' |
|
6446 The encodings for the pre-defined standard opcodes are given |
|
6447 .IX line number information, standard opcodes |
|
6448 .nr aX \n(Fg+1 |
|
6449 in Figure \n(aX. |
|
6450 .DF |
|
6451 .TS |
|
6452 box center; |
|
6453 l l |
|
6454 lf(CW) lf(CW) |
|
6455 . |
|
6456 Opcode Name Value |
|
6457 _ |
|
6458 DW_LNS_copy 1 |
|
6459 DW_LNS_advance_pc 2 |
|
6460 DW_LNS_advance_line 3 |
|
6461 DW_LNS_set_file 4 |
|
6462 DW_LNS_set_column 5 |
|
6463 DW_LNS_negate_stmt 6 |
|
6464 DW_LNS_set_basic_block 7 |
|
6465 DW_LNS_const_add_pc 8 |
|
6466 DW_LNS_fixed_advance_pc 9 |
|
6467 .TE |
|
6468 .FG "Standard Opcode Encodings" |
|
6469 .DE |
|
6470 The encodings for the pre-defined extended opcodes are given |
|
6471 .IX line number information, extended opcodes |
|
6472 .nr aX \n(Fg+1 |
|
6473 in Figure \n(aX. |
|
6474 .DF |
|
6475 .TS |
|
6476 box center; |
|
6477 l l |
|
6478 lf(CW) lf(CW) |
|
6479 . |
|
6480 Opcode Name Value |
|
6481 _ |
|
6482 DW_LNE_end_sequence 1 |
|
6483 DW_LNE_set_address 2 |
|
6484 DW_LNE_define_file 3 |
|
6485 .TE |
|
6486 .FG "Extended Opcode Encodings" |
|
6487 .DE |
|
6488 .H 2 "Macro Information" |
|
6489 .IX macro information |
|
6490 .IX source, files |
|
6491 The source line numbers and source file indices encoded in the |
|
6492 macro information section are represented as unsigned LEB128 numbers |
|
6493 as are the constants in an |
|
6494 .Cf DW_MACINFO_vendor_ext |
|
6495 entry. |
|
6496 The macinfo type is encoded as a single byte. The encodings are given |
|
6497 .nr aX \n(Fg+1 |
|
6498 in Figure \n(aX. |
|
6499 .DF |
|
6500 .TS |
|
6501 box center; |
|
6502 l l |
|
6503 lf(CW) lf(CW) |
|
6504 . |
|
6505 Macinfo Type Name Value |
|
6506 _ |
|
6507 DW_MACINFO_define 1 |
|
6508 DW_MACINFO_undef 2 |
|
6509 DW_MACINFO_start_file 3 |
|
6510 DW_MACINFO_end_file 4 |
|
6511 DW_MACINFO_vendor_ext 255 |
|
6512 .TE |
|
6513 .FG "Macinfo Type Encodings" |
|
6514 .DE |
|
6515 .H 2 "Call Frame Information" |
|
6516 .IX call frame information |
|
6517 The value of the CIE id in the CIE header is |
|
6518 .Cf 0xffffffff . |
|
6519 The initial value of the CIE version number is 1. |
|
6520 .P |
|
6521 Call frame instructions are encoded in one or more bytes. |
|
6522 .IX call frame information, instructions |
|
6523 The primary opcode is encoded in the high order two bits of |
|
6524 the first byte (that is, opcode = byte >> 6). |
|
6525 An operand or extended opcode may be encoded in the low order |
|
6526 6 bits. Additional operands are encoded in subsequent bytes. |
|
6527 The instructions and their encodings are presented |
|
6528 .nr aX \n(Fg+1 |
|
6529 in Figure \n(aX. |
|
6530 .DS |
|
6531 .TS |
|
6532 center box; |
|
6533 l l l l l |
|
6534 lf(CW) lf(CW) l l |
|
6535 lf(CW) lf(CW) l l |
|
6536 lf(CW) lf(CW) l l |
|
6537 lf(CW) lf(CW) lf(CW) l. |
|
6538 Instruction High 2 Bits Low 6 Bits Operand 1 Operand 2 |
|
6539 _ |
|
6540 DW_CFA_advance_loc 0x1 delta |
|
6541 DW_CFA_offset 0x2 register ULEB128 offset |
|
6542 DW_CFA_restore 0x3 register |
|
6543 DW_CFA_set_loc 0 0x01 address |
|
6544 DW_CFA_advance_loc1 0 0x02 1-byte delta |
|
6545 DW_CFA_advance_loc2 0 0x03 2-byte delta |
|
6546 DW_CFA_advance_loc4 0 0x04 4-byte delta |
|
6547 DW_CFA_offset_extended 0 0x05 ULEB128 register ULEB128 offset |
|
6548 DW_CFA_restore_extended 0 0x06 ULEB128 register |
|
6549 DW_CFA_undefined 0 0x07 ULEB128 register |
|
6550 DW_CFA_same_value 0 0x08 ULEB128 register |
|
6551 DW_CFA_register 0 0x09 ULEB128 register ULEB128 register |
|
6552 DW_CFA_remember_state 0 0x0a |
|
6553 DW_CFA_restore_state 0 0x0b |
|
6554 DW_CFA_def_cfa 0 0x0c ULEB128 register ULEB128 offset |
|
6555 DW_CFA_def_cfa_register 0 0x0d ULEB128 register |
|
6556 DW_CFA_def_cfa_offset 0 0x0e ULEB128 offset |
|
6557 DW_CFA_nop 0 0 |
|
6558 DW_CFA_lo_user 0 0x1c |
|
6559 DW_CFA_hi_user 0 0x3f |
|
6560 .TE |
|
6561 .FG "Call frame instruction encodings" |
|
6562 .DE |
|
6563 .H 2 "Dependencies" |
|
6564 The debugging information in this format is intended to exist in the |
|
6565 .Cf .debug_abbrev , |
|
6566 .Cf .debug_aranges , |
|
6567 .Cf .debug_frame , |
|
6568 .Cf .debug_info , |
|
6569 .Cf .debug_line , |
|
6570 .Cf .debug_loc , |
|
6571 .Cf .debug_macinfo , |
|
6572 .Cf .debug_pubnames |
|
6573 and |
|
6574 .Cf .debug_str |
|
6575 .IX \f(CW.debug_abbrev\fP %debugaab |
|
6576 .IX \f(CW.debug_aranges\fP %debugaar |
|
6577 .IX \f(CW.debug_frame\fP %debugaf |
|
6578 .IX \f(CW.debug_info\fP %debugai |
|
6579 .IX \f(CW.debug_line\fP %debugali |
|
6580 .IX \f(CW.debug_loc\fP %debugalo |
|
6581 .IX \f(CW.debug_macinfo\fP %debugam |
|
6582 .IX \f(CW.debug_pubnames\fP %debugap |
|
6583 .IX \f(CW.debug_str\fP %debugas |
|
6584 sections of an object file. |
|
6585 The information is not word-aligned, so the assembler must provide a |
|
6586 way for the compiler to produce 2-byte and 4-byte quantities without |
|
6587 alignment restrictions, and the linker must be able to |
|
6588 relocate a 4-byte reference at an arbitrary alignment. |
|
6589 In target architectures with 64-bit addresses, the assembler and linker |
|
6590 must similarly handle 8-byte references at arbitrary alignments. |
|
6591 .OP |
|
6592 .H 1 "FUTURE DIRECTIONS" |
|
6593 The \*(iX \*(tE is working on a specification for a set of interfaces |
|
6594 for reading DWARF information, that will hide changes in the |
|
6595 representation of that information from its consumers. It is |
|
6596 hoped that using these interfaces will make the transition from |
|
6597 DWARF Version 1 to Version 2 much simpler and will make it |
|
6598 easier for a single consumer to support objects using either |
|
6599 Version 1 or Version 2 DWARF. |
|
6600 .P |
|
6601 A draft of this specification is available for review from |
|
6602 \*(iX. The \*(tE wishes to stress, however, that the specification |
|
6603 is still in flux. |
|
6604 .OP |
|
6605 .HU "Appendix 1 -- Current Attributes by Tag Value" |
|
6606 .P |
|
6607 The list below enumerates the attributes that are most applicable to each type |
|
6608 of debugging information entry. |
|
6609 DWARF does not in general require that a given debugging information |
|
6610 entry contain a particular attribute or set of attributes. Instead, a |
|
6611 DWARF producer is free to generate any, all, or none of the attributes |
|
6612 described in the text as being applicable to a given entry. Other |
|
6613 attributes (both those defined within this document but not explicitly |
|
6614 associated with the entry in question, and new, vendor-defined ones) |
|
6615 may also appear in a given debugging entry. |
|
6616 Therefore, the list may be |
|
6617 taken as instructive, but cannot be considered definitive. |
|
6618 .sp |
|
6619 .sp |
|
6620 .DS |
|
6621 .TS |
|
6622 box, tab(:) ; |
|
6623 lfB lfB |
|
6624 lf(CW) lf(CW) . |
|
6625 TAG NAME:APPLICABLE ATTRIBUTES |
|
6626 _ |
|
6627 DW_TAG_access_declaration:DECL\(dg |
|
6628 :DW_AT_accessibility |
|
6629 :DW_AT_name |
|
6630 :DW_AT_sibling |
|
6631 _ |
|
6632 DW_TAG_array_type:DECL |
|
6633 :DW_AT_abstract_origin |
|
6634 :DW_AT_accessibility |
|
6635 :DW_AT_byte_size |
|
6636 :DW_AT_declaration |
|
6637 :DW_AT_name |
|
6638 :DW_AT_ordering |
|
6639 :DW_AT_sibling |
|
6640 :DW_AT_start_scope |
|
6641 :DW_AT_stride_size |
|
6642 :DW_AT_type |
|
6643 :DW_AT_visibility |
|
6644 _ |
|
6645 DW_TAG_base_type:DW_AT_bit_offset |
|
6646 :DW_AT_bit_size |
|
6647 :DW_AT_byte_size |
|
6648 :DW_AT_encoding |
|
6649 :DW_AT_name |
|
6650 :DW_AT_sibling |
|
6651 _ |
|
6652 DW_TAG_catch_block:DW_AT_abstract_origin |
|
6653 :DW_AT_high_pc |
|
6654 :DW_AT_low_pc |
|
6655 :DW_AT_segment |
|
6656 :DW_AT_sibling |
|
6657 .TE |
|
6658 .DE |
|
6659 .br |
|
6660 \(dg |
|
6661 .Cf DW_AT_decl_column , |
|
6662 .Cf DW_AT_decl_file , |
|
6663 .Cf DW_AT_decl_line . |
|
6664 .SK |
|
6665 .DS |
|
6666 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6667 |
|
6668 |
|
6669 |
|
6670 .TS |
|
6671 box, tab(:) ; |
|
6672 lfB lfB |
|
6673 lf(CW) lf(CW) . |
|
6674 TAG NAME:APPLICABLE ATTRIBUTES |
|
6675 _ |
|
6676 DW_TAG_class_type:DECL |
|
6677 :DW_AT_abstract_origin |
|
6678 :DW_AT_accessibility |
|
6679 :DW_AT_byte_size |
|
6680 :DW_AT_declaration |
|
6681 :DW_AT_name |
|
6682 :DW_AT_sibling |
|
6683 :DW_AT_start_scope |
|
6684 :DW_AT_visibility |
|
6685 _ |
|
6686 DW_TAG_common_block:DECL |
|
6687 :DW_AT_declaration |
|
6688 :DW_AT_location |
|
6689 :DW_AT_name |
|
6690 :DW_AT_sibling |
|
6691 :DW_AT_visibility |
|
6692 _ |
|
6693 DW_TAG_common_inclusion:DECL |
|
6694 :DW_AT_common_reference |
|
6695 :DW_AT_declaration |
|
6696 :DW_AT_sibling |
|
6697 :DW_AT_visibility |
|
6698 _ |
|
6699 DW_TAG_compile_unit:DW_AT_base_types |
|
6700 :DW_AT_comp_dir |
|
6701 :DW_AT_identifier_case |
|
6702 :DW_AT_high_pc |
|
6703 :DW_AT_language |
|
6704 :DW_AT_low_pc |
|
6705 :DW_AT_macro_info |
|
6706 :DW_AT_name |
|
6707 :DW_AT_producer |
|
6708 :DW_AT_sibling |
|
6709 :DW_AT_stmt_list |
|
6710 _ |
|
6711 DW_TAG_const_type:DW_AT_sibling |
|
6712 :DW_AT_type |
|
6713 .TE |
|
6714 .DE |
|
6715 .br |
|
6716 .SK |
|
6717 .DS |
|
6718 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6719 |
|
6720 |
|
6721 |
|
6722 .TS |
|
6723 box, tab(:) ; |
|
6724 lfB lfB |
|
6725 lf(CW) lf(CW) . |
|
6726 TAG NAME:APPLICABLE ATTRIBUTES |
|
6727 _ |
|
6728 DW_TAG_constant:DECL |
|
6729 :DW_AT_accessibility |
|
6730 :DW_AT_constant_value |
|
6731 :DW_AT_declaration |
|
6732 :DW_AT_external |
|
6733 :DW_AT_name |
|
6734 :DW_AT_sibling |
|
6735 :DW_AT_start_scope |
|
6736 :DW_AT_type |
|
6737 :DW_AT_visibility |
|
6738 _ |
|
6739 DW_TAG_entry_point:DW_AT_address_class |
|
6740 :DW_AT_low_pc |
|
6741 :DW_AT_name |
|
6742 :DW_AT_return_addr |
|
6743 :DW_AT_segment |
|
6744 :DW_AT_sibling |
|
6745 :DW_AT_static_link |
|
6746 :DW_AT_type |
|
6747 _ |
|
6748 DW_TAG_enumeration_type:DECL |
|
6749 :DW_AT_abstract_origin |
|
6750 :DW_AT_accessibility |
|
6751 :DW_AT_byte_size |
|
6752 :DW_AT_declaration |
|
6753 :DW_AT_name |
|
6754 :DW_AT_sibling |
|
6755 :DW_AT_start_scope |
|
6756 :DW_AT_visibility |
|
6757 _ |
|
6758 DW_TAG_enumerator:DECL |
|
6759 :DW_AT_const_value |
|
6760 :DW_AT_name |
|
6761 :DW_AT_sibling |
|
6762 _ |
|
6763 DW_TAG_file_type:DECL |
|
6764 :DW_AT_abstract_origin |
|
6765 :DW_AT_byte_size |
|
6766 :DW_AT_name |
|
6767 :DW_AT_sibling |
|
6768 :DW_AT_start_scope |
|
6769 :DW_AT_type |
|
6770 :DW_AT_visibility |
|
6771 .TE |
|
6772 .DE |
|
6773 .br |
|
6774 .SK |
|
6775 .DS |
|
6776 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6777 |
|
6778 |
|
6779 |
|
6780 .TS |
|
6781 box, tab(:) ; |
|
6782 lfB lfB |
|
6783 lf(CW) lf(CW) . |
|
6784 TAG NAME:APPLICABLE ATTRIBUTES |
|
6785 _ |
|
6786 DW_TAG_formal_parameter:DECL |
|
6787 :DW_AT_abstract_origin |
|
6788 :DW_AT_artificial |
|
6789 :DW_AT_default_value |
|
6790 :DW_AT_is_optional |
|
6791 :DW_AT_location |
|
6792 :DW_AT_name |
|
6793 :DW_AT_segment |
|
6794 :DW_AT_sibling |
|
6795 :DW_AT_type |
|
6796 :DW_AT_variable_parameter |
|
6797 _ |
|
6798 DW_TAG_friend:DECL |
|
6799 :DW_AT_abstract_origin |
|
6800 :DW_AT_friend |
|
6801 :DW_AT_sibling |
|
6802 _ |
|
6803 DW_TAG_imported_declaration:DECL |
|
6804 :DW_AT_accessibility |
|
6805 :DW_AT_import |
|
6806 :DW_AT_name |
|
6807 :DW_AT_sibling |
|
6808 :DW_AT_start_scope |
|
6809 _ |
|
6810 DW_TAG_inheritance:DECL |
|
6811 :DW_AT_accessibility |
|
6812 :DW_AT_data_member_location |
|
6813 :DW_AT_sibling |
|
6814 :DW_AT_type |
|
6815 :DW_AT_virtuality |
|
6816 _ |
|
6817 DW_TAG_inlined_subroutine:DECL |
|
6818 :DW_AT_abstract_origin |
|
6819 :DW_AT_high_pc |
|
6820 :DW_AT_low_pc |
|
6821 :DW_AT_segment |
|
6822 :DW_AT_sibling |
|
6823 :DW_AT_return_addr |
|
6824 :DW_AT_start_scope |
|
6825 _ |
|
6826 DW_TAG_label:DW_AT_abstract_origin |
|
6827 :DW_AT_low_pc |
|
6828 :DW_AT_name |
|
6829 :DW_AT_segment |
|
6830 :DW_AT_start_scope |
|
6831 :DW_AT_sibling |
|
6832 .TE |
|
6833 .DE |
|
6834 .br |
|
6835 .SK |
|
6836 .DS |
|
6837 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6838 |
|
6839 |
|
6840 |
|
6841 .TS |
|
6842 box, tab(:) ; |
|
6843 lfB lfB |
|
6844 lf(CW) lf(CW) . |
|
6845 TAG NAME:APPLICABLE ATTRIBUTES |
|
6846 _ |
|
6847 DW_TAG_lexical_block:DW_AT_abstract_origin |
|
6848 :DW_AT_high_pc |
|
6849 :DW_AT_low_pc |
|
6850 :DW_AT_name |
|
6851 :DW_AT_segment |
|
6852 :DW_AT_sibling |
|
6853 _ |
|
6854 DW_TAG_member:DECL |
|
6855 :DW_AT_accessibility |
|
6856 :DW_AT_byte_size |
|
6857 :DW_AT_bit_offset |
|
6858 :DW_AT_bit_size |
|
6859 :DW_AT_data_member_location |
|
6860 :DW_AT_declaration |
|
6861 :DW_AT_name |
|
6862 :DW_AT_sibling |
|
6863 :DW_AT_type |
|
6864 :DW_AT_visibility |
|
6865 _ |
|
6866 DW_TAG_module:DECL |
|
6867 :DW_AT_accessibility |
|
6868 :DW_AT_declaration |
|
6869 :DW_AT_high_pc |
|
6870 :DW_AT_low_pc |
|
6871 :DW_AT_name |
|
6872 :DW_AT_priority |
|
6873 :DW_AT_segment |
|
6874 :DW_AT_sibling |
|
6875 :DW_AT_visibility |
|
6876 _ |
|
6877 DW_TAG_namelist:DECL |
|
6878 :DW_AT_accessibility |
|
6879 :DW_AT_abstract_origin |
|
6880 :DW_AT_declaration |
|
6881 :DW_AT_sibling |
|
6882 :DW_AT_visibility |
|
6883 _ |
|
6884 DW_TAG_namelist_item:DECL |
|
6885 :DW_AT_namelist_item |
|
6886 :DW_AT_sibling |
|
6887 _ |
|
6888 DW_TAG_packed_type:DW_AT_sibling |
|
6889 :DW_AT_type |
|
6890 .TE |
|
6891 .DE |
|
6892 .br |
|
6893 .SK |
|
6894 .DS |
|
6895 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6896 |
|
6897 |
|
6898 |
|
6899 .TS |
|
6900 box, tab(:) ; |
|
6901 lfB lfB |
|
6902 lf(CW) lf(CW) . |
|
6903 TAG NAME:APPLICABLE ATTRIBUTES |
|
6904 _ |
|
6905 DW_TAG_pointer_type:DW_AT_address_class |
|
6906 :DW_AT_sibling |
|
6907 :DW_AT_type |
|
6908 _ |
|
6909 DW_TAG_ptr_to_member_type:DECL |
|
6910 :DW_AT_abstract_origin |
|
6911 :DW_AT_address_class |
|
6912 :DW_AT_containing_type |
|
6913 :DW_AT_declaration |
|
6914 :DW_AT_name |
|
6915 :DW_AT_sibling |
|
6916 :DW_AT_type |
|
6917 :DW_AT_use_location |
|
6918 :DW_AT_visibility |
|
6919 _ |
|
6920 DW_TAG_reference_type:DW_AT_address_class |
|
6921 :DW_AT_sibling |
|
6922 :DW_AT_type |
|
6923 _ |
|
6924 DW_TAG_set_type:DECL |
|
6925 :DW_AT_abstract_origin |
|
6926 :DW_AT_accessibility |
|
6927 :DW_AT_byte_size |
|
6928 :DW_AT_declaration |
|
6929 :DW_AT_name |
|
6930 :DW_AT_start_scope |
|
6931 :DW_AT_sibling |
|
6932 :DW_AT_type |
|
6933 :DW_AT_visibility |
|
6934 _ |
|
6935 DW_TAG_string_type:DECL |
|
6936 :DW_AT_accessibility |
|
6937 :DW_AT_abstract_origin |
|
6938 :DW_AT_byte_size |
|
6939 :DW_AT_declaration |
|
6940 :DW_AT_name |
|
6941 :DW_AT_segment |
|
6942 :DW_AT_sibling |
|
6943 :DW_AT_start_scope |
|
6944 :DW_AT_string_length |
|
6945 :DW_AT_visibility |
|
6946 .TE |
|
6947 .DE |
|
6948 .SK |
|
6949 .DS |
|
6950 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6951 |
|
6952 |
|
6953 |
|
6954 .TS |
|
6955 box, tab(:) ; |
|
6956 lfB lfB |
|
6957 lf(CW) lf(CW) . |
|
6958 TAG NAME:APPLICABLE ATTRIBUTES |
|
6959 _ |
|
6960 DW_TAG_structure_type:DECL |
|
6961 :DW_AT_abstract_origin |
|
6962 :DW_AT_accessibility |
|
6963 :DW_AT_byte_size |
|
6964 :DW_AT_declaration |
|
6965 :DW_AT_name |
|
6966 :DW_AT_sibling |
|
6967 :DW_AT_start_scope |
|
6968 :DW_AT_visibility |
|
6969 _ |
|
6970 DW_TAG_subprogram:DECL |
|
6971 :DW_AT_abstract_origin |
|
6972 :DW_AT_accessibility |
|
6973 :DW_AT_address_class |
|
6974 :DW_AT_artificial |
|
6975 :DW_AT_calling_convention |
|
6976 :DW_AT_declaration |
|
6977 :DW_AT_external |
|
6978 :DW_AT_frame_base |
|
6979 :DW_AT_high_pc |
|
6980 :DW_AT_inline |
|
6981 :DW_AT_low_pc |
|
6982 :DW_AT_name |
|
6983 :DW_AT_prototyped |
|
6984 :DW_AT_return_addr |
|
6985 :DW_AT_segment |
|
6986 :DW_AT_sibling |
|
6987 :DW_AT_specification |
|
6988 :DW_AT_start_scope |
|
6989 :DW_AT_static_link |
|
6990 :DW_AT_type |
|
6991 :DW_AT_visibility |
|
6992 :DW_AT_virtuality |
|
6993 :DW_AT_vtable_elem_location |
|
6994 .TE |
|
6995 .DE |
|
6996 .SK |
|
6997 .DS |
|
6998 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
6999 |
|
7000 |
|
7001 |
|
7002 .TS |
|
7003 box, tab(:) ; |
|
7004 lfB lfB |
|
7005 lf(CW) lf(CW) . |
|
7006 TAG NAME:APPLICABLE ATTRIBUTES |
|
7007 _ |
|
7008 DW_TAG_subrange_type:DECL |
|
7009 :DW_AT_abstract_origin |
|
7010 :DW_AT_accessibility |
|
7011 :DW_AT_byte_size |
|
7012 :DW_AT_count |
|
7013 :DW_AT_declaration |
|
7014 :DW_AT_lower_bound |
|
7015 :DW_AT_name |
|
7016 :DW_AT_sibling |
|
7017 :DW_AT_type |
|
7018 :DW_AT_upper_bound |
|
7019 :DW_AT_visibility |
|
7020 _ |
|
7021 DW_TAG_subroutine_type:DECL |
|
7022 :DW_AT_abstract_origin |
|
7023 :DW_AT_accessibility |
|
7024 :DW_AT_address_class |
|
7025 :DW_AT_declaration |
|
7026 :DW_AT_name |
|
7027 :DW_AT_prototyped |
|
7028 :DW_AT_sibling |
|
7029 :DW_AT_start_scope |
|
7030 :DW_AT_type |
|
7031 :DW_AT_visibility |
|
7032 _ |
|
7033 DW_TAG_template_type_param:DECL |
|
7034 :DW_AT_name |
|
7035 :DW_AT_sibling |
|
7036 :DW_AT_type |
|
7037 _ |
|
7038 DW_TAG_template_value_param:DECL |
|
7039 :DW_AT_name |
|
7040 :DW_AT_const_value |
|
7041 :DW_AT_sibling |
|
7042 :DW_AT_type |
|
7043 _ |
|
7044 DW_TAG_thrown_type:DECL |
|
7045 :DW_AT_sibling |
|
7046 :DW_AT_type |
|
7047 _ |
|
7048 DW_TAG_try_block:DW_AT_abstract_origin |
|
7049 :DW_AT_high_pc |
|
7050 :DW_AT_low_pc |
|
7051 :DW_AT_segment |
|
7052 :DW_AT_sibling |
|
7053 .TE |
|
7054 .DE |
|
7055 .br |
|
7056 .SK |
|
7057 .DS |
|
7058 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
7059 |
|
7060 |
|
7061 |
|
7062 .TS |
|
7063 box, tab(:) ; |
|
7064 lfB lfB |
|
7065 lf(CW) lf(CW) . |
|
7066 TAG NAME:APPLICABLE ATTRIBUTES |
|
7067 _ |
|
7068 DW_TAG_typedef:DECL |
|
7069 :DW_AT_abstract_origin |
|
7070 :DW_AT_accessibility |
|
7071 :DW_AT_declaration |
|
7072 :DW_AT_name |
|
7073 :DW_AT_sibling |
|
7074 :DW_AT_start_scope |
|
7075 :DW_AT_type |
|
7076 :DW_AT_visibility |
|
7077 _ |
|
7078 DW_TAG_union_type:DECL |
|
7079 :DW_AT_abstract_origin |
|
7080 :DW_AT_accessibility |
|
7081 :DW_AT_byte_size |
|
7082 :DW_AT_declaration |
|
7083 :DW_AT_friends |
|
7084 :DW_AT_name |
|
7085 :DW_AT_sibling |
|
7086 :DW_AT_start_scope |
|
7087 :DW_AT_visibility |
|
7088 _ |
|
7089 DW_TAG_unspecified_parameters:DECL |
|
7090 :DW_AT_abstract_origin |
|
7091 :DW_AT_artificial |
|
7092 :DW_AT_sibling |
|
7093 _ |
|
7094 DW_TAG_variable:DECL |
|
7095 :DW_AT_accessibility |
|
7096 :DW_AT_constant_value |
|
7097 :DW_AT_declaration |
|
7098 :DW_AT_external |
|
7099 :DW_AT_location |
|
7100 :DW_AT_name |
|
7101 :DW_AT_segment |
|
7102 :DW_AT_sibling |
|
7103 :DW_AT_specification |
|
7104 :DW_AT_start_scope |
|
7105 :DW_AT_type |
|
7106 :DW_AT_visibility |
|
7107 .TE |
|
7108 .DE |
|
7109 .br |
|
7110 .SK |
|
7111 .DS |
|
7112 .B "Appendix 1 (cont'd) -- Current Attributes by Tag Value" |
|
7113 |
|
7114 |
|
7115 |
|
7116 .TS |
|
7117 box, tab(:) ; |
|
7118 lfB lfB |
|
7119 lf(CW) lf(CW) . |
|
7120 TAG NAME:APPLICABLE ATTRIBUTES |
|
7121 _ |
|
7122 DW_TAG_variant:DECL |
|
7123 :DW_AT_accessibility |
|
7124 :DW_AT_abstract_origin |
|
7125 :DW_AT_declaration |
|
7126 :DW_AT_discr_list |
|
7127 :DW_AT_discr_value |
|
7128 :DW_AT_sibling |
|
7129 _ |
|
7130 DW_TAG_variant_part:DECL |
|
7131 :DW_AT_accessibility |
|
7132 :DW_AT_abstract_origin |
|
7133 :DW_AT_declaration |
|
7134 :DW_AT_discr |
|
7135 :DW_AT_sibling |
|
7136 :DW_AT_type |
|
7137 _ |
|
7138 DW_TAG_volatile_type:DW_AT_sibling |
|
7139 :DW_AT_type |
|
7140 _ |
|
7141 DW_TAG_with_statement:DW_AT_accessibility |
|
7142 :DW_AT_address_class |
|
7143 :DW_AT_declaration |
|
7144 :DW_AT_high_pc |
|
7145 :DW_AT_location |
|
7146 :DW_AT_low_pc |
|
7147 :DW_AT_segment |
|
7148 :DW_AT_sibling |
|
7149 :DW_AT_type |
|
7150 :DW_AT_visibility |
|
7151 .TE |
|
7152 .DE |
|
7153 .SK |
|
7154 .OP |
|
7155 .HU "Appendix 2 -- Organization of Debugging Information" |
|
7156 The following diagram depicts the relationship of the abbreviation |
|
7157 tables contained in the |
|
7158 .Cf .debug_abbrev |
|
7159 section to the information contained in the |
|
7160 .Cf .debug_info |
|
7161 section. Values are given in symbolic form, where possible. |
|
7162 .DF |
|
7163 .nf |
|
7164 .PS |
|
7165 scale=100 |
|
7166 define t201 | |
|
7167 [ box invis ht 154 wid 295 with .sw at 0,0 |
|
7168 "\f(CW\s9\&1\f1\s0" at 0,147 ljust |
|
7169 "\f(CW\s9\&DW_TAG_compile_unit\f1\s0" at 0,133 ljust |
|
7170 "\f(CW\s9\&DW_CHILDREN_yes\f1\s0" at 0,119 ljust |
|
7171 "\f(CW\s9\&DW_AT_name DW_FORM_string\f1\s0" at 0,105 ljust |
|
7172 "\f(CW\s9\&DW_AT_producer DW_FORM_string\f1\s0" at 0,91 ljust |
|
7173 "\f(CW\s9\&DW_AT_compdir DW_FORM_string\f1\s0" at 0,77 ljust |
|
7174 "\f(CW\s9\&DW_AT_language DW_FORM_data1\f1\s0" at 0,63 ljust |
|
7175 "\f(CW\s9\&DW_AT_low_poc DW_FORM_addr\f1\s0" at 0,49 ljust |
|
7176 "\f(CW\s9\&DW_AT_high_pc DW_FORM_addr\f1\s0" at 0,35 ljust |
|
7177 "\f(CW\s9\&DW_AT_stmt_list DW_FORM_indirect\f1\s0" at 0,21 ljust |
|
7178 "\f(CW\s9\&0 0\f1\s0" at 0,7 ljust |
|
7179 ] | |
|
7180 |
|
7181 define t103 | |
|
7182 [ box invis ht 42 wid 74 with .sw at 0,0 |
|
7183 "\f(CW\s9\&4\f1\s0" at 0,35 ljust |
|
7184 "\f(CW\s9\&\"POINTER\"\f1\s0" at 0,21 ljust |
|
7185 "\f(CW\s9\&\f1\s0" at 0,7 ljust |
|
7186 ] | |
|
7187 |
|
7188 define t177 | |
|
7189 [ box invis ht 28 wid 13 with .sw at 0,0 |
|
7190 "\f(CW\s9\&3\f1\s0" at 0,21 ljust |
|
7191 "\f(CW\s9\&\f1\s0" at 0,7 ljust |
|
7192 ] | |
|
7193 |
|
7194 define t224 | |
|
7195 [ box invis ht 84 wid 280 with .sw at 0,0 |
|
7196 "\f(CW\s9\&4\f1\s0" at 0,77 ljust |
|
7197 "\f(CW\s9\&DW_TAG_typedef\f1\s0" at 0,63 ljust |
|
7198 "\f(CW\s9\&DW_CHILDREN_no\f1\s0" at 0,49 ljust |
|
7199 "\f(CW\s9\&DW_AT_name DW_FORM_string\f1\s0" at 0,35 ljust |
|
7200 "\f(CW\s9\&DW_AT_type DW_FORM_ref4 \f1\s0" at 0,21 ljust |
|
7201 "\f(CW\s9\&0 0 \f1\s0" at 0,7 ljust |
|
7202 ] | |
|
7203 |
|
7204 define t149 | |
|
7205 [ box invis ht 28 wid 51 with .sw at 0,0 |
|
7206 "\f(CW\s9\&4\f1\s0" at 0,21 ljust |
|
7207 "\f(CW\s9\&\"strp\"\f1\s0" at 0,7 ljust |
|
7208 ] | |
|
7209 |
|
7210 define t205 | |
|
7211 [ box invis ht 98 wid 280 with .sw at 0,0 |
|
7212 "\f(CW\s9\&2\f1\s0" at 0,91 ljust |
|
7213 "\f(CW\s9\&DW_TAG_base_type\f1\s0" at 0,77 ljust |
|
7214 "\f(CW\s9\&DW_CHILDREN_no\f1\s0" at 0,63 ljust |
|
7215 "\f(CW\s9\&DW_AT_name DW_FORM_string\f1\s0" at 0,49 ljust |
|
7216 "\f(CW\s9\&DW_AT_encoding DW_FORM_data1\f1\s0" at 0,35 ljust |
|
7217 "\f(CW\s9\&DW_AT_byte_size DW_FORM_data1\f1\s0" at 0,21 ljust |
|
7218 "\f(CW\s9\&0 0\f1\s0" at 0,7 ljust |
|
7219 ] | |
|
7220 |
|
7221 define t126 | |
|
7222 [ box invis ht 126 wid 257 with .sw at 0,0 |
|
7223 "\f(CW\s9\&\"myfile.c\"\f1\s0" at 0,119 ljust |
|
7224 "\f(CW\s9\&\"Best Compiler Corp: Version 1.3\"\f1\s0" at 0,105 ljust |
|
7225 "\f(CW\s9\&\"mymachine:/home/mydir/src:\"\f1\s0" at 0,91 ljust |
|
7226 "\f(CW\s9\&DW_LANG_C89\f1\s0" at 0,77 ljust |
|
7227 "\f(CW\s9\&0x0\f1\s0" at 0,63 ljust |
|
7228 "\f(CW\s9\&0x55\f1\s0" at 0,49 ljust |
|
7229 "\f(CW\s9\&DW_FORM_data4\f1\s0" at 0,35 ljust |
|
7230 "\f(CW\s9\&0x0\f1\s0" at 0,21 ljust |
|
7231 "\f(CW\s9\&\f1\s0" at 0,7 ljust |
|
7232 ] | |
|
7233 |
|
7234 define t219 | |
|
7235 [ box invis ht 70 wid 260 with .sw at 0,0 |
|
7236 "\f(CW\s9\&3\f1\s0" at 0,63 ljust |
|
7237 "\f(CW\s9\&DW_TAG_pointer_type\f1\s0" at 0,49 ljust |
|
7238 "\f(CW\s9\&DW_CHILDREN_no\f1\s0" at 0,35 ljust |
|
7239 "\f(CW\s9\&DW_AT_type DW_FORM_ref4\f1\s0" at 0,21 ljust |
|
7240 "\f(CW\s9\&0 0\f1\s0" at 0,7 ljust |
|
7241 ] | |
|
7242 |
|
7243 define t109 | |
|
7244 [ box invis ht 42 wid 165 with .sw at 0,0 |
|
7245 "\f(CW\s9\&\"char\"\f1\s0" at 0,35 ljust |
|
7246 "\f(CW\s9\&DW_ATE_unsigned_char\f1\s0" at 0,21 ljust |
|
7247 "\f(CW\s9\&1\f1\s0" at 0,7 ljust |
|
7248 ] | |
|
7249 |
|
7250 box invis ht 704 wid 680 with .sw at 0,0 |
|
7251 t201 with .nw at 376,657 |
|
7252 box ht 520 wid 320 with .nw at 360,672 |
|
7253 box ht 208 wid 280 with .nw at 24,208 |
|
7254 t103 with .nw at 40,353 |
|
7255 t177 with .nw at 40,398 |
|
7256 line from 360,176 to 680,176 |
|
7257 line from 360,280 to 680,280 |
|
7258 line from 360,368 to 680,368 |
|
7259 line from 360,488 to 680,488 |
|
7260 t224 with .nw at 376,270 |
|
7261 "\f(CW\s9\&0\f1\s0" at 376,164 ljust |
|
7262 "\f(CW\s9\&0\f1\s0" at 40,289 ljust |
|
7263 "\fI\s9\&e2\f1\s0" at 40,317 ljust |
|
7264 "\fI\s9\&e2:\f1\s0" at 0,389 ljust |
|
7265 "\f(CW\s9\&2\f1\s0" at 44,176 ljust |
|
7266 line from 24,128 to 304,128 |
|
7267 "\f(CW\s9\&...\f1\s0" at 44,113 ljust |
|
7268 t149 with .nw at 44,88 |
|
7269 "\fI\s9\&e2\f1\s0" at 44,49 ljust |
|
7270 "\f(CW\s9\&...\f1\s0" at 44,17 ljust |
|
7271 box ht 416 wid 280 with .nw at 24,688 |
|
7272 "\fI\s9\&length\f1\s0" at 44,192 ljust |
|
7273 "\f(CW\s9\&4\f1\s0" at 48,140 |
|
7274 "\fI\s9\&a1 (abbreviation table offset)\f1\s0" at 44,160 ljust |
|
7275 "\f(CW\s9\&4\f1\s0" at 44,624 |
|
7276 "\fI\s9\&a1 (abbreviation table offset)\f1\s0" at 40,640 ljust |
|
7277 t205 with .nw at 376,477 |
|
7278 "\fI\s9\&a1:\f1\s0" at 348,657 rjust |
|
7279 "\fI\s9\&length\f1\s0" at 40,672 ljust |
|
7280 "\fR\s10\&Abbreviation Table - .debug_abbrev\f1\s0" at 384,678 ljust |
|
7281 "\fR\s10\&Compilation Unit 1 - .debug_info\f1\s0" at 68,694 ljust |
|
7282 "\fR\s10\&Compilation Unit 2 - .debug_info\f1\s0" at 64,218 ljust |
|
7283 "\f(CW\s9\&2\f1\s0" at 44,656 |
|
7284 "\f(CW\s9\&1\f1\s0" at 44,605 |
|
7285 t126 with .nw at 36,599 |
|
7286 line from 24,616 to 304,616 |
|
7287 "\f(CW\s9\&2\f1\s0" at 40,461 ljust |
|
7288 t219 with .nw at 376,359 |
|
7289 line from 24,96 to 304,96 |
|
7290 line from 24,32 to 304,32 |
|
7291 t109 with .nw at 40,449 |
|
7292 "\fI\s9\&e1\f1\s0" at 40,373 ljust |
|
7293 "\fI\s9\&e1:\f1\s0" at 0,461 ljust |
|
7294 line from 24,480 to 304,480 |
|
7295 line from 24,400 to 304,400 |
|
7296 line from 24,360 to 304,360 |
|
7297 line from 24,304 to 304,304 |
|
7298 .PE |
|
7299 .fi |
|
7300 .DE |
|
7301 .SK |
|
7302 .OP |
|
7303 .HU "Appendix 3 -- Statement Program Examples" |
|
7304 .P |
|
7305 Consider this simple source file and the resulting machine code for |
|
7306 the Intel 8086 processor: |
|
7307 .DS |
|
7308 .S -2 |
|
7309 .TS |
|
7310 ; |
|
7311 lf(CW) lf(CW) s |
|
7312 lf(CW) lf(CW) s |
|
7313 lf(CW) lf(CW) lf(CW) |
|
7314 lf(CW) lf(CW) lf(CW) |
|
7315 lf(CW) lf(CW) s |
|
7316 lf(CW) lf(CW) s |
|
7317 lf(CW) lf(CW) lf(CW) |
|
7318 lf(CW) lf(CW) lf(CW) |
|
7319 lf(CW) lf(CW) lf(CW) |
|
7320 lf(CW) lf(CW) lf(CW) |
|
7321 lf(CW) lf(CW) s |
|
7322 lf(CW) lf(CW) lf(CW) |
|
7323 lf(CW) lf(CW) lf(CW) |
|
7324 lf(CW) lf(CW) lf(CW) |
|
7325 lf(CW) lf(CW) lf(CW) |
|
7326 lf(CW) lf(CW) s |
|
7327 lf(CW) lf(CW) lf(CW) |
|
7328 lf(CW) lf(CW) lf(CW) |
|
7329 lf(CW) lf(CW) s |
|
7330 lf(CW) lf(CW) lf(CW). |
|
7331 1: int |
|
7332 2: main() |
|
7333 0x239: push pb |
|
7334 0x23a: mov bp,sp |
|
7335 3: { |
|
7336 4: printf("Omit needless words\en"); |
|
7337 0x23c: mov ax,0xaa |
|
7338 0x23f: push ax |
|
7339 0x240: call _printf |
|
7340 0x243: pop cx |
|
7341 5: exit(0); |
|
7342 0x244: xor ax,ax |
|
7343 0x246: push ax |
|
7344 0x247: call _exit |
|
7345 0x24a: pop cx |
|
7346 6: } |
|
7347 0x24b: pop bp |
|
7348 0x24c: ret |
|
7349 7: |
|
7350 0x24d: |
|
7351 .TE |
|
7352 .S +2 |
|
7353 .DE |
|
7354 .P |
|
7355 If the statement program prologue specifies the following: |
|
7356 .DS |
|
7357 .S -2 |
|
7358 .TS |
|
7359 ; |
|
7360 lf(CW) lf(CW). |
|
7361 minimum_instruction_length 1 |
|
7362 opcode_base 10 |
|
7363 line_base 1 |
|
7364 line_range 15 |
|
7365 .TE |
|
7366 .S +2 |
|
7367 .DE |
|
7368 .P |
|
7369 Then one encoding of the statement program would occupy 12 bytes |
|
7370 (the opcode \f(CWSPECIAL(\fIm\fP, \fIn\fP)\fR indicates the special |
|
7371 opcode generated for a line increment of \fIm\fP and an address increment |
|
7372 of \fIn\fP): |
|
7373 .DS |
|
7374 .S -2 |
|
7375 .TS |
|
7376 ; |
|
7377 l l l |
|
7378 lf(CW) lf(CW) lf(CW). |
|
7379 Opcode Operand Byte Stream |
|
7380 _ |
|
7381 DW_LNS_advance_pc LEB128(0x239) 0x2, 0xb9, 0x04 |
|
7382 SPECIAL(2, 0) 0xb |
|
7383 SPECIAL(2, 3) 0x38 |
|
7384 SPECIAL(1, 8) 0x82 |
|
7385 SPECIAL(1, 7) 0x73 |
|
7386 DW_LNS_advance_pc LEB128(2) 0x2, 0x2 |
|
7387 DW_LNE_end_sequence 0x0, 0x1, 0x1 |
|
7388 .TE |
|
7389 .S +2 |
|
7390 .DE |
|
7391 .P |
|
7392 An alternate encoding of the same program using standard opcodes to |
|
7393 advance the program counter would occupy 22 bytes: |
|
7394 .DS |
|
7395 .S -2 |
|
7396 .TS |
|
7397 ; |
|
7398 l l l |
|
7399 lf(CW) lf(CW) lf(CW). |
|
7400 Opcode Operand Byte Stream |
|
7401 _ |
|
7402 DW_LNS_fixed_advance_pc 0x239 0x9, 0x39, 0x2 |
|
7403 SPECIAL(2, 0) 0xb |
|
7404 DW_LNS_fixed_advance_pc 0x3 0x9, 0x3, 0x0 |
|
7405 SPECIAL(2, 0) 0xb |
|
7406 DW_LNS_fixed_advance_pc 0x8 0x9, 0x8, 0x0 |
|
7407 SPECIAL(1, 0) 0xa |
|
7408 DW_LNS_fixed_advance_pc 0x7 0x9, 0x7, 0x0 |
|
7409 SPECIAL(1, 0) 0xa |
|
7410 DW_LNS_fixed_advance_pc 0x2 0x9, 0x2, 0x0 |
|
7411 DW_LNE_end_sequence 0x0, 0x1, 0x1 |
|
7412 .TE |
|
7413 .S +2 |
|
7414 .DE |
|
7415 .SK |
|
7416 .OP |
|
7417 .HU "Appendix 4 -- Encoding and decoding variable length data" |
|
7418 .ta .5i +.5i +.5i +.5i +.5i +.5i +.5i +.5i |
|
7419 .P |
|
7420 Here are algorithms expressed in a C-like pseudo-code to encode and decode |
|
7421 signed and unsigned numbers in LEB128: |
|
7422 .P |
|
7423 \fBEncode an unsigned integer:\fP |
|
7424 .br |
|
7425 .DS |
|
7426 .S -2 |
|
7427 \f(CWdo |
|
7428 { |
|
7429 byte = low order 7 bits of value; |
|
7430 value >>= 7; |
|
7431 if (value != 0) /* more bytes to come */ |
|
7432 set high order bit of byte; |
|
7433 emit byte; |
|
7434 } while (value != 0);\fP |
|
7435 .S +2 |
|
7436 .DE |
|
7437 .P |
|
7438 \fBEncode a signed integer:\fP |
|
7439 .br |
|
7440 .DS |
|
7441 .S -2 |
|
7442 \f(CWmore = 1; |
|
7443 negative = (value < 0); |
|
7444 size = no. of bits in signed integer; |
|
7445 while(more) |
|
7446 { |
|
7447 byte = low order 7 bits of value; |
|
7448 value >>= 7; |
|
7449 /* the following is unnecessary if the implementation of >>= |
|
7450 * uses an arithmetic rather than logical shift for a signed |
|
7451 * left operand |
|
7452 */ |
|
7453 if (negative) |
|
7454 /* sign extend */ |
|
7455 value |= - (1 << (size - 7)); |
|
7456 /* sign bit of byte is 2nd high order bit (0x40) */ |
|
7457 if ((value == 0 && sign bit of byte is clear) || |
|
7458 (value == -1 && sign bit of byte is set)) |
|
7459 more = 0; |
|
7460 else |
|
7461 set high order bit of byte; |
|
7462 emit byte; |
|
7463 }\fP |
|
7464 .S +2 |
|
7465 .DE |
|
7466 .SK |
|
7467 .ta .5i +.5i +.5i +.5i +.5i +.5i +.5i +.5i |
|
7468 .P |
|
7469 \fBDecode unsigned LEB128 number:\fP |
|
7470 .br |
|
7471 .DS |
|
7472 .S -2 |
|
7473 \f(CWresult = 0; |
|
7474 shift = 0; |
|
7475 while(true) |
|
7476 { |
|
7477 byte = next byte in input; |
|
7478 result |= (low order 7 bits of byte << shift); |
|
7479 if (high order bit of byte == 0) |
|
7480 break; |
|
7481 shift += 7; |
|
7482 }\fP |
|
7483 .S +2 |
|
7484 .DE |
|
7485 .P |
|
7486 \fBDecode signed LEB128 number:\fP |
|
7487 .br |
|
7488 .DS |
|
7489 .S -2 |
|
7490 \f(CWresult = 0; |
|
7491 shift = 0; |
|
7492 size = no. of bits in signed integer; |
|
7493 while(true) |
|
7494 { |
|
7495 byte = next byte in input; |
|
7496 result |= (low order 7 bits of byte << shift); |
|
7497 shift += 7; |
|
7498 /* sign bit of byte is 2nd high order bit (0x40) */ |
|
7499 if (high order bit of byte == 0) |
|
7500 break; |
|
7501 } |
|
7502 if ((shift < size) && (sign bit of byte is set)) |
|
7503 /* sign extend */ |
|
7504 result |= - (1 << shift);\fP |
|
7505 .S +2 |
|
7506 .DE |
|
7507 .SK |
|
7508 .OP |
|
7509 .HU "Appendix 5 -- Call Frame Information Examples" |
|
7510 The following example uses a hypothetical RISC machine in the style of |
|
7511 the Motorola 88000. |
|
7512 .BL |
|
7513 .LI |
|
7514 Memory is byte addressed. |
|
7515 .LI |
|
7516 Instructions are all 4-bytes each and word aligned. |
|
7517 .LI |
|
7518 Instruction operands are typically of the form: |
|
7519 .br |
|
7520 .DS |
|
7521 <destination reg> <source reg> <constant> |
|
7522 .DE |
|
7523 .LI |
|
7524 The address for the load and store instructions is computed by |
|
7525 adding the contents of the source register with the constant. |
|
7526 .LI |
|
7527 There are 8 4-byte registers: |
|
7528 .br |
|
7529 .DS |
|
7530 R0 always 0 |
|
7531 R1 holds return address on call |
|
7532 R2-R3 temp registers (not preserved on call) |
|
7533 R4-R6 preserved on call |
|
7534 R7 stack pointer. |
|
7535 .DE |
|
7536 .LI |
|
7537 The stack grows in the negative direction. |
|
7538 .LE |
|
7539 .P |
|
7540 The following are two code fragments from a subroutine |
|
7541 called \f(CWfoo\fP that |
|
7542 uses a frame pointer (in addition to the stack pointer.) The first |
|
7543 column values are byte addresses. |
|
7544 .DS |
|
7545 .S -2 |
|
7546 .TS |
|
7547 ; |
|
7548 lf(CW) lf(CW) s s |
|
7549 lf(CW) lf(CW) lf(CW) lf(CW) |
|
7550 lf(CW) lf(CW) lf(CW) lf(CW) |
|
7551 lf(CW) lf(CW) lf(CW) lf(CW) |
|
7552 lf(CW) lf(CW) lf(CW) lf(CW) |
|
7553 lf(CW) lf(CW) lf(CW) lf(CW) |
|
7554 lf(CW) lf(CW) s s |
|
7555 lf(CW) lf(CW) s s |
|
7556 lf(CW) lf(CW) s s |
|
7557 lf(CW) lf(CW) lf(CW) lf(CW). |
|
7558 ;; start prologue |
|
7559 foo sub R7, R7, <fsize> ; Allocate frame |
|
7560 foo+4 store R1, R7, (<fsize>-4) ; Save the return address |
|
7561 foo+8 store R6, R7, (<fsize>-8) ; Save R6 |
|
7562 foo+12 add R6, R7, 0 ; R6 is now the Frame ptr |
|
7563 foo+16 store R4, R6, (<fsize>-12) ; Save a preserve reg. |
|
7564 ;; This subroutine does not change R5 |
|
7565 ... |
|
7566 ;; Start epilogue (R7 has been returned to entry value) |
|
7567 foo+64 load R4, R6, (<fsize>-12) ; Restore R4 |
|
7568 foo+68 load R6, R7, (<fsize>-8) ; Restore R6 |
|
7569 foo+72 load R1, R7, (<fsize>-4) ; Restore return address |
|
7570 foo+76 add R7, R7, <fsize> ; Deallocate frame |
|
7571 foo+80 jump R ; Return |
|
7572 foo+84 |
|
7573 .TE |
|
7574 .S +2 |
|
7575 .DE |
|
7576 .SK |
|
7577 The table for the \f(CWfoo\fP subroutine is as follows. |
|
7578 It is followed by the |
|
7579 corresponding fragments from the |
|
7580 .Cf .debug_frame |
|
7581 section. |
|
7582 .DS |
|
7583 .S -2 |
|
7584 .TS |
|
7585 tab(|); |
|
7586 lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) lf(CW) lf(CW). |
|
7587 Loc|CFA|R0|R1|R2|R3|R4|R5|R6|R7|R8 |
|
7588 foo|[R7]+0|s|u|u|u|s|s|s|s|r1 |
|
7589 foo+4|[R7]+fsize|s|u|u|u|s|s|s|s|r1 |
|
7590 foo+8|[R7]+fsize|s|u|u|u|s|s|s|s|c4 |
|
7591 foo+12|[R7]+fsize|s|u|u|u|s|s|c8|s|c4 |
|
7592 foo+16|[R6]+fsize|s|u|u|u|s|s|c8|s|c4 |
|
7593 foo+20|[R6]+fsize|s|u|u|u|c12|s|c8|s|c4 |
|
7594 ... |
|
7595 foo+64|[R6]+fsize|s|u|u|u|c12|s|c8|s|c4 |
|
7596 foo+68|[R6]+fsize|s|u|u|u|s|s|c8|s|c4 |
|
7597 foo+72|[R7]+fsize|s|u|u|u|s|s|s|s|c4 |
|
7598 foo+76|[R7]+fsize|s|u|u|u|s|s|s|s|r1 |
|
7599 foo+80|[R7]+0|s|u|u|u|s|s|s|s|r1 |
|
7600 .TE |
|
7601 .TS |
|
7602 ; |
|
7603 l s |
|
7604 l l. |
|
7605 notes: |
|
7606 1. R8 is the return address |
|
7607 2. s = same_value rule |
|
7608 3. u = undefined rule |
|
7609 4. rN = register(N) rule |
|
7610 5. cN = offset(N) rule |
|
7611 .sp |
|
7612 .sp |
|
7613 .TE |
|
7614 .S +2 |
|
7615 .DE |
|
7616 .P |
|
7617 Common Information Entry (CIE): |
|
7618 .DS |
|
7619 .S -2 |
|
7620 .TS |
|
7621 ; |
|
7622 lf(CW) lf(CW) lf(CW). |
|
7623 cie 32 ; length |
|
7624 cie+4 0xffffffff ; CIE_id |
|
7625 cie+8 1 ; version |
|
7626 cie+9 0 ; augmentation |
|
7627 cie+10 4 ; code_alignment_factor |
|
7628 cie+11 4 ; data_alignment_factor |
|
7629 cie+12 8 ; R8 is the return addr. |
|
7630 cie+13 DW_CFA_def_cfa (7, 0) ; CFA = [R7]+0 |
|
7631 cie+16 DW_CFA_same_value (0) ; R0 not modified (=0) |
|
7632 cie+18 DW_CFA_undefined (1) ; R1 scratch |
|
7633 cie+20 DW_CFA_undefined (2) ; R2 scratch |
|
7634 cie+22 DW_CFA_undefined (3) ; R3 scratch |
|
7635 cie+24 DW_CFA_same_value (4) ; R4 preserve |
|
7636 cie+26 DW_CFA_same_value (5) ; R5 preserve |
|
7637 cie+28 DW_CFA_same_value (6) ; R6 preserve |
|
7638 cie+30 DW_CFA_same_value (7) ; R7 preserve |
|
7639 cie+32 DW_CFA_register (8, 1) ; R8 is in R1 |
|
7640 cie+35 DW_CFA_nop ; padding |
|
7641 cie+36 |
|
7642 .TE |
|
7643 .S +2 |
|
7644 .DE |
|
7645 .SK |
|
7646 .P |
|
7647 Frame Description Entry (FDE): |
|
7648 .DS |
|
7649 .S -2 |
|
7650 .TS |
|
7651 ; |
|
7652 lf(CW) lf(CW) lf(CW). |
|
7653 fde 40 ; length |
|
7654 fde+4 cie ; CIE_ptr |
|
7655 fde+8 foo ; initial_location |
|
7656 fde+12 84 ; address_range |
|
7657 fde+16 DW_CFA_advance_loc(1) ; instructions |
|
7658 fde+17 DW_CFA_def_cfa_offset(<fsize>/4) ; assuming <fsize> < 512 |
|
7659 fde+19 DW_CFA_advance_loc(1) |
|
7660 fde+20 DW_CFA_offset(8,1) |
|
7661 fde+22 DW_CFA_advance_loc(1) |
|
7662 fde+23 DW_CFA_offset(6,2) |
|
7663 fde+25 DW_CFA_advance_loc(1) |
|
7664 fde+26 DW_CFA_def_cfa_register(6) |
|
7665 fde+28 DW_CFA_advance_loc(1) |
|
7666 fde+29 DW_CFA_offset(4,3) |
|
7667 fde+31 DW_CFA_advance_loc(11) |
|
7668 fde+32 DW_CFA_restore(4) |
|
7669 fde+33 DW_CFA_advance_loc(1) |
|
7670 fde+34 DW_CFA_restore(6) |
|
7671 fde+35 DW_CFA_def_cfa_register(7) |
|
7672 fde+37 DW_CFA_advance_loc(1) |
|
7673 fde+38 DW_CFA_restore(8) |
|
7674 fde+39 DW_CFA_advance_loc(1) |
|
7675 fde+40 DW_CFA_def_cfa_offset(0) |
|
7676 fde+42 DW_CFA_nop ; padding |
|
7677 fde+43 DW_CFA_nop ; padding |
|
7678 fde+44 |
|
7679 .TE |
|
7680 .S +2 |
|
7681 .DE |
|
7682 .S +1 |
|
7683 |
|
7684 '\" |
|
7685 '\" Table of Contents stuff |
|
7686 '\" |
|
7687 .de TP |
|
7688 .sp 4 |
|
7689 .. |
|
7690 .VM |
|
7691 .de TY |
|
7692 .ce 1 |
|
7693 Table of Contents |
|
7694 .sp |
|
7695 .. |
|
7696 .nr Lf 1 |
|
7697 .ds Lf List of Figures |
|
7698 .SK |
|
7699 .TC 1 1 7 0 |