diff options
Diffstat (limited to 'share/doc/gdb/Index-Section-Format.html')
| -rw-r--r-- | share/doc/gdb/Index-Section-Format.html | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/share/doc/gdb/Index-Section-Format.html b/share/doc/gdb/Index-Section-Format.html new file mode 100644 index 0000000..30bd6fe --- /dev/null +++ b/share/doc/gdb/Index-Section-Format.html @@ -0,0 +1,308 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs +Free Documentation", with the Front-Cover Texts being "A GNU Manual," +and with the Back-Cover Texts as in (a) below. + +(a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Debugging with GDB: Index Section Format</title> + +<meta name="description" content="Debugging with GDB: Index Section Format"> +<meta name="keywords" content="Debugging with GDB: Index Section Format"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Debuginfod.html#Debuginfod" rel="next" title="Debuginfod"> +<link href="Trace-File-Format.html#Trace-File-Format" rel="previous" title="Trace File Format"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Index-Section-Format"></a> +<div class="header"> +<p> +Next: <a href="Debuginfod.html#Debuginfod" accesskey="n" rel="next">Debuginfod</a>, Previous: <a href="Trace-File-Format.html#Trace-File-Format" accesskey="p" rel="previous">Trace File Format</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="g_t_002egdb_005findex-section-format"></a> +<h2 class="appendix">Appendix J <code>.gdb_index</code> section format</h2> +<a name="index-_002egdb_005findex-section-format"></a> +<a name="index-index-section-format"></a> + +<p>This section documents the index section that is created by <code>save +gdb-index</code> (see <a href="Index-Files.html#Index-Files">Index Files</a>). The index section is +DWARF-specific; some knowledge of DWARF is assumed in this +description. +</p> +<p>The mapped index file format is designed to be directly +<code>mmap</code>able on any architecture. In most cases, a datum is +represented using a little-endian 32-bit integer value, called an +<code>offset_type</code>. Big endian machines must byte-swap the values +before using them. Exceptions to this rule are noted. The data is +laid out such that alignment is always respected. +</p> +<p>A mapped index consists of several areas, laid out in order. +</p> +<ol> +<li> The file header. This is a sequence of values, of <code>offset_type</code> +unless otherwise noted: + +<ol> +<li> The version number, currently 8. Versions 1, 2 and 3 are obsolete. +Version 4 uses a different hashing function from versions 5 and 6. +Version 6 includes symbols for inlined functions, whereas versions 4 +and 5 do not. Version 7 adds attributes to the CU indices in the +symbol table. Version 8 specifies that symbols from DWARF type units +(‘<samp>DW_TAG_type_unit</samp>’) refer to the type unit’s symbol table and not the +compilation unit (‘<samp>DW_TAG_comp_unit</samp>’) using the type. + +<p><small>GDB</small> will only read version 4, 5, or 6 indices +by specifying <code>set use-deprecated-index-sections on</code>. +GDB has a workaround for potentially broken version 7 indices so it is +currently not flagged as deprecated. +</p> +</li><li> The offset, from the start of the file, of the CU list. + +</li><li> The offset, from the start of the file, of the types CU list. Note +that this area can be empty, in which case this offset will be equal +to the next offset. + +</li><li> The offset, from the start of the file, of the address area. + +</li><li> The offset, from the start of the file, of the symbol table. + +</li><li> The offset, from the start of the file, of the constant pool. +</li></ol> + +</li><li> The CU list. This is a sequence of pairs of 64-bit little-endian +values, sorted by the CU offset. The first element in each pair is +the offset of a CU in the <code>.debug_info</code> section. The second +element in each pair is the length of that CU. References to a CU +elsewhere in the map are done using a CU index, which is just the +0-based index into this table. Note that if there are type CUs, then +conceptually CUs and type CUs form a single list for the purposes of +CU indices. + +</li><li> The types CU list. This is a sequence of triplets of 64-bit +little-endian values. In a triplet, the first value is the CU offset, +the second value is the type offset in the CU, and the third value is +the type signature. The types CU list is not sorted. + +</li><li> The address area. The address area consists of a sequence of address +entries. Each address entry has three elements: + +<ol> +<li> The low address. This is a 64-bit little-endian value. + +</li><li> The high address. This is a 64-bit little-endian value. Like +<code>DW_AT_high_pc</code>, the value is one byte beyond the end. + +</li><li> The CU index. This is an <code>offset_type</code> value. +</li></ol> + +</li><li> The symbol table. This is an open-addressed hash table. The size of +the hash table is always a power of 2. + +<p>Each slot in the hash table consists of a pair of <code>offset_type</code> +values. The first value is the offset of the symbol’s name in the +constant pool. The second value is the offset of the CU vector in the +constant pool. +</p> +<p>If both values are 0, then this slot in the hash table is empty. This +is ok because while 0 is a valid constant pool index, it cannot be a +valid index for both a string and a CU vector. +</p> +<p>The hash value for a table entry is computed by applying an +iterative hash function to the symbol’s name. Starting with an +initial value of <code>r = 0</code>, each (unsigned) character ‘<samp>c</samp>’ in +the string is incorporated into the hash using the formula depending on the +index version: +</p> +<dl compact="compact"> +<dt>Version 4</dt> +<dd><p>The formula is <code>r = r * 67 + c - 113</code>. +</p> +</dd> +<dt>Versions 5 to 7</dt> +<dd><p>The formula is <code>r = r * 67 + tolower (c) - 113</code>. +</p></dd> +</dl> + +<p>The terminating ‘<samp>\0</samp>’ is not incorporated into the hash. +</p> +<p>The step size used in the hash table is computed via +<code>((hash * 17) & (size - 1)) | 1</code>, where ‘<samp>hash</samp>’ is the hash +value, and ‘<samp>size</samp>’ is the size of the hash table. The step size +is used to find the next candidate slot when handling a hash +collision. +</p> +<p>The names of C<tt>++</tt> symbols in the hash table are canonicalized. We +don’t currently have a simple description of the canonicalization +algorithm; if you intend to create new index sections, you must read +the code. +</p> +</li><li> The constant pool. This is simply a bunch of bytes. It is organized +so that alignment is correct: CU vectors are stored first, followed by +strings. + +<p>A CU vector in the constant pool is a sequence of <code>offset_type</code> +values. The first value is the number of CU indices in the vector. +Each subsequent value is the index and symbol attributes of a CU in +the CU list. This element in the hash table is used to indicate which +CUs define the symbol and how the symbol is used. +See below for the format of each CU index+attributes entry. +</p> +<p>A string in the constant pool is zero-terminated. +</p></li></ol> + +<p>Attributes were added to CU index values in <code>.gdb_index</code> version 7. +If a symbol has multiple uses within a CU then there is one +CU index+attributes value for each use. +</p> +<p>The format of each CU index+attributes entry is as follows +(bit 0 = LSB): +</p> +<dl compact="compact"> +<dt>Bits 0-23</dt> +<dd><p>This is the index of the CU in the CU list. +</p></dd> +<dt>Bits 24-27</dt> +<dd><p>These bits are reserved for future purposes and must be zero. +</p></dd> +<dt>Bits 28-30</dt> +<dd><p>The kind of the symbol in the CU. +</p> +<dl compact="compact"> +<dt>0</dt> +<dd><p>This value is reserved and should not be used. +By reserving zero the full <code>offset_type</code> value is backwards compatible +with previous versions of the index. +</p></dd> +<dt>1</dt> +<dd><p>The symbol is a type. +</p></dd> +<dt>2</dt> +<dd><p>The symbol is a variable or an enum value. +</p></dd> +<dt>3</dt> +<dd><p>The symbol is a function. +</p></dd> +<dt>4</dt> +<dd><p>Any other kind of symbol. +</p></dd> +<dt>5,6,7</dt> +<dd><p>These values are reserved. +</p></dd> +</dl> + +</dd> +<dt>Bit 31</dt> +<dd><p>This bit is zero if the value is global and one if it is static. +</p> +<p>The determination of whether a symbol is global or static is complicated. +The authorative reference is the file <samp>dwarf2read.c</samp> in +<small>GDB</small> sources. +</p> +</dd> +</dl> + +<p>This pseudo-code describes the computation of a symbol’s kind and +global/static attributes in the index. +</p> +<div class="smallexample"> +<pre class="smallexample">is_external = get_attribute (die, DW_AT_external); +language = get_attribute (cu_die, DW_AT_language); +switch (die->tag) + { + case DW_TAG_typedef: + case DW_TAG_base_type: + case DW_TAG_subrange_type: + kind = TYPE; + is_static = 1; + break; + case DW_TAG_enumerator: + kind = VARIABLE; + is_static = language != CPLUS; + break; + case DW_TAG_subprogram: + kind = FUNCTION; + is_static = ! (is_external || language == ADA); + break; + case DW_TAG_constant: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_variable: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_namespace: + kind = TYPE; + is_static = 0; + break; + case DW_TAG_class_type: + case DW_TAG_interface_type: + case DW_TAG_structure_type: + case DW_TAG_union_type: + case DW_TAG_enumeration_type: + kind = TYPE; + is_static = language != CPLUS; + break; + default: + assert (0); + } +</pre></div> + +<hr> +<div class="header"> +<p> +Next: <a href="Debuginfod.html#Debuginfod" accesskey="n" rel="next">Debuginfod</a>, Previous: <a href="Trace-File-Format.html#Trace-File-Format" accesskey="p" rel="previous">Trace File Format</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |