DWARF5 Clarifications

From wiki.dwarfstd.org
Revision as of 15:02, 30 June 2022 by Davea (talk | contribs) (Now mentions DWARF6 final wording may differ from what this page says.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

DWARF5 Clarifications

Describing ambiguities in the DWARF5 Standard (released in 2017) which interfere with understanding the documents.

ISSUE (where present) refers to the numbered ISSUES page on dwarfstd.org

Created 2021-10-08

With reasonably full data. The wording here should not be treated as authoritative, the eventual DWARF6 standard wording may differ.

See also DWARF5 Errata

Section Copyright Page ii

ISSUE: Not created. The 2005 copyright year on the third line from the top should probably not be there.

Section 1.4 indefinite antecedents (et al) Page 10 line 11

ISSUE 210314.1

Here is a brief presentation of edits to remove indefinite antecedents across all of DWARF5.

1) Page 10, lines 11-12

-type. (Previously it described the size of the optional
+type. (Previously DW_AT_byte_size described the size of the optional

2) Page 163, lines 34-35

-information alone; it must be determined in combination
+information alone; the function must be determined in combination

3) Page 164 line 34

-stores a relocatable value into it instead.
+stores a relocatable value into the address register instead.

4) Page 170 lines 23

-as though it occurs in place of the import operation.
+as though the sequence of entries occurs in place of the import operation.

5) Page 172 lines 33-34

-Canonical Frame Address value; it may be either a register
+Canonical Frame Address value; the rule may be either a register

6) Page 347 lines 2-4

-a specific range), it may choose to materialize that
+a specific range), the compiler may choose to materialize that


7) Page 405 lines 21-22

-section in a non-split object, but it has some small
+section in a non-split object, but the section has some small

Section 2.6.1.2, DW_OP_piece, DW_OP_bit_piece Page 42 line 25 and later

ISSUE 191025.1

The following issue, ISSUE 161206.2, is on the same pair of attributes. The wording here (for each) is not necessarily the final text for DWARF6 and the presentation here is not necessarily complete.

The DWARF6 document drops the DWARF5 sentence If the location is a register, the offset is from the least significant bit end of the register.

In addition, before the non-normative text (see just below) the normative text In all other cases, the source of the piece is either a register or an implicit value description (section 2.6.1.1.4); the offset is from the least significant bit of the register or implicit value. will be added to the DWARF6 document.



Section 2.6.1.2, DW_OP_piece, DW_OP_bit_piece Page 42 lines 11-32

ISSUE 161206.2

See also the previous ISSUE 191025.1.

The DWARF5 specifications of DW_OP_piece and DW_OP_bit_piece do not make it sufficiently clear whether DW_OP_piece is just a backward-compatible short-hand notation for special cases of DW_OP_bit_piece.

To clarify this the DWARF6 document will add non-normative text.

For instance, so that structure variables passed by register can be loaded and stored using register-sized transfers, a big-endian ABI may specify that the pieces of a structure are "left aligned" within a register (located in the most significant bytes of the register). Thus,DW_OP_piece <n> is not necessarily equivalent to DW_OP_bit_piece <8*n> 0.

Figure 6.1 Names Table Page 139

ISSUE number not yet created.

Partly due to page size constraints this page of the Name Index Layout leaves out the blob for the Abbrev Table, which goes after the Entry Offsets and before Index Entries.

Figure 6.1 Names Table Page 140.

ISSUE number not yet created

Partly due to page size constraints the text identifying the content of the Index Table and the Abbrev Table is somewhat misleading.

The Abbrev Table does not contain attributes (unlike what the graphic implies). The Abbrev Table is a sequence of abbrev-code followed by attribute-form pairs ended by 0,0. Followed by the next abbrev code entry.

Entry Pool values are sequences of abbrev-code followed by values (Exactly as in .debug_info where abbrev-codes are followed by values). So the index entry text is possibly misleading.

An abbrev code of zero is the end of Entry Table entries for a given name string.

An abbrev code in the Entry Table is a link to the Abbrev Table.

Section 6.1.1.2: Structure of the Name Index. page 141 line 16.

ISSUE 200505.3

Text: The standard attributes are:

No replacement text has been defined, but the reader should be aware that in this phrase the attributes are Index Attributes, defined in Table 6.1, page 147.

Possibly it should read The standard Index Attributes are: and there should be a link to Table 6.1.

Section 6.1.1.4.1 Header unit_length Page 143 line 14

ISSUE 180625.1

The definition of unit_length is inconsistent across the document, as is the spelling of initial length (initial_length). Next we show all the places involved.

In 6.1.1.4.1 Page 143 it is The length of this contribution to the name index section, not including the length field itself.

Other places with this about unit_length are

Section 6.1.2 Lookup By Address Page 147

Section 6.2.4 Line Number Program Header Page 154, which has a link to Section 7.2.2 Page 184.

a link all unit_length fields should have.

Section 7.5.1.1 Full and Partial Compilation Unit Page 200 has a longer description.

Section 7.5.1.2 Skeleton and Split Compilation Unit Headers Page 201 has a longer description

Section 7.5.1.3 Type Unit Headers has a longer description. Page 202 has a longer description

Section 7.2.1 Address Range Table Page 235 has a longer description.

Section 7.2.2 Initial Length Values page 184

Section 7.26 String Offsets Table Page 240 has a longer description.

Section 7.2.7 Address Table page 241 has a longer description.

Section 7.28 Range List Table Page 242 has a longer description.

Section 7.29 Location List Table Page 243 has a longer description.


Section 7.5.1 Unit Headers Page 199 calls the initial field initial_length which is spelled initial length everywhere unit_length appears.

Apparently all instances should be spelled initial length.

Section 6.1.1.4.8 Entry Pool Page 147 lines 5-8

ISSUE Not Created

"Each index entry in the series begins with an abbreviation code, and is followed by the attributes described by the abbreviation declaration for that code. The last index entry in the series is followed by a terminating entry whose abbreviation code is 0."

The text is is unnecessarily opaque.

It is actually followed by the attribute values. The attribute numbers and FORMS are in the Abbrev Table.

Section 7.6 LEB128 Page 221 lines 11-12

ISSUE 180503.1

DWARF5 says:

Typically, several of the high order bytes will be zero; discard them.

Replace the sentence with

Typically, several of the high order bytes will be zero,which may be discarded.

Add the non-normative paragraph

Some producers may choose to insert padding or alignment bytes by retaining (not discarding) one or more high-order bytes that would not affect the decoded value.

The wording allows extra zero bytes but does not guarantee that an arbitrary length of extra zero bytes can be read as valid.

Section B.1 Debug section relationships Page 274 Figure B.1

ISSUE 200427.1

1) Missing an arc from .debug_rnglists to .debug_addr; the arc should be there because of a couple of DW_RLE entry types that use .debug_addr indexes.

2) Along the same lines, the arc from .debug_loclists to .debug_addr and note (o) to the figure mention only two DW_OP expression opcodes, there are also a couple of DW_LLE entry types that use .debug_addr indexes.