Merge branch 'master' of dwarfstd.org:dwarf-doc
[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 The design of the
17 debugging information format is open-ended, allowing for
18 the addition of new debugging information to accommodate new
19 languages or debugger capabilities while remaining compatible
20 with other languages or different debuggers.
21
22 \section{Purpose and Scope}
23 The debugging information format described in this document is
24 designed to meet the symbolic, source-level debugging needs of
25 different languages in a unified fashion by requiring language
26 independent debugging information whenever possible.  
27 Aspects
28 of individual languages, such as \addtoindex{C++} virtual functions or
29 \addtoindex{Fortran} common 
30 \nolink{blocks}, are accommodated by creating attributes
31 that are used only for those languages. 
32 This document is
33 believed to cover most debugging information needs of 
34 \addtoindex{Ada},
35 \addtoindex{C}, \addtoindex{C++}, \addtoindex{COBOL}, 
36 and \addtoindex{Fortran}; it also covers the basic needs
37 of various other languages.
38
39 This document describes \addtoindex{DWARF Version 4},
40 the fourth generation
41 of debugging information based on the DWARF format. DWARF
42 Version 4 extends \addtoindex{DWARF Version 3}
43 in a compatible manner.
44
45 The intended audience for this document is the developers
46 of both producers and consumers of debugging information,
47 typically compilers, debuggers and other tools that need to
48 interpret a binary program in terms of its original source.
49
50
51 \section{Overview}
52
53 There are two major pieces to the description of the DWARF
54 format in this document. The first piece is the informational
55 content of the debugging entries. The second piece is the
56 way the debugging information is encoded and represented in
57 an object file.
58
59 The informational content is described in 
60 Sections \refersec{chap:generaldescription} 
61 through
62 \refersec{chap:otherdebugginginformation}. 
63 Section  \refersec{chap:generaldescription}
64 describes the overall structure of the information
65 and attributes that is common to many or all of the different
66 debugging information entries. 
67 Sections \refersec{chap:programscopeentries}, 
68 \refersec{chap:dataobjectandobjectlistentries} and 
69 \refersec{chap:typeentries} describe
70 the specific debugging information entries and how they
71 communicate the necessary information about the source program
72 to a debugger. 
73 Section \refersec{chap:otherdebugginginformation} 
74 describes debugging information
75 contained outside of the debugging information entries. The
76 encoding of the DWARF information is presented in 
77 Section \refersec{datarep:datarepresentation}.
78
79 This organization closely follows that used in the DWARF
80 Version 3 document. Except where needed to incorporate
81 new material or to correct errors, the 
82 \addtoindex{DWARF Version 3}
83 text is generally reused in this document with little or
84 no modification.
85
86 In the following sections, text in normal font describes
87 required aspects of the DWARF format.  Text in italics is
88 explanatory or supplementary material, and not part of the
89 format definition itself. The several appendices consist only
90 of explanatory or supplementary material, and are not part
91 of the formal definition.
92 \section{Vendor Extensibility}
93
94 This document does not attempt to cover all interesting
95 languages or even to cover all of the interesting debugging
96 information needs for its primary target languages. 
97 Therefore,
98 the document provides vendors a way to define their own
99 debugging information tags, attributes, base type encodings,
100 location operations, language names, calling conventions and
101 call frame instructions by reserving a subset of the valid
102 values for these constructs for vendor specific additions
103 and defining related naming conventions. 
104 Vendors may also use
105 debugging information entries and attributes defined here in
106 new situations. 
107 Future versions of this document will not use
108 names or values reserved for vendor specific additions. 
109 All
110 names and values not reserved for vendor additions, however,
111 are reserved for future versions of this document.
112
113 \addtoindex{DWARF Version 4} is intended to be permissive rather than
114 prescriptive. 
115 Where this specification provides a means for
116 describing the source language, implementors are expected
117 to adhere to that specification. 
118 For language features that
119 are not supported, implementors may use existing attributes
120 in novel ways or add vendor-defined attributes. 
121 Implementors
122 who make extensions are strongly encouraged to design them
123 to be compatible with this specification in the absence of
124 those extensions.
125
126 The DWARF format is organized so that a consumer can skip over
127 data which it does not recognize. 
128 This may allow a consumer
129 to read and process files generated according to a later
130 version of this standard or which contain vendor extensions,
131 albeit possibly in a degraded manner.
132
133
134 \section{Changes from Version 3 to Version 4}
135 The following is a list of the major changes made to the DWARF Debugging Information
136 Format since Version 3 was published. The list is not meant to be exhaustive.
137
138
139 \begin{itemize}
140
141 \item Reformulate 
142 Section 2.6 (Location Descriptions) 
143 to better distinguish DWARF location descriptions, which
144 compute the location where a value is found (such as an address in memory or a register
145 name) from DWARF expressions, which compute a final value (such as an array bound).
146 \item Add support for bundled instructions on machine architectures where instructions do not
147 occupy a whole number of bytes.
148 \item Add a new attribute form for 
149 section offsets, \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}, 
150 \addtoindexx{section offset}
151 to replace the use
152 of \livelink{chap:DWFORMdata4}{DW\-\_FORM\-\_data4} and \livelink{chap:DWFORMdata8}{DW\-\_FORM\-\_data8} for section offsets.
153 \item Add an attribute, \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}, to identify the main subprogram of a
154 program.
155 \item Define default array lower bound values for each supported language.
156 \item Add a new technique using separate type units, type signatures and COMDAT sections to
157 improve compression and duplicate elimination of DWARF information.
158 \item Add support for new C++ language constructs, including rvalue references, generalized
159 constant expressions, Unicode character types and template aliases.
160 \item Clarify and generalize support for packed arrays and structures.
161 \item Add new line number table support to facilitate profile based compiler optimization.
162 \item Add additional support for template parameters in instantiations.
163 \item Add support for strongly typed enumerations in languages (such as C++) that have two
164 kinds of enumeration declarations.
165 \end{itemize}
166 \addtoindex{DWARF Version 4} is compatible with 
167 \addtoindex{DWARF Version 3} except as follows:
168 \begin{itemize}
169 \item DWARF attributes that use any of the new forms of attribute value representation (for
170 section offsets, flag compression, type signature references, and so on) cannot be read by
171 \addtoindex{DWARF Version 3}
172 consumers because the consumer will not know how to skip over the
173 unexpected form of data.
174 \item DWARF frame and line table sections include a additional fields that affect the location
175 and interpretation of other data in the section.
176 \end{itemize}
177
178 \section{Changes from Version 2 to Version 3}
179 The following is a list of the major differences between
180 Version 2 and Version 3 of the DWARF Debugging Information
181 Format. The list is not meant to be exhaustive.
182
183 \begin{itemize}
184 \item
185 Make provision for DWARF information files that are larger
186 than 4 GBytes.
187
188 \item
189 Allow attributes to refer to debugging information entries
190 in other shared libraries.
191
192 \item
193 Add support for \addtoindex{Fortran 90} modules as well as allocatable
194 array and pointer types.
195
196 \item
197 Add additional base types for \addtoindex{C} (as revised for 1999).
198
199 \item
200 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
201
202 \item
203 Add namespace support for \addtoindex{C++}.
204
205 \item
206 Add an optional section for global type names (similar to
207 the global section for objects and functions).
208
209 \item
210 Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
211 \item
212 Add improved support for optimized code (discontiguous
213 scopes, end of prologue determination, multiple section
214 code generation).  
215
216 \item Improve the ability to eliminate
217 duplicate DWARF information during linking.  
218
219 \end{itemize}
220
221 \addtoindex{DWARF Version 3}
222 is compatible with 
223 \addtoindex{DWARF Version 2} except as follows:
224
225 \begin{itemize}
226 \item
227 Certain very large values of the initial length fields that
228 begin DWARF sections as well as certain structures are reserved
229 to act as escape codes for future extension; one such extension
230 is defined to increase the possible size of DWARF descriptions
231 (see Section 7.4).
232
233 \item
234 References that use the attribute form \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr}
235 are specified to be four bytes in the DWARF 32-bit format and
236 eight bytes in the DWARF 64-bit format, while 
237 \addtoindex{DWARF Version 2} 
238 specifies that such references have the same size as an
239 address on the target system (see Sections 7.4 and 7.5.4).
240
241 \item
242 The return\_address\_register field in a Common Information
243 Entry record for call frame information is changed to unsigned
244 LEB representation (see Section 6.4.1).
245
246 \end{itemize}
247
248
249 \section{Changes from Version 1 to Version 2}
250 \addtoindex{DWARF Version 2} 
251 describes the second generation of debugging
252 information based on the DWARF format. While 
253 \addtoindex{DWARF Version 2}
254 provides new debugging information not available in
255 Version 1, the primary focus of the changes for Version
256 2 is the representation of the information, rather than
257 the information content itself. The basic structure of
258 the Version 2 format remains as in Version 1: the debugging
259 information is represented as a series of debugging information
260 entries, each containing one or more attributes (name/value
261 pairs). The Version 2 representation, however, is much more
262 compact than the Version 1 representation. In some cases,
263 this greater density has been achieved at the expense of
264 additional complexity or greater difficulty in producing and
265 processing the DWARF information. The definers believe that the
266 reduction in I/O and in memory paging should more than make
267 up for any increase in processing time.  
268
269 The representation
270 of information changed from Version 1 to Version 2, so that
271 Version 2 DWARF information is not binary compatible with
272 Version 1 information. To make it easier for consumers to
273 support both Version 1 and Version 2 DWARF information, the
274 Version 2 information has been moved to a different object
275 file section, \addtoindex{.debug\_info}.  
276
277 \textit{
278 A summary of the major changes made in 
279 \addtoindex{DWARF Version 2}
280 compared to the DWARF Version 1 may be found in the 
281 \addtoindex{DWARF Version 2}
282 document.
283 }
284