251 lines
10 KiB
HTML
251 lines
10 KiB
HTML
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Index Section Format - Debugging with GDB</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="Debugging with GDB">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="prev" href="Trace-File-Format.html#Trace-File-Format" title="Trace File Format">
|
||
|
|
<link rel="next" href="Man-Pages.html#Man-Pages" title="Man Pages">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
Copyright (C) 1988-2019 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.''
|
||
|
|
-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Index-Section-Format"></a>
|
||
|
|
<p>
|
||
|
|
Next: <a rel="next" accesskey="n" href="Man-Pages.html#Man-Pages">Man Pages</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="Trace-File-Format.html#Trace-File-Format">Trace File Format</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="appendix">Appendix J <code>.gdb_index</code> section format</h2>
|
||
|
|
|
||
|
|
<p><a name="index-g_t_002egdb_005findex-section-format-3679"></a><a name="index-index-section-format-3680"></a>
|
||
|
|
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>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>A mapped index consists of several areas, laid out in order.
|
||
|
|
|
||
|
|
<ol type=1 start=1>
|
||
|
|
<li>The file header. This is a sequence of values, of <code>offset_type</code>
|
||
|
|
unless otherwise noted:
|
||
|
|
|
||
|
|
<ol type=1 start=1>
|
||
|
|
<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><span class="samp">DW_TAG_type_unit</span></samp>’) refer to the type unit's symbol table and not the
|
||
|
|
compilation unit (‘<samp><span class="samp">DW_TAG_comp_unit</span></samp>’) using the type.
|
||
|
|
|
||
|
|
<p><span class="sc">gdb</span> 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.
|
||
|
|
|
||
|
|
<li>The offset, from the start of the file, of the CU list.
|
||
|
|
|
||
|
|
<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>The offset, from the start of the file, of the address area.
|
||
|
|
|
||
|
|
<li>The offset, from the start of the file, of the symbol table.
|
||
|
|
|
||
|
|
<li>The offset, from the start of the file, of the constant pool.
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<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>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>The address area. The address area consists of a sequence of address
|
||
|
|
entries. Each address entry has three elements:
|
||
|
|
|
||
|
|
<ol type=1 start=1>
|
||
|
|
<li>The low address. This is a 64-bit little-endian value.
|
||
|
|
|
||
|
|
<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>The CU index. This is an <code>offset_type</code> value.
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<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>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>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><span class="samp">c</span></samp>’ in
|
||
|
|
the string is incorporated into the hash using the formula depending on the
|
||
|
|
index version:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>Version 4<dd>The formula is <code>r = r * 67 + c - 113</code>.
|
||
|
|
|
||
|
|
<br><dt>Versions 5 to 7<dd>The formula is <code>r = r * 67 + tolower (c) - 113</code>.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The terminating ‘<samp><span class="samp">\0</span></samp>’ is not incorporated into the hash.
|
||
|
|
|
||
|
|
<p>The step size used in the hash table is computed via
|
||
|
|
<code>((hash * 17) & (size - 1)) | 1</code>, where ‘<samp><span class="samp">hash</span></samp>’ is the hash
|
||
|
|
value, and ‘<samp><span class="samp">size</span></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>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.
|
||
|
|
|
||
|
|
<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>A string in the constant pool is zero-terminated.
|
||
|
|
</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>The format of each CU index+attributes entry is as follows
|
||
|
|
(bit 0 = LSB):
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>Bits 0-23<dd>This is the index of the CU in the CU list.
|
||
|
|
<br><dt>Bits 24-27<dd>These bits are reserved for future purposes and must be zero.
|
||
|
|
<br><dt>Bits 28-30<dd>The kind of the symbol in the CU.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>0<dd>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.
|
||
|
|
<br><dt>1<dd>The symbol is a type.
|
||
|
|
<br><dt>2<dd>The symbol is a variable or an enum value.
|
||
|
|
<br><dt>3<dd>The symbol is a function.
|
||
|
|
<br><dt>4<dd>Any other kind of symbol.
|
||
|
|
<br><dt>5,6,7<dd>These values are reserved.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br><dt>Bit 31<dd>This bit is zero if the value is global and one if it is static.
|
||
|
|
|
||
|
|
<p>The determination of whether a symbol is global or static is complicated.
|
||
|
|
The authorative reference is the file <samp><span class="file">dwarf2read.c</span></samp> in
|
||
|
|
<span class="sc">gdb</span> sources.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>This pseudo-code describes the computation of a symbol's kind and
|
||
|
|
global/static attributes in the index.
|
||
|
|
|
||
|
|
<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>
|
||
|
|
</body></html>
|
||
|
|
|