9a2fba21edc2867af230e8883c177795f2bb2a14
[dwarf-doc.git] / dwarf5 / latexdoc / introduction.tex
1 \chapter{Introduction}
2 \label{chap:introduction}
3 This document defines a format for describing programs to
4 facilitate user source level debugging. This description
5 can be generated by compilers, assemblers and linkage
6 editors. 
7 It can be used by debuggers and other tools. 
8 The
9 debugging information format does not favor the design of any
10 compiler or debugger. 
11 Instead, the goal is to create a method
12 of communicating an accurate picture of the source program
13 to any debugger in a form that is extensible to different
14 languages while retaining compatibility.  
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 \addtoindex{DWARF Version 4},
39 the fourth generation
40 of debugging information based on the DWARF format. DWARF
41 Version 4 extends \addtoindex{DWARF Version 3}
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 \section{Overview}
50
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 \refersec{chap:generaldescription} 
60 through
61 \refersec{chap:otherdebugginginformation}. 
62 Section  \refersec{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 \refersec{chap:programscopeentries}, 
67 \refersec{chap:dataobjectandobjectlistentries} and 
68 \refersec{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 \refersec{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 \refersec{datarep:datarepresentation}.
77
78 This organization closely follows that used in the DWARF
79 Version 3 document. Except where needed to incorporate
80 new material or to correct errors, the 
81 \addtoindex{DWARF Version 3}
82 text is generally reused in this document with little or
83 no modification.
84
85 In the following sections, text in normal font describes
86 required aspects of the DWARF format.  Text in italics is
87 explanatory or supplementary material, and not part of the
88 format definition itself. The several appendices consist only
89 of explanatory or supplementary material, and are not part
90 of the formal definition.
91 \section{Vendor Extensibility}
92
93 This document does not attempt to cover all interesting
94 languages or even to cover all of the interesting 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 \addtoindex{DWARF Version 5} 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
133 \section[Changes Version 4 to 5]{Changes from Version 4 to Version 5}
134 TBD
135 \section[Changes Version 3 to 4]{Changes from Version 3 to Version 4}
136 The following is a list of the major changes made to the DWARF Debugging Information
137 Format since Version 3 was published. The list is not meant to be exhaustive.
138
139
140 \begin{itemize}
141
142 \item Reformulate 
143 Section 2.6 (Location Descriptions) 
144 to better distinguish DWARF location descriptions, which
145 compute the location where a value is found (such as an address in memory or a register
146 name) from DWARF expressions, which compute a final value (such as an array bound).
147 \item Add support for bundled instructions on machine architectures where instructions do not
148 occupy a whole number of bytes.
149 \item Add a new attribute form for 
150 section offsets, \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}, 
151 \addtoindexx{section offset}
152 to replace the use
153 of \livelink{chap:DWFORMdata4}{DW\-\_FORM\-\_data4} and \livelink{chap:DWFORMdata8}{DW\-\_FORM\-\_data8} for section offsets.
154 \item Add an attribute, \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}, to identify the main subprogram of a
155 program.
156 \item Define default array lower bound values for each supported language.
157 \item Add a new technique using separate type units, type signatures and COMDAT sections to
158 improve compression and duplicate elimination of DWARF information.
159 \item Add support for new C++ language constructs, including rvalue references, generalized
160 constant expressions, Unicode character types and template aliases.
161 \item Clarify and generalize support for packed arrays and structures.
162 \item Add new line number table support to facilitate profile based compiler optimization.
163 \item Add additional support for template parameters in instantiations.
164 \item Add support for strongly typed enumerations in languages (such as C++) that have two
165 kinds of enumeration declarations.
166 \addtoindex{DWARF Version 4} is compatible with 
167 \addtoindex{DWARF Version 3} except as follows:
168 \item DWARF attributes that use any of the new forms of attribute value representation (for
169 section offsets, flag compression, type signature references, and so on) cannot be read by
170 \addtoindex{DWARF Version 3}
171 consumers because the consumer will not know how to skip over the
172 unexpected form of data.
173 \item DWARF frame and line table sections include a additional fields that affect the location
174 and interpretation of other data in the section.
175 \end{itemize}
176
177
178 Contents needed.
179 \section{Changes from Version 2 to Version 3}
180 The following is a list of the major differences between
181 Version 2 and Version 3 of the DWARF Debugging Information
182 Format. The list is not meant to be exhaustive.
183
184 \begin{itemize}
185 \item
186 Make provision for DWARF information files that are larger
187 than 4 GBytes.
188
189 \item
190 Allow attributes to refer to debugging information entries
191 in other shared libraries.
192
193 \item
194 Add support for \addtoindex{Fortran 90} modules as well as allocatable
195 array and pointer types.
196
197 \item
198 Add additional base types for \addtoindex{C} (as revised for 1999).
199
200 \item
201 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
202
203 \item
204 Add namespace support for \addtoindex{C++}.
205
206 \item
207 Add an optional section for global type names (similar to
208 the global section for objects and functions).
209
210 \item
211 Adopt UTF-8 as the preferred representation of program name strings.
212 \item
213 Add improved support for optimized code (discontiguous
214 scopes, end of prologue determination, multiple section
215 code generation).  
216
217 \item Improve the ability to eliminate
218 duplicate DWARF information during linking.  
219
220 \end{itemize}
221
222 \addtoindex{DWARF Version 3}
223 is compatible with 
224 \addtoindex{DWARF Version 2} except as follows:
225
226 \begin{itemize}
227 \item
228 Certain very large values of the initial length fields that
229 begin DWARF sections as well as certain structures are reserved
230 to act as escape codes for future extension; one such extension
231 is defined to increase the possible size of DWARF descriptions
232 (see Section 7.4).
233
234 \item
235 References that use the attribute form \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr}
236 are specified to be four bytes in the DWARF 32-bit format and
237 eight bytes in the DWARF 64-bit format, while 
238 \addtoindex{DWARF Version 2} 
239 specifies that such references have the same size as an
240 address on the target system (see Sections 7.4 and 7.5.4).
241
242 \item
243 The return\_address\_register field in a Common Information
244 Entry record for call frame information is changed to unsigned
245 LEB representation (see Section 6.4.1).
246
247 \end{itemize}
248
249
250 \section[Changes Version1 to 2]{Changes from Version 1 to Version 2}
251 \addtoindex{DWARF Version 2} 
252 describes the second generation of debugging
253 information based on the DWARF format. While 
254 \addtoindex{DWARF Version 2}
255 provides new debugging information not available in
256 Version 1, the primary focus of the changes for Version
257 2 is the representation of the information, rather than
258 the information content itself. The basic structure of
259 the Version 2 format remains as in Version 1: the debugging
260 information is represented as a series of debugging information
261 entries, each containing one or more attributes (name/value
262 pairs). The Version 2 representation, however, is much more
263 compact than the Version 1 representation. In some cases,
264 this greater density has been achieved at the expense of
265 additional complexity or greater difficulty in producing and
266 processing the DWARF information. The definers believe that the
267 reduction in I/O and in memory paging should more than make
268 up for any increase in processing time.  
269
270 The representation
271 of information changed from Version 1 to Version 2, so that
272 Version 2 DWARF information is not binary compatible with
273 Version 1 information. To make it easier for consumers to
274 support both Version 1 and Version 2 DWARF information, the
275 Version 2 information has been moved to a different object
276 file section, \addtoindex{.debug\_info}.  
277
278 \textit{
279 A summary of the major changes
280 made in 
281 \addtoindex{DWARF Version 2}
282 compared to the DWARF Version 1 may
283 be found in the 
284 \addtoindex{DWARF Version 2}
285 document
286 }
287