Working checkpoint for editoial changes resulting from 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. 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 \bb 
60 Chapters
61 \eb
62 \ref{chap:generaldescription} 
63 through
64 \ref{chap:otherdebugginginformation}. 
65 Chapter \ref{chap:generaldescription}
66 describes the overall structure of the information
67 and attributes that are common to many or all of the different
68 debugging information entries. 
69 \bb
70 Chapters
71 \eb \ref{chap:programscopeentries}, 
72 \ref{chap:dataobjectandobjectlistentries} and 
73 \ref{chap:typeentries} describe
74 the specific debugging information entries and how they
75 communicate the necessary information about the source program
76 to a debugger. 
77 \bb
78 Chapter
79 \eb
80 \ref{chap:otherdebugginginformation} 
81 describes debugging information
82 contained outside of the debugging information entries. The
83 encoding of the DWARF information is presented in 
84 \bb
85 Chapter
86 \eb
87 \ref{datarep:datarepresentation}.
88
89 This organization closely follows that used in the 
90 \DWARFVersionIV{} document. Except where needed to incorporate
91 new material or to correct errors, the \DWARFVersionIV{}
92 text is generally reused in this document with little or
93 no modification.
94
95 In the following sections, text in normal font describes
96 required aspects of the DWARF format.  Text in \textit{italics} is
97 explanatory or supplementary material, and not part of the
98 format definition itself. The several appendices consist only
99 of explanatory or supplementary material, and are not part
100 of the formal definition.
101
102 \section{Objectives and Rationale}
103
104 DWARF has had a set of objectives since its inception which have 
105 guided the design and evolution of the debugging format.  A discussion 
106 of these objectives and the rationale behind them may help with an 
107 understanding of the DWARF Debugging Format. 
108
109 Although DWARF Version 1 was developed in the late 1980's as a 
110 format to support debugging C programs written for AT\&T hardware 
111 running SVR4, \DWARFVersionII{} and later has evolved far beyond 
112 this origin. One difference between DWARF and other 
113 \bb\eb
114 formats 
115 is that the latter are often specific to a particular language, 
116 architecture, and/or operating system. 
117
118 \subsection{Language Independence}
119 DWARF is applicable to a broad range of existing procedural 
120 languages and is designed to be extensible to future languages.  
121 These languages may be considered to be "C-like" but the 
122 characteristics of C are not incorporated into DWARF Version 2 
123 and later, unlike DWARF Version 1 and other debugging formats.  
124 DWARF abstracts concepts as much as possible so that the 
125 description can be used to describe a program in any language. 
126 As an example, the DWARF descriptions used to describe C functions, 
127 Pascal subroutines, and Fortran subprograms are all the same, 
128 with different attributes used to specify the differences between 
129 these similar programming language features. 
130
131 On occasion, there is a feature which is specific to one 
132 particular language and which doesn't appear to have more 
133 general application.  For these, DWARF has a description 
134 designed to meet the language requirements, although, to the 
135 extent possible, an effort is made to generalize the attribute. 
136 An example of this is the \DWTAGconditionNAME{} DIE, 
137 \bb\eb 
138 used to describe \addtoindex{COBOL} level 88 conditions, which 
139 is described in abstract terms rather than COBOL-specific terms.  
140 Conceivably, this TAG might be used with a different language 
141 which had similar functionality. 
142
143 \subsection{Architecture Independence}
144 DWARF can be used with a wide range of processor architectures, 
145 whether byte or word oriented, linear or segmented, with any 
146 word or byte size.  DWARF can be used with Von Neumann architectures, 
147 using a single address space for both code and data; Harvard 
148 architectures, with separate code and data address spaces; and 
149 potentially for other architectures such as DSPs with their 
150 idiosyncratic memory organizations.  DWARF can be used with 
151 common register-oriented architectures or with stack architectures. 
152
153 DWARF assumes that memory has individual units (words or bytes) 
154 which have unique addresses which are ordered.  (Some architectures 
155 like the i386 can represent the same physical machine location with 
156 different segment and offset pairs.  Identifying aliases is an 
157 implementation issue.)
158
159 \subsection{Operating System Independence}
160 DWARF is widely associated with SVR4 Unix and similar operating 
161 systems like BSD and Linux.  DWARF fits well with the section 
162 organization of the ELF object file format. Nonetheless, DWARF 
163 attempts to be independent of either the OS or the object file 
164 format.  There have been implementations of DWARF debugging 
165 data in 
166 \bb
167 COFF, Mach-O and other object file formats. 
168 \eb
169
170 DWARF assumes that any object file format will be able to 
171 distinguish the various DWARF data sections in some fashion, 
172 preferably by name. 
173
174 DWARF makes a few assumptions about functionality provided by 
175 the underlying operating system.  DWARF data sections can be 
176 read sequentially and independently.
177 \bb\eb
178 Each DWARF data section is a \bb\eb sequence of 8-bit bytes, 
179 numbered starting with zero.  The presence of offsets from one 
180 DWARF data section into other data sections does not imply that 
181 the underlying OS must be able to position files randomly; a 
182 data section could be read sequentially and indexed using the offset. 
183
184 \subsection{Compact Data Representation} 
185 The DWARF description is designed to be a compact file-oriented 
186 representation.\bb\eb
187
188 There are several encodings which achieve this goal, such as the 
189 TAG and attribute abbreviations or the line number encoding.  
190 References from one section to another, especially to refer to 
191 strings, allow these sections to be compacted to eliminate 
192 duplicate data. 
193
194 There are multiple schemes for eliminating duplicate data or 
195 reducing the size of the DWARF debug data associated with a 
196 given file.  These include COMDAT, used to eliminate duplicate 
197 function or data definitions, the split DWARF object files 
198 which allow a consumer to find DWARF data in files other than 
199 the executable, or the type units, which allow similar type 
200 definitions from multiple compilations to be combined. 
201
202 \bb
203 In most cases, it is anticipated that DWARF 
204 debug data will be read by a consumer (usually a debugger) and 
205 converted into a more efficiently accessed internal representation.  
206 For the most part, the DWARF data in a section is not the same as 
207 this internal representation.
208 \eb
209
210 \subsection{Efficient Processing} 
211 DWARF is designed to be processed efficiently, so that a 
212 producer (a compiler) can generate the debug descriptions 
213 incrementally and a consumer can read only the descriptions 
214 which it needs at a given time. The data formats are designed 
215 to be efficiently interpreted by a consumer.
216
217 As mentioned, there is a tension between this objective and 
218 the preceding one.  A DWARF data representation which resembles 
219 an internal data representation may lead to faster processing, 
220 but at the expense of larger data files. This may also constrain 
221 the possible implementations.
222
223 \subsection{Implementation Independence}
224 DWARF attempts to allow developers the greatest flexibility 
225 in designing implementations, without mandating any particular 
226 design decisions. Issues which can be described as 
227 \bb
228 quality-of-implementation
229 \eb
230 are avoided.
231
232 \bb
233 \subsection{Explicit Rather Than Implicit Description}
234 \eb
235 DWARF describes the source to object translation explicitly 
236 rather than using common practice or convention as an implicit 
237 understanding between producer and consumer.  For example, where 
238 other debugging formats assume that a debugger knows how to 
239 unwind the stack, moving from one stack frame to the next using 
240 implicit knowledge about the architecture or operating system, 
241 DWARF makes this explicit in the Call Frame Information description.
242
243 \subsection{Avoid Duplication of Information}
244 DWARF has a goal of describing characteristics of a program once, 
245 rather than repeating the same information multiple times.  The 
246 string sections can be compacted to eliminate duplicate strings, 
247 for example.  Other compaction schemes or references between 
248 \bb
249 sections 
250 \eb
251 support this. Whether a particular implementation is 
252 effective at eliminating duplicate data, or even attempts to, 
253 is a 
254 \bb
255 quality-of-implementation
256 \eb
257 issue.  
258
259 \subsection{Leverage Other Standards}
260 Where another standard exists which describes how to interpret 
261 aspects of a program, DWARF defers to that standard rather than 
262 attempting to duplicate the description.  For example, C++ has 
263 \bb
264 specific 
265 \eb
266 rules for deciding which function to call depending 
267 name, scope, argument types, and other factors.  DWARF describes 
268 the functions and arguments, but doesn't attempt to describe 
269 how one would be selected by a consumer performing any particular 
270 operation.
271
272 \subsection{Limited Dependence on Tools}
273 DWARF data is designed so that it can be processed by commonly 
274 available assemblers, linkers, and other support programs, 
275 without requiring additional functionality specifically to 
276 support DWARF data.  This may require the implementer to be 
277 careful that they do not generate DWARF data which cannot be 
278 processed by these programs.  Conversely, an assembler which 
279 can generate LEB128 
280 \bb
281 (Little-Endian Base 128) 
282 \eb
283 values may allow the compiler to generate 
284 more compact descriptions, and a linker which understands the 
285 format of string sections can merge these sections.  Whether 
286 or not an implementation includes these functions is a 
287 \bb
288 quality-of-implementation 
289 \eb
290 issue, not mandated by the DWARF specification.
291
292 \subsection{Separate Description From Implementation}
293 DWARF intends to describe the translation of a program from 
294 source to object, while neither mandating any particular design 
295 nor making any other design difficult.  For example, DWARF 
296 describes how the arguments and local variables in a function 
297 are to be described, but doesn't specify how this data is 
298 collected or organized by a producer.  Where a particular DWARF 
299 feature anticipates that it will be implemented in a certain 
300 fashion, 
301 \bb
302 informative 
303 \eb
304 text will suggest but not require this design.
305
306 \bb 
307 \subsection{Permissive Rather Than Prescriptive}
308 \eb
309 The DWARF Standard specifies the meaning of DWARF descriptions.  
310 It does not specify what a particular producer should generate 
311 for any source to object conversion, nor what a particular 
312 consumer should do with this description.  DWARF is permissive, 
313 allowing different producer to generate different descriptions 
314 for the same source to object conversion.  As long as the DWARF 
315 description follows this specification, the producer is 
316 generating valid DWARF.
317 For example, DWARF allows 
318 \bb
319 a producer 
320 \eb
321 to identify the end of a 
322 function prologue in the Line Information so that a debugger 
323 can stop at this location.  A producer which does this is 
324 generating valid DWARF, as is another which doesn't.  
325
326 \subsection{Vendor Extensibility}
327 This document does not attempt to cover all interesting
328 languages or even to cover all of the possible debugging
329 information needs for its primary target languages. 
330 Therefore,
331 the document provides vendors a way to define their own
332 debugging information tags, attributes, base type encodings,
333 location operations, language names, calling conventions and
334 call frame instructions by reserving a subset of the valid
335 values for these constructs for vendor specific additions
336 and defining related naming conventions. 
337 Vendors may also use
338 debugging information entries and attributes defined here in
339 new situations. 
340 Future versions of this document will not use
341 names or values reserved for vendor specific additions. 
342 All
343 names and values not reserved for vendor additions, however,
344 are reserved for future versions of this document.
345
346 Where this specification provides a means for
347 describing the source language, implementors are expected
348 to adhere to that specification. 
349 For language features that
350 are not supported, implementors may use existing attributes
351 in novel ways or add vendor-defined attributes. 
352 Implementors
353 who make extensions are strongly encouraged to design them
354 to be compatible with this specification in the absence of
355 those extensions.
356
357 The DWARF format is organized so that a consumer can skip over
358 data which it does not recognize. 
359 This may allow a consumer
360 to read and process files generated according to a later
361 version of this standard or which contain vendor extensions,
362 albeit possibly in a degraded manner.
363
364 \bb
365 \section{Changes From Version 4 to Version 5}
366 \eb
367 \addtoindexx{DWARF Version 5}
368 The following is a list of the major changes made to the DWARF Debugging Information
369 Format since Version 4 was published. The list is not meant to be exhaustive.
370 \begin{itemize}
371 \item The \dotdebugtypes{}
372 %\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
373 section introduced in \DWARFVersionIV{} 
374 is eliminated and its contents instead contained in \dotdebuginfo{} sections.
375 \bb\eb
376 \item Add support for collecting common DWARF information 
377 \bb
378 (debugging information entries 
379 \eb
380 and macro definitions)
381 across multiple executable and shared files and keeping it in a single
382 \addtoindex{supplementary object file}.
383 \item A new line number program header 
384 \bb
385 format 
386 \eb
387 provides the ability to 
388 use an MD5 hash to validate 
389 \bb
390 the
391 \eb
392 source file version in use, allows pooling 
393 of directory and file name strings and makes provision for vendor-defined
394 extensions. It also adds a string section specific to the line number table 
395 (\dotdebuglinestr)
396 to properly support the common practice of stripping all DWARF sections
397 except for line number information.
398 \needlines{4}
399 \item Add a split object file and package representations to allow most 
400 DWARF information to be 
401 \bb\eb
402 kept separate from an executable 
403 or shared image. This includes new sections 
404 \dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo, 
405 \dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
406 \dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{} 
407 together with new forms of attribute value for referencing these sections.
408 This enhances DWARF support 
409 \bb
410 by reducing executable program size and
411 by improving link times.
412 \eb
413 \item Replace the \dotdebugmacinfo{} macro information representation with
414 \bb
415 with a \dotdebugmacro{} representation that can potentially be much more compact.
416 \eb
417 \item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
418 with a single and more functional name index section, \dotdebugnames{}.
419 \item Add a new debugging information entry (\DWTAGcallsiteNAME), related 
420 \bb\eb
421 attributes and DWARF expression operators to describe call site information, 
422 including identification of tail calls and tail recursion.
423 \bb\eb
424 \item Add improved support for \addtoindex{FORTRAN} assumed rank arrays 
425 (\DWTAGgenericsubrangeNAME), dynamic rank arrays (\DWATrankNAME)
426 and co-arrays (\DWTAGcoarraytypeNAME{}).
427 \item Add
428 \bb
429 new operations that allow support for 
430 \eb
431 a DWARF expression stack containing typed values.
432 \item Add improved support for the \addtoindex{C++}:
433 \bb\eb
434 \texttt{auto} return type, deleted member functions (\DWATdeletedNAME), 
435 as well as defaulted constructors and destructors (\DWATdefaultedNAME).
436 \item Add a new attribute 
437 \bb
438 (\DWATnoreturnNAME{}), 
439 \eb
440 to identify 
441 a subprogram that does not return to its caller.
442 \item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
443 Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
444 Julia, Modula 3, Ocaml, 
445 \bb
446 OpenCL, Rust 
447 \eb
448 and Swift.
449 \item Numerous other more minor additions to improve functionality
450 and performance.
451 \end{itemize}
452
453 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
454 \begin{itemize}
455 \item The compilation unit header (in the \dotdebuginfo{} section) has
456 a new \HFNunittype{} field.
457 \needlines{4}
458 \item New operand forms for attribute values are defined 
459 (\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, 
460 \bb
461 \DWFORMimplicitconstNAME, 
462 \eb
463 \DWFORMlinestrpNAME, 
464 \DWFORMrefsupNAME, \DWFORMstrpsupNAME{} and \DWFORMstrxNAME).
465
466 \textit{Because a pre-DWARF Version 5 consumer will not be able to interpret 
467 these even to ignore and skip over them, new forms must be 
468 considered incompatible additions.}
469 \item The line number table header 
470 \bb\eb 
471 is substantially revised.
472 \needlines{4}
473 \item A location list entry 
474 \bb\eb
475 with the address range \mbox{(0, \textit{maximum-address})} is defined 
476 as the new default location list entry.
477 \item In a string type,
478 \bb 
479 the \DWATbytesizeNAME{} attribute is re-defined 
480 \eb
481 to always describe the size of the string type. 
482 (Previously it described the size of the optional string length data 
483 field if the \DWATstringlengthNAME{} attribute was 
484 \bb
485 also 
486 \eb
487 present.)
488 \end{itemize}
489
490 While not strictly an incompatibility, the macro information 
491 representation is completely new; further, producers 
492 and consumers may optionally continue to support the older 
493 representation. While the two representations cannot both be 
494 used in the same compilation unit, they can co-exist in 
495 executable or shared images.
496
497 Similar comments apply to replacement of the \dotdebugpubnames{} 
498 and \dotdebugpubtypes{} sections with the new \dotdebugnames{} 
499 section.
500
501 \needlines{4}
502 \section{Changes from Version 3 to Version 4}
503 \addtoindexx{DWARF Version 4}
504 The following is a list of the major changes made to the 
505 DWARF Debugging Information Format since Version 3 was 
506 published. The list is not meant to be exhaustive.
507 \begin{itemize}
508 \item Reformulate 
509 Section 2.6 (Location Descriptions) 
510 to better distinguish DWARF location descriptions, which
511 compute the location where a value is found (such as an 
512 address in memory or a register name) from DWARF expressions, 
513 which compute a final value (such as an array bound).
514 \item Add support for bundled instructions on machine architectures 
515 where instructions do not occupy a whole number of bytes.
516 \item Add a new attribute form for section offsets, 
517 \DWFORMsecoffsetNAME,\addtoindexx{section offset}
518 to replace the use of 
519 \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
520 \item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
521 program.
522 \item Define default array lower bound values for each supported language.
523 \item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
524 improve compression and duplicate elimination of DWARF information.
525 \item Add support for new \addtoindex{C++} language constructs, including rvalue references, generalized
526 constant expressions, Unicode character types and template aliases.
527 \item Clarify and generalize support for packed arrays and structures.
528 \item Add new line number table support to facilitate profile based compiler optimization.
529 \item Add additional support for template parameters in instantiations.
530 \item Add support for strongly typed enumerations in languages (such as \addtoindex{C++}) that have two
531 kinds of enumeration declarations.
532 \end{itemize}
533 \addtoindex{DWARF Version 4} is compatible with 
534 \addtoindex{DWARF Version 3} except as follows:
535 \begin{itemize}
536 \item DWARF attributes that use any of the new forms of attribute value representation (for
537 section offsets, flag compression, type signature references, and so on) cannot be read by
538 \addtoindex{DWARF Version 3}
539 consumers because the consumer will not know how to skip over the
540 unexpected form of data.
541 \item DWARF frame and line number table sections include additional fields that affect the location
542 and interpretation of other data in the section.
543 \end{itemize}
544
545 \section{Changes from Version 2 to Version 3}
546 \addtoindexx{DWARF Version 3}
547 The following is a list of the major differences between
548 Version 2 and Version 3 of the DWARF Debugging Information
549 Format. The list is not meant to be exhaustive.
550 \begin{itemize}
551 \item
552 Make provision for DWARF information files that are larger
553 than 4 GBytes.
554 \item
555 Allow attributes to refer to debugging information entries
556 in other shared libraries.
557 \item
558 Add support for \addtoindex{Fortran 90} modules as well as allocatable
559 array and pointer types.
560 \item
561 Add additional base types for \addtoindex{C} (as revised for 1999).
562 \item
563 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
564 \item
565 Add namespace support for \addtoindex{C++}.
566 \item
567 Add an optional section for global type names (similar to
568 the global section for objects and functions).
569 \item
570 Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
571 \item
572 Add improved support for optimized code (discontiguous
573 scopes, end of prologue determination, multiple section
574 code generation).  
575 \item Improve the ability to eliminate
576 duplicate DWARF information during linking.  
577 \end{itemize}
578
579 \addtoindex{DWARF Version 3}
580 is compatible with 
581 \addtoindex{DWARF Version 2} except as follows:
582 \begin{itemize}
583 \item
584 Certain very large values of the initial length fields that
585 begin DWARF sections as well as certain structures are reserved
586 to act as escape codes for future extension; one such extension
587 is defined to increase the possible size of DWARF descriptions
588 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
589 \item
590 References that use the attribute form 
591 \DWFORMrefaddrNAME{}
592 are specified to be four bytes in the DWARF 32-bit format and
593 eight bytes in the DWARF 64-bit format, while 
594 \addtoindex{DWARF Version 2} 
595 specifies that such references have the same size as an
596 address on the target system (see Sections 
597 \refersec{datarep:32bitand64bitdwarfformats} and 
598 \refersec{datarep:attributeencodings}).
599 \item
600 The return\_address\_register field in a Common Information
601 Entry record for call frame information is changed to unsigned
602 LEB representation (see Section 
603 \refersec{chap:structureofcallframeinformation}).
604 \end{itemize}
605
606 \section{Changes from Version 1 to Version 2}
607 \addtoindex{DWARF Version 2} 
608 describes the second generation of debugging
609 information based on the DWARF format. While 
610 \addtoindex{DWARF Version 2}
611 provides new debugging information not available in
612 Version 1, the primary focus of the changes for Version
613 2 is the representation of the information, rather than
614 the information content itself. The basic structure of
615 the Version 2 format remains as in Version 1: the debugging
616 information is represented as a series of debugging information
617 entries, each containing one or more attributes (name/value
618 pairs). The Version 2 representation, however, is much more
619 compact than the Version 1 representation. In some cases,
620 this greater density has been achieved at the expense of
621 additional complexity or greater difficulty in producing and
622 processing the DWARF information. The definers believe that the
623 reduction in I/O and in memory paging should more than make
624 up for any increase in processing time.  
625
626 \needlines{5}
627 The representation
628 of information changed from Version 1 to Version 2, so that
629 Version 2 DWARF information is not binary compatible with
630 Version 1 information. To make it easier for consumers to
631 support both Version 1 and Version 2 DWARF information, the
632 Version 2 information has been moved to a different object
633 file section, \dotdebuginfo{}.  
634
635 \textit{
636 A summary of the major changes made in 
637 \addtoindex{DWARF Version 2}
638 compared to the DWARF Version 1 may be found in the 
639 \addtoindex{DWARF Version 2}
640 document.
641 }
642