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