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