1 \chapter{Program Scope Entries}
2 \label{chap:programscopeentries}
3 This section describes debugging information entries that
4 relate to different levels of program scope: compilation,
5 module, subprogram, and so on. Except for separate type
6 entries (see Section \refersec{chap:separatetypeunitentries}),
7 these entries may be thought of
8 as bounded by ranges of text addresses within the program.
10 \section{Unit Entries}
11 An object file may contain one or more compilation units,
13 \addtoindexx{unit|see {compilation unit, partial unit \textit{or} type unit}}
14 \addtoindexx{compilation unit}
16 \addtoindexx{normal compilation unit}
17 \addtoindexx{normal compilation unit|see {compilation unit}}
18 normal compilation units,
19 partial compilation units and
20 \addtoindexx{type unit}
22 \addtoindex{partial compilation unit}
23 is related to one or more other compilation units that
25 \addtoindex{type unit} represents
26 a single complete type in a
27 separate unit. Either a normal compilation unit or a
28 \addtoindex{partial compilation unit}
29 may be logically incorporated into another
30 compilation unit using an
31 \addtoindex{imported unit entry}.
34 \subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
35 \label{chap:normalandpartialcompilationunitentries}
37 A \addtoindex{normal compilation unit} is represented by a debugging
38 information entry with the
39 tag \DWTAGcompileunitTARG.
40 A \addtoindex{partial compilation unit} is represented by a debugging information
42 tag \DWTAGpartialunitTARG.
44 In a simple normal compilation, a single compilation unit with
46 \DWTAGcompileunit{} represents a complete object file
48 \DWTAGpartialunit{} is not used.
50 employing the DWARF space compression and duplicate elimination
52 Appendix \refersec{app:usingcompilationunits},
53 multiple compilation units using
55 \DWTAGcompileunit{} and/or
56 \DWTAGpartialunit{} are
57 used to represent portions of an object file.
59 \textit{A normal compilation unit typically represents the text and
60 data contributed to an executable by a single relocatable
61 object file. It may be derived from several source files,
62 including pre\dash processed \doublequote{include files.}
63 A \addtoindex{partial compilation unit} typically represents a part of the text
64 and data of a relocatable object file, in a manner that can
65 potentially be shared with the results of other compilations
66 to save space. It may be derived from an \doublequote{include file,}
67 template instantiation, or other implementation\dash dependent
68 portion of a compilation. A normal compilation unit can also
69 function in a manner similar to a partial compilation unit
72 A compilation unit entry owns debugging information
73 entries that represent all or part of the declarations
74 made in the corresponding compilation. In the case of a
75 partial compilation unit, the containing scope of its owned
76 declarations is indicated by imported unit entries in one
77 or more other compilation unit entries that refer to that
78 partial compilation unit (see
79 Section \refersec{chap:importedunitentries}).
82 Compilation unit entries may have the following
84 \begin{enumerate}[1. ]
85 \item Either a \DWATlowpc{} and
87 \addtoindexx{high PC attribute}
89 \addtoindexx{low PC attribute}
91 \addtoindexx{ranges attribute}
93 \DWATranges{} attribute
94 \addtoindexx{ranges attribute}
96 \addtoindexx{discontiguous address ranges|see{non-contiguous address ranges}}
99 non\dash contiguous address ranges, respectively,
100 of the machine instructions generated for the compilation
101 unit (see Section \refersec{chap:codeaddressesandranges}).
103 A \DWATlowpc{} attribute
107 \addtoindexx{ranges attribute}
109 \DWATranges{} to specify the
110 \addtoindexx{ranges attribute}
111 default base address for use in
112 \addtoindexx{location list}
113 location lists (see Section
114 \refersec{chap:locationlists}) and range lists
115 \addtoindexx{range list}
116 (see Section \refersec{chap:noncontiguousaddressranges}).
118 \item A \DWATname{} attribute
119 \addtoindexx{name attribute}
120 whose value is a null\dash terminated
122 \hypertarget{chap:DWATnamepathnameofcompilationsource}{}
123 containing the full or relative path name of the primary
124 source file from which the compilation unit was derived.
126 \item A \DWATlanguage{} attribute
127 \addtoindexx{language attribute}
128 whose constant value is an
129 \hypertarget{chap:DWATlanguageprogramminglanguage}{}
131 \addtoindexx{language attribute}
132 indicating the source language of the compilation
133 unit. The set of language names and their meanings are given
134 in Table \refersec{tab:languagenames}.
138 \caption{Language names}
139 \label{tab:languagenames}
142 Language name & Meaning\\ \hline
143 \addtoindexx{ISO-defined language names}
144 \DWLANGAdaeightythreeTARG{} \dag & ISO Ada:1983 \addtoindexx{Ada:1983 (ISO)} \\
145 \DWLANGAdaninetyfiveTARG{} \dag & ISO Ada:1995 \addtoindexx{Ada:1995 (ISO)} \\
146 \DWLANGCTARG & Non-standardized C, such as K\&R \addtoindexx{C!non-standard}\\
147 \DWLANGCeightynineTARG & ISO C:1989 \addtoindexx{C:1989 (ISO)} \\
148 \DWLANGCninetynineTARG & ISO C:1999 \addtoindexx{C:1999 (ISO)} \\
149 \DWLANGCelevenTARG & ISO C:2011 \addtoindexx{C:2011 (ISO)} \\
150 \DWLANGCplusplusTARG & ISO C++:1998 \addtoindexx{C++:1998 (ISO)} \\
151 \DWLANGCpluspluszerothreeTARG & ISO C++:2003 \addtoindexx{C++:2003 (ISO)} \\
152 \DWLANGCpluspluselevenTARG & ISO C++:2011 \addtoindexx{C++:2011 (ISO)} \\
153 \DWLANGCobolseventyfourTARG & ISO COBOL:1974 \addtoindexx{COBOL:1974 (ISO)} \\
154 \DWLANGCoboleightyfiveTARG & ISO COBOL:1985 \addtoindexx{COBOL:1985 (ISO)} \\
155 \DWLANGDTARG{}~\dag & D \addtoindexx{D language} \\
156 \DWLANGDylanTARG~\dag & Dylan \addtoindexx{Dylan language} \\
157 \DWLANGFortranseventysevenTARG & ISO FORTRAN:1977 \addtoindexx{FORTRAN:1977 (ISO)} \\
158 \DWLANGFortranninetyTARG & ISO Fortran:1990 \addtoindexx{Fortran:1990 (ISO)} \\
159 \DWLANGFortranninetyfiveTARG & ISO Fortran:1995 \addtoindexx{Fortran:1995 (ISO)} \\
160 \DWLANGGoTARG{}~\dag & \addtoindex{Go} \\
161 \DWLANGHaskellTARG{} \dag & \addtoindex{Haskell} \\
162 \DWLANGJavaTARG{} & \addtoindex{Java}\\
163 \DWLANGJuliaTARG{}~\dag & \addtoindex{Julia} \\
164 \DWLANGModulatwoTARG & ISO Modula\dash 2:1996 \addtoindexx{Modula-2:1996 (ISO)} \\
165 \DWLANGModulathreeTARG & \addtoindex{Modula-3} \\
166 \DWLANGObjCTARG{} & \addtoindex{Objective C} \\
167 \DWLANGObjCplusplusTARG{} & \addtoindex{Objective C++} \\
168 \DWLANGOCamlTARG{}~\dag & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}} \\
169 \DWLANGOpenCLTARG{}~\dag & \addtoindex{OpenCL} \\
170 \DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\
171 \DWLANGPLITARG{}~\dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
172 \DWLANGPythonTARG{}~\dag & \addtoindex{Python} \\
173 \DWLANGRustTARG{}~\dag & \addtoindex{Rust} \\
174 \DWLANGSwiftTARG{}~\dag & \addtoindex{Swift} \\
175 \DWLANGUPCTARG{} & UPC (Unified Parallel C) \addtoindexx{UPC}
176 \index{Unified Parallel C|see{UPC}} \\
178 \dag \ \ \textit{Support for these languages is limited}& \\
182 \item A \DWATstmtlist{}
183 attribute whose value is
184 \addtoindexx{statement list attribute}
186 \addtoindexx{section offset!in statement list attribute}
188 \hypertarget{chap:DWATstmtlistlinenumberinformationforunit}{}
189 offset to the line number information for this compilation
192 This information is placed in a separate object file
193 section from the debugging information entries themselves. The
194 value of the statement list attribute is the offset in the
195 \dotdebugline{} section of the first byte of the line number
196 information for this compilation unit
197 (see Section \refersec{chap:linenumberinformation}).
202 \item A \DWATmacros{} attribute
203 \addtoindexx{macro information attribute}
205 \addtoindexx{section offset!in macro information attribute}
207 \hypertarget{chap:DWATmacrosmacroinformation}{}
208 offset to the macro information for this compilation unit.
210 This information is placed in a separate object file section
211 from the debugging information entries themselves. The
212 value of the macro information attribute is the offset in
213 the \dotdebugmacro{} section of the first byte of the macro
214 information for this compilation unit
215 (see Section \refersec{chap:macroinformation}).
217 \textit{The \DWATmacros{} attribute is new in \DWARFVersionV,
219 \DWATmacroinfo{} attribute of earlier DWARF versions.
220 \livetarg{chap:DWATmacroinfomacroinformation}{}
221 While \DWATmacros{} and \DWATmacroinfo{} attributes cannot both occur in the same
222 compilation unit, both may be found in the set of units that make up an executable
223 or shared object. The two attributes have distinct encodings to facilitate such
230 \hypertarget{chap:DWATcompdircompilationdirectory}{}
232 null\dash terminated string containing the current working directory
233 of the compilation command that produced this compilation
234 unit in whatever form makes sense for the host system.
236 \item A \DWATproducer{} attribute
237 \addtoindexx{producer attribute}
238 whose value is a null\dash
239 terminated string containing information about the compiler
240 \hypertarget{chap:DWATproducercompileridentification}{}
241 that produced the compilation unit. The actual contents of
242 the string will be specific to each producer, but should
243 begin with the name of the compiler vendor or some other
244 identifying character sequence that should avoid confusion
245 with other producer values.
248 \item A \DWATidentifiercase{}
250 \addtoindexx{identifier case attribute}
252 \hypertarget{chap:DWATidentifiercaseidentifiercaserule}{}
253 constant value is a code describing the treatment
254 of identifiers within this compilation unit. The
255 set of identifier case codes is given in
256 Table \refersec{tab:identifiercasecodes}.
258 \begin{simplenametable}{Identifier case codes}{tab:identifiercasecodes}
259 \DWIDcasesensitive{} \\
262 \DWIDcaseinsensitive{} \\
263 \end{simplenametable}
265 \DWIDcasesensitiveTARG{} is the default for all compilation units
266 that do not have this attribute. It indicates that names given
267 as the values of \DWATname{} attributes
268 \addtoindexx{name attribute}
269 in debugging information
270 entries for the compilation unit reflect the names as they
271 appear in the source program. The debugger should be sensitive
272 to the case of identifier names when doing identifier lookups.
275 \DWIDupcaseTARG{} means that the
276 producer of the debugging
277 information for this compilation unit converted all source
278 names to upper case. The values of the name attributes may not
279 reflect the names as they appear in the source program. The
280 debugger should convert all names to upper case when doing
283 \DWIDdowncaseTARG{} means that
284 the producer of the debugging
285 information for this compilation unit converted all source
286 names to lower case. The values of the name attributes may not
287 reflect the names as they appear in the source program. The
288 debugger should convert all names to lower case when doing
292 \DWIDcaseinsensitiveTARG{} means that the values of the name
293 attributes reflect the names as they appear in the source
294 program but that a case insensitive lookup should be used to
298 \item A \DWATbasetypes{} attribute whose value is a
299 \livelink{chap:classreference}{reference}.
302 \hypertarget{chap:DWATbasetypesprimitivedatatypesofcompilationunit}{}
304 \addtoindexx{base types attribute}
305 points to a debugging information entry
306 representing another compilation unit. It may be used
307 to specify the compilation unit containing the base type
308 entries used by entries in the current compilation unit
309 (see Section \refersec{chap:basetypeentries}).
312 This attribute provides a consumer a way to find the definition
313 of base types for a compilation unit that does not itself
314 contain such definitions. This allows a consumer, for example,
315 to interpret a type conversion to a base type
316 % getting this link target at the right spot is tricky.
317 \hypertarget{chap:DWATuseUTF8compilationunitusesutf8strings}{}
320 \item A \DWATuseUTFeight{} attribute,
321 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8}
322 which is a \livelink{chap:classflag}{flag} whose
323 presence indicates that all strings (such as the names of
324 declared entities in the source program, or file names in the line table)
325 are represented using the UTF\dash 8 representation.
327 \item A \DWATmainsubprogram{} attribute, which is a \livelink{chap:classflag}{flag}
328 \addtoindexx{main subprogram attribute}
329 whose presence indicates
330 \hypertarget{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}{}
331 that the compilation unit contains a
332 subprogram that has been identified as the starting function
333 of the program. If more than one compilation unit contains
334 this \nolink{flag}, any one of them may contain the starting function.
336 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement}
338 to specify and provide a user\dash specified name for the main
339 subroutine of a program.
340 \addtoindex{C} uses the name \doublequote{main} to identify
341 the main subprogram of a program. Some other languages provide
342 similar or other means to identify the main subprogram of
345 \item A \DWATentrypc{} attribute whose value is the address of the first
346 \hypertarget{chap:DWATentrypcofcompileunit}{}
347 \hypertarget{chap:DWATentrypcofpartialunit}{}
348 \addtoindexx{entry pc attribute!for normal compilation unit}
349 \addtoindexx{entry pc attribute!for partial compilation unit}
350 executable instruction of the unit (see
351 Section \refersec{chap:entryaddress}).
353 \item A \DWATstroffsetsbaseNAME\addtoindexx{string offset base attribute}
354 \hypertarget{chap:DWATstroffsetbaseforindirectstringtable}{}
355 attribute, whose value is a reference.
356 This attribute points to the first string
357 offset of the compilation unit's contribution to the
358 \dotdebugstroffsets{} (or \dotdebugstroffsetsdwo{}) section.
359 Indirect string references
360 (using \DWFORMstrx) within the compilation unit are
361 interpreted as indices relative to this base.
364 \item A \DWATaddrbaseNAME\addtoindexx{address table base attribute}
365 \hypertarget{chap:DWATaddrbaseforaddresstable}{}
366 attribute, whose value is a reference.
367 This attribute points to the beginning of the compilation
368 unit's contribution to the \dotdebugaddr{} section.
369 Indirect references (using \DWFORMaddrx, \DWOPaddrx,
370 \DWOPconstx, \DWLLEbaseaddressselectionentry{},
371 \DWLLEstartendentry, or \DWLLEstartlengthentry) within the compilation unit are
372 interpreted as indices relative to this base.
375 \item A \DWATrangesbaseNAME\addtoindexx{ranges table base attribute}
376 \hypertarget{chap:DWATrangesbaseforrangelists}{}
377 attribute, whose value is a reference.
378 This attribute points to the beginning of the compilation
379 unit's contribution to the \dotdebugranges{} section.
380 References to range lists (using \DWFORMsecoffset)
381 within the compilation unit are
382 interpreted as offsets relative to this base.
387 The base address of a compilation unit is defined as the
388 value of the \DWATlowpc{} attribute, if present; otherwise,
389 it is undefined. If the base address is undefined, then any
390 DWARF entry or structure defined in terms of the base address
391 of that compilation unit is not valid.
393 \subsection{Skeleton Compilation Unit Entries}
394 \label{chap:skeletoncompilationunitentries}
395 When generating a split DWARF object (see
396 Section \refersec{datarep:splitdwarfobjects}), the
397 compilation unit in the \dotdebuginfo{} section is a "skeleton"
398 compilation unit, which contains only a subset of the
399 attributes of the full compilation unit. In general, it
400 contains those attributes that are necessary for the consumer
401 to locate the DWARF object where the full compilation unit
402 can be found, and for the consumer to interpret references to
403 addresses in the program.
405 A skeleton compilation unit has no
406 children, and may have the following attributes:
407 \begin{enumerate}[1. ]
410 Either a \DWATlowpc{} and \DWAThighpc{} pair of attributes
411 or a \DWATranges{} attribute (the same as for regular
412 compilation unit entries).
415 A \DWATstmtlist{} attribute (the same as for regular
416 compilation unit entries).
419 A \DWATcompdir{} attribute (the same as for regular
420 compilation unit entries).
423 \livetarg{chap:DWATdwonameforunit}{}
424 A \DWATdwonameNAME{} attribute whose value is a
425 null-terminated string containing the full or relative
426 path name of the DWARF object file that contains the full
430 \livetarg{chap:DWATdwoidforunit}{}
431 A \DWATdwoidNAME{} attribute whose value is an 8-byte
432 unsigned hash of the full compilation unit. This hash
433 value is computed by the method described in
434 Section \refersec{datarep:typesignaturecomputation}.
438 A \DWATuseUTFeight{} attribute (the same as for regular compilation unit
441 \textit{This attribute applies to strings referred to by the skeleton
442 compilation unit entry itself, and strings in the associated line
444 The representation for strings in the DWARF object file is determined
445 by the presence of a \DWATuseUTFeight{} attribute in the full compilation
449 A \DWATstroffsetsbase{} attribute, for indirect strings references
450 from the skeleton compilation unit (the same as for regular
451 compilation unit entries).
454 A \DWATaddrbase{} attribute (the same as for regular
455 compilation unit entries).
458 A \DWATrangesbase{} attribute (the same as for regular
459 compilation unit entries).
463 All other attributes of a compilation unit entry (described
464 in Section \refersec{chap:normalandpartialcompilationunitentries})
465 should be placed in the full compilation
466 unit entry in the \dotdebuginfodwo{} section of the split DWARF
467 object. The attributes provided by the skeleton compilation
468 unit entry do not need to be repeated in the full compilation
469 unit entry, except for \DWATdwoid, which should appear in
470 both entries so that the consumer can verify that it has
471 found the correct DWARF object.
474 \subsection{Imported Unit Entries}
475 \label{chap:importedunitentries}
477 \hypertarget{chap:DWATimportimportedunit}{}
478 place where a normal or partial unit is imported is
479 represented by a debugging information entry with the
480 \addtoindexx{imported unit entry}
481 tag \DWTAGimportedunitTARG.
482 An imported unit entry contains
483 \addtoindexx{import attribute}
485 \DWATimport{} attribute
486 whose value is a \livelink{chap:classreference}{reference} to the
487 normal or partial compilation unit whose declarations logically
488 belong at the place of the imported unit entry.
490 \textit{An imported unit entry does not necessarily correspond to
491 any entity or construct in the source program. It is merely
492 \doublequote{glue} used to relate a partial unit, or a compilation
493 unit used as a partial unit, to a place in some other
497 \subsection{Separate Type Unit Entries}
498 \label{chap:separatetypeunitentries}
499 An object file may contain any number of separate type
500 unit entries, each representing a single complete type
502 Each \addtoindex{type unit} must be uniquely identified by
503 a 64\dash bit signature, stored as part of the type unit, which
504 can be used to reference the type definition from debugging
505 information entries in other compilation units and type units.
507 A type unit is represented by a debugging information entry
508 with the tag \DWTAGtypeunitTARG.
509 A \addtoindex{type unit entry} owns debugging
510 information entries that represent the definition of a single
511 type, plus additional debugging information entries that may
512 be necessary to include as part of the definition of the type.
514 A type unit entry may have a
515 \DWATlanguage{} attribute,
517 \addtoindexx{language attribute}
518 constant value is an integer code indicating the source
519 language used to define the type. The set of language names
520 and their meanings are given in Table \refersec{tab:languagenames}.
522 A type unit entry may have a
523 \DWATstroffsetsbase\addtoindexx{string base offset attribute}
524 attribute, whose value is a reference. This attribute points
525 to the first string offset of the type unit's contribution to
526 the \dotdebugstroffsets{} section. Indirect string references
527 (using \DWFORMstrx) within the type unit must be interpreted
528 as indices relative to this base.
530 A type unit entry may have a \DWATstmtlist{} attribute, whose
531 value is a section offset to a line number table for this
532 type unit. Because type units do not describe any code, they
533 do not actually need a line number table, but the line number
534 tables also contain a list of directories and file names that
535 may be referenced by the \DWATdeclfile{} attribute. In a
536 normal object file with a regular compilation unit entry, the
537 type unit entries can simply refer to the line number table
538 used by the compilation unit. In a split DWARF object, where
539 the type units are located in a separate DWARF object file,
540 the \DWATstmtlist{} attribute refers to a "skeleton"
541 line number table in the \dotdebuglinedwo{} section, which
542 contains only the list of directories and file names. All
543 type unit entries in a split DWARF object may (but are not
544 required to) refer to the same skeleton line number table.
546 A type unit entry may have a \DWATuseUTFeight{} attribute, which is a flag
547 whose presence indicates that all strings referred to by this type
548 unit entry, its children, and the skeleton line number table, are
549 represented using the UTF-8 representation.
552 A \addtoindex{type unit} entry for a given type T owns a debugging
553 information entry that represents a defining declaration
554 of type T. If the type is nested within enclosing types or
555 namespaces, the debugging information entry for T is nested
556 within debugging information entries describing its containers;
557 otherwise, T is a direct child of the type unit entry.
559 A type unit entry may also own additional debugging information
560 entries that represent declarations of additional types that
561 are referenced by type T and have not themselves been placed in
562 separate type units. Like T, if an additional type U is nested
563 within enclosing types or namespaces, the debugging information
564 entry for U is nested within entries describing its containers;
565 otherwise, U is a direct child of the type unit entry.
567 The containing entries for types T and U are declarations,
568 and the outermost containing entry for any given type T or
569 U is a direct child of the type unit entry. The containing
570 entries may be shared among the additional types and between
571 T and the additional types.
573 \textit{Types are not required to be placed in type units. In general,
574 only large types such as structure, class, enumeration, and
575 union types included from header files should be considered
576 for separate type units. Base types and other small types
577 are not usually worth the overhead of placement in separate
578 type units. Types that are unlikely to be replicated, such
579 as those defined in the main source file, are also better
580 left in the main compilation unit.}
582 \section{Module, Namespace and Importing Entries}
583 \textit{Modules and namespaces provide a means to collect related
584 entities into a single entity and to manage the names of
587 \subsection{Module Entries}
588 \label{chap:moduleentries}
589 \textit{Several languages have the concept of a \doublequote{module.}
590 \addtoindexx{Modula-2}
591 A Modula\dash 2 definition module
592 \addtoindexx{Modula-2!definition module}
593 may be represented by a module
595 \addtoindex{declaration attribute}
596 (\DWATdeclaration). A
597 \addtoindex{Fortran 90} module
598 \addtoindexx{Fortran!module (Fortran 90)}
599 may also be represented by a module entry
600 (but no declaration attribute is warranted because \addtoindex{Fortran}
601 has no concept of a corresponding module body).}
603 A module is represented by a debugging information entry
605 tag \DWTAGmoduleTARG.
606 Module entries may own other
607 debugging information entries describing program entities
608 whose declaration scopes end at the end of the module itself.
610 If the module has a name, the module entry has a
611 \DWATname{} attribute
612 \addtoindexx{name attribute}
613 whose value is a null\dash terminated string containing
614 the module name as it appears in the source program.
616 The \addtoindex{module entry} may have either a
620 \addtoindexx{high PC attribute}
622 \addtoindexx{low PC attribute}
624 \DWATranges{} attribute
625 \addtoindexx{ranges attribute}
626 whose values encode the contiguous or non\dash contiguous address
627 ranges, respectively, of the machine instructions generated for
628 the module initialization code
629 (see Section \refersec{chap:codeaddressesandranges}).
630 \hypertarget{chap:DWATentrypcentryaddressofmoduleinitialization}{}
632 \addtoindexx{entry pc attribute!for module initialization}
634 \DWATentrypc{} attribute whose value is the address of
635 the first executable instruction of that initialization code
636 (see Section \refersec{chap:entryaddress}).
639 \hypertarget{chap:DWATprioritymodulepriority}{}
640 the module has been assigned a priority, it may have
641 \addtoindexx{priority attribute}
643 \DWATpriority{} attribute.
644 The value of this attribute is a
645 reference to another debugging information entry describing
646 a variable with a constant value. The value of this variable
647 is the actual constant value of the module\textquoteright s priority,
648 represented as it would be on the target architecture.
650 \subsection{Namespace Entries}
651 \label{chap:namespaceentries}
652 \textit{\addtoindex{C++} has the notion of a namespace, which provides a way to
653 \addtoindexx{namespace (C++)}
654 implement name hiding, so that names of unrelated things
655 do not accidentally clash in the
656 \addtoindex{global namespace} when an
657 application is linked together.}
659 A namespace is represented by a debugging information entry
661 tag \DWTAGnamespaceTARG.
662 A namespace extension is
663 \hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{}
665 \DWTAGnamespace{} entry
667 \addtoindexx{extension attribute}
670 attribute referring to the previous extension, or if there
671 is no previous extension, to the original
673 entry. A namespace extension entry does not need to duplicate
674 information in a previous extension entry of the namespace
675 nor need it duplicate information in the original namespace
676 entry. (Thus, for a namespace with a name,
677 a \DWATname{} attribute
678 \addtoindexx{name attribute}
679 need only be attached directly to the original
680 \DWTAGnamespace{} entry.)
683 Namespace and namespace extension entries may own
684 \addtoindexx{namespace extension entry}
686 \addtoindexx{namespace declaration entry}
687 debugging information entries describing program entities
688 whose declarations occur in the namespace.
690 \textit{For \addtoindex{C++}, such
691 owned program entities may be declarations,
692 including certain declarations that are also object or
693 function definitions.}
695 If a type, variable, or function declared in a namespace is
696 defined outside of the body of the namespace declaration,
697 that type, variable, or function definition entry has a
698 \DWATspecification{} attribute
699 \addtoindexx{specification attribute}
700 whose value is a \livelink{chap:classreference}{reference} to the
701 debugging information entry representing the declaration of
702 the type, variable or function. Type, variable, or function
704 \DWATspecification{} attribute
705 \addtoindexx{specification attribute}
707 to duplicate information provided by the declaration entry
708 referenced by the specification attribute.
710 \textit{The \addtoindex{C++} \addtoindex{global namespace}
712 \addtoindexx{global namespace|see{namespace (C++), global}}
714 \addtoindexx{namespace (C++)!global}
716 \texttt{::f}, for example) is not explicitly represented in
717 DWARF with a namespace entry (thus mirroring the situation
718 in \addtoindex{C++} source).
719 Global items may be simply declared with no
720 reference to a namespace.}
722 \textit{The \addtoindex{C++}
723 compilation unit specific \doublequote{unnamed namespace} may
724 \addtoindexx{namespace (C++)!unnamed}
725 \addtoindexx{unnamed namespace|see {namespace (C++), unnamed}}
726 be represented by a namespace entry with no name attribute in
727 the original namespace declaration entry (and therefore no name
728 attribute in any namespace extension entry of this namespace).
731 \textit{A compiler emitting namespace information may choose to
732 explicitly represent namespace extensions, or to represent the
733 final namespace declaration of a compilation unit; this is a
734 quality\dash of\dash implementation issue and no specific requirements
735 are given here. If only the final namespace is represented,
736 \addtoindexx{namespace (C++)!using declaration}
737 it is impossible for a debugger to interpret using declaration
738 references in exactly the manner defined by the
739 \addtoindex{C++} language.
742 \textit{Emitting all namespace declaration information in all
743 compilation units can result in a significant increase in the
744 size of the debug information and significant duplication of
745 information across compilation units.
746 The \addtoindex{C++} namespace std,
748 \addtoindexx{namespace (C++)!std}
749 is large and will probably be referenced in
750 every \addtoindex{C++} compilation unit.
753 \textit{For a \addtoindex{C++} namespace example,
754 see Appendix \refersec{app:namespaceexample}.
759 \subsection{Imported (or Renamed) Declaration Entries}
760 \label{chap:importedorrenameddeclarationentries}
761 \textit{Some languages support the concept of importing into or making
762 accessible in a given unit declarations made in a different
763 module or scope. An imported declaration may sometimes be
768 imported declaration is represented by one or
769 \addtoindexx{imported declaration entry}
770 more debugging information entries with the
771 tag \DWTAGimporteddeclarationTARG.
773 \hypertarget{chap:DWATimportimporteddeclaration}{}
775 is imported, there is one imported declaration entry for
777 \addtoindexx{import attribute}
778 Each imported declaration entry has a
779 \DWATimport{} attribute,
780 whose value is a \livelink{chap:classreference}{reference} to the
781 debugging information entry representing the declaration that
784 An imported declaration may also have a
787 \addtoindexx{name attribute}
788 whose value is a null\dash terminated string containing the
789 name, as it appears in the source program, by which the
790 imported entity is to be known in the context of the imported
791 declaration entry (which may be different than the name of
792 the entity being imported). If no name is present, then the
793 name by which the entity is to be known is the same as the
794 name of the entity being imported.
796 An imported declaration entry with a name attribute may be
797 used as a general means to rename or provide an alias for
798 \addtoindexx{alias declaration|see{imported declaration entry}}
799 an entity, regardless of the context in which the importing
800 declaration or the imported entity occurs.
802 \textit{A \addtoindex{C++} namespace alias may be represented by an imported
803 \hypertarget{chap:DWATimportnamespacealias}{}
805 \addtoindexx{namespace (C++)!alias}
806 with a name attribute whose value is
807 a null\dash terminated string containing the alias name as it
808 appears in the source program and an import attribute whose
809 value is a \livelink{chap:classreference}{reference} to the applicable original namespace or
810 namespace extension entry.
813 \textit{A \addtoindex{C++} using declaration may be represented by one or more
814 \hypertarget{chap:DWATimportnamespaceusingdeclaration}{}
816 \addtoindexx{namespace (C++)!using declaration}
817 declaration entries. When the using declaration
818 refers to an overloaded function, there is one imported
819 declaration entry corresponding to each overloading. Each
820 imported declaration entry has no name attribute but it does
821 have an import attribute that refers to the entry for the
822 entity being imported. (\addtoindex{C++}
823 provides no means to \doublequote{rename}
824 an imported entity, other than a namespace).
827 \textit{A \addtoindex{Fortran} use statement
828 \addtoindexx{Fortran!use statement}
829 \addtoindexx{use statement|see {Fortran, use statement}}
830 with an \doublequote{only list} may be
831 represented by a series of imported declaration entries,
832 one (or more) for each entity that is imported. An entity
833 \addtoindexx{renamed declaration|see{imported declaration entry}}
834 that is renamed in the importing context may be represented
835 by an imported declaration entry with a name attribute that
836 specifies the new local name.
839 \subsection{Imported Module Entries}
840 \label{chap:importedmoduleentries}
842 \textit{Some languages support the concept of importing into or making
843 accessible in a given unit all of the declarations contained
844 within a separate module or namespace.
847 An imported module declaration is represented by a debugging
848 information entry with
849 \addtoindexx{imported module attribute}
851 \addtoindexx{imported module entry}
852 tag \DWTAGimportedmoduleTARG.
854 imported module entry contains a
855 \DWATimport{} attribute
856 \addtoindexx{import attribute}
857 whose value is a \livelink{chap:classreference}{reference}
858 to the module or namespace entry
859 containing the definition and/or declaration entries for
860 the entities that are to be imported into the context of the
861 imported module entry.
863 An imported module declaration may own a set of imported
864 declaration entries, each of which refers to an entry in the
865 module whose corresponding entity is to be known in the context
866 of the imported module declaration by a name other than its
867 name in that module. Any entity in the module that is not
868 renamed in this way is known in the context of the imported
869 module entry by the same name as it is declared in the module.
871 \textit{A \addtoindex{C++} using directive
872 \addtoindexx{namespace (C++)!using directive}
873 \addtoindexx{using directive|see {namespace (C++), using directive}}
874 may be represented by an imported module
875 \hypertarget{chap:DWATimportnamespaceusingdirective}{}
876 entry, with an import attribute referring to the namespace
877 entry of the appropriate extension of the namespace (which
878 might be the original namespace entry) and no owned entries.
881 \textit{A \addtoindex{Fortran} use statement
882 \addtoindexx{Fortran!use statement}
883 with a \doublequote{rename list} may be
884 represented by an imported module entry with an import
885 attribute referring to the module and owned entries
886 corresponding to those entities that are renamed as part of
890 \textit{A \addtoindex{Fortran} use statement
891 \addtoindexx{Fortran!use statement}
892 with neither a \doublequote{rename list} nor
893 an \doublequote{only list} may be represented by an imported module
894 entry with an import attribute referring to the module and
895 no owned child entries.
898 \textit{A use statement with an \doublequote{only list} is represented by a
899 series of individual imported declaration entries as described
900 in Section \refersec{chap:importedorrenameddeclarationentries}.
903 \textit{A \addtoindex{Fortran} use statement for an entity in a module that is
904 \addtoindexx{Fortran!use statement}
905 itself imported by a use statement without an explicit mention
906 may be represented by an imported declaration entry that refers
907 to the original debugging information entry. For example, given
924 \textit{the imported declaration entry for Q within module C refers
925 directly to the variable declaration entry for X in module A
926 because there is no explicit representation for X in module B.
929 \textit{A similar situation arises for a \addtoindex{C++} using declaration
930 \addtoindexx{namespace (C++)!using declaration}
931 \addtoindexx{using declaration|see {namespace (C++), using declaration}}
932 that imports an entity in terms of a namespace alias. See
933 Appendix \refersec{app:namespaceexample}
937 \section{Subroutine and Entry Point Entries}
938 \label{chap:subroutineandentrypointentries}
940 The following tags exist to describe
941 debugging information entries
942 \addtoindexx{function entry|see{subroutine entry}}
944 \addtoindexx{subroutine entry}
946 \addtoindexx{subprogram entry}
948 % FIXME: is entry point entry the right index 'entry'?
949 \addtoindexx{entry point entry}
952 \begin{tabular}{lp{9.0cm}}
953 \DWTAGsubprogramTARG{} & A subroutine or function \\
954 \DWTAGinlinedsubroutine{} & A particular inlined
955 \addtoindexx{inlined subprogram entry}
956 instance of a subroutine or function \\
957 \DWTAGentrypointTARG{} & An alternate entry point \\
962 \subsection{General Subroutine and Entry Point Information}
963 \label{chap:generalsubroutineandentrypointinformation}
964 The subroutine or entry point entry has a \DWATname{}
965 attribute whose value is a null-terminated string containing the
966 subroutine or entry point name as it appears in the source program.
967 It may also have a \DWATlinkagename{} attribute as
968 described in Section \refersec{chap:linkagenames}.
970 If the name of the subroutine described by an entry with the
971 \addtoindexx{subprogram entry}
972 tag \DWTAGsubprogram{}
973 is visible outside of its containing
974 \hypertarget{chap:DWATexternalexternalsubroutine}{}
975 compilation unit, that entry has
976 \addtoindexx{external attribute}
978 \DWATexternalNAME{} attribute,
979 which is a \livelink{chap:classflag}{flag}.
981 \textit{Additional attributes for functions that are members of a
982 class or structure are described in
983 Section \refersec{chap:memberfunctionentries}.
987 \hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}{}
990 \DWATmainsubprogramNAME{}
992 \addtoindexx{main subprogram attribute}
994 a \CLASSflag whose presence indicates that the
995 subroutine has been identified as the starting function of
996 the program. If more than one subprogram contains this
998 any one of them may be the starting subroutine of the program.
1000 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement}
1001 which is used to specify
1002 and provide a user\dash supplied name for the main subroutine of
1006 \textit{A common debugger feature is to allow the debugger user to call
1007 a subroutine within the subject program. In certain cases,
1008 however, the generated code for a subroutine will not obey
1009 the standard calling conventions for the target architecture
1010 and will therefore not be safe to call from within a debugger.
1013 A subroutine entry may
1014 \hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}{}
1016 \DWATcallingconventionNAME{}
1017 attribute, whose value is an
1018 \livelink{chap:classconstant}{integer constant}. The set of
1019 calling convention codes is given in
1020 Table \refersec{tab:callingconventioncodes}.
1022 \begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
1026 \end{simplenametable}
1028 If this attribute is not present, or its value is the constant
1029 \DWCCnormalTARG, then the subroutine may be safely called by
1030 obeying the \doublequote{standard} calling conventions of the target
1031 architecture. If the value of the calling convention attribute
1032 is the constant \DWCCnocallTARG, the subroutine does not obey
1033 standard calling conventions, and it may not be safe for the
1034 debugger to call this subroutine.
1036 If the semantics of the language of the compilation unit
1037 containing the subroutine entry distinguishes between ordinary
1038 subroutines and subroutines that can serve as the \doublequote{main
1039 program,} that is, subroutines that cannot be called
1040 directly according to the ordinary calling conventions,
1041 then the debugging information entry for such a subroutine
1042 may have a calling convention attribute whose value is the
1043 constant \DWCCprogramTARG.
1045 \textit{The \DWCCprogram{}
1046 value is intended to support \addtoindex{Fortran} main
1047 \addtoindexx{Fortran!main program}
1048 programs which in some implementations may not be callable
1049 or which must be invoked in a special way. It is not intended
1050 as a way of finding the entry address for the program.
1053 \textit{In \addtoindex{C}
1054 there is a difference between the types of functions
1055 declared using function prototype style declarations and
1056 those declared using non\dash prototype declarations.
1059 A subroutine entry declared with a function prototype style
1060 declaration may have
1061 \addtoindexx{prototyped attribute}
1063 \DWATprototypedNAME{} attribute, which is
1066 \textit{The \addtoindex{Fortran}
1067 language allows the keywords \texttt{elemental}, \texttt{pure}
1068 and \texttt{recursive} to be included as part of the declaration of
1069 a subroutine; these attributes reflect that usage. These
1070 attributes are not relevant for languages that do not support
1071 similar keywords or syntax. In particular, the \DWATrecursiveNAME{}
1072 attribute is neither needed nor appropriate in languages such
1074 where functions support recursion by default.
1078 \hypertarget{chap:DWATelementalelementalpropertyofasubroutine}{}
1080 \addtoindexx{elemental attribute}
1082 \DWATelementalNAME{} attribute, which
1083 is a \livelink{chap:classflag}{flag}.
1084 The attribute indicates whether the subroutine
1085 or entry point was declared with the \doublequote{elemental} keyword
1089 \hypertarget{chap:DWATpurepurepropertyofasubroutine}{}
1090 subprogram entry may have
1091 \addtoindexx{pure attribute}
1093 \DWATpureNAME{} attribute, which is
1094 a \livelink{chap:classflag}{flag}.
1095 The attribute indicates whether the subroutine was
1096 declared with the \doublequote{pure} keyword or property.
1099 \hypertarget{chap:DWATrecursiverecursivepropertyofasubroutine}{}
1100 subprogram entry may have a
1101 \DWATrecursiveNAME{} attribute, which
1102 is a \livelink{chap:classflag}{flag}.
1103 The attribute indicates whether the subroutine
1104 or entry point was declared with the \doublequote{recursive} keyword
1107 A subprogram entry may have a
1109 \livetargi{chap:DWATnoreturnofsubprogram}{ attribute}{noreturn attribute},
1110 which is a \CLASSflag. The attribute
1111 indicates whether the subprogram was declared with the \doublequote{noreturn} keyword or property
1112 indicating that the subprogram can be called, but will never return to its caller.
1114 \subsubsection{Call Site-Related Attributes}
1115 A subroutine entry may have \DWATcallalltailcalls, \DWATcallallcalls{}
1116 and/or \DWATcallallsourcecalls{} attributes, each of which is a
1117 \livelink{chap:classflag}{flag}.
1118 These flags indicate the completeness of the call site information
1119 within the subprogram.
1121 The \DWATcallalltailcallsNAME{}
1122 \livetargi{chap:DWATcallalltailcallsofasubprogram}{attribute}{all tail calls summary attribute}
1123 indicates that every tail call
1124 that occurs in the code for the subprogram is described by a
1125 \DWTAGcallsite{} entry.
1126 (There may or may not be other non-tail calls to some of the same
1127 target subprograms.)
1129 The \DWATcallallcallsNAME{}
1130 \livetargi{chap:DWATcallallcallsofasubprogram}{attribute}{all calls summary attribute}
1131 indicates that every non-inlined call
1132 (either a tail call or a normal call) that occurs in the code for the subprogram
1133 is described by a \DWTAGcallsite{} entry.
1135 The \DWATcallallsourcecallsNAME{}
1136 \livetargi{chap:DWATcallallsourcecallsofasubprogram}{attribute}{all source calls summary attribute}
1137 indicates that every call that occurs in the
1138 code for the subprogram, including every call inlined into it, is described by either a
1139 \DWTAGcallsite{} entry or a \DWTAGinlinedsubroutine{} entry; further, any call
1140 that is optimized out is nonetheless also described using a \DWTAGcallsite{} entry
1141 that has neither a \DWATcallpc{} nor \DWATcallreturnpc{} attribute.
1143 \textit{The \DWATcallallsourcecallsNAME{} attribute is intended for debugging
1144 information format consumers that analyse call graphs.}
1146 If the value of the \DWATcallallsourcecalls{} attribute is true then the values of the
1147 \DWATcallallcalls{} and \DWATcallallcalls{} attributes are necessarily also true, and
1148 those attributes need not be present. Similarly, if the value of the
1149 \DWATcallallcalls{} attribute is true then the value of the \DWATcallalltailcalls{}
1150 attribute is also true and the latter attribute need not be present.
1152 \subsection{Subroutine and Entry Point Return Types}
1153 \label{chap:subroutineandentrypointreturntypes}
1156 \hypertarget{chap:DWATtypetypeofsubroutinereturn}{}
1157 the subroutine or entry point
1158 \addtoindexx{return type of subroutine}
1159 is a function that returns a
1160 value, then its debugging information entry has
1161 \addtoindexx{type attribute}
1162 a \DWATtype{} attribute
1163 to denote the type returned by that function.
1165 \textit{Debugging information entries for
1166 \addtoindex{C} void functions should
1167 not have an attribute for the return type. }
1169 \textit{Debugging information entries for declarations of \addtoindex{C++}
1170 member functions with an
1171 \addtoindex{\texttt{auto} return type} specifier should use an unspecified
1173 Section \refersec{chap:unspecifiedtypeentries}).
1174 The debugging information entry for the corresponding definition
1175 should provide the deduced return type. This practice causes the description of
1176 the containing class to be consistent across compilation units, allowing the class
1177 declaration to be placed into a separate type unit if desired.}
1180 \subsection{Subroutine and Entry Point Locations}
1181 \label{chap:subroutineandentrypointlocations}
1183 A subroutine entry may have either a \DWATlowpc{} and
1184 \DWAThighpc{} pair of attributes or a \DWATranges{} attribute
1185 \addtoindexx{ranges attribute}
1187 \addtoindexx{high PC attribute}
1189 \addtoindexx{low PC attribute}
1190 encode the contiguous or non\dash contiguous address
1191 ranges, respectively, of the machine instructions generated
1192 for the subroutine (see
1193 Section \refersec{chap:codeaddressesandranges}).
1196 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}{}
1197 subroutine entry may also have
1198 \addtoindexx{entry pc attribute!for subroutine}
1200 \DWATentrypc{} attribute
1201 whose value is the address of the first executable instruction
1202 of the subroutine (see
1203 Section \refersec{chap:entryaddress}).
1205 An entry point has a \DWATlowpc{} attribute whose value is the
1206 relocated address of the first machine instruction generated
1207 for the entry point.
1210 \DWATentrypc{} attribute
1211 \addtoindexx{entry pc attribute!for subroutine}
1213 also seem appropriate
1214 for this purpose, historically the
1215 \DWATlowpc{} attribute
1217 \DWATentrypc{} was introduced (in
1218 \addtoindex{DWARF Version 3}).
1219 There is insufficient reason to change this.}
1225 \addtoindexx{address class!attribute}
1227 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}{}
1231 \DWATaddressclass{} attributes,
1232 as appropriate, to specify
1233 which segments the code for the subroutine resides in and
1234 the addressing mode to be used in calling that subroutine.
1236 A subroutine entry representing a subroutine declaration
1237 that is not also a definition does not have code address or
1241 \subsection{Declarations Owned by Subroutines and Entry Points}
1242 \label{chap:declarationsownedbysubroutinesandentrypoints}
1244 The declarations enclosed by a subroutine or entry point are
1245 represented by debugging information entries that are owned
1246 by the subroutine or entry point entry. Entries representing
1247 \addtoindexx{formal parameter}
1248 the formal parameters of the subroutine or entry point appear
1249 in the same order as the corresponding declarations in the
1253 \textit{There is no ordering requirement for entries for declarations
1254 that are children of subroutine or entry point entries but
1255 that do not represent formal parameters. The formal parameter
1256 entries may be interspersed with other entries used by formal
1257 parameter entries, such as type entries.}
1259 The unspecified parameters of a variable parameter list are
1260 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
1262 \DWTAGunspecifiedparametersTARG.
1265 The entry for a subroutine that includes a
1266 \addtoindex{Fortran}
1267 \addtoindexx{Fortran!common block}
1268 \livelink{chap:fortrancommonblock}{common}
1269 \livelink{chap:commonblockentry}{block}
1270 \addtoindexx{common block|see{Fortran common block}}
1271 has a child entry with the
1272 tag \DWTAGcommoninclusionTARG.
1274 \hypertarget{chap:commonreferencecommonblockusage}{}
1275 common inclusion entry has a
1276 \DWATcommonreference{} attribute
1277 whose value is a \livelink{chap:classreference}{reference}
1278 to the debugging information entry
1279 for the common \nolink{block} being included
1280 (see Section \refersec{chap:commonblockentries}).
1282 \subsection{Low-Level Information}
1283 \label{chap:lowlevelinformation}
1286 \hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{}
1287 subroutine or entry point entry may have
1288 \addtoindexx{return address attribute}
1291 attribute, whose value is a location description. The location
1292 calculated is the place where the return address for the
1293 subroutine or entry point is stored.
1296 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}{}
1297 subroutine or entry point entry may also have
1298 \addtoindexx{frame base attribute}
1300 \DWATframebase{} attribute, whose value is a location
1301 description that computes the \doublequote{frame base} for the
1302 subroutine or entry point. If the location description is
1303 a simple register location description, the given register
1304 contains the frame base address. If the location description is
1305 a DWARF expression, the result of evaluating that expression
1306 is the frame base address. Finally, for a
1307 \addtoindex{location list},
1308 this interpretation applies to each location description
1309 contained in the list of \addtoindex{location list} entries.
1311 \textit{The use of one of the \DWOPregn{}
1313 context is equivalent to using
1316 compact. However, these are not equivalent in general.}
1319 \textit{The frame base for a procedure is typically an address fixed
1320 relative to the first unit of storage allocated for the
1321 procedure\textquoteright s stack frame. The \DWATframebase{} attribute
1322 can be used in several ways:}
1323 \begin{enumerate}[1. ]
1324 \item \textit{In procedures that need
1325 \addtoindexx{location list}
1326 location lists to locate local
1327 variables, the \DWATframebase{} can hold the needed location
1328 list, while all variables\textquoteright\ location descriptions can be
1329 simpler ones involving the frame base.}
1331 \item \textit{It can be used in resolving \doublequote{up\dash level} addressing
1332 within nested routines.
1333 (See also \DWATstaticlink, below)}
1337 \textit{Some languages support nested subroutines. In such languages,
1338 it is possible to reference the local variables of an
1339 outer subroutine from within an inner subroutine. The
1340 \DWATstaticlink{} and \DWATframebase{} attributes allow
1341 debuggers to support this same kind of referencing.}
1344 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}{}
1346 \addtoindexx{address!uplevel|see {static link attribute}}
1347 \addtoindexx{uplevel address|see {static link attribute}}
1348 subroutine or entry point is nested, it may have a
1350 attribute, whose value is a location
1351 description that computes the frame base of the relevant
1352 instance of the subroutine that immediately encloses the
1353 subroutine or entry point.
1355 In the context of supporting nested subroutines, the
1356 \DWATframebase{} attribute value should obey the following
1359 \begin{enumerate}[1. ]
1360 \item It should compute a value that does not change during the
1361 life of the procedure, and
1363 \item The computed value should be unique among instances of
1364 the same subroutine. (For typical \DWATframebase{} use, this
1365 means that a recursive subroutine\textquoteright s stack frame must have
1366 non\dash zero size.)
1369 \textit{If a debugger is attempting to resolve an up\dash level reference
1370 to a variable, it uses the nesting structure of DWARF to
1371 determine which subroutine is the lexical parent and the
1372 \DWATstaticlink{} value to identify the appropriate active
1373 frame of the parent. It can then attempt to find the reference
1374 within the context of the parent.}
1378 \subsection{Types Thrown by Exceptions}
1379 \label{chap:typesthrownbyexceptions}
1381 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1382 it may validly throw.}
1384 If a subroutine explicitly declares that it may throw
1385 \addtoindexx{exception thrown|see{thrown type entry}}
1387 \addtoindexx{thrown exception|see{thrown type entry}}
1388 exception of one or more types, each such type is
1389 represented by a debugging information entry with
1390 \addtoindexx{thrown type entry}
1392 \DWTAGthrowntypeTARG.
1393 Each such entry is a child of the entry
1394 representing the subroutine that may throw this type. Each
1395 thrown type entry contains
1396 \addtoindexx{type attribute}
1397 a \DWATtype{} attribute, whose
1398 value is a \livelink{chap:classreference}{reference}
1399 to an entry describing the type of the
1400 exception that may be thrown.
1402 \subsection{Function Template Instantiations}
1403 \label{chap:functiontemplateinstantiations}
1405 \textit{In \addtoindex{C++}, a function template is a generic definition of
1406 a function that is instantiated differently for calls with
1407 values of different types. DWARF does not represent the generic
1408 template definition, but does represent each instantiation.}
1411 A \addtoindex{template instantiation} is represented by a debugging
1412 information entry with the
1413 \addtoindexx{subprogram entry!use for template instantiation}
1414 tag \DWTAGsubprogram.
1416 exceptions, such an entry will contain the same attributes and
1417 will have the same types of child entries as would an entry
1418 for a subroutine defined explicitly using the instantiation
1419 types and values. The exceptions are:
1421 \begin{enumerate}[1. ]
1422 \item Template parameters are described and referenced as specified in
1423 Section \refersec{chap:templateparameters}.
1425 \item If the compiler has generated a special compilation unit
1426 to hold the template instantiation and that compilation unit
1427 has a different name from the compilation unit containing
1428 the template definition, the name attribute for the debugging
1429 information entry representing that compilation unit is empty
1432 \item If the subprogram entry representing the template
1433 instantiation or any of its child entries contain declaration
1434 coordinate attributes, those attributes refer to the source
1435 for the template definition, not to any source generated
1436 artificially by the compiler for this instantiation.
1441 \subsection{Inlinable and Inlined Subroutines}
1442 \label{chap:inlinedsubroutines}
1443 A declaration or a definition of an inlinable subroutine
1444 is represented by a debugging information entry with the
1448 \addtoindexx{subprogram entry!use in inlined subprogram}
1450 \hypertarget{chap:DWATinlineinlinedsubroutine}{}
1451 explicitly declared to be available for inline expansion or
1452 that was expanded inline implicitly by the compiler has
1453 \addtoindexx{inline attribute}
1455 \DWATinline{} attribute whose value is an
1456 \livelink{chap:classconstant}{integer constant}. The
1457 set of values for the \DWATinline{} attribute is given in
1458 Table \refersec{tab:inlinecodes}.
1462 \caption{Inline codes}
1463 \label{tab:inlinecodes}
1464 \begin{tabular}{l|p{8cm}}
1466 Name&Meaning\\ \hline
1467 \DWINLnotinlinedTARG{} & Not declared inline nor inlined by the
1468 \mbox{compiler} (equivalent to the absence of the
1469 containing \DWATinline{} attribute) \\
1470 \DWINLinlinedTARG{} & Not declared inline but inlined by the \mbox{compiler} \\
1471 \DWINLdeclarednotinlinedTARG{} & Declared inline but
1472 not inlined by the \mbox{compiler} \\
1473 \DWINLdeclaredinlinedTARG{} & Declared inline and inlined by the
1479 \textit{In \addtoindex{C++}, a function or a constructor declared with
1480 \addttindex{constexpr} is implicitly declared inline. The abstract inline
1481 instance (see below) is represented by a debugging information
1482 entry with the tag \DWTAGsubprogram. Such an entry has a
1483 \DWATinline{} attribute whose value is \DWINLinlined.}
1486 \subsubsection{Abstract Instances}
1487 \label{chap:abstractinstances}
1488 Any debugging information entry that is owned (either
1489 \hypertarget{chap:DWATinlineabstracttinstance}{}
1490 directly or indirectly) by a debugging information entry
1492 \DWATinline{} attribute is referred to
1493 \addtoindexx{abstract instance!entry}
1494 as an \doublequote{abstract instance entry.}
1495 Any subroutine entry
1497 \addtoindexx{inline attribute}
1498 a \DWATinline{} attribute whose value is other
1499 than \DWINLnotinlined{}
1501 \addtoindexx{abstract instance!root}
1502 an \doublequote{abstract instance root.}
1503 Any set of abstract instance entries that are all
1504 children (either directly or indirectly) of some abstract
1505 instance root, together with the root itself, is known as
1506 \addtoindexx{abstract instance!tree}
1507 an \doublequote{abstract instance tree.} However, in the case where
1508 an abstract instance tree is nested within another abstract
1509 instance tree, the entries in the
1510 \addtoindex{nested abstract instance}
1511 tree are not considered to be entries in the outer abstract
1514 Each abstract instance root is either part of a larger
1515 \addtoindexx{abstract instance!root}
1516 tree (which gives a context for the root) or
1517 \addtoindexx{specification attribute}
1519 \DWATspecification{}
1520 to refer to the declaration in context.
1522 \textit{For example, in \addtoindex{C++} the context might be a namespace
1523 declaration or a class declaration.}
1525 \textit{Abstract instance trees are defined so that no entry is part
1526 of more than one abstract instance tree. This simplifies the
1527 following descriptions.}
1529 A debugging information entry that is a member of an abstract
1530 instance tree should not contain any attributes which describe
1531 aspects of the subroutine which vary between distinct inlined
1532 expansions or distinct out\dash of\dash line expansions. For example,
1533 \addtoindexx{entry pc attribute!and abstract instance}
1544 \addtoindexx{location attribute!and abstract instance}
1546 \addtoindexx{ranges attribute!and abstract instance}
1548 \addtoindexx{high PC attribute!and abstract instance}
1550 \addtoindexx{low PC attribute!and abstract instance}
1552 \addtoindexx{segment attribute!and abstract instance}
1554 \addtoindexx{return address attribute!and abstract instance}
1556 \addtoindexx{segment attribute!and abstract instance}
1558 \addtoindexx{start scope attribute!and abstract instance}
1562 \textit{It would not make sense normally to put these attributes into
1563 abstract instance entries since such entries do not represent
1564 actual (concrete) instances and thus do not actually exist at
1565 run\dash time. However,
1566 see Appendix \refersec{app:inlineouteronenormalinner}
1567 for a contrary example.}
1569 The rules for the relative location of entries belonging to
1570 abstract instance trees are exactly the same as for other
1571 similar types of entries that are not abstract. Specifically,
1572 the rule that requires that an entry representing a declaration
1573 be a direct child of the entry representing the scope of the
1574 declaration applies equally to both abstract and non\dash abstract
1575 entries. Also, the ordering rules for formal parameter entries,
1576 member entries, and so on, all apply regardless of whether
1577 or not a given entry is abstract.
1580 \subsubsection{Concrete Inlined Instances}
1581 \label{chap:concreteinlinedinstances}
1583 Each inline expansion of a subroutine is represented
1584 by a debugging information entry with the
1585 tag \DWTAGinlinedsubroutineTARG.
1586 Each such entry should be a direct
1587 child of the entry that represents the scope within which
1588 the inlining occurs.
1591 Each inlined subroutine entry may have either a
1593 and \DWAThighpc{} pair
1595 \addtoindexx{high PC attribute}
1597 \addtoindexx{low PC attribute}
1599 \addtoindexx{ranges attribute}
1602 attribute whose values encode the contiguous or non\dash contiguous
1603 address ranges, respectively, of the machine instructions
1604 generated for the inlined subroutine (see
1605 Section \referfol{chap:codeaddressesandranges}).
1607 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}{}
1608 inlined subroutine entry may
1609 \addtoindexx{inlined subprogram entry!in concrete instance}
1611 \addtoindexx{inlined subprogram entry}
1613 \addtoindexx{entry pc attribute!for inlined subprogram}
1616 attribute, representing the first executable instruction of
1617 the inline expansion (see
1618 Section \refersec{chap:entryaddress}).
1620 % Positions of the 3 targets here is a bit arbitrary.
1622 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{}
1624 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{}
1626 \hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{}
1627 may also have \DWATcallfile,
1628 \DWATcallline{} and \DWATcallcolumn{} attributes,
1630 value is an \livelink{chap:classconstant}{integer constant}.
1631 These attributes represent the
1632 source file, source line number, and source column number,
1633 respectively, of the first character of the statement or
1634 expression that caused the inline expansion. The call file,
1635 call line, and call column attributes are interpreted in
1636 the same way as the declaration file, declaration line, and
1637 declaration column attributes, respectively (see
1638 Section \refersec{chap:declarationcoordinates}).
1640 \textit{The call file, call line and call column coordinates do not
1641 describe the coordinates of the subroutine declaration that
1642 was inlined, rather they describe the coordinates of the call.
1645 An inlined subroutine entry
1646 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}{}
1649 attribute, which is a \livelink{chap:classflag}{flag}
1650 whose presence indicates that the
1651 subroutine has been evaluated as a compile\dash time constant. Such
1652 an entry may also have a \DWATconstvalue{} attribute,
1653 whose value may be of any form that is appropriate for the
1654 representation of the subroutine's return value. The value of
1655 this attribute is the actual return value of the subroutine,
1656 represented as it would be on the target architecture.
1658 \textit{In \addtoindex{C++}, if a function or a constructor declared with
1659 \addttindex{constexpr}
1660 is called with constant expressions, then the corresponding
1661 concrete inlined instance has a
1662 \DWATconstexpr{} attribute,
1663 as well as a \DWATconstvalue{} attribute whose value represents
1664 the actual return value of the concrete inlined instance.}
1666 Any debugging information entry that is owned (either
1667 directly or indirectly) by a debugging information entry
1668 with the tag \DWTAGinlinedsubroutine{} is referred to as a
1669 \doublequote{concrete inlined instance entry.} Any entry that has
1671 \DWTAGinlinedsubroutine{}
1672 is known as a \doublequote{concrete inlined instance root.}
1673 Any set of concrete inlined instance
1674 entries that are all children (either directly or indirectly)
1675 of some concrete inlined instance root, together with the root
1676 itself, is known as a \doublequote{concrete inlined instance tree.}
1677 However, in the case where a concrete inlined instance tree
1678 is nested within another concrete instance tree, the entries
1679 in the \addtoindex{nested concrete inline instance} tree
1680 are not considered to
1681 be entries in the outer concrete instance tree.
1684 \textit{Concrete inlined instance trees are defined so that no entry
1685 is part of more than one concrete inlined instance tree. This
1686 simplifies later descriptions.}
1688 Each concrete inlined instance tree is uniquely associated
1689 with one (and only one) abstract instance tree.
1691 \textit{Note, however, that the reverse is not true. Any given abstract
1692 instance tree may be associated with several different concrete
1693 inlined instance trees, or may even be associated with zero
1694 concrete inlined instance trees.}
1696 Concrete inlined instance entries may omit attributes that
1697 are not specific to the concrete instance (but present in
1698 the abstract instance) and need include only attributes that
1699 are specific to the concrete instance (but omitted in the
1700 abstract instance). In place of these omitted attributes, each
1701 \hypertarget{chap:DWATabstractorigininlineinstance}{}
1702 concrete inlined instance entry
1703 \addtoindexx{abstract origin attribute}
1705 \DWATabstractorigin{}
1706 attribute that may be used to obtain the missing information
1707 (indirectly) from the associated abstract instance entry. The
1708 value of the abstract origin attribute is a reference to the
1709 associated abstract instance entry.
1711 If an entry within a concrete inlined instance tree contains
1712 attributes describing the
1713 \addtoindexx{declaration coordinates!in concrete instance}
1714 \livelink{chap:declarationcoordinates}{declaration coordinates}
1715 of that entry, then those attributes should refer to the file, line
1716 and column of the original declaration of the subroutine,
1717 not to the point at which it was inlined. As a consequence,
1718 they may usually be omitted from any entry that has an abstract
1722 For each pair of entries that are associated via a
1723 \addtoindexx{abstract origin attribute}
1724 \DWATabstractorigin{} attribute, both members of the pair
1725 have the same tag. So, for example, an entry with the tag
1726 \DWTAGvariable{} can only be associated with another entry
1727 that also has the tag \DWTAGvariable. The only exception
1728 to this rule is that the root of a concrete instance tree
1729 (which must always have the tag \DWTAGinlinedsubroutine)
1730 can only be associated with the root of its associated abstract
1731 instance tree (which must have the tag \DWTAGsubprogram).
1734 In general, the structure and content of any given concrete
1735 inlined instance tree will be closely analogous to the
1736 structure and content of its associated abstract instance
1737 tree. There are a few exceptions:
1739 \begin{enumerate}[1. ]
1740 \item An entry in the concrete instance tree may be omitted if
1742 \addtoindexx{abstract origin attribute}
1743 \DWATabstractorigin{} attribute and either
1744 has no children, or its children are omitted. Such entries
1745 would provide no useful information. In C\dash like languages,
1746 such entries frequently include types, including structure,
1747 union, class, and interface types; and members of types. If any
1748 entry within a concrete inlined instance tree needs to refer
1749 to an entity declared within the scope of the relevant inlined
1750 subroutine and for which no concrete instance entry exists,
1751 the reference should refer to the abstract instance entry.
1754 \item Entries in the concrete instance tree which are associated
1755 with entries in the abstract instance tree such that neither
1756 has a \DWATname{} attribute,
1757 \addtoindexx{name attribute}
1758 and neither is referenced by
1759 any other debugging information entry, may be omitted. This
1760 may happen for debugging information entries in the abstract
1761 instance trees that became unnecessary in the concrete instance
1762 tree because of additional information available there. For
1763 example, an anonymous variable might have been created and
1764 described in the abstract instance tree, but because of
1765 the actual parameters for a particular inlined expansion,
1766 it could be described as a constant value without the need
1767 for that separate debugging information entry.
1769 \item A concrete instance tree may contain entries which do
1770 not correspond to entries in the abstract instance tree
1771 to describe new entities that are specific to a particular
1772 inlined expansion. In that case, they will not have associated
1773 entries in the abstract instance tree, should not contain
1774 \addtoindexx{abstract origin attribute}
1775 \DWATabstractorigin{} attributes, and must contain all their
1776 own attributes directly. This allows an abstract instance tree
1777 to omit debugging information entries for anonymous entities
1778 that are unlikely to be needed in most inlined expansions. In
1779 any expansion which deviates from that expectation, the
1780 entries can be described in its concrete inlined instance tree.
1784 \subsubsection{Out-of-Line Instances of Inlined Subroutines}
1785 \label{chap:outoflineinstancesofinlinedsubroutines}
1786 Under some conditions, compilers may need to generate concrete
1787 executable instances of inlined subroutines other than at
1788 points where those subroutines are actually called. Such
1789 concrete instances of inlined subroutines are referred to as
1790 \doublequote{concrete out\dash of\dash line instances.}
1792 \textit{In \addtoindex{C++}, for example,
1793 taking the address of a function declared
1794 to be inline can necessitate the generation of a concrete
1795 out\dash of\dash line instance of the given function.}
1797 The DWARF representation of a concrete out\dash of\dash line instance
1798 of an inlined subroutine is essentially the same as for a
1799 concrete inlined instance of that subroutine (as described in
1800 the preceding section). The representation of such a concrete
1801 % It is critical that the hypertarget and livelink be
1802 % separated to avoid problems with latex.
1803 out\dash of\dash line
1804 \addtoindexx{abstract origin attribute}
1806 \hypertarget{chap:DWATabstractoriginoutoflineinstance}{}
1808 \DWATabstractorigin{}
1809 attributes in exactly the same way as they are used for
1810 a concrete inlined instance (that is, as references to
1811 corresponding entries within the associated abstract instance
1815 The differences between the DWARF representation of a
1816 concrete out\dash of\dash line instance of a given subroutine and the
1817 representation of a concrete inlined instance of that same
1818 subroutine are as follows:
1820 \begin{enumerate}[1. ]
1821 \item The root entry for a concrete out\dash of\dash line instance
1822 of a given inlined subroutine has the same tag as does its
1823 associated (abstract) inlined subroutine entry (that is, tag
1824 \DWTAGsubprogram{} rather than \DWTAGinlinedsubroutine).
1826 \item The root entry for a concrete out\dash of\dash line instance tree
1827 is normally owned by the same parent entry that also owns
1828 the root entry of the associated abstract instance. However,
1829 it is not required that the abstract and out\dash of\dash line instance
1830 trees be owned by the same parent entry.
1834 \subsubsection{Nested Inlined Subroutines}
1835 \label{nestedinlinedsubroutines}
1836 Some languages and compilers may permit the logical nesting of
1837 a subroutine within another subroutine, and may permit either
1838 the outer or the nested subroutine, or both, to be inlined.
1840 For a non\dash inlined subroutine nested within an inlined
1841 subroutine, the nested subroutine is described normally in
1842 both the abstract and concrete inlined instance trees for
1843 the outer subroutine. All rules pertaining to the abstract
1844 and concrete instance trees for the outer subroutine apply
1845 also to the abstract and concrete instance entries for the
1849 For an inlined subroutine nested within another inlined
1850 subroutine, the following rules apply to their abstract and
1851 \addtoindexx{abstract instance!nested}
1852 \addtoindexx{concrete instance!nested}
1853 concrete instance trees:
1855 \begin{enumerate}[1. ]
1856 \item The abstract instance tree for the nested subroutine is
1857 described within the abstract instance tree for the outer
1858 subroutine according to the rules in
1859 Section \refersec{chap:abstractinstances}, and
1860 without regard to the fact that it is within an outer abstract
1863 \item Any abstract instance tree for a nested subroutine is
1864 always omitted within the concrete instance tree for an
1867 \item A concrete instance tree for a nested subroutine is
1868 always omitted within the abstract instance tree for an
1871 \item The concrete instance tree for any inlined or
1872 \addtoindexx{out-of-line instance}
1874 \addtoindexx{out-of-line-instance|see{concrete out-of-line-instance}}
1875 expansion of the nested subroutine is described within a
1876 concrete instance tree for the outer subroutine according
1878 Sections \refersec{chap:concreteinlinedinstances} or
1879 \referfol{chap:outoflineinstancesofinlinedsubroutines}
1881 and without regard to the fact that it is within an outer
1882 concrete instance tree.
1885 See Appendix \refersec{app:inliningexamples}
1886 for discussion and examples.
1888 \subsection{Trampolines}
1889 \label{chap:trampolines}
1891 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1892 \hypertarget{chap:DWATtrampolinetargetsubroutine}{}
1893 an intermediary in making a call to another subroutine. It may
1894 adjust parameters and/or the result (if any) as appropriate
1895 to the combined calling and called execution contexts.}
1897 A trampoline is represented by a debugging information entry
1898 \addtoindexx{trampoline (subprogram) entry}
1899 with the tag \DWTAGsubprogram{} or \DWTAGinlinedsubroutine{}
1901 \addtoindexx{trampoline attribute}
1902 a \DWATtrampoline{} attribute.
1904 attribute indicates the target subroutine of the trampoline,
1905 that is, the subroutine to which the trampoline passes
1906 control. (A trampoline entry may but need not also have a
1907 \DWATartificial{} attribute.)
1910 The value of the trampoline attribute may be represented
1911 using any of the following forms, which are listed in order
1915 \item If the value is of class reference, then the value
1916 specifies the debugging information entry of the target
1919 \item If the value is of class address, then the value is
1920 the relocated address of the target subprogram.
1922 \item If the value is of class string, then the value is the
1923 (possibly mangled) \addtoindexx{mangled names}
1924 name of the target subprogram.
1926 \item If the value is of class \livelink{chap:classflag}{flag}, then the value true
1927 indicates that the containing subroutine is a trampoline but
1928 that the target subroutine is not known.
1932 The target subprogram may itself be a trampoline. (A sequence
1933 of trampolines necessarily ends with a non\dash trampoline
1936 \textit{In \addtoindex{C++}, trampolines may be used
1937 to implement derived virtual
1938 member functions; such trampolines typically adjust the
1939 \addtoindexx{this parameter}
1940 implicit this pointer parameter in the course of passing
1942 Other languages and environments may use trampolines
1943 in a manner sometimes known as transfer functions or transfer
1946 \textit{Trampolines may sometimes pass control to the target
1947 subprogram using a branch or jump instruction instead of a
1948 call instruction, thereby leaving no trace of their existence
1949 in the subsequent execution context. }
1951 \textit{This attribute helps make it feasible for a debugger to arrange
1952 that stepping into a trampoline or setting a breakpoint in
1953 a trampoline will result in stepping into or setting the
1954 breakpoint in the target subroutine instead. This helps to
1955 hide the compiler generated subprogram from the user. }
1957 \textit{If the target subroutine is not known, a debugger may choose
1958 to repeatedly step until control arrives in a new subroutine
1959 which can be assumed to be the target subroutine. }
1961 \subsection{Call Site Entries}
1962 \label{chap:callsiteentries}
1964 A call site entry provides a way to represent the static or dynamic
1965 call graph of a program in the debugging information. It also provides
1966 information about how parameters are passed so that they may be more
1967 easily accessed by a debugger. Together with the \DWOPentryvalue{} opcode,
1968 call site entries can be also useful for computing values of variables
1969 and expressions where some value is no longer present in the current
1970 subroutine's registers or local stack frame, but it is known that the
1971 values are equal to some parameter passed to the function.
1972 The consumer can then use unwind
1973 information to find the caller and in the call site information sometimes
1974 find how to compute the value passed in a particular parameter.}
1976 A call site is represented by a debugging information entry with the tag
1977 \DWTAGcallsiteTARG{}. The entry for a call site is owned by the innermost
1978 debugging information entry representing the scope within which the
1979 call is present in the source program.
1981 \textit{A scope entry (for example, for a lexical block) that would not
1982 otherwise be present in the debugging information of a subroutine
1983 need not be introduced solely to represent the immediately containing scope
1984 of a call. The call site entry is owned by the innermost scope entry that
1987 A source call can be compiled into different types of machine code:
1990 A \textit{normal call} uses a call-like instruction which transfers control to the start
1991 of some subprogram and leaves the call site location address somewhere where
1992 unwind information can find it.
1994 A \textit{tail call} uses a jump-like instruction which
1995 transfers control to the start of some subprogram, but the call site location
1996 address is not preserved (and thus not available using the unwind information).
1998 A \textit{tail recursion call} is a call
1999 to the current subroutine which is compiled as a loop into the middle of the
2002 An \textit{inline (or inlined) call} is a call to an inlined subprogram,
2003 where at least one instruction has the location of the inlined subprogram
2004 or any of its blocks or inlined subprograms.
2008 There are also different types of \doublequote{optimized out} calls:
2011 An \textit{optimized out (normal) call} is a call that is in unreachable code that
2012 has not been emitted (such as, for example, the call to \texttt{foo} in
2013 \texttt{if (0) foo();}).
2015 An \textit{optimized out inline call}
2016 is a call to an inlined subprogram which either did not expand to any instructions
2017 or only parts of instructions belong to it and for debug information purposes those
2018 instructions are given a location in the caller.
2021 \DWTAGcallsite{} entries describe normal and tail calls but not tail recursion calls,
2022 while \DWTAGinlinedsubroutine{} entries describe inlined calls
2023 (see Section \refersec{chap:inlinedsubroutines}).
2025 The call site entry has a
2026 \DWATcallreturnpcNAME{}
2027 \livetargi{chap:DWATcallreturnpcofcallsite}{attribute}{call return pc attribute}
2028 which is the return address after the call.
2029 The value of this attribute corresponds to the return address computed by
2030 call frame information in the called subprogram
2031 (see Section \refersec{datarep:callframeinformation}).
2033 \textit{On many architectures the return address is the address immediately following the
2034 call instruction, but on architectures with delay slots it might
2035 be an address after the delay slot of the call.}
2037 The call site entry may have a
2039 \livetargi{chap:DWATcallpcofcallsite}{attribute}{call pc attribute} which is the
2040 address of the call instruction.
2042 If the call site entry corresponds to a tail call, it has the
2043 \DWATcalltailcallNAME{}
2044 \livetargi{chap:DWATcalltailcallofcallsite}{attribute}{call tail call attribute},
2045 which is a \CLASSflag.
2047 The call site entry may have a
2048 \DWATcalloriginNAME{}
2049 \livetargi{chap:DWATcalloriginofcallsite}{attribute}{call origin attribute}
2050 which is a \CLASSreference. For direct calls or jumps where the called subprogram is
2051 known it is a reference to the called subprogram's debugging
2052 information entry. For indirect calls it may be a reference to a
2053 \DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
2054 the subroutine pointer that is called.
2056 The call site may have a
2057 \DWATcalltargetNAME{}
2058 \livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
2059 a DWARF expression. For indirect calls or jumps where it is unknown at
2060 compile time which subprogram will be called the expression computes the
2061 address of the subprogram that will be called. The DWARF expression should
2062 not use register or memory locations that might be clobbered by the call.
2064 The call site entry may have a
2065 \DWATcalltargetclobberedNAME{}
2066 \livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
2067 which is a DWARF expression. For indirect calls or jumps where the
2068 address is not computable without use of registers or memory locations that
2069 might be clobbered by the call the \DWATcalltargetclobberedNAME{}
2070 attribute is used instead of the \DWATcalltarget{} attribute.
2072 The call site entry may have a \DWATtypeNAME{}
2073 \livetargi{chap:DWATtypeofcallsite}{attribute}{type attribute!of call site entry}
2074 referencing a debugging information entry for the type of the called function.
2075 When \DWATcallorigin{} is present, \DWATtypeNAME{} is usually omitted.
2077 The call site entry may have
2078 \DWATcallfileNAME{}, \DWATcalllineNAME{} and \DWATcallcolumnNAME{}
2079 \livetargi{chap:DWATcallfileofcallsite}{attributes,}{call file attribute!of call site entry}
2080 \livetargi{chap:DWATcalllineofcallsite}{}{call line attribute!of call site entry}
2081 \livetargi{chap:DWATcallcolumnofcallsite}{}{call column attribute!of call site entry}
2082 each of whose value is an integer constant.
2083 These attributes represent the source file, source line number, and source
2084 column number, respectively, of the first character of the call statement or
2085 expression. The call file, call line, and call column attributes are
2086 interpreted in the same way as the declaration file, declaration
2087 line, and declaration column attributes, respectively
2088 (see Section \refersec{chap:declarationcoordinates}).
2090 \textit{The call file, call line and call column coordinates do not describe the
2091 coordinates of the subroutine declaration that was inlined, rather they describe
2092 the coordinates of the call.}
2094 The call site entry may own \DWTAGcallsiteparameterTARG{} debugging information
2095 entries\index{call site parameter entry} representing the parameters passed to the call.
2096 Each such entry has a \DWATlocation{} attribute which is a location expression.
2097 This location expression describes where the parameter is passed
2098 (usually either some register, or a memory location expressible as the
2099 contents of the stack register plus some offset).
2101 Each \DWTAGcallsiteparameter{} entry may have a
2102 \DWATcallvalueNAME{}
2103 \livetargi{chap:DWATcallvalueofcallparameter}{attribute}{call value attribute}
2104 which is a DWARF expression. This expression computes the value
2105 passed for that parameter. The expression should not use registers or memory
2106 locations that might be clobbered by the call, as it might be evaluated after
2107 unwinding from the called function back to the caller. If it is not
2108 possible to avoid registers or memory locations that might be clobbered by
2109 the call in the expression, then the \DWATcallvalueNAME{} attribute should
2112 \textit{The reason for the restriction is that the value of the parameter may be
2113 needed in the middle of the callee, where the call clobbered registers or
2114 memory might be already clobbered, and if the consumer was not assured by
2115 the producer it can safely use those values, the consumer could not safely
2116 use the values at all.}
2118 For parameters passed by reference, where the code passes a pointer to
2119 a location which contains the parameter, or for reference type parameters
2120 the \DWTAGcallsiteparameter{} entry may also have
2121 \DWATcalldatalocationNAME{}
2122 \livetargi{chap:DWATcalldatalocationofcallparameter}{attribute}{call data location attribute}
2123 whose value is a location expression and a
2124 \DWATcalldatavalueNAME{}
2125 \livetargi{chap:DWATcalldatavalueofcallparameter}{attribute}{call data value attribute}
2126 whose value is a DWARF expression. The \DWATcalldatalocationNAME{} attribute
2127 describes where the referenced value lives during the call. If it is just
2128 \DWOPpushobjectaddress{}, it may be left out. The
2129 \DWATcalldatavalueNAME{} attribute describes the value in that location.
2130 The expression should not use registers or memory
2131 locations that might be clobbered by the call, as it might be evaluated after
2132 unwinding from the called function back to the caller.
2135 Each call site parameter entry may also have a
2136 \DWATcallparameter{}
2137 \livetargi{chap:DWATcallparameterofcallparameter}{attribute}{call parameter attribute}
2138 which contains a reference to a \DWTAGformalparameter{} entry,
2139 \DWATtype{} attribute referencing the type of the parameter or \DWATname{}
2140 attribute describing the parameter's name.
2144 \section{Lexical Block Entries}
2145 \label{chap:lexicalblockentries}
2148 lexical \livetargi{chap:lexicalblock}{block}{lexical block}
2150 \addtoindexx{lexical block}
2151 a bracketed sequence of source statements
2152 that may contain any number of declarations. In some languages
2153 (including \addtoindex{C} and \addtoindex{C++}),
2154 \nolink{blocks} can be nested within other
2155 \nolink{blocks} to any depth.}
2157 % We do not need to link to the preceding paragraph.
2158 A lexical \nolink{block} is represented by a debugging information
2160 tag \DWTAGlexicalblockTARG.
2162 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry}
2164 either a \DWATlowpc{} and
2165 \DWAThighpc{} pair of
2167 \addtoindexx{high PC attribute}
2169 \addtoindexx{low PC attribute}
2171 \DWATranges{} attribute
2172 \addtoindexx{ranges attribute}
2173 whose values encode the contiguous or non-contiguous address
2174 ranges, respectively, of the machine instructions generated
2175 for the lexical \nolink{block}
2176 (see Section \refersec{chap:codeaddressesandranges}).
2179 \hypertarget{chap:DWATentrypcoflexicalblock}{}
2180 lexical block entry may also have
2181 \addtoindexx{entry pc attribute!for lexical block}
2183 \DWATentrypc{} attribute
2184 whose value is the address of the first executable instruction
2185 of the lexical block (see
2186 Section \refersec{chap:entryaddress}).
2188 If a name has been given to the
2189 lexical \nolink{block}
2191 program, then the corresponding
2192 lexical \nolink{block} entry has a
2193 \DWATname{} attribute whose
2194 \addtoindexx{name attribute}
2195 value is a null\dash terminated string
2196 containing the name of the lexical \nolink{block}
2200 \textit{This is not the same as a \addtoindex{C} or
2201 \addtoindex{C++} label (see below).}
2203 The lexical \nolink{block} entry owns
2204 debugging information entries that
2205 describe the declarations within that lexical \nolink{block}.
2207 one such debugging information entry for each local declaration
2208 of an identifier or inner lexical \nolink{block}.
2211 \section{Label Entries}
2212 \label{chap:labelentries}
2213 \textit{A label is a way of identifying a source statement. A labeled
2214 statement is usually the target of one or more \doublequote{go to}
2219 A label is represented by a debugging information entry with
2220 \addtoindexx{label entry}
2222 tag \DWTAGlabelTARG.
2223 The entry for a label should be owned by
2224 the debugging information entry representing the scope within
2225 which the name of the label could be legally referenced within
2228 The label entry has a \DWATlowpc{} attribute whose value
2229 is the relocated address of the first machine instruction
2230 generated for the statement identified by the label in
2231 the source program. The label entry also has a
2232 \DWATname{} attribute
2233 \addtoindexx{name attribute}
2234 whose value is a null-terminated string containing
2235 the name of the label as it appears in the source program.
2238 \section{With Statement Entries}
2239 \label{chap:withstatemententries}
2241 \textit{Both \addtoindex{Pascal} and
2242 \addtoindexx{Modula-2}
2243 Modula\dash 2 support the concept of a \doublequote{with}
2244 statement. The with statement specifies a sequence of
2245 executable statements within which the fields of a record
2246 variable may be referenced, unqualified by the name of the
2249 A with statement is represented by a
2250 \addtoindexi{debugging information entry}{with statement entry}
2251 with the tag \DWTAGwithstmtTARG.
2253 A with statement entry may have either a
2255 \DWAThighpc{} pair of attributes
2256 \addtoindexx{high PC attribute}
2258 \addtoindexx{low PC attribute}
2259 a \DWATranges{} attribute
2260 \addtoindexx{ranges attribute}
2261 whose values encode the contiguous or non\dash contiguous address
2262 ranges, respectively, of the machine instructions generated
2263 for the with statement
2264 (see Section \refersec{chap:codeaddressesandranges}).
2267 \hypertarget{chap:DWATentrypcofwithstmt}{}
2268 with statement entry may also have
2269 \addtoindexx{entry pc attribute!for with statement}
2271 \DWATentrypc{} attribute
2272 whose value is the address of the first executable instruction
2273 of the with statement (see
2274 Section \refersec{chap:entryaddress}).
2277 The with statement entry has
2278 \addtoindexx{type attribute}
2279 a \DWATtype{} attribute, denoting
2280 the type of record whose fields may be referenced without full
2281 qualification within the body of the statement. It also has
2282 \addtoindexx{location attribute}
2283 a \DWATlocation{} attribute, describing how to find the base
2284 address of the record object referenced within the body of
2288 \section{Try and Catch Block Entries}
2289 \label{chap:tryandcatchblockentries}
2291 \textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be
2292 designated as a \doublequote{catch \nolink{block}.}
2293 A catch \livetargi{chap:catchblock}{block}{catch block} is an
2294 exception handler that handles
2295 exceptions thrown by an immediately
2296 preceding \doublequote{try \livelink{chap:tryblock}{block}.}
2297 A catch \livelink{chap:catchblock}{block}
2298 designates the type of the exception that it
2301 A try \livetargi{chap:tryblock}{block}{try block} is represented
2302 by a debugging information entry
2303 \addtoindexx{try block entry}
2304 with the tag \DWTAGtryblockTARG.
2305 A catch \livelink{chap:catchblock}{block} is represented by
2306 a debugging information entry with
2307 \addtoindexx{catch block entry}
2308 the tag \DWTAGcatchblockTARG.
2310 % nolink as we have links just above and do not have a combo link for both
2311 Both try and catch \nolink{block} entries may have either a
2313 \DWAThighpc{} pair of attributes
2314 \addtoindexx{high PC attribute}
2316 \addtoindexx{low PC attribute}
2318 \DWATranges{} attribute
2319 \addtoindexx{ranges attribute}
2320 whose values encode the contiguous
2321 or non\dash contiguous address ranges, respectively, of the
2322 machine instructions generated for the \livelink{chap:lexicalblock}{block}
2324 \refersec{chap:codeaddressesandranges}).
2327 \hypertarget{chap:DWATentrypcoftryblock}{}
2328 \hypertarget{chap:DWATentrypcofcatchblock}{}
2329 try or catch block entry may also have
2330 \addtoindexx{entry pc attribute!for try block}
2331 \addtoindexx{entry pc attribute!for catch block}
2333 \DWATentrypc{} attribute
2334 whose value is the address of the first executable instruction
2335 of the try or catch block (see
2336 Section \refersec{chap:entryaddress}).
2338 Catch \livelink{chap:catchblock}{block} entries have at
2339 least one child entry, an
2340 entry representing the type of exception accepted by
2341 that catch \livelink{chap:catchblock}{block}.
2342 This child entry has one of
2343 \addtoindexx{formal parameter entry!in catch block}
2345 \addtoindexx{unspecified parameters entry!in catch block}
2347 \DWTAGformalparameter{} or
2348 \DWTAGunspecifiedparameters,
2349 and will have the same form as other parameter entries.
2351 The siblings immediately following
2352 a try \livelink{chap:tryblock}{block} entry are its
2353 corresponding catch \livelink{chap:catchblock}{block} entries.