Issue 251122.1: New .debug_names index attributes

Author:	Simon Marchi
Champion:
Date submitted:	2025-11-22
Date revised:	2026-03-16
Date closed:
Type:	Enhancement
Status:	Open
DWARF version:	6

Overview

This proposal adds four DW_IDX_* attributes for use in .debug_names index entries. These attributes are currently produced and consumed by GDB as an extension to DWARF 5. The new attributes provide some information that helps it build its in-memory name index at startup without having to peek at the .debug_info section.

The proposed attributes are:

DW_IDX_main_subprogram: It is a flag that, when set, indicates that the associated entry is the program's main subprogram. An index entry with DW_IDX_main_subprogram means that the associated DIE has the DW_AT_main_subprogram flag.

Note: in its extensions, GDB calls this DW_IDX_GNU_main, but I think it would be preferable for the name to match DW_AT_main_subprogram.

Note: GDB ingests the name index into its own in-memory index structure, which means it can find which entries have the DW_IDX_main_subprogram attribute at no additional cost. This attribute would not be very useful to other consumers that might memory-map the name index and use it directly as-is, because they would need to search all index entries to find which ones have the DW_IDX_main_subprogram attribute, something they presumably don't want to do. I included it as-is in the proposal, because this is what we have implementation experience with.

Alternatively, or additionally, we could consider a field of some sort in the section header that would point to the index entries that are main subprograms.
DW_IDX_language_name and DW_IDX_language_version: They are respectively a DW_LNAME_ constant and an integer constant, indicating the language of the associated entry. They reflect the DW_AT_language_name and DW_AT_language_version attributes of the unit containing the associated DIE.

Note: in its extensions, GDB uses DW_IDX_GNU_language, which is equivalent to the DWARF 5 DW_AT_language attribute (removed by issue 210419.1).

Note: I made the wording such that if the containing unit has the language attributes, then it is mandatory for the index entries to have the corresponding attributes. Otherwise, I don't see how a consumer could know whether it can trust what is in the index or not.

Note: in the .debug_info section, languages are associated with units, not individual symbols. It is probably not space-efficient to attach the language information to each index entry. I included it as-is in the proposal, because this is what we have implementation experience with.

Alternatively, we could find a way to have this information per-unit in the CU/TU lists. A consumer would be able to find the language associated with an entry by taking the offset of the associated DIE and finding which unit contains it in the appropriate CU/TU list (the closest unit with an offset smaller than the offset of the DIE).
DW_IDX_linkage_name: It is a flag that, when set, indicates that the associated entry is a linkage name, and not a source name. An index entry with DW_IDX_linkage_name means that the name associated with this entry is the DW_AT_linkage_name of the associated DIE, not the DW_AT_name.

Proposed Changes

Section 7.1.1.4.8 Abbreviations Table

Add the following entries to Table 7.1 ("Index attribute encodings"):

Index attribute name	Meaning
`DW_IDX_main_subprogram`	Whether `DW_AT_main_subprogram` is set on the DIE
`DW_IDX_language_name`	Language name of the containing unit
`DW_IDX_language_version`	Language version of the containing unit
`DW_IDX_linkage_name`	Whether the name is the source name (`DW_AT_name`) or the linkage name (`DW_AT_linkage_name`) of the DIE

Section 7.1.1.4.9 Entry Pool

Add the following text after the paragraph about DW_IDX_external:

Each index entry has a flag indicating whether the corresponding DIE has the DW_AT_main_subprogram attribute with a true value. If the DW_IDX_main_subprogram attribute is missing from an entry, it means that DW_AT_main_subprogram is false for that DIE.

Each index entry may have the DW_IDX_language_name and DW_IDX_language_version attributes. If present, their values reflect the DW_AT_language_name and DW_AT_language_version attributes of the unit containing the corresponding DIE. If missing, this indicates that the containing unit has no DW_AT_language_versionor DW_AT_language_version attribute, respectively.

Each index entry has a flag indicating whether the name is the source or linkage name of the corresponding DIE. If the DW_IDX_linkage_name attribute is present and true, the name corresponds to the DW_AT_linkage_name attribute of the DIE. If the DW_IDX_linkage_name attribute is false or missing, the name corresponds to the DW_AT_name attribute of the DIE.

Section 8.19 Name Index Table

Add the following entries to Table 8.23 ("Name index attribute encodings"):

Attribute name	Value	Form/Class
`DW_IDX_main_subprogram`	[TBD]	flag
`DW_IDX_language_name`	[TBD]	constant
`DW_IDX_language_version`	[TBD]	constant
`DW_IDX_linkage_name`	[TBD]	flag

Replace:

It is suggested that producers should use the form code DW_FORM_flag_present for the DW_IDX_external attribute for abbreviation codes that represent external names.

With:

It is suggested that producers should use the form code DW_FORM_flag_present for the DW_IDX_external, DW_IDX_main_subprogram and DW_IDX_linkage_name attributes.

References

GDB Documentation: Debug Names Section

2026-03-16: Fixed typos and character encoding issues.

View Markdown Source