Working document update--not distributed to Committee/
[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 \section{Vendor Extensibility}
92
93 This document does not attempt to cover all interesting
94 languages or even to cover all of the possible debugging
95 information needs for its primary target languages. 
96 Therefore,
97 the document provides vendors a way to define their own
98 debugging information tags, attributes, base type encodings,
99 location operations, language names, calling conventions and
100 call frame instructions by reserving a subset of the valid
101 values for these constructs for vendor specific additions
102 and defining related naming conventions. 
103 Vendors may also use
104 debugging information entries and attributes defined here in
105 new situations. 
106 Future versions of this document will not use
107 names or values reserved for vendor specific additions. 
108 All
109 names and values not reserved for vendor additions, however,
110 are reserved for future versions of this document.
111
112 DWARF is intended to be permissive rather than
113 prescriptive. 
114 Where this specification provides a means for
115 describing the source language, implementors are expected
116 to adhere to that specification. 
117 For language features that
118 are not supported, implementors may use existing attributes
119 in novel ways or add vendor-defined attributes. 
120 Implementors
121 who make extensions are strongly encouraged to design them
122 to be compatible with this specification in the absence of
123 those extensions.
124
125 The DWARF format is organized so that a consumer can skip over
126 data which it does not recognize. 
127 This may allow a consumer
128 to read and process files generated according to a later
129 version of this standard or which contain vendor extensions,
130 albeit possibly in a degraded manner.
131
132 \section{Changes from Version 4 to Version 5}
133 \addtoindexx{DWARF Version 5}
134 The following is a list of the major changes made to the DWARF Debugging Information
135 Format since Version 4 was published. The list is not meant to be exhaustive.
136 \begin{itemize}
137 \item The \dotdebugtypes{}
138 %\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
139 section introduced in \DWARFVersionIV{} 
140 is eliminated and its contents instead contained in \dotdebuginfo{} sections
141 to facilitate other changes.
142 \item Add support for collecting common DWARF information (DIEs and macro definitions)
143 across multiple executable and shared files and keeping it in a single
144 \addtoindex{supplementary object file}.
145 \item A new line number program header design provides the ability to 
146 use an MD5 hash to validate source file version in use, allows pooling 
147 of directory and file name strings and makes provision for vendor-defined
148 extensions. It also adds a string section specific to the line number table 
149 (\dotdebuglinestr)
150 to properly support the common practice of stripping all DWARF sections
151 except for line number information.
152 \item Add a split object file and package representations to allow most 
153 DWARF information to be compacted and/or kept separate from an executable 
154 or shared image. This includes new sections 
155 \dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo, 
156 \dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
157 \dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{} 
158 together with new forms of attribute value for referencing these sections.
159 This enhances DWARF support for very large programs by saving space 
160 and improving link times.
161 \item Replace the \dotdebugmacinfo{} macro information representation with
162 a much more compact \dotdebugmacro{} representation.
163 \item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
164 with a single and more functional name index section, \dotdebugnames{}.
165 \item Add a new debugging information entry (\DWTAGcallsiteNAME) and related 
166 attributes and DWARF expression operators to describe call site information, 
167 including identification of tail calls and tail recursion.
168 This facilitates debugging of optimized code.
169 \item Add improved support for \addtoindex{FORTRAN} assumed rank arrays 
170 (\DWTAGgenericsubrangeNAME), dynamic rank arrays (\DWATrankNAME)
171 and co-arrays (\DWTAGcoarraytypeNAME{}).
172 \item Add a new option to allow debuggers and other DWARF consumers to
173 support a DWARF expression stack containing typed values.
174 \item Add improved support for the \addtoindex{C++} \texttt{auto}
175 return type, deleted member functions (\DWATdeletedNAME), as well as defaulted 
176 constructors and destructors (\DWATdefaultedNAME).
177 \item Add a new attribute, \DWATnoreturnNAME{}, to identify 
178 a subprogram that does not return to its caller.
179 \item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
180 Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
181 Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
182 \item Numerous other more minor additions to improve functionality
183 and performance.
184 \end{itemize}
185
186 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
187 \begin{itemize}
188 \item The compilation unit header (in the \dotdebuginfo{} section) has
189 a new \HFNunittype{} field.
190 \needlines{4}
191 \item New operand forms for attribute values are defined 
192 (\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, 
193 \DWFORMrefsupNAME, \DWFORMstrpsupNAME{} and \DWFORMstrxNAME).
194 (Because a pre-DWARF Version 5 consumer will not be able to interpret 
195 these even to ignore and skip over them, such new forms must be 
196 considered incompatible.)
197 \item The line number table header (in the \dotdebugline{} section) 
198 is substantially revised.
199 \needlines{4}
200 \item A location list entry (see Section \refersec{chap:locationlists}) 
201 with the address range \mbox{(0, \textit{maximum-address})} is defined 
202 as the new default location list entry.
203 \item In a string type (see Section \refersec{chap:stringtypeentries}), 
204 a \DWATbytesizeNAME{} attribute is defined to always describe the size 
205 of the string type. (Previously
206 it described the size of the optional string length data field if the 
207 \DWATstringlengthNAME{} attribute was present.)
208 \end{itemize}
209
210 While not strictly an incompatibility, the macro information 
211 representation is completely new; further, producers 
212 and consumers may optionally continue to support the older 
213 representation. While the two representations cannot both be 
214 used in the same compilation unit, they can co-exist in 
215 executable or shared images.
216
217 Similar comments apply to replacement of the \dotdebugpubnames{} 
218 and \dotdebugpubtypes{} sections with the new \dotdebugnames{} 
219 section.
220
221 \needlines{4}
222 \section{Changes from Version 3 to Version 4}
223 \addtoindexx{DWARF Version 4}
224 The following is a list of the major changes made to the 
225 DWARF Debugging Information Format since Version 3 was 
226 published. The list is not meant to be exhaustive.
227 \begin{itemize}
228 \item Reformulate 
229 Section 2.6 (Location Descriptions) 
230 to better distinguish DWARF location descriptions, which
231 compute the location where a value is found (such as an 
232 address in memory or a register name) from DWARF expressions, 
233 which compute a final value (such as an array bound).
234 \item Add support for bundled instructions on machine architectures 
235 where instructions do not occupy a whole number of bytes.
236 \item Add a new attribute form for section offsets, 
237 \DWFORMsecoffsetNAME,\addtoindexx{section offset}
238 to replace the use of 
239 \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
240 \item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
241 program.
242 \item Define default array lower bound values for each supported language.
243 \item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
244 improve compression and duplicate elimination of DWARF information.
245 \item Add support for new \addtoindex{C++} language constructs, including rvalue references, generalized
246 constant expressions, Unicode character types and template aliases.
247 \item Clarify and generalize support for packed arrays and structures.
248 \item Add new line number table support to facilitate profile based compiler optimization.
249 \item Add additional support for template parameters in instantiations.
250 \item Add support for strongly typed enumerations in languages (such as \addtoindex{C++}) that have two
251 kinds of enumeration declarations.
252 \end{itemize}
253 \addtoindex{DWARF Version 4} is compatible with 
254 \addtoindex{DWARF Version 3} except as follows:
255 \begin{itemize}
256 \item DWARF attributes that use any of the new forms of attribute value representation (for
257 section offsets, flag compression, type signature references, and so on) cannot be read by
258 \addtoindex{DWARF Version 3}
259 consumers because the consumer will not know how to skip over the
260 unexpected form of data.
261 \item DWARF frame and line number table sections include additional fields that affect the location
262 and interpretation of other data in the section.
263 \end{itemize}
264
265 \section{Changes from Version 2 to Version 3}
266 \addtoindexx{DWARF Version 3}
267 The following is a list of the major differences between
268 Version 2 and Version 3 of the DWARF Debugging Information
269 Format. The list is not meant to be exhaustive.
270 \begin{itemize}
271 \item
272 Make provision for DWARF information files that are larger
273 than 4 GBytes.
274 \item
275 Allow attributes to refer to debugging information entries
276 in other shared libraries.
277 \item
278 Add support for \addtoindex{Fortran 90} modules as well as allocatable
279 array and pointer types.
280 \item
281 Add additional base types for \addtoindex{C} (as revised for 1999).
282 \item
283 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
284 \item
285 Add namespace support for \addtoindex{C++}.
286 \item
287 Add an optional section for global type names (similar to
288 the global section for objects and functions).
289 \item
290 Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
291 \item
292 Add improved support for optimized code (discontiguous
293 scopes, end of prologue determination, multiple section
294 code generation).  
295 \item Improve the ability to eliminate
296 duplicate DWARF information during linking.  
297 \end{itemize}
298
299 \addtoindex{DWARF Version 3}
300 is compatible with 
301 \addtoindex{DWARF Version 2} except as follows:
302 \begin{itemize}
303 \item
304 Certain very large values of the initial length fields that
305 begin DWARF sections as well as certain structures are reserved
306 to act as escape codes for future extension; one such extension
307 is defined to increase the possible size of DWARF descriptions
308 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
309 \item
310 References that use the attribute form 
311 \DWFORMrefaddrNAME{}
312 are specified to be four bytes in the DWARF 32-bit format and
313 eight bytes in the DWARF 64-bit format, while 
314 \addtoindex{DWARF Version 2} 
315 specifies that such references have the same size as an
316 address on the target system (see Sections 
317 \refersec{datarep:32bitand64bitdwarfformats} and 
318 \refersec{datarep:attributeencodings}).
319 \item
320 The return\_address\_register field in a Common Information
321 Entry record for call frame information is changed to unsigned
322 LEB representation (see Section 
323 \refersec{chap:structureofcallframeinformation}).
324 \end{itemize}
325
326 \section{Changes from Version 1 to Version 2}
327 \addtoindex{DWARF Version 2} 
328 describes the second generation of debugging
329 information based on the DWARF format. While 
330 \addtoindex{DWARF Version 2}
331 provides new debugging information not available in
332 Version 1, the primary focus of the changes for Version
333 2 is the representation of the information, rather than
334 the information content itself. The basic structure of
335 the Version 2 format remains as in Version 1: the debugging
336 information is represented as a series of debugging information
337 entries, each containing one or more attributes (name/value
338 pairs). The Version 2 representation, however, is much more
339 compact than the Version 1 representation. In some cases,
340 this greater density has been achieved at the expense of
341 additional complexity or greater difficulty in producing and
342 processing the DWARF information. The definers believe that the
343 reduction in I/O and in memory paging should more than make
344 up for any increase in processing time.  
345
346 \needlines{5}
347 The representation
348 of information changed from Version 1 to Version 2, so that
349 Version 2 DWARF information is not binary compatible with
350 Version 1 information. To make it easier for consumers to
351 support both Version 1 and Version 2 DWARF information, the
352 Version 2 information has been moved to a different object
353 file section, \dotdebuginfo{}.  
354
355 \textit{
356 A summary of the major changes made in 
357 \addtoindex{DWARF Version 2}
358 compared to the DWARF Version 1 may be found in the 
359 \addtoindex{DWARF Version 2}
360 document.
361 }
362