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