DWARF 5 Errata and Clarifications

This page summarizes corrections and clarifications to the DWARF 5 specification.

Chapter 1: Introduction

Intro paragraph, page 1

Delete the accidental word "unittype".

This document defines a format for describing programs to facilitate user source level debugging. This description can be generated by compilers, assemblers and linkage editors. It can be used by debuggers and other tools. The debugging information format does not favor the design of any compiler or debugger. Instead, the goal is to create a method of communicating an accurate picture of the source program to any debugger in a form that is extensible to different languages while retaining compatibility.unittype

[Issue 200505.1]

Chapter 2: General Description

Section 2.5.1.5 Control Flow Operations, page 36

Correction: the DW_OP_call_ref operator may not be used for cross-module references.

DW_OP_call2, DW_OP_call4, DW_OP_call_ref DW_OP_call2, DW_OP_call4, and DW_OP_call_ref perform DWARF procedure calls during evaluation of a DWARF expression or location description. For DW_OP_call2 and DW_OP_call4, the operand is the 2- or 4-byte unsigned offset, respectively, of a debugging information entry in the current compilation unit. The DW_OP_call_ref operator has a single operand. In the 32-bit DWARF format, the operand is a 4-byte unsigned value; in the 64-bit DWARF format, it is an 8-byte unsigned value (see Section 7.4 following). The operand is used as the offset of a debugging information entry in a .debug_info section which may be contained in an executable or shared object file other than that containing the operator. For references from one executable or shared object file to another, the relocation must be performed by the consumer. The operand is used as the offset of a debugging information entry in the .debug_info section of the current executable or shared object file.

[Issue 230120.1]

Section 2.5.1.7 Special Operations, page 37

Clarify meaning of DW_OP_entry_value.

The DW_OP_entry_value operation pushes the value that the described location held a DWARF expression would have computed, or that a register location held upon entering the current subprogram....

[Issue 230808.1]

Section 2.6.1.1.4 Implicit Location Descriptions, page 41

Correction: DW_OP_implicit_pointer cannot reference an external module.

The DW_OP_implicit_pointer operation has two operands: a reference to a debugging information entry that describes the dereferenced object’s value, and a signed number that is treated as a byte offset from the start of that value. The first operand is a 4-byte unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format (see Section 7.4 on page 196), that is used as the offset of a debugging information entry in the .debug_info section of the current executable or shared object file. The second operand is a signed LEB128 number.

The first operand is used as the offset of a debugging information entry in a .debug_info section, which may be contained in an executable or shared object file other than that containing the operator. For references from one executable or shared object file to another, the relocation must be performed by the consumer.

[Issue 230120.1]

Section 2.6.1.2 Composite Location Descriptions, page 47

Clarification: Add the following normative text:

A composition operation that follows an empty location description indicates that the piece is undefined, for example because it has been optimized away.

[Issue 181205.1]

Section 2.17 Code Addresses, Ranges and Base Addresses, page 53

Clarify definition of empty range. This paragraph is changed from normative to non-normative.

A bounded range entry whose beginning and ending address offsets addresses are equal (including zero) indicates an empty range and may be ignored.

[Issue 211022.1]

Chapter 3: Program Scope Entries

Section 3.1.1 Full and Partial Compilation Unit Entries, page 64

Clarify meaning of relative paths.

6. A DW_AT_comp_dir attribute whose value is a null-terminated string containing the current working directory of the compilation command that produced this compilation unit in whatever form makes sense for the host system.

If a relative path is used in DW_AT_comp_dir, it will be relative to the location of the linked image containing the DW_AT_comp_dir entry.

In some cases a producer may allow the user to specify a relative path for DW_AT_comp_dir. There are a few cases in which this is useful, but in general using a relative path for DW_AT_comp_dir is discouraged as it will not work well in many cases including the following: different relative paths are used within the same build; the build system creates multiple linked images in different directories; the final linked image is moved before being debugged; .o files need to be debugged directly.

[Issue 210628.1]

