# DWARF Extension Registry ## 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 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][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 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 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.org` so that > 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. > 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 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.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: [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.