Bring up to date with the February 2015 meeting and the
[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. 
8 It can be used by debuggers and other tools. 
9 The
10 debugging information format does not favor the design of any
11 compiler or debugger. 
12 Instead, the goal is to create a method
13 of communicating an accurate picture of the source program
14 to any debugger in a form that is extensible to different
15 languages while retaining compatibility.
16   
17 The design of the
18 debugging information format is open-ended, allowing for
19 the addition of new debugging information to accommodate new
20 languages or debugger capabilities while remaining compatible
21 with other languages or different debuggers.
22
23 \section{Purpose and Scope}
24 The debugging information format described in this document is
25 designed to meet the symbolic, source-level debugging needs of
26 different languages in a unified fashion by requiring language
27 independent debugging information whenever possible.  
28 Aspects
29 of individual languages, such as \addtoindex{C++} virtual functions or
30 \addtoindex{Fortran} common 
31 \nolink{blocks}, are accommodated by creating attributes
32 that are used only for those languages. 
33 This document is
34 believed to cover most debugging information needs of 
35 \addtoindex{Ada},
36 \addtoindex{C}, \addtoindex{C++}, \addtoindex{COBOL}, 
37 and \addtoindex{Fortran}; it also covers the basic needs
38 of various other languages.
39
40 This document describes \addtoindex{DWARF Version 4},
41 the fourth generation
42 of debugging information based on the DWARF format. DWARF
43 Version 4 extends \addtoindex{DWARF Version 3}
44 in a compatible manner.
45
46 The intended audience for this document is the developers
47 of both producers and consumers of debugging information,
48 typically compilers, debuggers and other tools that need to
49 interpret a binary program in terms of its original source.
50
51
52 \section{Overview}
53
54 There are two major pieces to the description of the DWARF
55 format in this document. The first piece is the informational
56 content of the debugging entries. The second piece is the
57 way the debugging information is encoded and represented in
58 an object file.
59
60 The informational content is described in 
61 Sections \ref{chap:generaldescription} 
62 through
63 \ref{chap:otherdebugginginformation}. 
64 Section  \ref{chap:generaldescription}
65 describes the overall structure of the information
66 and attributes that is common to many or all of the different
67 debugging information entries. 
68 Sections \ref{chap:programscopeentries}, 
69 \ref{chap:dataobjectandobjectlistentries} and 
70 \ref{chap:typeentries} describe
71 the specific debugging information entries and how they
72 communicate the necessary information about the source program
73 to a debugger. 
74 Section \ref{chap:otherdebugginginformation} 
75 describes debugging information
76 contained outside of the debugging information entries. The
77 encoding of the DWARF information is presented in 
78 Section \ref{datarep:datarepresentation}.
79
80 This organization closely follows that used in the DWARF
81 Version 3 document. Except where needed to incorporate
82 new material or to correct errors, the 
83 \addtoindex{DWARF Version 3}
84 text is generally reused in this document with little or
85 no modification.
86
87 In the following sections, text in normal font describes
88 required aspects of the DWARF format.  Text in \textit{italics} is
89 explanatory or supplementary material, and not part of the
90 format definition itself. The several appendices consist only
91 of explanatory or supplementary material, and are not part
92 of the formal definition.
93
94 \section{Vendor Extensibility}
95
96 This document does not attempt to cover all interesting
97 languages or even to cover all of the interesting debugging
98 information needs for its primary target languages. 
99 Therefore,
100 the document provides vendors a way to define their own
101 debugging information tags, attributes, base type encodings,
102 location operations, language names, calling conventions and
103 call frame instructions by reserving a subset of the valid
104 values for these constructs for vendor specific additions
105 and defining related naming conventions. 
106 Vendors may also use
107 debugging information entries and attributes defined here in
108 new situations. 
109 Future versions of this document will not use
110 names or values reserved for vendor specific additions. 
111 All
112 names and values not reserved for vendor additions, however,
113 are reserved for future versions of this document.
114
115 DWARF is intended to be permissive rather than
116 prescriptive. 
117 Where this specification provides a means for
118 describing the source language, implementors are expected
119 to adhere to that specification. 
120 For language features that
121 are not supported, implementors may use existing attributes
122 in novel ways or add vendor-defined attributes. 
123 Implementors
124 who make extensions are strongly encouraged to design them
125 to be compatible with this specification in the absence of
126 those extensions.
127
128 The DWARF format is organized so that a consumer can skip over
129 data which it does not recognize. 
130 This may allow a consumer
131 to read and process files generated according to a later
132 version of this standard or which contain vendor extensions,
133 albeit possibly in a degraded manner.
134
135 \section{Changes from Version 4 to Version 5}
136 \addtoindexx{DWARF Version 5}
137 The following is a list of the major changes made to the DWARF Debugging Information
138 Format since Version 4 was published. The list is not meant to be exhaustive.
139 \begin{itemize}
140 \item The \dotdebugtypes{}
141 %\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
142 section introduced in \DWARFVersionIV{} 
143 is eliminated and its contents instead contained in \dotdebuginfo{} sections
144 to facilitate other changes.
145 \item Add support for collecting common DWARF information (DIEs and macro definitions)
146 across multiple executable and shared files and keeping it in a single
147 supplementary object file.
148 \item A new line number program header design provides the ability to 
149 use an MD5 hash to validate source file version in use, allows pooling 
150 of directory and file name strings and makes provision for vendor-defined
151 extensions. It also adds a string section specific to the line number table 
152 (\dotdebuglinestr)
153 to properly support the common practice of stripping all DWARF sections
154 except for line number information.
155 \item Add a split object file and package representations to allow most 
156 DWARF information to be compacted and/or kept separate from an executable 
157 or shared image. This includes new sections 
158 \dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo, 
159 \dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
160 \dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{} 
161 together with new forms of attribute value for referencing these sections.
162 This enhances DWARF support for very large programs by saving space 
163 and improving link times.
164 \item Replace the \dotdebugmacinfo{} macro information representation with
165 a much more compact \dotdebugmacro{} representation.
166 \item Replace the \dotdebugpubnames{} and \dotdebugtypes{} section
167 with a single and more functional name index section, \dotdebugnames{}.
168 \item Add a new debugging information entry, related attributes and
169 DWARF expression operators, to describe call information, 
170 including identification of tail calls and tail recursion.
171 This facilitates debugging optimized code.
172 \item Add a new attribute, \DWATnoreturnNAME{}, to identify 
173 a subprogram that does not return to its caller.
174 \item Add a new attribute, \DWATrankNAME{}, to describe the 
175 dimensionality of an array with dynamic rank.
176 \item Add a new tag, \DWTAGgenericsubrangeNAME{}, to describe the
177 bounds of Fortran assumed-rank arrays.
178 \item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
179 Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
180 Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
181 \item Numerous other more minor additions to improve functionality
182 and performance.
183 \end{itemize}
184
185 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
186 \begin{itemize}
187 \item The line number table header is substantially revised.
188 \item New operand forms for attribute values are defined 
189 (\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, \DWFORMrefsupNAME, 
190 \DWFORMstrpNAME, \DWFORMstrpsupNAME, \DWFORMstrxNAME).
191 (Because a pre-DWARF Version 5 consumer will not be able to interpret these even to
192 ignore and skip over them, such new forms must be considered incompatible.)
193 \item A location list entry (see Section \refersec{chap:locationlists}) with 
194 the address range \mbox{(0, \doublequote{-1})} is defined as the new default location 
195 list entry.
196 \item In a string type (see Section \refersec{chap:stringtypeentries}), a \DWATbytesizeNAME{}
197 attribute is defined to always describe the size of the string type. (Previously
198 it described the size of the optional string length data field if the \DWATstringlengthNAME{}
199 attribute was present.)
200 \end{itemize}
201
202 While not strictly an incompatibility, the macro information 
203 representation is completely new; further, producers 
204 and consumers may optionally continue to support the older 
205 representation. While the two representations cannot both be 
206 used in the same compilation unit, they can co-exist in 
207 executable or shared images.
208
209 \needlines{4}
210 \section{Changes from Version 3 to Version 4}
211 \addtoindexx{DWARF Version 4}
212 The following is a list of the major changes made to the DWARF Debugging Information
213 Format since Version 3 was published. The list is not meant to be exhaustive.
214 \begin{itemize}
215 \item Reformulate 
216 Section 2.6 (Location Descriptions) 
217 to better distinguish DWARF location descriptions, which
218 compute the location where a value is found (such as an address in memory or a register
219 name) from DWARF expressions, which compute a final value (such as an array bound).
220 \item Add support for bundled instructions on machine architectures where instructions do not
221 occupy a whole number of bytes.
222 \item Add a new attribute form for 
223 section offsets, \DWFORMsecoffsetNAME, 
224 \addtoindexx{section offset}
225 to replace the use
226 of \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
227 \item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
228 program.
229 \item Define default array lower bound values for each supported language.
230 \item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
231 improve compression and duplicate elimination of DWARF information.
232 \item Add support for new \addtoindex{C++} language constructs, including rvalue references, generalized
233 constant expressions, Unicode character types and template aliases.
234 \item Clarify and generalize support for packed arrays and structures.
235 \item Add new line number table support to facilitate profile based compiler optimization.
236 \item Add additional support for template parameters in instantiations.
237 \item Add support for strongly typed enumerations in languages (such as \addtoindex{C++}) that have two
238 kinds of enumeration declarations.
239 \end{itemize}
240 \addtoindex{DWARF Version 4} is compatible with 
241 \addtoindex{DWARF Version 3} except as follows:
242 \begin{itemize}
243 \item DWARF attributes that use any of the new forms of attribute value representation (for
244 section offsets, flag compression, type signature references, and so on) cannot be read by
245 \addtoindex{DWARF Version 3}
246 consumers because the consumer will not know how to skip over the
247 unexpected form of data.
248 \item DWARF frame and line number table sections include additional fields that affect the location
249 and interpretation of other data in the section.
250 \end{itemize}
251
252 \section{Changes from Version 2 to Version 3}
253 \addtoindexx{DWARF Version 3}
254 The following is a list of the major differences between
255 Version 2 and Version 3 of the DWARF Debugging Information
256 Format. The list is not meant to be exhaustive.
257 \begin{itemize}
258 \item
259 Make provision for DWARF information files that are larger
260 than 4 GBytes.
261 \item
262 Allow attributes to refer to debugging information entries
263 in other shared libraries.
264 \item
265 Add support for \addtoindex{Fortran 90} modules as well as allocatable
266 array and pointer types.
267 \item
268 Add additional base types for \addtoindex{C} (as revised for 1999).
269 \item
270 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
271 \item
272 Add namespace support for \addtoindex{C++}.
273 \item
274 Add an optional section for global type names (similar to
275 the global section for objects and functions).
276 \item
277 Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
278 \item
279 Add improved support for optimized code (discontiguous
280 scopes, end of prologue determination, multiple section
281 code generation).  
282 \item Improve the ability to eliminate
283 duplicate DWARF information during linking.  
284 \end{itemize}
285
286 \addtoindex{DWARF Version 3}
287 is compatible with 
288 \addtoindex{DWARF Version 2} except as follows:
289 \begin{itemize}
290 \item
291 Certain very large values of the initial length fields that
292 begin DWARF sections as well as certain structures are reserved
293 to act as escape codes for future extension; one such extension
294 is defined to increase the possible size of DWARF descriptions
295 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
296 \item
297 References that use the attribute form 
298 \DWFORMrefaddrNAME{}
299 are specified to be four bytes in the DWARF 32-bit format and
300 eight bytes in the DWARF 64-bit format, while 
301 \addtoindex{DWARF Version 2} 
302 specifies that such references have the same size as an
303 address on the target system (see Sections 
304 \refersec{datarep:32bitand64bitdwarfformats} and 
305 \refersec{datarep:attributeencodings}).
306 \item
307 The return\_address\_register field in a Common Information
308 Entry record for call frame information is changed to unsigned
309 LEB representation (see Section 
310 \refersec{chap:structureofcallframeinformation}).
311 \end{itemize}
312
313 \section{Changes from Version 1 to Version 2}
314 \addtoindex{DWARF Version 2} 
315 describes the second generation of debugging
316 information based on the DWARF format. While 
317 \addtoindex{DWARF Version 2}
318 provides new debugging information not available in
319 Version 1, the primary focus of the changes for Version
320 2 is the representation of the information, rather than
321 the information content itself. The basic structure of
322 the Version 2 format remains as in Version 1: the debugging
323 information is represented as a series of debugging information
324 entries, each containing one or more attributes (name/value
325 pairs). The Version 2 representation, however, is much more
326 compact than the Version 1 representation. In some cases,
327 this greater density has been achieved at the expense of
328 additional complexity or greater difficulty in producing and
329 processing the DWARF information. The definers believe that the
330 reduction in I/O and in memory paging should more than make
331 up for any increase in processing time.  
332
333 The representation
334 of information changed from Version 1 to Version 2, so that
335 Version 2 DWARF information is not binary compatible with
336 Version 1 information. To make it easier for consumers to
337 support both Version 1 and Version 2 DWARF information, the
338 Version 2 information has been moved to a different object
339 file section, \dotdebuginfo{}.  
340
341 \textit{
342 A summary of the major changes made in 
343 \addtoindex{DWARF Version 2}
344 compared to the DWARF Version 1 may be found in the 
345 \addtoindex{DWARF Version 2}
346 document.
347 }
348