288b25d70b84b4e9350d09fb92897d170de6e8b5
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
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.
9
10 \section{Unit Entries}
11 An object file may contain one or more compilation units,
12 of which there are
13 \addtoindexx{unit|see {compilation unit, partial unit \textit{or} type unit}} 
14 \addtoindexx{compilation unit}
15 three kinds: 
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}
21 type units. A 
22 \addtoindex{partial compilation unit}
23 is related to one or more other compilation units that
24 import it. A 
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}.
32
33
34 \subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
35 \label{chap:normalandpartialcompilationunitentries}
36
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
41 entry with the 
42 tag \DWTAGpartialunitTARG.
43
44 In a simple normal compilation, a single compilation unit with
45 the tag 
46 \DWTAGcompileunit{} represents a complete object file
47 and the tag 
48 \DWTAGpartialunit{} is not used. 
49 In a compilation
50 employing the DWARF space compression and duplicate elimination
51 techniques from 
52 Appendix \refersec{app:usingcompilationunits}, 
53 multiple compilation units using
54 the tags 
55 \DWTAGcompileunit{} and/or 
56 \DWTAGpartialunit{} are
57 used to represent portions of an object file.
58
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
70 in some cases.}
71
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}).
80
81
82 Compilation unit entries may have the following 
83 attributes:
84 \begin{enumerate}[1. ]
85 \item Either a \DWATlowpc{} and 
86 \DWAThighpc{} pair of
87 \addtoindexx{high PC attribute}
88 attributes 
89 \addtoindexx{low PC attribute}
90 or 
91 \addtoindexx{ranges attribute}
92
93 \DWATranges{} attribute
94 \addtoindexx{ranges attribute}
95 whose values encode 
96 \addtoindexx{discontiguous address ranges|see{non-contiguous address ranges}}
97 the
98 contiguous or 
99 non\dash contiguous address ranges, respectively,
100 of the machine instructions generated for the compilation
101 unit (see Section \refersec{chap:codeaddressesandranges}).
102   
103 A \DWATlowpc{} attribute 
104 may also
105 be specified 
106 in combination 
107 \addtoindexx{ranges attribute}
108 with 
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}).
117
118 \item A \DWATname{} attribute 
119 \addtoindexx{name attribute}
120 whose value is a null\dash terminated
121 string 
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.
125
126 \item A \DWATlanguage{} attribute 
127 \addtoindexx{language attribute}
128 whose constant value is an
129 \hypertarget{chap:DWATlanguageprogramminglanguage}{}
130 integer code 
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}.
135
136 \begin{table}[t]
137 \centering
138 \caption{Language names}
139 \label{tab:languagenames}
140 \begin{tabular}{l|l}
141 \hline
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} \\
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}} \\ 
177 \hline
178 \dag \ \ \textit{Support for these languages is limited}& \\
179 \end{tabular}
180 \end{table}
181
182 \item A \DWATstmtlist{}
183 attribute whose value is 
184 \addtoindexx{statement list attribute}
185
186 \addtoindexx{section offset!in statement list attribute}
187 section
188 \hypertarget{chap:DWATstmtlistlinenumberinformationforunit}{}
189 offset to the line number information for this compilation
190 unit.
191
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}).
198
199 \clearpage
200
201 \needlines{6}
202 \item A \DWATmacros{} attribute 
203 \addtoindexx{macro information attribute}
204 whose value is a 
205 \addtoindexx{section offset!in macro information attribute}
206 section
207 \hypertarget{chap:DWATmacrosmacroinformation}{}
208 offset to the macro information for this compilation unit.
209
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}).
216
217 \textit{The \DWATmacros{} attribute is new in \DWARFVersionV, 
218 and supersedes the 
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
224 coexistence.}
225
226 \needlines{6}
227 \item  A 
228 \DWATcompdir{} 
229 attribute 
230 \hypertarget{chap:DWATcompdircompilationdirectory}{}
231 whose value is a
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.
235
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.
246
247 \needlines{4}
248 \item  A \DWATidentifiercase{} 
249 attribute 
250 \addtoindexx{identifier case attribute}
251 whose integer
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}.
257
258 \begin{simplenametable}{Identifier case codes}{tab:identifiercasecodes}
259 \DWIDcasesensitive{}      \\
260 \DWIDupcase{}             \\
261 \DWIDdowncase{}           \\
262 \DWIDcaseinsensitive{}    \\
263 \end{simplenametable}
264
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.
273
274 \needlines{4}
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
281 lookups.
282
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
289 lookups.
290
291 \needlines{4}
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
295 access those names.
296
297 \needlines{5}
298 \item A \DWATbasetypes{} attribute whose value is a 
299 \livelink{chap:classreference}{reference}.
300
301 This 
302 \hypertarget{chap:DWATbasetypesprimitivedatatypesofcompilationunit}{}
303 attribute 
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}).
310
311 \needlines{6}
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}{}
318 correctly.
319
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. 
326
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.
335
336 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement}
337 which is used
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
343 a program.}
344
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}).
352
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.
362
363 \needlines{6}
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.
373
374 \needlines{5}
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.
383
384
385 \end{enumerate}
386
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.
392
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. 
404
405 A skeleton compilation unit has no
406 children, and may have the following attributes:
407 \begin{enumerate}[1. ]
408
409 \item
410 Either a \DWATlowpc{} and \DWAThighpc{} pair of attributes
411 or a \DWATranges{} attribute (the same as for regular
412 compilation unit entries).
413
414 \item
415 A \DWATstmtlist{} attribute (the same as for regular
416 compilation unit entries).
417
418 \item
419 A \DWATcompdir{} attribute (the same as for regular
420 compilation unit entries).
421
422 \item
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
427 compilation unit.
428
429 \item
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}.
435
436 \needlines{6}
437 \item
438 A \DWATuseUTFeight{} attribute (the same as for regular compilation unit
439 entries).
440
441 \textit{This attribute applies to strings referred to by the skeleton
442 compilation unit entry itself, and strings in the associated line
443 number information.
444 The representation for strings in the DWARF object file is determined
445 by the presence of a \DWATuseUTFeight{} attribute in the full compilation
446 unit.}
447
448 \item
449 A \DWATstroffsetsbase{} attribute, for indirect strings references 
450 from the skeleton compilation unit (the same as for regular 
451 compilation unit entries).
452
453 \item
454 A \DWATaddrbase{} attribute (the same as for regular
455 compilation unit entries).
456
457 \item
458 A \DWATrangesbase{} attribute (the same as for regular
459 compilation unit entries).
460
461 \end{enumerate}
462
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.
472
473
474 \subsection{Imported Unit Entries}
475 \label{chap:importedunitentries}
476 The 
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}
484 a
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.
489
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
494 compilation unit.}
495
496 \needlines{6}
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
501 definition. 
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.
506
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.
513
514 A type unit entry may have a 
515 \DWATlanguage{} attribute, 
516 whose
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}.
521
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.
529
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.
545
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.
550
551 \needlines{4}
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.
558
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.
566
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.
572
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.}
581
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
585 those entities.}
586
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
594 entry containing a 
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).}
602
603 A module is represented by a debugging information entry
604 with the 
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.
609
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.
615
616 The \addtoindex{module entry} may have either a 
617 \DWATlowpc{} and
618 \DWAThighpc{} 
619 pair 
620 \addtoindexx{high PC attribute}
621 of 
622 \addtoindexx{low PC attribute}
623 attributes or a 
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}{}
631 It may also
632 \addtoindexx{entry pc attribute!for module initialization}
633 have a 
634 \DWATentrypc{} attribute whose value is the address of
635 the first executable instruction of that initialization code
636 (see Section \refersec{chap:entryaddress}).
637
638 If 
639 \hypertarget{chap:DWATprioritymodulepriority}{}
640 the module has been assigned a priority, it may have 
641 \addtoindexx{priority attribute}
642 a
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.
649
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.}
658
659 A namespace is represented by a debugging information entry
660 with the 
661 tag \DWTAGnamespaceTARG. 
662 A namespace extension is
663 \hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{}
664 represented by a 
665 \DWTAGnamespace{} entry 
666 with 
667 \addtoindexx{extension attribute}
668
669 \DWATextension{}
670 attribute referring to the previous extension, or if there
671 is no previous extension, to the original 
672 \DWTAGnamespace{}
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.)
681
682 \needlines{4}
683 Namespace and namespace extension entries may own 
684 \addtoindexx{namespace extension entry}
685 other
686 \addtoindexx{namespace declaration entry}
687 debugging information entries describing program entities
688 whose declarations occur in the namespace.
689
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.}
694
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
703 entries with a 
704 \DWATspecification{} attribute 
705 \addtoindexx{specification attribute}
706 do not need
707 to duplicate information provided by the declaration entry
708 referenced by the specification attribute.
709
710 \textit{The \addtoindex{C++} \addtoindex{global namespace}
711 (the 
712 \addtoindexx{global namespace|see{namespace (C++), global}}
713 namespace 
714 \addtoindexx{namespace (C++)!global}
715 referred to by
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.}
721
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).
729 }
730
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.
740 }
741
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,
747 for example, 
748 \addtoindexx{namespace (C++)!std}
749 is large and will probably be referenced in
750 every \addtoindex{C++} compilation unit.
751 }
752
753 \textit{For a \addtoindex{C++} namespace example, 
754 see Appendix \refersec{app:namespaceexample}.
755 }
756
757
758
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
764 given another name.
765 }
766
767 An 
768 imported declaration is represented by one or
769 \addtoindexx{imported declaration entry}
770 more debugging information entries with the 
771 tag \DWTAGimporteddeclarationTARG. 
772 When 
773 \hypertarget{chap:DWATimportimporteddeclaration}{}
774 an overloaded entity
775 is imported, there is one imported declaration entry for
776 each overloading. 
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
782 is being imported.
783
784 An imported declaration may also have a 
785 \DWATname{}
786 attribute
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.
795
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.
801
802 \textit{A \addtoindex{C++} namespace alias may be represented by an imported
803 \hypertarget{chap:DWATimportnamespacealias}{}
804 declaration entry 
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.
811 }
812
813 \textit{A \addtoindex{C++} using declaration may be represented by one or more
814 \hypertarget{chap:DWATimportnamespaceusingdeclaration}{}
815 imported 
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).
825 }
826
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.
837 }
838
839 \subsection{Imported Module Entries}
840 \label{chap:importedmoduleentries}
841
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.
845 }
846
847 An imported module declaration is represented by a debugging
848 information entry with 
849 \addtoindexx{imported module attribute}
850 the 
851 \addtoindexx{imported module entry}
852 tag \DWTAGimportedmoduleTARG.
853 An
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.
862
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.
870
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.
879 }
880
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
887 being imported.
888 }
889
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.
896 }
897
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}.
901 }
902
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
908 }
909
910 \begin{lstlisting}
911 module A
912 integer X, Y, Z
913 end module
914
915 module B
916 use A
917 end module
918
919 module C
920 use B, only Q => X
921 end module
922 \end{lstlisting}
923
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.
927 }
928
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}
934 for an example.
935 }
936
937 \section{Subroutine and Entry Point Entries}
938 \label{chap:subroutineandentrypointentries}
939
940 The following tags exist to describe 
941 debugging information entries 
942 \addtoindexx{function entry|see{subroutine entry}}
943 for 
944 \addtoindexx{subroutine entry}
945 subroutines 
946 \addtoindexx{subprogram entry}
947 and entry
948 % FIXME: is entry point entry the right index 'entry'?
949 \addtoindexx{entry point entry}
950 points:
951
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 \\
958 \end{tabular}
959
960
961 \needlines{6}
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}.
969
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}
977
978 \DWATexternalNAME{} attribute,
979 which is a \livelink{chap:classflag}{flag}.
980
981 \textit{Additional attributes for functions that are members of a
982 class or structure are described in 
983 Section \refersec{chap:memberfunctionentries}.
984 }
985
986
987 \hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}{}
988 subroutine entry 
989 may contain a 
990 \DWATmainsubprogramNAME{}
991 attribute 
992 \addtoindexx{main subprogram attribute}
993 which is 
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 
997 \nolink{flag},
998 any one of them may be the starting subroutine of the program.
999
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
1003 a program.
1004 }
1005
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.
1011 }
1012
1013 A subroutine entry may 
1014 \hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}{}
1015 contain a 
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}.
1021
1022 \begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
1023 \DWCCnormal        \\
1024 \DWCCprogram       \\
1025 \DWCCnocall        \\
1026 \end{simplenametable}
1027
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.
1035
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.
1044
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.
1051 }
1052
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.
1057 }
1058
1059 A subroutine entry declared with a function prototype style
1060 declaration may have 
1061 \addtoindexx{prototyped attribute}
1062
1063 \DWATprototypedNAME{} attribute, which is
1064 a \CLASSflag.
1065
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
1073 as \addtoindex{C} 
1074 where functions support recursion by default.
1075 }
1076
1077 A subprogram entry 
1078 \hypertarget{chap:DWATelementalelementalpropertyofasubroutine}{}
1079 may have 
1080 \addtoindexx{elemental attribute}
1081
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
1086 or property.
1087
1088
1089 \hypertarget{chap:DWATpurepurepropertyofasubroutine}{}
1090 subprogram entry may have 
1091 \addtoindexx{pure attribute}
1092
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.
1097
1098
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
1105 or property.
1106
1107 A subprogram entry may have a 
1108 \DWATnoreturnNAME
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.
1113
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.
1120
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.)
1128
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.
1134
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.
1142
1143 \textit{The \DWATcallallsourcecallsNAME{} attribute is intended for debugging 
1144 information format consumers that analyse call graphs.}
1145
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.
1151
1152 \subsection{Subroutine and Entry Point Return Types}
1153 \label{chap:subroutineandentrypointreturntypes}
1154
1155 If 
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.
1164
1165 \textit{Debugging information entries for 
1166 \addtoindex{C} void functions should
1167 not have an attribute for the return type.  }
1168
1169 \textit{Debugging information entries for declarations of \addtoindex{C++} 
1170 member functions with an 
1171 \autoreturntype{} specifier should use an unspecified type entry (see 
1172 Section \refersec{chap:unspecifiedtypeentries}). 
1173 The debugging information entry for the corresponding definition
1174 should provide the deduced return type.  This practice causes the description of
1175 the containing class to be consistent across compilation units, allowing the class
1176 declaration to be placed into a separate type unit if desired.}
1177
1178
1179 \subsection{Subroutine and Entry Point Locations}
1180 \label{chap:subroutineandentrypointlocations}
1181
1182 A subroutine entry may have either a \DWATlowpc{} and
1183 \DWAThighpc{} pair of attributes or a \DWATranges{} attribute
1184 \addtoindexx{ranges attribute}
1185 whose 
1186 \addtoindexx{high PC attribute}
1187 values 
1188 \addtoindexx{low PC attribute}
1189 encode the contiguous or non\dash contiguous address
1190 ranges, respectively, of the machine instructions generated
1191 for the subroutine (see 
1192 Section \refersec{chap:codeaddressesandranges}).
1193
1194
1195 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}{}
1196 subroutine entry may also have 
1197 \addtoindexx{entry pc attribute!for subroutine}
1198
1199 \DWATentrypc{} attribute
1200 whose value is the address of the first executable instruction
1201 of the subroutine (see 
1202 Section \refersec{chap:entryaddress}).
1203
1204 An entry point has a \DWATlowpc{} attribute whose value is the
1205 relocated address of the first machine instruction generated
1206 for the entry point.
1207
1208 \textit{While the 
1209 \DWATentrypc{} attribute 
1210 \addtoindexx{entry pc attribute!for subroutine}
1211 might 
1212 also seem appropriate
1213 for this purpose, historically the 
1214 \DWATlowpc{} attribute
1215 was used before the 
1216 \DWATentrypc{} was introduced (in
1217 \addtoindex{DWARF Version 3}). 
1218 There is insufficient reason to change this.}
1219
1220
1221 Subroutines 
1222 and 
1223 entry
1224 \addtoindexx{address class attribute}
1225 points 
1226 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}{}
1227 may also have 
1228 \DWATsegment{} 
1229 and
1230 \DWATaddressclass{} attributes,
1231 as appropriate, to specify
1232 which segments the code for the subroutine resides in and
1233 the addressing mode to be used in calling that subroutine.
1234
1235 A subroutine entry representing a subroutine declaration
1236 that is not also a definition does not have code address or
1237 range attributes.
1238
1239
1240 \subsection{Declarations Owned by Subroutines and Entry Points} 
1241 \label{chap:declarationsownedbysubroutinesandentrypoints}
1242
1243 The declarations enclosed by a subroutine or entry point are
1244 represented by debugging information entries that are owned
1245 by the subroutine or entry point entry. Entries representing
1246 \addtoindexx{formal parameter}
1247 the formal parameters of the subroutine or entry point appear
1248 in the same order as the corresponding declarations in the
1249 source program.
1250
1251 \needlines{5}
1252 \textit{There is no ordering requirement for entries for declarations
1253 that are children of subroutine or entry point entries but
1254 that do not represent formal parameters. The formal parameter
1255 entries may be interspersed with other entries used by formal
1256 parameter entries, such as type entries.}
1257
1258 The unspecified parameters of a variable parameter list are
1259 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
1260 with the tag
1261 \DWTAGunspecifiedparametersTARG.
1262
1263 \needlines{4}
1264 The entry for a subroutine that includes a
1265 \addtoindex{Fortran}
1266 \addtoindexx{Fortran!common block}
1267 \livelink{chap:fortrancommonblock}{common} 
1268 \livelink{chap:commonblockentry}{block}
1269 \addtoindexx{common block|see{Fortran common block}}
1270 has a child entry with the 
1271 tag \DWTAGcommoninclusionTARG. 
1272 The
1273 \hypertarget{chap:commonreferencecommonblockusage}{}
1274 common inclusion entry has a 
1275 \DWATcommonreference{} attribute
1276 whose value is a \livelink{chap:classreference}{reference} 
1277 to the debugging information entry
1278 for the common \nolink{block} being included 
1279 (see Section \refersec{chap:commonblockentries}).
1280
1281 \subsection{Low-Level Information}
1282 \label{chap:lowlevelinformation}
1283
1284
1285 \hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{}
1286 subroutine or entry point entry may have 
1287 \addtoindexx{return address attribute}
1288
1289 \DWATreturnaddr{}
1290 attribute, whose value is a location description. The location
1291 calculated is the place where the return address for the
1292 subroutine or entry point is stored.
1293
1294
1295 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}{}
1296 subroutine or entry point entry may also have 
1297 \addtoindexx{frame base attribute}
1298 a
1299 \DWATframebase{} attribute, whose value is a location
1300 description that computes the \doublequote{frame base} for the
1301 subroutine or entry point. If the location description is
1302 a simple register location description, the given register
1303 contains the frame base address. If the location description is
1304 a DWARF expression, the result of evaluating that expression
1305 is the frame base address. Finally, for a 
1306 \addtoindex{location list},
1307 this interpretation applies to each location description
1308 contained in the list of \addtoindex{location list} entries.
1309
1310 \textit{The use of one of the \DWOPregn{} 
1311 operations in this
1312 context is equivalent to using 
1313 \DWOPbregn(0) 
1314 but more
1315 compact. However, these are not equivalent in general.}
1316
1317 \needlines{5}
1318 \textit{The frame base for a procedure is typically an address fixed
1319 relative to the first unit of storage allocated for the
1320 procedure\textquoteright s stack frame. The \DWATframebase{} attribute
1321 can be used in several ways:}
1322 \begin{enumerate}[1. ]
1323 \item \textit{In procedures that need 
1324 \addtoindexx{location list}
1325 location lists to locate local
1326 variables, the \DWATframebase{} can hold the needed location
1327 list, while all variables\textquoteright\  location descriptions can be
1328 simpler ones involving the frame base.}
1329
1330 \item \textit{It can be used in resolving \doublequote{up\dash level} addressing
1331 within nested routines. 
1332 (See also \DWATstaticlink, below)}
1333 \end{enumerate}
1334
1335 \needlines{5}
1336 \textit{Some languages support nested subroutines. In such languages,
1337 it is possible to reference the local variables of an
1338 outer subroutine from within an inner subroutine. The
1339 \DWATstaticlink{} and \DWATframebase{} attributes allow
1340 debuggers to support this same kind of referencing.}
1341
1342 If 
1343 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}{}
1344
1345 \addtoindexx{address!uplevel|see {static link attribute}}
1346 \addtoindexx{uplevel address|see {static link attribute}}
1347 subroutine or entry point is nested, it may have a
1348 \DWATstaticlink{}
1349 attribute, whose value is a location
1350 description that computes the frame base of the relevant
1351 instance of the subroutine that immediately encloses the
1352 subroutine or entry point.
1353
1354 In the context of supporting nested subroutines, the
1355 \DWATframebase{} attribute value should obey the following
1356 constraints:
1357
1358 \begin{enumerate}[1. ]
1359 \item It should compute a value that does not change during the
1360 life of the procedure, and
1361
1362 \item The computed value should be unique among instances of
1363 the same subroutine. (For typical \DWATframebase{} use, this
1364 means that a recursive subroutine\textquoteright s stack frame must have
1365 non\dash zero size.)
1366 \end{enumerate}
1367
1368 \textit{If a debugger is attempting to resolve an up\dash level reference
1369 to a variable, it uses the nesting structure of DWARF to
1370 determine which subroutine is the lexical parent and the
1371 \DWATstaticlink{} value to identify the appropriate active
1372 frame of the parent. It can then attempt to find the reference
1373 within the context of the parent.}
1374
1375
1376 \needlines{8}
1377 \subsection{Types Thrown by Exceptions}
1378 \label{chap:typesthrownbyexceptions}
1379
1380 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1381 it may validly throw.}
1382
1383 If a subroutine explicitly declares that it may throw
1384 \addtoindexx{exception thrown|see{thrown type entry}}
1385 an 
1386 \addtoindexx{thrown exception|see{thrown type entry}}
1387 exception of one or more types, each such type is
1388 represented by a debugging information entry with 
1389 \addtoindexx{thrown type entry}
1390 the tag
1391 \DWTAGthrowntypeTARG.  
1392 Each such entry is a child of the entry
1393 representing the subroutine that may throw this type. Each
1394 thrown type entry contains 
1395 \addtoindexx{type attribute}
1396 a \DWATtype{} attribute, whose
1397 value is a \livelink{chap:classreference}{reference} 
1398 to an entry describing the type of the
1399 exception that may be thrown.
1400
1401 \subsection{Function Template Instantiations}
1402 \label{chap:functiontemplateinstantiations}
1403
1404 \textit{In \addtoindex{C++}, a function template is a generic definition of
1405 a function that is instantiated differently for calls with
1406 values of different types. DWARF does not represent the generic
1407 template definition, but does represent each instantiation.}
1408
1409 \needlines{4}
1410 A \addtoindex{template instantiation} is represented by a debugging
1411 information entry with the 
1412 \addtoindexx{subprogram entry!use for template instantiation}
1413 tag \DWTAGsubprogram. 
1414 With the following
1415 exceptions, such an entry will contain the same attributes and
1416 will have the same types of child entries as would an entry
1417 for a subroutine defined explicitly using the instantiation
1418 types and values. The exceptions are:
1419
1420 \begin{enumerate}[1. ]
1421 \item Template parameters are described and referenced as specified in
1422 Section \refersec{chap:templateparameters}.
1423
1424 \item If the compiler has generated a special compilation unit
1425 to hold the template instantiation and that compilation unit
1426 has a different name from the compilation unit containing
1427 the template definition, the name attribute for the debugging
1428 information entry representing that compilation unit is empty
1429 or omitted.
1430
1431 \item If the subprogram entry representing the template
1432 instantiation or any of its child entries contain declaration
1433 coordinate attributes, those attributes refer to the source
1434 for the template definition, not to any source generated
1435 artificially by the compiler for this instantiation.
1436 \end{enumerate}
1437
1438
1439 \needlines{8}
1440 \subsection{Inlinable and Inlined Subroutines}
1441 \label{chap:inlinedsubroutines}
1442 A declaration or a definition of an inlinable subroutine
1443 is represented by a debugging information entry with the
1444 tag 
1445 \DWTAGsubprogram.
1446 The entry for a 
1447 \addtoindexx{subprogram entry!use in inlined subprogram}
1448 subroutine that is
1449 \hypertarget{chap:DWATinlineinlinedsubroutine}{}
1450 explicitly declared to be available for inline expansion or
1451 that was expanded inline implicitly by the compiler has 
1452 \addtoindexx{inline attribute}
1453 a
1454 \DWATinline{} attribute whose value is an 
1455 \livelink{chap:classconstant}{integer constant}. The
1456 set of values for the \DWATinline{} attribute is given in
1457 Table \refersec{tab:inlinecodes}.
1458
1459 \begin{table}[here]
1460 \centering
1461 \caption{Inline codes}
1462 \label{tab:inlinecodes}
1463 \begin{tabular}{l|p{8cm}}
1464 \hline
1465 Name&Meaning\\ \hline
1466 \DWINLnotinlinedTARG{} & Not declared inline nor inlined by the
1467   \mbox{compiler} (equivalent to the absence of the
1468   containing \DWATinline{} attribute) \\
1469 \DWINLinlinedTARG{} & Not declared inline but inlined by the \mbox{compiler} \\
1470 \DWINLdeclarednotinlinedTARG{} & Declared inline but 
1471   not inlined by the \mbox{compiler} \\
1472 \DWINLdeclaredinlinedTARG{} & Declared inline and inlined by the 
1473   \mbox{compiler} \\
1474 \hline
1475 \end{tabular}
1476 \end{table}
1477
1478 \textit{In \addtoindex{C++}, a function or a constructor declared with
1479 \addttindex{constexpr} is implicitly declared inline. The abstract inline
1480 instance (see below) is represented by a debugging information
1481 entry with the tag \DWTAGsubprogram. Such an entry has a
1482 \DWATinline{} attribute whose value is \DWINLinlined.}
1483
1484
1485 \subsubsection{Abstract Instances}
1486 \label{chap:abstractinstances}
1487 Any debugging information entry that is owned (either
1488 \hypertarget{chap:DWATinlineabstracttinstance}{}
1489 directly or indirectly) by a debugging information entry
1490 that contains the 
1491 \DWATinline{} attribute is referred to
1492 \addtoindexx{abstract instance!entry}
1493 as an \doublequote{abstract instance entry.} 
1494 Any subroutine entry
1495 that contains 
1496 \addtoindexx{inline attribute}
1497 a \DWATinline{} attribute whose value is other
1498 than \DWINLnotinlined{}
1499 is known as 
1500 \addtoindexx{abstract instance!root}
1501 an \doublequote{abstract instance root.} 
1502 Any set of abstract instance entries that are all
1503 children (either directly or indirectly) of some abstract
1504 instance root, together with the root itself, is known as
1505 \addtoindexx{abstract instance!tree}
1506 an \doublequote{abstract instance tree.} However, in the case where
1507 an abstract instance tree is nested within another abstract
1508 instance tree, the entries in the 
1509 \addtoindex{nested abstract instance}
1510 tree are not considered to be entries in the outer abstract
1511 instance tree.
1512
1513 Each abstract instance root is either part of a larger
1514 \addtoindexx{abstract instance!root}
1515 tree (which gives a context for the root) or 
1516 \addtoindexx{specification attribute}
1517 uses
1518 \DWATspecification{} 
1519 to refer to the declaration in context.
1520
1521 \textit{For example, in \addtoindex{C++} the context might be a namespace
1522 declaration or a class declaration.}
1523
1524 \textit{Abstract instance trees are defined so that no entry is part
1525 of more than one abstract instance tree. This simplifies the
1526 following descriptions.}
1527
1528 A debugging information entry that is a member of an abstract
1529 instance tree should not contain any attributes which describe
1530 aspects of the subroutine which vary between distinct inlined
1531 expansions or distinct out\dash of\dash line expansions. For example,
1532 \addtoindexx{entry pc attribute!and abstract instance}
1533 the \DWATlowpc,
1534 \DWAThighpc, 
1535 \DWATranges, 
1536 \DWATentrypc, 
1537 \DWATlocation,
1538 \DWATreturnaddr, 
1539 \DWATstartscope, 
1540 and 
1541 \DWATsegment{}
1542 attributes 
1543 \addtoindexx{location attribute!and abstract instance}
1544 typically 
1545 \addtoindexx{ranges attribute!and abstract instance}
1546 should 
1547 \addtoindexx{high PC attribute!and abstract instance}
1548 be 
1549 \addtoindexx{low PC attribute!and abstract instance}
1550 omitted; 
1551 \addtoindexx{segment attribute!and abstract instance}
1552 however, 
1553 \addtoindexx{return address attribute!and abstract instance}
1554 this 
1555 \addtoindexx{segment attribute!and abstract instance}
1556 list
1557 \addtoindexx{start scope attribute!and abstract instance}
1558 is not exhaustive.
1559
1560 \needlines{5}
1561 \textit{It would not make sense normally to put these attributes into
1562 abstract instance entries since such entries do not represent
1563 actual (concrete) instances and thus do not actually exist at
1564 run\dash time.  However, 
1565 see Appendix \refersec{app:inlineouteronenormalinner} 
1566 for a contrary example.}
1567
1568 The rules for the relative location of entries belonging to
1569 abstract instance trees are exactly the same as for other
1570 similar types of entries that are not abstract. Specifically,
1571 the rule that requires that an entry representing a declaration
1572 be a direct child of the entry representing the scope of the
1573 declaration applies equally to both abstract and non\dash abstract
1574 entries. Also, the ordering rules for formal parameter entries,
1575 member entries, and so on, all apply regardless of whether
1576 or not a given entry is abstract.
1577
1578 \needlines{5}
1579 \subsubsection{Concrete Inlined Instances}
1580 \label{chap:concreteinlinedinstances}
1581
1582 Each inline expansion of a subroutine is represented
1583 by a debugging information entry with the 
1584 tag \DWTAGinlinedsubroutineTARG. 
1585 Each such entry should be a direct
1586 child of the entry that represents the scope within which
1587 the inlining occurs.
1588
1589 \needlines{4}
1590 Each inlined subroutine entry may have either a 
1591 \DWATlowpc{}
1592 and \DWAThighpc{} pair 
1593 of 
1594 \addtoindexx{high PC attribute}
1595 attributes 
1596 \addtoindexx{low PC attribute}
1597 or 
1598 \addtoindexx{ranges attribute}
1599
1600 \DWATranges{}
1601 attribute whose values encode the contiguous or non\dash contiguous
1602 address ranges, respectively, of the machine instructions
1603 generated for the inlined subroutine (see 
1604 Section \referfol{chap:codeaddressesandranges}). 
1605 An
1606 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}{}
1607 inlined subroutine entry may 
1608 \addtoindexx{inlined subprogram entry!in concrete instance}
1609 also 
1610 \addtoindexx{inlined subprogram entry}
1611 contain 
1612 \addtoindexx{entry pc attribute!for inlined subprogram}
1613
1614 \DWATentrypc{}
1615 attribute, representing the first executable instruction of
1616 the inline expansion (see 
1617 Section \refersec{chap:entryaddress}).
1618
1619 % Positions of the 3 targets here is a bit arbitrary.
1620 An inlined 
1621 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{}
1622 subroutine 
1623 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{}
1624 entry 
1625 \hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{}
1626 may also have \DWATcallfile,
1627 \DWATcallline{} and \DWATcallcolumn{} attributes, 
1628 each of whose
1629 value is an \livelink{chap:classconstant}{integer constant}. 
1630 These attributes represent the
1631 source file, source line number, and source column number,
1632 respectively, of the first character of the statement or
1633 expression that caused the inline expansion. The call file,
1634 call line, and call column attributes are interpreted in
1635 the same way as the declaration file, declaration line, and
1636 declaration column attributes, respectively (see 
1637 Section \refersec{chap:declarationcoordinates}).
1638
1639 \textit{The call file, call line and call column coordinates do not
1640 describe the coordinates of the subroutine declaration that
1641 was inlined, rather they describe the coordinates of the call.
1642 }
1643
1644 An inlined subroutine entry 
1645 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}{}
1646 may have a 
1647 \DWATconstexpr{}
1648 attribute, which is a \livelink{chap:classflag}{flag} 
1649 whose presence indicates that the
1650 subroutine has been evaluated as a compile\dash time constant. Such
1651 an entry may also have a \DWATconstvalue{} attribute,
1652 whose value may be of any form that is appropriate for the
1653 representation of the subroutine's return value. The value of
1654 this attribute is the actual return value of the subroutine,
1655 represented as it would be on the target architecture.
1656
1657 \textit{In \addtoindex{C++}, if a function or a constructor declared with 
1658 \addttindex{constexpr}
1659 is called with constant expressions, then the corresponding
1660 concrete inlined instance has a 
1661 \DWATconstexpr{} attribute,
1662 as well as a \DWATconstvalue{} attribute whose value represents
1663 the actual return value of the concrete inlined instance.}
1664
1665 Any debugging information entry that is owned (either
1666 directly or indirectly) by a debugging information entry
1667 with the tag \DWTAGinlinedsubroutine{} is referred to as a
1668 \doublequote{concrete inlined instance entry.} Any entry that has
1669 the tag 
1670 \DWTAGinlinedsubroutine{} 
1671 is known as a \doublequote{concrete inlined instance root.} 
1672 Any set of concrete inlined instance
1673 entries that are all children (either directly or indirectly)
1674 of some concrete inlined instance root, together with the root
1675 itself, is known as a \doublequote{concrete inlined instance tree.}
1676 However, in the case where a concrete inlined instance tree
1677 is nested within another concrete instance tree, the entries
1678 in the \addtoindex{nested concrete inline instance} tree 
1679 are not considered to
1680 be entries in the outer concrete instance tree.
1681
1682 \needlines{3}
1683 \textit{Concrete inlined instance trees are defined so that no entry
1684 is part of more than one concrete inlined instance tree. This
1685 simplifies later descriptions.}
1686
1687 Each concrete inlined instance tree is uniquely associated
1688 with one (and only one) abstract instance tree.
1689
1690 \textit{Note, however, that the reverse is not true. Any given abstract
1691 instance tree may be associated with several different concrete
1692 inlined instance trees, or may even be associated with zero
1693 concrete inlined instance trees.}
1694
1695 Concrete inlined instance entries may omit attributes that
1696 are not specific to the concrete instance (but present in
1697 the abstract instance) and need include only attributes that
1698 are specific to the concrete instance (but omitted in the
1699 abstract instance). In place of these omitted attributes, each
1700 \hypertarget{chap:DWATabstractorigininlineinstance}{}
1701 concrete inlined instance entry 
1702 \addtoindexx{abstract origin attribute}
1703 has a 
1704 \DWATabstractorigin{}
1705 attribute that may be used to obtain the missing information
1706 (indirectly) from the associated abstract instance entry. The
1707 value of the abstract origin attribute is a reference to the
1708 associated abstract instance entry.
1709
1710 If an entry within a concrete inlined instance tree contains
1711 attributes describing the 
1712 \addtoindexx{declaration coordinates!in concrete instance}
1713 \livelink{chap:declarationcoordinates}{declaration coordinates} 
1714 of that entry, then those attributes should refer to the file, line
1715 and column of the original declaration of the subroutine,
1716 not to the point at which it was inlined. As a consequence,
1717 they may usually be omitted from any entry that has an abstract
1718 origin attribute.
1719
1720 \needlines{4}
1721 For each pair of entries that are associated via a
1722 \addtoindexx{abstract origin attribute}
1723 \DWATabstractorigin{} attribute, both members of the pair
1724 have the same tag. So, for example, an entry with the tag
1725 \DWTAGvariable{} can only be associated with another entry
1726 that also has the tag \DWTAGvariable. The only exception
1727 to this rule is that the root of a concrete instance tree
1728 (which must always have the tag \DWTAGinlinedsubroutine)
1729 can only be associated with the root of its associated abstract
1730 instance tree (which must have the tag \DWTAGsubprogram).
1731
1732 \needlines{6}
1733 In general, the structure and content of any given concrete
1734 inlined instance tree will be closely analogous to the
1735 structure and content of its associated abstract instance
1736 tree. There are a few exceptions:
1737
1738 \begin{enumerate}[1. ]
1739 \item An entry in the concrete instance tree may be omitted if
1740 it contains only a 
1741 \addtoindexx{abstract origin attribute}
1742 \DWATabstractorigin{} attribute and either
1743 has no children, or its children are omitted. Such entries
1744 would provide no useful information. In C\dash like languages,
1745 such entries frequently include types, including structure,
1746 union, class, and interface types; and members of types. If any
1747 entry within a concrete inlined instance tree needs to refer
1748 to an entity declared within the scope of the relevant inlined
1749 subroutine and for which no concrete instance entry exists,
1750 the reference should refer to the abstract instance entry.
1751
1752 \needlines{4}
1753 \item Entries in the concrete instance tree which are associated
1754 with entries in the abstract instance tree such that neither
1755 has a \DWATname{} attribute,
1756 \addtoindexx{name attribute}
1757 and neither is referenced by
1758 any other debugging information entry, may be omitted. This
1759 may happen for debugging information entries in the abstract
1760 instance trees that became unnecessary in the concrete instance
1761 tree because of additional information available there. For
1762 example, an anonymous variable might have been created and
1763 described in the abstract instance tree, but because of
1764 the actual parameters for a particular inlined expansion,
1765 it could be described as a constant value without the need
1766 for that separate debugging information entry.
1767
1768 \item A concrete instance tree may contain entries which do
1769 not correspond to entries in the abstract instance tree
1770 to describe new entities that are specific to a particular
1771 inlined expansion. In that case, they will not have associated
1772 entries in the abstract instance tree, should not contain
1773 \addtoindexx{abstract origin attribute}
1774 \DWATabstractorigin{} attributes, and must contain all their
1775 own attributes directly. This allows an abstract instance tree
1776 to omit debugging information entries for anonymous entities
1777 that are unlikely to be needed in most inlined expansions. In
1778 any expansion which deviates from that expectation, the
1779 entries can be described in its concrete inlined instance tree.
1780
1781 \end{enumerate}
1782
1783 \subsubsection{Out-of-Line Instances of Inlined Subroutines}
1784 \label{chap:outoflineinstancesofinlinedsubroutines}
1785 Under some conditions, compilers may need to generate concrete
1786 executable instances of inlined subroutines other than at
1787 points where those subroutines are actually called. Such
1788 concrete instances of inlined subroutines are referred to as
1789 \doublequote{concrete out\dash of\dash line instances.}
1790
1791 \textit{In \addtoindex{C++}, for example, 
1792 taking the address of a function declared
1793 to be inline can necessitate the generation of a concrete
1794 out\dash of\dash line instance of the given function.}
1795
1796 The DWARF representation of a concrete out\dash of\dash line instance
1797 of an inlined subroutine is essentially the same as for a
1798 concrete inlined instance of that subroutine (as described in
1799 the preceding section). The representation of such a concrete
1800 % It is critical that the hypertarget and livelink be
1801 % separated to avoid problems with latex.
1802 out\dash of\dash line 
1803 \addtoindexx{abstract origin attribute}
1804 instance 
1805 \hypertarget{chap:DWATabstractoriginoutoflineinstance}{}
1806 makes use of 
1807 \DWATabstractorigin{}
1808 attributes in exactly the same way as they are used for
1809 a concrete inlined instance (that is, as references to
1810 corresponding entries within the associated abstract instance
1811 tree).
1812
1813 \needlines{5}
1814 The differences between the DWARF representation of a
1815 concrete out\dash of\dash line instance of a given subroutine and the
1816 representation of a concrete inlined instance of that same
1817 subroutine are as follows:
1818
1819 \begin{enumerate}[1. ]
1820 \item  The root entry for a concrete out\dash of\dash line instance
1821 of a given inlined subroutine has the same tag as does its
1822 associated (abstract) inlined subroutine entry (that is, tag
1823 \DWTAGsubprogram{} rather than \DWTAGinlinedsubroutine).
1824
1825 \item The root entry for a concrete out\dash of\dash line instance tree
1826 is normally owned by the same parent entry that also owns
1827 the root entry of the associated abstract instance. However,
1828 it is not required that the abstract and out\dash of\dash line instance
1829 trees be owned by the same parent entry.
1830
1831 \end{enumerate}
1832
1833 \subsubsection{Nested Inlined Subroutines}
1834 \label{nestedinlinedsubroutines}
1835 Some languages and compilers may permit the logical nesting of
1836 a subroutine within another subroutine, and may permit either
1837 the outer or the nested subroutine, or both, to be inlined.
1838
1839 For a non\dash inlined subroutine nested within an inlined
1840 subroutine, the nested subroutine is described normally in
1841 both the abstract and concrete inlined instance trees for
1842 the outer subroutine. All rules pertaining to the abstract
1843 and concrete instance trees for the outer subroutine apply
1844 also to the abstract and concrete instance entries for the
1845 nested subroutine.
1846
1847 \needlines{5}
1848 For an inlined subroutine nested within another inlined
1849 subroutine, the following rules apply to their abstract and
1850 \addtoindexx{abstract instance!nested}
1851 \addtoindexx{concrete instance!nested}
1852 concrete instance trees:
1853
1854 \begin{enumerate}[1. ]
1855 \item The abstract instance tree for the nested subroutine is
1856 described within the abstract instance tree for the outer
1857 subroutine according to the rules in 
1858 Section \refersec{chap:abstractinstances}, and
1859 without regard to the fact that it is within an outer abstract
1860 instance tree.
1861
1862 \item Any abstract instance tree for a nested subroutine is
1863 always omitted within the concrete instance tree for an
1864 outer subroutine.
1865
1866 \item  A concrete instance tree for a nested subroutine is
1867 always omitted within the abstract instance tree for an
1868 outer subroutine.
1869
1870 \item The concrete instance tree for any inlined or 
1871 \addtoindexx{out-of-line instance}
1872 out-of-line
1873 \addtoindexx{out-of-line instance|see{\textit{also} concrete out-of-line instance}}
1874 expansion of the nested subroutine is described within a
1875 concrete instance tree for the outer subroutine according
1876 to the rules in 
1877 Sections \refersec{chap:concreteinlinedinstances} or 
1878 \referfol{chap:outoflineinstancesofinlinedsubroutines}
1879 , respectively,
1880 and without regard to the fact that it is within an outer
1881 concrete instance tree.
1882 \end{enumerate}
1883
1884 See Appendix \refersec{app:inliningexamples} 
1885 for discussion and examples.
1886
1887 \subsection{Trampolines}
1888 \label{chap:trampolines}
1889
1890 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1891 \hypertarget{chap:DWATtrampolinetargetsubroutine}{}
1892 an intermediary in making a call to another subroutine. It may
1893 adjust parameters and/or the result (if any) as appropriate
1894 to the combined calling and called execution contexts.}
1895
1896 A trampoline is represented by a debugging information entry
1897 \addtoindexx{trampoline (subprogram) entry}
1898 with the tag \DWTAGsubprogram{} or \DWTAGinlinedsubroutine{}
1899 that has 
1900 \addtoindexx{trampoline attribute}
1901 a \DWATtrampoline{} attribute. 
1902 The value of that
1903 attribute indicates the target subroutine of the trampoline,
1904 that is, the subroutine to which the trampoline passes
1905 control. (A trampoline entry may but need not also have a
1906 \DWATartificial{} attribute.)
1907
1908 \needlines{5}
1909 The value of the trampoline attribute may be represented
1910 using any of the following forms, which are listed in order
1911 of preference:
1912
1913 \begin{itemize}
1914 \item If the value is of class reference, then the value
1915 specifies the debugging information entry of the target
1916 subprogram.
1917
1918 \item If the value is of class address, then the value is
1919 the relocated address of the target subprogram.
1920
1921 \item If the value is of class string, then the value is the
1922 (possibly mangled) \addtoindexx{mangled names}
1923 name of the target subprogram.
1924
1925 \item If the value is of class \livelink{chap:classflag}{flag}, then the value true
1926 indicates that the containing subroutine is a trampoline but
1927 that the target subroutine is not known.
1928 \end{itemize}
1929
1930
1931 The target subprogram may itself be a trampoline. (A sequence
1932 of trampolines necessarily ends with a non\dash trampoline
1933 subprogram.)
1934
1935 \textit{In \addtoindex{C++}, trampolines may be used 
1936 to implement derived virtual
1937 member functions; such trampolines typically adjust the
1938 \addtoindexx{this parameter}
1939 implicit this pointer parameter in the course of passing
1940 control.  
1941 Other languages and environments may use trampolines
1942 in a manner sometimes known as transfer functions or transfer
1943 vectors.}
1944
1945 \textit{Trampolines may sometimes pass control to the target
1946 subprogram using a branch or jump instruction instead of a
1947 call instruction, thereby leaving no trace of their existence
1948 in the subsequent execution context. }
1949
1950 \textit{This attribute helps make it feasible for a debugger to arrange
1951 that stepping into a trampoline or setting a breakpoint in
1952 a trampoline will result in stepping into or setting the
1953 breakpoint in the target subroutine instead. This helps to
1954 hide the compiler generated subprogram from the user. }
1955
1956 \textit{If the target subroutine is not known, a debugger may choose
1957 to repeatedly step until control arrives in a new subroutine
1958 which can be assumed to be the target subroutine. }
1959
1960 \subsection{Call Site Entries}
1961 \label{chap:callsiteentries}
1962 \textit{
1963 A call site entry provides a way to represent the static or dynamic 
1964 call graph of a program in the debugging information. It also provides
1965 information about how parameters are passed so that they may be more
1966 easily accessed by a debugger. Together with the \DWOPentryvalue{} opcode,
1967 call site entries can be also useful for computing values of variables 
1968 and expressions where some value is no longer present in the current 
1969 subroutine's registers or local stack frame, but it is known that the 
1970 values are equal to some parameter passed to the function.  
1971 The consumer can then use unwind
1972 information to find the caller and in the call site information sometimes
1973 find how to compute the value passed in a particular parameter.}
1974
1975 A call site is represented by a debugging information entry with the tag
1976 \DWTAGcallsiteTARG{}.  The entry for a call site is owned by the innermost
1977 debugging information entry representing the scope within which the
1978 call is present in the source program.
1979
1980 \textit{A scope entry (for example, for a lexical block) that would not 
1981 otherwise be present in the debugging information of a subroutine
1982 need not be introduced solely to represent the immediately containing scope
1983 of a call. The call site entry is owned by the innermost scope entry that
1984 is present.}
1985
1986 A source call can be compiled into different types of machine code:
1987 \begin{itemize}
1988 \item
1989 A \textit{normal call} uses a call-like instruction which transfers control to the start
1990 of some subprogram and leaves the call site location address somewhere where
1991 unwind information can find it.  
1992 \item
1993 A \textit{tail call} uses a jump-like instruction which
1994 transfers control to the start of some subprogram, but the call site location
1995 address is not preserved (and thus not available using the unwind information).  
1996 \item
1997 A \textit{tail recursion call} is a call
1998 to the current subroutine which is compiled as a loop into the middle of the
1999 current subroutine.
2000 \item
2001 An \textit{inline (or inlined) call} is a call to an inlined subprogram,
2002 where at least one instruction has the location of the inlined subprogram
2003 or any of its blocks or inlined subprograms. 
2004 \end{itemize}
2005
2006 \needlines{4}
2007 There are also different types of \doublequote{optimized out} calls:
2008 \begin{itemize}
2009 \item
2010 An \textit{optimized out (normal) call} is a call that is in unreachable code that 
2011 has not been emitted (such as, for example, the call to \texttt{foo} in 
2012 \texttt{if (0) foo();}).  
2013 \item
2014 An \textit{optimized out inline call}
2015 is a call to an inlined subprogram which either did not expand to any instructions
2016 or only parts of instructions belong to it and for debug information purposes those
2017 instructions are given a location in the caller.
2018 \end{itemize}
2019
2020 \DWTAGcallsite{} entries describe normal and tail calls but not tail recursion calls,
2021 while \DWTAGinlinedsubroutine{} entries describe inlined calls 
2022 (see Section \refersec{chap:inlinedsubroutines}).
2023
2024 The call site entry has a 
2025 \DWATcallreturnpcNAME{}
2026 \livetargi{chap:DWATcallreturnpcofcallsite}{attribute}{call return pc attribute} 
2027 which is the return address after the call.  
2028 The value of this attribute corresponds to the return address computed by 
2029 call frame information in the called subprogram 
2030 (see Section \refersec{datarep:callframeinformation}).
2031
2032 \textit{On many architectures the return address is the address immediately following the
2033 call instruction, but on architectures with delay slots it might
2034 be an address after the delay slot of the call.}
2035
2036 The call site entry may have a 
2037 \DWATcallpcNAME{}
2038 \livetargi{chap:DWATcallpcofcallsite}{attribute}{call pc attribute} which is the
2039 address of the call instruction.
2040
2041 If the call site entry corresponds to a tail call, it has the 
2042 \DWATcalltailcallNAME{}
2043 \livetargi{chap:DWATcalltailcallofcallsite}{attribute}{call tail call attribute},
2044 which is a \CLASSflag.
2045
2046 The call site entry may have a 
2047 \DWATcalloriginNAME{}
2048 \livetargi{chap:DWATcalloriginofcallsite}{attribute}{call origin attribute}
2049 which is a \CLASSreference.  For direct calls or jumps where the called subprogram is
2050 known it is a reference to the called subprogram's debugging
2051 information entry.  For indirect calls it may be a reference to a
2052 \DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
2053 the subroutine pointer that is called.
2054
2055 The call site may have a 
2056 \DWATcalltargetNAME{}
2057 \livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
2058 a DWARF expression.  For indirect calls or jumps where it is unknown at
2059 compile time which subprogram will be called the expression computes the
2060 address of the subprogram that will be called.  The DWARF expression should
2061 not use register or memory locations that might be clobbered by the call.
2062
2063 The call site entry may have a 
2064 \DWATcalltargetclobberedNAME{}
2065 \livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
2066 which is a DWARF expression.  For indirect calls or jumps where the
2067 address is not computable without use of registers or memory locations that
2068 might be clobbered by the call the \DWATcalltargetclobberedNAME{}
2069 attribute is used instead of the \DWATcalltarget{} attribute.
2070
2071 The call site entry may have a \DWATtypeNAME{}
2072 \livetargi{chap:DWATtypeofcallsite}{attribute}{type attribute!of call site entry}
2073 referencing a debugging information entry for the type of the called function.  
2074 When \DWATcallorigin{} is present, \DWATtypeNAME{} is usually omitted.
2075
2076 The call site entry may have 
2077 \DWATcallfileNAME{}, \DWATcalllineNAME{} and \DWATcallcolumnNAME{} 
2078 \livetargi{chap:DWATcallfileofcallsite}{attributes,}{call file attribute!of call site entry}
2079 \livetargi{chap:DWATcalllineofcallsite}{}{call line attribute!of call site entry}
2080 \livetargi{chap:DWATcallcolumnofcallsite}{}{call column attribute!of call site entry}
2081 each of whose value is an integer constant.
2082 These attributes represent the source file, source line number, and source
2083 column number, respectively, of the first character of the call statement or
2084 expression.  The call file, call line, and call column attributes are
2085 interpreted in the same way as the declaration file, declaration
2086 line, and declaration column attributes, respectively 
2087 (see Section \refersec{chap:declarationcoordinates}).
2088
2089 \textit{The call file, call line and call column coordinates do not describe the
2090 coordinates of the subroutine declaration that was inlined, rather they describe
2091 the coordinates of the call.}
2092
2093 The call site entry may own \DWTAGcallsiteparameterTARG{} debugging information
2094 entries\index{call site parameter entry} representing the parameters passed to the call.
2095 Each such entry has a \DWATlocation{} attribute which is a location expression.
2096 This location expression describes where the parameter is passed
2097 (usually either some register, or a memory location expressible as the
2098 contents of the stack register plus some offset).
2099
2100 Each \DWTAGcallsiteparameter{} entry may have a 
2101 \DWATcallvalueNAME{}
2102 \livetargi{chap:DWATcallvalueofcallparameter}{attribute}{call value attribute}
2103 which is a DWARF expression.  This expression computes the value
2104 passed for that parameter.  The expression should not use registers or memory
2105 locations that might be clobbered by the call, as it might be evaluated after
2106 unwinding from the called function back to the caller.  If it is not
2107 possible to avoid registers or memory locations that might be clobbered by
2108 the call in the expression, then the \DWATcallvalueNAME{} attribute should
2109 not be provided.
2110
2111 \textit{The reason for the restriction is that the value of the parameter may be
2112 needed in the middle of the callee, where the call clobbered registers or
2113 memory might be already clobbered, and if the consumer was not assured by
2114 the producer it can safely use those values, the consumer could not safely
2115 use the values at all.}
2116
2117 For parameters passed by reference, where the code passes a pointer to
2118 a location which contains the parameter, or for reference type parameters
2119 the \DWTAGcallsiteparameter{} entry may also have 
2120 \DWATcalldatalocationNAME{}
2121 \livetargi{chap:DWATcalldatalocationofcallparameter}{attribute}{call data location attribute}
2122 whose value is a location expression and a
2123 \DWATcalldatavalueNAME{}
2124 \livetargi{chap:DWATcalldatavalueofcallparameter}{attribute}{call data value attribute}
2125 whose value is a DWARF expression.  The \DWATcalldatalocationNAME{} attribute 
2126 describes where the referenced value lives during the call.  If it is just 
2127 \DWOPpushobjectaddress{}, it may be left out.  The 
2128 \DWATcalldatavalueNAME{} attribute describes the value in that location. 
2129 The expression should not use registers or memory
2130 locations that might be clobbered by the call, as it might be evaluated after
2131 unwinding from the called function back to the caller.
2132
2133 \needlines{4}
2134 Each call site parameter entry may also have a 
2135 \DWATcallparameter{}
2136 \livetargi{chap:DWATcallparameterofcallparameter}{attribute}{call parameter attribute}
2137 which contains a reference to a \DWTAGformalparameter{} entry,
2138 \DWATtype{} attribute referencing the type of the parameter or \DWATname{}
2139 attribute describing the parameter's name.
2140
2141
2142
2143 \section{Lexical Block Entries}
2144 \label{chap:lexicalblockentries}
2145
2146 \textit{A 
2147 lexical \livetargi{chap:lexicalblock}{block}{lexical block} 
2148 is 
2149 \addtoindexx{lexical block}
2150 a bracketed sequence of source statements
2151 that may contain any number of declarations. In some languages
2152 (including \addtoindex{C} and \addtoindex{C++}),
2153 \nolink{blocks} can be nested within other
2154 \nolink{blocks} to any depth.}
2155
2156 % We do not need to link to the preceding paragraph.
2157 A lexical \nolink{block} is represented by a debugging information
2158 entry with the 
2159 tag \DWTAGlexicalblockTARG.
2160
2161 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} 
2162 entry may have 
2163 either a \DWATlowpc{} and
2164 \DWAThighpc{} pair of 
2165 attributes 
2166 \addtoindexx{high PC attribute}
2167 or 
2168 \addtoindexx{low PC attribute}
2169
2170 \DWATranges{} attribute
2171 \addtoindexx{ranges attribute}
2172 whose values encode the contiguous or non-contiguous address
2173 ranges, respectively, of the machine instructions generated
2174 for the lexical \nolink{block} 
2175 (see Section \refersec{chap:codeaddressesandranges}).
2176
2177
2178 \hypertarget{chap:DWATentrypcoflexicalblock}{}
2179 lexical block entry may also have 
2180 \addtoindexx{entry pc attribute!for lexical block}
2181
2182 \DWATentrypc{} attribute
2183 whose value is the address of the first executable instruction
2184 of the lexical block (see 
2185 Section \refersec{chap:entryaddress}).
2186
2187 If a name has been given to the 
2188 lexical \nolink{block} 
2189 in the source
2190 program, then the corresponding 
2191 lexical \nolink{block} entry has a
2192 \DWATname{} attribute whose 
2193 \addtoindexx{name attribute}
2194 value is a null\dash terminated string
2195 containing the name of the lexical \nolink{block} 
2196 as it appears in
2197 the source program.
2198
2199 \textit{This is not the same as a \addtoindex{C} or 
2200 \addtoindex{C++} label (see below).}
2201
2202 The lexical \nolink{block} entry owns 
2203 debugging information entries that
2204 describe the declarations within that lexical \nolink{block}. 
2205 There is
2206 one such debugging information entry for each local declaration
2207 of an identifier or inner lexical \nolink{block}.
2208
2209 \needlines{10}
2210 \section{Label Entries}
2211 \label{chap:labelentries}
2212 \textit{A label is a way of identifying a source statement. A labeled
2213 statement is usually the target of one or more \doublequote{go to}
2214 statements.
2215 }
2216
2217 \needlines{4}
2218 A label is represented by a debugging information entry with
2219 \addtoindexx{label entry}
2220 the 
2221 tag \DWTAGlabelTARG. 
2222 The entry for a label should be owned by
2223 the debugging information entry representing the scope within
2224 which the name of the label could be legally referenced within
2225 the source program.
2226
2227 The label entry has a \DWATlowpc{} attribute whose value
2228 is the relocated address of the first machine instruction
2229 generated for the statement identified by the label in
2230 the source program.  The label entry also has a 
2231 \DWATname{} attribute 
2232 \addtoindexx{name attribute}
2233 whose value is a null-terminated string containing
2234 the name of the label as it appears in the source program.
2235
2236
2237 \section{With Statement Entries}
2238 \label{chap:withstatemententries}
2239
2240 \textit{Both \addtoindex{Pascal} and 
2241 \addtoindexx{Modula-2}
2242 Modula\dash 2 support the concept of a \doublequote{with}
2243 statement. The with statement specifies a sequence of
2244 executable statements within which the fields of a record
2245 variable may be referenced, unqualified by the name of the
2246 record variable.}
2247
2248 A with statement is represented by a
2249 \addtoindexi{debugging information entry}{with statement entry}
2250 with the tag \DWTAGwithstmtTARG.
2251
2252 A with statement entry may have either a 
2253 \DWATlowpc{} and
2254 \DWAThighpc{} pair of attributes 
2255 \addtoindexx{high PC attribute}
2256 or 
2257 \addtoindexx{low PC attribute}
2258 a \DWATranges{} attribute
2259 \addtoindexx{ranges attribute}
2260 whose values encode the contiguous or non\dash contiguous address
2261 ranges, respectively, of the machine instructions generated
2262 for the with statement 
2263 (see Section \refersec{chap:codeaddressesandranges}).
2264
2265
2266 \hypertarget{chap:DWATentrypcofwithstmt}{}
2267 with statement entry may also have 
2268 \addtoindexx{entry pc attribute!for with statement}
2269
2270 \DWATentrypc{} attribute
2271 whose value is the address of the first executable instruction
2272 of the with statement (see 
2273 Section \refersec{chap:entryaddress}).
2274
2275 \needlines{5}
2276 The with statement entry has 
2277 \addtoindexx{type attribute}
2278 a \DWATtype{} attribute, denoting
2279 the type of record whose fields may be referenced without full
2280 qualification within the body of the statement. It also has
2281 \addtoindexx{location attribute}
2282 a \DWATlocation{} attribute, describing how to find the base
2283 address of the record object referenced within the body of
2284 the with statement.
2285
2286 \needlines{6}
2287 \section{Try and Catch Block Entries}
2288 \label{chap:tryandcatchblockentries}
2289
2290 \textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be 
2291 designated as a \doublequote{catch \nolink{block}.} 
2292 A catch \livetargi{chap:catchblock}{block}{catch block} is an 
2293 exception handler that handles
2294 exceptions thrown by an immediately 
2295 preceding \doublequote{try \livelink{chap:tryblock}{block}.}
2296 A catch \livelink{chap:catchblock}{block} 
2297 designates the type of the exception that it
2298 can handle.}
2299
2300 A try \livetargi{chap:tryblock}{block}{try block} is represented 
2301 by a debugging information entry
2302 \addtoindexx{try block entry}
2303 with the tag \DWTAGtryblockTARG.  
2304 A catch \livelink{chap:catchblock}{block} is represented by
2305 a debugging information entry with 
2306 \addtoindexx{catch block entry}
2307 the tag \DWTAGcatchblockTARG.
2308
2309 % nolink as we have links just above and do not have a combo link for both
2310 Both try and catch \nolink{block} entries may have either a
2311 \DWATlowpc{} and 
2312 \DWAThighpc{} pair of attributes 
2313 \addtoindexx{high PC attribute}
2314 or 
2315 \addtoindexx{low PC attribute}
2316 a
2317 \DWATranges{} attribute 
2318 \addtoindexx{ranges attribute}
2319 whose values encode the contiguous
2320 or non\dash contiguous address ranges, respectively, of the
2321 machine instructions generated for the \livelink{chap:lexicalblock}{block}
2322 (see Section
2323 \refersec{chap:codeaddressesandranges}).
2324
2325
2326 \hypertarget{chap:DWATentrypcoftryblock}{}
2327 \hypertarget{chap:DWATentrypcofcatchblock}{}
2328 try or catch block entry may also have 
2329 \addtoindexx{entry pc attribute!for try block}
2330 \addtoindexx{entry pc attribute!for catch block}
2331
2332 \DWATentrypc{} attribute
2333 whose value is the address of the first executable instruction
2334 of the try or catch block (see 
2335 Section \refersec{chap:entryaddress}).
2336
2337 Catch \livelink{chap:catchblock}{block} entries have at 
2338 least one child entry, an
2339 entry representing the type of exception accepted by
2340 that catch \livelink{chap:catchblock}{block}. 
2341 This child entry has one of 
2342 \addtoindexx{formal parameter entry!in catch block}
2343 the 
2344 \addtoindexx{unspecified parameters entry!in catch block}
2345 tags
2346 \DWTAGformalparameter{} or
2347 \DWTAGunspecifiedparameters,
2348 and will have the same form as other parameter entries.
2349
2350 The siblings immediately following 
2351 a try \livelink{chap:tryblock}{block} entry are its
2352 corresponding catch \livelink{chap:catchblock}{block} entries.
2353