Re: [PATCH v2 8/8] Update .debug_names documentation

[Simon Marchi <simark@simark.ca>]

On 2026-01-26 16:33, Tom Tromey wrote:
> This updates the .debug_names documentation to explain some DWARF
> issues that we've handled in gdb.
> 
> This list still isn't exhaustive.  I think there are some situations
> where gdb may examine a declaration (which DWARF says not to do), but
> I didn't document this as I don't recall the details.
> ---
>  gdb/doc/gdb.texinfo | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 80f49e21b7e..1b3813286e6 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -23297,6 +23297,43 @@ source name.
>  
>  @end table
>  
> +@value{GDBN} also has some special handling for cases not considered
> +in the DWARF specification.
> +
> +@itemize @bullet
> +@item
> +The @code{DW_IDX_parent} for a C-style enumerator does not point at
> +the entry for @code{enum} itself, but rather the parent of the type.
> +The reason for this is that C-style enumerators are injected into the
> +containing scope, and so their name is not qualified by the
> +@code{enum}; and furthermore there is no way to distinguish between
> +C-style enumerators and @code{enum class}-style enumerators in
> +@samp{.debug_names}.

Ok, so IIUC: there is a way to distinguish between C enums and C++
enum-class enums in the debug info itself, but not in .debug_names.  So
there is no way just from the index to tell if an enumerator name should
be visible from the enclosing scope of not.

It sounds like another fix I could bring up to the committee, if we can
find a good solution.

Note: I found this proposal that suggested adding enumerators to the
index, and it was rejected, "Size impact would be too great.".

https://dwarfstd.org/issues/230224.1.html

So, is putting enumerators in .debug_names an extension to the standard
in itself?

I don't really understand the logic of not putting the non-enum-class
enumerators in the index.  If you have:

enum Foo {
  Foo_Bar = 12,
};

then you want "print Foo_Bar" to work, which requires "Foo_bar" to be
find-able.

> +
> +@item
> +Similarly, @code{DW_IDX_parent} is omitted for any linkage name
> +entries that are written.

Is this just an optimization? Because for a linkage name, you don't need
to know the parent, since there is not need to build the fully qualified
name?

I don't know if this is actually an extension or not.  Is it mandantory
to include a DW_IDX_parent (if there is an indexed parent), according to
the spec?  As usual, DWARF is not clear about that.

I suppose that this works in conjunction with DW_IDX_GNU_linkage_name?
It is currently being proposed for standardization here:

https://dwarfstd.org/issues/251122.1.html

If accepted, I could propose a change that says clearly "for entries
with DW_IDX_linkage_name, a DW_IDX_parent is not required".

> +
> +@item
> +Definitions in partial units are handled differently.  These most
> +typically are seen in the output of @code{dwz}.
> +
> +In general, a DWARF partial unit cannot be read in isolation, but only
> +by reading it in the context of some other unit that references it via
> +@code{DW_TAG_imported_unit}.
> +
> +Therefore, an ordinary definition in a partial unit is attributed to
> +one of the outermost containing units.  This is done by referencing
> +this containing CU in the @code{DW_IDX_compile_unit} attribute.

It's not explicitly said in the spec, but this is how I understand it is
expected to work.  There is no way to for an index entry to reference a
PU anyway.

> +A further special case applies to @code{DW_TAG_inlined_subroutine}
> +entries.  An inlined subroutine appearing in a partial unit may be
> +inlined in all of the outermost compilation units that directly or
> +indirectly include the partial unit.  Therefore, in this case,
> +@value{GDBN} will emit a separate index entry for the entry, once for
> +each such containing unit.
> +@end itemize

This question probably relates more to the previous patch, but I don't
quite understand why this applies to inlined functions but not to other
entities found in the PU.  You'd think that if you have a static
(file-local) variable defined in a PU, it means that all including CUs
have this variable defined.  So wouldn't you want an entry at that name
for all these CUs?

Simon