Issue 231110.3: DWARF Extension Registry
| Author: | Ben Woodard |
|---|---|
| Champion: | Mark Wielaard |
| Date submitted: | 2023-11-10 |
| Date revised: | 2024-11-26 |
| Date closed: | |
| Type: | Enhancement |
| Status: | Open |
| DWARF version: | 6 |
Comparing original with latest. [ Return to the latest version ]
## Background This is an Enhancement request split off from Issue [231110.1][231110.1] to introduce a DWARF Extension Registry. [231110.1]: 231110.1.html
The DWARF standard has always had the wisdom to acknowledge the need for
The DWARF standard has always had the wisdom to acknowledge the need
Vendor Extensibility. Section 1.3.13 describes this policy. For the
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
versions of the standard. Producers are given the freedom to use these
to skip over data that they do not recognize.
values and consumers are 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
consumer. However, the range of tools has expanded beyond a toolchain
provided by a single vendor and so the concept of a private agreement
provided by a single vendor. The concept of a private agreement
between a specific producer and a cooperating consumer came to be
between a specific producer and a cooperating consumer has been replaced
regarded as a registry of vendor extensions that every tool must be
by the notion of a registry of producer 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][1] and [llvm][2] (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
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. [1]: https://sourceware.org/elfutils/DwarfExtensions [2]: https://llvm.org/docs/SourceLevelDebugging.html#new-dwarf-tags ## Proposed Changes
### Section 1.3.13
### Section 1.3.13 Extensibility
Add two paragraphs, one for producers and one for consumers referring
Add two paragraphs, one for producer developers and one for consumer
them to a "url" on the dwarfstd.org website referring to the new
developers, that refer them to a url on the `dwarfstd.org` website for the
DWARF Extension Registry:
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
> Producer developers who make extensions should design them to be compatible > with this specification. They should also register the extension > name and code (which must be in the user extension range) by sending > an email explaining them to `dwarf-discuss@lists.dwarfstd.org` so that
> can be included in the database of known extensions which can be found
> they can be included in the database of known extensions found at > `https://dwarfstd.org/producerextensions.html`. This > will allow consumer developers that are not even known to them to be > aware of their extensions and know how to interpret them.
> 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.
> 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. Consumer developers should therefore > refer to `https://dwarfstd.org/producerextensions.html` 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
> To ensure full tool intercompatibility, producer-defined DWARF
> extensions should be registered with the DWARF standards body at `<url>`.
> extensions should be registered with the DWARF standards body by > sending an email to `dwarf-discuss@lists.dwarfstd.org` that includes > the proposed names and constant codes in the user extension range so > they can be included at `https://dwarfstd.org/producerextensions.html`. > Please reserve an extension code early to prevent overlap. When you > send an email to `dwarf-discuss@dwarfstd.org` with a proposed > number, you'll get a response back with an alternative if the number > is already in use.
---
2024-03-25: Split from [231110.1][231110.1].
2024-03-25: [Original proposal][orig]. Split from [231110.1][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.
2024-06-10: General approval, but needs revisions: (1) Only need to mention in 1.3.13 and 7.1, leave other places unchanged; (2) Mark suggested URL dwarfstd.org/extensions.html. Extensions page on website will have instructions for registering extensions. During discussion of [231110.4][231110.4], suggestion to include any available info on validity of extensions wrt versions of DWARF, and whether extensions have been superseded by new standard features. [231110.4]: 231110.4.html 2024-11-26: [Revised][diff1] background, removed changes to Chapter 6, and revised wording in Chapters 1 and 7.
