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 |
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. Producers are given the freedom to use these 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 has expanded beyond a toolchain provided by a single vendor. The concept of a private agreement between a specific producer and a cooperating consumer has been replaced 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 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 Extensibility
Add two paragraphs, one for producer developers and one for consumer
developers, that refer them to a url on the dwarfstd.org website for the
new DWARF Extension Registry:
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.orgso that they can be included in the database of known extensions found athttps://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.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.htmlwhen encountering a producer-specific construct that they are not familiar with.
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 by sending an email to
dwarf-discuss@lists.dwarfstd.orgthat includes the proposed names and constant codes in the user extension range so they can be included athttps://dwarfstd.org/producerextensions.html.Please reserve an extension code early to prevent overlap. When you send an email to
dwarf-discuss@dwarfstd.orgwith a proposed number, you'll get a response back with an alternative if the number is already in use.
2024-03-25: Original proposal. 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.
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, suggestion to include any available info on validity of extensions wrt versions of DWARF, and whether extensions have been superseded by new standard features.
2024-11-26: Revised background, removed changes to Chapter 6, and revised wording in Chapters 1 and 7.
