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