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