Section 3.1.2 Skeleton Compilation Unit Entries, page 67

Change bullet items 6 and 7:

6. A DW_AT_str_offsets attribute, for indirect string references from this the skeleton compilation unit to a (non-split) .debug_str_offsets section.

7. A DW_AT_addr_base attribute, for indirect references from this skeleton compilation unit and from the corresponding split full compilation unit (See Section 3.1.3) to the compilation unit's contribution to the .debug_addr section. The DW_AT_addr_base attribute provides context that may be necessary to interpret the contents of the corresponding split DWARF object file.

Add DW_AT_rnglists_base to list of attributes for a skeleton compilation unit.

8. A DW_AT_rnglists_base attribute, for range list entry references from this skeleton compilation unit to a (non-split) .debug_rnglists section.

Remove the non-normative paragraph:

The DW_AT_addr_base and DW_AT_str_offsets_base_ attributes provides context that may be necessary to interpret the contents of the corresponding split DWARF object file.

[Issues 200709.1, 250311.1]

Section 3.1.3 Split Full Compilation Unit Entries, page 68

Remove DW_AT_rnglists_base and DW_AT_str_offsets_base from the list of attributes inherited by the split full unit from the skeleton unit.

The following attributes are not part of a split full compilation unit entry but instead are inherited (if present) from the corresponding skeleton compilation unit: DW_AT_low_pc, DW_AT_high_pc, DW_AT_ranges, DW_AT_stmt_list, DW_AT_comp_dir, DW_AT_str_offsets_base, and DW_AT_addr_base and DW_AT_rnglists_base.

Add the following non-normative paragraph clarifying offsets in .dwo files to the end of the section:

Use of DW_FORM_sec_offset and other equivalent encodings (eg: the abbrev offset in a compilation unit header) are resolved relative to the beginning of the contribution of the relevant section within the .dwo or .dwp file and cannot be used for sharing content between multiple compilation units. DW_FORM_sec_offset may not be used when a reference to content in the skeleton unit is required (as the value present in the .dwo file could not be relocated during linking of the skeleton units), such as for the addrptr class.

[Issue 221203.1]

Section 3.2.5 Imported Unit Entries, page 74

Replace "normal or partial compilation unit" with "normal or partial compilation unit entry".

The place where a normal or partial compilation unit is imported is represented by a debugging information entry with the tag DW_TAG_imported_unit. An imported unit entry contains a DW_AT_import attribute whose value is a reference to the normal or partial compilation unit entry whose declarations logically belong at the place of the imported unit entry.

[Issue 181019.1]

3.4 Call Site Entries and Parameters, page 89

Clarify use of call site entries for tail recursion and optimized-out calls.

DW_TAG_call_site entries describe normal and tail calls but not tail recursion calls, while DW_TAG_inlined_subroutine entries describe inlined calls (see Section 3.3.8 on page 81). Call site entries cannot without a DW_AT_call_return_pc attribute may describe tail recursion or optimized out calls.

[Issue 211103.1]

Section 3.9 Declarations with Reduced Scope, page 94

In case (1)(b), remove "a default location entry," which does not apply here.

b) If the address range of the containing scope is non-contiguous (see 2.17.3 on page 52) the value of this attribute is the offset in bytes of the beginning of the address range for the scope of the entity from the beginning of the first range list entry for the containing scope that is not a base address entry, a default location entry or an end-of-list entry.

[Issue 200505.7]

In case (2), change "rnglistptr" to "rnglist".

2. Otherwise, the set of addresses for the scope of the entity is specified using a value of class rnglistsptr rnglist. This value indicates the beginning of a range list (see Section 2.17.3 on page 52).

[Issue 241231.2]

Chapter 5: Type Entries

Section 5.7.10 Variant Entries, page 123

Clarify meaning of a variant part without a discriminant.

If the variant part does not have a discriminant (tag field), the variant part entry has a DW_AT_type attribute to represent the tag type.

A reference to a type supports the Pascal notion of a tagless variant part where the omitted tag nonetheless is given a type whose values are used in later parts of the variant syntax.

