[binutils-gdb] Document GDB extensions to DWARF .debug_names

[binutils-gdb] Document GDB extensions to DWARF .debug_names

[Tom Tromey]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=374807b60751a5f890005d16dd8b466b22185a3f

commit 374807b60751a5f890005d16dd8b466b22185a3f
Author: Tom Tromey <tom@tromey.com>
Date:   Sun Dec 3 13:42:29 2023 -0700

    Document GDB extensions to DWARF .debug_names
    
    GDB's new .debug_names implementation uses some extensions.  This
    patch adds some documentation on this to the manual.
    
    Reviewed-By: Eli Zaretskii <eliz@gnu.org>

Diff:
---
 gdb/doc/gdb.texinfo | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 55ebf752435..e98c15242bc 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21479,6 +21479,7 @@ program.  To debug a core dump of a previous run, you must also tell
 * Separate Debug Files::        Debugging information in separate files
 * MiniDebugInfo::               Debugging information in a special section
 * Index Files::                 Index files speed up GDB
+* Debug Names::                 Extensions to .debug_names
 * Symbol Errors::               Errors reading symbol files
 * Data Files::                  GDB data files
 @end menu
@@ -22682,6 +22683,44 @@ Print the number of cache hits and misses since the launch of @value{GDBN}.
 
 @end table
 
+@node Debug Names
+@section Extensions to @samp{.debug_names}
+@cindex index files
+@cindex @samp{.debug_names} section
+
+The DWARF specification documents an optional index section called
+@samp{.debug_names}.  @value{GDBN} can both read and create this
+section.  However, in order to work with @value{GDBN}, some extensions
+were necessary.
+
+@value{GDBN} uses the augmentation string @samp{GDB2}.  Earlier
+versions used the string @samp{GDB}, but these versions of the index
+are no longer supported.
+
+@value{GDBN} does not use the specified hash table.  Therefore,
+because this hash table is optional, @value{GDBN} also does not write
+it.
+
+@value{GDBN} also generates and uses some extra index attributes:
+@table @code
+@item DW_IDX_GNU_internal
+This has the value @samp{0x2000}.  It is a flag that, when set,
+indicates that the associated entry has @code{static} linkage.
+
+@item DW_IDX_GNU_main
+This has the value @samp{0x2002}.  It is a flag that, when set,
+indicates that the associated entry is the program's @code{main}.
+
+@item DW_IDX_GNU_language
+This has the value @samp{0x2003}.  It is @samp{DW_LANG_} constant,
+indicating the language of the associated entry.
+
+@item DW_IDX_GNU_linkage_name
+This has the value @samp{0x2004}.  It is a flag that, when set,
+indicates that the associated entry is a linkage name, and not a
+source name.
+@end table
+
 @node Symbol Errors
 @section Errors Reading Symbol Files