You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
308 lines
12 KiB
HTML
308 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- 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." -->
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<title>Index Section Format (Debugging with GDB)</title>
|
|
|
|
<meta name="description" content="Index Section Format (Debugging with GDB)">
|
|
<meta name="keywords" content="Index Section Format (Debugging with GDB)">
|
|
<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="Man-Pages.html#Man-Pages" rel="next" title="Man Pages">
|
|
<link href="Trace-File-Format.html#Trace-File-Format" rel="prev" title="Trace File Format">
|
|
<style type="text/css">
|
|
<!--
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
|
blockquote.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
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.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<a name="Index-Section-Format"></a>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Man-Pages.html#Man-Pages" accesskey="n" rel="next">Man Pages</a>, Previous: <a href="Trace-File-Format.html#Trace-File-Format" accesskey="p" rel="prev">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="Man-Pages.html#Man-Pages" accesskey="n" rel="next">Man Pages</a>, Previous: <a href="Trace-File-Format.html#Trace-File-Format" accesskey="p" rel="prev">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>
|