[05/17] Document GDB extensions to DWARF .debug_names
Checks
Commit Message
GDB's new .debug_names implementation uses some extensions. This
patch adds some documentation on this to the manual.
---
gdb/doc/gdb.texinfo | 39 +++++++++++++++++++++++++++++++++++++++
1 file changed, 39 insertions(+)
Comments
> From: Tom Tromey <tom@tromey.com>
> Date: Sun, 10 Dec 2023 09:44:54 -0700
>
> GDB's new .debug_names implementation uses some extensions. This
> patch adds some documentation on this to the manual.
> ---
> gdb/doc/gdb.texinfo | 39 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 39 insertions(+)
Thanks.
> +@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
> +
After reading this, I wonder what is the purpose of having this i the
manual. This section seems to assume the reader is familiar with the
DWARF spec, including some of its very intimate details. Is that
really the case? For example, the part about the "augmentation
string", or the description of the extra index attributes -- what kind
of readers of the manual will need this information, and for what
purposes?
But if this information is deemed useful, I have no objections for it
being included, and it's fine by me, both English-wise and
markup-wise.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
Eli> After reading this, I wonder what is the purpose of having this i the
Eli> manual. This section seems to assume the reader is familiar with the
Eli> DWARF spec, including some of its very intimate details. Is that
Eli> really the case? For example, the part about the "augmentation
Eli> string", or the description of the extra index attributes -- what kind
Eli> of readers of the manual will need this information, and for what
Eli> purposes?
Eli> But if this information is deemed useful, I have no objections for it
Eli> being included, and it's fine by me, both English-wise and
Eli> markup-wise.
gdb has expectations for this section that go beyond what DWARF
specifies. So, this text is technical documentation about a format used
by gdb, for other people working on debuginfo tools; sort of like how
.gdb_index is also documented.
Tom
@@ -21477,6 +21477,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
@@ -22680,6 +22681,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