[Issue 180517.1]

Chapter 6: Other Debugging Information

Section 6.1.1 Lookup By Name, page 136

Replace "load module" with "module."

An executable or shareable object file may contain either a collection of "per-CU" indexes, simply copied from each relocatable object file, or the linker may produce a "per-module" index by combining the per-CU indexes into a single index that covers the entire load module.

[Issue 200505.2]

Section 6.1.1.4.1 Section Header, page 144

Clarify contents of the name index augmentation field.

10. augmentation_string_size (uword)

The size in bytes of the augmentation string sequence. This value is rounded up to must be a multiple of 4.

11. augmentation_string (sequence of UTF-8 characters ubyte)

A vendor-specific augmentation string sequence of bytes, which provides additional information about the contents of this index. If provided, the string sequence begins with a 4-character four bytes which serve as a vendor ID. The remainder of the string sequence is meant to be read by a cooperating consumer, and its contents and interpretation are not specified here. The string augmentation is padded with null characters to a multiple of four bytes in length.

The presence of an unrecognised augmentation string does not make it impossible for a consumer to process data in the .debug_names section. The augmentation string only provides hints to the consumer regarding the completeness of the set of names in the index.

[Issue 200505.4]

Section 6.1.1.4.5 Hash Lookup Table, page 145

Delete accidental LaTeX markup.

For the purposes of the hash computation, each symbol name should be folded according to the simple case folding algorithm defined in the "Caseless Matching" subsection of Section 5.18 ("Case Mappings") of the Unicode Standard, Version 9.0.0. The original symbol name, as it appears in the source code, should be stored in the name table.name index!case folding

[Issue 210218.1]

Section 6.2 Line Number Information, page 149

Clarify the compression technique for the line number program.

Such a matrix, however, would be impractically large. We shrink it with two techniques. First, we delete from the matrix each row whose file, line, source column and discriminator is identical with that of its predecessors, except where the instruction is marked as a suggested breakpoint location, the end of a prologue region, or the beginning of an epilogue region. Any deleted row would never be the beginning of a source statement. Second, we design a byte-coded language for a state machine and store a stream of bytes in the object file instead of the matrix. This language can be much more compact than the matrix. To the line number information a consumer must “run” the state machine to generate the matrix for each compilation unit of interest. The concept of an encoded matrix also leaves room for expansion. In the future, columns can be added to the matrix to encode other things that are related to individual instruction addresses.

[Issue 240320.2]

Section 6.2.2 State Machine Registers, page 152

In Table 6.3, remove extraneous word from description of the "discriminator" register.

An unsigned integer identifying the block to which the current instruction belongs. Discriminator values are assigned arbitrarily by the DWARF producer and serve to distinguish among multiple blocks that may all be associated with the same source file, line, and column. Where only one block exists for a given source position, the discriminator value is be zero.

[Issue 200505.6]

Section 6.2.4 Line Number Program Header, page 156

Item 15, directories_count, should note that it is new in DWARF 5.

15. directories_count (ULEB128) A count of the number of entries that occur in the following directories field. This field is new in DWARF 5.

[Issue 180914.1]

Section 6.2.4 Line Number Program Header, page 157

In item 16, directories, clarify meaning of relative paths.

The first entry is the current directory of the compilation. Each additional path entry is either a full path name or is relative to the current directory of the compilation. If the current directory itself is specified as a relative path, it is relative to the location of the linked image containing the line table entries.

[Issue 210628.1]

Section 6.3.1 Macro Information Header, page 166

Clarify that references to line table from a .dwo file are to .debug_line.dwo section.

3. debug_line_offset

An offset in the .debug_line section (if this header is in a .debug_macro section) or .debug_line.dwo section (if this header is in a .debug_macro.dwo section) of the beginning of the line number information in the containing compilation, encoded as a 4-byte offset for a 32-bit DWARF format macro section and an 8-byte offset for a 64-bit DWARF format macro section.

