6ef456bd5a3e7ca512e5264d56b2f332b884abd1
[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 language} \\
157 \DWLANGFortranseventysevenTARG & ISO FORTRAN:1977 \addtoindexx{FORTRAN:1977 (ISO)} \\
158 \DWLANGFortranninetyTARG       & ISO Fortran:1990 \addtoindexx{Fortran:1990 (ISO)} \\
159 \DWLANGFortranninetyfiveTARG   & ISO Fortran:1995 \addtoindexx{Fortran:1995 (ISO)} \\
160 \DWLANGGoTARG{}~\dag & \addtoindex{Go} \\
161 \DWLANGHaskellTARG{} \dag & \addtoindex{Haskell} \\
162 \DWLANGJavaTARG{} & \addtoindex{Java}\\
163 \DWLANGJuliaTARG{}~\dag & \addtoindex{Julia} \\
164 \DWLANGModulatwoTARG   & ISO Modula\dash 2:1996 \addtoindexx{Modula-2:1996 (ISO)} \\
165 \DWLANGModulathreeTARG & \addtoindex{Modula-3} \\
166 \DWLANGObjCTARG{}         & \addtoindex{Objective C} \\
167 \DWLANGObjCplusplusTARG{} & \addtoindex{Objective C++} \\
168 \DWLANGOCamlTARG{}~\dag  & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}} \\
169 \DWLANGOpenCLTARG{}~\dag & \addtoindex{OpenCL} \\
170 \DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\
171 \DWLANGPLITARG{}~\dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
172 \DWLANGPythonTARG{}~\dag & \addtoindex{Python} \\
173 \DWLANGRustTARG{}~\dag & \addtoindex{Rust} \\
174 \DWLANGSwiftTARG{}~\dag & \addtoindex{Swift} \\
175 \DWLANGUPCTARG{} & UPC (Unified Parallel C) \addtoindexx{UPC}  
176                          \index{Unified Parallel C|see{UPC}} \\ 
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 \addtoindex{\texttt{auto} return type} specifier should use an unspecified 
1172 type entry (see 
1173 Section \refersec{chap:unspecifiedtypeentries}). 
1174 The debugging information entry for the corresponding definition
1175 should provide the deduced return type.  This practice causes the description of
1176 the containing class to be consistent across compilation units, allowing the class
1177 declaration to be placed into a separate type unit if desired.}
1178
1179
1180 \subsection{Subroutine and Entry Point Locations}
1181 \label{chap:subroutineandentrypointlocations}
1182
1183 A subroutine entry may have either a \DWATlowpc{} and
1184 \DWAThighpc{} pair of attributes or a \DWATranges{} attribute
1185 \addtoindexx{ranges attribute}
1186 whose 
1187 \addtoindexx{high PC attribute}
1188 values 
1189 \addtoindexx{low PC attribute}
1190 encode the contiguous or non\dash contiguous address
1191 ranges, respectively, of the machine instructions generated
1192 for the subroutine (see 
1193 Section \refersec{chap:codeaddressesandranges}).
1194
1195
1196 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}{}
1197 subroutine entry may also have 
1198 \addtoindexx{entry pc attribute!for subroutine}
1199
1200 \DWATentrypc{} attribute
1201 whose value is the address of the first executable instruction
1202 of the subroutine (see 
1203 Section \refersec{chap:entryaddress}).
1204
1205 An entry point has a \DWATlowpc{} attribute whose value is the
1206 relocated address of the first machine instruction generated
1207 for the entry point.
1208
1209 \textit{While the 
1210 \DWATentrypc{} attribute 
1211 \addtoindexx{entry pc attribute!for subroutine}
1212 might 
1213 also seem appropriate
1214 for this purpose, historically the 
1215 \DWATlowpc{} attribute
1216 was used before the 
1217 \DWATentrypc{} was introduced (in
1218 \addtoindex{DWARF Version 3}). 
1219 There is insufficient reason to change this.}
1220
1221
1222 Subroutines 
1223 and 
1224 entry
1225 \addtoindexx{address class!attribute}
1226 points 
1227 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}{}
1228 may also have 
1229 \DWATsegment{} 
1230 and
1231 \DWATaddressclass{} attributes,
1232 as appropriate, to specify
1233 which segments the code for the subroutine resides in and
1234 the addressing mode to be used in calling that subroutine.
1235
1236 A subroutine entry representing a subroutine declaration
1237 that is not also a definition does not have code address or
1238 range attributes.
1239
1240
1241 \subsection{Declarations Owned by Subroutines and Entry Points} 
1242 \label{chap:declarationsownedbysubroutinesandentrypoints}
1243
1244 The declarations enclosed by a subroutine or entry point are
1245 represented by debugging information entries that are owned
1246 by the subroutine or entry point entry. Entries representing
1247 \addtoindexx{formal parameter}
1248 the formal parameters of the subroutine or entry point appear
1249 in the same order as the corresponding declarations in the
1250 source program.
1251
1252 \needlines{5}
1253 \textit{There is no ordering requirement for entries for declarations
1254 that are children of subroutine or entry point entries but
1255 that do not represent formal parameters. The formal parameter
1256 entries may be interspersed with other entries used by formal
1257 parameter entries, such as type entries.}
1258
1259 The unspecified parameters of a variable parameter list are
1260 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
1261 with the tag
1262 \DWTAGunspecifiedparametersTARG.
1263
1264 \needlines{4}
1265 The entry for a subroutine that includes a
1266 \addtoindex{Fortran}
1267 \addtoindexx{Fortran!common block}
1268 \livelink{chap:fortrancommonblock}{common} 
1269 \livelink{chap:commonblockentry}{block}
1270 \addtoindexx{common block|see{Fortran common block}}
1271 has a child entry with the 
1272 tag \DWTAGcommoninclusionTARG. 
1273 The
1274 \hypertarget{chap:commonreferencecommonblockusage}{}
1275 common inclusion entry has a 
1276 \DWATcommonreference{} attribute
1277 whose value is a \livelink{chap:classreference}{reference} 
1278 to the debugging information entry
1279 for the common \nolink{block} being included 
1280 (see Section \refersec{chap:commonblockentries}).
1281
1282 \subsection{Low-Level Information}
1283 \label{chap:lowlevelinformation}
1284
1285
1286 \hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{}
1287 subroutine or entry point entry may have 
1288 \addtoindexx{return address attribute}
1289
1290 \DWATreturnaddr{}
1291 attribute, whose value is a location description. The location
1292 calculated is the place where the return address for the
1293 subroutine or entry point is stored.
1294
1295
1296 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}{}
1297 subroutine or entry point entry may also have 
1298 \addtoindexx{frame base attribute}
1299 a
1300 \DWATframebase{} attribute, whose value is a location
1301 description that computes the \doublequote{frame base} for the
1302 subroutine or entry point. If the location description is
1303 a simple register location description, the given register
1304 contains the frame base address. If the location description is
1305 a DWARF expression, the result of evaluating that expression
1306 is the frame base address. Finally, for a 
1307 \addtoindex{location list},
1308 this interpretation applies to each location description
1309 contained in the list of \addtoindex{location list} entries.
1310
1311 \textit{The use of one of the \DWOPregn{} 
1312 operations in this
1313 context is equivalent to using 
1314 \DWOPbregn(0) 
1315 but more
1316 compact. However, these are not equivalent in general.}
1317
1318 \needlines{5}
1319 \textit{The frame base for a procedure is typically an address fixed
1320 relative to the first unit of storage allocated for the
1321 procedure\textquoteright s stack frame. The \DWATframebase{} attribute
1322 can be used in several ways:}
1323 \begin{enumerate}[1. ]
1324 \item \textit{In procedures that need 
1325 \addtoindexx{location list}
1326 location lists to locate local
1327 variables, the \DWATframebase{} can hold the needed location
1328 list, while all variables\textquoteright\  location descriptions can be
1329 simpler ones involving the frame base.}
1330
1331 \item \textit{It can be used in resolving \doublequote{up\dash level} addressing
1332 within nested routines. 
1333 (See also \DWATstaticlink, below)}
1334 \end{enumerate}
1335
1336 \needlines{5}
1337 \textit{Some languages support nested subroutines. In such languages,
1338 it is possible to reference the local variables of an
1339 outer subroutine from within an inner subroutine. The
1340 \DWATstaticlink{} and \DWATframebase{} attributes allow
1341 debuggers to support this same kind of referencing.}
1342
1343 If 
1344 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}{}
1345
1346 \addtoindexx{address!uplevel|see {static link attribute}}
1347 \addtoindexx{uplevel address|see {static link attribute}}
1348 subroutine or entry point is nested, it may have a
1349 \DWATstaticlink{}
1350 attribute, whose value is a location
1351 description that computes the frame base of the relevant
1352 instance of the subroutine that immediately encloses the
1353 subroutine or entry point.
1354
1355 In the context of supporting nested subroutines, the
1356 \DWATframebase{} attribute value should obey the following
1357 constraints:
1358
1359 \begin{enumerate}[1. ]
1360 \item It should compute a value that does not change during the
1361 life of the procedure, and
1362
1363 \item The computed value should be unique among instances of
1364 the same subroutine. (For typical \DWATframebase{} use, this
1365 means that a recursive subroutine\textquoteright s stack frame must have
1366 non\dash zero size.)
1367 \end{enumerate}
1368
1369 \textit{If a debugger is attempting to resolve an up\dash level reference
1370 to a variable, it uses the nesting structure of DWARF to
1371 determine which subroutine is the lexical parent and the
1372 \DWATstaticlink{} value to identify the appropriate active
1373 frame of the parent. It can then attempt to find the reference
1374 within the context of the parent.}
1375
1376
1377 \needlines{8}
1378 \subsection{Types Thrown by Exceptions}
1379 \label{chap:typesthrownbyexceptions}
1380
1381 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1382 it may validly throw.}
1383
1384 If a subroutine explicitly declares that it may throw
1385 \addtoindexx{exception thrown|see{thrown type entry}}
1386 an 
1387 \addtoindexx{thrown exception|see{thrown type entry}}
1388 exception of one or more types, each such type is
1389 represented by a debugging information entry with 
1390 \addtoindexx{thrown type entry}
1391 the tag
1392 \DWTAGthrowntypeTARG.  
1393 Each such entry is a child of the entry
1394 representing the subroutine that may throw this type. Each
1395 thrown type entry contains 
1396 \addtoindexx{type attribute}
1397 a \DWATtype{} attribute, whose
1398 value is a \livelink{chap:classreference}{reference} 
1399 to an entry describing the type of the
1400 exception that may be thrown.
1401
1402 \subsection{Function Template Instantiations}
1403 \label{chap:functiontemplateinstantiations}
1404
1405 \textit{In \addtoindex{C++}, a function template is a generic definition of
1406 a function that is instantiated differently for calls with
1407 values of different types. DWARF does not represent the generic
1408 template definition, but does represent each instantiation.}
1409
1410 \needlines{4}
1411 A \addtoindex{template instantiation} is represented by a debugging
1412 information entry with the 
1413 \addtoindexx{subprogram entry!use for template instantiation}
1414 tag \DWTAGsubprogram. 
1415 With the following
1416 exceptions, such an entry will contain the same attributes and
1417 will have the same types of child entries as would an entry
1418 for a subroutine defined explicitly using the instantiation
1419 types and values. The exceptions are:
1420
1421 \begin{enumerate}[1. ]
1422 \item Template parameters are described and referenced as specified in
1423 Section \refersec{chap:templateparameters}.
1424
1425 \item If the compiler has generated a special compilation unit
1426 to hold the template instantiation and that compilation unit
1427 has a different name from the compilation unit containing
1428 the template definition, the name attribute for the debugging
1429 information entry representing that compilation unit is empty
1430 or omitted.
1431
1432 \item If the subprogram entry representing the template
1433 instantiation or any of its child entries contain declaration
1434 coordinate attributes, those attributes refer to the source
1435 for the template definition, not to any source generated
1436 artificially by the compiler for this instantiation.
1437 \end{enumerate}
1438
1439
1440 \needlines{8}
1441 \subsection{Inlinable and Inlined Subroutines}
1442 \label{chap:inlinedsubroutines}
1443 A declaration or a definition of an inlinable subroutine
1444 is represented by a debugging information entry with the
1445 tag 
1446 \DWTAGsubprogram.
1447 The entry for a 
1448 \addtoindexx{subprogram entry!use in inlined subprogram}
1449 subroutine that is
1450 \hypertarget{chap:DWATinlineinlinedsubroutine}{}
1451 explicitly declared to be available for inline expansion or
1452 that was expanded inline implicitly by the compiler has 
1453 \addtoindexx{inline attribute}
1454 a
1455 \DWATinline{} attribute whose value is an 
1456 \livelink{chap:classconstant}{integer constant}. The
1457 set of values for the \DWATinline{} attribute is given in
1458 Table \refersec{tab:inlinecodes}.
1459
1460 \begin{table}[here]
1461 \centering
1462 \caption{Inline codes}
1463 \label{tab:inlinecodes}
1464 \begin{tabular}{l|p{8cm}}
1465 \hline
1466 Name&Meaning\\ \hline
1467 \DWINLnotinlinedTARG{} & Not declared inline nor inlined by the
1468   \mbox{compiler} (equivalent to the absence of the
1469   containing \DWATinline{} attribute) \\
1470 \DWINLinlinedTARG{} & Not declared inline but inlined by the \mbox{compiler} \\
1471 \DWINLdeclarednotinlinedTARG{} & Declared inline but 
1472   not inlined by the \mbox{compiler} \\
1473 \DWINLdeclaredinlinedTARG{} & Declared inline and inlined by the 
1474   \mbox{compiler} \\
1475 \hline
1476 \end{tabular}
1477 \end{table}
1478
1479 \textit{In \addtoindex{C++}, a function or a constructor declared with
1480 \addttindex{constexpr} is implicitly declared inline. The abstract inline
1481 instance (see below) is represented by a debugging information
1482 entry with the tag \DWTAGsubprogram. Such an entry has a
1483 \DWATinline{} attribute whose value is \DWINLinlined.}
1484
1485
1486 \subsubsection{Abstract Instances}
1487 \label{chap:abstractinstances}
1488 Any debugging information entry that is owned (either
1489 \hypertarget{chap:DWATinlineabstracttinstance}{}
1490 directly or indirectly) by a debugging information entry
1491 that contains the 
1492 \DWATinline{} attribute is referred to
1493 \addtoindexx{abstract instance!entry}
1494 as an \doublequote{abstract instance entry.} 
1495 Any subroutine entry
1496 that contains 
1497 \addtoindexx{inline attribute}
1498 a \DWATinline{} attribute whose value is other
1499 than \DWINLnotinlined{}
1500 is known as 
1501 \addtoindexx{abstract instance!root}
1502 an \doublequote{abstract instance root.} 
1503 Any set of abstract instance entries that are all
1504 children (either directly or indirectly) of some abstract
1505 instance root, together with the root itself, is known as
1506 \addtoindexx{abstract instance!tree}
1507 an \doublequote{abstract instance tree.} However, in the case where
1508 an abstract instance tree is nested within another abstract
1509 instance tree, the entries in the 
1510 \addtoindex{nested abstract instance}
1511 tree are not considered to be entries in the outer abstract
1512 instance tree.
1513
1514 Each abstract instance root is either part of a larger
1515 \addtoindexx{abstract instance!root}
1516 tree (which gives a context for the root) or 
1517 \addtoindexx{specification attribute}
1518 uses
1519 \DWATspecification{} 
1520 to refer to the declaration in context.
1521
1522 \textit{For example, in \addtoindex{C++} the context might be a namespace
1523 declaration or a class declaration.}
1524
1525 \textit{Abstract instance trees are defined so that no entry is part
1526 of more than one abstract instance tree. This simplifies the
1527 following descriptions.}
1528
1529 A debugging information entry that is a member of an abstract
1530 instance tree should not contain any attributes which describe
1531 aspects of the subroutine which vary between distinct inlined
1532 expansions or distinct out\dash of\dash line expansions. For example,
1533 \addtoindexx{entry pc attribute!and abstract instance}
1534 the \DWATlowpc,
1535 \DWAThighpc, 
1536 \DWATranges, 
1537 \DWATentrypc, 
1538 \DWATlocation,
1539 \DWATreturnaddr, 
1540 \DWATstartscope, 
1541 and 
1542 \DWATsegment{}
1543 attributes 
1544 \addtoindexx{location attribute!and abstract instance}
1545 typically 
1546 \addtoindexx{ranges attribute!and abstract instance}
1547 should 
1548 \addtoindexx{high PC attribute!and abstract instance}
1549 be 
1550 \addtoindexx{low PC attribute!and abstract instance}
1551 omitted; 
1552 \addtoindexx{segment attribute!and abstract instance}
1553 however, 
1554 \addtoindexx{return address attribute!and abstract instance}
1555 this 
1556 \addtoindexx{segment attribute!and abstract instance}
1557 list
1558 \addtoindexx{start scope attribute!and abstract instance}
1559 is not exhaustive.
1560
1561 \needlines{5}
1562 \textit{It would not make sense normally to put these attributes into
1563 abstract instance entries since such entries do not represent
1564 actual (concrete) instances and thus do not actually exist at
1565 run\dash time.  However, 
1566 see Appendix \refersec{app:inlineouteronenormalinner} 
1567 for a contrary example.}
1568
1569 The rules for the relative location of entries belonging to
1570 abstract instance trees are exactly the same as for other
1571 similar types of entries that are not abstract. Specifically,
1572 the rule that requires that an entry representing a declaration
1573 be a direct child of the entry representing the scope of the
1574 declaration applies equally to both abstract and non\dash abstract
1575 entries. Also, the ordering rules for formal parameter entries,
1576 member entries, and so on, all apply regardless of whether
1577 or not a given entry is abstract.
1578
1579 \needlines{5}
1580 \subsubsection{Concrete Inlined Instances}
1581 \label{chap:concreteinlinedinstances}
1582
1583 Each inline expansion of a subroutine is represented
1584 by a debugging information entry with the 
1585 tag \DWTAGinlinedsubroutineTARG. 
1586 Each such entry should be a direct
1587 child of the entry that represents the scope within which
1588 the inlining occurs.
1589
1590 \needlines{4}
1591 Each inlined subroutine entry may have either a 
1592 \DWATlowpc{}
1593 and \DWAThighpc{} pair 
1594 of 
1595 \addtoindexx{high PC attribute}
1596 attributes 
1597 \addtoindexx{low PC attribute}
1598 or 
1599 \addtoindexx{ranges attribute}
1600
1601 \DWATranges{}
1602 attribute whose values encode the contiguous or non\dash contiguous
1603 address ranges, respectively, of the machine instructions
1604 generated for the inlined subroutine (see 
1605 Section \referfol{chap:codeaddressesandranges}). 
1606 An
1607 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}{}
1608 inlined subroutine entry may 
1609 \addtoindexx{inlined subprogram entry!in concrete instance}
1610 also 
1611 \addtoindexx{inlined subprogram entry}
1612 contain 
1613 \addtoindexx{entry pc attribute!for inlined subprogram}
1614
1615 \DWATentrypc{}
1616 attribute, representing the first executable instruction of
1617 the inline expansion (see 
1618 Section \refersec{chap:entryaddress}).
1619
1620 % Positions of the 3 targets here is a bit arbitrary.
1621 An inlined 
1622 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{}
1623 subroutine 
1624 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{}
1625 entry 
1626 \hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{}
1627 may also have \DWATcallfile,
1628 \DWATcallline{} and \DWATcallcolumn{} attributes, 
1629 each of whose
1630 value is an \livelink{chap:classconstant}{integer constant}. 
1631 These attributes represent the
1632 source file, source line number, and source column number,
1633 respectively, of the first character of the statement or
1634 expression that caused the inline expansion. The call file,
1635 call line, and call column attributes are interpreted in
1636 the same way as the declaration file, declaration line, and
1637 declaration column attributes, respectively (see 
1638 Section \refersec{chap:declarationcoordinates}).
1639
1640 \textit{The call file, call line and call column coordinates do not
1641 describe the coordinates of the subroutine declaration that
1642 was inlined, rather they describe the coordinates of the call.
1643 }
1644
1645 An inlined subroutine entry 
1646 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}{}
1647 may have a 
1648 \DWATconstexpr{}
1649 attribute, which is a \livelink{chap:classflag}{flag} 
1650 whose presence indicates that the
1651 subroutine has been evaluated as a compile\dash time constant. Such
1652 an entry may also have a \DWATconstvalue{} attribute,
1653 whose value may be of any form that is appropriate for the
1654 representation of the subroutine's return value. The value of
1655 this attribute is the actual return value of the subroutine,
1656 represented as it would be on the target architecture.
1657
1658 \textit{In \addtoindex{C++}, if a function or a constructor declared with 
1659 \addttindex{constexpr}
1660 is called with constant expressions, then the corresponding
1661 concrete inlined instance has a 
1662 \DWATconstexpr{} attribute,
1663 as well as a \DWATconstvalue{} attribute whose value represents
1664 the actual return value of the concrete inlined instance.}
1665
1666 Any debugging information entry that is owned (either
1667 directly or indirectly) by a debugging information entry
1668 with the tag \DWTAGinlinedsubroutine{} is referred to as a
1669 \doublequote{concrete inlined instance entry.} Any entry that has
1670 the tag 
1671 \DWTAGinlinedsubroutine{} 
1672 is known as a \doublequote{concrete inlined instance root.} 
1673 Any set of concrete inlined instance
1674 entries that are all children (either directly or indirectly)
1675 of some concrete inlined instance root, together with the root
1676 itself, is known as a \doublequote{concrete inlined instance tree.}
1677 However, in the case where a concrete inlined instance tree
1678 is nested within another concrete instance tree, the entries
1679 in the \addtoindex{nested concrete inline instance} tree 
1680 are not considered to
1681 be entries in the outer concrete instance tree.
1682
1683 \needlines{3}
1684 \textit{Concrete inlined instance trees are defined so that no entry
1685 is part of more than one concrete inlined instance tree. This
1686 simplifies later descriptions.}
1687
1688 Each concrete inlined instance tree is uniquely associated
1689 with one (and only one) abstract instance tree.
1690
1691 \textit{Note, however, that the reverse is not true. Any given abstract
1692 instance tree may be associated with several different concrete
1693 inlined instance trees, or may even be associated with zero
1694 concrete inlined instance trees.}
1695
1696 Concrete inlined instance entries may omit attributes that
1697 are not specific to the concrete instance (but present in
1698 the abstract instance) and need include only attributes that
1699 are specific to the concrete instance (but omitted in the
1700 abstract instance). In place of these omitted attributes, each
1701 \hypertarget{chap:DWATabstractorigininlineinstance}{}
1702 concrete inlined instance entry 
1703 \addtoindexx{abstract origin attribute}
1704 has a 
1705 \DWATabstractorigin{}
1706 attribute that may be used to obtain the missing information
1707 (indirectly) from the associated abstract instance entry. The
1708 value of the abstract origin attribute is a reference to the
1709 associated abstract instance entry.
1710
1711 If an entry within a concrete inlined instance tree contains
1712 attributes describing the 
1713 \addtoindexx{declaration coordinates!in concrete instance}
1714 \livelink{chap:declarationcoordinates}{declaration coordinates} 
1715 of that entry, then those attributes should refer to the file, line
1716 and column of the original declaration of the subroutine,
1717 not to the point at which it was inlined. As a consequence,
1718 they may usually be omitted from any entry that has an abstract
1719 origin attribute.
1720
1721 \needlines{4}
1722 For each pair of entries that are associated via a
1723 \addtoindexx{abstract origin attribute}
1724 \DWATabstractorigin{} attribute, both members of the pair
1725 have the same tag. So, for example, an entry with the tag
1726 \DWTAGvariable{} can only be associated with another entry
1727 that also has the tag \DWTAGvariable. The only exception
1728 to this rule is that the root of a concrete instance tree
1729 (which must always have the tag \DWTAGinlinedsubroutine)
1730 can only be associated with the root of its associated abstract
1731 instance tree (which must have the tag \DWTAGsubprogram).
1732
1733 \needlines{6}
1734 In general, the structure and content of any given concrete
1735 inlined instance tree will be closely analogous to the
1736 structure and content of its associated abstract instance
1737 tree. There are a few exceptions:
1738
1739 \begin{enumerate}[1. ]
1740 \item An entry in the concrete instance tree may be omitted if
1741 it contains only a 
1742 \addtoindexx{abstract origin attribute}
1743 \DWATabstractorigin{} attribute and either
1744 has no children, or its children are omitted. Such entries
1745 would provide no useful information. In C\dash like languages,
1746 such entries frequently include types, including structure,
1747 union, class, and interface types; and members of types. If any
1748 entry within a concrete inlined instance tree needs to refer
1749 to an entity declared within the scope of the relevant inlined
1750 subroutine and for which no concrete instance entry exists,
1751 the reference should refer to the abstract instance entry.
1752
1753 \needlines{4}
1754 \item Entries in the concrete instance tree which are associated
1755 with entries in the abstract instance tree such that neither
1756 has a \DWATname{} attribute,
1757 \addtoindexx{name attribute}
1758 and neither is referenced by
1759 any other debugging information entry, may be omitted. This
1760 may happen for debugging information entries in the abstract
1761 instance trees that became unnecessary in the concrete instance
1762 tree because of additional information available there. For
1763 example, an anonymous variable might have been created and
1764 described in the abstract instance tree, but because of
1765 the actual parameters for a particular inlined expansion,
1766 it could be described as a constant value without the need
1767 for that separate debugging information entry.
1768
1769 \item A concrete instance tree may contain entries which do
1770 not correspond to entries in the abstract instance tree
1771 to describe new entities that are specific to a particular
1772 inlined expansion. In that case, they will not have associated
1773 entries in the abstract instance tree, should not contain
1774 \addtoindexx{abstract origin attribute}
1775 \DWATabstractorigin{} attributes, and must contain all their
1776 own attributes directly. This allows an abstract instance tree
1777 to omit debugging information entries for anonymous entities
1778 that are unlikely to be needed in most inlined expansions. In
1779 any expansion which deviates from that expectation, the
1780 entries can be described in its concrete inlined instance tree.
1781
1782 \end{enumerate}
1783
1784 \subsubsection{Out-of-Line Instances of Inlined Subroutines}
1785 \label{chap:outoflineinstancesofinlinedsubroutines}
1786 Under some conditions, compilers may need to generate concrete
1787 executable instances of inlined subroutines other than at
1788 points where those subroutines are actually called. Such
1789 concrete instances of inlined subroutines are referred to as
1790 \doublequote{concrete out\dash of\dash line instances.}
1791
1792 \textit{In \addtoindex{C++}, for example, 
1793 taking the address of a function declared
1794 to be inline can necessitate the generation of a concrete
1795 out\dash of\dash line instance of the given function.}
1796
1797 The DWARF representation of a concrete out\dash of\dash line instance
1798 of an inlined subroutine is essentially the same as for a
1799 concrete inlined instance of that subroutine (as described in
1800 the preceding section). The representation of such a concrete
1801 % It is critical that the hypertarget and livelink be
1802 % separated to avoid problems with latex.
1803 out\dash of\dash line 
1804 \addtoindexx{abstract origin attribute}
1805 instance 
1806 \hypertarget{chap:DWATabstractoriginoutoflineinstance}{}
1807 makes use of 
1808 \DWATabstractorigin{}
1809 attributes in exactly the same way as they are used for
1810 a concrete inlined instance (that is, as references to
1811 corresponding entries within the associated abstract instance
1812 tree).
1813
1814 \needlines{5}
1815 The differences between the DWARF representation of a
1816 concrete out\dash of\dash line instance of a given subroutine and the
1817 representation of a concrete inlined instance of that same
1818 subroutine are as follows:
1819
1820 \begin{enumerate}[1. ]
1821 \item  The root entry for a concrete out\dash of\dash line instance
1822 of a given inlined subroutine has the same tag as does its
1823 associated (abstract) inlined subroutine entry (that is, tag
1824 \DWTAGsubprogram{} rather than \DWTAGinlinedsubroutine).
1825
1826 \item The root entry for a concrete out\dash of\dash line instance tree
1827 is normally owned by the same parent entry that also owns
1828 the root entry of the associated abstract instance. However,
1829 it is not required that the abstract and out\dash of\dash line instance
1830 trees be owned by the same parent entry.
1831
1832 \end{enumerate}
1833
1834 \subsubsection{Nested Inlined Subroutines}
1835 \label{nestedinlinedsubroutines}
1836 Some languages and compilers may permit the logical nesting of
1837 a subroutine within another subroutine, and may permit either
1838 the outer or the nested subroutine, or both, to be inlined.
1839
1840 For a non\dash inlined subroutine nested within an inlined
1841 subroutine, the nested subroutine is described normally in
1842 both the abstract and concrete inlined instance trees for
1843 the outer subroutine. All rules pertaining to the abstract
1844 and concrete instance trees for the outer subroutine apply
1845 also to the abstract and concrete instance entries for the
1846 nested subroutine.
1847
1848 \needlines{5}
1849 For an inlined subroutine nested within another inlined
1850 subroutine, the following rules apply to their abstract and
1851 \addtoindexx{abstract instance!nested}
1852 \addtoindexx{concrete instance!nested}
1853 concrete instance trees:
1854
1855 \begin{enumerate}[1. ]
1856 \item The abstract instance tree for the nested subroutine is
1857 described within the abstract instance tree for the outer
1858 subroutine according to the rules in 
1859 Section \refersec{chap:abstractinstances}, and
1860 without regard to the fact that it is within an outer abstract
1861 instance tree.
1862
1863 \item Any abstract instance tree for a nested subroutine is
1864 always omitted within the concrete instance tree for an
1865 outer subroutine.
1866
1867 \item  A concrete instance tree for a nested subroutine is
1868 always omitted within the abstract instance tree for an
1869 outer subroutine.
1870
1871 \item The concrete instance tree for any inlined or 
1872 \addtoindexx{out-of-line instance}
1873 out-of-line
1874 \addtoindexx{out-of-line-instance|see{concrete out-of-line-instance}}
1875 expansion of the nested subroutine is described within a
1876 concrete instance tree for the outer subroutine according
1877 to the rules in 
1878 Sections \refersec{chap:concreteinlinedinstances} or 
1879 \referfol{chap:outoflineinstancesofinlinedsubroutines}
1880 , respectively,
1881 and without regard to the fact that it is within an outer
1882 concrete instance tree.
1883 \end{enumerate}
1884
1885 See Appendix \refersec{app:inliningexamples} 
1886 for discussion and examples.
1887
1888 \subsection{Trampolines}
1889 \label{chap:trampolines}
1890
1891 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1892 \hypertarget{chap:DWATtrampolinetargetsubroutine}{}
1893 an intermediary in making a call to another subroutine. It may
1894 adjust parameters and/or the result (if any) as appropriate
1895 to the combined calling and called execution contexts.}
1896
1897 A trampoline is represented by a debugging information entry
1898 \addtoindexx{trampoline (subprogram) entry}
1899 with the tag \DWTAGsubprogram{} or \DWTAGinlinedsubroutine{}
1900 that has 
1901 \addtoindexx{trampoline attribute}
1902 a \DWATtrampoline{} attribute. 
1903 The value of that
1904 attribute indicates the target subroutine of the trampoline,
1905 that is, the subroutine to which the trampoline passes
1906 control. (A trampoline entry may but need not also have a
1907 \DWATartificial{} attribute.)
1908
1909 \needlines{5}
1910 The value of the trampoline attribute may be represented
1911 using any of the following forms, which are listed in order
1912 of preference:
1913
1914 \begin{itemize}
1915 \item If the value is of class reference, then the value
1916 specifies the debugging information entry of the target
1917 subprogram.
1918
1919 \item If the value is of class address, then the value is
1920 the relocated address of the target subprogram.
1921
1922 \item If the value is of class string, then the value is the
1923 (possibly mangled) \addtoindexx{mangled names}
1924 name of the target subprogram.
1925
1926 \item If the value is of class \livelink{chap:classflag}{flag}, then the value true
1927 indicates that the containing subroutine is a trampoline but
1928 that the target subroutine is not known.
1929 \end{itemize}
1930
1931
1932 The target subprogram may itself be a trampoline. (A sequence
1933 of trampolines necessarily ends with a non\dash trampoline
1934 subprogram.)
1935
1936 \textit{In \addtoindex{C++}, trampolines may be used 
1937 to implement derived virtual
1938 member functions; such trampolines typically adjust the
1939 \addtoindexx{this parameter}
1940 implicit this pointer parameter in the course of passing
1941 control.  
1942 Other languages and environments may use trampolines
1943 in a manner sometimes known as transfer functions or transfer
1944 vectors.}
1945
1946 \textit{Trampolines may sometimes pass control to the target
1947 subprogram using a branch or jump instruction instead of a
1948 call instruction, thereby leaving no trace of their existence
1949 in the subsequent execution context. }
1950
1951 \textit{This attribute helps make it feasible for a debugger to arrange
1952 that stepping into a trampoline or setting a breakpoint in
1953 a trampoline will result in stepping into or setting the
1954 breakpoint in the target subroutine instead. This helps to
1955 hide the compiler generated subprogram from the user. }
1956
1957 \textit{If the target subroutine is not known, a debugger may choose
1958 to repeatedly step until control arrives in a new subroutine
1959 which can be assumed to be the target subroutine. }
1960
1961 \subsection{Call Site Entries}
1962 \label{chap:callsiteentries}
1963 \textit{
1964 A call site entry provides a way to represent the static or dynamic 
1965 call graph of a program in the debugging information. It also provides
1966 information about how parameters are passed so that they may be more
1967 easily accessed by a debugger. Together with the \DWOPentryvalue{} opcode,
1968 call site entries can be also useful for computing values of variables 
1969 and expressions where some value is no longer present in the current 
1970 subroutine's registers or local stack frame, but it is known that the 
1971 values are equal to some parameter passed to the function.  
1972 The consumer can then use unwind
1973 information to find the caller and in the call site information sometimes
1974 find how to compute the value passed in a particular parameter.}
1975
1976 A call site is represented by a debugging information entry with the tag
1977 \DWTAGcallsiteTARG{}.  The entry for a call site is owned by the innermost
1978 debugging information entry representing the scope within which the
1979 call is present in the source program.
1980
1981 \textit{A scope entry (for example, for a lexical block) that would not 
1982 otherwise be present in the debugging information of a subroutine
1983 need not be introduced solely to represent the immediately containing scope
1984 of a call. The call site entry is owned by the innermost scope entry that
1985 is present.}
1986
1987 A source call can be compiled into different types of machine code:
1988 \begin{itemize}
1989 \item
1990 A \textit{normal call} uses a call-like instruction which transfers control to the start
1991 of some subprogram and leaves the call site location address somewhere where
1992 unwind information can find it.  
1993 \item
1994 A \textit{tail call} uses a jump-like instruction which
1995 transfers control to the start of some subprogram, but the call site location
1996 address is not preserved (and thus not available using the unwind information).  
1997 \item
1998 A \textit{tail recursion call} is a call
1999 to the current subroutine which is compiled as a loop into the middle of the
2000 current subroutine.
2001 \item
2002 An \textit{inline (or inlined) call} is a call to an inlined subprogram,
2003 where at least one instruction has the location of the inlined subprogram
2004 or any of its blocks or inlined subprograms. 
2005 \end{itemize}
2006
2007 \needlines{4}
2008 There are also different types of \doublequote{optimized out} calls:
2009 \begin{itemize}
2010 \item
2011 An \textit{optimized out (normal) call} is a call that is in unreachable code that 
2012 has not been emitted (such as, for example, the call to \texttt{foo} in 
2013 \texttt{if (0) foo();}).  
2014 \item
2015 An \textit{optimized out inline call}
2016 is a call to an inlined subprogram which either did not expand to any instructions
2017 or only parts of instructions belong to it and for debug information purposes those
2018 instructions are given a location in the caller.
2019 \end{itemize}
2020
2021 \DWTAGcallsite{} entries describe normal and tail calls but not tail recursion calls,
2022 while \DWTAGinlinedsubroutine{} entries describe inlined calls 
2023 (see Section \refersec{chap:inlinedsubroutines}).
2024
2025 The call site entry has a 
2026 \DWATcallreturnpcNAME{}
2027 \livetargi{chap:DWATcallreturnpcofcallsite}{attribute}{call return pc attribute} 
2028 which is the return address after the call.  
2029 The value of this attribute corresponds to the return address computed by 
2030 call frame information in the called subprogram 
2031 (see Section \refersec{datarep:callframeinformation}).
2032
2033 \textit{On many architectures the return address is the address immediately following the
2034 call instruction, but on architectures with delay slots it might
2035 be an address after the delay slot of the call.}
2036
2037 The call site entry may have a 
2038 \DWATcallpcNAME{}
2039 \livetargi{chap:DWATcallpcofcallsite}{attribute}{call pc attribute} which is the
2040 address of the call instruction.
2041
2042 If the call site entry corresponds to a tail call, it has the 
2043 \DWATcalltailcallNAME{}
2044 \livetargi{chap:DWATcalltailcallofcallsite}{attribute}{call tail call attribute},
2045 which is a \CLASSflag.
2046
2047 The call site entry may have a 
2048 \DWATcalloriginNAME{}
2049 \livetargi{chap:DWATcalloriginofcallsite}{attribute}{call origin attribute}
2050 which is a \CLASSreference.  For direct calls or jumps where the called subprogram is
2051 known it is a reference to the called subprogram's debugging
2052 information entry.  For indirect calls it may be a reference to a
2053 \DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
2054 the subroutine pointer that is called.
2055
2056 The call site may have a 
2057 \DWATcalltargetNAME{}
2058 \livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
2059 a DWARF expression.  For indirect calls or jumps where it is unknown at
2060 compile time which subprogram will be called the expression computes the
2061 address of the subprogram that will be called.  The DWARF expression should
2062 not use register or memory locations that might be clobbered by the call.
2063
2064 The call site entry may have a 
2065 \DWATcalltargetclobberedNAME{}
2066 \livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
2067 which is a DWARF expression.  For indirect calls or jumps where the
2068 address is not computable without use of registers or memory locations that
2069 might be clobbered by the call the \DWATcalltargetclobberedNAME{}
2070 attribute is used instead of the \DWATcalltarget{} attribute.
2071
2072 The call site entry may have a \DWATtypeNAME{}
2073 \livetargi{chap:DWATtypeofcallsite}{attribute}{type attribute!of call site entry}
2074 referencing a debugging information entry for the type of the called function.  
2075 When \DWATcallorigin{} is present, \DWATtypeNAME{} is usually omitted.
2076
2077 The call site entry may have 
2078 \DWATcallfileNAME{}, \DWATcalllineNAME{} and \DWATcallcolumnNAME{} 
2079 \livetargi{chap:DWATcallfileofcallsite}{attributes,}{call file attribute!of call site entry}
2080 \livetargi{chap:DWATcalllineofcallsite}{}{call line attribute!of call site entry}
2081 \livetargi{chap:DWATcallcolumnofcallsite}{}{call column attribute!of call site entry}
2082 each of whose value is an integer constant.
2083 These attributes represent the source file, source line number, and source
2084 column number, respectively, of the first character of the call statement or
2085 expression.  The call file, call line, and call column attributes are
2086 interpreted in the same way as the declaration file, declaration
2087 line, and declaration column attributes, respectively 
2088 (see Section \refersec{chap:declarationcoordinates}).
2089
2090 \textit{The call file, call line and call column coordinates do not describe the
2091 coordinates of the subroutine declaration that was inlined, rather they describe
2092 the coordinates of the call.}
2093
2094 The call site entry may own \DWTAGcallsiteparameterTARG{} debugging information
2095 entries\index{call site parameter entry} representing the parameters passed to the call.
2096 Each such entry has a \DWATlocation{} attribute which is a location expression.
2097 This location expression describes where the parameter is passed
2098 (usually either some register, or a memory location expressible as the
2099 contents of the stack register plus some offset).
2100
2101 Each \DWTAGcallsiteparameter{} entry may have a 
2102 \DWATcallvalueNAME{}
2103 \livetargi{chap:DWATcallvalueofcallparameter}{attribute}{call value attribute}
2104 which is a DWARF expression.  This expression computes the value
2105 passed for that parameter.  The expression should not use registers or memory
2106 locations that might be clobbered by the call, as it might be evaluated after
2107 unwinding from the called function back to the caller.  If it is not
2108 possible to avoid registers or memory locations that might be clobbered by
2109 the call in the expression, then the \DWATcallvalueNAME{} attribute should
2110 not be provided.
2111
2112 \textit{The reason for the restriction is that the value of the parameter may be
2113 needed in the middle of the callee, where the call clobbered registers or
2114 memory might be already clobbered, and if the consumer was not assured by
2115 the producer it can safely use those values, the consumer could not safely
2116 use the values at all.}
2117
2118 For parameters passed by reference, where the code passes a pointer to
2119 a location which contains the parameter, or for reference type parameters
2120 the \DWTAGcallsiteparameter{} entry may also have 
2121 \DWATcalldatalocationNAME{}
2122 \livetargi{chap:DWATcalldatalocationofcallparameter}{attribute}{call data location attribute}
2123 whose value is a location expression and a
2124 \DWATcalldatavalueNAME{}
2125 \livetargi{chap:DWATcalldatavalueofcallparameter}{attribute}{call data value attribute}
2126 whose value is a DWARF expression.  The \DWATcalldatalocationNAME{} attribute 
2127 describes where the referenced value lives during the call.  If it is just 
2128 \DWOPpushobjectaddress{}, it may be left out.  The 
2129 \DWATcalldatavalueNAME{} attribute describes the value in that location. 
2130 The expression should not use registers or memory
2131 locations that might be clobbered by the call, as it might be evaluated after
2132 unwinding from the called function back to the caller.
2133
2134 \needlines{4}
2135 Each call site parameter entry may also have a 
2136 \DWATcallparameter{}
2137 \livetargi{chap:DWATcallparameterofcallparameter}{attribute}{call parameter attribute}
2138 which contains a reference to a \DWTAGformalparameter{} entry,
2139 \DWATtype{} attribute referencing the type of the parameter or \DWATname{}
2140 attribute describing the parameter's name.
2141
2142
2143
2144 \section{Lexical Block Entries}
2145 \label{chap:lexicalblockentries}
2146
2147 \textit{A 
2148 lexical \livetargi{chap:lexicalblock}{block}{lexical block} 
2149 is 
2150 \addtoindexx{lexical block}
2151 a bracketed sequence of source statements
2152 that may contain any number of declarations. In some languages
2153 (including \addtoindex{C} and \addtoindex{C++}),
2154 \nolink{blocks} can be nested within other
2155 \nolink{blocks} to any depth.}
2156
2157 % We do not need to link to the preceding paragraph.
2158 A lexical \nolink{block} is represented by a debugging information
2159 entry with the 
2160 tag \DWTAGlexicalblockTARG.
2161
2162 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} 
2163 entry may have 
2164 either a \DWATlowpc{} and
2165 \DWAThighpc{} pair of 
2166 attributes 
2167 \addtoindexx{high PC attribute}
2168 or 
2169 \addtoindexx{low PC attribute}
2170
2171 \DWATranges{} attribute
2172 \addtoindexx{ranges attribute}
2173 whose values encode the contiguous or non-contiguous address
2174 ranges, respectively, of the machine instructions generated
2175 for the lexical \nolink{block} 
2176 (see Section \refersec{chap:codeaddressesandranges}).
2177
2178
2179 \hypertarget{chap:DWATentrypcoflexicalblock}{}
2180 lexical block entry may also have 
2181 \addtoindexx{entry pc attribute!for lexical block}
2182
2183 \DWATentrypc{} attribute
2184 whose value is the address of the first executable instruction
2185 of the lexical block (see 
2186 Section \refersec{chap:entryaddress}).
2187
2188 If a name has been given to the 
2189 lexical \nolink{block} 
2190 in the source
2191 program, then the corresponding 
2192 lexical \nolink{block} entry has a
2193 \DWATname{} attribute whose 
2194 \addtoindexx{name attribute}
2195 value is a null\dash terminated string
2196 containing the name of the lexical \nolink{block} 
2197 as it appears in
2198 the source program.
2199
2200 \textit{This is not the same as a \addtoindex{C} or 
2201 \addtoindex{C++} label (see below).}
2202
2203 The lexical \nolink{block} entry owns 
2204 debugging information entries that
2205 describe the declarations within that lexical \nolink{block}. 
2206 There is
2207 one such debugging information entry for each local declaration
2208 of an identifier or inner lexical \nolink{block}.
2209
2210 \needlines{10}
2211 \section{Label Entries}
2212 \label{chap:labelentries}
2213 \textit{A label is a way of identifying a source statement. A labeled
2214 statement is usually the target of one or more \doublequote{go to}
2215 statements.
2216 }
2217
2218 \needlines{4}
2219 A label is represented by a debugging information entry with
2220 \addtoindexx{label entry}
2221 the 
2222 tag \DWTAGlabelTARG. 
2223 The entry for a label should be owned by
2224 the debugging information entry representing the scope within
2225 which the name of the label could be legally referenced within
2226 the source program.
2227
2228 The label entry has a \DWATlowpc{} attribute whose value
2229 is the relocated address of the first machine instruction
2230 generated for the statement identified by the label in
2231 the source program.  The label entry also has a 
2232 \DWATname{} attribute 
2233 \addtoindexx{name attribute}
2234 whose value is a null-terminated string containing
2235 the name of the label as it appears in the source program.
2236
2237
2238 \section{With Statement Entries}
2239 \label{chap:withstatemententries}
2240
2241 \textit{Both \addtoindex{Pascal} and 
2242 \addtoindexx{Modula-2}
2243 Modula\dash 2 support the concept of a \doublequote{with}
2244 statement. The with statement specifies a sequence of
2245 executable statements within which the fields of a record
2246 variable may be referenced, unqualified by the name of the
2247 record variable.}
2248
2249 A with statement is represented by a
2250 \addtoindexi{debugging information entry}{with statement entry}
2251 with the tag \DWTAGwithstmtTARG.
2252
2253 A with statement entry may have either a 
2254 \DWATlowpc{} and
2255 \DWAThighpc{} pair of attributes 
2256 \addtoindexx{high PC attribute}
2257 or 
2258 \addtoindexx{low PC attribute}
2259 a \DWATranges{} attribute
2260 \addtoindexx{ranges attribute}
2261 whose values encode the contiguous or non\dash contiguous address
2262 ranges, respectively, of the machine instructions generated
2263 for the with statement 
2264 (see Section \refersec{chap:codeaddressesandranges}).
2265
2266
2267 \hypertarget{chap:DWATentrypcofwithstmt}{}
2268 with statement entry may also have 
2269 \addtoindexx{entry pc attribute!for with statement}
2270
2271 \DWATentrypc{} attribute
2272 whose value is the address of the first executable instruction
2273 of the with statement (see 
2274 Section \refersec{chap:entryaddress}).
2275
2276 \needlines{5}
2277 The with statement entry has 
2278 \addtoindexx{type attribute}
2279 a \DWATtype{} attribute, denoting
2280 the type of record whose fields may be referenced without full
2281 qualification within the body of the statement. It also has
2282 \addtoindexx{location attribute}
2283 a \DWATlocation{} attribute, describing how to find the base
2284 address of the record object referenced within the body of
2285 the with statement.
2286
2287 \needlines{6}
2288 \section{Try and Catch Block Entries}
2289 \label{chap:tryandcatchblockentries}
2290
2291 \textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be 
2292 designated as a \doublequote{catch \nolink{block}.} 
2293 A catch \livetargi{chap:catchblock}{block}{catch block} is an 
2294 exception handler that handles
2295 exceptions thrown by an immediately 
2296 preceding \doublequote{try \livelink{chap:tryblock}{block}.}
2297 A catch \livelink{chap:catchblock}{block} 
2298 designates the type of the exception that it
2299 can handle.}
2300
2301 A try \livetargi{chap:tryblock}{block}{try block} is represented 
2302 by a debugging information entry
2303 \addtoindexx{try block entry}
2304 with the tag \DWTAGtryblockTARG.  
2305 A catch \livelink{chap:catchblock}{block} is represented by
2306 a debugging information entry with 
2307 \addtoindexx{catch block entry}
2308 the tag \DWTAGcatchblockTARG.
2309
2310 % nolink as we have links just above and do not have a combo link for both
2311 Both try and catch \nolink{block} entries may have either a
2312 \DWATlowpc{} and 
2313 \DWAThighpc{} pair of attributes 
2314 \addtoindexx{high PC attribute}
2315 or 
2316 \addtoindexx{low PC attribute}
2317 a
2318 \DWATranges{} attribute 
2319 \addtoindexx{ranges attribute}
2320 whose values encode the contiguous
2321 or non\dash contiguous address ranges, respectively, of the
2322 machine instructions generated for the \livelink{chap:lexicalblock}{block}
2323 (see Section
2324 \refersec{chap:codeaddressesandranges}).
2325
2326
2327 \hypertarget{chap:DWATentrypcoftryblock}{}
2328 \hypertarget{chap:DWATentrypcofcatchblock}{}
2329 try or catch block entry may also have 
2330 \addtoindexx{entry pc attribute!for try block}
2331 \addtoindexx{entry pc attribute!for catch block}
2332
2333 \DWATentrypc{} attribute
2334 whose value is the address of the first executable instruction
2335 of the try or catch block (see 
2336 Section \refersec{chap:entryaddress}).
2337
2338 Catch \livelink{chap:catchblock}{block} entries have at 
2339 least one child entry, an
2340 entry representing the type of exception accepted by
2341 that catch \livelink{chap:catchblock}{block}. 
2342 This child entry has one of 
2343 \addtoindexx{formal parameter entry!in catch block}
2344 the 
2345 \addtoindexx{unspecified parameters entry!in catch block}
2346 tags
2347 \DWTAGformalparameter{} or
2348 \DWTAGunspecifiedparameters,
2349 and will have the same form as other parameter entries.
2350
2351 The siblings immediately following 
2352 a try \livelink{chap:tryblock}{block} entry are its
2353 corresponding catch \livelink{chap:catchblock}{block} entries.
2354