Issue 231110.3: DWARF Extension Registry
| Author: | Ben Woodard |
|---|---|
| Champion: | Mark Wielaard |
| Date submitted: | 2023-11-10 |
| Date revised: | 2024-03-25 |
| Date closed: | |
| Type: | Enhancement |
| Status: | Open |
| DWARF Version: | 6 |
Background
This is an Enhancement request split off from Issue 231110.1 to introduce a DWARF Extension Registry.
The DWARF standard has always had the wisdom to acknowledge the need for Vendor Extensibility. Section 1.3.13 describes this policy. For the producers it explicitly reserves some of the valid values for encoding various constructs and promises not to use those values in future versions of the standard. Consumers are given the freedom and expected to skip over data that they do not recognize.
The original intent of these vendor extensions was that they would be a private agreement between a particular producer and a cooperating consumer. However, the range of tools expanded beyond a toolchain provided by a single vendor and so the concept of a private agreement between a specific producer and a cooperating consumer came to be regarded as a registry of vendor extensions that every tool must be aware of for the sake of compatibility.
Overview
This proposal seeks to foster compatibility and collaboration by taking the collection of informal registries such as elfutils and llvm (gcc and libdwarf sources also contain lists of extensions) and collects them and brings them under the aegis of the DWARF standards body. To facilitate innovation and quickly meet producer’s and consumer’s needs the expectation is that registering a new producer specific construct and encoding would be a simple, light weight or even partially automated task. It would not be at all like amending the standard. The registry would be published on the DWARF standard’s web site so that consumers can easily find it. Each extension would be listed along with the producers that emit it.
Extensions that persist over several versions of the DWARF standard probably should be considered for inclusion into the official standard.
Proposed Changes
Section 1.3.13
Add two paragraphs, one for producers and one for consumers referring them to a "url" on the dwarfstd.org website referring to the new DWARF Extension Registry:
Implementers who make extensions are strongly encouraged to design them to be compatible with this specification in the absence of those extensions. Implementers should also register them at
<url>so that they can be included in the database of known extensions which can be found at<url>. This will allow consumers that they are not directly cooperating with to be aware of their extensions and know how to interpret them.While the DWARF format is organized so that a consumer can skip over data which it does not recognize and this may allow a consumer to read and process files generated according to a later version of this standard or which contain producer specific extensions, albeit possibly in a degraded manner, this has been found to reduce the tool compatibility which users have come to expect. Consumers should therefore refer to
<url>when encountering a producer specific construct that they are not familiar with.
Section 6.1.1.2 Structure of the Name Index
The paragraph:
A producer may define additional vendor-specific attributes, and a consumer will be able to ignore and skip over any attributes it is not prepared to handle.
is replaced by:
A producer may define additional producer-specific attributes, and a consumer should be able to ignore and skip over any attributes it is not prepared to handle. However, to achieve full compatibility a consumer should refer to
<url>where all known producer specific attributes that apply to the Name Index are enumerated.
Section 6.2.4 The Line Number Program Header
The non-normative text following the section should be changed to:
If a consumer encounters a producer-defined content type that it does not understand, it should skip the content data as though it were not present. However, to achieve full compatibility the consumer’s developer should refer to
<url>where all known producer-defined line number content descriptors are enumerated.
Section 6.3.1 Macro Information Header
In the second paragraph of item 4 the phrase “Vendor extension entry opcodes” should be replaced with “Producer specific entry opcodes”.
Section 7.1 Vendor Extensibility
Add the end of the section add:
To ensure full tool intercompatibility, producer defined DWARF extensions should be registered with the DWARF standards body at
<url>.
2024-03-25: Split from 231110.1.
Mark to provide a mockup of the DWARF Extensions Registry page and instructions on the minimal amount of data to provide to add new extensions.
