Fix hot link problem found on page 400.
[dwarf-doc.git] / dwarf5 / latexdoc / introduction.tex
1 \chapter{Introduction}
2 \label{chap:introduction}
3 \pagenumbering{arabic}
4 This document defines a format for describing programs to
5 facilitate user source level debugging. This description
6 can be generated by compilers, assemblers and linkage
7 editors. It can be used by debuggers and other tools. 
8 The debugging information format does not favor the design of any
9 compiler or debugger. 
10 Instead, the goal is to create a method
11 of communicating an accurate picture of the source program
12 to any debugger in a form that is extensible to different
13 languages while retaining compatibility.
14   
15 The design of the
16 debugging information format is open-ended, allowing for
17 the addition of new debugging information to accommodate new
18 languages or debugger capabilities while remaining compatible
19 with other languages or different debuggers.
20
21 \section{Purpose and Scope}
22 The debugging information format described in this document is
23 designed to meet the symbolic, source-level debugging needs of
24 different languages in a unified fashion by requiring language
25 independent debugging information whenever possible.  
26 Aspects
27 of individual languages, such as \addtoindex{C++} virtual functions or
28 \addtoindex{Fortran} common 
29 \nolink{blocks}, are accommodated by creating attributes
30 that are used only for those languages. 
31 This document is
32 believed to cover most debugging information needs of 
33 \addtoindex{Ada},
34 \addtoindex{C}, \addtoindex{C++}, \addtoindex{COBOL}, 
35 and \addtoindex{Fortran}; it also covers the basic needs
36 of various other languages.
37
38 This document describes \DWARFVersionV,
39 the fifth generation
40 of debugging information based on the DWARF format. 
41 \DWARFVersionV{} extends \DWARFVersionIV{}
42 in a compatible manner.
43
44 The intended audience for this document is the developers
45 of both producers and consumers of debugging information,
46 typically compilers, debuggers and other tools that need to
47 interpret a binary program in terms of its original source.
48
49
50 \section{Overview}
51
52 There are two major pieces to the description of the DWARF
53 format in this document. The first piece is the informational
54 content of the debugging entries. The second piece is the
55 way the debugging information is encoded and represented in
56 an object file.
57
58 The informational content is described in 
59 Sections \ref{chap:generaldescription} 
60 through
61 \ref{chap:otherdebugginginformation}. 
62 Section  \ref{chap:generaldescription}
63 describes the overall structure of the information
64 and attributes that is common to many or all of the different
65 debugging information entries. 
66 Sections \ref{chap:programscopeentries}, 
67 \ref{chap:dataobjectandobjectlistentries} and 
68 \ref{chap:typeentries} describe
69 the specific debugging information entries and how they
70 communicate the necessary information about the source program
71 to a debugger. 
72 Section \ref{chap:otherdebugginginformation} 
73 describes debugging information
74 contained outside of the debugging information entries. The
75 encoding of the DWARF information is presented in 
76 Section \ref{datarep:datarepresentation}.
77
78 This organization closely follows that used in the 
79 \DWARFVersionIV{} document. Except where needed to incorporate
80 new material or to correct errors, the \DWARFVersionIV{}
81 text is generally reused in this document with little or
82 no modification.
83
84 In the following sections, text in normal font describes
85 required aspects of the DWARF format.  Text in \textit{italics} is
86 explanatory or supplementary material, and not part of the
87 format definition itself. The several appendices consist only
88 of explanatory or supplementary material, and are not part
89 of the formal definition.
90
91 \bb
92 \section{Objectives and Rationale}
93
94 DWARF has had a set of objectives since its inception which have 
95 guided the design and evolution of the debugging format.  A discussion 
96 of these objectives and the rationale behind them may help with an 
97 understanding of the DWARF Debugging Format. 
98
99 Although DWARF Version 1 was developed in the late 1980's as a 
100 format to support debugging C programs written for AT\&T hardware 
101 running SVR4, \DWARFVersionII{} and later has evolved far beyond 
102 this origin. One difference between DWARF and other object formats 
103 is that the latter are often specific to a particular language, 
104 architecture, and/or operating system. 
105
106 \subsection{Language Independence}
107 DWARF is applicable to a broad range of existing procedural 
108 languages and is designed to be extensible to future languages.  
109 These languages may be considered to be "C-like" but the 
110 characteristics of C are not incorporated into DWARF Version 2 
111 and later, unlike DWARF Version 1 and other debugging formats.  
112 DWARF abstracts concepts as much as possible so that the 
113 description can be used to describe a program in any language. 
114 As an example, the DWARF descriptions used to describe C functions, 
115 Pascal subroutines, and Fortran subprograms are all the same, 
116 with different attributes used to specify the differences between 
117 these similar programming language features. 
118
119 On occasion, there is a feature which is specific to one 
120 particular language and which doesn't appear to have more 
121 general application.  For these, DWARF has a description 
122 designed to meet the language requirements, although, to the 
123 extent possible, an effort is made to generalize the attribute. 
124 An example of this is the \DWTAGconditionNAME{} DIE, which is 
125 used to describe \addtoindex{COBOL} level 88 conditions, which 
126 is described in abstract terms rather than COBOL-specific terms.  
127 Conceivably, this TAG might be used with a different language 
128 which had similar functionality. 
129
130 \subsection{Architecture Independence}
131 DWARF can be used with a wide range of processor architectures, 
132 whether byte or word oriented, linear or segmented, with any 
133 word or byte size.  DWARF can be used with Von Neumann architectures, 
134 using a single address space for both code and data; Harvard 
135 architectures, with separate code and data address spaces; and 
136 potentially for other architectures such as DSPs with their 
137 idiosyncratic memory organizations.  DWARF can be used with 
138 common register-oriented architectures or with stack architectures. 
139
140 DWARF assumes that memory has individual units (words or bytes) 
141 which have unique addresses which are ordered.  (Some architectures 
142 like the i386 can represent the same physical machine location with 
143 different segment and offset pairs.  Identifying aliases is an 
144 implementation issue.)
145
146 \subsection{Operating System Independence}
147 DWARF is widely associated with SVR4 Unix and similar operating 
148 systems like BSD and Linux.  DWARF fits well with the section 
149 organization of the ELF object file format. Nonetheless, DWARF 
150 attempts to be independent of either the OS or the object file 
151 format.  There have been implementations of DWARF debugging 
152 data in OMF or COFF object files. 
153
154 DWARF assumes that any object file format will be able to 
155 distinguish the various DWARF data sections in some fashion, 
156 preferably by name. 
157
158 DWARF makes a few assumptions about functionality provided by 
159 the underlying operating system.  DWARF data sections can be 
160 read sequentially and independently, for example, to read the 
161 \dotdebugabbrev{} section before the \dotdebuginfo{} section.  
162 Each DWARF data section is a sequential sequence of 8-bit bytes, 
163 numbered starting with zero.  The presence of offsets from one 
164 DWARF data section into other data sections does not imply that 
165 the underlying OS must be able to position files randomly; a 
166 data section could be read sequentially and indexed using the offset. 
167
168 \subsection{Compact Data Representation} 
169 The DWARF description is designed to be a compact file-oriented 
170 representation. In most cases, it is anticipated that DWARF 
171 debug data will be read by a consumer (usually a debugger) and 
172 onverted into a more efficiently accessed internal representation.  
173 For the most part, the DWARF data in a section is not the same as 
174 this internal representation. 
175
176 There are several encodings which achieve this goal, such as the 
177 TAG and attribute abbreviations or the line number encoding.  
178 References from one section to another, especially to refer to 
179 strings, allow these sections to be compacted to eliminate 
180 duplicate data. 
181
182 There are multiple schemes for eliminating duplicate data or 
183 reducing the size of the DWARF debug data associated with a 
184 given file.  These include COMDAT, used to eliminate duplicate 
185 function or data definitions, the split DWARF object files 
186 which allow a consumer to find DWARF data in files other than 
187 the executable, or the type units, which allow similar type 
188 definitions from multiple compilations to be combined. 
189
190 There is a tension between this objective and the following 
191 objective. Every compaction scheme results in more processing 
192 which needs to be performed to process the DWARF debug data. 
193
194 \subsection{Efficient Processing} 
195 DWARF is designed to be processed efficiently, so that a 
196 producer (a compiler) can generate the debug descriptions 
197 incrementally and a consumer can read only the descriptions 
198 which it needs at a given time. The data formats are designed 
199 to be efficiently interpreted by a consumer.
200
201 As mentioned, there is a tension between this objective and 
202 the preceding one.  A DWARF data representation which resembles 
203 an internal data representation may lead to faster processing, 
204 but at the expense of larger data files. This may also constrain 
205 the possible implementations.
206
207 \subsection{Implementation Independence}
208 DWARF attempts to allow developers the greatest flexibility 
209 in designing implementations, without mandating any particular 
210 design decisions. Issues which can be described as 
211 \doublequote{Quality of Implementation} are avoided.
212
213 \subsection{Explicit rather than Implicit Description}
214 DWARF describes the source to object translation explicitly 
215 rather than using common practice or convention as an implicit 
216 understanding between producer and consumer.  For example, where 
217 other debugging formats assume that a debugger knows how to 
218 unwind the stack, moving from one stack frame to the next using 
219 implicit knowledge about the architecture or operating system, 
220 DWARF makes this explicit in the Call Frame Information description.
221
222 \subsection{Avoid Duplication of Information}
223 DWARF has a goal of describing characteristics of a program once, 
224 rather than repeating the same information multiple times.  The 
225 string sections can be compacted to eliminate duplicate strings, 
226 for example.  Other compaction schemes or references between 
227 ections support this. Whether a particular implementation is 
228 effective at eliminating duplicate data, or even attempts to, 
229 is a Quality of Implementation issue.  
230
231 \subsection{Leverage Other Standards}
232 Where another standard exists which describes how to interpret 
233 aspects of a program, DWARF defers to that standard rather than 
234 attempting to duplicate the description.  For example, C++ has 
235 pecific rules for deciding which function to call depending 
236 name, scope, argument types, and other factors.  DWARF describes 
237 the functions and arguments, but doesn't attempt to describe 
238 how one would be selected by a consumer performing any particular 
239 operation.
240
241 \subsection{Limited Dependence on Tools}
242 DWARF data is designed so that it can be processed by commonly 
243 available assemblers, linkers, and other support programs, 
244 without requiring additional functionality specifically to 
245 support DWARF data.  This may require the implementer to be 
246 careful that they do not generate DWARF data which cannot be 
247 processed by these programs.  Conversely, an assembler which 
248 can generate LEB128 values may allow the compiler to generate 
249 more compact descriptions, and a linker which understands the 
250 format of string sections can merge these sections.  Whether 
251 or not an implementation includes these functions is a Quality 
252 of Implementation issue, not mandated by the DWARF specification.
253
254 \subsection{Separate Description from Implementation}
255 DWARF intends to describe the translation of a program from 
256 source to object, while neither mandating any particular design 
257 nor making any other design difficult.  For example, DWARF 
258 describes how the arguments and local variables in a function 
259 are to be described, but doesn't specify how this data is 
260 collected or organized by a producer.  Where a particular DWARF 
261 feature anticipates that it will be implemented in a certain 
262 fashion, non-normative text will suggest but not require this design.
263
264 \subsection{Permissive rather than Prescriptive}
265 The DWARF Standard specifies the meaning of DWARF descriptions.  
266 It does not specify what a particular producer should generate 
267 for any source to object conversion, nor what a particular 
268 consumer should do with this description.  DWARF is permissive, 
269 allowing different producer to generate different descriptions 
270 for the same source to object conversion.  As long as the DWARF 
271 description follows this specification, the producer is 
272 generating valid DWARF.
273 For example, DWARF allows producers to identify the end of a 
274 function prologue in the Line Information so that a debugger 
275 can stop at this location.  A producer which does this is 
276 generating valid DWARF, as is another which doesn't.  
277
278 \subsection{Vendor Extensibility}
279 \eb
280 This document does not attempt to cover all interesting
281 languages or even to cover all of the possible debugging
282 information needs for its primary target languages. 
283 Therefore,
284 the document provides vendors a way to define their own
285 debugging information tags, attributes, base type encodings,
286 location operations, language names, calling conventions and
287 call frame instructions by reserving a subset of the valid
288 values for these constructs for vendor specific additions
289 and defining related naming conventions. 
290 Vendors may also use
291 debugging information entries and attributes defined here in
292 new situations. 
293 Future versions of this document will not use
294 names or values reserved for vendor specific additions. 
295 All
296 names and values not reserved for vendor additions, however,
297 are reserved for future versions of this document.
298
299 \bb
300 Where this specification provides a means for
301 \eb
302 describing the source language, implementors are expected
303 to adhere to that specification. 
304 For language features that
305 are not supported, implementors may use existing attributes
306 in novel ways or add vendor-defined attributes. 
307 Implementors
308 who make extensions are strongly encouraged to design them
309 to be compatible with this specification in the absence of
310 those extensions.
311
312 The DWARF format is organized so that a consumer can skip over
313 data which it does not recognize. 
314 This may allow a consumer
315 to read and process files generated according to a later
316 version of this standard or which contain vendor extensions,
317 albeit possibly in a degraded manner.
318
319 \section{Changes from Version 4 to Version 5}
320 \addtoindexx{DWARF Version 5}
321 The following is a list of the major changes made to the DWARF Debugging Information
322 Format since Version 4 was published. The list is not meant to be exhaustive.
323 \begin{itemize}
324 \item The \dotdebugtypes{}
325 %\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
326 section introduced in \DWARFVersionIV{} 
327 is eliminated and its contents instead contained in \dotdebuginfo{} sections
328 to facilitate other changes.
329 \item Add support for collecting common DWARF information (DIEs and macro definitions)
330 across multiple executable and shared files and keeping it in a single
331 \addtoindex{supplementary object file}.
332 \item A new line number program header design provides the ability to 
333 use an MD5 hash to validate source file version in use, allows pooling 
334 of directory and file name strings and makes provision for vendor-defined
335 extensions. It also adds a string section specific to the line number table 
336 (\dotdebuglinestr)
337 to properly support the common practice of stripping all DWARF sections
338 except for line number information.
339 \needlines{4}
340 \item Add a split object file and package representations to allow most 
341 DWARF information to be compacted and/or kept separate from an executable 
342 or shared image. This includes new sections 
343 \dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo, 
344 \dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
345 \dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{} 
346 together with new forms of attribute value for referencing these sections.
347 This enhances DWARF support for very large programs by saving space 
348 and improving link times.
349 \item Replace the \dotdebugmacinfo{} macro information representation with
350 a much more compact \dotdebugmacro{} representation.
351 \item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
352 with a single and more functional name index section, \dotdebugnames{}.
353 \item Add a new debugging information entry (\DWTAGcallsiteNAME) and related 
354 attributes and DWARF expression operators to describe call site information, 
355 including identification of tail calls and tail recursion.
356 This facilitates debugging of optimized code.
357 \item Add improved support for \addtoindex{FORTRAN} assumed rank arrays 
358 (\DWTAGgenericsubrangeNAME), dynamic rank arrays (\DWATrankNAME)
359 and co-arrays (\DWTAGcoarraytypeNAME{}).
360 \item Add a new option to allow debuggers and other DWARF consumers to
361 support a DWARF expression stack containing typed values.
362 \item Add improved support for the \addtoindex{C++} \texttt{auto}
363 return type, deleted member functions (\DWATdeletedNAME), as well as defaulted 
364 constructors and destructors (\DWATdefaultedNAME).
365 \item Add a new attribute, \DWATnoreturnNAME{}, to identify 
366 a subprogram that does not return to its caller.
367 \item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
368 Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
369 Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
370 \item Numerous other more minor additions to improve functionality
371 and performance.
372 \end{itemize}
373
374 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
375 \begin{itemize}
376 \item The compilation unit header (in the \dotdebuginfo{} section) has
377 a new \HFNunittype{} field.
378 \needlines{4}
379 \item New operand forms for attribute values are defined 
380 (\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, 
381 \DWFORMrefsupNAME, \DWFORMstrpsupNAME{} and \DWFORMstrxNAME).
382 (Because a pre-DWARF Version 5 consumer will not be able to interpret 
383 these even to ignore and skip over them, such new forms must be 
384 considered incompatible.)
385 \item The line number table header (in the \dotdebugline{} section) 
386 is substantially revised.
387 \needlines{4}
388 \item A location list entry (see Section \refersec{chap:locationlists}) 
389 with the address range \mbox{(0, \textit{maximum-address})} is defined 
390 as the new default location list entry.
391 \item In a string type (see Section \refersec{chap:stringtypeentries}), 
392 a \DWATbytesizeNAME{} attribute is defined to always describe the size 
393 of the string type. (Previously
394 it described the size of the optional string length data field if the 
395 \DWATstringlengthNAME{} attribute was present.)
396 \end{itemize}
397
398 While not strictly an incompatibility, the macro information 
399 representation is completely new; further, producers 
400 and consumers may optionally continue to support the older 
401 representation. While the two representations cannot both be 
402 used in the same compilation unit, they can co-exist in 
403 executable or shared images.
404
405 Similar comments apply to replacement of the \dotdebugpubnames{} 
406 and \dotdebugpubtypes{} sections with the new \dotdebugnames{} 
407 section.
408
409 \needlines{4}
410 \section{Changes from Version 3 to Version 4}
411 \addtoindexx{DWARF Version 4}
412 The following is a list of the major changes made to the 
413 DWARF Debugging Information Format since Version 3 was 
414 published. The list is not meant to be exhaustive.
415 \begin{itemize}
416 \item Reformulate 
417 Section 2.6 (Location Descriptions) 
418 to better distinguish DWARF location descriptions, which
419 compute the location where a value is found (such as an 
420 address in memory or a register name) from DWARF expressions, 
421 which compute a final value (such as an array bound).
422 \item Add support for bundled instructions on machine architectures 
423 where instructions do not occupy a whole number of bytes.
424 \item Add a new attribute form for section offsets, 
425 \DWFORMsecoffsetNAME,\addtoindexx{section offset}
426 to replace the use of 
427 \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
428 \item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
429 program.
430 \item Define default array lower bound values for each supported language.
431 \item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
432 improve compression and duplicate elimination of DWARF information.
433 \item Add support for new \addtoindex{C++} language constructs, including rvalue references, generalized
434 constant expressions, Unicode character types and template aliases.
435 \item Clarify and generalize support for packed arrays and structures.
436 \item Add new line number table support to facilitate profile based compiler optimization.
437 \item Add additional support for template parameters in instantiations.
438 \item Add support for strongly typed enumerations in languages (such as \addtoindex{C++}) that have two
439 kinds of enumeration declarations.
440 \end{itemize}
441 \addtoindex{DWARF Version 4} is compatible with 
442 \addtoindex{DWARF Version 3} except as follows:
443 \begin{itemize}
444 \item DWARF attributes that use any of the new forms of attribute value representation (for
445 section offsets, flag compression, type signature references, and so on) cannot be read by
446 \addtoindex{DWARF Version 3}
447 consumers because the consumer will not know how to skip over the
448 unexpected form of data.
449 \item DWARF frame and line number table sections include additional fields that affect the location
450 and interpretation of other data in the section.
451 \end{itemize}
452
453 \section{Changes from Version 2 to Version 3}
454 \addtoindexx{DWARF Version 3}
455 The following is a list of the major differences between
456 Version 2 and Version 3 of the DWARF Debugging Information
457 Format. The list is not meant to be exhaustive.
458 \begin{itemize}
459 \item
460 Make provision for DWARF information files that are larger
461 than 4 GBytes.
462 \item
463 Allow attributes to refer to debugging information entries
464 in other shared libraries.
465 \item
466 Add support for \addtoindex{Fortran 90} modules as well as allocatable
467 array and pointer types.
468 \item
469 Add additional base types for \addtoindex{C} (as revised for 1999).
470 \item
471 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
472 \item
473 Add namespace support for \addtoindex{C++}.
474 \item
475 Add an optional section for global type names (similar to
476 the global section for objects and functions).
477 \item
478 Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
479 \item
480 Add improved support for optimized code (discontiguous
481 scopes, end of prologue determination, multiple section
482 code generation).  
483 \item Improve the ability to eliminate
484 duplicate DWARF information during linking.  
485 \end{itemize}
486
487 \addtoindex{DWARF Version 3}
488 is compatible with 
489 \addtoindex{DWARF Version 2} except as follows:
490 \begin{itemize}
491 \item
492 Certain very large values of the initial length fields that
493 begin DWARF sections as well as certain structures are reserved
494 to act as escape codes for future extension; one such extension
495 is defined to increase the possible size of DWARF descriptions
496 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
497 \item
498 References that use the attribute form 
499 \DWFORMrefaddrNAME{}
500 are specified to be four bytes in the DWARF 32-bit format and
501 eight bytes in the DWARF 64-bit format, while 
502 \addtoindex{DWARF Version 2} 
503 specifies that such references have the same size as an
504 address on the target system (see Sections 
505 \refersec{datarep:32bitand64bitdwarfformats} and 
506 \refersec{datarep:attributeencodings}).
507 \item
508 The return\_address\_register field in a Common Information
509 Entry record for call frame information is changed to unsigned
510 LEB representation (see Section 
511 \refersec{chap:structureofcallframeinformation}).
512 \end{itemize}
513
514 \section{Changes from Version 1 to Version 2}
515 \addtoindex{DWARF Version 2} 
516 describes the second generation of debugging
517 information based on the DWARF format. While 
518 \addtoindex{DWARF Version 2}
519 provides new debugging information not available in
520 Version 1, the primary focus of the changes for Version
521 2 is the representation of the information, rather than
522 the information content itself. The basic structure of
523 the Version 2 format remains as in Version 1: the debugging
524 information is represented as a series of debugging information
525 entries, each containing one or more attributes (name/value
526 pairs). The Version 2 representation, however, is much more
527 compact than the Version 1 representation. In some cases,
528 this greater density has been achieved at the expense of
529 additional complexity or greater difficulty in producing and
530 processing the DWARF information. The definers believe that the
531 reduction in I/O and in memory paging should more than make
532 up for any increase in processing time.  
533
534 \needlines{5}
535 The representation
536 of information changed from Version 1 to Version 2, so that
537 Version 2 DWARF information is not binary compatible with
538 Version 1 information. To make it easier for consumers to
539 support both Version 1 and Version 2 DWARF information, the
540 Version 2 information has been moved to a different object
541 file section, \dotdebuginfo{}.  
542
543 \textit{
544 A summary of the major changes made in 
545 \addtoindex{DWARF Version 2}
546 compared to the DWARF Version 1 may be found in the 
547 \addtoindex{DWARF Version 2}
548 document.
549 }
550