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