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