Initial commit of a work-in-progress of latex source
[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 FIXME REF , below)}
781 \end{enumerate}
782
783 \textit{Some languages support nested subroutines. In such languages,
784 it is possible to reference the local variables of an
785 outer subroutine from within an inner subroutine. The
786 DW\_AT\_static\_link and DW\_AT\_frame\_base attributes allow
787 debuggers to support this same kind of referencing.}
788
789 If a subroutine or entry point is nested, it may have a
790 DW\_AT\_static\_link attribute, whose value is a location
791 description that computes the frame base of the relevant
792 instance of the subroutine that immediately encloses the
793 subroutine or entry point.
794
795 In the context of supporting nested subroutines, the
796 DW\_AT\_frame\_base attribute value should obey the following
797 constraints:
798
799 \begin{enumerate}[1.]
800 \item It should compute a value that does not change during the
801 life of the procedure, and
802
803 \item The computed value should be unique among instances of
804 the same subroutine. (For typical DW\_AT\_frame\_base use, this
805 means that a recursive subroutine’s stack frame must have
806 non\dash zero size.)
807 \end{enumerate}
808
809 \textit{If a debugger is attempting to resolve an up\dash level reference
810 to a variable, it uses the nesting structure of DWARF to
811 determine which subroutine is the lexical parent and the
812 DW\_AT\_static\_link value to identify the appropriate active
813 frame of the parent. It can then attempt to find the reference
814 within the context of the parent.}
815
816
817
818 \subsection{Types Thrown by Exceptions}
819 \label{chap:typesthrownbyexceptions}
820
821 \textit{In C++ a subroutine may declare a set of types which
822 it may validly throw.}
823
824 If a subroutine explicitly declares that it may throw
825 an exception for one or more types, each such type is
826 represented by a debugging information entry with the tag
827 DW\-\_TAG\-\_thrown\-\_type.  Each such entry is a child of the entry
828 representing the subroutine that may throw this type. Each
829 thrown type entry contains a DW\-\_AT\-\_type attribute, whose
830 value is a reference to an entry describing the type of the
831 exception that may be thrown.
832
833 \subsection{Function Template Instantiations}
834 \label{chap:functiontemplateinstantiations}
835
836 \textit{In C++, a function template is a generic definition of
837 a function that is instantiated differently when called with
838 values of different types. DWARF does not represent the generic
839 template definition, but does represent each instantiation.}
840
841 A template instantiation is represented by a debugging
842 information entry with the tag DW\_TAG\_subprogram. With four
843 exceptions, such an entry will contain the same attributes and
844 will have the same types of child entries as would an entry
845 for a subroutine defined explicitly using the instantiation
846 types. The exceptions are:
847
848 \begin{enumerate}[1.]
849 \item Each formal parameterized type declaration appearing in the
850 template definition is represented by a debugging information
851 entry with the tag DW\-\_TAG\-\_template\-\_type\-\_parameter. Each
852 such entry has a DW\-\_AT\-\_name attribute, whose value is a
853 null\dash terminated string containing the name of the formal
854 type parameter as it appears in the source program. The
855 template type parameter entry also has a DW\_AT\_type attribute
856 describing the actual type by which the formal is replaced
857 for this instantiation.
858
859 \item The subprogram entry and each of its child entries reference
860 a template type parameter entry in any circumstance where
861 the template definition referenced a formal parameterized type.
862
863 \item If the compiler has generated a special compilation unit
864 to hold the template instantiation and that compilation unit
865 has a different name from the compilation unit containing
866 the template definition, the name attribute for the debugging
867 information entry representing that compilation unit is empty
868 or omitted.
869
870 \item If the subprogram entry representing the template
871 instantiation or any of its child entries contain declaration
872 coordinate attributes, those attributes refer to the source
873 for the template definition, not to any source generated
874 artificially by the compiler for this instantiation.
875 \end{enumerate}
876
877
878
879 \subsection{Inlinable and Inlined Subroutines}
880 A declaration or a definition of an inlinable subroutine
881 is represented by a debugging information entry with the
882 tag DW\_TAG\_subprogram. The entry for a subroutine that is
883 explicitly declared to be available for inline expansion or
884 that was expanded inline implicitly by the compiler has a
885 DW\_AT\_inline attribute whose value is an integer constant. The
886 set of values for the DW\_AT\_inline attribute is given in
887 Figure \refersec{fig:inlinecodes}.
888
889 \begin{figure}[here]
890 \centering
891 \caption{Inline codes}
892 \label{fig:inlinecodes}
893 \begin{tabular}{lp{9cm}}
894 Name&Meaning\\ \hline
895 DW\_INL\_not\_inlined & Not delared inline nor inlined by the
896   compiler(equivalent to the absense of the containing
897   DW\-\_AT\-\_linline attribute) \\
898 DW\_INL\_inlined & Not declared inline but inlined by the compiler \\
899 DW\_INL\_declared\_not\_inlined & Declared inline but 
900   not inlined by the compiler \\
901 DW\_INL\_declared\_inlined & Declared inline and inlined by the compiler \\
902 \end{tabular}
903 \end{figure}
904
905 \textit{In C++, a function or a constructor declared with
906 constexpr is implicitly declared inline. The abstract inline
907 instance (see below) is represented by a debugging information
908 entry with the tag DW\_TAG\_subprogram. Such an entry has a
909 DW\_AT\_inline attribute whose value is DW\_INL\_inlined.}
910
911
912 \paragraph{Abstract Instances}
913 \label{chap:abstractinstances}
914 Any debugging information entry that is owned (either
915 directly or indirectly) by a debugging information entry
916 that contains the DW\_AT\_inline attribute is referred to
917 as an “abstract instance entry.” Any subroutine entry
918 that contains a DW\_AT\_inline attribute whose value is other
919 than DW\_INL\_not\_inlined is known as an “abstract instance
920 root.” Any set of abstract instance entries that are all
921 children (either directly or indirectly) of some abstract
922 instance root, together with the root itself, is known as
923 an “abstract instance tree.” However, in the case where
924 an abstract instance tree is nested within another abstract
925 instance tree, the entries in the nested abstract instance
926 tree are not considered to be entries in the outer abstract
927 instance tree.
928
929 Each abstract instance root is either part of a larger
930 tree (which gives a context for the root) or uses
931 DW\_AT\_specification to refer to the declaration in context.
932
933 \textit{For example, in C++ the context might be a namespace
934 declaration or a class declaration.}
935
936 \textit{Abstract instance trees are defined so that no entry is part
937 of more than one abstract instance tree. This simplifies the
938 following descriptions.}
939
940 A debugging information entry that is a member of an abstract
941 instance tree should not contain any attributes which describe
942 aspects of the subroutine which vary between distinct inlined
943 expansions or distinct out\dash of\dash line expansions. For example,
944 the DW\-\_AT\-\_low\-\_pc,
945 DW\-\_AT\-\_high\-\_pc, DW\-\_AT\-\_ranges, 
946 DW\-\_AT\-\_entry\-\_pc, DW\-\_AT\-\_location,
947 DW\-\_AT\-\_return\-\_addr, DW\-\_AT\-\_start\-\_scope, and 
948 DW\-\_AT\-\_segment
949 attributes typically should be omitted; however, this list
950 is not exhaustive.
951
952 \textit{It would not make sense normally to put these attributes into
953 abstract instance entries since such entries do not represent
954 actual (concrete) instances and thus do not actually exist at
955 run\dash time.  However, 
956 see Appendix \refersec{app:inlineouteronenormalinner} 
957 for a contrary example.}
958
959 The rules for the relative location of entries belonging to
960 abstract instance trees are exactly the same as for other
961 similar types of entries that are not abstract. Specifically,
962 the rule that requires that an entry representing a declaration
963 be a direct child of the entry representing the scope of the
964 declaration applies equally to both abstract and non\dash abstract
965 entries. Also, the ordering rules for formal parameter entries,
966 member entries, and so on, all apply regardless of whether
967 or not a given entry is abstract.
968
969 \paragraph{Concrete Inlined Instances}
970 \label{chap:concreteinlinedinstances}
971
972 Each inline expansion of a subroutine is represented
973 by a debugging information entry with the tag
974 DW\_TAG\_inlined\_subroutine. Each such entry should be a direct
975 child of the entry that represents the scope within which
976 the inlining occurs.
977
978 Each inlined subroutine entry may have either a DW\_AT\_low\_pc
979 and DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges
980 attribute whose values encode the contiguous or non\dash contiguous
981 address ranges, respectively, of the machine instructions
982 generated for the inlined subroutine (see 
983 Section \refersec{chap:codeaddressesandranges}). An
984 inlined subroutine entry may also contain a DW\_AT\_entry\_pc
985 attribute, representing the first executable instruction of
986 the inline expansion (see 
987 Section \refersec{chap:entryaddress}).
988
989 An inlined subroutine entry may also have DW\-\_AT\-\_call\-\_file,
990 DW\-\_AT\-\_call\-\_line and DW\-\_AT\-\_call\-\_column attributes, 
991 each of whose
992 value is an integer constant. These attributes represent the
993 source file, source line number, and source column number,
994 respectively, of the first character of the statement or
995 expression that caused the inline expansion. The call file,
996 call line, and call column attributes are interpreted in
997 the same way as the declaration file, declaration line, and
998 declaration column attributes, respectively (see 
999 Section \refersec{chap:declarationcoordinates}).
1000
1001 The call file, call line and call column coordinates do not
1002 describe the coordinates of the subroutine declaration that
1003 was inlined, rather they describe the coordinates of the call.
1004
1005 An inlined subroutine entry may have a DW\_AT\_const\_expr
1006 attribute, which is a flag whose presence indicates that the
1007 subroutine has been evaluated as a compile\dash time constant. Such
1008 an entry may also have a DW\_AT\_const\_value attribute,
1009 whose value may be of any form that is appropriate for the
1010 representation of the subroutine's return value. The value of
1011 this attribute is the actual return value of the subroutine,
1012 represented as it would be on the target architecture.
1013
1014 \textit{In C++, if a function or a constructor declared with constexpr
1015 is called with constant expressions, then the corresponding
1016 concrete inlined instance has a DW\_AT\_const\_expr attribute,
1017 as well as a DW\_AT\_const\_value attribute whose value represents
1018 the actual return value of the concrete inlined instance.}
1019
1020 Any debugging information entry that is owned (either
1021 directly or indirectly) by a debugging information entry
1022 with the tag DW\_TAG\_inlined\_subroutine is referred to as a
1023 “concrete inlined instance entry.” Any entry that has
1024 the tag DW\_TAG\_inlined\_subroutine is known as a “concrete
1025 inlined instance root.” Any set of concrete inlined instance
1026 entries that are all children (either directly or indirectly)
1027 of some concrete inlined instance root, together with the root
1028 itself, is known as a ``concrete inlined instance tree.''
1029 However, in the case where a concrete inlined instance tree
1030 is nested within another concrete instance tree, the entries
1031 in the nested concrete instance tree are not considered to
1032 be entries in the outer concrete instance tree.
1033
1034 \textit{Concrete inlined instance trees are defined so that no entry
1035 is part of more than one concrete inlined instance tree. This
1036 simplifies later descriptions.}
1037
1038 Each concrete inlined instance tree is uniquely associated
1039 with one (and only one) abstract instance tree.
1040
1041 \textit{Note, however, that the reverse is not true. Any given abstract
1042 instance tree may be associated with several different concrete
1043 inlined instance trees, or may even be associated with zero
1044 concrete inlined instance trees.}
1045
1046 Concrete inlined instance entries may omit attributes that
1047 are not specific to the concrete instance (but present in
1048 the abstract instance) and need include only attributes that
1049 are specific to the concrete instance (but omitted in the
1050 abstract instance). In place of these omitted attributes, each
1051 concrete inlined instance entry has a DW\_AT\_abstract\_origin
1052 attribute that may be used to obtain the missing information
1053 (indirectly) from the associated abstract instance entry. The
1054 value of the abstract origin attribute is a reference to the
1055 associated abstract instance entry.
1056
1057 If an entry within a concrete inlined instance tree contains
1058 attributes describing the declaration coordinates of that
1059 entry, then those attributes should refer to the file, line
1060 and column of the original declaration of the subroutine,
1061 not to the point at which it was inlined. As a consequence,
1062 they may usually be omitted from any entry that has an abstract
1063 origin attribute.
1064
1065 For each pair of entries that are associated via a
1066 DW\-\_AT\-\_abstract\-\_origin attribute, both members of the pair
1067 have the same tag. So, for example, an entry with the tag
1068 DW\-\_TAG\-\_variable can only be associated with another entry
1069 that also has the tag DW\-\_TAG\-\_variable. The only exception
1070 to this rule is that the root of a concrete instance tree
1071 (which must always have the tag DW\-\_TAG\-\_\-inlined\_subroutine)
1072 can only be associated with the root of its associated abstract
1073 instance tree (which must have the tag DW\-\_TAG\-\_subprogram).
1074
1075 In general, the structure and content of any given concrete
1076 inlined instance tree will be closely analogous to the
1077 structure and content of its associated abstract instance
1078 tree. There are a few exceptions:
1079
1080 \begin{enumerate}[1.]
1081 \item An entry in the concrete instance tree may be omitted if
1082 it contains only a DW\-\_AT\-\_abstract\-\_origin attribute and either
1083 has no children, or its children are omitted. Such entries
1084 would provide no useful information. In C\dash like languages,
1085 such entries frequently include types, including structure,
1086 union, class, and interface types; and members of types. If any
1087 entry within a concrete inlined instance tree needs to refer
1088 to an entity declared within the scope of the relevant inlined
1089 subroutine and for which no concrete instance entry exists,
1090 the reference should refer to the abstract instance entry.
1091
1092 \item Entries in the concrete instance tree which are associated
1093 with entries in the abstract instance tree such that neither
1094 has a DW\_AT\_name attribute, and neither is referenced by
1095 any other debugging information entry, may be omitted. This
1096 may happen for debugging information entries in the abstract
1097 instance trees that became unnecessary in the concrete instance
1098 tree because of additional information available there. For
1099 example, an anonymous variable might have been created and
1100 described in the abstract instance tree, but because of
1101 the actual parameters for a particular inlined expansion,
1102 it could be described as a constant value without the need
1103 for that separate debugging information entry.
1104
1105 \item A concrete instance tree may contain entries which do
1106 not correspond to entries in the abstract instance tree
1107 to describe new entities that are specific to a particular
1108 inlined expansion. In that case, they will not have associated
1109 entries in the abstract instance tree, should not contain
1110 DW\_AT\_abstract\_origin attributes, and must contain all their
1111 own attributes directly. This allows an abstract instance tree
1112 to omit debugging information entries for anonymous entities
1113 that are unlikely to be needed in most inlined expansions. In
1114 any expansion which deviates from that expectation, the
1115 entries can be described in its concrete inlined instance tree.
1116
1117 \end{enumerate}
1118
1119 \paragraph{Out-of-Line Instances of Inlined Subroutines}
1120 \label{chap:outoflineinstancesofinlinedsubroutines}
1121 Under some conditions, compilers may need to generate concrete
1122 executable instances of inlined subroutines other than at
1123 points where those subroutines are actually called. Such
1124 concrete instances of inlined subroutines are referred to as
1125 ``concrete out\dash of\dash line instances.''
1126
1127 \textit{In C++, for example, taking the address of a function declared
1128 to be inline can necessitate the generation of a concrete
1129 out\dash of\dash line instance of the given function.}
1130
1131 The DWARF representation of a concrete out\dash of\dash line instance
1132 of an inlined subroutine is essentially the same as for a
1133 concrete inlined instance of that subroutine (as described in
1134 the preceding section). The representation of such a concrete
1135 out\dash of\dash line instance makes use of DW\_AT\_abstract\_origin
1136 attributes in exactly the same way as they are used for
1137 a concrete inlined instance (that is, as references to
1138 corresponding entries within the associated abstract instance
1139 tree).
1140
1141 The differences between the DWARF representation of a
1142 concrete out\dash of\dash line instance of a given subroutine and the
1143 representation of a concrete inlined instance of that same
1144 subroutine are as follows:
1145
1146 \begin{enumerate}[1.]
1147 \item  The root entry for a concrete out\dash of\dash line instance
1148 of a given inlined subroutine has the same tag as does its
1149 associated (abstract) inlined subroutine entry (that is, tag
1150 DW\_TAG\_subprogram rather than DW\_TAG\_inlined\_subroutine).
1151
1152 \item The root entry for a concrete out\dash of\dash line instance tree
1153 is normally owned by the same parent entry that also owns
1154 the root entry of the associated abstract instance. However,
1155 it is not required that the abstract and out\dash of\dash line instance
1156 trees be owned by the same parent entry.
1157
1158 \end{enumerate}
1159
1160 \paragraph{Nested Inlined Subroutines}
1161 \label{nestedinlinedsubroutines}
1162 Some languages and compilers may permit the logical nesting of
1163 a subroutine within another subroutine, and may permit either
1164 the outer or the nested subroutine, or both, to be inlined.
1165
1166 For a non\dash inlined subroutine nested within an inlined
1167 subroutine, the nested subroutine is described normally in
1168 both the abstract and concrete inlined instance trees for
1169 the outer subroutine. All rules pertaining to the abstract
1170 and concrete instance trees for the outer subroutine apply
1171 also to the abstract and concrete instance entries for the
1172 nested subroutine.
1173
1174 For an inlined subroutine nested within another inlined
1175 subroutine, the following rules apply to their abstract and
1176 concrete instance trees:
1177
1178 \begin{enumerate}[1.]
1179 \item The abstract instance tree for the nested subroutine is
1180 described within the abstract instance tree for the outer
1181 subroutine according to the rules in 
1182 Section \refersec{chap:abstractinstances}, and
1183 without regard to the fact that it is within an outer abstract
1184 instance tree.
1185
1186 \item Any abstract instance tree for a nested subroutine is
1187 always omitted within the concrete instance tree for an
1188 outer subroutine.
1189
1190 \item  A concrete instance tree for a nested subroutine is
1191 always omitted within the abstract instance tree for an
1192 outer subroutine.
1193
1194 \item The concrete instance tree for any inlined or out-of-line
1195 expansion of the nested subroutine is described within a
1196 concrete instance tree for the outer subroutine according
1197 to the rules in 
1198 Sections \refersec{chap:concreteinlinedinstances} or 
1199 \refersec{chap:outoflineinstancesofinlinedsubroutines}
1200 , respectively,
1201 and without regard to the fact that it is within an outer
1202 concrete instance tree.
1203 \end{enumerate}
1204
1205 See Appendix \refersec{app:inliningexamples} 
1206 for discussion and examples.
1207
1208 \subsection{Trampolines}
1209 \label{chap:trampolines}
1210
1211 \textit{A trampoline is a compiler\dash generated subroutine that serves as
1212 an intermediary in making a call to another subroutine. It may
1213 adjust parameters and/or the result (if any) as appropriate
1214 to the combined calling and called execution contexts.}
1215
1216 A trampoline is represented by a debugging information entry
1217 with the tag DW\-\_TAG\-\_subprogram or DW\-\_TAG\-\_inlined\-\_subroutine
1218 that has a DW\_AT\_trampoline attribute. The value of that
1219 attribute indicates the target subroutine of the trampoline,
1220 that is, the subroutine to which the trampoline passes
1221 control. (A trampoline entry may but need not also have a
1222 DW\_AT\_artificial attribute.)
1223
1224 The value of the trampoline attribute may be represented
1225 using any of the following forms, which are listed in order
1226 of preference:
1227
1228 \begin{itemize}
1229 \item If the value is of class reference, then the value
1230 specifies the debugging information entry of the target
1231 subprogram.
1232
1233 \item If the value is of class address, then the value is
1234 the relocated address of the target subprogram.
1235
1236 \item If the value is of class string, then the value is the
1237 (possibly mangled) name of the target subprogram.
1238
1239 \item If the value is of class flag, then the value true
1240 indicates that the containing subroutine is a trampoline but
1241 that the target subroutine is not known.
1242 \end{itemize}
1243
1244
1245 The target subprogram may itself be a trampoline. (A sequence
1246 of trampolines necessarily ends with a non\dash trampoline
1247 subprogram.)
1248
1249 \textit{In C++, trampolines may be used to implement derived virtual
1250 member functions; such trampolines typically adjust the
1251 implicit this pointer parameter in the course of passing
1252 control.  Other languages and environments may use trampolines
1253 in a manner sometimes known as transfer functions or transfer
1254 vectors.}
1255
1256 \textit{Trampolines may sometimes pass control to the target
1257 subprogram using a branch or jump instruction instead of a
1258 call instruction, thereby leaving no trace of their existence
1259 in the subsequent execution context. }
1260
1261 \textit{This attribute helps make it feasible for a debugger to arrange
1262 that stepping into a trampoline or setting a breakpoint in
1263 a trampoline will result in stepping into or setting the
1264 breakpoint in the target subroutine instead. This helps to
1265 hide the compiler generated subprogram from the user. }
1266
1267 \textit{If the target subroutine is not known, a debugger may choose
1268 to repeatedly step until control arrives in a new subroutine
1269 which can be assumed to be the target subroutine. }
1270
1271
1272
1273 \section{Lexical Block Entries}
1274 \label{chap:lexicalblockentries}
1275
1276 \textit{A lexical block is a bracketed sequence of source statements
1277 that may contain any number of declarations. In some languages
1278 (including C and C++), blocks can be nested within other
1279 blocks to any depth.}
1280
1281 A lexical block is represented by a debugging information
1282 entry with the tag DW\-\_TAG\-\_lexical\-\_block.
1283
1284 The lexical block entry may have either a DW\_AT\_low\_pc and
1285 DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges attribute
1286 whose values encode the contiguous or non-contiguous address
1287 ranges, respectively, of the machine instructions generated
1288 for the lexical block 
1289 (see Section \refersec{chap:codeaddressesandranges}).
1290
1291 If a name has been given to the lexical block in the source
1292 program, then the corresponding lexical block entry has a
1293 DW\_AT\_name attribute whose value is a null-terminated string
1294 containing the name of the lexical block as it appears in
1295 the source program.
1296
1297 \textit{This is not the same as a C or C++ label (see below).}
1298
1299 The lexical block entry owns debugging information entries that
1300 describe the declarations within that lexical block. There is
1301 one such debugging information entry for each local declaration
1302 of an identifier or inner lexical block.
1303
1304 \section{Label Entries}
1305 \label{chap:labelentries}
1306
1307 A label is a way of identifying a source statement. A labeled
1308 statement is usually the target of one or more ``go to''
1309 statements.
1310
1311 A label is represented by a debugging information entry with
1312 the tag DW\_TAG\_label. The entry for a label should be owned by
1313 the debugging information entry representing the scope within
1314 which the name of the label could be legally referenced within
1315 the source program.
1316
1317 The label entry has a DW\_AT\_low\_pc attribute whose value
1318 is the relocated address of the first machine instruction
1319 generated for the statement identified by the label in
1320 the source program.  The label entry also has a DW\_AT\_name
1321 attribute whose value is a null-terminated string containing
1322 the name of the label as it appears in the source program.
1323
1324
1325 \section{With Statement Entries}
1326 \label{chap:withstatemententries}
1327
1328 \textit{Both Pascal and Modula\dash 2 support the concept of a ``with''
1329 statement. The with statement specifies a sequence of
1330 executable statements within which the fields of a record
1331 variable may be referenced, unqualified by the name of the
1332 record variable.}
1333
1334 A with statement is represented by a debugging information
1335 entry with the tag DW\-\_TAG\-\_with\-\_stmt.
1336
1337 A with statement entry may have either a DW\_AT\_low\_pc and
1338 DW\_AT\_high\_pc pair of attributes or a DW\_AT\_ranges attribute
1339 whose values encode the contiguous or non\dash contiguous address
1340 ranges, respectively, of the machine instructions generated
1341 for the with statement 
1342 (see Section \refersec{chap:codeaddressesandranges}).
1343
1344 The with statement entry has a DW\_AT\_type attribute, denoting
1345 the type of record whose fields may be referenced without full
1346 qualification within the body of the statement. It also has
1347 a DW\_AT\_location attribute, describing how to find the base
1348 address of the record object referenced within the body of
1349 the with statement.
1350
1351 \section{Try and Catch Block Entries}
1352 \label{chap:tryandcatchblockentries}
1353
1354 \textit{In C++ a lexical block may be designated as a ``catch
1355 block.'' A catch block is an exception handler that handles
1356 exceptions thrown by an immediately preceding ``try block.''
1357 A catch block designates the type of the exception that it
1358 can handle.}
1359
1360 A try block is represented by a debugging information entry
1361 with the tag DW\_TAG\_try\_block.  A catch block is represented by
1362 a debugging information entry with the tag DW\_TAG\_catch\_block.
1363
1364 Both try and catch block entries may have either a
1365 DW\_AT\_low\_pc and DW\_AT\_high\_pc pair of attributes or a
1366 DW\_AT\_ranges attribute whose values encode the contiguous
1367 or non- contiguous address ranges, respectively, of the
1368 machine instructions generated for the block (see Section
1369 \refersec{chap:codeaddressesandranges}).
1370
1371 Catch block entries have at least one child entry, an
1372 entry representing the type of exception accepted by
1373 that catch block. This child entry has one of the tags
1374 DW\_TAG\_formal\_parameter or DW\_TAG\_unspecified\_parameters,
1375 and will have the same form as other parameter entries.
1376
1377 The siblings immediately following a try block entry are its
1378 corresponding catch block entries.
1379
1380
1381
1382
1383
1384
1385