Google Git
Sign in
android-kvm / toolchains / linux-x86 / gcc / fed620776f0e84cb3f4428b51ebf7e04618da707 / . / aarch64-linux-gnu-4.9 / share / doc / gdb / gdb / Index-Section-Format.html
blob: ea2af7faf1b5a6e25895c51b47e5294bc24fb8cb [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2015 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.2, 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="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.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="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> &nbsp; [<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
(&lsquo;<samp>DW_TAG_type_unit</samp>&rsquo;) refer to the type unit&rsquo;s symbol table and not the
compilation unit (&lsquo;<samp>DW_TAG_comp_unit</samp>&rsquo;) 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&rsquo;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&rsquo;s name. Starting with an
initial value of <code>r = 0</code>, each (unsigned) character &lsquo;<samp>c</samp>&rsquo; 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 &lsquo;<samp>\0</samp>&rsquo; is not incorporated into the hash.
</p>
<p>The step size used in the hash table is computed via
<code>((hash * 17) &amp; (size - 1)) | 1</code>, where &lsquo;<samp>hash</samp>&rsquo; is the hash
value, and &lsquo;<samp>size</samp>&rsquo; 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&rsquo;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&rsquo;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-&gt;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 &amp;&amp; language != JAVA);
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 &amp;&amp; language != JAVA);
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> &nbsp; [<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>