This completes the text, one thinks.
[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 three kinds: normal compilation units,
13 partial compilation units and type units. A partial compilation
14 unit is related to one or more other compilation units that
15 import it. A type unit represents a single complete type in a
16 separate unit. Either a normal compilation unit or a partial
17 compilation unit may be logically incorporated into another
18 compilation unit using an imported unit entry.
19
20 \subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
21 \label{chap:normalandpartialcompilationunitentries}
22
23 A normal compilation unit is represented by a debugging
24 information entry with the tag DW\_TAG\_compile\_unit. A partial
25 compilation unit is represented by a debugging information
26 entry with the tag DW\_TAG\_partial\_unit.
27
28 In a simple normal compilation, a single compilation unit with
29 the tag 
30 DW\-\_TAG\-\_compile\-\_unit represents a complete object file
31 and the tag 
32 DW\-\_TAG\-\_partial\-\_unit is not used. 
33 In a compilation
34 employing the DWARF space compression and duplicate elimination
35 techniques from 
36 Appendix \refersec{app:usingcompilationunits}, 
37 multiple compilation units using
38 the tags 
39 DW\-\_TAG\-\_compile\-\_unit and/or 
40 DW\-\_TAG\-\_partial\-\_unit are
41 used to represent portions of an object file.
42
43 \textit{A normal compilation unit typically represents the text and
44 data contributed to an executable by a single relocatable
45 object file. It may be derived from several source files,
46 including pre\dash processed ``include files.'' A partial
47 compilation unit typically represents a part of the text
48 and data of a relocatable object file, in a manner that can
49 potentially be shared with the results of other compilations
50 to save space. It may be derived from an ``include file'',
51 template instantiation, or other implementation\dash dependent
52 portion of a compilation. A normal compilation unit can also
53 function in a manner similar to a partial compilation unit
54 in some cases.}
55
56 A compilation unit entry owns debugging information
57 entries that represent all or part of the declarations
58 made in the corresponding compilation. In the case of a
59 partial compilation unit, the containing scope of its owned
60 declarations is indicated by imported unit entries in one
61 or more other compilation unit entries that refer to that
62 partial compilation unit (see 
63 Section \refersec{chap:importedunitentries}).
64
65
66 Compilation unit entries may have the following attributes:
67
68 \begin{enumerate}[1]
69 \item Either a DW\_AT\_low\_pc and DW\_AT\_high\_pc pair of
70 attributes or a DW\_AT\_ranges attribute whose values encode the
71 contiguous or non\dash contiguous address ranges, respectively,
72 of the machine instructions generated for the compilation
73 unit (see Section {chap:codeaddressesandranges}).  
74 A DW\_AT\_low\_pc attribute may also
75 be specified in combination with DW\_AT\_ranges to specify the
76 default base address for use in location lists (see Section
77 \refersec{chap:locationlists}) and range lists 
78 (see Section \refersec{chap:noncontiguousaddressranges}).
79
80 \item A DW\_AT\_name attribute whose value is a null\dash terminated
81 string containing the full or relative path name of the primary
82 source file from which the compilation unit was derived.
83
84 \item A DW\_AT\_language attribute whose constant value is an
85 integer code indicating the source language of the compilation
86 unit. The set of language names and their meanings are given
87 in 
88 Figure \refersec{fig:languagenames}.
89
90 \begin{figure}[here]
91 \centering
92 \caption{Language names}
93 \label{fig:languagenames}
94 \begin{tabular}{ll}
95 Language name & Meaning\\ \hline
96 DW\_LANG\_Ada83 \dag&ISO Ada:1983 \\
97 DW\_LANG\_Ada95 \dag&ISO Ada:1995 \\
98 DW\_LANG\_C&Non-standardized C, such as K\&R \\
99 DW\_LANG\_C89&ISO C:1989 \\
100 DW\_LANG\_C99 & ISO C:1999 \\
101 DW\_LANG\_C\_plus\_plus&ISO C++:1998 \\
102 DW\_LANG\_Cobol74& ISO Cobol:1974 \\
103 DW\_LANG\_Cobol85 & ISO Cobol:1985 \\
104 DW\_LANG\_D \dag & D \\
105 DW\_LANG\_Fortran77 &ISO FORTRAN 77\\
106 DW\_LANG\_Fortran90 & ISO Fortran 90\\
107 DW\_LANG\_Fortran95 & ISO Fortran 95\\
108 DW\_LANG\_Java & Java\\
109 DW\_LANG\_Modula2 & ISO Modula\dash 2:1996\\
110 DW\_LANG\_ObjC & Objective C\\
111 DW\_LANG\_ObjC\_plus\_plus & Objective C++\\
112 DW\_LANG\_Pascal83 & ISO Pascal:1983\\
113 DW\_LANG\_PLI \dag & ANSI PL/I:1976\\
114 DW\_LANG\_Python \dag & Python\\
115 DW\_LANG\_UPC &Unified Parallel C\\ \hline
116 \dag \ \ Support for these languages is limited.& \\
117 \end{tabular}
118 \end{figure}
119
120 \item A DW\_AT\_stmt\_list attribute whose value is a section
121 offset to the line number information for this compilation
122 unit.  This information is placed in a separate object file
123 section from the debugging information entries themselves. The
124 value of the statement list attribute is the offset in the
125 .debug\_line section of the first byte of the line number
126 information for this compilation unit 
127 (see Section \refersec{chap:linenumberinformation}).
128
129 \item A DW\_AT\_macro\_info attribute whose value is a section
130 offset to the macro information for this compilation unit.
131 This information is placed in a separate object file section
132 from the debugging information entries themselves. The
133 value of the macro information attribute is the offset in
134 the .debug\_macinfo section of the first byte of the macro
135 information for this compilation unit 
136 (see Section \refersec{chap:macroinformation}).
137
138 \item  A DW\_AT\_comp\_dir attribute whose value is a
139 null\dash terminated string containing the current working directory
140 of the compilation command that produced this compilation
141 unit in whatever form makes sense for the host system.
142
143 \item  A DW\_AT\_producer attribute whose value is a null\dash
144 terminated string containing information about the compiler
145 that produced the compilation unit. The actual contents of
146 the string will be specific to each producer, but should
147 begin with the name of the compiler vendor or some other
148 identifying character sequence that should avoid confusion
149 with other producer values.
150
151
152 \item  A DW\_AT\_identifier\_case attribute whose integer
153 constant value is a code describing the treatment
154 of identifiers within this compilation unit. The
155 set of identifier case codes is given in Figure
156 \refersec{fig:identifiercasecodes}.
157
158 \begin{figure}[here]
159 \autorows[0pt]{c}{1}{l}{
160 \addtoindex{DW\_ID\_case\_sensitive},
161 \addtoindex{DW\_ID\_up\_case},
162 \addtoindex{DW\_ID\_down\_case},
163 \addtoindex{DW\_ID\_case\_insensitive}
164 }
165 \caption{Identifier case codes}\label{fig:identifiercasecodes}
166 \end{figure}
167
168 DW\_ID\_case\_sensitive is the default for all compilation units
169 that do not have this attribute.  It indicates that names given
170 as the values of DW\_AT\_name attributes in debugging information
171 entries for the compilation unit reflect the names as they
172 appear in the source program. The debugger should be sensitive
173 to the case of identifier names when doing identifier lookups.
174
175 DW\_ID\_up\_case means that the producer of the debugging
176 information for this compilation unit converted all source
177 names to upper case. The values of the name attributes may not
178 reflect the names as they appear in the source program. The
179 debugger should convert all names to upper case when doing
180 lookups.
181
182 DW\_ID\_down\_case means that the producer of the debugging
183 information for this compilation unit converted all source
184 names to lower case. The values of the name attributes may not
185 reflect the names as they appear in the source program. The
186 debugger should convert all names to lower case when doing
187 lookups.
188
189 DW\_ID\_case\_insensitive means that the values of the name
190 attributes reflect the names as they appear in the source
191 program but that a case insensitive lookup should be used to
192 access those names.
193
194 \item A DW\_AT\_base\_types attribute whose value is a reference.
195
196 This attribute points to a debugging information entry
197 representing another compilation unit.  It may be used
198 to specify the compilation unit containing the base type
199 entries used by entries in the current compilation unit
200 (see Section \refersec{chap:basetypeentries}).
201
202 This attribute provides a consumer a way to find the definition
203 of base types for a compilation unit that does not itself
204 contain such definitions. This allows a consumer, for example,
205 to interpret a type conversion to a base type correctly.
206
207 \item A DW\_AT\_use\_UTF8 attribute, which is a flag whose
208 presence indicates that all strings (such as the names of
209 declared entities in the source program) are represented
210 using the UTF\dash 8 representation 
211 (see Section \refersec{datarep:attributeencodings}).
212
213
214 \item A DW\_AT\_main\_subprogram attribute, which is a flag
215 whose presence indicates that the compilation unit contains a
216 subprogram that has been identified as the starting function
217 of the program. If more than one compilation unit contains
218 this flag, any one of them may contain the starting function.
219
220 \textit{Fortran has a PROGRAM statement which is used
221 to specify and provide a user\dash specified name for the main
222 subroutine of a program. C uses the name “main” to identify
223 the main subprogram of a program. Some other languages provide
224 similar or other means to identify the main subprogram of
225 a program.}
226
227 \end{enumerate}
228
229 The  base address of a compilation unit is defined as the
230 value of the DW\_AT\_low\_pc attribute, if present; otherwise,
231 it is undefined. If the base address is undefined, then any
232 DWARF entry or structure defined in terms of the base address
233 of that compilation unit is not valid.
234
235
236 \subsection{Imported Unit Entries}
237 \label{chap:importedunitentries}
238 The place where a normal or partial unit is imported is
239 represented by a debugging information entry with the tag
240 DW\_TAG\_imported\_unit. An imported unit entry contains a
241 DW\_AT\_import attribute whose value is a reference to the
242 normal or partial compilation unit whose declarations logically
243 belong at the place of the imported unit entry.
244
245 An imported unit entry does not necessarily correspond to
246 any entity or construct in the source program. It is merely
247 “glue” used to relate a partial unit, or a compilation
248 unit used as a partial unit, to a place in some other
249 compilation unit.
250
251 \subsection{Separate Type Unit Entries}
252 \label{chap:separatetypeunitentries}
253 An object file may contain any number of separate type
254 unit entries, each representing a single complete type
255 definition. Each type unit must be uniquely identified by
256 a 64\dash bit signature, stored as part of the type unit, which
257 can be used to reference the type definition from debugging
258 information entries in other compilation units and type units.
259
260 A type unit is represented by a debugging information entry
261 with the tag DW\-\_TAG\-\_type\-\_unit. 
262 A type unit entry owns debugging
263 information entries that represent the definition of a single
264 type, plus additional debugging information entries that may
265 be necessary to include as part of the definition of the type.
266
267 A type unit entry may have a DW\_AT\_language attribute, whose
268 constant value is an integer code indicating the source
269 language used to define the type. The set of language names
270 and their meanings are given in Figure \refersec{fig:languagenames}.
271
272 A type unit entry for a given type T owns a debugging
273 information entry that represents a defining declaration
274 of type T. If the type is nested within enclosing types or
275 namespaces, the debugging information entry for T is nested
276 within debugging information entries describing its containers;
277 otherwise, T is a direct child of the type unit entry.
278
279 A type unit entry may also own additional debugging information
280 entries that represent declarations of additional types that
281 are referenced by type T and have not themselves been placed in
282 separate type units. Like T, if an additional type U is nested
283 within enclosing types or namespaces, the debugging information
284 entry for U is nested within entries describing its containers;
285 otherwise, U is a direct child of the type unit entry.
286
287 The containing entries for types T and U are declarations,
288 and the outermost containing entry for any given type T or
289 U is a direct child of the type unit entry. The containing
290 entries may be shared among the additional types and between
291 T and the additional types.
292
293 Types are not required to be placed in type units. In general,
294 only large types such as structure, class, enumeration, and
295 union types included from header files should be considered
296 for separate type units. Base types and other small types
297 are not usually worth the overhead of placement in separate
298 type units. Types that are unlikely to be replicated, such
299 as those defined in the main source file, are also better
300 left in the main compilation unit.
301
302 \section{Module, Namespace and Importing Entries}
303 \textit{Modules and namespaces provide a means to collect related
304 entities into a single entity and to manage the names of
305 those entities.}
306
307 \subsection{Module Entries}
308 \label{chap:moduleentries}
309 \textit{Several languages have the concept of a ``module.''
310 A Modula\dash 2 definition module may be represented by a module
311 entry containing a declaration attribute (DW\_AT\_declaration). A
312 Fortran 90 module may also be represented by a module entry
313 (but no declaration attribute is warranted because Fortran
314 has no concept of a corresponding module body).}
315
316 A module is represented by a debugging information entry
317 with the tag DW\_TAG\_module.  Module entries may own other
318 debugging information entries describing program entities
319 whose declaration scopes end at the end of the module itself.
320
321 If the module has a name, the module entry has a DW\_AT\_name
322 attribute whose value is a null\dash terminated string containing
323 the module name as it appears in the source program.
324
325 The module entry may have either a DW\_AT\_low\_pc and
326 DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges attribute
327 whose values encode the contiguous or non\dash contiguous address
328 ranges, respectively, of the machine instructions generated for
329 the module initialization code 
330 (see Section \refersec{chap:codeaddressesandranges}). 
331 It may also
332 have a DW\_AT\_entry\_pc attribute whose value is the address of
333 the first executable instruction of that initialization code
334 (see Section \refersec{chap:entryaddress}).
335
336 If the module has been assigned a priority, it may have a
337 DW\_AT\_priority attribute. The value of this attribute is a
338 reference to another debugging information entry describing
339 a variable with a constant value. The value of this variable
340 is the actual constant value of the module’s priority,
341 represented as it would be on the target architecture.
342
343 \subsection{Namespace Entries}
344 \label{chap:namespaceentries}
345 \textit{C++ has the notion of a namespace, which provides a way to
346 implement name hiding, so that names of unrelated things
347 do not accidentally clash in the global namespace when an
348 application is linked together.}
349
350 A namespace is represented by a debugging information entry
351 with the tag DW\-\_TAG\-\_namespace. A namespace extension is
352 represented by a DW\-\_TAG\-\_namespace entry with a DW\-\_AT\-\_extension
353 attribute referring to the previous extension, or if there
354 is no previous extension, to the original DW\-\_TAG\-\_namespace
355 entry. A namespace extension entry does not need to duplicate
356 information in a previous extension entry of the namespace
357 nor need it duplicate information in the original namespace
358 entry. (Thus, for a namespace with a name, a DW\_AT\_name
359 attribute need only be attached directly to the original
360 DW\-\_TAG\-\_namespace entry.)
361
362 Namespace and namespace extension entries may own other
363 debugging information entries describing program entities
364 whose declarations occur in the namespace.
365
366 \textit{For C++, such owned program entities may be declarations,
367 including certain declarations that are also object or
368 function definitions.}
369
370 If a type, variable, or function declared in a namespace is
371 defined outside of the body of the namespace declaration,
372 that type, variable, or function definition entry has a
373 DW\-\_AT\-\_specification attribute whose value is a reference to the
374 debugging information entry representing the declaration of
375 the type, variable or function. Type, variable, or function
376 entries with a DW\-\_AT\-\_specification attribute do not need
377 to duplicate information provided by the declaration entry
378 referenced by the specification attribute.
379
380 \textit{The C++ global namespace (the namespace referred to by
381 ``::f'', for example) is not explicitly represented in
382 DWARF with a namespace entry (thus mirroring the situation
383 in C++ source).  Global items may be simply declared with no
384 reference to a namespace.}
385
386 \textit{The C++ compilation unit specific ``unnamed namespace'' may
387 be represented by a namespace entry with no name attribute in
388 the original namespace declaration entry (and therefore no name
389 attribute in any namespace extension entry of this namespace).
390 }
391
392 \textit{A compiler emitting namespace information may choose to
393 explicitly represent namespace extensions, or to represent the
394 final namespace declaration of a compilation unit; this is a
395 quality\dash of\dash implementation issue and no specific requirements
396 are given here. If only the final namespace is represented,
397 it is impossible for a debugger to interpret using declaration
398 references in exactly the manner defined by the C++ language.
399 }
400
401 \textit{Emitting all namespace declaration information in all
402 compilation units can result in a significant increase in the
403 size of the debug information and significant duplication of
404 information across compilation units. The C++ namespace std,
405 for example, is large and will probably be referenced in
406 every C++ compilation unit.
407 }
408
409 \textit{For a C++ namespace example, see Appendix \refersec{app:namespaceexample}.
410 }
411
412
413
414 \subsection{Imported (or Renamed) Declaration Entries} 
415 \label{chap:importedorrenameddeclarationentries}
416 \textit{Some languages support the concept of importing into or making
417 accessible in a given unit declarations made in a different
418 module or scope. An imported declaration may sometimes be
419 given another name.
420 }
421
422 An imported declaration is represented by one or
423 more debugging information entries with the tag
424 DW\_TAG\_imported\_declaration. When an overloaded entity
425 is imported, there is one imported declaration entry for
426 each overloading. Each imported declaration entry has a
427 DW\_AT\_import attribute, whose value is a reference to the
428 debugging information entry representing the declaration that
429 is being imported.
430
431 An imported declaration may also have a DW\_AT\_name attribute
432 whose value is a null\dash terminated string containing the
433 name, as it appears in the source program, by which the
434 imported entity is to be known in the context of the imported
435 declaration entry (which may be different than the name of
436 the entity being imported). If no name is present, then the
437 name by which the entity is to be known is the same as the
438 name of the entity being imported.
439
440 An imported declaration entry with a name attribute may be
441 used as a general means to rename or provide an alias for
442 an entity, regardless of the context in which the importing
443 declaration or the imported entity occurs.
444
445 \textit{A C++ namespace alias may be represented by an imported
446 declaration entry with a name attribute whose value is
447 a null\dash terminated string containing the alias name as it
448 appears in the source program and an import attribute whose
449 value is a reference to the applicable original namespace or
450 namespace extension entry.
451 }
452
453 \textit{A C++ using declaration may be represented by one or more
454 imported declaration entries.  When the using declaration
455 refers to an overloaded function, there is one imported
456 declaration entry corresponding to each overloading. Each
457 imported declaration entry has no name attribute but it does
458 have an import attribute that refers to the entry for the
459 entity being imported. (C++ provides no means to ``rename''
460 an imported entity, other than a namespace).
461 }
462
463 \textit{A Fortran use statement with an ``only list'' may be
464 represented by a series of imported declaration entries,
465 one (or more) for each entity that is imported. An entity
466 that is renamed in the importing context may be represented
467 by an imported declaration entry with a name attribute that
468 specifies the new local name.
469 }
470
471 \subsection{Imported Module Entries}
472 \label{chap:importedmoduleentries}
473
474 \textit{Some languages support the concept of importing into or making
475 accessible in a given unit all of the declarations contained
476 within a separate module or namespace.
477 }
478
479 An imported module declaration is represented by a debugging
480 information entry with the tag DW\-\_TAG\-\_imported\-\_module. An
481 imported module entry contains a DW\-\_AT\-\_import attribute
482 whose value is a reference to the module or namespace entry
483 containing the definition and/or declaration entries for
484 the entities that are to be imported into the context of the
485 imported module entry.
486
487 An imported module declaration may own a set of imported
488 declaration entries, each of which refers to an entry in the
489 module whose corresponding entity is to be known in the context
490 of the imported module declaration by a name other than its
491 name in that module. Any entity in the module that is not
492 renamed in this way is known in the context of the imported
493 module entry by the same name as it is declared in the module.
494
495 \textit{A C++ using directive may be represented by an imported module
496 entry, with an import attribute referring to the namespace
497 entry of the appropriate extension of the namespace (which
498 might be the original namespace entry) and no owned entries.
499 }
500
501 \textit{A Fortran use statement with a “rename list” may be
502 represented by an imported module entry with an import
503 attribute referring to the module and owned entries
504 corresponding to those entities that are renamed as part of
505 being imported.
506 }
507
508 \textit{A Fortran use statement with neither a “rename list” nor
509 an “only list” may be represented by an imported module
510 entry with an import attribute referring to the module and
511 no owned child entries.
512 }
513
514 \textit{A use statement with an “only list” is represented by a
515 series of individual imported declaration entries as described
516 in Section \refersec{chap:importedorrenameddeclarationentries}.
517 }
518
519 \textit{A Fortran use statement for an entity in a module that is
520 itself imported by a use statement without an explicit mention
521 may be represented by an imported declaration entry that refers
522 to the original debugging information entry. For example, given
523 }
524 \begin{lstlisting}
525 module A
526 integer X, Y, Z
527 end module
528
529 module B
530 use A
531 end module
532
533 module C
534 use B, only Q => X
535 end module
536 \end{lstlisting}
537
538 the imported declaration entry for Q within module C refers
539 directly to the variable declaration entry for A in module A
540 because there is no explicit representation for X in module B.
541
542 A similar situation arises for a C++ using declaration that
543 imports an entity in terms of a namespace alias. See 
544 Appendix  \refersec{app:namespaceexample}
545 for an example.
546
547
548 \section{Subroutine and Entry Point Entries}
549 \label{chap:subroutineandentrypointentries}
550
551 The following tags exist to describe debugging information entries for subroutines and entry
552 points:
553
554 \begin{tabular}{lp{9.0cm}}
555 DW\_TAG\_subprogram & A subroutine or function. \\
556 DW\_TAG\_inlined\_subroutine & A particular inlined 
557   instance of a subroutine or function. \\
558 DW\_TAG\_entry\_point & An alternate entry point. \\
559 \end{tabular}
560
561 \subsection{General Subroutine and Entry Point Information}
562 \label{chap:generalsubroutineandentrypointinformation}
563
564 It may also have a DW\_AT\_linkage\_name attribute as
565 described in Section \refersec{chap:linkagenames}.
566
567 If the name of the subroutine described by an entry with the
568 tag DW\_TAG\_subprogram is visible outside of its containing
569 compilation unit, that entry has a DW\_AT\_external attribute,
570 which is a flag.
571
572 \textit{Additional attributes for functions that are members of a
573 class or structure are described in 
574 Section \refersec{chap:memberfunctionentries}.
575 }
576
577 A subroutine entry may contain a DW\_AT\_main\_subprogram
578 attribute which is a flag whose presence indicates that the
579 subroutine has been identified as the starting function of
580 the program.  If more than one subprogram contains this flag,
581 any one of them may be the starting subroutine of the program.
582
583 \textit{Fortran has a PROGRAM statement which is used to specify
584 and provide a user\dash supplied name for the main subroutine of
585 a program.
586 }
587
588 \textit{A common debugger feature is to allow the debugger user to call
589 a subroutine within the subject program. In certain cases,
590 however, the generated code for a subroutine will not obey
591 the standard calling conventions for the target architecture
592 and will therefore not be safe to call from within a debugger.
593 }
594
595 A subroutine entry may contain a DW\_AT\_calling\_convention
596 attribute, whose value is an integer constant. The set of
597 calling convention codes is given in 
598 Figure \refersec{fig:callingconventioncodes}.
599
600 \begin{figure}[here]
601 \autorows[0pt]{c}{1}{l}{
602 \addtoindex{DW\_CC\_normal},
603 \addtoindex{DW\_CC\_program},
604 \addtoindex{DW\_CC\_nocall},
605 }
606 \caption{Calling convention codes}\label{fig:callingconventioncodes}
607 \end{figure}
608
609 If this attribute is not present, or its value is the constant
610 DW\_CC\_normal, then the subroutine may be safely called by
611 obeying the ``standard'' calling conventions of the target
612 architecture. If the value of the calling convention attribute
613 is the constant DW\_CC\_nocall, the subroutine does not obey
614 standard calling conventions, and it may not be safe for the
615 debugger to call this subroutine.
616
617 If the semantics of the language of the compilation unit
618 containing the subroutine entry distinguishes between ordinary
619 subroutines and subroutines that can serve as the ``main
620 program,'' that is, subroutines that cannot be called
621 directly according to the ordinary calling conventions,
622 then the debugging information entry for such a subroutine
623 may have a calling convention attribute whose value is the
624 constant DW\_CC\_program.
625
626 \textit{The DW\_CC\_program value is intended to support Fortran main
627 programs which in some implementations may not be callable
628 or which must be invoked in a special way. It is not intended
629 as a way of finding the entry address for the program.
630 }
631
632 \textit{In C there is a difference between the types of functions
633 declared using function prototype style declarations and
634 those declared using non\dash prototype declarations.
635 }
636
637 A subroutine entry declared with a function prototype style
638 declaration may have a 
639 DW\-\_AT\-\_prototyped attribute, which is
640 a flag.
641
642 \textit{The Fortran language allows the keywords elemental, pure
643 and recursive to be included as part of the declaration of
644 a subroutine; these attributes reflect that usage. These
645 attributes are not relevant for languages that do not support
646 similar keywords or syntax. In particular, the DW\_AT\_recursive
647 attribute is neither needed nor appropriate in languages such
648 as C where functions support recursion by default.
649 }
650
651 A subprogram entry may have a DW\_AT\_elemental attribute, which
652 is a flag. The attribute indicates whether the subroutine
653 or entry point was declared with the ``elemental'' keyword
654 or property.
655
656 A subprogram entry may have a DW\_AT\_pure attribute, which is
657 a flag. The attribute indicates whether the subroutine was
658 declared with the ``pure'' keyword or property.
659
660 A subprogram entry may have a DW\_AT\_recursive attribute, which
661 is a flag. The attribute indicates whether the subroutine
662 or entry point was declared with the ``recursive'' keyword
663 or property.
664
665
666
667 \subsection{Subroutine and Entry Point Return Types}
668 \label{chap:subroutineandentrypointreturntypes}
669
670 If the subroutine or entry point is a function that returns a
671 value, then its debugging information entry has a DW\_AT\_type
672 attribute to denote the type returned by that function.
673
674 \textit{Debugging information entries for C void functions should
675 not have an attribute for the return type.  }
676
677
678 \subsection{Subroutine and Entry Point Locations}
679 \label{chap:subroutineandentrypointlocations}
680
681 A subroutine entry may have either a DW\_AT\_low\_pc and
682 DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges attribute
683 whose values encode the contiguous or non\dash contiguous address
684 ranges, respectively, of the machine instructions generated
685 for the subroutine (see 
686 Section \refersec{chap:codeaddressesandranges}).
687
688 A subroutine entry may also have a DW\_AT\_entry\_pc attribute
689 whose value is the address of the first executable instruction
690 of the subroutine (see 
691 Section \refersec{chap:entryaddress}).
692
693 An entry point has a DW\_AT\_low\_pc attribute whose value is the
694 relocated address of the first machine instruction generated
695 for the entry point.
696
697 \textit{While the DW\_AT\_entry\_pc attribute might also seem appropriate
698 for this purpose, historically the DW\_AT\_low\_pc attribute
699 was used before the DW\_AT\_entry\_pc was introduced (in DWARF
700 Version 3). There is insufficient reason to change this.}
701
702 Subroutines and entry points may also have DW\_AT\_segment and
703 DW\_AT\_address\_class attributes, as appropriate, to specify
704 which segments the code for the subroutine resides in and
705 the addressing mode to be used in calling that subroutine.
706
707 A subroutine entry representing a subroutine declaration
708 that is not also a definition does not have code address or
709 range attributes.
710
711
712 \subsection{Declarations Owned by Subroutines and Entry Points} 
713 \label{chap:declarationsownedbysubroutinesandentrypoints}
714
715 The declarations enclosed by a subroutine or entry point are
716 represented by debugging information entries that are owned
717 by the subroutine or entry point entry. Entries representing
718 the formal parameters of the subroutine or entry point appear
719 in the same order as the corresponding declarations in the
720 source program.
721
722 \textit{There is no ordering requirement for entries for declarations
723 that are children of subroutine or entry point entries but
724 that do not represent formal parameters. The formal parameter
725 entries may be interspersed with other entries used by formal
726 parameter entries, such as type entries.}
727
728 The unspecified parameters of a variable parameter list are
729 represented by a debugging information entry with the tag
730 DW\_TAG\_unspecified\_parameters.
731
732 The entry for a subroutine that includes a Fortran common block
733 has a child entry with the tag 
734 DW\-\_TAG\-\_common\-\_inclusion. The
735 common inclusion entry has a 
736 DW\-\_AT\-\_common\-\_reference attribute
737 whose value is a reference to the debugging information entry
738 for the common block being included 
739 (see Section \refersec{chap:commonblockentries}).
740
741 \subsection{Low-Level Information}
742 \label{chap:lowlevelinformation}
743
744 A subroutine or entry point entry may have a DW\_AT\_return\_addr
745 attribute, whose value is a location description. The location
746 calculated is the place where the return address for the
747 subroutine or entry point is stored.
748
749 A subroutine or entry point entry may also have a
750 DW\_AT\_frame\_base attribute, whose value is a location
751 description that computes the “frame base” for the
752 subroutine or entry point. If the location description is
753 a simple register location description, the given register
754 contains the frame base address. If the location description is
755 a DWARF expression, the result of evaluating that expression
756 is the frame base address. Finally, for a location list,
757 this interpretation applies to each location description
758 contained in the list of location list entries.
759
760 \textit{The use of one of the DW\_OP\_reg~\textless~n~\textgreater 
761 operations in this
762 context is equivalent to using 
763 DW\_OP\_breg~\textless~n~\textgreater(0) 
764 but more
765 compact. However, these are not equivalent in general.}
766
767 \textit{The frame base for a procedure is typically an address fixed
768 relative to the first unit of storage allocated for the
769 procedure’s stack frame. The DW\_AT\_frame\_base attribute
770 can be used in several ways:}
771
772 \begin{enumerate}[1.]
773 \item \textit{In procedures that need location lists to locate local
774 variables, the DW\_AT\_frame\_base can hold the needed location
775 list, while all variables’ location descriptions can be
776 simpler ones involving the frame base.}
777
778 \item \textit{It can be used in resolving ``up\dash level'' addressing
779 within nested routines. 
780 (See also DW\_AT\_static\_link, below)}
781 %The -See also- here is ok, the DW_AT should be
782 %a hyperref to the def itself, which is earlier in this document.
783 \end{enumerate}
784
785 \textit{Some languages support nested subroutines. In such languages,
786 it is possible to reference the local variables of an
787 outer subroutine from within an inner subroutine. The
788 DW\_AT\_static\_link and DW\_AT\_frame\_base attributes allow
789 debuggers to support this same kind of referencing.}
790
791 If a subroutine or entry point is nested, it may have a
792 DW\_AT\_static\_link attribute, whose value is a location
793 description that computes the frame base of the relevant
794 instance of the subroutine that immediately encloses the
795 subroutine or entry point.
796
797 In the context of supporting nested subroutines, the
798 DW\_AT\_frame\_base attribute value should obey the following
799 constraints:
800
801 \begin{enumerate}[1.]
802 \item It should compute a value that does not change during the
803 life of the procedure, and
804
805 \item The computed value should be unique among instances of
806 the same subroutine. (For typical DW\_AT\_frame\_base use, this
807 means that a recursive subroutine’s stack frame must have
808 non\dash zero size.)
809 \end{enumerate}
810
811 \textit{If a debugger is attempting to resolve an up\dash level reference
812 to a variable, it uses the nesting structure of DWARF to
813 determine which subroutine is the lexical parent and the
814 DW\_AT\_static\_link value to identify the appropriate active
815 frame of the parent. It can then attempt to find the reference
816 within the context of the parent.}
817
818
819
820 \subsection{Types Thrown by Exceptions}
821 \label{chap:typesthrownbyexceptions}
822
823 \textit{In C++ a subroutine may declare a set of types which
824 it may validly throw.}
825
826 If a subroutine explicitly declares that it may throw
827 an exception for one or more types, each such type is
828 represented by a debugging information entry with the tag
829 DW\-\_TAG\-\_thrown\-\_type.  Each such entry is a child of the entry
830 representing the subroutine that may throw this type. Each
831 thrown type entry contains a DW\-\_AT\-\_type attribute, whose
832 value is a reference to an entry describing the type of the
833 exception that may be thrown.
834
835 \subsection{Function Template Instantiations}
836 \label{chap:functiontemplateinstantiations}
837
838 \textit{In C++, a function template is a generic definition of
839 a function that is instantiated differently when called with
840 values of different types. DWARF does not represent the generic
841 template definition, but does represent each instantiation.}
842
843 A template instantiation is represented by a debugging
844 information entry with the tag DW\_TAG\_subprogram. With four
845 exceptions, such an entry will contain the same attributes and
846 will have the same types of child entries as would an entry
847 for a subroutine defined explicitly using the instantiation
848 types. The exceptions are:
849
850 \begin{enumerate}[1.]
851 \item Each formal parameterized type declaration appearing in the
852 template definition is represented by a debugging information
853 entry with the tag DW\-\_TAG\-\_template\-\_type\-\_parameter. Each
854 such entry has a DW\-\_AT\-\_name attribute, whose value is a
855 null\dash terminated string containing the name of the formal
856 type parameter as it appears in the source program. The
857 template type parameter entry also has a DW\_AT\_type attribute
858 describing the actual type by which the formal is replaced
859 for this instantiation.
860
861 \item The subprogram entry and each of its child entries reference
862 a template type parameter entry in any circumstance where
863 the template definition referenced a formal parameterized type.
864
865 \item If the compiler has generated a special compilation unit
866 to hold the template instantiation and that compilation unit
867 has a different name from the compilation unit containing
868 the template definition, the name attribute for the debugging
869 information entry representing that compilation unit is empty
870 or omitted.
871
872 \item If the subprogram entry representing the template
873 instantiation or any of its child entries contain declaration
874 coordinate attributes, those attributes refer to the source
875 for the template definition, not to any source generated
876 artificially by the compiler for this instantiation.
877 \end{enumerate}
878
879
880
881 \subsection{Inlinable and Inlined Subroutines}
882 A declaration or a definition of an inlinable subroutine
883 is represented by a debugging information entry with the
884 tag DW\_TAG\_subprogram. The entry for a subroutine that is
885 explicitly declared to be available for inline expansion or
886 that was expanded inline implicitly by the compiler has a
887 DW\_AT\_inline attribute whose value is an integer constant. The
888 set of values for the DW\_AT\_inline attribute is given in
889 Figure \refersec{fig:inlinecodes}.
890
891 \begin{figure}[here]
892 \centering
893 \caption{Inline codes}
894 \label{fig:inlinecodes}
895 \begin{tabular}{lp{9cm}}
896 Name&Meaning\\ \hline
897 DW\_INL\_not\_inlined & Not delared inline nor inlined by the
898   compiler(equivalent to the absense of the containing
899   DW\-\_AT\-\_linline attribute) \\
900 DW\_INL\_inlined & Not declared inline but inlined by the compiler \\
901 DW\_INL\_declared\_not\_inlined & Declared inline but 
902   not inlined by the compiler \\
903 DW\_INL\_declared\_inlined & Declared inline and inlined by the compiler \\
904 \end{tabular}
905 \end{figure}
906
907 \textit{In C++, a function or a constructor declared with
908 constexpr is implicitly declared inline. The abstract inline
909 instance (see below) is represented by a debugging information
910 entry with the tag DW\_TAG\_subprogram. Such an entry has a
911 DW\_AT\_inline attribute whose value is DW\_INL\_inlined.}
912
913
914 \paragraph{Abstract Instances}
915 \label{chap:abstractinstances}
916 Any debugging information entry that is owned (either
917 directly or indirectly) by a debugging information entry
918 that contains the DW\_AT\_inline attribute is referred to
919 as an “abstract instance entry.” Any subroutine entry
920 that contains a DW\_AT\_inline attribute whose value is other
921 than DW\_INL\_not\_inlined is known as an “abstract instance
922 root.” Any set of abstract instance entries that are all
923 children (either directly or indirectly) of some abstract
924 instance root, together with the root itself, is known as
925 an “abstract instance tree.” However, in the case where
926 an abstract instance tree is nested within another abstract
927 instance tree, the entries in the nested abstract instance
928 tree are not considered to be entries in the outer abstract
929 instance tree.
930
931 Each abstract instance root is either part of a larger
932 tree (which gives a context for the root) or uses
933 DW\_AT\_specification to refer to the declaration in context.
934
935 \textit{For example, in C++ the context might be a namespace
936 declaration or a class declaration.}
937
938 \textit{Abstract instance trees are defined so that no entry is part
939 of more than one abstract instance tree. This simplifies the
940 following descriptions.}
941
942 A debugging information entry that is a member of an abstract
943 instance tree should not contain any attributes which describe
944 aspects of the subroutine which vary between distinct inlined
945 expansions or distinct out\dash of\dash line expansions. For example,
946 the DW\-\_AT\-\_low\-\_pc,
947 DW\-\_AT\-\_high\-\_pc, DW\-\_AT\-\_ranges, 
948 DW\-\_AT\-\_entry\-\_pc, DW\-\_AT\-\_location,
949 DW\-\_AT\-\_return\-\_addr, DW\-\_AT\-\_start\-\_scope, and 
950 DW\-\_AT\-\_segment
951 attributes typically should be omitted; however, this list
952 is not exhaustive.
953
954 \textit{It would not make sense normally to put these attributes into
955 abstract instance entries since such entries do not represent
956 actual (concrete) instances and thus do not actually exist at
957 run\dash time.  However, 
958 see Appendix \refersec{app:inlineouteronenormalinner} 
959 for a contrary example.}
960
961 The rules for the relative location of entries belonging to
962 abstract instance trees are exactly the same as for other
963 similar types of entries that are not abstract. Specifically,
964 the rule that requires that an entry representing a declaration
965 be a direct child of the entry representing the scope of the
966 declaration applies equally to both abstract and non\dash abstract
967 entries. Also, the ordering rules for formal parameter entries,
968 member entries, and so on, all apply regardless of whether
969 or not a given entry is abstract.
970
971 \paragraph{Concrete Inlined Instances}
972 \label{chap:concreteinlinedinstances}
973
974 Each inline expansion of a subroutine is represented
975 by a debugging information entry with the tag
976 DW\_TAG\_inlined\_subroutine. Each such entry should be a direct
977 child of the entry that represents the scope within which
978 the inlining occurs.
979
980 Each inlined subroutine entry may have either a DW\_AT\_low\_pc
981 and DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges
982 attribute whose values encode the contiguous or non\dash contiguous
983 address ranges, respectively, of the machine instructions
984 generated for the inlined subroutine (see 
985 Section \refersec{chap:codeaddressesandranges}). An
986 inlined subroutine entry may also contain a DW\_AT\_entry\_pc
987 attribute, representing the first executable instruction of
988 the inline expansion (see 
989 Section \refersec{chap:entryaddress}).
990
991 An inlined subroutine entry may also have DW\-\_AT\-\_call\-\_file,
992 DW\-\_AT\-\_call\-\_line and DW\-\_AT\-\_call\-\_column attributes, 
993 each of whose
994 value is an integer constant. These attributes represent the
995 source file, source line number, and source column number,
996 respectively, of the first character of the statement or
997 expression that caused the inline expansion. The call file,
998 call line, and call column attributes are interpreted in
999 the same way as the declaration file, declaration line, and
1000 declaration column attributes, respectively (see 
1001 Section \refersec{chap:declarationcoordinates}).
1002
1003 The call file, call line and call column coordinates do not
1004 describe the coordinates of the subroutine declaration that
1005 was inlined, rather they describe the coordinates of the call.
1006
1007 An inlined subroutine entry may have a DW\_AT\_const\_expr
1008 attribute, which is a flag whose presence indicates that the
1009 subroutine has been evaluated as a compile\dash time constant. Such
1010 an entry may also have a DW\_AT\_const\_value attribute,
1011 whose value may be of any form that is appropriate for the
1012 representation of the subroutine's return value. The value of
1013 this attribute is the actual return value of the subroutine,
1014 represented as it would be on the target architecture.
1015
1016 \textit{In C++, if a function or a constructor declared with constexpr
1017 is called with constant expressions, then the corresponding
1018 concrete inlined instance has a DW\_AT\_const\_expr attribute,
1019 as well as a DW\_AT\_const\_value attribute whose value represents
1020 the actual return value of the concrete inlined instance.}
1021
1022 Any debugging information entry that is owned (either
1023 directly or indirectly) by a debugging information entry
1024 with the tag DW\_TAG\_inlined\_subroutine is referred to as a
1025 “concrete inlined instance entry.” Any entry that has
1026 the tag DW\_TAG\_inlined\_subroutine is known as a “concrete
1027 inlined instance root.” Any set of concrete inlined instance
1028 entries that are all children (either directly or indirectly)
1029 of some concrete inlined instance root, together with the root
1030 itself, is known as a ``concrete inlined instance tree.''
1031 However, in the case where a concrete inlined instance tree
1032 is nested within another concrete instance tree, the entries
1033 in the nested concrete instance tree are not considered to
1034 be entries in the outer concrete instance tree.
1035
1036 \textit{Concrete inlined instance trees are defined so that no entry
1037 is part of more than one concrete inlined instance tree. This
1038 simplifies later descriptions.}
1039
1040 Each concrete inlined instance tree is uniquely associated
1041 with one (and only one) abstract instance tree.
1042
1043 \textit{Note, however, that the reverse is not true. Any given abstract
1044 instance tree may be associated with several different concrete
1045 inlined instance trees, or may even be associated with zero
1046 concrete inlined instance trees.}
1047
1048 Concrete inlined instance entries may omit attributes that
1049 are not specific to the concrete instance (but present in
1050 the abstract instance) and need include only attributes that
1051 are specific to the concrete instance (but omitted in the
1052 abstract instance). In place of these omitted attributes, each
1053 concrete inlined instance entry has a DW\_AT\_abstract\_origin
1054 attribute that may be used to obtain the missing information
1055 (indirectly) from the associated abstract instance entry. The
1056 value of the abstract origin attribute is a reference to the
1057 associated abstract instance entry.
1058
1059 If an entry within a concrete inlined instance tree contains
1060 attributes describing the declaration coordinates of that
1061 entry, then those attributes should refer to the file, line
1062 and column of the original declaration of the subroutine,
1063 not to the point at which it was inlined. As a consequence,
1064 they may usually be omitted from any entry that has an abstract
1065 origin attribute.
1066
1067 For each pair of entries that are associated via a
1068 DW\-\_AT\-\_abstract\-\_origin attribute, both members of the pair
1069 have the same tag. So, for example, an entry with the tag
1070 DW\-\_TAG\-\_variable can only be associated with another entry
1071 that also has the tag DW\-\_TAG\-\_variable. The only exception
1072 to this rule is that the root of a concrete instance tree
1073 (which must always have the tag DW\-\_TAG\-\_\-inlined\_subroutine)
1074 can only be associated with the root of its associated abstract
1075 instance tree (which must have the tag DW\-\_TAG\-\_subprogram).
1076
1077 In general, the structure and content of any given concrete
1078 inlined instance tree will be closely analogous to the
1079 structure and content of its associated abstract instance
1080 tree. There are a few exceptions:
1081
1082 \begin{enumerate}[1.]
1083 \item An entry in the concrete instance tree may be omitted if
1084 it contains only a DW\-\_AT\-\_abstract\-\_origin attribute and either
1085 has no children, or its children are omitted. Such entries
1086 would provide no useful information. In C\dash like languages,
1087 such entries frequently include types, including structure,
1088 union, class, and interface types; and members of types. If any
1089 entry within a concrete inlined instance tree needs to refer
1090 to an entity declared within the scope of the relevant inlined
1091 subroutine and for which no concrete instance entry exists,
1092 the reference should refer to the abstract instance entry.
1093
1094 \item Entries in the concrete instance tree which are associated
1095 with entries in the abstract instance tree such that neither
1096 has a DW\_AT\_name attribute, and neither is referenced by
1097 any other debugging information entry, may be omitted. This
1098 may happen for debugging information entries in the abstract
1099 instance trees that became unnecessary in the concrete instance
1100 tree because of additional information available there. For
1101 example, an anonymous variable might have been created and
1102 described in the abstract instance tree, but because of
1103 the actual parameters for a particular inlined expansion,
1104 it could be described as a constant value without the need
1105 for that separate debugging information entry.
1106
1107 \item A concrete instance tree may contain entries which do
1108 not correspond to entries in the abstract instance tree
1109 to describe new entities that are specific to a particular
1110 inlined expansion. In that case, they will not have associated
1111 entries in the abstract instance tree, should not contain
1112 DW\_AT\_abstract\_origin attributes, and must contain all their
1113 own attributes directly. This allows an abstract instance tree
1114 to omit debugging information entries for anonymous entities
1115 that are unlikely to be needed in most inlined expansions. In
1116 any expansion which deviates from that expectation, the
1117 entries can be described in its concrete inlined instance tree.
1118
1119 \end{enumerate}
1120
1121 \paragraph{Out-of-Line Instances of Inlined Subroutines}
1122 \label{chap:outoflineinstancesofinlinedsubroutines}
1123 Under some conditions, compilers may need to generate concrete
1124 executable instances of inlined subroutines other than at
1125 points where those subroutines are actually called. Such
1126 concrete instances of inlined subroutines are referred to as
1127 ``concrete out\dash of\dash line instances.''
1128
1129 \textit{In C++, for example, taking the address of a function declared
1130 to be inline can necessitate the generation of a concrete
1131 out\dash of\dash line instance of the given function.}
1132
1133 The DWARF representation of a concrete out\dash of\dash line instance
1134 of an inlined subroutine is essentially the same as for a
1135 concrete inlined instance of that subroutine (as described in
1136 the preceding section). The representation of such a concrete
1137 out\dash of\dash line instance makes use of DW\_AT\_abstract\_origin
1138 attributes in exactly the same way as they are used for
1139 a concrete inlined instance (that is, as references to
1140 corresponding entries within the associated abstract instance
1141 tree).
1142
1143 The differences between the DWARF representation of a
1144 concrete out\dash of\dash line instance of a given subroutine and the
1145 representation of a concrete inlined instance of that same
1146 subroutine are as follows:
1147
1148 \begin{enumerate}[1.]
1149 \item  The root entry for a concrete out\dash of\dash line instance
1150 of a given inlined subroutine has the same tag as does its
1151 associated (abstract) inlined subroutine entry (that is, tag
1152 DW\_TAG\_subprogram rather than DW\_TAG\_inlined\_subroutine).
1153
1154 \item The root entry for a concrete out\dash of\dash line instance tree
1155 is normally owned by the same parent entry that also owns
1156 the root entry of the associated abstract instance. However,
1157 it is not required that the abstract and out\dash of\dash line instance
1158 trees be owned by the same parent entry.
1159
1160 \end{enumerate}
1161
1162 \paragraph{Nested Inlined Subroutines}
1163 \label{nestedinlinedsubroutines}
1164 Some languages and compilers may permit the logical nesting of
1165 a subroutine within another subroutine, and may permit either
1166 the outer or the nested subroutine, or both, to be inlined.
1167
1168 For a non\dash inlined subroutine nested within an inlined
1169 subroutine, the nested subroutine is described normally in
1170 both the abstract and concrete inlined instance trees for
1171 the outer subroutine. All rules pertaining to the abstract
1172 and concrete instance trees for the outer subroutine apply
1173 also to the abstract and concrete instance entries for the
1174 nested subroutine.
1175
1176 For an inlined subroutine nested within another inlined
1177 subroutine, the following rules apply to their abstract and
1178 concrete instance trees:
1179
1180 \begin{enumerate}[1.]
1181 \item The abstract instance tree for the nested subroutine is
1182 described within the abstract instance tree for the outer
1183 subroutine according to the rules in 
1184 Section \refersec{chap:abstractinstances}, and
1185 without regard to the fact that it is within an outer abstract
1186 instance tree.
1187
1188 \item Any abstract instance tree for a nested subroutine is
1189 always omitted within the concrete instance tree for an
1190 outer subroutine.
1191
1192 \item  A concrete instance tree for a nested subroutine is
1193 always omitted within the abstract instance tree for an
1194 outer subroutine.
1195
1196 \item The concrete instance tree for any inlined or out-of-line
1197 expansion of the nested subroutine is described within a
1198 concrete instance tree for the outer subroutine according
1199 to the rules in 
1200 Sections \refersec{chap:concreteinlinedinstances} or 
1201 \refersec{chap:outoflineinstancesofinlinedsubroutines}
1202 , respectively,
1203 and without regard to the fact that it is within an outer
1204 concrete instance tree.
1205 \end{enumerate}
1206
1207 See Appendix \refersec{app:inliningexamples} 
1208 for discussion and examples.
1209
1210 \subsection{Trampolines}
1211 \label{chap:trampolines}
1212
1213 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1214 an intermediary in making a call to another subroutine. It may
1215 adjust parameters and/or the result (if any) as appropriate
1216 to the combined calling and called execution contexts.}
1217
1218 A trampoline is represented by a debugging information entry
1219 with the tag DW\-\_TAG\-\_subprogram or DW\-\_TAG\-\_inlined\-\_subroutine
1220 that has a DW\_AT\_trampoline attribute. The value of that
1221 attribute indicates the target subroutine of the trampoline,
1222 that is, the subroutine to which the trampoline passes
1223 control. (A trampoline entry may but need not also have a
1224 DW\_AT\_artificial attribute.)
1225
1226 The value of the trampoline attribute may be represented
1227 using any of the following forms, which are listed in order
1228 of preference:
1229
1230 \begin{itemize}
1231 \item If the value is of class reference, then the value
1232 specifies the debugging information entry of the target
1233 subprogram.
1234
1235 \item If the value is of class address, then the value is
1236 the relocated address of the target subprogram.
1237
1238 \item If the value is of class string, then the value is the
1239 (possibly mangled) name of the target subprogram.
1240
1241 \item If the value is of class flag, then the value true
1242 indicates that the containing subroutine is a trampoline but
1243 that the target subroutine is not known.
1244 \end{itemize}
1245
1246
1247 The target subprogram may itself be a trampoline. (A sequence
1248 of trampolines necessarily ends with a non\dash trampoline
1249 subprogram.)
1250
1251 \textit{In C++, trampolines may be used to implement derived virtual
1252 member functions; such trampolines typically adjust the
1253 implicit this pointer parameter in the course of passing
1254 control.  Other languages and environments may use trampolines
1255 in a manner sometimes known as transfer functions or transfer
1256 vectors.}
1257
1258 \textit{Trampolines may sometimes pass control to the target
1259 subprogram using a branch or jump instruction instead of a
1260 call instruction, thereby leaving no trace of their existence
1261 in the subsequent execution context. }
1262
1263 \textit{This attribute helps make it feasible for a debugger to arrange
1264 that stepping into a trampoline or setting a breakpoint in
1265 a trampoline will result in stepping into or setting the
1266 breakpoint in the target subroutine instead. This helps to
1267 hide the compiler generated subprogram from the user. }
1268
1269 \textit{If the target subroutine is not known, a debugger may choose
1270 to repeatedly step until control arrives in a new subroutine
1271 which can be assumed to be the target subroutine. }
1272
1273
1274
1275 \section{Lexical Block Entries}
1276 \label{chap:lexicalblockentries}
1277
1278 \textit{A lexical block is a bracketed sequence of source statements
1279 that may contain any number of declarations. In some languages
1280 (including C and C++), blocks can be nested within other
1281 blocks to any depth.}
1282
1283 A lexical block is represented by a debugging information
1284 entry with the tag DW\-\_TAG\-\_lexical\-\_block.
1285
1286 The lexical block entry may have either a DW\_AT\_low\_pc and
1287 DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges attribute
1288 whose values encode the contiguous or non-contiguous address
1289 ranges, respectively, of the machine instructions generated
1290 for the lexical block 
1291 (see Section \refersec{chap:codeaddressesandranges}).
1292
1293 If a name has been given to the lexical block in the source
1294 program, then the corresponding lexical block entry has a
1295 DW\_AT\_name attribute whose value is a null-terminated string
1296 containing the name of the lexical block as it appears in
1297 the source program.
1298
1299 \textit{This is not the same as a C or C++ label (see below).}
1300
1301 The lexical block entry owns debugging information entries that
1302 describe the declarations within that lexical block. There is
1303 one such debugging information entry for each local declaration
1304 of an identifier or inner lexical block.
1305
1306 \section{Label Entries}
1307 \label{chap:labelentries}
1308
1309 A label is a way of identifying a source statement. A labeled
1310 statement is usually the target of one or more ``go to''
1311 statements.
1312
1313 A label is represented by a debugging information entry with
1314 the tag DW\_TAG\_label. The entry for a label should be owned by
1315 the debugging information entry representing the scope within
1316 which the name of the label could be legally referenced within
1317 the source program.
1318
1319 The label entry has a DW\_AT\_low\_pc attribute whose value
1320 is the relocated address of the first machine instruction
1321 generated for the statement identified by the label in
1322 the source program.  The label entry also has a DW\_AT\_name
1323 attribute whose value is a null-terminated string containing
1324 the name of the label as it appears in the source program.
1325
1326
1327 \section{With Statement Entries}
1328 \label{chap:withstatemententries}
1329
1330 \textit{Both Pascal and Modula\dash 2 support the concept of a ``with''
1331 statement. The with statement specifies a sequence of
1332 executable statements within which the fields of a record
1333 variable may be referenced, unqualified by the name of the
1334 record variable.}
1335
1336 A with statement is represented by a debugging information
1337 entry with the tag DW\-\_TAG\-\_with\-\_stmt.
1338
1339 A with statement entry may have either a DW\_AT\_low\_pc and
1340 DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges attribute
1341 whose values encode the contiguous or non\dash contiguous address
1342 ranges, respectively, of the machine instructions generated
1343 for the with statement 
1344 (see Section \refersec{chap:codeaddressesandranges}).
1345
1346 The with statement entry has a DW\_AT\_type attribute, denoting
1347 the type of record whose fields may be referenced without full
1348 qualification within the body of the statement. It also has
1349 a DW\_AT\_location attribute, describing how to find the base
1350 address of the record object referenced within the body of
1351 the with statement.
1352
1353 \section{Try and Catch Block Entries}
1354 \label{chap:tryandcatchblockentries}
1355
1356 \textit{In C++ a lexical block may be designated as a ``catch
1357 block.'' A catch block is an exception handler that handles
1358 exceptions thrown by an immediately preceding ``try block.''
1359 A catch block designates the type of the exception that it
1360 can handle.}
1361
1362 A try block is represented by a debugging information entry
1363 with the tag DW\_TAG\_try\_block.  A catch block is represented by
1364 a debugging information entry with the tag DW\_TAG\_catch\_block.
1365
1366 Both try and catch block entries may have either a
1367 DW\_AT\_low\_pc and DW\_AT\_high\_pc pair of attributes or a
1368 DW\_AT\_ranges attribute whose values encode the contiguous
1369 or non- contiguous address ranges, respectively, of the
1370 machine instructions generated for the block (see Section
1371 \refersec{chap:codeaddressesandranges}).
1372
1373 Catch block entries have at least one child entry, an
1374 entry representing the type of exception accepted by
1375 that catch block. This child entry has one of the tags
1376 DW\_TAG\_formal\_parameter or DW\_TAG\_unspecified\_parameters,
1377 and will have the same form as other parameter entries.
1378
1379 The siblings immediately following a try block entry are its
1380 corresponding catch block entries.
1381
1382
1383
1384
1385
1386
1387