Section 6.3.3.1 Source Include Directives, page 169

Clarify that references to line table from a .dwo file are to .debug_line.dwo section.

If a DW_MACRO_start_file entry is present, the header contains a reference to the .debug_line section or .debug_line.dwo section of the compilation, as appropriate.

[Issue 200602.1]

Section 6.4.2.4 Row State Instructions, page 181

Clarify that DW_CFA_remember_state should take the current CFA into account.

1. DW_CFA_remember_state

The DW_CFA_remember_state instruction takes no operands. The required action is to push the set of rules for the current CFA and every register onto an implicit stack.

[Issue 230103.1]

Chapter 7: Data Representation

Section 7.3.1 Relocatable Object Files, page 186

After the bullet item for DW_FORM_strp, add a bullet item for the .debug_macro section.

The .debug_macro section may have DW_MACRO_define_strp and DW_MACRO_undef_strp entries (see Section 6.3.2.1). These entries refer to strings in the .debug_str section. These values require relocation.

[Issue 211102.1]

Section 7.3.2.2 Second Partition, page 188

In the sixth bullet item, referring the specialized line number table, add references to macro information.

A specialized line number table (for the type units, and macro information), in the .debug_line.dwo section.

This table contains only the directory and filename lists needed to interpret DW_AT_decl_file attributes in the debugging information entries and DW_MACRO_start_file entries in the macro information.

[Issue 200602.1]

Section 7.3.2.2 Second Partition, page 189

Clarify use of string offsets table.

A string offsets table, in the .debug_str_offsets.dwo section for the strings in the .debug_str.dwo section.

Attributes that refer to the .debug_str.dwo string table do so only indirectly through the .debug_str_offsets.dwo section using the form DW_FORM_strx, DW_FORM_strx1, DW_FORM_strx2, DW_FORM_strx3, or DW_FORM_strx4, as well as macro entries DW_MACRO_define_strx or DW_MACRO_undef_strx. Direct reference using form DW_FORM_strp or DW_FORM_strp8, as well as the macro entries DW_MACRO_define_strp or DW_MACRO_undef_strp, is not allowed.

[Issue 211102.1]

Section 7.3.2.2 Second Partition, page 189

Clarify reference forms that cannot be used in a .dwo file.

Split DWARF object files do not get linked with any other files, therefore references between sections must not make use of normal object file relocation information. As a result, symbolic references within or between sections (such as from using DW_FORM_ref_addr and DW_OP_call_ref) are not possible. Split DWARF object files contain at most one compilation unit.

[Issue 181003.1]

Section 7.3.3 Executable Objects and .dwo Files, page 189

Clarify (non-)relocation of .dwo files.

The sections containing the debugging information are typically not loaded as part of the memory image of the program (in ELF terminology, the sections are not "allocatable" and are not part of a loadable segment). Therefore, the debugging information sections described in this document are typically linked as if they were each to be loaded at virtual address 0, and references within the debugging information always implicitly indicate which section a particular offset refers to. Similarly, debugging information in a .dwo file is not loaded in the memory image. The absence (or non-use) of relocation information in a .dwo file means that sections described in this document are effectively linked as if they were each to be loaded at virtual address 0. In both cases, references within the debugging information always implicitly indicate which section a particular offset refers to. (For example, a reference of form DW_FORM_sec_offset may refer to one of several sections, depending on the class allowed by a particular attribute of a debugging information entry, as shown in Table 7.5.)

[Issue 211102.1]

Section 7.4 32-Bit and 64-Bit DWARF Formats, page 198

Fix typo in bullet 7.

7. In the body of the .debug_loclists and .debug_rnglists sections, the offsets the that follow the header depend on the DWARF format as follows: in the 32-bit DWARF format, offsets are 4-byte unsigned integer values; in the 64-bit DWARF format, they are 8-byte unsigned integers.

[Issue 210622.1]

Section 7.4 32-Bit and 64-Bit DWARF Formats, page 198

Move note from below the itemized list of rules to immediately after the first paragraph of the section, adding a new non-normative paragraph.

