Complete work on live links, cleanup some indexing and redo pagination.
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
1 \chapter{Program Scope Entries}
2 \label{chap:programscopeentries} 
3 This section describes debugging information entries that
4 relate to different levels of program scope: compilation,
5 module, subprogram, and so on. Except for separate type
6 entries (see Section \refersec{chap:separatetypeunitentries}), 
7 these entries may be thought of
8 as bounded by ranges of text addresses within the program.
9
10 \section{Unit Entries}
11 An object file may contain one or more compilation units,
12 of which there are
13 \addtoindexx{unit|see {compilation unit, partial unit \textit{or} type unit}} 
14 \addtoindexx{compilation unit}
15 three kinds: 
16 \addtoindexx{normal compilation unit}
17 \addtoindexx{normal compilation unit|see {compilation unit}}
18 normal compilation units,
19 partial compilation units and 
20 \addtoindexx{type unit}
21 type units. A 
22 \addtoindex{partial compilation unit}
23 is related to one or more other compilation units that
24 import it. A 
25 \addtoindex{type unit} represents 
26 a single complete type in a
27 separate unit. Either a normal compilation unit or a 
28 \addtoindex{partial compilation unit}
29 may be logically incorporated into another
30 compilation unit using an 
31 \addtoindex{imported unit entry}.
32
33 \subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
34 \label{chap:normalandpartialcompilationunitentries}
35
36 A \addtoindex{normal compilation unit} is represented by a debugging
37 information entry with the 
38 tag \livetarg{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit}. 
39 A \addtoindex{partial compilation unit} is represented by a debugging information
40 entry with the 
41 tag \livetarg{chap:DWTAGpartialunit}{DW\_TAG\_partial\_unit}.
42
43 In a simple normal compilation, a single compilation unit with
44 the tag 
45 \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit} represents a complete object file
46 and the tag 
47 \livelink{chap:DWTAGpartialunit}{DW\_TAG\_partial\_unit} is not used. 
48 In a compilation
49 employing the DWARF space compression and duplicate elimination
50 techniques from 
51 Appendix \refersec{app:usingcompilationunits}, 
52 multiple compilation units using
53 the tags 
54 \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit} and/or 
55 \livelink{chap:DWTAGpartialunit}{DW\_TAG\_partial\_unit} are
56 used to represent portions of an object file.
57
58 \textit{A normal compilation unit typically represents the text and
59 data contributed to an executable by a single relocatable
60 object file. It may be derived from several source files,
61 including pre\dash processed \doublequote{include files}. 
62 A \addtoindex{partial compilation unit} typically represents a part of the text
63 and data of a relocatable object file, in a manner that can
64 potentially be shared with the results of other compilations
65 to save space. It may be derived from an \doublequote{include file},
66 template instantiation, or other implementation\dash dependent
67 portion of a compilation. A normal compilation unit can also
68 function in a manner similar to a partial compilation unit
69 in some cases.}
70
71 A compilation unit entry owns debugging information
72 entries that represent all or part of the declarations
73 made in the corresponding compilation. In the case of a
74 partial compilation unit, the containing scope of its owned
75 declarations is indicated by imported unit entries in one
76 or more other compilation unit entries that refer to that
77 partial compilation unit (see 
78 Section \refersec{chap:importedunitentries}).
79
80
81 Compilation unit entries may have the following 
82 attributes:
83 \begin{enumerate}[1. ]
84 \item Either a \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} and 
85 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} pair of
86 \addtoindexx{high PC attribute}
87 attributes 
88 \addtoindexx{low PC attribute}
89 or 
90 \addtoindexx{ranges attribute}
91
92 \livelink{chap:DWATranges}{DW\_AT\_ranges} attribute
93 \addtoindexx{ranges attribute}
94 whose values encode 
95 \addtoindexx{discontiguous address ranges|see{non-contiguous address ranges}}
96 the
97 contiguous or 
98 non\dash contiguous address ranges, respectively,
99 of the machine instructions generated for the compilation
100 unit (see Section \refersec{chap:codeaddressesandranges}).
101   
102 A \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} attribute 
103 may also
104 be specified 
105 in combination 
106 \addtoindexx{ranges attribute}
107 with 
108 \livelink{chap:DWATranges}{DW\_AT\_ranges} to specify the
109 \addtoindexx{ranges attribute}
110 default base address for use in 
111 \addtoindexx{location list}
112 location lists (see Section
113 \refersec{chap:locationlists}) and range lists 
114 \addtoindexx{range list}
115 (see Section \refersec{chap:noncontiguousaddressranges}).
116
117 \item A \livelink{chap:DWATname}{DW\_AT\_name} attribute 
118 \addtoindexx{name attribute}
119 whose value is a null\dash terminated
120 string 
121 \hypertarget{chap:DWATnamepathnameofcompilationsource}
122 containing the full or relative path name of the primary
123 source file from which the compilation unit was derived.
124
125 \item A \livelink{chap:DWATlanguage}{DW\_AT\_language} attribute 
126 \addtoindexx{language attribute}
127 whose constant value is an
128 \hypertarget{chap:DWATlanguageprogramminglanguage}
129 integer code 
130 \addtoindexx{language attribute}
131 indicating the source language of the compilation
132 unit. The set of language names and their meanings are given
133 in Table \refersec{tab:languagenames}.
134
135 \begin{table}[here]
136 \centering
137 \caption{Language names}
138 \label{tab:languagenames}
139 \begin{tabular}{l|l}
140 \hline
141 Language name & Meaning\\ \hline
142 \livetarg{chap:DWLANGAda83}{DW\_LANG\_Ada83} \dag&ISO \addtoindex{Ada}:1983 \addtoindexx{Ada} \\
143 \livetarg{chap:DWLANGAda95}{DW\_LANG\_Ada95} \dag&ISO Ada:1995 \addtoindexx{Ada} \\
144 \livetarg{chap:DWLANGC}{DW\_LANG\_C}&Non-standardized C, such as K\&R \\
145 \livetarg{chap:DWLANGC89}{DW\_LANG\_C89}&ISO C:1989 \\
146 \livetarg{chap:DWLANGC99}{DW\_LANG\_C99} & ISO \addtoindex{C}:1999 \\
147 \livetarg{chap:DWLANGCplusplus}{DW\_LANG\_C\_plus\_plus}&ISO \addtoindex{C++}:1998 \\
148 \livetarg{chap:DWLANGCobol74}{DW\_LANG\_Cobol74}& ISO \addtoindex{Cobol}:1974 \\
149 \livetarg{chap:DWLANGCobol85}{DW\_LANG\_Cobol85} & ISO \addtoindex{Cobol}:1985 \\
150 \livetarg{chap:DWLANGD}{DW\_LANG\_D} \dag & D \addtoindexx{D language} \\
151 \livetarg{chap:DWLANGFortran77}{DW\_LANG\_Fortran77} &ISO \addtoindex{FORTRAN} 77\\
152 \livetarg{chap:DWLANGFortran90}{DW\_LANG\_Fortran90} & ISO \addtoindex{Fortran 90}\\
153 \livetarg{chap:DWLANGFortran95}{DW\_LANG\_Fortran95} & ISO \addtoindex{Fortran 95}\\
154 \livetarg{chap:DWLANGJava}{DW\_LANG\_Java} & \addtoindex{Java}\\
155 \livetarg{chap:DWLANGModula2}{DW\_LANG\_Modula2} & ISO Modula\dash 2:1996 \addtoindexx{Modula-2}\\
156 \livetarg{chap:DWLANGObjC}{DW\_LANG\_ObjC} & \addtoindex{Objective C}\\
157 \livetarg{chap:DWLANGObjCplusplus}{DW\_LANG\_ObjC\_plus\_plus} & \addtoindex{Objective C++}\\
158 \livetarg{chap:DWLANGPascal83}{DW\_LANG\_Pascal83} & ISO \addtoindex{Pascal}:1983\\
159 \livetarg{chap:DWLANGPLI}{DW\_LANG\_PLI} \dag & ANSI \addtoindex{PL/I}:1976\\
160 \livetarg{chap:DWLANGPython}{DW\_LANG\_Python} \dag & \addtoindex{Python}\\
161 \livetarg{chap:DWLANGUPC}{DW\_LANG\_UPC} &\addtoindex{Unified Parallel C}\addtoindexx{UPC}\\ \hline
162 \dag \ \ \textit{Support for these languages is limited.}& \\
163 \end{tabular}
164 \end{table}
165
166 \item A \livelink{chap:DWATstmtlist}{DW\_AT\_stmt\_list}
167 attribute whose value is 
168 \addtoindexx{statement list attribute}
169
170 \addtoindexx{section offset!in statement list attribute}
171 section
172 \hypertarget{chap:DWATstmtlistlinenumberinformationforunit}
173 offset to the line number information for this compilation
174 unit.
175
176 This information is placed in a separate object file
177 section from the debugging information entries themselves. The
178 value of the statement list attribute is the offset in the
179 \dotdebugline{} section of the first byte of the line number
180 information for this compilation unit 
181 (see Section \refersec{chap:linenumberinformation}).
182
183 \item A \livelink{chap:DWATmacroinfo}{DW\_AT\_macro\_info} attribute 
184 \addtoindexx{macro information attribute}
185 whose value is a 
186 \addtoindexx{section offset!in macro information attribute}
187 section
188 \hypertarget{chap:DWATmacroinfomacroinformation}
189 offset to the macro information for this compilation unit.
190
191 This information is placed in a separate object file section
192 from the debugging information entries themselves. The
193 value of the macro information attribute is the offset in
194 the \dotdebugmacinfo{} section of the first byte of the macro
195 information for this compilation unit 
196 (see Section \refersec{chap:macroinformation}).
197
198 \item  A 
199 \livelink{chap:DWATcompdir}{DW\_AT\_comp\_dir} 
200 attribute 
201 \hypertarget{chap:DWATcompdircompilationdirectory}
202 whose value is a
203 null\dash terminated string containing the current working directory
204 of the compilation command that produced this compilation
205 unit in whatever form makes sense for the host system.
206
207 \item  A \livelink{chap:DWATproducer}{DW\_AT\_producer} attribute 
208 \addtoindexx{producer attribute}
209 whose value is a null\dash
210 terminated string containing information about the compiler
211 \hypertarget{chap:DWATproducercompileridentification}
212 that produced the compilation unit. The actual contents of
213 the string will be specific to each producer, but should
214 begin with the name of the compiler vendor or some other
215 identifying character sequence that should avoid confusion
216 with other producer values.
217
218 \needlines{4}
219 \item  A \livelink{chap:DWATidentifiercase}{DW\_AT\_identifier\_case} 
220 attribute 
221 \addtoindexx{identifier case attribute}
222 whose integer
223 \hypertarget{chap:DWATidentifiercaseidentifiercaserule}
224 constant value is a code describing the treatment
225 of identifiers within this compilation unit. The
226 set of identifier case codes is given in
227 Table \refersec{tab:identifiercasecodes}.
228
229 \begin{simplenametable}{Identifier case codes}{tab:identifiercasecodes}
230 \livelink{chap:DWIDcasesensitive}{DW\_ID\_case\_sensitive}        \\
231 \livelink{chap:DWIDupcase}{DW\_ID\_up\_case}                      \\
232 \livelink{chap:DWIDdowncase}{DW\_ID\_down\_case}                  \\
233 \livelink{chap:DWIDcaseinsensitive}{DW\_ID\_case\_insensitive}    \\
234 \end{simplenametable}
235
236 \livetarg{chap:DWIDcasesensitive}{DW\_ID\_case\_sensitive} is the default for all compilation units
237 that do not have this attribute.  It indicates that names given
238 as the values of \livelink{chap:DWATname}{DW\_AT\_name} attributes 
239 \addtoindexx{name attribute}
240 in debugging information
241 entries for the compilation unit reflect the names as they
242 appear in the source program. The debugger should be sensitive
243 to the case of identifier names when doing identifier lookups.
244
245 \livetarg{chap:DWIDupcase}{DW\_ID\_up\_case} means that the 
246 producer of the debugging
247 information for this compilation unit converted all source
248 names to upper case. The values of the name attributes may not
249 reflect the names as they appear in the source program. The
250 debugger should convert all names to upper case when doing
251 lookups.
252
253 \livetarg{chap:DWIDdowncase}{DW\_ID\_down\_case} means that 
254 the producer of the debugging
255 information for this compilation unit converted all source
256 names to lower case. The values of the name attributes may not
257 reflect the names as they appear in the source program. The
258 debugger should convert all names to lower case when doing
259 lookups.
260
261 \livetarg{chap:DWIDcaseinsensitive}{DW\_ID\_case\_insensitive} means that the values of the name
262 attributes reflect the names as they appear in the source
263 program but that a case insensitive lookup should be used to
264 access those names.
265
266 \item A \livelink{chap:DWATbasetypes}{DW\_AT\_base\_types} attribute whose value is a 
267 \livelink{chap:classreference}{reference}.
268
269
270 This 
271 \hypertarget{chap:DWATbasetypesprimitivedatatypesofcompilationunit}
272 attribute 
273 \addtoindexx{base types attribute}
274 points to a debugging information entry
275 representing another compilation unit.  It may be used
276 to specify the compilation unit containing the base type
277 entries used by entries in the current compilation unit
278 (see Section \refersec{chap:basetypeentries}).
279
280 \needlines{6}
281 This attribute provides a consumer a way to find the definition
282 of base types for a compilation unit that does not itself
283 contain such definitions. This allows a consumer, for example,
284 to interpret a type conversion to a base type 
285 % getting this link target at the right spot is tricky.
286 \hypertarget{chap:DWATuseUTF8compilationunitusesutf8strings}
287 correctly.
288
289 \item A \livelink{chap:DWATuseUTF8}{DW\_AT\_use\_UTF8} attribute,
290 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} 
291 which is a \livelink{chap:classflag}{flag} whose
292 presence indicates that all strings (such as the names of
293 declared entities in the source program) are represented
294 using the UTF\dash 8 representation 
295 (see Section \refersec{datarep:attributeencodings}).
296
297
298 \item A \livelink{chap:DWATmainsubprogram}{DW\_AT\_main\_subprogram} attribute, which is a \livelink{chap:classflag}{flag}
299 \addtoindexx{main subprogram attribute}
300 whose presence indicates 
301 \hypertarget{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}
302 that the compilation unit contains a
303 subprogram that has been identified as the starting function
304 of the program. If more than one compilation unit contains
305 this \nolink{flag}, any one of them may contain the starting function.
306
307 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement}
308 which is used
309 to specify and provide a user\dash specified name for the main
310 subroutine of a program. 
311 \addtoindex{C} uses the name \doublequote{main} to identify
312 the main subprogram of a program. Some other languages provide
313 similar or other means to identify the main subprogram of
314 a program.}
315
316 \end{enumerate}
317
318 The  base address of a compilation unit is defined as the
319 value of the \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} attribute, if present; otherwise,
320 it is undefined. If the base address is undefined, then any
321 DWARF entry or structure defined in terms of the base address
322 of that compilation unit is not valid.
323
324
325 \subsection{Imported Unit Entries}
326 \label{chap:importedunitentries}
327 The 
328 \hypertarget{chap:DWATimportimportedunit}
329 place where a normal or partial unit is imported is
330 represented by a debugging information entry with the 
331 \addtoindexx{imported unit entry}
332 tag \livetarg{chap:DWTAGimportedunit}{DW\_TAG\_imported\_unit}. 
333 An imported unit entry contains 
334 \addtoindexx{import attribute}
335 a
336 \livelink{chap:DWATimport}{DW\_AT\_import} attribute 
337 whose value is a \livelink{chap:classreference}{reference} to the
338 normal or partial compilation unit whose declarations logically
339 belong at the place of the imported unit entry.
340
341 \textit{An imported unit entry does not necessarily correspond to
342 any entity or construct in the source program. It is merely
343 \doublequote{glue} used to relate a partial unit, or a compilation
344 unit used as a partial unit, to a place in some other
345 compilation unit.}
346
347 \subsection{Separate Type Unit Entries}
348 \label{chap:separatetypeunitentries}
349 An object file may contain any number of separate type
350 unit entries, each representing a single complete type
351 definition. 
352 Each \addtoindex{type unit} must be uniquely identified by
353 a 64\dash bit signature, stored as part of the type unit, which
354 can be used to reference the type definition from debugging
355 information entries in other compilation units and type units.
356
357 A type unit is represented by a debugging information entry
358 with the tag \livetarg{chap:DWTAGtypeunit}{DW\_TAG\_type\_unit}. 
359 A \addtoindex{type unit entry} owns debugging
360 information entries that represent the definition of a single
361 type, plus additional debugging information entries that may
362 be necessary to include as part of the definition of the type.
363
364 A type unit entry may have a 
365 \livelink{chap:DWATlanguage}{DW\_AT\_language} attribute, 
366 whose
367 \addtoindexx{language attribute}
368 constant value is an integer code indicating the source
369 language used to define the type. The set of language names
370 and their meanings are given in Table \refersec{tab:languagenames}.
371
372 A \addtoindex{type unit} entry for a given type T owns a debugging
373 information entry that represents a defining declaration
374 of type T. If the type is nested within enclosing types or
375 namespaces, the debugging information entry for T is nested
376 within debugging information entries describing its containers;
377 otherwise, T is a direct child of the type unit entry.
378
379 A type unit entry may also own additional debugging information
380 entries that represent declarations of additional types that
381 are referenced by type T and have not themselves been placed in
382 separate type units. Like T, if an additional type U is nested
383 within enclosing types or namespaces, the debugging information
384 entry for U is nested within entries describing its containers;
385 otherwise, U is a direct child of the type unit entry.
386
387 The containing entries for types T and U are declarations,
388 and the outermost containing entry for any given type T or
389 U is a direct child of the type unit entry. The containing
390 entries may be shared among the additional types and between
391 T and the additional types.
392
393 \textit{Types are not required to be placed in type units. In general,
394 only large types such as structure, class, enumeration, and
395 union types included from header files should be considered
396 for separate type units. Base types and other small types
397 are not usually worth the overhead of placement in separate
398 type units. Types that are unlikely to be replicated, such
399 as those defined in the main source file, are also better
400 left in the main compilation unit.}
401
402 \section{Module, Namespace and Importing Entries}
403 \textit{Modules and namespaces provide a means to collect related
404 entities into a single entity and to manage the names of
405 those entities.}
406
407 \subsection{Module Entries}
408 \label{chap:moduleentries}
409 \textit{Several languages have the concept of a ``module.''
410 \addtoindexx{Modula-2}
411 A Modula\dash 2 definition module 
412 \addtoindexx{Modula-2!definition module}
413 may be represented by a module
414 entry containing a 
415 \addtoindex{declaration attribute}
416 (\livelink{chap:DWATdeclaration}{DW\_AT\_declaration}). A
417 \addtoindex{Fortran 90} module 
418 \addtoindexx{Fortran!module (Fortran 90)}
419 may also be represented by a module entry
420 (but no declaration attribute is warranted because \addtoindex{Fortran}
421 has no concept of a corresponding module body).}
422
423 A module is represented by a debugging information entry
424 with the 
425 tag \livetarg{chap:DWTAGmodule}{DW\_TAG\_module}.  
426 Module entries may own other
427 debugging information entries describing program entities
428 whose declaration scopes end at the end of the module itself.
429
430 If the module has a name, the module entry has a 
431 \livelink{chap:DWATname}{DW\_AT\_name} attribute 
432 \addtoindexx{name attribute}
433 whose value is a null\dash terminated string containing
434 the module name as it appears in the source program.
435
436 The \addtoindex{module entry} may have either a 
437 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} and
438 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} 
439 pair 
440 \addtoindexx{high PC attribute}
441 of 
442 \addtoindexx{low PC attribute}
443 attributes or a 
444 \livelink{chap:DWATranges}{DW\_AT\_ranges} attribute
445 \addtoindexx{ranges attribute}
446 whose values encode the contiguous or non\dash contiguous address
447 ranges, respectively, of the machine instructions generated for
448 the module initialization code 
449 (see Section \refersec{chap:codeaddressesandranges}). 
450 \hypertarget{chap:DWATentrypcentryaddressofmoduleinitialization}
451 It may also
452 \addtoindexx{entry pc attribute!for module initialization}
453 have a 
454 \livelink{chap:DWATentrypc}{DW\_AT\_entry\_pc} attribute whose value is the address of
455 the first executable instruction of that initialization code
456 (see Section \refersec{chap:entryaddress}).
457
458 If 
459 \hypertarget{chap:DWATprioritymodulepriority}
460 the module has been assigned a priority, it may have 
461 \addtoindexx{priority attribute}
462 a
463 \livelink{chap:DWATpriority}{DW\_AT\_priority} attribute. 
464 The value of this attribute is a
465 reference to another debugging information entry describing
466 a variable with a constant value. The value of this variable
467 is the actual constant value of the module\textquoteright s priority,
468 represented as it would be on the target architecture.
469
470 \subsection{Namespace Entries}
471 \label{chap:namespaceentries}
472 \textit{\addtoindex{C++} has the notion of a namespace, which provides a way to
473 \addtoindexx{namespace (C++)}
474 implement name hiding, so that names of unrelated things
475 do not accidentally clash in the 
476 \addtoindex{global namespace} when an
477 application is linked together.}
478
479 A namespace is represented by a debugging information entry
480 with the 
481 tag \livetarg{chap:DWTAGnamespace}{DW\_TAG\_namespace}. 
482 A namespace extension is
483 \hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}
484 represented by a 
485 \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace} entry 
486 with 
487 \addtoindexx{extension attribute}
488
489 \livelink{chap:DWATextension}{DW\_AT\_extension}
490 attribute referring to the previous extension, or if there
491 is no previous extension, to the original 
492 \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace}
493 entry. A namespace extension entry does not need to duplicate
494 information in a previous extension entry of the namespace
495 nor need it duplicate information in the original namespace
496 entry. (Thus, for a namespace with a name, 
497 a \livelink{chap:DWATname}{DW\_AT\_name} attribute 
498 \addtoindexx{name attribute}
499 need only be attached directly to the original
500 \livelink{chap:DWTAGnamespace}{DW\_TAG\_namespace} entry.)
501
502 \needlines{4}
503 Namespace and namespace extension entries may own 
504 \addtoindexx{namespace extension entry}
505 other
506 \addtoindexx{namespace declaration entry}
507 debugging information entries describing program entities
508 whose declarations occur in the namespace.
509
510 \textit{For \addtoindex{C++}, such 
511 owned program entities may be declarations,
512 including certain declarations that are also object or
513 function definitions.}
514
515 If a type, variable, or function declared in a namespace is
516 defined outside of the body of the namespace declaration,
517 that type, variable, or function definition entry has a
518 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute 
519 \addtoindexx{specification attribute}
520 whose value is a \livelink{chap:classreference}{reference} to the
521 debugging information entry representing the declaration of
522 the type, variable or function. Type, variable, or function
523 entries with a 
524 \livelink{chap:DWATspecification}{DW\_AT\_specification} attribute 
525 \addtoindexx{specification attribute}
526 do not need
527 to duplicate information provided by the declaration entry
528 referenced by the specification attribute.
529
530 \textit{The \addtoindex{C++} \addtoindex{global namespace}
531 (the 
532 \addtoindexx{global namespace|see{namespace (C++), global}}
533 namespace 
534 \addtoindexx{namespace (C++)!global}
535 referred to by
536 ``::f'', for example) is not explicitly represented in
537 DWARF with a namespace entry (thus mirroring the situation
538 in \addtoindex{C++} source).  
539 Global items may be simply declared with no
540 reference to a namespace.}
541
542 \textit{The \addtoindex{C++} 
543 compilation unit specific ``unnamed namespace'' may
544 \addtoindexx{namespace (C++)!unnamed}
545 \addtoindexx{unnamed namespace|see {namespace (C++), unnamed}}
546 be represented by a namespace entry with no name attribute in
547 the original namespace declaration entry (and therefore no name
548 attribute in any namespace extension entry of this namespace).
549 }
550
551 \textit{A compiler emitting namespace information may choose to
552 explicitly represent namespace extensions, or to represent the
553 final namespace declaration of a compilation unit; this is a
554 quality\dash of\dash implementation issue and no specific requirements
555 are given here. If only the final namespace is represented,
556 \addtoindexx{namespace (C++)!using declaration}
557 it is impossible for a debugger to interpret using declaration
558 references in exactly the manner defined by the 
559 \addtoindex{C++} language.
560 }
561
562 \textit{Emitting all namespace declaration information in all
563 compilation units can result in a significant increase in the
564 size of the debug information and significant duplication of
565 information across compilation units. 
566 The \addtoindex{C++} namespace std,
567 for example, 
568 \addtoindexx{namespace (C++)!std}
569 is large and will probably be referenced in
570 every \addtoindex{C++} compilation unit.
571 }
572
573 \textit{For a \addtoindex{C++} namespace example, 
574 see Appendix \refersec{app:namespaceexample}.
575 }
576
577
578
579 \subsection{Imported (or Renamed) Declaration Entries} 
580 \label{chap:importedorrenameddeclarationentries}
581 \textit{Some languages support the concept of importing into or making
582 accessible in a given unit declarations made in a different
583 module or scope. An imported declaration may sometimes be
584 given another name.
585 }
586
587 An 
588 imported declaration is represented by one or
589 \addtoindexx{imported declaration entry}
590 more debugging information entries with the 
591 tag \livetarg{chap:DWTAGimporteddeclaration}{DW\_TAG\_imported\_declaration}. 
592 When 
593 \hypertarget{chap:DWATimportimporteddeclaration}
594 an overloaded entity
595 is imported, there is one imported declaration entry for
596 each overloading. 
597 \addtoindexx{import attribute}
598 Each imported declaration entry has a
599 \livelink{chap:DWATimport}{DW\_AT\_import} attribute,
600 whose value is a \livelink{chap:classreference}{reference} to the
601 debugging information entry representing the declaration that
602 is being imported.
603
604 An imported declaration may also have a 
605 \livelink{chap:DWATname}{DW\_AT\_name}
606 attribute
607 \addtoindexx{name attribute}
608 whose value is a null\dash terminated string containing the
609 name, as it appears in the source program, by which the
610 imported entity is to be known in the context of the imported
611 declaration entry (which may be different than the name of
612 the entity being imported). If no name is present, then the
613 name by which the entity is to be known is the same as the
614 name of the entity being imported.
615
616 An imported declaration entry with a name attribute may be
617 used as a general means to rename or provide an alias for
618 \addtoindexx{alias declaration|see{imported declaration entry}}
619 an entity, regardless of the context in which the importing
620 declaration or the imported entity occurs.
621
622 \textit{A \addtoindex{C++} namespace alias may be represented by an imported
623 \hypertarget{chap:DWATimportnamespacealias}
624 declaration entry 
625 \addtoindexx{namespace (C++)!alias}
626 with a name attribute whose value is
627 a null\dash terminated string containing the alias name as it
628 appears in the source program and an import attribute whose
629 value is a \livelink{chap:classreference}{reference} to the applicable original namespace or
630 namespace extension entry.
631 }
632
633 \textit{A \addtoindex{C++} using declaration may be represented by one or more
634 \hypertarget{chap:DWATimportnamespaceusingdeclaration}
635 imported 
636 \addtoindexx{namespace (C++)!using declaration}
637 declaration entries.  When the using declaration
638 refers to an overloaded function, there is one imported
639 declaration entry corresponding to each overloading. Each
640 imported declaration entry has no name attribute but it does
641 have an import attribute that refers to the entry for the
642 entity being imported. (\addtoindex{C++} 
643 provides no means to ``rename''
644 an imported entity, other than a namespace).
645 }
646
647 \textit{A \addtoindex{Fortran} use statement 
648 \addtoindexx{Fortran!use statement}
649 \addtoindexx{use statement|see {Fortran, use statement}}
650 with an ``only list'' may be
651 represented by a series of imported declaration entries,
652 one (or more) for each entity that is imported. An entity
653 \addtoindexx{renamed declaration|see{imported declaration entry}}
654 that is renamed in the importing context may be represented
655 by an imported declaration entry with a name attribute that
656 specifies the new local name.
657 }
658
659 \subsection{Imported Module Entries}
660 \label{chap:importedmoduleentries}
661
662 \textit{Some languages support the concept of importing into or making
663 accessible in a given unit all of the declarations contained
664 within a separate module or namespace.
665 }
666
667 An imported module declaration is represented by a debugging
668 information entry with 
669 \addtoindexx{imported module attribute}
670 the 
671 \addtoindexx{imported module entry}
672 tag \livetarg{chap:DWTAGimportedmodule}{DW\_TAG\_imported\_module}.
673 An
674 imported module entry contains a 
675 \livelink{chap:DWATimport}{DW\_AT\_import} attribute
676 \addtoindexx{import attribute}
677 whose value is a \livelink{chap:classreference}{reference} 
678 to the module or namespace entry
679 containing the definition and/or declaration entries for
680 the entities that are to be imported into the context of the
681 imported module entry.
682
683 An imported module declaration may own a set of imported
684 declaration entries, each of which refers to an entry in the
685 module whose corresponding entity is to be known in the context
686 of the imported module declaration by a name other than its
687 name in that module. Any entity in the module that is not
688 renamed in this way is known in the context of the imported
689 module entry by the same name as it is declared in the module.
690
691 \textit{A \addtoindex{C++} using directive
692 \addtoindexx{namespace (C++)!using directive}
693 \addtoindexx{using directive|see {namespace (C++), using directive}} 
694 may be represented by an imported module
695 \hypertarget{chap:DWATimportnamespaceusingdirective}
696 entry, with an import attribute referring to the namespace
697 entry of the appropriate extension of the namespace (which
698 might be the original namespace entry) and no owned entries.
699 }
700
701 \textit{A \addtoindex{Fortran} use statement 
702 \addtoindexx{Fortran!use statement}
703 with a \doublequote{rename list} may be
704 represented by an imported module entry with an import
705 attribute referring to the module and owned entries
706 corresponding to those entities that are renamed as part of
707 being imported.
708 }
709
710 \textit{A \addtoindex{Fortran} use statement
711 \addtoindexx{Fortran!use statement}
712 with neither a \doublequote{rename list} nor
713 an \doublequote{only list} may be represented by an imported module
714 entry with an import attribute referring to the module and
715 no owned child entries.
716 }
717
718 \textit{A use statement with an \doublequote{only list} is represented by a
719 series of individual imported declaration entries as described
720 in Section \refersec{chap:importedorrenameddeclarationentries}.
721 }
722
723 \textit{A \addtoindex{Fortran} use statement for an entity in a module that is
724 \addtoindexx{Fortran!use statement}
725 itself imported by a use statement without an explicit mention
726 may be represented by an imported declaration entry that refers
727 to the original debugging information entry. For example, given
728 }
729
730 \begin{lstlisting}
731 module A
732 integer X, Y, Z
733 end module
734
735 module B
736 use A
737 end module
738
739 module C
740 use B, only Q => X
741 end module
742 \end{lstlisting}
743
744 \textit{the imported declaration entry for Q within module C refers
745 directly to the variable declaration entry for X in module A
746 because there is no explicit representation for X in module B.
747 }
748
749 \textit{A similar situation arises for a \addtoindex{C++} using declaration
750 \addtoindexx{namespace (C++)!using declaration}
751 \addtoindexx{using declaration|see {namespace (C++), using declaration}}
752 that imports an entity in terms of a namespace alias. See 
753 Appendix  \refersec{app:namespaceexample}
754 for an example.
755 }
756
757 \section{Subroutine and Entry Point Entries}
758 \label{chap:subroutineandentrypointentries}
759
760 The following tags exist to describe 
761 debugging information entries 
762 \addtoindexx{function entry|see{subroutine entry}}
763 for 
764 \addtoindexx{subroutine entry}
765 subroutines 
766 \addtoindexx{subprogram entry}
767 and entry
768 % FIXME: is entry point entry the right index 'entry'?
769 \addtoindexx{entry point entry}
770 points:
771
772 \begin{tabular}{lp{9.0cm}}
773 \livetarg{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} & A subroutine or function \\
774 \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine} & A particular inlined 
775 \addtoindexx{inlined subprogram entry}
776 instance of a subroutine or function \\
777 \livetarg{chap:DWTAGentrypoint}{DW\_TAG\_entry\_point} & An alternate entry point \\
778 \end{tabular}
779
780 \subsection{General Subroutine and Entry Point Information}
781 \label{chap:generalsubroutineandentrypointinformation}
782 The subroutine or entry point entry has a \livelink{chap:DWATname}{DW\_AT\_name} 
783 attribute whose value is a null-terminated string containing the 
784 subroutine or entry point name as it appears in the source program.
785 It may also have a \livelink{chap:DWATlinkagename}{DW\_AT\_linkage\_name} attribute as
786 described in Section \refersec{chap:linkagenames}.
787
788 If the name of the subroutine described by an entry with the
789 \addtoindexx{subprogram entry}
790 tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
791 is visible outside of its containing
792 \hypertarget{chap:DWATexternalexternalsubroutine}
793 compilation unit, that entry has 
794 \addtoindexx{external attribute}
795
796 \livelink{chap:DWATexternal}{DW\_AT\_external} attribute,
797 which is a \livelink{chap:classflag}{flag}.
798
799 \textit{Additional attributes for functions that are members of a
800 class or structure are described in 
801 Section \refersec{chap:memberfunctionentries}.
802 }
803
804
805 \hypertarget{chap:DWATmainsubprogrammainorstartingsubprogram}
806 subroutine entry 
807 may contain a 
808 \livelink{chap:DWATmainsubprogram}{DW\_AT\_main\_subprogram}
809 attribute 
810 \addtoindexx{main subprogram attribute}
811 which is 
812 a \livelink{chap:classflag}{flag} whose presence indicates that the
813 subroutine has been identified as the starting function of
814 the program.  If more than one subprogram contains this 
815 \nolink{flag},
816 any one of them may be the starting subroutine of the program.
817
818 \textit{\addtoindex{Fortran} has a \addtoindex{PROGRAM statement} 
819 which is used to specify
820 and provide a user\dash supplied name for the main subroutine of
821 a program.
822 }
823
824 \textit{A common debugger feature is to allow the debugger user to call
825 a subroutine within the subject program. In certain cases,
826 however, the generated code for a subroutine will not obey
827 the standard calling conventions for the target architecture
828 and will therefore not be safe to call from within a debugger.
829 }
830
831 A subroutine entry may 
832 \hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}
833 contain a 
834 \livelink{chap:DWATcallingconvention}{DW\_AT\_calling\_convention}
835 attribute, whose value is an 
836 \livelink{chap:classconstant}{integer constant}. The set of
837 calling convention codes is given in 
838 Table \refersec{tab:callingconventioncodes}.
839
840 \begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
841 \addtoindex{DW\_CC\_normal}        \\
842 \addtoindex{DW\_CC\_program}       \\
843 \addtoindex{DW\_CC\_nocall}        \\
844 \end{simplenametable}
845
846 If this attribute is not present, or its value is the constant
847 \livetarg{chap:DWCCnormal}{DW\_CC\_normal}, then the subroutine may be safely called by
848 obeying the ``standard'' calling conventions of the target
849 architecture. If the value of the calling convention attribute
850 is the constant \livetarg{chap:DWCCnocall}{DW\_CC\_nocall}, the subroutine does not obey
851 standard calling conventions, and it may not be safe for the
852 debugger to call this subroutine.
853
854 If the semantics of the language of the compilation unit
855 containing the subroutine entry distinguishes between ordinary
856 subroutines and subroutines that can serve as the ``main
857 program,'' that is, subroutines that cannot be called
858 directly according to the ordinary calling conventions,
859 then the debugging information entry for such a subroutine
860 may have a calling convention attribute whose value is the
861 constant \livetarg{chap:DWCCprogram}{DW\_CC\_program}.
862
863 \textit{The \livelink{chap:DWCCprogram}{DW\_CC\_program} 
864 value is intended to support \addtoindex{Fortran} main
865 \addtoindexx{Fortran!main program}
866 programs which in some implementations may not be callable
867 or which must be invoked in a special way. It is not intended
868 as a way of finding the entry address for the program.
869 }
870
871 \textit{In \addtoindex{C}
872 there is a difference between the types of functions
873 declared using function prototype style declarations and
874 those declared using non\dash prototype declarations.
875 }
876
877 A subroutine entry declared with a function prototype style
878 declaration may have 
879 \addtoindexx{prototyped attribute}
880
881 \livelink{chap:DWATprototyped}{DW\_AT\_prototyped} attribute, which is
882 a \livelink{chap:classflag}{flag}.
883
884 \textit{The \addtoindex{Fortran} 
885 language allows the keywords \texttt{elemental}, \texttt{pure}
886 and \texttt{recursive} to be included as part of the declaration of
887 a subroutine; these attributes reflect that usage. These
888 attributes are not relevant for languages that do not support
889 similar keywords or syntax. In particular, the \livelink{chap:DWATrecursive}{DW\_AT\_recursive}
890 attribute is neither needed nor appropriate in languages such
891 as \addtoindex{C} 
892 where functions support recursion by default.
893 }
894
895 A subprogram entry 
896 \hypertarget{chap:DWATelementalelementalpropertyofasubroutine}
897 may have 
898 \addtoindexx{elemental attribute}
899
900 \livelink{chap:DWATelemental}{DW\_AT\_elemental} attribute, which
901 is a \livelink{chap:classflag}{flag}. 
902 The attribute indicates whether the subroutine
903 or entry point was declared with the ``elemental'' keyword
904 or property.
905
906
907 \hypertarget{chap:DWATpurepurepropertyofasubroutine}
908 subprogram entry may have 
909 \addtoindexx{pure attribute}
910
911 \livelink{chap:DWATpure}{DW\_AT\_pure} attribute, which is
912 a \livelink{chap:classflag}{flag}. 
913 The attribute indicates whether the subroutine was
914 declared with the ``pure'' keyword or property.
915
916
917 \hypertarget{chap:DWATrecursiverecursivepropertyofasubroutine}
918 subprogram entry may have a 
919 \livelink{chap:DWATrecursive}{DW\_AT\_recursive} attribute, which
920 is a \livelink{chap:classflag}{flag}. 
921 The attribute indicates whether the subroutine
922 or entry point was declared with the ``recursive'' keyword
923 or property.
924
925
926
927 \subsection{Subroutine and Entry Point Return Types}
928 \label{chap:subroutineandentrypointreturntypes}
929
930 If 
931 \hypertarget{chap:DWATtypetypeofsubroutinereturn}
932 the subroutine or entry point 
933 \addtoindexx{return type of subroutine}
934 is a function that returns a
935 value, then its debugging information entry has 
936 \addtoindexx{type attribute}
937 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute 
938 to denote the type returned by that function.
939
940 \textit{Debugging information entries for 
941 \addtoindex{C} void functions should
942 not have an attribute for the return type.  }
943
944
945 \subsection{Subroutine and Entry Point Locations}
946 \label{chap:subroutineandentrypointlocations}
947
948 A subroutine entry may have either a \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} and
949 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} pair of attributes or a \livelink{chap:DWATranges}{DW\_AT\_ranges} attribute
950 \addtoindexx{ranges attribute}
951 whose 
952 \addtoindexx{high PC attribute}
953 values 
954 \addtoindexx{low PC attribute}
955 encode the contiguous or non\dash contiguous address
956 ranges, respectively, of the machine instructions generated
957 for the subroutine (see 
958 Section \refersec{chap:codeaddressesandranges}).
959
960
961 \hypertarget{chap:DWATentrypcentryaddressofsubprogram}
962 subroutine entry may also have 
963 \addtoindexx{entry pc attribute!for subroutine}
964
965 \livelink{chap:DWATentrypc}{DW\_AT\_entry\_pc} attribute
966 whose value is the address of the first executable instruction
967 of the subroutine (see 
968 Section \refersec{chap:entryaddress}).
969
970 An entry point has a \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} attribute whose value is the
971 relocated address of the first machine instruction generated
972 for the entry point.
973
974 \textit{While the 
975 \livelink{chap:DWATentrypc}{DW\_AT\_entry\_pc} attribute 
976 \addtoindexx{entry pc attribute!for subroutine}
977 might 
978 also seem appropriate
979 for this purpose, historically the 
980 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} attribute
981 was used before the 
982 \livelink{chap:DWATentrypc}{DW\_AT\_entry\_pc} was introduced (in
983 \addtoindex{DWARF Version 3}). 
984 There is insufficient reason to change this.}
985
986
987 Subroutines 
988 and 
989 entry
990 \addtoindexx{address class!attribute}
991 points 
992 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}
993 may also have 
994 \livelink{chap:DWATsegment}{DW\_AT\_segment} 
995 and
996 \livelink{chap:DWATaddressclass}{DW\_AT\_address\_class} attributes,
997 as appropriate, to specify
998 which segments the code for the subroutine resides in and
999 the addressing mode to be used in calling that subroutine.
1000
1001 A subroutine entry representing a subroutine declaration
1002 that is not also a definition does not have code address or
1003 range attributes.
1004
1005
1006 \subsection{Declarations Owned by Subroutines and Entry Points} 
1007 \label{chap:declarationsownedbysubroutinesandentrypoints}
1008
1009 The declarations enclosed by a subroutine or entry point are
1010 represented by debugging information entries that are owned
1011 by the subroutine or entry point entry. Entries representing
1012 \addtoindexx{formal parameter}
1013 the formal parameters of the subroutine or entry point appear
1014 in the same order as the corresponding declarations in the
1015 source program.
1016
1017 \needlines{5}
1018 \textit{There is no ordering requirement for entries for declarations
1019 that are children of subroutine or entry point entries but
1020 that do not represent formal parameters. The formal parameter
1021 entries may be interspersed with other entries used by formal
1022 parameter entries, such as type entries.}
1023
1024 The unspecified parameters of a variable parameter list are
1025 represented by a debugging information entry\addtoindexx{unspecified parameters entry}
1026 with the tag
1027 \livetarg{chap:DWTAGunspecifiedparameters}{DW\_TAG\_unspecified\_parameters}.
1028
1029 The entry for a subroutine that includes a
1030 \addtoindex{Fortran}
1031 \addtoindexx{Fortran!common block}
1032 \livelink{chap:fortrancommonblock}{common} 
1033 \livelink{chap:commonblockentry}{block}
1034 \addtoindexx{common block|see{Fortran common block}}
1035 has a child entry with the 
1036 tag \livetarg{chap:DWTAGcommoninclusion}{DW\_TAG\_common\_inclusion}. 
1037 The
1038 \hypertarget{chap:commonreferencecommonblockusage}
1039 common inclusion entry has a 
1040 \livelink{chap:DWATcommonreference}{DW\_AT\_common\_reference} attribute
1041 whose value is a \livelink{chap:classreference}{reference} 
1042 to the debugging information entry
1043 for the common \nolink{block} being included 
1044 (see Section \refersec{chap:commonblockentries}).
1045
1046 \subsection{Low-Level Information}
1047 \label{chap:lowlevelinformation}
1048
1049
1050 \hypertarget{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}
1051 subroutine or entry point entry may have 
1052 \addtoindexx{return address attribute}
1053
1054 \livelink{chap:DWATreturnaddr}{DW\_AT\_return\_addr}
1055 attribute, whose value is a location description. The location
1056 calculated is the place where the return address for the
1057 subroutine or entry point is stored.
1058
1059
1060 \hypertarget{chap:DWATframebasesubroutineframebaseaddress}
1061 subroutine or entry point entry may also have 
1062 \addtoindexx{frame base attribute}
1063 a
1064 \livelink{chap:DWATframebase}{DW\_AT\_frame\_base} attribute, whose value is a location
1065 description that computes the \doublequote{frame base} for the
1066 subroutine or entry point. If the location description is
1067 a simple register location description, the given register
1068 contains the frame base address. If the location description is
1069 a DWARF expression, the result of evaluating that expression
1070 is the frame base address. Finally, for a 
1071 \addtoindex{location list},
1072 this interpretation applies to each location description
1073 contained in the list of \addtoindex{location list} entries.
1074
1075 \textit{The use of one of the \livelink{chap:DWOPreg}{DW\_OP\_reg}~\textless~n~\textgreater 
1076 operations in this
1077 context is equivalent to using 
1078 \livelink{chap:DWOPbreg}{DW\_OP\_breg}~\textless~n~\textgreater(0) 
1079 but more
1080 compact. However, these are not equivalent in general.}
1081
1082 \needlines{5}
1083 \textit{The frame base for a procedure is typically an address fixed
1084 relative to the first unit of storage allocated for the
1085 procedure\textquoteright s stack frame. The \livelink{chap:DWATframebase}{DW\_AT\_frame\_base} attribute
1086 can be used in several ways:}
1087 \begin{enumerate}[1. ]
1088 \item \textit{In procedures that need 
1089 \addtoindexx{location list}
1090 location lists to locate local
1091 variables, the \livelink{chap:DWATframebase}{DW\_AT\_frame\_base} can hold the needed location
1092 list, while all variables\textquoteright\  location descriptions can be
1093 simpler ones involving the frame base.}
1094
1095 \item \textit{It can be used in resolving ``up\dash level'' addressing
1096 within nested routines. 
1097 (See also \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}, below)}
1098 %The -See also- here is ok, the DW\_AT should be
1099 %a hyperref to the def itself, which is earlier in this document.
1100 \end{enumerate}
1101
1102 \needlines{5}
1103 \textit{Some languages support nested subroutines. In such languages,
1104 it is possible to reference the local variables of an
1105 outer subroutine from within an inner subroutine. The
1106 \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link} and \livelink{chap:DWATframebase}{DW\_AT\_frame\_base} attributes allow
1107 debuggers to support this same kind of referencing.}
1108
1109 If 
1110 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}
1111
1112 \addtoindexx{address!uplevel|see {static link attribute}}
1113 \addtoindexx{uplevel address|see {static link attribute}}
1114 subroutine or entry point is nested, it may have a
1115 \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link}
1116 attribute, whose value is a location
1117 description that computes the frame base of the relevant
1118 instance of the subroutine that immediately encloses the
1119 subroutine or entry point.
1120
1121 In the context of supporting nested subroutines, the
1122 \livelink{chap:DWATframebase}{DW\_AT\_frame\_base} attribute value should obey the following
1123 constraints:
1124
1125 \begin{enumerate}[1. ]
1126 \item It should compute a value that does not change during the
1127 life of the procedure, and
1128
1129 \item The computed value should be unique among instances of
1130 the same subroutine. (For typical \livelink{chap:DWATframebase}{DW\_AT\_frame\_base} use, this
1131 means that a recursive subroutine\textquoteright s stack frame must have
1132 non\dash zero size.)
1133 \end{enumerate}
1134
1135 \textit{If a debugger is attempting to resolve an up\dash level reference
1136 to a variable, it uses the nesting structure of DWARF to
1137 determine which subroutine is the lexical parent and the
1138 \livelink{chap:DWATstaticlink}{DW\_AT\_static\_link} value to identify the appropriate active
1139 frame of the parent. It can then attempt to find the reference
1140 within the context of the parent.}
1141
1142
1143
1144 \subsection{Types Thrown by Exceptions}
1145 \label{chap:typesthrownbyexceptions}
1146
1147 \textit{In \addtoindex{C++} a subroutine may declare a set of types which
1148 it may validly throw.}
1149
1150 If a subroutine explicitly declares that it may throw
1151 \addtoindexx{exception thrown|see{thrown type entry}}
1152 an 
1153 \addtoindexx{thrown exception|see{thrown type entry}}
1154 exception of one or more types, each such type is
1155 represented by a debugging information entry with 
1156 \addtoindexx{thrown type entry}
1157 the tag
1158 \livetarg{chap:DWTAGthrowntype}{DW\_TAG\_thrown\_type}.  
1159 Each such entry is a child of the entry
1160 representing the subroutine that may throw this type. Each
1161 thrown type entry contains 
1162 \addtoindexx{type attribute}
1163 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute, whose
1164 value is a \livelink{chap:classreference}{reference} 
1165 to an entry describing the type of the
1166 exception that may be thrown.
1167
1168 \subsection{Function Template Instantiations}
1169 \label{chap:functiontemplateinstantiations}
1170
1171 \textit{In \addtoindex{C++}, a function template is a generic definition of
1172 a function that is instantiated differently for calls with
1173 values of different types. DWARF does not represent the generic
1174 template definition, but does represent each instantiation.}
1175
1176 A \addtoindex{template instantiation} is represented by a debugging
1177 information entry with the 
1178 \addtoindexx{subprogram entry!use for template instantiation}
1179 tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}. 
1180 With four
1181 exceptions, such an entry will contain the same attributes and
1182 will have the same types of child entries as would an entry
1183 for a subroutine defined explicitly using the instantiation
1184 types. The exceptions are:
1185
1186 \begin{enumerate}[1. ]
1187 \item Each formal parameterized type declaration appearing in the
1188 template definition is represented by a debugging information
1189 entry with the 
1190 \addtoindexx{template type parameter entry}
1191 tag \livetarg{chap:DWTAGtemplatetypeparameter}{DW\_TAG\_template\_type\_parameter}. 
1192 Each
1193 such entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute, 
1194 \addtoindexx{name attribute}
1195 whose value is a
1196 null\dash terminated string containing the name of the formal
1197 type parameter as it appears in the source program. The
1198 \addtoindexx{formal type parameter|see{template type parameter entry}}
1199 template type parameter entry also has 
1200 \addtoindexx{type attribute}
1201 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute
1202 describing the actual type by which the formal is replaced
1203 for this instantiation.
1204
1205 \item The subprogram entry and each of its child entries reference
1206 a template type parameter entry in any circumstance where
1207 the template definition referenced a formal parameterized type.
1208
1209 \item If the compiler has generated a special compilation unit
1210 to hold the template instantiation and that compilation unit
1211 has a different name from the compilation unit containing
1212 the template definition, the name attribute for the debugging
1213 information entry representing that compilation unit is empty
1214 or omitted.
1215
1216 \item If the subprogram entry representing the template
1217 instantiation or any of its child entries contain declaration
1218 coordinate attributes, those attributes refer to the source
1219 for the template definition, not to any source generated
1220 artificially by the compiler for this instantiation.
1221 \end{enumerate}
1222
1223
1224
1225 \subsection{Inlinable and Inlined Subroutines}
1226 A declaration or a definition of an inlinable subroutine
1227 is represented by a debugging information entry with the
1228 tag 
1229 \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}.
1230 The entry for a 
1231 \addtoindexx{subprogram entry!use in inlined subprogram}
1232 subroutine that is
1233 \hypertarget{chap:DWATinlineinlinedsubroutine}
1234 explicitly declared to be available for inline expansion or
1235 that was expanded inline implicitly by the compiler has 
1236 \addtoindexx{inline attribute}
1237 a
1238 \livelink{chap:DWATinline}{DW\_AT\_inline} attribute whose value is an 
1239 \livelink{chap:classconstant}{integer constant}. The
1240 set of values for the \livelink{chap:DWATinline}{DW\_AT\_inline} attribute is given in
1241 Table \refersec{tab:inlinecodes}.
1242
1243 \begin{table}[here]
1244 \centering
1245 \caption{Inline codes}
1246 \label{tab:inlinecodes}
1247 \begin{tabular}{l|p{8cm}}
1248 \hline
1249 Name&Meaning\\ \hline
1250 \livetarg{chap:DWINLnotinlined}{DW\_INL\_not\_inlined} & Not declared inline nor inlined by the
1251   \mbox{compiler} (equivalent to the absence of the
1252   containing \livelink{chap:DWATinline}{DW\_AT\_inline} attribute) \\
1253 \livetarg{chap:DWINLinlined}{DW\_INL\_inlined} & Not declared inline but inlined by the \mbox{compiler} \\
1254 \livetarg{chap:DWINLdeclarednotinlined}{DW\_INL\_declared\_not\_inlined} & Declared inline but 
1255   not inlined by the \mbox{compiler} \\
1256 \livetarg{chap:DWINLdeclaredinlined}{DW\_INL\_declared\_inlined} & Declared inline and inlined by the 
1257   \mbox{compiler} \\
1258 \hline
1259 \end{tabular}
1260 \end{table}
1261
1262 \textit{In \addtoindex{C++}, a function or a constructor declared with
1263 \addttindex{constexpr} is implicitly declared inline. The abstract inline
1264 instance (see below) is represented by a debugging information
1265 entry with the tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}. Such an entry has a
1266 \livelink{chap:DWATinline}{DW\_AT\_inline} attribute whose value is \livelink{chap:DWINLinlined}{DW\_INL\_inlined}.}
1267
1268
1269 \subsubsection{Abstract Instances}
1270 \label{chap:abstractinstances}
1271 Any debugging information entry that is owned (either
1272 \hypertarget{chap:DWATinlineabstracttinstance}
1273 directly or indirectly) by a debugging information entry
1274 that contains the 
1275 \livelink{chap:DWATinline}{DW\_AT\_inline} attribute is referred to
1276 \addtoindexx{abstract instance!entry}
1277 as an ``abstract instance entry.'' 
1278 Any subroutine entry
1279 that contains 
1280 \addtoindexx{inline attribute}
1281 a \livelink{chap:DWATinline}{DW\_AT\_inline} attribute whose value is other
1282 than \livelink{chap:DWINLnotinlined}{DW\_INL\_not\_inlined}
1283 is known as 
1284 \addtoindexx{abstract instance!root}
1285 an ``abstract instance root.'' 
1286 Any set of abstract instance entries that are all
1287 children (either directly or indirectly) of some abstract
1288 instance root, together with the root itself, is known as
1289 \addtoindexx{abstract instance!tree}
1290 an ``abstract instance tree.'' However, in the case where
1291 an abstract instance tree is nested within another abstract
1292 instance tree, the entries in the 
1293 \addtoindex{nested abstract instance}
1294 tree are not considered to be entries in the outer abstract
1295 instance tree.
1296
1297 Each abstract instance root is either part of a larger
1298 \addtoindexx{abstract instance!root}
1299 tree (which gives a context for the root) or 
1300 \addtoindexx{specification attribute}
1301 uses
1302 \livelink{chap:DWATspecification}{DW\_AT\_specification} 
1303 to refer to the declaration in context.
1304
1305 \textit{For example, in \addtoindex{C++} the context might be a namespace
1306 declaration or a class declaration.}
1307
1308 \textit{Abstract instance trees are defined so that no entry is part
1309 of more than one abstract instance tree. This simplifies the
1310 following descriptions.}
1311
1312 A debugging information entry that is a member of an abstract
1313 instance tree should not contain any attributes which describe
1314 aspects of the subroutine which vary between distinct inlined
1315 expansions or distinct out\dash of\dash line expansions. For example,
1316 \addtoindexx{entry pc attribute!and abstract instance}
1317 the \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc},
1318 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc}, 
1319 \livelink{chap:DWATranges}{DW\_AT\_ranges}, 
1320 \livelink{chap:DWATentrypc}{DW\_AT\_entry\_pc}, 
1321 \livelink{chap:DWATlocation}{DW\_AT\_location},
1322 \livelink{chap:DWATreturnaddr}{DW\_AT\_return\_addr}, 
1323 \livelink{chap:DWATstartscope}{DW\_AT\_start\_scope}, 
1324 and 
1325 \livelink{chap:DWATsegment}{DW\_AT\_segment}
1326 attributes 
1327 \addtoindexx{location attribute!and abstract instance}
1328 typically 
1329 \addtoindexx{ranges attribute!and abstract instance}
1330 should 
1331 \addtoindexx{high PC attribute!and abstract instance}
1332 be 
1333 \addtoindexx{low PC attribute!and abstract instance}
1334 omitted; 
1335 \addtoindexx{segment attribute!and abstract instance}
1336 however, 
1337 \addtoindexx{return address attribute!and abstract instance}
1338 this 
1339 \addtoindexx{segment attribute!and abstract instance}
1340 list
1341 \addtoindexx{start scope attribute!and abstract instance}
1342 is not exhaustive.
1343
1344 \needlines{5}
1345 \textit{It would not make sense normally to put these attributes into
1346 abstract instance entries since such entries do not represent
1347 actual (concrete) instances and thus do not actually exist at
1348 run\dash time.  However, 
1349 see Appendix \refersec{app:inlineouteronenormalinner} 
1350 for a contrary example.}
1351
1352 The rules for the relative location of entries belonging to
1353 abstract instance trees are exactly the same as for other
1354 similar types of entries that are not abstract. Specifically,
1355 the rule that requires that an entry representing a declaration
1356 be a direct child of the entry representing the scope of the
1357 declaration applies equally to both abstract and non\dash abstract
1358 entries. Also, the ordering rules for formal parameter entries,
1359 member entries, and so on, all apply regardless of whether
1360 or not a given entry is abstract.
1361
1362 \subsubsection{Concrete Inlined Instances}
1363 \label{chap:concreteinlinedinstances}
1364
1365 Each inline expansion of a subroutine is represented
1366 by a debugging information entry with the 
1367 tag \livetarg{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}. 
1368 Each such entry should be a direct
1369 child of the entry that represents the scope within which
1370 the inlining occurs.
1371
1372 Each inlined subroutine entry may have either a 
1373 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc}
1374 and \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} pair 
1375 of 
1376 \addtoindexx{high PC attribute}
1377 attributes 
1378 \addtoindexx{low PC attribute}
1379 or 
1380 \addtoindexx{ranges attribute}
1381
1382 \livelink{chap:DWATranges}{DW\_AT\_ranges}
1383 attribute whose values encode the contiguous or non\dash contiguous
1384 address ranges, respectively, of the machine instructions
1385 generated for the inlined subroutine (see 
1386 Section \refersec{chap:codeaddressesandranges}). 
1387 An
1388 \hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}
1389 inlined subroutine entry may 
1390 \addtoindexx{inlined subprogram entry!in concrete instance}
1391 also 
1392 \addtoindexx{inlined subprogram entry}
1393 contain 
1394 \addtoindexx{entry pc attribute!for inlined subprogram}
1395
1396 \livelink{chap:DWATentrypc}{DW\_AT\_entry\_pc}
1397 attribute, representing the first executable instruction of
1398 the inline expansion (see 
1399 Section \refersec{chap:entryaddress}).
1400
1401 % Positions of the 3 targets here is a bit arbitrary.
1402 An inlined 
1403 \hypertarget{chap:DWATcalllinelinenumberofinlinedsubroutinecall}
1404 subroutine 
1405 \hypertarget{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}
1406 entry 
1407 \hypertarget{chap:DWATcallfilefilecontaininginlinedsubroutinecall}
1408 may also have \livelink{chap:DWATcallfile}{DW\_AT\_call\_file},
1409 \livelink{chap:DWATcallline}{DW\_AT\_call\_line} and \livelink{chap:DWATcallcolumn}{DW\_AT\_call\_column} attributes, 
1410 each of whose
1411 value is an \livelink{chap:classconstant}{integer constant}. 
1412 These attributes represent the
1413 source file, source line number, and source column number,
1414 respectively, of the first character of the statement or
1415 expression that caused the inline expansion. The call file,
1416 call line, and call column attributes are interpreted in
1417 the same way as the declaration file, declaration line, and
1418 declaration column attributes, respectively (see 
1419 Section \refersec{chap:declarationcoordinates}).
1420
1421 \textit{The call file, call line and call column coordinates do not
1422 describe the coordinates of the subroutine declaration that
1423 was inlined, rather they describe the coordinates of the call.
1424 }
1425
1426 An inlined subroutine entry 
1427 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}
1428 may have a 
1429 \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr}
1430 attribute, which is a \livelink{chap:classflag}{flag} 
1431 whose presence indicates that the
1432 subroutine has been evaluated as a compile\dash time constant. Such
1433 an entry may also have a \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value} attribute,
1434 whose value may be of any form that is appropriate for the
1435 representation of the subroutine's return value. The value of
1436 this attribute is the actual return value of the subroutine,
1437 represented as it would be on the target architecture.
1438
1439 \textit{In \addtoindex{C++}, if a function or a constructor declared with 
1440 \addttindex{constexpr}
1441 is called with constant expressions, then the corresponding
1442 concrete inlined instance has a 
1443 \livelink{chap:DWATconstexpr}{DW\_AT\_const\_expr} attribute,
1444 as well as a \livelink{chap:DWATconstvalue}{DW\_AT\_const\_value} attribute whose value represents
1445 the actual return value of the concrete inlined instance.}
1446
1447 Any debugging information entry that is owned (either
1448 directly or indirectly) by a debugging information entry
1449 with the tag \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine} is referred to as a
1450 ``concrete inlined instance entry.'' Any entry that has
1451 the tag 
1452 \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine} 
1453 is known as a ``concrete inlined instance root.'' 
1454 Any set of concrete inlined instance
1455 entries that are all children (either directly or indirectly)
1456 of some concrete inlined instance root, together with the root
1457 itself, is known as a ``concrete inlined instance tree.''
1458 However, in the case where a concrete inlined instance tree
1459 is nested within another concrete instance tree, the entries
1460 in the \addtoindex{nested concrete inline instance} tree 
1461 are not considered to
1462 be entries in the outer concrete instance tree.
1463
1464 \textit{Concrete inlined instance trees are defined so that no entry
1465 is part of more than one concrete inlined instance tree. This
1466 simplifies later descriptions.}
1467
1468 Each concrete inlined instance tree is uniquely associated
1469 with one (and only one) abstract instance tree.
1470
1471 \textit{Note, however, that the reverse is not true. Any given abstract
1472 instance tree may be associated with several different concrete
1473 inlined instance trees, or may even be associated with zero
1474 concrete inlined instance trees.}
1475
1476 Concrete inlined instance entries may omit attributes that
1477 are not specific to the concrete instance (but present in
1478 the abstract instance) and need include only attributes that
1479 are specific to the concrete instance (but omitted in the
1480 abstract instance). In place of these omitted attributes, each
1481 \hypertarget{chap:DWATabstractorigininlineinstance}
1482 concrete inlined instance entry 
1483 \addtoindexx{abstract origin attribute}
1484 has a 
1485 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}
1486 attribute that may be used to obtain the missing information
1487 (indirectly) from the associated abstract instance entry. The
1488 value of the abstract origin attribute is a reference to the
1489 associated abstract instance entry.
1490
1491 If an entry within a concrete inlined instance tree contains
1492 attributes describing the 
1493 \addtoindexx{declaration coordinates!in concrete instance}
1494 \livelink{chap:declarationcoordinates}{declaration coordinates} 
1495 of that entry, then those attributes should refer to the file, line
1496 and column of the original declaration of the subroutine,
1497 not to the point at which it was inlined. As a consequence,
1498 they may usually be omitted from any entry that has an abstract
1499 origin attribute.
1500
1501 \needlines{4}
1502 For each pair of entries that are associated via a
1503 \addtoindexx{abstract origin attribute}
1504 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin} attribute, both members of the pair
1505 have the same tag. So, for example, an entry with the tag
1506 \livelink{chap:DWTAGvariable}{DW\_TAG\_variable} can only be associated with another entry
1507 that also has the tag \livelink{chap:DWTAGvariable}{DW\_TAG\_variable}. The only exception
1508 to this rule is that the root of a concrete instance tree
1509 (which must always have the tag \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine})
1510 can only be associated with the root of its associated abstract
1511 instance tree (which must have the tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}).
1512
1513 In general, the structure and content of any given concrete
1514 inlined instance tree will be closely analogous to the
1515 structure and content of its associated abstract instance
1516 tree. There are a few exceptions:
1517
1518 \begin{enumerate}[1. ]
1519 \item An entry in the concrete instance tree may be omitted if
1520 it contains only a 
1521 \addtoindexx{abstract origin attribute}
1522 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin} attribute and either
1523 has no children, or its children are omitted. Such entries
1524 would provide no useful information. In C\dash like languages,
1525 such entries frequently include types, including structure,
1526 union, class, and interface types; and members of types. If any
1527 entry within a concrete inlined instance tree needs to refer
1528 to an entity declared within the scope of the relevant inlined
1529 subroutine and for which no concrete instance entry exists,
1530 the reference should refer to the abstract instance entry.
1531
1532 \item Entries in the concrete instance tree which are associated
1533 with entries in the abstract instance tree such that neither
1534 has a \livelink{chap:DWATname}{DW\_AT\_name} attribute,
1535 \addtoindexx{name attribute}
1536 and neither is referenced by
1537 any other debugging information entry, may be omitted. This
1538 may happen for debugging information entries in the abstract
1539 instance trees that became unnecessary in the concrete instance
1540 tree because of additional information available there. For
1541 example, an anonymous variable might have been created and
1542 described in the abstract instance tree, but because of
1543 the actual parameters for a particular inlined expansion,
1544 it could be described as a constant value without the need
1545 for that separate debugging information entry.
1546
1547 \item A concrete instance tree may contain entries which do
1548 not correspond to entries in the abstract instance tree
1549 to describe new entities that are specific to a particular
1550 inlined expansion. In that case, they will not have associated
1551 entries in the abstract instance tree, should not contain
1552 \addtoindexx{abstract origin attribute}
1553 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin} attributes, and must contain all their
1554 own attributes directly. This allows an abstract instance tree
1555 to omit debugging information entries for anonymous entities
1556 that are unlikely to be needed in most inlined expansions. In
1557 any expansion which deviates from that expectation, the
1558 entries can be described in its concrete inlined instance tree.
1559
1560 \end{enumerate}
1561
1562 \subsubsection{Out-of-Line Instances of Inlined Subroutines}
1563 \label{chap:outoflineinstancesofinlinedsubroutines}
1564 Under some conditions, compilers may need to generate concrete
1565 executable instances of inlined subroutines other than at
1566 points where those subroutines are actually called. Such
1567 concrete instances of inlined subroutines are referred to as
1568 ``concrete out\dash of\dash line instances.''
1569
1570 \textit{In \addtoindex{C++}, for example, 
1571 taking the address of a function declared
1572 to be inline can necessitate the generation of a concrete
1573 out\dash of\dash line instance of the given function.}
1574
1575 The DWARF representation of a concrete out\dash of\dash line instance
1576 of an inlined subroutine is essentially the same as for a
1577 concrete inlined instance of that subroutine (as described in
1578 the preceding section). The representation of such a concrete
1579 % It is critical that the hypertarget and livelink be
1580 % separated to avoid problems with latex.
1581 out\dash of\dash line 
1582 \addtoindexx{abstract origin attribute}
1583 instance 
1584 \hypertarget{chap:DWATabstractoriginoutoflineinstance}
1585 makes use of 
1586 \livelink{chap:DWATabstractorigin}{DW\_AT\_abstract\_origin}
1587 attributes in exactly the same way as they are used for
1588 a concrete inlined instance (that is, as references to
1589 corresponding entries within the associated abstract instance
1590 tree).
1591
1592 The differences between the DWARF representation of a
1593 concrete out\dash of\dash line instance of a given subroutine and the
1594 representation of a concrete inlined instance of that same
1595 subroutine are as follows:
1596
1597 \begin{enumerate}[1. ]
1598 \item  The root entry for a concrete out\dash of\dash line instance
1599 of a given inlined subroutine has the same tag as does its
1600 associated (abstract) inlined subroutine entry (that is, tag
1601 \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} rather than \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}).
1602
1603 \item The root entry for a concrete out\dash of\dash line instance tree
1604 is normally owned by the same parent entry that also owns
1605 the root entry of the associated abstract instance. However,
1606 it is not required that the abstract and out\dash of\dash line instance
1607 trees be owned by the same parent entry.
1608
1609 \end{enumerate}
1610
1611 \subsubsection{Nested Inlined Subroutines}
1612 \label{nestedinlinedsubroutines}
1613 Some languages and compilers may permit the logical nesting of
1614 a subroutine within another subroutine, and may permit either
1615 the outer or the nested subroutine, or both, to be inlined.
1616
1617 For a non\dash inlined subroutine nested within an inlined
1618 subroutine, the nested subroutine is described normally in
1619 both the abstract and concrete inlined instance trees for
1620 the outer subroutine. All rules pertaining to the abstract
1621 and concrete instance trees for the outer subroutine apply
1622 also to the abstract and concrete instance entries for the
1623 nested subroutine.
1624
1625 \needlines{5}
1626 For an inlined subroutine nested within another inlined
1627 subroutine, the following rules apply to their abstract and
1628 \addtoindexx{abstract instance!nested}
1629 \addtoindexx{concrete instance!nested}
1630 concrete instance trees:
1631
1632 \begin{enumerate}[1. ]
1633 \item The abstract instance tree for the nested subroutine is
1634 described within the abstract instance tree for the outer
1635 subroutine according to the rules in 
1636 Section \refersec{chap:abstractinstances}, and
1637 without regard to the fact that it is within an outer abstract
1638 instance tree.
1639
1640 \item Any abstract instance tree for a nested subroutine is
1641 always omitted within the concrete instance tree for an
1642 outer subroutine.
1643
1644 \item  A concrete instance tree for a nested subroutine is
1645 always omitted within the abstract instance tree for an
1646 outer subroutine.
1647
1648 \item The concrete instance tree for any inlined or 
1649 \addtoindexx{out-of-line instance}
1650 out-of-line
1651 \addtoindexx{out-of-line-instance|see{concrete out-of-line-instance}}
1652 expansion of the nested subroutine is described within a
1653 concrete instance tree for the outer subroutine according
1654 to the rules in 
1655 Sections \refersec{chap:concreteinlinedinstances} or 
1656 \refersec{chap:outoflineinstancesofinlinedsubroutines}
1657 , respectively,
1658 and without regard to the fact that it is within an outer
1659 concrete instance tree.
1660 \end{enumerate}
1661
1662 See Appendix \refersec{app:inliningexamples} 
1663 for discussion and examples.
1664
1665 \subsection{Trampolines}
1666 \label{chap:trampolines}
1667
1668 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1669 \hypertarget{chap:DWATtrampolinetargetsubroutine}
1670 an intermediary in making a call to another subroutine. It may
1671 adjust parameters and/or the result (if any) as appropriate
1672 to the combined calling and called execution contexts.}
1673
1674 A trampoline is represented by a debugging information entry
1675 \addtoindexx{trampoline (subprogam) entry}
1676 with the tag \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram} or \livelink{chap:DWTAGinlinedsubroutine}{DW\_TAG\_inlined\_subroutine}
1677 that has 
1678 \addtoindexx{trampoline attribute}
1679 a \livelink{chap:DWATtrampoline}{DW\_AT\_trampoline} attribute. 
1680 The value of that
1681 attribute indicates the target subroutine of the trampoline,
1682 that is, the subroutine to which the trampoline passes
1683 control. (A trampoline entry may but need not also have a
1684 \livelink{chap:DWATartificial}{DW\_AT\_artificial} attribute.)
1685
1686 \needlines{5}
1687 The value of the trampoline attribute may be represented
1688 using any of the following forms, which are listed in order
1689 of preference:
1690
1691 \begin{itemize}
1692 \item If the value is of class reference, then the value
1693 specifies the debugging information entry of the target
1694 subprogram.
1695
1696 \item If the value is of class address, then the value is
1697 the relocated address of the target subprogram.
1698
1699 \item If the value is of class string, then the value is the
1700 (possibly mangled) \addtoindexx{mangled names}
1701 name of the target subprogram.
1702
1703 \item If the value is of class \livelink{chap:classflag}{flag}, then the value true
1704 indicates that the containing subroutine is a trampoline but
1705 that the target subroutine is not known.
1706 \end{itemize}
1707
1708
1709 The target subprogram may itself be a trampoline. (A sequence
1710 of trampolines necessarily ends with a non\dash trampoline
1711 subprogram.)
1712
1713 \textit{In \addtoindex{C++}, trampolines may be used 
1714 to implement derived virtual
1715 member functions; such trampolines typically adjust the
1716 \addtoindexx{this parameter}
1717 implicit this pointer parameter in the course of passing
1718 control.  
1719 Other languages and environments may use trampolines
1720 in a manner sometimes known as transfer functions or transfer
1721 vectors.}
1722
1723 \textit{Trampolines may sometimes pass control to the target
1724 subprogram using a branch or jump instruction instead of a
1725 call instruction, thereby leaving no trace of their existence
1726 in the subsequent execution context. }
1727
1728 \textit{This attribute helps make it feasible for a debugger to arrange
1729 that stepping into a trampoline or setting a breakpoint in
1730 a trampoline will result in stepping into or setting the
1731 breakpoint in the target subroutine instead. This helps to
1732 hide the compiler generated subprogram from the user. }
1733
1734 \textit{If the target subroutine is not known, a debugger may choose
1735 to repeatedly step until control arrives in a new subroutine
1736 which can be assumed to be the target subroutine. }
1737
1738
1739
1740 \section{Lexical Block Entries}
1741 \label{chap:lexicalblockentries}
1742
1743 \textit{A 
1744 lexical \livetargi{chap:lexicalblock}{block}{lexical block} 
1745 is 
1746 \addtoindexx{lexical block}
1747 a bracketed sequence of source statements
1748 that may contain any number of declarations. In some languages
1749 (including \addtoindex{C} and \addtoindex{C++}),
1750 \nolink{blocks} can be nested within other
1751 \nolink{blocks} to any depth.}
1752
1753 % We do not need to link to the preceding paragraph.
1754 A lexical \nolink{block} is represented by a debugging information
1755 entry with the 
1756 tag \livetarg{chap:DWTAGlexicalblock}{DW\_TAG\_lexical\_block}.
1757
1758 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} 
1759 entry may have 
1760 either a \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} and
1761 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} pair of 
1762 attributes 
1763 \addtoindexx{high PC attribute}
1764 or 
1765 \addtoindexx{low PC attribute}
1766
1767 \livelink{chap:DWATranges}{DW\_AT\_ranges} attribute
1768 \addtoindexx{ranges attribute}
1769 whose values encode the contiguous or non-contiguous address
1770 ranges, respectively, of the machine instructions generated
1771 for the lexical \nolink{block} 
1772 (see Section \refersec{chap:codeaddressesandranges}).
1773
1774 If a name has been given to the 
1775 lexical \nolink{block} 
1776 in the source
1777 program, then the corresponding 
1778 lexical \nolink{block} entry has a
1779 \livelink{chap:DWATname}{DW\_AT\_name} attribute whose 
1780 \addtoindexx{name attribute}
1781 value is a null\dash terminated string
1782 containing the name of the lexical \nolink{block} 
1783 as it appears in
1784 the source program.
1785
1786 \textit{This is not the same as a \addtoindex{C} or 
1787 \addtoindex{C++} label (see below).}
1788
1789 The lexical \nolink{block} entry owns 
1790 debugging information entries that
1791 describe the declarations within that lexical \nolink{block}. 
1792 There is
1793 one such debugging information entry for each local declaration
1794 of an identifier or inner lexical \nolink{block}.
1795
1796 \section{Label Entries}
1797 \label{chap:labelentries}
1798 \textit{A label is a way of identifying a source statement. A labeled
1799 statement is usually the target of one or more ``go to''
1800 statements.
1801 }
1802
1803 A label is represented by a debugging information entry with
1804 \addtoindexx{label entry}
1805 the 
1806 tag \livetarg{chap:DWTAGlabel}{DW\_TAG\_label}. 
1807 The entry for a label should be owned by
1808 the debugging information entry representing the scope within
1809 which the name of the label could be legally referenced within
1810 the source program.
1811
1812 The label entry has a \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} attribute whose value
1813 is the relocated address of the first machine instruction
1814 generated for the statement identified by the label in
1815 the source program.  The label entry also has a 
1816 \livelink{chap:DWATname}{DW\_AT\_name} attribute 
1817 \addtoindexx{name attribute}
1818 whose value is a null-terminated string containing
1819 the name of the label as it appears in the source program.
1820
1821
1822 \section{With Statement Entries}
1823 \label{chap:withstatemententries}
1824
1825 \textit{Both \addtoindex{Pascal} and 
1826 \addtoindexx{Modula-2}
1827 Modula\dash 2 support the concept of a ``with''
1828 statement. The with statement specifies a sequence of
1829 executable statements within which the fields of a record
1830 variable may be referenced, unqualified by the name of the
1831 record variable.}
1832
1833 A with statement is represented by a
1834 \addtoindexi{debugging information entry}{with statement entry}
1835 with the tag \livetarg{chap:DWTAGwithstmt}{DW\_TAG\_with\_stmt}.
1836
1837 A with statement entry may have either a 
1838 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} and
1839 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} pair of attributes 
1840 \addtoindexx{high PC attribute}
1841 or 
1842 \addtoindexx{low PC attribute}
1843 a \livelink{chap:DWATranges}{DW\_AT\_ranges} attribute
1844 \addtoindexx{ranges attribute}
1845 whose values encode the contiguous or non\dash contiguous address
1846 ranges, respectively, of the machine instructions generated
1847 for the with statement 
1848 (see Section \refersec{chap:codeaddressesandranges}).
1849
1850 The with statement entry has 
1851 \addtoindexx{type attribute}
1852 a \livelink{chap:DWATtype}{DW\_AT\_type} attribute, denoting
1853 the type of record whose fields may be referenced without full
1854 qualification within the body of the statement. It also has
1855 \addtoindexx{location attribute}
1856 a \livelink{chap:DWATlocation}{DW\_AT\_location} attribute, describing how to find the base
1857 address of the record object referenced within the body of
1858 the with statement.
1859
1860 \section{Try and Catch Block Entries}
1861 \label{chap:tryandcatchblockentries}
1862
1863 \textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be 
1864 designated as a ``catch \nolink{block}.'' 
1865 A catch \livetargi{chap:catchblock}{block}{catch block} is an 
1866 exception handler that handles
1867 exceptions thrown by an immediately 
1868 preceding ``try \livelink{chap:tryblock}{block}.''
1869 A catch \livelink{chap:catchblock}{block} 
1870 designates the type of the exception that it
1871 can handle.}
1872
1873 A try \livetargi{chap:tryblock}{block}{try block} is represented 
1874 by a debugging information entry
1875 \addtoindexx{try block entry}
1876 with the tag \livetarg{chap:DWTAGtryblock}{DW\_TAG\_try\_block}.  
1877 A catch \livelink{chap:catchblock}{block} is represented by
1878 a debugging information entry with 
1879 \addtoindexx{catch block entry}
1880 the tag \livetarg{chap:DWTAGcatchblock}{DW\_TAG\_catch\_block}.
1881
1882 % nolink as we have links just above and do not have a combo link for both
1883 Both try and catch \nolink{block} entries may have either a
1884 \livelink{chap:DWATlowpc}{DW\_AT\_low\_pc} and 
1885 \livelink{chap:DWAThighpc}{DW\_AT\_high\_pc} pair of attributes 
1886 \addtoindexx{high PC attribute}
1887 or 
1888 \addtoindexx{low PC attribute}
1889 a
1890 \livelink{chap:DWATranges}{DW\_AT\_ranges} attribute 
1891 \addtoindexx{ranges attribute}
1892 whose values encode the contiguous
1893 or non\dash contiguous address ranges, respectively, of the
1894 machine instructions generated for the \livelink{chap:lexicalblock}{block}
1895 (see Section
1896 \refersec{chap:codeaddressesandranges}).
1897
1898 Catch \livelink{chap:catchblock}{block} entries have at 
1899 least one child entry, an
1900 entry representing the type of exception accepted by
1901 that catch \livelink{chap:catchblock}{block}. 
1902 This child entry has one of 
1903 \addtoindexx{formal parameter entry!in catch block}
1904 the 
1905 \addtoindexx{unspecified parameters entry!in catch block}
1906 tags
1907 \livelink{chap:DWTAGformalparameter}{DW\_TAG\_formal\_parameter} or
1908 \livelink{chap:DWTAGunspecifiedparameters}{DW\_TAG\_unspecified\_parameters},
1909 and will have the same form as other parameter entries.
1910
1911 The siblings immediately following 
1912 a try \livelink{chap:tryblock}{block} entry are its
1913 corresponding catch \livelink{chap:catchblock}{block} entries.
1914
1915
1916
1917
1918
1919
1920