370357c2a5a688bd9be5fd9f9329be96aab42524
[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{centering}
137   \setlength{\extrarowheight}{0.1cm}
138 \begin{longtable}{l|l}
139   \caption{Language names} \label{tab:languagenames} \\
140   \hline \bfseries Language name & \bfseries Meaning \\ \hline
141 \endfirsthead
142   \bfseries Language name & \bfseries Meaning \\ \hline
143 \endhead
144   \hline \emph{Continued on next page}
145 \endfoot
146 \endlastfoot
147 \addtoindexx{ISO-defined language names}
148 \DWLANGAdaeightythreeTARG{} \dag & ISO Ada:1983 \addtoindexx{Ada:1983 (ISO)} \\
149 \DWLANGAdaninetyfiveTARG{}  \dag & ISO Ada:1995 \addtoindexx{Ada:1995 (ISO)} \\
150 \DWLANGCTARG & Non-standardized C, such as K\&R \addtoindexx{C!non-standard}\\
151 \DWLANGCeightynineTARG & ISO C:1989 \addtoindexx{C:1989 (ISO)} \\
152 \DWLANGCninetynineTARG & ISO C:1999 \addtoindexx{C:1999 (ISO)} \\
153 \DWLANGCelevenTARG     & ISO C:2011 \addtoindexx{C:2011 (ISO)} \\
154 \DWLANGCplusplusTARG          & ISO C++:1998 \addtoindexx{C++:1998 (ISO)} \\
155 \DWLANGCpluspluszerothreeTARG & ISO C++:2003 \addtoindexx{C++:2003 (ISO)} \\
156 \DWLANGCpluspluselevenTARG    & ISO C++:2011 \addtoindexx{C++:2011 (ISO)} \\
157 \DWLANGCplusplusfourteenTARG  & ISO C++:2014 \addtoindexx{C++:2014 (ISO)} \\
158 \DWLANGCobolseventyfourTARG & ISO COBOL:1974 \addtoindexx{COBOL:1974 (ISO)} \\
159 \DWLANGCoboleightyfiveTARG  & ISO COBOL:1985 \addtoindexx{COBOL:1985 (ISO)} \\
160 \DWLANGDTARG{}~\dag & D \addtoindexx{D language} \\
161 \DWLANGDylanTARG~\dag & Dylan \addtoindexx{Dylan} \\
162 \DWLANGFortranseventysevenTARG & ISO FORTRAN:1977 \addtoindexx{FORTRAN:1977 (ISO)} \\
163 \DWLANGFortranninetyTARG       & ISO Fortran:1990 \addtoindexx{Fortran:1990 (ISO)} \\
164 \DWLANGFortranninetyfiveTARG   & ISO Fortran:1995 \addtoindexx{Fortran:1995 (ISO)} \\
165 \DWLANGFortranzerothreeTARG    & ISO Fortran:2004 \addtoindexx{Fortran:2004 (ISO)} \\
166 \DWLANGFortranzeroeightTARG    & ISO Fortran:2010 \addtoindexx{Fortran:2010 (ISO)} \\
167 \DWLANGGoTARG{}~\dag & \addtoindex{Go} \\
168 \DWLANGHaskellTARG{} \dag & \addtoindex{Haskell} \\
169 \DWLANGJavaTARG{} & \addtoindex{Java}\\
170 \DWLANGJuliaTARG{}~\dag & \addtoindex{Julia} \\
171 \DWLANGModulatwoTARG   & ISO Modula\dash 2:1996 \addtoindexx{Modula-2:1996 (ISO)} \\
172 \DWLANGModulathreeTARG & \addtoindex{Modula-3} \\
173 \DWLANGObjCTARG{}         & \addtoindex{Objective C} \\
174 \DWLANGObjCplusplusTARG{} & \addtoindex{Objective C++} \\
175 \DWLANGOCamlTARG{}~\dag  & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}} \\
176 \DWLANGOpenCLTARG{}~\dag & \addtoindex{OpenCL} \\
177 \DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\
178 \DWLANGPLITARG{}~\dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
179 \DWLANGPythonTARG{}~\dag & \addtoindex{Python} \\
180 \DWLANGRustTARG{}~\dag & \addtoindex{Rust} \\
181 \DWLANGSwiftTARG{}~\dag & \addtoindex{Swift} \\
182 \DWLANGUPCTARG{} & UPC (Unified Parallel C) \addtoindexx{UPC}  
183                          \index{Unified Parallel C|see{UPC}} \\ 
184 \hline
185 \dag \ \ \textit{Support for these languages is limited}& \\
186 \end{longtable}
187 \end{centering}
188
189 \needlines{6}
190 \item A \DWATstmtlist{}
191 attribute whose value is 
192 \addtoindexx{statement list attribute}
193
194 \addtoindexx{section offset!in statement list attribute}
195 section
196 \hypertarget{chap:DWATstmtlistlinenumberinformationforunit}{}
197 offset to the line number information for this compilation
198 unit.
199
200 This information is placed in a separate object file
201 section from the debugging information entries themselves. The
202 value of the statement list attribute is the offset in the
203 \dotdebugline{} section of the first byte of the line number
204 information for this compilation unit 
205 (see Section \refersec{chap:linenumberinformation}).
206
207 \item A \DWATmacros{} attribute 
208 \addtoindexx{macro information attribute}
209 whose value is a 
210 \addtoindexx{section offset!in macro information attribute}
211 section
212 \hypertarget{chap:DWATmacrosmacroinformation}{}
213 offset to the macro information for this compilation unit.
214
215 This information is placed in a separate object file section
216 from the debugging information entries themselves. The
217 value of the macro information attribute is the offset in
218 the \dotdebugmacro{} section of the first byte of the macro
219 information for this compilation unit 
220 (see Section \refersec{chap:macroinformation}).
221
222 \textit{The \DWATmacros{} attribute is new in \DWARFVersionV, 
223 and supersedes the 
224 \DWATmacroinfo{} attribute of earlier DWARF versions.
225 \livetarg{chap:DWATmacroinfomacroinformation}{}
226 While \DWATmacros{} and \DWATmacroinfo{} attributes cannot both occur in the same
227 compilation unit, both may be found in the set of units that make up an executable
228 or shared object. The two attributes have distinct encodings to facilitate such
229 coexistence.}
230
231 \needlines{6}
232 \item  A 
233 \DWATcompdir{} 
234 attribute 
235 \hypertarget{chap:DWATcompdircompilationdirectory}{}
236 whose value is a
237 null\dash terminated string containing the current working directory
238 of the compilation command that produced this compilation
239 unit in whatever form makes sense for the host system.
240
241 \item  A \DWATproducer{} attribute 
242 \addtoindexx{producer attribute}
243 whose value is a null\dash
244 terminated string containing information about the compiler
245 \hypertarget{chap:DWATproducercompileridentification}{}
246 that produced the compilation unit. The actual contents of
247 the string will be specific to each producer, but should
248 begin with the name of the compiler vendor or some other
249 identifying character sequence that should avoid confusion
250 with other producer values.
251
252 \needlines{4}
253 \item  A \DWATidentifiercase{} 
254 attribute 
255 \addtoindexx{identifier case attribute}
256 whose integer
257 \hypertarget{chap:DWATidentifiercaseidentifiercaserule}{}
258 constant value is a code describing the treatment
259 of identifiers within this compilation unit. The
260 set of identifier case codes is given in
261 Table \refersec{tab:identifiercasecodes}.
262
263 \begin{simplenametable}{Identifier case codes}{tab:identifiercasecodes}
264 \DWIDcasesensitive{}      \\
265 \DWIDupcase{}             \\
266 \DWIDdowncase{}           \\
267 \DWIDcaseinsensitive{}    \\
268 \end{simplenametable}
269
270 \DWIDcasesensitiveTARG{} is the default for all compilation units
271 that do not have this attribute.  It indicates that names given
272 as the values of \DWATname{} attributes 
273 \addtoindexx{name attribute}
274 in debugging information
275 entries for the compilation unit reflect the names as they
276 appear in the source program. The debugger should be sensitive
277 to the case of identifier names when doing identifier lookups.
278
279 \needlines{4}
280 \DWIDupcaseTARG{} means that the 
281 producer of the debugging
282 information for this compilation unit converted all source
283 names to upper case. The values of the name attributes may not
284 reflect the names as they appear in the source program. The
285 debugger should convert all names to upper case when doing
286 lookups.
287
288 \DWIDdowncaseTARG{} means that 
289 the producer of the debugging
290 information for this compilation unit converted all source
291 names to lower case. The values of the name attributes may not
292 reflect the names as they appear in the source program. The
293 debugger should convert all names to lower case when doing
294 lookups.
295
296 \needlines{4}
297 \DWIDcaseinsensitiveTARG{} means that the values of the name
298 attributes reflect the names as they appear in the source
299 program but that a case insensitive lookup should be used to
300 access those names.
301
302 \needlines{5}
303 \item A \DWATbasetypes{} attribute whose value is a 
304 \livelink{chap:classreference}{reference}.
305
306 This 
307 \hypertarget{chap:DWATbasetypesprimitivedatatypesofcompilationunit}{}
308 attribute 
309 \addtoindexx{base types attribute}
310 points to a debugging information entry
311 representing another compilation unit.  It may be used
312 to specify the compilation unit containing the base type
313 entries used by entries in the current compilation unit
314 (see Section \refersec{chap:basetypeentries}).
315
316 \needlines{6}
317 This attribute provides a consumer a way to find the definition
318 of base types for a compilation unit that does not itself
319 contain such definitions. This allows a consumer, for example,
320 to interpret a type conversion to a base type 
321 % getting this link target at the right spot is tricky.
322 \hypertarget{chap:DWATuseUTF8compilationunitusesutf8strings}{}
323 correctly.
324
325 \item A \DWATuseUTFeight{} attribute,
326 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} 
327 which is a \livelink{chap:classflag}{flag} whose
328 presence indicates that all strings (such as the names of
329 declared entities in the source program, or filenames in the line number table) 
330 are represented using the UTF\dash 8 representation. 
331
332 \needlines{4}
333 \item A \DWATmainsubprogram{} attribute, which is a \livelink{chap:classflag}{flag}
334 \addtoindexx{main subprogram attribute}
335 whose presence indicates 
336 \hypertarget{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}{}
337 that the compilation unit contains a
338 subprogram that has been identified as the starting function
339 of the program. If more than one compilation unit contains
340 this \nolink{flag}, any one of them may contain the starting function.
341
342 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement}
343 which is used
344 to specify and provide a user\dash specified name for the main
345 subroutine of a program. 
346 \addtoindex{C} uses the name \doublequote{main} to identify
347 the main subprogram of a program. Some other languages provide
348 similar or other means to identify the main subprogram of
349 a program.}
350
351 \item A \DWATentrypc{} attribute whose value is the address of the first
352 \hypertarget{chap:DWATentrypcofcompileunit}{}
353 \hypertarget{chap:DWATentrypcofpartialunit}{}
354 \addtoindexx{entry pc attribute!for normal compilation unit}
355 \addtoindexx{entry pc attribute!for partial compilation unit}
356 executable instruction of the unit (see 
357 Section \refersec{chap:entryaddress}).
358
359 \item A \DWATstroffsetsbaseNAME\addtoindexx{string offset base attribute}
360 \hypertarget{chap:DWATstroffsetbaseforindirectstringtable}{} 
361 attribute, whose value is a reference. 
362 This attribute points to the first string
363 offset of the compilation unit's contribution to the
364 \dotdebugstroffsets{} (or \dotdebugstroffsetsdwo{}) section. 
365 Indirect string references
366 (using \DWFORMstrx) within the compilation unit are
367 interpreted as indices relative to this base.
368
369 \needlines{6}
370 \item A \DWATaddrbaseNAME\addtoindexx{address table base attribute}
371 \hypertarget{chap:DWATaddrbaseforaddresstable}{}
372 attribute, whose value is a reference.
373 This attribute points to the beginning of the compilation
374 unit's contribution to the \dotdebugaddr{} section.
375 Indirect references (using \DWFORMaddrx, \DWOPaddrx, 
376 \DWOPconstx, \DWLLEbaseaddressselectionentry{}, 
377 \DWLLEstartendentry, or \DWLLEstartlengthentry) within the compilation unit are
378 interpreted as indices relative to this base.
379
380 \needlines{5}
381 \item A \DWATrangesbaseNAME\addtoindexx{ranges table base attribute}
382 \hypertarget{chap:DWATrangesbaseforrangelists}{}
383 attribute, whose value is a reference.
384 This attribute points to the beginning of the compilation
385 unit's contribution to the \dotdebugranges{} section.
386 References to range lists (using \DWFORMsecoffset)
387 within the compilation unit are
388 interpreted as offsets relative to this base.
389
390
391 \end{enumerate}
392
393 The  base address of a compilation unit is defined as the
394 value of the \DWATlowpc{} attribute, if present; otherwise,
395 it is undefined. If the base address is undefined, then any
396 DWARF entry or structure defined in terms of the base address
397 of that compilation unit is not valid.
398
399 \subsection{Skeleton Compilation Unit Entries}
400 \label{chap:skeletoncompilationunitentries}
401 When generating a split DWARF object (see 
402 Section \refersec{datarep:splitdwarfobjects}), the
403 compilation unit in the \dotdebuginfo{} section is a "skeleton"
404 compilation unit, which contains only a subset of the
405 attributes of a full normal or partial compilation unit. In general, 
406 it contains those attributes that are necessary for the consumer
407 to locate the DWARF object where the full compilation unit
408 can be found, and for the consumer to interpret references to
409 addresses in the program. 
410
411 A skeleton compilation unit has no
412 children, and may have the following attributes:
413 \begin{enumerate}[1. ]
414
415 \item
416 Either a \DWATlowpc{} and \DWAThighpc{} pair of attributes
417 or a \DWATranges{} attribute (the same as for regular
418 compilation unit entries).
419
420 \item
421 A \DWATstmtlist{} attribute (the same as for regular
422 compilation unit entries).
423
424 \item
425 A \DWATcompdir{} attribute (the same as for regular
426 compilation unit entries).
427
428 \item
429 \livetarg{chap:DWATdwonameforunit}{}
430 A \DWATdwonameNAME{} attribute whose value is a
431 null-terminated string containing the full or relative
432 path name of the DWARF object file that contains the full
433 compilation unit.
434
435 \item
436 \livetarg{chap:DWATdwoidforunit}{}
437 A \DWATdwoidNAME{} attribute whose value is an 8-byte
438 unsigned hash of the full compilation unit.  This hash
439 value is computed by the method described in 
440 Section \refersec{datarep:typesignaturecomputation}.
441
442 \needlines{6}
443 \item
444 A \DWATuseUTFeight{} attribute (the same as for regular compilation unit
445 entries).
446
447 \textit{This attribute applies to strings referred to by the skeleton
448 compilation unit entry itself, and strings in the associated line
449 number information.
450 The representation for strings in the DWARF object file is determined
451 by the presence of a \DWATuseUTFeight{} attribute in the full compilation
452 unit.}
453
454 \item
455 A \DWATstroffsetsbase{} attribute, for indirect strings references 
456 from the skeleton compilation unit (the same as for regular 
457 compilation unit entries).
458
459 \item
460 A \DWATaddrbase{} attribute (the same as for regular
461 compilation unit entries).
462
463 \item
464 A \DWATrangesbase{} attribute (the same as for regular
465 compilation unit entries).
466
467 \end{enumerate}
468
469 All other attributes of a compilation unit entry (described
470 in Section \refersec{chap:normalandpartialcompilationunitentries}) 
471 should be placed in the full compilation
472 unit entry in the \dotdebuginfodwo{} section of the split DWARF
473 object. The attributes provided by the skeleton compilation
474 unit entry do not need to be repeated in the full compilation
475 unit entry, except for \DWATdwoid, which should appear in
476 both entries so that the consumer can verify that it has
477 found the correct DWARF object.
478
479
480 \subsection{Imported Unit Entries}
481 \label{chap:importedunitentries}
482 The 
483 \hypertarget{chap:DWATimportimportedunit}{}
484 place where a normal or partial unit is imported is
485 represented by a debugging information entry with the 
486 \addtoindexx{imported unit entry}
487 tag \DWTAGimportedunitTARG. 
488 An imported unit entry contains 
489 \addtoindexx{import attribute}
490 a
491 \DWATimport{} attribute 
492 whose value is a \livelink{chap:classreference}{reference} to the
493 normal or partial compilation unit whose declarations logically
494 belong at the place of the imported unit entry.
495
496 \textit{An imported unit entry does not necessarily correspond to
497 any entity or construct in the source program. It is merely
498 \doublequote{glue} used to relate a partial unit, or a compilation
499 unit used as a partial unit, to a place in some other
500 compilation unit.}
501
502 \needlines{6}
503 \subsection{Separate Type Unit Entries}
504 \label{chap:separatetypeunitentries}
505 An object file may contain any number of separate type
506 unit entries, each representing a single complete type
507 definition. 
508 Each \addtoindex{type unit} must be uniquely identified by
509 a 64\dash bit signature, stored as part of the type unit, which
510 can be used to reference the type definition from debugging
511 information entries in other compilation units and type units.
512
513 A type unit is represented by a debugging information entry
514 with the tag \DWTAGtypeunitTARG. 
515 A \addtoindex{type unit entry} owns debugging
516 information entries that represent the definition of a single
517 type, plus additional debugging information entries that may
518 be necessary to include as part of the definition of the type.
519
520 A type unit entry may have a 
521 \DWATlanguage{} attribute, 
522 whose
523 \addtoindexx{language attribute}
524 constant value is an integer code indicating the source
525 language used to define the type. The set of language names
526 and their meanings are given in Table \refersec{tab:languagenames}.
527
528 A type unit entry may have a 
529 \DWATstroffsetsbase\addtoindexx{string base offset attribute}
530 attribute, whose value is a reference. This attribute points
531 to the first string offset of the type unit's contribution to
532 the \dotdebugstroffsets{} section. Indirect string references
533 (using \DWFORMstrx) within the type unit must be interpreted
534 as indices relative to this base.
535
536 A type unit entry may have a \DWATstmtlist{} attribute, whose
537 value is a section offset to a line number table for this
538 type unit. Because type units do not describe any code, they
539 do not actually need a line number table, but the line number
540 tables also contain a list of directories and file names that
541 may be referenced by the \DWATdeclfile{} attribute. In a
542 normal object file with a regular compilation unit entry, the
543 type unit entries can simply refer to the line number table
544 used by the compilation unit. In a split DWARF object, where
545 the type units are located in a separate DWARF object file,
546 the \DWATstmtlist{} attribute refers to a "skeleton"
547 line number table in the \dotdebuglinedwo{} section, which
548 contains only the list of directories and file names. All
549 type unit entries in a split DWARF object may (but are not
550 required to) refer to the same skeleton line number table.
551
552 A type unit entry may have a \DWATuseUTFeight{} attribute, which is a flag
553 whose presence indicates that all strings referred to by this type
554 unit entry, its children, and the skeleton line number table, are
555 represented using the UTF-8 representation.
556
557 \needlines{4}
558 A \addtoindex{type unit} entry for a given type T owns a debugging
559 information entry that represents a defining declaration
560 of type T. If the type is nested within enclosing types or
561 namespaces, the debugging information entry for T is nested
562 within debugging information entries describing its containers;
563 otherwise, T is a direct child of the type unit entry.
564
565 A type unit entry may also own additional debugging information
566 entries that represent declarations of additional types that
567 are referenced by type T and have not themselves been placed in
568 separate type units. Like T, if an additional type U is nested
569 within enclosing types or namespaces, the debugging information
570 entry for U is nested within entries describing its containers;
571 otherwise, U is a direct child of the type unit entry.
572
573 The containing entries for types T and U are declarations,
574 and the outermost containing entry for any given type T or
575 U is a direct child of the type unit entry. The containing
576 entries may be shared among the additional types and between
577 T and the additional types.
578
579 \textit{Types are not required to be placed in type units. In general,
580 only large types such as structure, class, enumeration, and
581 union types included from header files should be considered
582 for separate type units. Base types and other small types
583 are not usually worth the overhead of placement in separate
584 type units. Types that are unlikely to be replicated, such
585 as those defined in the main source file, are also better
586 left in the main compilation unit.}
587
588 \section{Module, Namespace and Importing Entries}
589 \textit{Modules and namespaces provide a means to collect related
590 entities into a single entity and to manage the names of
591 those entities.}
592
593 \subsection{Module Entries}
594 \label{chap:moduleentries}
595 \textit{Several languages have the concept of a \doublequote{module.}
596 \addtoindexx{Modula-2}
597 A Modula\dash 2 definition module 
598 \addtoindexx{Modula-2!definition module}
599 may be represented by a module
600 entry containing a 
601 \addtoindex{declaration attribute}
602 (\DWATdeclaration). A
603 \addtoindex{Fortran 90} module 
604 \addtoindexx{Fortran!module (Fortran 90)}
605 may also be represented by a module entry
606 (but no declaration attribute is warranted because \addtoindex{Fortran}
607 has no concept of a corresponding module body).}
608
609 A module is represented by a debugging information entry
610 with the 
611 tag \DWTAGmoduleTARG.  
612 Module entries may own other
613 debugging information entries describing program entities
614 whose declaration scopes end at the end of the module itself.
615
616 If the module has a name, the module entry has a 
617 \DWATname{} attribute 
618 \addtoindexx{name attribute}
619 whose value is a null\dash terminated string containing
620 the module name as it appears in the source program.
621
622 The \addtoindex{module entry} may have either a 
623 \DWATlowpc{} and
624 \DWAThighpc{} 
625 pair 
626 \addtoindexx{high PC attribute}
627 of 
628 \addtoindexx{low PC attribute}
629 attributes or a 
630 \DWATranges{} attribute
631 \addtoindexx{ranges attribute}
632 whose values encode the contiguous or non\dash contiguous address
633 ranges, respectively, of the machine instructions generated for
634 the module initialization code 
635 (see Section \refersec{chap:codeaddressesandranges}). 
636 \hypertarget{chap:DWATentrypcentryaddressofmoduleinitialization}{}
637 It may also
638 \addtoindexx{entry pc attribute!for module initialization}
639 have a 
640 \DWATentrypc{} attribute whose value is the address of
641 the first executable instruction of that initialization code
642 (see Section \refersec{chap:entryaddress}).
643
644 If 
645 \hypertarget{chap:DWATprioritymodulepriority}{}
646 the module has been assigned a priority, it may have 
647 \addtoindexx{priority attribute}
648 a
649 \DWATpriority{} attribute. 
650 The value of this attribute is a
651 reference to another debugging information entry describing
652 a variable with a constant value. The value of this variable
653 is the actual constant value of the module\textquoteright s priority,
654 represented as it would be on the target architecture.
655
656 \subsection{Namespace Entries}
657 \label{chap:namespaceentries}
658 \textit{\addtoindex{C++} has the notion of a namespace, which provides a way to
659 \addtoindexx{namespace (C++)}
660 implement name hiding, so that names of unrelated things
661 do not accidentally clash in the 
662 \addtoindex{global namespace} when an
663 application is linked together.}
664
665 A namespace is represented by a debugging information entry
666 with the 
667 tag \DWTAGnamespaceTARG. 
668 A namespace extension is
669 \hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{}
670 represented by a 
671 \DWTAGnamespace{} entry 
672 with 
673 \addtoindexx{extension attribute}
674
675 \DWATextension{}
676 attribute referring to the previous extension, or if there
677 is no previous extension, to the original 
678 \DWTAGnamespace{}
679 entry. A namespace extension entry does not need to duplicate
680 information in a previous extension entry of the namespace
681 nor need it duplicate information in the original namespace
682 entry. (Thus, for a namespace with a name, 
683 a \DWATname{} attribute 
684 \addtoindexx{name attribute}
685 need only be attached directly to the original
686 \DWTAGnamespace{} entry.)
687
688 \needlines{4}
689 Namespace and namespace extension entries may own 
690 \addtoindexx{namespace extension entry}
691 other
692 \addtoindexx{namespace declaration entry}
693 debugging information entries describing program entities
694 whose declarations occur in the namespace.
695
696 \textit{For \addtoindex{C++}, such 
697 owned program entities may be declarations,
698 including certain declarations that are also object or
699 function definitions.}
700
701 A namespace may have a \DWATexportsymbolsNAME{} attribute
702 \livetarg{chap:DWATexportsymbolsofnamespace}{}
703 \addtoindexx{export symbols attribute}
704 \addtoindexx{inline namespace|see{\textit{also} export symbols attribute}}
705 which indicates that all member names defined within the 
706 namespace may be referenced as if they were defined within 
707 the containing namespace. 
708
709 \textit{This may be used to describe an \addtoindex{inline namespace} in \addtoindex{C++}}.
710
711 If a type, variable, or function declared in a namespace is
712 defined outside of the body of the namespace declaration,
713 that type, variable, or function definition entry has a
714 \DWATspecification{} attribute 
715 \addtoindexx{specification attribute}
716 whose value is a \livelink{chap:classreference}{reference} to the
717 debugging information entry representing the declaration of
718 the type, variable or function. Type, variable, or function
719 entries with a 
720 \DWATspecification{} attribute 
721 \addtoindexx{specification attribute}
722 do not need
723 to duplicate information provided by the declaration entry
724 referenced by the specification attribute.
725
726 \textit{The \addtoindex{C++} \addtoindex{global namespace}
727 (the 
728 \addtoindexx{global namespace|see{namespace (C++), global}}
729 namespace 
730 \addtoindexx{namespace (C++)!global}
731 referred to by
732 \texttt{::f}, for example) is not explicitly represented in
733 DWARF with a namespace entry (thus mirroring the situation
734 in \addtoindex{C++} source).  
735 Global items may be simply declared with no
736 reference to a namespace.}
737
738 \textit{The \addtoindex{C++} 
739 compilation unit specific \doublequote{unnamed namespace} may
740 \addtoindexx{namespace (C++)!unnamed}
741 \addtoindexx{unnamed namespace|see {namespace (C++), unnamed}}
742 be represented by a namespace entry with no name attribute in
743 the original namespace declaration entry (and therefore no name
744 attribute in any namespace extension entry of this namespace).
745 }
746
747 \textit{A compiler emitting namespace information may choose to
748 explicitly represent namespace extensions, or to represent the
749 final namespace declaration of a compilation unit; this is a
750 quality\dash of\dash implementation issue and no specific requirements
751 are given here. If only the final namespace is represented,
752 \addtoindexx{namespace (C++)!using declaration}
753 it is impossible for a debugger to interpret using declaration
754 references in exactly the manner defined by the 
755 \addtoindex{C++} language.
756 }
757
758 \textit{Emitting all namespace declaration information in all
759 compilation units can result in a significant increase in the
760 size of the debug information and significant duplication of
761 information across compilation units. 
762 The \addtoindex{C++} namespace std,
763 for example, 
764 \addtoindexx{namespace (C++)!std}
765 is large and will probably be referenced in
766 every \addtoindex{C++} compilation unit.
767 }
768
769 \textit{For \addtoindex{C++} namespace examples, 
770 see Appendix \refersec{app:namespaceexamples}.
771 }
772
773
774 \needlines{5}
775 \subsection{Imported (or Renamed) Declaration Entries} 
776 \label{chap:importedorrenameddeclarationentries}
777 \textit{Some languages support the concept of importing into or making
778 accessible in a given unit declarations made in a different
779 module or scope. An imported declaration may sometimes be
780 given another name.
781 }
782
783 An 
784 imported declaration is represented by one or
785 \addtoindexx{imported declaration entry}
786 more debugging information entries with the 
787 tag \DWTAGimporteddeclarationTARG. 
788 When 
789 \hypertarget{chap:DWATimportimporteddeclaration}{}
790 an overloaded entity
791 is imported, there is one imported declaration entry for
792 each overloading. 
793 \addtoindexx{import attribute}
794 Each imported declaration entry has a
795 \DWATimport{} attribute,
796 whose value is a \livelink{chap:classreference}{reference} to the
797 debugging information entry representing the declaration that
798 is being imported.
799
800 An imported declaration may also have a 
801 \DWATname{}
802 attribute
803 \addtoindexx{name attribute}
804 whose value is a null\dash terminated string containing the
805 name, as it appears in the source program, by which the
806 imported entity is to be known in the context of the imported
807 declaration entry (which may be different than the name of
808 the entity being imported). If no name is present, then the
809 name by which the entity is to be known is the same as the
810 name of the entity being imported.
811
812 An imported declaration entry with a name attribute may be
813 used as a general means to rename or provide an alias for
814 \addtoindexx{alias declaration|see{imported declaration entry}}
815 an entity, regardless of the context in which the importing
816 declaration or the imported entity occurs.
817
818 \textit{A \addtoindex{C++} namespace alias may be represented by an imported
819 \hypertarget{chap:DWATimportnamespacealias}{}
820 declaration entry 
821 \addtoindexx{namespace (C++)!alias}
822 with a name attribute whose value is
823 a null\dash terminated string containing the alias name as it
824 appears in the source program and an import attribute whose
825 value is a \livelink{chap:classreference}{reference} to the applicable original namespace or
826 namespace extension entry.
827 }
828
829 \textit{A \addtoindex{C++} using declaration may be represented by one or more
830 \hypertarget{chap:DWATimportnamespaceusingdeclaration}{}
831 imported 
832 \addtoindexx{namespace (C++)!using declaration}
833 declaration entries.  When the using declaration
834 refers to an overloaded function, there is one imported
835 declaration entry corresponding to each overloading. Each
836 imported declaration entry has no name attribute but it does
837 have an import attribute that refers to the entry for the
838 entity being imported. (\addtoindex{C++} 
839 provides no means to \doublequote{rename}
840 an imported entity, other than a namespace).
841 }
842
843 \textit{A \addtoindex{Fortran} use statement 
844 \addtoindexx{Fortran!use statement}
845 \addtoindexx{use statement|see {Fortran, use statement}}
846 with an \doublequote{only list} may be
847 represented by a series of imported declaration entries,
848 one (or more) for each entity that is imported. An entity
849 \addtoindexx{renamed declaration|see{imported declaration entry}}
850 that is renamed in the importing context may be represented
851 by an imported declaration entry with a name attribute that
852 specifies the new local name.
853 }
854
855 \subsection{Imported Module Entries}
856 \label{chap:importedmoduleentries}
857
858 \textit{Some languages support the concept of importing into or making
859 accessible in a given unit all of the declarations contained
860 within a separate module or namespace.
861 }
862
863 An imported module declaration is represented by a debugging
864 information entry with 
865 \addtoindexx{imported module attribute}
866 the 
867 \addtoindexx{imported module entry}
868 tag \DWTAGimportedmoduleTARG.
869 An
870 imported module entry contains a 
871 \DWATimport{} attribute
872 \addtoindexx{import attribute}
873 whose value is a \livelink{chap:classreference}{reference} 
874 to the module or namespace entry
875 containing the definition and/or declaration entries for
876 the entities that are to be imported into the context of the
877 imported module entry.
878
879 An imported module declaration may own a set of imported
880 declaration entries, each of which refers to an entry in the
881 module whose corresponding entity is to be known in the context
882 of the imported module declaration by a name other than its
883 name in that module. Any entity in the module that is not
884 renamed in this way is known in the context of the imported
885 module entry by the same name as it is declared in the module.
886
887 \textit{A \addtoindex{C++} using directive
888 \addtoindexx{namespace (C++)!using directive}
889 \addtoindexx{using directive|see {namespace (C++), using directive}} 
890 may be represented by an imported module
891 \hypertarget{chap:DWATimportnamespaceusingdirective}{}
892 entry, with an import attribute referring to the namespace
893 entry of the appropriate extension of the namespace (which
894 might be the original namespace entry) and no owned entries.
895 }
896
897 \textit{A \addtoindex{Fortran} use statement 
898 \addtoindexx{Fortran!use statement}
899 with a \doublequote{rename list} may be
900 represented by an imported module entry with an import
901 attribute referring to the module and owned entries
902 corresponding to those entities that are renamed as part of
903 being imported.
904 }
905
906 \textit{A \addtoindex{Fortran} use statement
907 \addtoindexx{Fortran!use statement}
908 with neither a \doublequote{rename list} nor
909 an \doublequote{only list} may be represented by an imported module
910 entry with an import attribute referring to the module and
911 no owned child entries.
912 }
913
914 \textit{A use statement with an \doublequote{only list} is represented by a
915 series of individual imported declaration entries as described
916 in Section \refersec{chap:importedorrenameddeclarationentries}.
917 }
918
919 \textit{A \addtoindex{Fortran} use statement for an entity in a module that is
920 \addtoindexx{Fortran!use statement}
921 itself imported by a use statement without an explicit mention
922 may be represented by an imported declaration entry that refers
923 to the original debugging information entry. For example, given
924 }
925
926 \begin{lstlisting}
927 module A
928 integer X, Y, Z
929 end module
930
931 module B
932 use A
933 end module
934
935 module C
936 use B, only Q => X
937 end module
938 \end{lstlisting}
939
940 \textit{the imported declaration entry for Q within module C refers
941 directly to the variable declaration entry for X in module A
942 because there is no explicit representation for X in module B.
943 }
944
945 \textit{A similar situation arises for a \addtoindex{C++} using declaration
946 \addtoindexx{namespace (C++)!using declaration}
947 \addtoindexx{using declaration|see {namespace (C++), using declaration}}
948 that imports an entity in terms of a namespace alias. See 
949 Appendix  \refersec{app:namespaceexamples}
950 for an example.
951 }
952
953 \section{Subroutine and Entry Point Entries}
954 \label{chap:subroutineandentrypointentries}
955
956 The following tags exist to describe 
957 debugging information entries 
958 \addtoindexx{function entry|see{subroutine entry}}
959 for 
960 \addtoindexx{subroutine entry}
961 subroutines 
962 \addtoindexx{subprogram entry}
963 and entry
964 % FIXME: is entry point entry the right index 'entry'?
965 \addtoindexx{entry point entry}
966 points:
967
968 \begin{tabular}{lp{9.0cm}}
969 \DWTAGsubprogramTARG{} & A subroutine or function \\
970 \DWTAGinlinedsubroutine{} & A particular inlined 
971 \addtoindexx{inlined subprogram entry}
972 instance of a subroutine or function \\
973 \DWTAGentrypointTARG{} & An alternate entry point \\
974 \end{tabular}
975
976
977 \needlines{6}
978 \subsection{General Subroutine and Entry Point Information}
979 \label{chap:generalsubroutineandentrypointinformation}
980 The subroutine or entry point entry has a \DWATname{} 
981 attribute whose value is a null-terminated string containing the 
982 subroutine or entry point name as it appears in the source program.
983 It may also have a \DWATlinkagename{} attribute as
984 described in Section \refersec{chap:linkagenames}.
985
986 If the name of the subroutine described by an entry with the
987 \addtoindexx{subprogram entry}
988 tag \DWTAGsubprogram{}
989 is visible outside of its containing
990 \hypertarget{chap:DWATexternalexternalsubroutine}{}
991 compilation unit, that entry has 
992 \addtoindexx{external attribute}
993
994 \DWATexternalNAME{} attribute,
995 which is a \livelink{chap:classflag}{flag}.
996
997 \textit{Additional attributes for functions that are members of a
998 class or structure are described in 
999 Section \refersec{chap:memberfunctionentries}.
1000 }
1001
1002
1003 \hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}{}
1004 subroutine entry 
1005 may contain a 
1006 \DWATmainsubprogramNAME{}
1007 attribute 
1008 \addtoindexx{main subprogram attribute}
1009 which is 
1010 a \CLASSflag whose presence indicates that the
1011 subroutine has been identified as the starting function of
1012 the program.  If more than one subprogram contains this 
1013 \nolink{flag},
1014 any one of them may be the starting subroutine of the program.
1015
1016 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement} 
1017 which is used to specify
1018 and provide a user\dash supplied name for the main subroutine of
1019 a program.
1020 }
1021
1022 \textit{A common debugger feature is to allow the debugger user to call
1023 a subroutine within the subject program. In certain cases,
1024 however, the generated code for a subroutine will not obey
1025 the standard calling conventions for the target architecture
1026 and will therefore not be safe to call from within a debugger.
1027 }
1028
1029 A subroutine entry may 
1030 \hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}{}
1031 contain a 
1032 \DWATcallingconventionNAME{}
1033 attribute, whose value is an 
1034 \livelink{chap:classconstant}{integer constant}. The set of
1035 calling convention codes is given in 
1036 Table \refersec{tab:callingconventioncodes}.
1037
1038 \begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
1039 \DWCCnormal        \\
1040 \DWCCprogram       \\
1041 \DWCCnocall        \\
1042 \end{simplenametable}
1043
1044 If this attribute is not present, or its value is the constant
1045 \DWCCnormalTARG, then the subroutine may be safely called by
1046 obeying the \doublequote{standard} calling conventions of the target
1047 architecture. If the value of the calling convention attribute
1048 is the constant \DWCCnocallTARG, the subroutine does not obey
1049 standard calling conventions, and it may not be safe for the
1050 debugger to call this subroutine.
1051
1052 If the semantics of the language of the compilation unit
1053 containing the subroutine entry distinguishes between ordinary
1054 subroutines and subroutines that can serve as the \doublequote{main
1055 program,} that is, subroutines that cannot be called
1056 directly according to the ordinary calling conventions,
1057 then the debugging information entry for such a subroutine
1058 may have a calling convention attribute whose value is the
1059 constant \DWCCprogramTARG.
1060
1061 \textit{The \DWCCprogram{} 
1062 value is intended to support \addtoindex{Fortran} main
1063 \addtoindexx{Fortran!main program}
1064 programs which in some implementations may not be callable
1065 or which must be invoked in a special way. It is not intended
1066 as a way of finding the entry address for the program.
1067 }
1068
1069 \textit{In \addtoindex{C}
1070 there is a difference between the types of functions
1071 declared using function prototype style declarations and
1072 those declared using non\dash prototype declarations.
1073 }
1074
1075 A subroutine entry declared with a function prototype style
1076 declaration may have 
1077 \addtoindexx{prototyped attribute}
1078
1079 \DWATprototypedNAME{} attribute, which is
1080 a \CLASSflag.
1081
1082 \textit{The \addtoindex{Fortran} 
1083 language allows the keywords \texttt{elemental}, \texttt{pure}
1084 and \texttt{recursive} to be included as part of the declaration of
1085 a subroutine; these attributes reflect that usage. These
1086 attributes are not relevant for languages that do not support
1087 similar keywords or syntax. In particular, the \DWATrecursiveNAME{}
1088 attribute is neither needed nor appropriate in languages such
1089 as \addtoindex{C} 
1090 where functions support recursion by default.
1091 }
1092
1093 A subprogram entry 
1094 \hypertarget{chap:DWATelementalelementalpropertyofasubroutine}{}
1095 may have 
1096 \addtoindexx{elemental attribute}
1097
1098 \DWATelementalNAME{} attribute, which
1099 is a \livelink{chap:classflag}{flag}. 
1100 The attribute indicates whether the subroutine
1101 or entry point was declared with the \doublequote{elemental} keyword
1102 or property.
1103
1104
1105 \hypertarget{chap:DWATpurepurepropertyofasubroutine}{}
1106 subprogram entry may have 
1107 \addtoindexx{pure attribute}
1108
1109 \DWATpureNAME{} attribute, which is
1110 a \livelink{chap:classflag}{flag}. 
1111 The attribute indicates whether the subroutine was
1112 declared with the \doublequote{pure} keyword or property.
1113
1114
1115 \hypertarget{chap:DWATrecursiverecursivepropertyofasubroutine}{}
1116 subprogram entry may have a 
1117 \DWATrecursiveNAME{} attribute, which
1118 is a \livelink{chap:classflag}{flag}. 
1119 The attribute indicates whether the subroutine
1120 or entry point was declared with the \doublequote{recursive} keyword
1121 or property.
1122
1123 A subprogram entry may have a 
1124 \DWATnoreturnNAME
1125 \livetargi{chap:DWATnoreturnofsubprogram}{ attribute}{noreturn attribute}, 
1126 which is a \CLASSflag. The attribute 
1127 indicates whether the subprogram was declared with the \doublequote{noreturn} keyword or property 
1128 indicating that the subprogram can be called, but will never return to its caller.
1129
1130 \subsubsection{Call Site-Related Attributes}
1131 A subroutine entry may have \DWATcallalltailcalls, \DWATcallallcalls{} 
1132 and/or \DWATcallallsourcecalls{} attributes, each of which is a 
1133 \livelink{chap:classflag}{flag}.
1134 These flags indicate the completeness of the call site information 
1135 within the subprogram.
1136
1137 The \DWATcallalltailcallsNAME{}
1138 \livetargi{chap:DWATcallalltailcallsofasubprogram}{attribute}{all tail calls summary attribute} 
1139 indicates that every tail call 
1140 that occurs in the code for the subprogram is described by a 
1141 \DWTAGcallsite{} entry. 
1142 (There may or may not be other non-tail calls to some of the same 
1143 target subprograms.)
1144
1145 The \DWATcallallcallsNAME{}
1146 \livetargi{chap:DWATcallallcallsofasubprogram}{attribute}{all calls summary attribute} 
1147 indicates that every non-inlined call
1148 (either a tail call or a normal call) that occurs in the code for the subprogram
1149 is described by a \DWTAGcallsite{} entry.
1150
1151 The \DWATcallallsourcecallsNAME{}
1152 \livetargi{chap:DWATcallallsourcecallsofasubprogram}{attribute}{all source calls summary attribute} 
1153 indicates that every call that occurs in the
1154 code for the subprogram, including every call inlined into it, is described by either a 
1155 \DWTAGcallsite{} entry or a \DWTAGinlinedsubroutine{} entry; further, any call
1156 that is optimized out is nonetheless also described using a \DWTAGcallsite{} entry 
1157 that has neither a \DWATcallpc{} nor \DWATcallreturnpc{} attribute.
1158
1159 \textit{The \DWATcallallsourcecallsNAME{} attribute is intended for debugging 
1160 information format consumers that analyse call graphs.}
1161
1162 If the value of the \DWATcallallsourcecalls{} attribute is true then the values of the
1163 \DWATcallallcalls{} and \DWATcallallcalls{} attributes are necessarily also true, and 
1164 those attributes need not be present. Similarly, if the value of the 
1165 \DWATcallallcalls{} attribute is true then the value of the \DWATcallalltailcalls{} 
1166 attribute is also true and the latter attribute need not be present.
1167
1168 \needlines{5}
1169 \subsection{Subroutine and Entry Point Return Types}
1170 \label{chap:subroutineandentrypointreturntypes}
1171
1172 If 
1173 \hypertarget{chap:DWATtypetypeofsubroutinereturn}{}
1174 the subroutine or entry point 
1175 \addtoindexx{return type of subroutine}
1176 is a function that returns a
1177 value, then its debugging information entry has 
1178 \addtoindexx{type attribute}
1179 a \DWATtype{} attribute 
1180 to denote the type returned by that function.
1181
1182 \textit{Debugging information entries for 
1183 \addtoindex{C} void functions should
1184 not have an attribute for the return type.  }
1185
1186 \textit{Debugging information entries for declarations of \addtoindex{C++} 
1187 member functions with an 
1188 \autoreturntype{} specifier should use an unspecified type entry (see 
1189 Section \refersec{chap:unspecifiedtypeentries}). 
1190 The debugging information entry for the corresponding definition
1191 should provide the deduced return type.  This practice causes the description of
1192 the containing class to be consistent across compilation units, allowing the class
1193 declaration to be placed into a separate type unit if desired.}
1194
1195
1196 \subsection{Subroutine and Entry Point Locations}
1197 \label{chap:subroutineandentrypointlocations}
1198
1199 A subroutine entry may have either a \DWATlowpc{} and
1200 \DWAThighpc{} pair of attributes or a \DWATranges{} attribute
1201 \addtoindexx{ranges attribute}
1202 whose 
1203 \addtoindexx{high PC attribute}
1204 values 
1205 \addtoindexx{low PC attribute}
1206 encode the contiguous or non\dash contiguous address
1207 ranges, respectively, of the machine instructions generated
1208 for the subroutine (see 
1209 Section \refersec{chap:codeaddressesandranges}).
1210
1211
1212 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}{}
1213 subroutine entry may also have 
1214 \addtoindexx{entry pc attribute!for subroutine}
1215
1216 \DWATentrypc{} attribute
1217 whose value is the address of the first executable instruction
1218 of the subroutine (see 
1219 Section \refersec{chap:entryaddress}).
1220
1221 An entry point has a \DWATlowpc{} attribute whose value is the
1222 relocated address of the first machine instruction generated
1223 for the entry point.
1224
1225 \textit{While the 
1226 \DWATentrypc{} attribute 
1227 \addtoindexx{entry pc attribute!for subroutine}
1228 might 
1229 also seem appropriate
1230 for this purpose, historically the 
1231 \DWATlowpc{} attribute
1232 was used before the 
1233 \DWATentrypc{} was introduced (in
1234 \addtoindex{DWARF Version 3}). 
1235 There is insufficient reason to change this.}
1236
1237
1238 Subroutines 
1239 and 
1240 entry
1241 \addtoindexx{address class attribute}
1242 points 
1243 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}{}
1244 may also have 
1245 \DWATsegment{} 
1246 and
1247 \DWATaddressclass{} attributes,
1248 as appropriate, to specify
1249 which segments the code for the subroutine resides in and
1250 the addressing mode to be used in calling that subroutine.
1251
1252 A subroutine entry representing a subroutine declaration
1253 that is not also a definition does not have code address or
1254 range attributes.
1255
1256
1257 \subsection{Declarations Owned by Subroutines and Entry Points} 
1258 \label{chap:declarationsownedbysubroutinesandentrypoints}
1259
1260 The declarations enclosed by a subroutine or entry point are
1261 represented by debugging information entries that are owned
1262 by the subroutine or entry point entry. Entries representing
1263 \addtoindexx{formal parameter}
1264 the formal parameters of the subroutine or entry point appear
1265 in the same order as the corresponding declarations in the
1266 source program.
1267
1268 \needlines{5}
1269 \textit{There is no ordering requirement for entries for declarations
1270 that are children of subroutine or entry point entries but
1271 that do not represent formal parameters. The formal parameter
1272 entries may be interspersed with other entries used by formal
1273 parameter entries, such as type entries.}
1274
1275 The unspecified parameters of a variable parameter list are
1276 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
1277 with the tag
1278 \DWTAGunspecifiedparametersTARG.
1279
1280 \needlines{4}
1281 The entry for a subroutine that includes a
1282 \addtoindex{Fortran}
1283 \addtoindexx{Fortran!common block}
1284 \livelink{chap:fortrancommonblock}{common} 
1285 \livelink{chap:commonblockentry}{block}
1286 \addtoindexx{common block|see{Fortran common block}}
1287 has a child entry with the 
1288 tag \DWTAGcommoninclusionTARG. 
1289 The
1290 \hypertarget{chap:commonreferencecommonblockusage}{}
1291 common inclusion entry has a 
1292 \DWATcommonreference{} attribute
1293 whose value is a \livelink{chap:classreference}{reference} 
1294 to the debugging information entry
1295 for the common \nolink{block} being included 
1296 (see Section \refersec{chap:commonblockentries}).
1297
1298 \subsection{Low-Level Information}
1299 \label{chap:lowlevelinformation}
1300
1301
1302 \hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{}
1303 subroutine or entry point entry may have 
1304 \addtoindexx{return address attribute}
1305
1306 \DWATreturnaddr{}
1307 attribute, whose value is a location description. The location
1308 calculated is the place where the return address for the
1309 subroutine or entry point is stored.
1310
1311
1312 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}{}
1313 subroutine or entry point entry may also have 
1314 \addtoindexx{frame base attribute}
1315 a
1316 \DWATframebase{} attribute, whose value is a location
1317 description that computes the \doublequote{frame base} for the
1318 subroutine or entry point. If the location description is
1319 a simple register location description, the given register
1320 contains the frame base address. If the location description is
1321 a DWARF expression, the result of evaluating that expression
1322 is the frame base address. Finally, for a 
1323 \addtoindex{location list},
1324 this interpretation applies to each location description
1325 contained in the list of \addtoindex{location list} entries.
1326
1327 \textit{The use of one of the \DWOPregn{} 
1328 operations in this
1329 context is equivalent to using 
1330 \DWOPbregn(0) 
1331 but more
1332 compact. However, these are not equivalent in general.}
1333
1334 \needlines{5}
1335 \textit{The frame base for a subprogram is typically an address fixed
1336 relative to the first unit of storage allocated for the
1337 subprogram\textquoteright s stack frame. The \DWATframebase{} attribute
1338 can be used in several ways:}
1339 \begin{enumerate}[1. ]
1340 \item \textit{In subprograms that need 
1341 \addtoindexx{location list}
1342 location lists to locate local
1343 variables, the \DWATframebase{} can hold the needed location
1344 list, while all variables\textquoteright\  location descriptions can be
1345 simpler ones involving the frame base.}
1346
1347 \item \textit{It can be used in resolving \doublequote{up\dash level} addressing
1348 within nested routines. 
1349 (See also \DWATstaticlink, below)}
1350 \end{enumerate}
1351
1352 \needlines{5}
1353 \textit{Some languages support nested subroutines. In such languages,
1354 it is possible to reference the local variables of an
1355 outer subroutine from within an inner subroutine. The
1356 \DWATstaticlink{} and \DWATframebase{} attributes allow
1357 debuggers to support this same kind of referencing.}
1358
1359 If 
1360 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}{}
1361
1362 \addtoindexx{address!uplevel|see {static link attribute}}
1363 \addtoindexx{uplevel address|see {static link attribute}}
1364 subroutine or entry point is nested, it may have a
1365 \DWATstaticlink{}
1366 attribute, whose value is a location
1367 description that computes the frame base of the relevant
1368 instance of the subroutine that immediately encloses the
1369 subroutine or entry point.
1370
1371 In the context of supporting nested subroutines, the
1372 \DWATframebase{} attribute value should obey the following
1373 constraints:
1374
1375 \begin{enumerate}[1. ]
1376 \item It should compute a value that does not change during the
1377 life of the subprogram, and
1378
1379 \item The computed value should be unique among instances of
1380 the same subroutine. (For typical \DWATframebase{} use, this
1381 means that a recursive subroutine\textquoteright s stack frame must have
1382 non\dash zero size.)
1383 \end{enumerate}
1384
1385 \textit{If a debugger is attempting to resolve an up\dash level reference
1386 to a variable, it uses the nesting structure of DWARF to
1387 determine which subroutine is the lexical parent and the
1388 \DWATstaticlink{} value to identify the appropriate active
1389 frame of the parent. It can then attempt to find the reference
1390 within the context of the parent.}
1391
1392
1393 \needlines{8}
1394 \subsection{Types Thrown by Exceptions}
1395 \label{chap:typesthrownbyexceptions}
1396
1397 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1398 it may validly throw.}
1399
1400 If a subroutine explicitly declares that it may throw
1401 \addtoindexx{exception thrown|see{thrown type entry}}
1402 an 
1403 \addtoindexx{thrown exception|see{thrown type entry}}
1404 exception of one or more types, each such type is
1405 represented by a debugging information entry with 
1406 \addtoindexx{thrown type entry}
1407 the tag
1408 \DWTAGthrowntypeTARG.  
1409 Each such entry is a child of the entry
1410 representing the subroutine that may throw this type. Each
1411 thrown type entry contains 
1412 \addtoindexx{type attribute}
1413 a \DWATtype{} attribute, whose
1414 value is a \livelink{chap:classreference}{reference} 
1415 to an entry describing the type of the
1416 exception that may be thrown.
1417
1418 \subsection{Function Template Instantiations}
1419 \label{chap:functiontemplateinstantiations}
1420
1421 \textit{In \addtoindex{C++}, a function template is a generic definition of
1422 a function that is instantiated differently for calls with
1423 values of different types. DWARF does not represent the generic
1424 template definition, but does represent each instantiation.}
1425
1426 \needlines{4}
1427 A \addtoindex{template instantiation} is represented by a debugging
1428 information entry with the 
1429 \addtoindexx{subprogram entry!use for template instantiation}
1430 tag \DWTAGsubprogram. 
1431 With the following
1432 exceptions, such an entry will contain the same attributes and
1433 will have the same types of child entries as would an entry
1434 for a subroutine defined explicitly using the instantiation
1435 types and values. The exceptions are:
1436
1437 \begin{enumerate}[1. ]
1438 \item Template parameters are described and referenced as specified in
1439 Section \refersec{chap:templateparameters}.
1440
1441 \needlines{4}
1442 \item If the compiler has generated a special compilation unit
1443 to hold the template instantiation and that compilation unit
1444 has a different name from the compilation unit containing
1445 the template definition, the name attribute for the debugging
1446 information entry representing that compilation unit is empty
1447 or omitted.
1448
1449 \item If the subprogram entry representing the template
1450 instantiation or any of its child entries contain declaration
1451 coordinate attributes, those attributes refer to the source
1452 for the template definition, not to any source generated
1453 artificially by the compiler for this instantiation.
1454 \end{enumerate}
1455
1456
1457 \needlines{8}
1458 \subsection{Inlinable and Inlined Subroutines}
1459 \label{chap:inlinedsubroutines}
1460 A declaration or a definition of an inlinable subroutine
1461 is represented by a debugging information entry with the
1462 tag 
1463 \DWTAGsubprogram.
1464 The entry for a 
1465 \addtoindexx{subprogram entry!use in inlined subprogram}
1466 subroutine that is
1467 \hypertarget{chap:DWATinlineinlinedsubroutine}{}
1468 explicitly declared to be available for inline expansion or
1469 that was expanded inline implicitly by the compiler has 
1470 \addtoindexx{inline attribute}
1471 a
1472 \DWATinline{} attribute whose value is an 
1473 \livelink{chap:classconstant}{integer constant}. The
1474 set of values for the \DWATinline{} attribute is given in
1475 Table \refersec{tab:inlinecodes}.
1476
1477 \begin{table}[here]
1478 \centering
1479 \caption{Inline codes}
1480 \label{tab:inlinecodes}
1481 \begin{tabular}{l|p{8cm}}
1482 \hline
1483 Name&Meaning\\ \hline
1484 \DWINLnotinlinedTARG{} & Not declared inline nor inlined by the
1485   \mbox{compiler} (equivalent to the absence of the
1486   containing \DWATinline{} attribute) \\
1487 \DWINLinlinedTARG{} & Not declared inline but inlined by the \mbox{compiler} \\
1488 \DWINLdeclarednotinlinedTARG{} & Declared inline but 
1489   not inlined by the \mbox{compiler} \\
1490 \DWINLdeclaredinlinedTARG{} & Declared inline and inlined by the 
1491   \mbox{compiler} \\
1492 \hline
1493 \end{tabular}
1494 \end{table}
1495
1496 \textit{In \addtoindex{C++}, a function or a constructor declared with
1497 \addttindex{constexpr} is implicitly declared inline. The abstract inline
1498 instance (see below) is represented by a debugging information
1499 entry with the tag \DWTAGsubprogram. Such an entry has a
1500 \DWATinline{} attribute whose value is \DWINLinlined.}
1501
1502 \needlines{4}
1503 \subsubsection{Abstract Instances}
1504 \label{chap:abstractinstances}
1505 Any debugging information entry that is owned (either
1506 \hypertarget{chap:DWATinlineabstracttinstance}{}
1507 directly or indirectly) by a debugging information entry
1508 that contains the 
1509 \DWATinline{} attribute is referred to
1510 \addtoindexx{abstract instance!entry}
1511 as an \doublequote{abstract instance entry.} 
1512 Any subroutine entry
1513 that contains 
1514 \addtoindexx{inline attribute}
1515 a \DWATinline{} attribute whose value is other
1516 than \DWINLnotinlined{}
1517 is known as 
1518 \addtoindexx{abstract instance!root}
1519 an \doublequote{abstract instance root.} 
1520 Any set of abstract instance entries that are all
1521 children (either directly or indirectly) of some abstract
1522 instance root, together with the root itself, is known as
1523 \addtoindexx{abstract instance!tree}
1524 an \doublequote{abstract instance tree.} However, in the case where
1525 an abstract instance tree is nested within another abstract
1526 instance tree, the entries in the 
1527 \addtoindex{nested abstract instance}
1528 tree are not considered to be entries in the outer abstract
1529 instance tree.
1530
1531 Each abstract instance root is either part of a larger
1532 \addtoindexx{abstract instance!root}
1533 tree (which gives a context for the root) or 
1534 \addtoindexx{specification attribute}
1535 uses
1536 \DWATspecification{} 
1537 to refer to the declaration in context.
1538
1539 \textit{For example, in \addtoindex{C++} the context might be a namespace
1540 declaration or a class declaration.}
1541
1542 \textit{Abstract instance trees are defined so that no entry is part
1543 of more than one abstract instance tree. This simplifies the
1544 following descriptions.}
1545
1546 A debugging information entry that is a member of an abstract
1547 instance tree should not contain any attributes which describe
1548 aspects of the subroutine which vary between distinct inlined
1549 expansions or distinct out\dash of\dash line expansions. For example,
1550 \addtoindexx{entry pc attribute!and abstract instance}
1551 the \DWATlowpc,
1552 \DWAThighpc, 
1553 \DWATranges, 
1554 \DWATentrypc, 
1555 \DWATlocation,
1556 \DWATreturnaddr, 
1557 \DWATstartscope, 
1558 and 
1559 \DWATsegment{}
1560 attributes 
1561 \addtoindexx{location attribute!and abstract instance}
1562 typically 
1563 \addtoindexx{ranges attribute!and abstract instance}
1564 should 
1565 \addtoindexx{high PC attribute!and abstract instance}
1566 be 
1567 \addtoindexx{low PC attribute!and abstract instance}
1568 omitted; 
1569 \addtoindexx{segment attribute!and abstract instance}
1570 however, 
1571 \addtoindexx{return address attribute!and abstract instance}
1572 this 
1573 \addtoindexx{segment attribute!and abstract instance}
1574 list
1575 \addtoindexx{start scope attribute!and abstract instance}
1576 is not exhaustive.
1577
1578 \needlines{5}
1579 \textit{It would not make sense normally to put these attributes into
1580 abstract instance entries since such entries do not represent
1581 actual (concrete) instances and thus do not actually exist at
1582 run\dash time.  However, 
1583 see Appendix \refersec{app:inlineouteronenormalinner} 
1584 for a contrary example.}
1585
1586 The rules for the relative location of entries belonging to
1587 abstract instance trees are exactly the same as for other
1588 similar types of entries that are not abstract. Specifically,
1589 the rule that requires that an entry representing a declaration
1590 be a direct child of the entry representing the scope of the
1591 declaration applies equally to both abstract and non\dash abstract
1592 entries. Also, the ordering rules for formal parameter entries,
1593 member entries, and so on, all apply regardless of whether
1594 or not a given entry is abstract.
1595
1596 \needlines{5}
1597 \subsubsection{Concrete Inlined Instances}
1598 \label{chap:concreteinlinedinstances}
1599
1600 Each inline expansion of a subroutine is represented
1601 by a debugging information entry with the 
1602 tag \DWTAGinlinedsubroutineTARG. 
1603 Each such entry should be a direct
1604 child of the entry that represents the scope within which
1605 the inlining occurs.
1606
1607 \needlines{4}
1608 Each inlined subroutine entry may have either a 
1609 \DWATlowpc{}
1610 and \DWAThighpc{} pair 
1611 of 
1612 \addtoindexx{high PC attribute}
1613 attributes 
1614 \addtoindexx{low PC attribute}
1615 or 
1616 \addtoindexx{ranges attribute}
1617
1618 \DWATranges{}
1619 attribute whose values encode the contiguous or non\dash contiguous
1620 address ranges, respectively, of the machine instructions
1621 generated for the inlined subroutine (see 
1622 Section \referfol{chap:codeaddressesandranges}). 
1623 An
1624 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}{}
1625 inlined subroutine entry may 
1626 \addtoindexx{inlined subprogram entry!in concrete instance}
1627 also 
1628 \addtoindexx{inlined subprogram entry}
1629 contain 
1630 \addtoindexx{entry pc attribute!for inlined subprogram}
1631
1632 \DWATentrypc{}
1633 attribute, representing the first executable instruction of
1634 the inline expansion (see 
1635 Section \refersec{chap:entryaddress}).
1636
1637 % Positions of the 3 targets here is a bit arbitrary.
1638 An inlined 
1639 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{}
1640 subroutine 
1641 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{}
1642 entry 
1643 \hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{}
1644 may also have \DWATcallfile,
1645 \DWATcallline{} and \DWATcallcolumn{} attributes, 
1646 each of whose
1647 value is an \livelink{chap:classconstant}{integer constant}. 
1648 These attributes represent the
1649 source file, source line number, and source column number,
1650 respectively, of the first character of the statement or
1651 expression that caused the inline expansion. The call file,
1652 call line, and call column attributes are interpreted in
1653 the same way as the declaration file, declaration line, and
1654 declaration column attributes, respectively (see 
1655 Section \refersec{chap:declarationcoordinates}).
1656
1657 \textit{The call file, call line and call column coordinates do not
1658 describe the coordinates of the subroutine declaration that
1659 was inlined, rather they describe the coordinates of the call.
1660 }
1661
1662 An inlined subroutine entry 
1663 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}{}
1664 may have a 
1665 \DWATconstexpr{}
1666 attribute, which is a \livelink{chap:classflag}{flag} 
1667 whose presence indicates that the
1668 subroutine has been evaluated as a compile\dash time constant. Such
1669 an entry may also have a \DWATconstvalue{} attribute,
1670 whose value may be of any form that is appropriate for the
1671 representation of the subroutine's return value. The value of
1672 this attribute is the actual return value of the subroutine,
1673 represented as it would be on the target architecture.
1674
1675 \textit{In \addtoindex{C++}, if a function or a constructor declared with 
1676 \addttindex{constexpr}
1677 is called with constant expressions, then the corresponding
1678 concrete inlined instance has a 
1679 \DWATconstexpr{} attribute,
1680 as well as a \DWATconstvalue{} attribute whose value represents
1681 the actual return value of the concrete inlined instance.}
1682
1683 Any debugging information entry that is owned (either
1684 directly or indirectly) by a debugging information entry
1685 with the tag \DWTAGinlinedsubroutine{} is referred to as a
1686 \doublequote{concrete inlined instance entry.} Any entry that has
1687 the tag 
1688 \DWTAGinlinedsubroutine{} 
1689 is known as a \doublequote{concrete inlined instance root.} 
1690 Any set of concrete inlined instance
1691 entries that are all children (either directly or indirectly)
1692 of some concrete inlined instance root, together with the root
1693 itself, is known as a \doublequote{concrete inlined instance tree.}
1694 However, in the case where a concrete inlined instance tree
1695 is nested within another concrete instance tree, the entries
1696 in the \addtoindex{nested concrete inline instance} tree 
1697 are not considered to
1698 be entries in the outer concrete instance tree.
1699
1700 \needlines{3}
1701 \textit{Concrete inlined instance trees are defined so that no entry
1702 is part of more than one concrete inlined instance tree. This
1703 simplifies later descriptions.}
1704
1705 Each concrete inlined instance tree is uniquely associated
1706 with one (and only one) abstract instance tree.
1707
1708 \textit{Note, however, that the reverse is not true. Any given abstract
1709 instance tree may be associated with several different concrete
1710 inlined instance trees, or may even be associated with zero
1711 concrete inlined instance trees.}
1712
1713 Concrete inlined instance entries may omit attributes that
1714 are not specific to the concrete instance (but present in
1715 the abstract instance) and need include only attributes that
1716 are specific to the concrete instance (but omitted in the
1717 abstract instance). In place of these omitted attributes, each
1718 \hypertarget{chap:DWATabstractorigininlineinstance}{}
1719 concrete inlined instance entry 
1720 \addtoindexx{abstract origin attribute}
1721 has a 
1722 \DWATabstractorigin{}
1723 attribute that may be used to obtain the missing information
1724 (indirectly) from the associated abstract instance entry. The
1725 value of the abstract origin attribute is a reference to the
1726 associated abstract instance entry.
1727
1728 If an entry within a concrete inlined instance tree contains
1729 attributes describing the 
1730 \addtoindexx{declaration coordinates!in concrete instance}
1731 \livelink{chap:declarationcoordinates}{declaration coordinates} 
1732 of that entry, then those attributes should refer to the file, line
1733 and column of the original declaration of the subroutine,
1734 not to the point at which it was inlined. As a consequence,
1735 they may usually be omitted from any entry that has an abstract
1736 origin attribute.
1737
1738 \needlines{4}
1739 For each pair of entries that are associated via a
1740 \addtoindexx{abstract origin attribute}
1741 \DWATabstractorigin{} attribute, both members of the pair
1742 have the same tag. So, for example, an entry with the tag
1743 \DWTAGvariable{} can only be associated with another entry
1744 that also has the tag \DWTAGvariable. The only exception
1745 to this rule is that the root of a concrete instance tree
1746 (which must always have the tag \DWTAGinlinedsubroutine)
1747 can only be associated with the root of its associated abstract
1748 instance tree (which must have the tag \DWTAGsubprogram).
1749
1750 \needlines{6}
1751 In general, the structure and content of any given concrete
1752 inlined instance tree will be closely analogous to the
1753 structure and content of its associated abstract instance
1754 tree. There are a few exceptions:
1755
1756 \begin{enumerate}[1. ]
1757 \item An entry in the concrete instance tree may be omitted if
1758 it contains only a 
1759 \addtoindexx{abstract origin attribute}
1760 \DWATabstractorigin{} attribute and either
1761 has no children, or its children are omitted. Such entries
1762 would provide no useful information. In C\dash like languages,
1763 such entries frequently include types, including structure,
1764 union, class, and interface types; and members of types. If any
1765 entry within a concrete inlined instance tree needs to refer
1766 to an entity declared within the scope of the relevant inlined
1767 subroutine and for which no concrete instance entry exists,
1768 the reference should refer to the abstract instance entry.
1769
1770 \needlines{4}
1771 \item Entries in the concrete instance tree which are associated
1772 with entries in the abstract instance tree such that neither
1773 has a \DWATname{} attribute,
1774 \addtoindexx{name attribute}
1775 and neither is referenced by
1776 any other debugging information entry, may be omitted. This
1777 may happen for debugging information entries in the abstract
1778 instance trees that became unnecessary in the concrete instance
1779 tree because of additional information available there. For
1780 example, an anonymous variable might have been created and
1781 described in the abstract instance tree, but because of
1782 the actual parameters for a particular inlined expansion,
1783 it could be described as a constant value without the need
1784 for that separate debugging information entry.
1785
1786 \item A concrete instance tree may contain entries which do
1787 not correspond to entries in the abstract instance tree
1788 to describe new entities that are specific to a particular
1789 inlined expansion. In that case, they will not have associated
1790 entries in the abstract instance tree, should not contain
1791 \addtoindexx{abstract origin attribute}
1792 \DWATabstractorigin{} attributes, and must contain all their
1793 own attributes directly. This allows an abstract instance tree
1794 to omit debugging information entries for anonymous entities
1795 that are unlikely to be needed in most inlined expansions. In
1796 any expansion which deviates from that expectation, the
1797 entries can be described in its concrete inlined instance tree.
1798
1799 \end{enumerate}
1800
1801 \subsubsection{Out-of-Line Instances of Inlined Subroutines}
1802 \label{chap:outoflineinstancesofinlinedsubroutines}
1803 Under some conditions, compilers may need to generate concrete
1804 executable instances of inlined subroutines other than at
1805 points where those subroutines are actually called. Such
1806 concrete instances of inlined subroutines are referred to as
1807 \doublequote{concrete out\dash of\dash line instances.}
1808
1809 \textit{In \addtoindex{C++}, for example, 
1810 taking the address of a function declared
1811 to be inline can necessitate the generation of a concrete
1812 out\dash of\dash line instance of the given function.}
1813
1814 The DWARF representation of a concrete out\dash of\dash line instance
1815 of an inlined subroutine is essentially the same as for a
1816 concrete inlined instance of that subroutine (as described in
1817 the preceding section). The representation of such a concrete
1818 % It is critical that the hypertarget and livelink be
1819 % separated to avoid problems with latex.
1820 out\dash of\dash line 
1821 \addtoindexx{abstract origin attribute}
1822 instance 
1823 \hypertarget{chap:DWATabstractoriginoutoflineinstance}{}
1824 makes use of 
1825 \DWATabstractorigin{}
1826 attributes in exactly the same way as they are used for
1827 a concrete inlined instance (that is, as references to
1828 corresponding entries within the associated abstract instance
1829 tree).
1830
1831 \needlines{5}
1832 The differences between the DWARF representation of a
1833 concrete out\dash of\dash line instance of a given subroutine and the
1834 representation of a concrete inlined instance of that same
1835 subroutine are as follows:
1836
1837 \begin{enumerate}[1. ]
1838 \item  The root entry for a concrete out\dash of\dash line instance
1839 of a given inlined subroutine has the same tag as does its
1840 associated (abstract) inlined subroutine entry (that is, tag
1841 \DWTAGsubprogram{} rather than \DWTAGinlinedsubroutine).
1842
1843 \item The root entry for a concrete out\dash of\dash line instance tree
1844 is normally owned by the same parent entry that also owns
1845 the root entry of the associated abstract instance. However,
1846 it is not required that the abstract and out\dash of\dash line instance
1847 trees be owned by the same parent entry.
1848
1849 \end{enumerate}
1850
1851 \subsubsection{Nested Inlined Subroutines}
1852 \label{nestedinlinedsubroutines}
1853 Some languages and compilers may permit the logical nesting of
1854 a subroutine within another subroutine, and may permit either
1855 the outer or the nested subroutine, or both, to be inlined.
1856
1857 For a non\dash inlined subroutine nested within an inlined
1858 subroutine, the nested subroutine is described normally in
1859 both the abstract and concrete inlined instance trees for
1860 the outer subroutine. All rules pertaining to the abstract
1861 and concrete instance trees for the outer subroutine apply
1862 also to the abstract and concrete instance entries for the
1863 nested subroutine.
1864
1865 \needlines{5}
1866 For an inlined subroutine nested within another inlined
1867 subroutine, the following rules apply to their abstract and
1868 \addtoindexx{abstract instance!nested}
1869 \addtoindexx{concrete instance!nested}
1870 concrete instance trees:
1871
1872 \begin{enumerate}[1. ]
1873 \item The abstract instance tree for the nested subroutine is
1874 described within the abstract instance tree for the outer
1875 subroutine according to the rules in 
1876 Section \refersec{chap:abstractinstances}, and
1877 without regard to the fact that it is within an outer abstract
1878 instance tree.
1879
1880 \item Any abstract instance tree for a nested subroutine is
1881 always omitted within the concrete instance tree for an
1882 outer subroutine.
1883
1884 \item  A concrete instance tree for a nested subroutine is
1885 always omitted within the abstract instance tree for an
1886 outer subroutine.
1887
1888 \item The concrete instance tree for any inlined or 
1889 \addtoindexx{out-of-line instance}
1890 out-of-line
1891 \addtoindexx{out-of-line instance|see{\textit{also} concrete out-of-line instance}}
1892 expansion of the nested subroutine is described within a
1893 concrete instance tree for the outer subroutine according
1894 to the rules in 
1895 Sections \refersec{chap:concreteinlinedinstances} or 
1896 \referfol{chap:outoflineinstancesofinlinedsubroutines}
1897 , respectively,
1898 and without regard to the fact that it is within an outer
1899 concrete instance tree.
1900 \end{enumerate}
1901
1902 See Appendix \refersec{app:inliningexamples} 
1903 for discussion and examples.
1904
1905 \subsection{Trampolines}
1906 \label{chap:trampolines}
1907
1908 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1909 \hypertarget{chap:DWATtrampolinetargetsubroutine}{}
1910 an intermediary in making a call to another subroutine. It may
1911 adjust parameters and/or the result (if any) as appropriate
1912 to the combined calling and called execution contexts.}
1913
1914 A trampoline is represented by a debugging information entry
1915 \addtoindexx{trampoline (subprogram) entry}
1916 with the tag \DWTAGsubprogram{} or \DWTAGinlinedsubroutine{}
1917 that has 
1918 \addtoindexx{trampoline attribute}
1919 a \DWATtrampoline{} attribute. 
1920 The value of that
1921 attribute indicates the target subroutine of the trampoline,
1922 that is, the subroutine to which the trampoline passes
1923 control. (A trampoline entry may but need not also have a
1924 \DWATartificial{} attribute.)
1925
1926 \needlines{5}
1927 The value of the trampoline attribute may be represented
1928 using any of the following forms, which are listed in order
1929 of preference:
1930
1931 \begin{itemize}
1932 \item If the value is of class reference, then the value
1933 specifies the debugging information entry of the target
1934 subprogram.
1935
1936 \item If the value is of class address, then the value is
1937 the relocated address of the target subprogram.
1938
1939 \item If the value is of class string, then the value is the
1940 (possibly mangled) \addtoindexx{mangled names}
1941 name of the target subprogram.
1942
1943 \item If the value is of class \livelink{chap:classflag}{flag}, then the value true
1944 indicates that the containing subroutine is a trampoline but
1945 that the target subroutine is not known.
1946 \end{itemize}
1947
1948
1949 The target subprogram may itself be a trampoline. (A sequence
1950 of trampolines necessarily ends with a non\dash trampoline
1951 subprogram.)
1952
1953 \textit{In \addtoindex{C++}, trampolines may be used 
1954 to implement derived virtual
1955 member functions; such trampolines typically adjust the
1956 \addtoindexx{this parameter}
1957 implicit this pointer parameter in the course of passing
1958 control.  
1959 Other languages and environments may use trampolines
1960 in a manner sometimes known as transfer functions or transfer
1961 vectors.}
1962
1963 \textit{Trampolines may sometimes pass control to the target
1964 subprogram using a branch or jump instruction instead of a
1965 call instruction, thereby leaving no trace of their existence
1966 in the subsequent execution context. }
1967
1968 \textit{This attribute helps make it feasible for a debugger to arrange
1969 that stepping into a trampoline or setting a breakpoint in
1970 a trampoline will result in stepping into or setting the
1971 breakpoint in the target subroutine instead. This helps to
1972 hide the compiler generated subprogram from the user. }
1973
1974 \textit{If the target subroutine is not known, a debugger may choose
1975 to repeatedly step until control arrives in a new subroutine
1976 which can be assumed to be the target subroutine. }
1977
1978 \subsection{Call Site Entries}
1979 \label{chap:callsiteentries}
1980 \textit{
1981 A call site entry provides a way to represent the static or dynamic 
1982 call graph of a program in the debugging information. It also provides
1983 information about how parameters are passed so that they may be more
1984 easily accessed by a debugger. Together with the \DWOPentryvalue{} opcode,
1985 call site entries can be also useful for computing values of variables 
1986 and expressions where some value is no longer present in the current 
1987 subroutine's registers or local stack frame, but it is known that the 
1988 values are equal to some parameter passed to the function.  
1989 The consumer can then use unwind
1990 information to find the caller and in the call site information sometimes
1991 find how to compute the value passed in a particular parameter.}
1992
1993 A call site is represented by a debugging information entry with the tag
1994 \DWTAGcallsiteTARG{}.  The entry for a call site is owned by the innermost
1995 debugging information entry representing the scope within which the
1996 call is present in the source program.
1997
1998 \textit{A scope entry (for example, for a lexical block) that would not 
1999 otherwise be present in the debugging information of a subroutine
2000 need not be introduced solely to represent the immediately containing scope
2001 of a call. The call site entry is owned by the innermost scope entry that
2002 is present.}
2003
2004 A source call can be compiled into different types of machine code:
2005 \begin{itemize}
2006 \item
2007 A \textit{normal call} uses a call-like instruction which transfers control to the start
2008 of some subprogram and leaves the call site location address somewhere where
2009 unwind information can find it.  
2010 \item
2011 A \textit{tail call} uses a jump-like instruction which
2012 transfers control to the start of some subprogram, but the call site location
2013 address is not preserved (and thus not available using the unwind information).  
2014 \item
2015 A \textit{tail recursion call} is a call
2016 to the current subroutine which is compiled as a loop into the middle of the
2017 current subroutine.
2018 \needlines{4}
2019 \item
2020 An \textit{inline (or inlined) call} is a call to an inlined subprogram,
2021 where at least one instruction has the location of the inlined subprogram
2022 or any of its blocks or inlined subprograms. 
2023 \end{itemize}
2024
2025 \needlines{4}
2026 There are also different types of \doublequote{optimized out} calls:
2027 \begin{itemize}
2028 \item
2029 An \textit{optimized out (normal) call} is a call that is in unreachable code that 
2030 has not been emitted (such as, for example, the call to \texttt{foo} in 
2031 \texttt{if (0) foo();}).  
2032 \item
2033 An \textit{optimized out inline call}
2034 is a call to an inlined subprogram which either did not expand to any instructions
2035 or only parts of instructions belong to it and for debug information purposes those
2036 instructions are given a location in the caller.
2037 \end{itemize}
2038
2039 \DWTAGcallsite{} entries describe normal and tail calls but not tail recursion calls,
2040 while \DWTAGinlinedsubroutine{} entries describe inlined calls 
2041 (see Section \refersec{chap:inlinedsubroutines}).
2042
2043 The call site entry has a 
2044 \DWATcallreturnpcNAME{}
2045 \livetargi{chap:DWATcallreturnpcofcallsite}{attribute}{call return pc attribute} 
2046 which is the return address after the call.  
2047 The value of this attribute corresponds to the return address computed by 
2048 call frame information in the called subprogram 
2049 (see Section \refersec{datarep:callframeinformation}).
2050
2051 \textit{On many architectures the return address is the address immediately following the
2052 call instruction, but on architectures with delay slots it might
2053 be an address after the delay slot of the call.}
2054
2055 The call site entry may have a 
2056 \DWATcallpcNAME{}
2057 \livetargi{chap:DWATcallpcofcallsite}{attribute}{call pc attribute} which is the
2058 address of the call instruction.
2059
2060 If the call site entry corresponds to a tail call, it has the 
2061 \DWATcalltailcallNAME{}
2062 \livetargi{chap:DWATcalltailcallofcallsite}{attribute}{call tail call attribute},
2063 which is a \CLASSflag.
2064
2065 The call site entry may have a 
2066 \DWATcalloriginNAME{}
2067 \livetargi{chap:DWATcalloriginofcallsite}{attribute}{call origin attribute}
2068 which is a \CLASSreference.  For direct calls or jumps where the called subprogram is
2069 known it is a reference to the called subprogram's debugging
2070 information entry.  For indirect calls it may be a reference to a
2071 \DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
2072 the subroutine pointer that is called.
2073
2074 \needlines{4}
2075 The call site may have a 
2076 \DWATcalltargetNAME{}
2077 \livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
2078 a DWARF expression.  For indirect calls or jumps where it is unknown at
2079 compile time which subprogram will be called the expression computes the
2080 address of the subprogram that will be called.  The DWARF expression should
2081 not use register or memory locations that might be clobbered by the call.
2082
2083 \needlines{4}
2084 The call site entry may have a 
2085 \DWATcalltargetclobberedNAME{}
2086 \livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
2087 which is a DWARF expression.  For indirect calls or jumps where the
2088 address is not computable without use of registers or memory locations that
2089 might be clobbered by the call the \DWATcalltargetclobberedNAME{}
2090 attribute is used instead of the \DWATcalltarget{} attribute.
2091
2092 The call site entry may have a \DWATtypeNAME{}
2093 \livetargi{chap:DWATtypeofcallsite}{attribute}{type attribute!of call site entry}
2094 referencing a debugging information entry for the type of the called function.  
2095 When \DWATcallorigin{} is present, \DWATtypeNAME{} is usually omitted.
2096
2097 The call site entry may have 
2098 \DWATcallfileNAME{}, \DWATcalllineNAME{} and \DWATcallcolumnNAME{} 
2099 \livetargi{chap:DWATcallfileofcallsite}{attributes,}{call file attribute!of call site entry}
2100 \livetargi{chap:DWATcalllineofcallsite}{}{call line attribute!of call site entry}
2101 \livetargi{chap:DWATcallcolumnofcallsite}{}{call column attribute!of call site entry}
2102 each of whose value is an integer constant.
2103 These attributes represent the source file, source line number, and source
2104 column number, respectively, of the first character of the call statement or
2105 expression.  The call file, call line, and call column attributes are
2106 interpreted in the same way as the declaration file, declaration
2107 line, and declaration column attributes, respectively 
2108 (see Section \refersec{chap:declarationcoordinates}).
2109
2110 \textit{The call file, call line and call column coordinates do not describe the
2111 coordinates of the subroutine declaration that was inlined, rather they describe
2112 the coordinates of the call.}
2113
2114 The call site entry may own \DWTAGcallsiteparameterTARG{} debugging information
2115 entries\index{call site parameter entry} representing the parameters passed to the call.
2116 Each such entry has a \DWATlocation{} attribute which is a location expression.
2117 This location expression describes where the parameter is passed
2118 (usually either some register, or a memory location expressible as the
2119 contents of the stack register plus some offset).
2120
2121 Each \DWTAGcallsiteparameter{} entry may have a 
2122 \DWATcallvalueNAME{}
2123 \livetargi{chap:DWATcallvalueofcallparameter}{attribute}{call value attribute}
2124 which is a DWARF expression.  This expression computes the value
2125 passed for that parameter.  The expression should not use registers or memory
2126 locations that might be clobbered by the call, as it might be evaluated after
2127 unwinding from the called function back to the caller.  If it is not
2128 possible to avoid registers or memory locations that might be clobbered by
2129 the call in the expression, then the \DWATcallvalueNAME{} attribute should
2130 not be provided.
2131
2132 \textit{The reason for the restriction is that the value of the parameter may be
2133 needed in the middle of the callee, where the call clobbered registers or
2134 memory might be already clobbered, and if the consumer was not assured by
2135 the producer it can safely use those values, the consumer could not safely
2136 use the values at all.}
2137
2138 For parameters passed by reference, where the code passes a pointer to
2139 a location which contains the parameter, or for reference type parameters
2140 the \DWTAGcallsiteparameter{} entry may also have 
2141 \DWATcalldatalocationNAME{}
2142 \livetargi{chap:DWATcalldatalocationofcallparameter}{attribute}{call data location attribute}
2143 whose value is a location expression and a
2144 \DWATcalldatavalueNAME{}
2145 \livetargi{chap:DWATcalldatavalueofcallparameter}{attribute}{call data value attribute}
2146 whose value is a DWARF expression.  The \DWATcalldatalocationNAME{} attribute 
2147 describes where the referenced value lives during the call.  If it is just 
2148 \DWOPpushobjectaddress{}, it may be left out.  The 
2149 \DWATcalldatavalueNAME{} attribute describes the value in that location. 
2150 The expression should not use registers or memory
2151 locations that might be clobbered by the call, as it might be evaluated after
2152 unwinding from the called function back to the caller.
2153
2154 \needlines{4}
2155 Each call site parameter entry may also have a 
2156 \DWATcallparameter{}
2157 \livetargi{chap:DWATcallparameterofcallparameter}{attribute}{call parameter attribute}
2158 which contains a reference to a \DWTAGformalparameter{} entry,
2159 \DWATtype{} attribute referencing the type of the parameter or \DWATname{}
2160 attribute describing the parameter's name.
2161
2162
2163
2164 \section{Lexical Block Entries}
2165 \label{chap:lexicalblockentries}
2166
2167 \textit{A 
2168 lexical \livetargi{chap:lexicalblock}{block}{lexical block} 
2169 is 
2170 \addtoindexx{lexical block}
2171 a bracketed sequence of source statements
2172 that may contain any number of declarations. In some languages
2173 (including \addtoindex{C} and \addtoindex{C++}),
2174 \nolink{blocks} can be nested within other
2175 \nolink{blocks} to any depth.}
2176
2177 % We do not need to link to the preceding paragraph.
2178 A lexical \nolink{block} is represented by a debugging information
2179 entry with the 
2180 tag \DWTAGlexicalblockTARG.
2181
2182 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} 
2183 entry may have 
2184 either a \DWATlowpc{} and
2185 \DWAThighpc{} pair of 
2186 attributes 
2187 \addtoindexx{high PC attribute}
2188 or 
2189 \addtoindexx{low PC attribute}
2190
2191 \DWATranges{} attribute
2192 \addtoindexx{ranges attribute}
2193 whose values encode the contiguous or non-contiguous address
2194 ranges, respectively, of the machine instructions generated
2195 for the lexical \nolink{block} 
2196 (see Section \refersec{chap:codeaddressesandranges}).
2197
2198
2199 \hypertarget{chap:DWATentrypcoflexicalblock}{}
2200 lexical block entry may also have 
2201 \addtoindexx{entry pc attribute!for lexical block}
2202
2203 \DWATentrypc{} attribute
2204 whose value is the address of the first executable instruction
2205 of the lexical block (see 
2206 Section \refersec{chap:entryaddress}).
2207
2208 If a name has been given to the 
2209 lexical \nolink{block} 
2210 in the source
2211 program, then the corresponding 
2212 lexical \nolink{block} entry has a
2213 \DWATname{} attribute whose 
2214 \addtoindexx{name attribute}
2215 value is a null\dash terminated string
2216 containing the name of the lexical \nolink{block} 
2217 as it appears in
2218 the source program.
2219
2220 \textit{This is not the same as a \addtoindex{C} or 
2221 \addtoindex{C++} label (see below).}
2222
2223 The lexical \nolink{block} entry owns 
2224 debugging information entries that
2225 describe the declarations within that lexical \nolink{block}. 
2226 There is
2227 one such debugging information entry for each local declaration
2228 of an identifier or inner lexical \nolink{block}.
2229
2230 \needlines{10}
2231 \section{Label Entries}
2232 \label{chap:labelentries}
2233 \textit{A label is a way of identifying a source statement. A labeled
2234 statement is usually the target of one or more \doublequote{go to}
2235 statements.
2236 }
2237
2238 \needlines{4}
2239 A label is represented by a debugging information entry with
2240 \addtoindexx{label entry}
2241 the 
2242 tag \DWTAGlabelTARG. 
2243 The entry for a label should be owned by
2244 the debugging information entry representing the scope within
2245 which the name of the label could be legally referenced within
2246 the source program.
2247
2248 The label entry has a \DWATlowpc{} attribute whose value
2249 is the relocated address of the first machine instruction
2250 generated for the statement identified by the label in
2251 the source program.  The label entry also has a 
2252 \DWATname{} attribute 
2253 \addtoindexx{name attribute}
2254 whose value is a null-terminated string containing
2255 the name of the label as it appears in the source program.
2256
2257
2258 \section{With Statement Entries}
2259 \label{chap:withstatemententries}
2260
2261 \textit{Both \addtoindex{Pascal} and 
2262 \addtoindexx{Modula-2}
2263 Modula\dash 2 support the concept of a \doublequote{with}
2264 statement. The with statement specifies a sequence of
2265 executable statements within which the fields of a record
2266 variable may be referenced, unqualified by the name of the
2267 record variable.}
2268
2269 A with statement is represented by a
2270 \addtoindexi{debugging information entry}{with statement entry}
2271 with the tag \DWTAGwithstmtTARG.
2272
2273 A with statement entry may have either a 
2274 \DWATlowpc{} and
2275 \DWAThighpc{} pair of attributes 
2276 \addtoindexx{high PC attribute}
2277 or 
2278 \addtoindexx{low PC attribute}
2279 a \DWATranges{} attribute
2280 \addtoindexx{ranges attribute}
2281 whose values encode the contiguous or non\dash contiguous address
2282 ranges, respectively, of the machine instructions generated
2283 for the with statement 
2284 (see Section \refersec{chap:codeaddressesandranges}).
2285
2286
2287 \hypertarget{chap:DWATentrypcofwithstmt}{}
2288 with statement entry may also have 
2289 \addtoindexx{entry pc attribute!for with statement}
2290
2291 \DWATentrypc{} attribute
2292 whose value is the address of the first executable instruction
2293 of the with statement (see 
2294 Section \refersec{chap:entryaddress}).
2295
2296 \needlines{5}
2297 The with statement entry has 
2298 \addtoindexx{type attribute}
2299 a \DWATtype{} attribute, denoting
2300 the type of record whose fields may be referenced without full
2301 qualification within the body of the statement. It also has
2302 \addtoindexx{location attribute}
2303 a \DWATlocation{} attribute, describing how to find the base
2304 address of the record object referenced within the body of
2305 the with statement.
2306
2307 \needlines{6}
2308 \section{Try and Catch Block Entries}
2309 \label{chap:tryandcatchblockentries}
2310
2311 \textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be 
2312 designated as a \doublequote{catch \nolink{block}.} 
2313 A catch \livetargi{chap:catchblock}{block}{catch block} is an 
2314 exception handler that handles
2315 exceptions thrown by an immediately 
2316 preceding \doublequote{try \livelink{chap:tryblock}{block}.}
2317 A catch \livelink{chap:catchblock}{block} 
2318 designates the type of the exception that it
2319 can handle.}
2320
2321 A try \livetargi{chap:tryblock}{block}{try block} is represented 
2322 by a debugging information entry
2323 \addtoindexx{try block entry}
2324 with the tag \DWTAGtryblockTARG.  
2325 A catch \livelink{chap:catchblock}{block} is represented by
2326 a debugging information entry with 
2327 \addtoindexx{catch block entry}
2328 the tag \DWTAGcatchblockTARG.
2329
2330 % nolink as we have links just above and do not have a combo link for both
2331 Both try and catch \nolink{block} entries may have either a
2332 \DWATlowpc{} and 
2333 \DWAThighpc{} pair of attributes 
2334 \addtoindexx{high PC attribute}
2335 or 
2336 \addtoindexx{low PC attribute}
2337 a
2338 \DWATranges{} attribute 
2339 \addtoindexx{ranges attribute}
2340 whose values encode the contiguous
2341 or non\dash contiguous address ranges, respectively, of the
2342 machine instructions generated for the \livelink{chap:lexicalblock}{block}
2343 (see Section
2344 \refersec{chap:codeaddressesandranges}).
2345
2346
2347 \hypertarget{chap:DWATentrypcoftryblock}{}
2348 \hypertarget{chap:DWATentrypcofcatchblock}{}
2349 try or catch block entry may also have 
2350 \addtoindexx{entry pc attribute!for try block}
2351 \addtoindexx{entry pc attribute!for catch block}
2352
2353 \DWATentrypc{} attribute
2354 whose value is the address of the first executable instruction
2355 of the try or catch block (see 
2356 Section \refersec{chap:entryaddress}).
2357
2358 Catch \livelink{chap:catchblock}{block} entries have at 
2359 least one child entry, an
2360 entry representing the type of exception accepted by
2361 that catch \livelink{chap:catchblock}{block}. 
2362 This child entry has one of 
2363 \addtoindexx{formal parameter entry!in catch block}
2364 the 
2365 \addtoindexx{unspecified parameters entry!in catch block}
2366 tags
2367 \DWTAGformalparameter{} or
2368 \DWTAGunspecifiedparameters,
2369 and will have the same form as other parameter entries.
2370
2371 The siblings immediately following 
2372 a try \livelink{chap:tryblock}{block} entry are its
2373 corresponding catch \livelink{chap:catchblock}{block} entries.
2374