The 32-bit and 64-bit DWARF format conventions must not be intermixed within a single compilation unit.

This rule greatly simplifies parsing DWARF in some cases. For example, the DW_AT_str_offsets_base attribute points to the zeroth entry of the string offset array, not to the header of that portion of the .debug_str_offsets section, making it inconvenient to determine the size of the entries in the array. By requiring that the referencing compilation unit and the referenced array use the same format, a consumer can know the array entry size without needing to find the .debug_str_offsets header.

Attribute values and section header fields that represent addresses in the target program are not affected by these rules.

[Issue 180326.1]

Section 7.5.3 Abbreviations Tables, page 206

In Table 7.3, DW_TAG_hi_user should be 0xffff, but is rendered in the PDF with spaces.

Section 7.5.4 Attribute Encodings, page 212

In Table 7.5, DW_AT_hi_user should be 0x3fff, but is rendered in the PDF with spaces.

[Issue 180613.1]

Section 7.5.3 Abbreviations Tables, page 207

Clarify the descriptions of DW_FORM_indirect and DW_FORM_implicit_const.

Finally, the child encoding is followed by a series of attribute specifications. Each attribute specification consists of two parts (except for DW_FORM_implicit_const and DW_FORM_indirect, see below). The first part is an unsigned LEB128 number representing the attribute’s name. The second part is an unsigned LEB128 number representing the attribute’s form. The series of attribute specifications ends with an entry containing 0 for the name and 0 for the form.

The attribute form DW_FORM_indirect is a special case. For attributes with this form, the attribute value itself in the .debug_info section begins with an unsigned LEB128 number that represents its form. This allows producers to choose forms for particular attributes dynamically, without having to add a new entry to the abbreviations table.

The attribute form DW_FORM_implicit_const is another special case. For attributes with this form, the attribute specification contains a third part, which is a signed LEB128 number. The value of this number is used as the value of the attribute, and no value is stored in the .debug_info section.

For attributes with the form DW_FORM_implicit_const, in addition to the attribute name and form values, the attribute specification contains a third part, which is a signed LEB128 number. The value of this number is used as the value of the attribute.

For attributes with the form DW_FORM_indirect, the actual attribute form value itself is in the .debug_info section which begins with an unsigned LEB128 number that specifies the actual form, followed by the value according to that form. This allows producers to choose forms for particular attributes dynamically, without having to add a new entry to the abbreviations table.

If the actual attribute form is DW_FORM_implicit_const, the form is (still) followed by a signed LEB128 number.

If the actual attribute form is itself DW_FORM_indirect, the indirection repeats. There may be one or more occurrences of DW_FORM_indirect in sequence until a non-DW_FORM_indirect form is reached. The sequence of DW_FORM_indirect forms does not have any effect other than to use up space.

[Issue 221114.1]

Section 7.5.4 Attribute Encodings, page 211

In Table 7.5, change class for DW_AT_call_origin to reference.

Attribute name Value Classes

DW_AT_call_origin 0x7f exprloc reference

Attribute name	Value	Classes
`DW_AT_call_origin`	0x7f	exprloc reference

[Issue 171103.1]

Section 7.5.5 Classes and Forms, pages 215–216

In the first bullet item under loclist, add reference to the .dwo section:

An index into the .debug_loclists or .debug_loclists.dwo section (DW_FORM_loclistx)....

In the first bullet item under rnglist, add reference to the .dwo section:

An index into the .debug_rnglists or .debug_rnglists.dwo section (DW_FORM_rnglistx)....

[Issue 250311.1]

Section 7.5.5 Classes and Forms, page 217

Remove text about references from one module to another.

