Issue 200505.4: Augmentation string

Author: David Anderson
Champion: Dave Anderson
Date submitted: 2020-05-05
Date revised: 2022-05-16
Date closed: 2022-05-16
Type: Editorial
Status: Accepted
DWARF Version: 6
Section 6.1.1.4.1, pg 144

The very unusual augmentation string needs some
elaboration for clarity.

Here is the full original DWARF5 wording on page 144, Sec 6.1.1.4.1

As a whole it clearly presents a non-null-terminated
string with the odd aspect of possible null-bytes.
So neither a standard length-known string nor a null-terminated
string.

Because a non-null terminated string whose length field
may cover null-bytes after the non-null bytes is so unusual in
the DWARF context a few words should be added (see below).

Problem: the original text is not precise (what does it mean 
by 'character', given it implies ASCII but does not say so?)
and calling it 'string' leads to confusion because it does not
quite fit the dwarf standard definition of a 'string'.  The 
original allowance of multi-byte (UTF-8) characters in the 
vendor id initial four characters seems unnecessary.

Originally the two section header fields numbered 10 and 11 
referred to 'string' Ron B. and David A. considered 'block'
but settled on 'sequence'.

We propose this as an appropriate replacement for the DWARF5
text.  All instances of 'string' in the original text of 10.
and 11. have been removed or replaced (depending on context).

ASCII DWARF5 content remains valid with this wording and we 
believe this is sufficiently precise. For example, LLVM's
DWARF5 interpretation remains valid with the wording proposed below. 

================original text 
page 144:
10. augmentation_string_size (uword)

The size in bytes of the augmentation string. This value must be
a multiple of four, possibly zero.
. 

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

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

--
2021-03-14:  Updated.
2021-10-18:  Accepted.
2022-03-20:  Reopened.
2022-03-26:  Revised.
             Previous version: http://dwarfstd.org/issues/200505.4-1.html
2022-05-16:  Revised to replace 'character' with 'string of bytes'.
2022-05-16:  Accepted.