de84adbacbad7c50236f20a57eb2c40501f2f395
[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 guided the design and evolution of the debugging format.  A discussion of these objectives and the rationale behind them may help with an understanding of the DWARF Debugging Format. 
95
96 Although DWARF Version 1 was developed in the late 1980's as a format to support debugging C programs written for AT\&T hardware running SVR4, DWARF Version 2 and later has evolved far beyond this origin. One difference between DWARF and other object formats is that the latter are often specific to a particular language, architecture, and/or operating system. 
97
98 \subsection{Language Independence}
99 DWARF is applicable to a broad range of existing procedural languages and is designed to be extensible to future languages.  These languages may be considered to be "C-like" but the characteristics of C are not incorporated into DWARF Version 2 and later, unlike DWARF Version 1 and other debugging formats.  DWARF abstracts concepts as much as possible so that the description can be used to describe a program in any language. As an example, the DWARF descriptions used to describe C functions, Pascal subroutines, and Fortran subprograms are all the same, with different attributes used to specify the differences between these similar programming language features. 
100
101 On occasion, there is a feature which is specific to one particular language and which doesn't appear to have more general application.  For these, DWARF has a description designed to meet the language requirements, although, to the extent possible, an effort is made to generalize the attribute. An example of this is the \DWTAGconditionNAME{} DIE, which is used to describe \addtoindex{COBOL} level 88 conditions, which is described in abstract terms rather than COBOL-specific terms.  Conceivably, this TAG might be used with a different language which had similar functionality. 
102
103 \subsection{Architecture Independence}
104 DWARF can be used with a wide range of processor architectures, whether byte or word oriented, linear or segmented, with any word or byte size.  DWARF can be used with Von Neumann architectures, using a single address space for both code and data; Harvard architectures, with 
105 separate code and data address spaces; and potentially for other architectures such as DSPs with their idiosyncratic memory organizations.  DWARF can be used with common register-oriented architectures or with stack architectures. 
106
107 DWARF assumes that memory has individual units (words or bytes) which have unique addresses which are ordered.  (Some architectures like the i386 can represent the same physical machine location with different segment/offset pairs.  Identifying aliases is an implementation issue.)
108
109 \subsection{Operating System Independence}
110 DWARF is widely associated with SVR4 Unix and similar operating systems like BSD and Linux.  DWARF fits well with the section organization of the ELF object file format. Nonetheless, DWARF attempts to be independent of either the OS or the object file format.  There have been implementations of DWARF debugging data in OMF or COFF object files. 
111
112 DWARF assumes that any object file format will be able to distinguish the various DWARF data sections in some fashion, preferably by name. 
113
114 DWARF makes a few assumptions about functionality provided by the underlying operating system.  DWARF data sections can be read sequentially and independently, for example, to read the \dotdebugabbrev{} section before the \dotdebuginfo{} section.  Each DWARF data section is a sequential sequence of 8-bit bytes, numbered starting with zero.  The presence of offsets from one DWARF data section into other data sections does not imply that the underlying OS must be able to position files randomly; a data section could be read sequentially and indexed using the offset. 
115
116 \subsection{Compact Data Representation} 
117 The DWARF description is designed to be a compact file-oriented representation. In most cases, it is anticipated that DWARF debug data will be read by a consumer (usually a debugger) and converted into a more efficiently accessed internal representation.  For the most part, the DWARF data in a section is not the same as this internal representation. 
118
119 There are several encodings which achieve this goal, such as the TAG and attribute abbreviations or the line number encoding.  References from one section to another, especially to refer to strings, allow these sections to be compacted to eliminate duplicate data. 
120
121 There are multiple schemes for eliminating duplicate data or reducing the size of the DWARF debug data associated with a given file.  These include COMDAT, used to eliminate duplicate function or data definitions, the split DWARF object files which allow a consumer to find DWARF data in files other than the executable, or the type units, which allow similar type definitions from multiple compilations to be combined. 
122
123 There is a tension between this objective and the following objective. Every compaction scheme results in more processing which needs to be performed to process the DWARF debug data. 
124
125 \subsection{Efficient Processing} 
126 DWARF is designed to be processed efficiently, so that a producer (a compiler) can generate the debug descriptions incrementally and a consumer can read only the descriptions which it needs at a given time. The data formats are designed to be efficiently interpreted by a consumer.
127
128 As mentioned, there is a tension between this objective and the preceding one.  A DWARF data representation which resembles an internal data representation may lead to faster processing, but at the expense of larger data files. This may also constrain the possible implementations.
129
130 \subsection{Implementation Independence}
131 DWARF attempts to allow developers the greatest flexibility in designing implementations, without mandating any particular design decisions.  We avoid issues which can be described as “Quality of Implementation”, where the decisions made by an implementer may affect performance or functionality.  
132
133 \subsection{Explicit rather than Implicit Description}
134 DWARF describes the source to object translation explicitly rather than using common practice or convention as an implicit understanding between producer and consumer.  For example, where other debugging formats assume that a debugger knows how to unwind the stack, moving from one stack frame to the next using implicit knowledge about the architecture or operating system, DWARF makes this explicit in the Call Frame Information description.
135
136 \subsection{Avoid Duplication of Information}
137 DWARF has a goal of describing characteristics of a program once, rather than repeating the same information multiple times.  The string sections can be compacted to eliminate duplicate strings, for example.  Other compaction schemes or references between sections support this.
138 Whether a particular implementation is effective at eliminating duplicate data, or even attempts to, is a Quality of Implementation issue.  
139
140 \subsection{Leverage Other Standards}
141 Where another standard exists which describes how to interpret aspects of a program, DWARF defers to that standard rather than attempting to duplicate the description.  For example, C++ has specific rules for deciding which function to call depending name, scope, argument types, and other factors.  DWARF describes the functions and arguments, but doesn't attempt to describe how one would be selected by a consumer performing any particular operation.
142
143 \subsection{Limited Dependence on Tools}
144 DWARF data is designed so that it can be processed by commonly available assemblers, linkers, and other support programs, without requiring additional functionality specifically to support DWARF data.  This may require the implementer to be careful that they do not generate DWARF data which cannot be processed by these programs.  
145 Conversely, an assembler which can generate LEB128 values may allow the compiler to generate more compact descriptions, and a linker which understands the format of string sections can merge these sections.  Whether or not an implementation includes these functions is a Quality of Implementation issue, not mandated by the DWARF specification.
146
147 \subsection{Separate Description from Implementation}
148 DWARF intends to describe the translation of a program from source to object, while neither mandating any particular design nor making any other design difficult.  For example, DWARF describes how the arguments and local variables in a function are to be described, but doesn't specify how this data is collected or organized by a producer.  
149 Where a particular DWARF feature anticipates that it will be implemented in a certain fashion, non-normative text will suggest but not require this design.
150
151 \subsection{Permissive rather than Prescriptive}
152 The DWARF Standard specifies the meaning of DWARF descriptions.  It does not specify what a particular producer should generate for any source to object conversion, nor what a particular consumer should do with this description.  DWARF is permissive, allowing different producer to generate different descriptions for the same source to object conversion.  As long as the DWARF description follows this specification, the producer is generating valid DWARF.
153 For example, DWARF allows producers to identify the end of a function prologue in the Line Information so that a debugger can stop at this location.  A producer which does this is generating valid DWARF, as is another which doesn't.  
154
155 \subsection{Vendor Extensibility}
156 \eb
157 This document does not attempt to cover all interesting
158 languages or even to cover all of the possible debugging
159 information needs for its primary target languages. 
160 Therefore,
161 the document provides vendors a way to define their own
162 debugging information tags, attributes, base type encodings,
163 location operations, language names, calling conventions and
164 call frame instructions by reserving a subset of the valid
165 values for these constructs for vendor specific additions
166 and defining related naming conventions. 
167 Vendors may also use
168 debugging information entries and attributes defined here in
169 new situations. 
170 Future versions of this document will not use
171 names or values reserved for vendor specific additions. 
172 All
173 names and values not reserved for vendor additions, however,
174 are reserved for future versions of this document.
175
176 \bb
177 Where this specification provides a means for
178 \eb
179 describing the source language, implementors are expected
180 to adhere to that specification. 
181 For language features that
182 are not supported, implementors may use existing attributes
183 in novel ways or add vendor-defined attributes. 
184 Implementors
185 who make extensions are strongly encouraged to design them
186 to be compatible with this specification in the absence of
187 those extensions.
188
189 The DWARF format is organized so that a consumer can skip over
190 data which it does not recognize. 
191 This may allow a consumer
192 to read and process files generated according to a later
193 version of this standard or which contain vendor extensions,
194 albeit possibly in a degraded manner.
195
196 \section{Changes from Version 4 to Version 5}
197 \addtoindexx{DWARF Version 5}
198 The following is a list of the major changes made to the DWARF Debugging Information
199 Format since Version 4 was published. The list is not meant to be exhaustive.
200 \begin{itemize}
201 \item The \dotdebugtypes{}
202 %\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
203 section introduced in \DWARFVersionIV{} 
204 is eliminated and its contents instead contained in \dotdebuginfo{} sections
205 to facilitate other changes.
206 \item Add support for collecting common DWARF information (DIEs and macro definitions)
207 across multiple executable and shared files and keeping it in a single
208 \addtoindex{supplementary object file}.
209 \item A new line number program header design provides the ability to 
210 use an MD5 hash to validate source file version in use, allows pooling 
211 of directory and file name strings and makes provision for vendor-defined
212 extensions. It also adds a string section specific to the line number table 
213 (\dotdebuglinestr)
214 to properly support the common practice of stripping all DWARF sections
215 except for line number information.
216 \needlines{4}
217 \item Add a split object file and package representations to allow most 
218 DWARF information to be compacted and/or kept separate from an executable 
219 or shared image. This includes new sections 
220 \dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo, 
221 \dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
222 \dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{} 
223 together with new forms of attribute value for referencing these sections.
224 This enhances DWARF support for very large programs by saving space 
225 and improving link times.
226 \item Replace the \dotdebugmacinfo{} macro information representation with
227 a much more compact \dotdebugmacro{} representation.
228 \item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
229 with a single and more functional name index section, \dotdebugnames{}.
230 \item Add a new debugging information entry (\DWTAGcallsiteNAME) and related 
231 attributes and DWARF expression operators to describe call site information, 
232 including identification of tail calls and tail recursion.
233 This facilitates debugging of optimized code.
234 \item Add improved support for \addtoindex{FORTRAN} assumed rank arrays 
235 (\DWTAGgenericsubrangeNAME), dynamic rank arrays (\DWATrankNAME)
236 and co-arrays (\DWTAGcoarraytypeNAME{}).
237 \item Add a new option to allow debuggers and other DWARF consumers to
238 support a DWARF expression stack containing typed values.
239 \item Add improved support for the \addtoindex{C++} \texttt{auto}
240 return type, deleted member functions (\DWATdeletedNAME), as well as defaulted 
241 constructors and destructors (\DWATdefaultedNAME).
242 \item Add a new attribute, \DWATnoreturnNAME{}, to identify 
243 a subprogram that does not return to its caller.
244 \item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
245 Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
246 Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
247 \item Numerous other more minor additions to improve functionality
248 and performance.
249 \end{itemize}
250
251 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
252 \begin{itemize}
253 \item The compilation unit header (in the \dotdebuginfo{} section) has
254 a new \HFNunittype{} field.
255 \needlines{4}
256 \item New operand forms for attribute values are defined 
257 (\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, 
258 \DWFORMrefsupNAME, \DWFORMstrpsupNAME{} and \DWFORMstrxNAME).
259 (Because a pre-DWARF Version 5 consumer will not be able to interpret 
260 these even to ignore and skip over them, such new forms must be 
261 considered incompatible.)
262 \item The line number table header (in the \dotdebugline{} section) 
263 is substantially revised.
264 \needlines{4}
265 \item A location list entry (see Section \refersec{chap:locationlists}) 
266 with the address range \mbox{(0, \textit{maximum-address})} is defined 
267 as the new default location list entry.
268 \item In a string type (see Section \refersec{chap:stringtypeentries}), 
269 a \DWATbytesizeNAME{} attribute is defined to always describe the size 
270 of the string type. (Previously
271 it described the size of the optional string length data field if the 
272 \DWATstringlengthNAME{} attribute was present.)
273 \end{itemize}
274
275 While not strictly an incompatibility, the macro information 
276 representation is completely new; further, producers 
277 and consumers may optionally continue to support the older 
278 representation. While the two representations cannot both be 
279 used in the same compilation unit, they can co-exist in 
280 executable or shared images.
281
282 Similar comments apply to replacement of the \dotdebugpubnames{} 
283 and \dotdebugpubtypes{} sections with the new \dotdebugnames{} 
284 section.
285
286 \needlines{4}
287 \section{Changes from Version 3 to Version 4}
288 \addtoindexx{DWARF Version 4}
289 The following is a list of the major changes made to the 
290 DWARF Debugging Information Format since Version 3 was 
291 published. The list is not meant to be exhaustive.
292 \begin{itemize}
293 \item Reformulate 
294 Section 2.6 (Location Descriptions) 
295 to better distinguish DWARF location descriptions, which
296 compute the location where a value is found (such as an 
297 address in memory or a register name) from DWARF expressions, 
298 which compute a final value (such as an array bound).
299 \item Add support for bundled instructions on machine architectures 
300 where instructions do not occupy a whole number of bytes.
301 \item Add a new attribute form for section offsets, 
302 \DWFORMsecoffsetNAME,\addtoindexx{section offset}
303 to replace the use of 
304 \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
305 \item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
306 program.
307 \item Define default array lower bound values for each supported language.
308 \item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
309 improve compression and duplicate elimination of DWARF information.
310 \item Add support for new \addtoindex{C++} language constructs, including rvalue references, generalized
311 constant expressions, Unicode character types and template aliases.
312 \item Clarify and generalize support for packed arrays and structures.
313 \item Add new line number table support to facilitate profile based compiler optimization.
314 \item Add additional support for template parameters in instantiations.
315 \item Add support for strongly typed enumerations in languages (such as \addtoindex{C++}) that have two
316 kinds of enumeration declarations.
317 \end{itemize}
318 \addtoindex{DWARF Version 4} is compatible with 
319 \addtoindex{DWARF Version 3} except as follows:
320 \begin{itemize}
321 \item DWARF attributes that use any of the new forms of attribute value representation (for
322 section offsets, flag compression, type signature references, and so on) cannot be read by
323 \addtoindex{DWARF Version 3}
324 consumers because the consumer will not know how to skip over the
325 unexpected form of data.
326 \item DWARF frame and line number table sections include additional fields that affect the location
327 and interpretation of other data in the section.
328 \end{itemize}
329
330 \section{Changes from Version 2 to Version 3}
331 \addtoindexx{DWARF Version 3}
332 The following is a list of the major differences between
333 Version 2 and Version 3 of the DWARF Debugging Information
334 Format. The list is not meant to be exhaustive.
335 \begin{itemize}
336 \item
337 Make provision for DWARF information files that are larger
338 than 4 GBytes.
339 \item
340 Allow attributes to refer to debugging information entries
341 in other shared libraries.
342 \item
343 Add support for \addtoindex{Fortran 90} modules as well as allocatable
344 array and pointer types.
345 \item
346 Add additional base types for \addtoindex{C} (as revised for 1999).
347 \item
348 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
349 \item
350 Add namespace support for \addtoindex{C++}.
351 \item
352 Add an optional section for global type names (similar to
353 the global section for objects and functions).
354 \item
355 Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
356 \item
357 Add improved support for optimized code (discontiguous
358 scopes, end of prologue determination, multiple section
359 code generation).  
360 \item Improve the ability to eliminate
361 duplicate DWARF information during linking.  
362 \end{itemize}
363
364 \addtoindex{DWARF Version 3}
365 is compatible with 
366 \addtoindex{DWARF Version 2} except as follows:
367 \begin{itemize}
368 \item
369 Certain very large values of the initial length fields that
370 begin DWARF sections as well as certain structures are reserved
371 to act as escape codes for future extension; one such extension
372 is defined to increase the possible size of DWARF descriptions
373 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
374 \item
375 References that use the attribute form 
376 \DWFORMrefaddrNAME{}
377 are specified to be four bytes in the DWARF 32-bit format and
378 eight bytes in the DWARF 64-bit format, while 
379 \addtoindex{DWARF Version 2} 
380 specifies that such references have the same size as an
381 address on the target system (see Sections 
382 \refersec{datarep:32bitand64bitdwarfformats} and 
383 \refersec{datarep:attributeencodings}).
384 \item
385 The return\_address\_register field in a Common Information
386 Entry record for call frame information is changed to unsigned
387 LEB representation (see Section 
388 \refersec{chap:structureofcallframeinformation}).
389 \end{itemize}
390
391 \section{Changes from Version 1 to Version 2}
392 \addtoindex{DWARF Version 2} 
393 describes the second generation of debugging
394 information based on the DWARF format. While 
395 \addtoindex{DWARF Version 2}
396 provides new debugging information not available in
397 Version 1, the primary focus of the changes for Version
398 2 is the representation of the information, rather than
399 the information content itself. The basic structure of
400 the Version 2 format remains as in Version 1: the debugging
401 information is represented as a series of debugging information
402 entries, each containing one or more attributes (name/value
403 pairs). The Version 2 representation, however, is much more
404 compact than the Version 1 representation. In some cases,
405 this greater density has been achieved at the expense of
406 additional complexity or greater difficulty in producing and
407 processing the DWARF information. The definers believe that the
408 reduction in I/O and in memory paging should more than make
409 up for any increase in processing time.  
410
411 \needlines{5}
412 The representation
413 of information changed from Version 1 to Version 2, so that
414 Version 2 DWARF information is not binary compatible with
415 Version 1 information. To make it easier for consumers to
416 support both Version 1 and Version 2 DWARF information, the
417 Version 2 information has been moved to a different object
418 file section, \dotdebuginfo{}.  
419
420 \textit{
421 A summary of the major changes made in 
422 \addtoindex{DWARF Version 2}
423 compared to the DWARF Version 1 may be found in the 
424 \addtoindex{DWARF Version 2}
425 document.
426 }
427