The second type of reference can identify any debugging information entry within a .debug_info section; in particular, it may refer to an entry in a different compilation unit from the unit containing the reference, and may refer to an entry in a different shared object file. This type of reference (DW_FORM_ref_addr) is an offset from the beginning of the .debug_info section of the target executable or shared object file, or, for references within a supplementary object file, an offset from the beginning of the local .debug_info section; it is relocatable in a relocatable object file and frequently relocated in an executable or shared object file. For references from one shared object or static executable file to another, the relocation and identification of the target object must be performed by the consumer. In the 32-bit DWARF format, this offset is a 4-byte unsigned value; in the 64-bit DWARF format, it is an 8-byte unsigned value (see Section 7.4 on page 196).

[Issue 230120.1]

Section 7.34 Contiguous Tables (NEW), page 250

Clarify that DWARF tables in a section must be contiguous with no padding.

Tables must be contiguous with the preceding table in the section or start of the section if there is no preceding table.

[Issue 230329.1]

Appendix A: Attributes by Tag

Intro section, page 251

Clarify that DW_AT_artificial may be used in places not specifically mentioned in the specification. Add a fifth bullet covering the conventions for DW_AT_artificial:

5. The DW_AT_artificial attribute can be used with any declarative debugging information entry. For simplicity, this attribute is not shown.

Remove DW_AT_artificial from all rows of Table A.1.

[Issue 211108.1]

Appendix B: Debug Section Relationships

Section B.2 Split DWARF Section Relationships

In Figure B.2 and following notes, remove arcs (do) and (po).

(do) .debug_info.dwo to .debug_str.dwo

Attribute values of class string may have form DW_FORM_strp, whose value is an offset in the .debug_str.dwo section of the corresponding string.

(po) .debug_macro.dwo to .debug_str.dwo

[There was no note for this arc in the following text.]

[Issue 211102.1]

Section B.2 Split DWARF Section Relationships

In Figure B.2 and following notes, remove arc (fo).

(fo) .debug_info.dwo to .debug_info.dwo

The operand of the DW_OP_call_ref DWARF expression operator is the offset of a debugging information entry in the .debug_info.dwo section of another compilation unit. Similarly for attribute operands that use DW_FORM_ref_addr. See Section 2.5.1.5 on page 35.

[Issues 181003.1, 220708.1]

Appendix D: Examples

Section D.1.3 DWARF Location Description Examples, pages 291-292

Clarify DW_OP_entry_value examples.

[Issue 230808.1]

Section D.2.1 Fortran Simple Array Example, page 294

Remove reference to non-existent example.

If an object has a descriptor, then the DWARF type for that object will have a DW_AT_data_location attribute. If an object does not have a descriptor, then usually the DWARF type for the object will not have a DW_AT_data_location attribute. (See the following Ada example for a case where the type for an object without a descriptor does have a DW_AT_data_location attribute. In that case the object doubles as its own descriptor.)

[Issue 241231.1]

Appendix E: Compression

Section E.3.2 Eliminating function duplication, page 388

In third paragraph, replace second instance of <file-designator> with <function-designator>.

References to other .debug_info sections follow the approach suggested above, but the naming rule is slightly different in that the <file-designator> should be interpreted as a <file-designator> <function-designator>.

[Issue 171130.1]

Appendix F: Split DWARF Object Files

Section F.1 Overview, page 392

Add clarifying text to end of last paragraph on page 392 and remove first paragraph on page 393.

In a .dwo file, there is no benefit to having a separate string section for directories and file names because the primary string table will never be stripped. Accordingly, no .debug_line_str.dwo section is defined. Content descriptions corresponding to DW_FORM_line_strp in an executable file (for example, in the skeleton compilation unit) instead use one of the forms DW_FORM_strx, DW_FORM_strx1, DW_FORM_strx2, DW_FORM_strx3 or DW_FORM_strx4. This allows directory and file name strings to be merged with general strings and across compilations in package files (where they are not subject to potential stripping). This merge is facilitated by the requirement that all references to the .debug_str.dwo string table are made indirectly through the .debug_str_offsets.dwo section so that only that section needs to be modified during string merging.

In a .dwo file, referring to a string using DW_FORM_strp is valid, but such use results in a file that cannot be incorporated into a package file (which involves string merging).

[Issue 211102.1]