Skip to content

Commit 0a4aeec

Browse files
niconico
committed
Convert PDB docs to unix line endings. No other changes.
llvm-svn: 359712
1 parent a0df4d3 commit 0a4aeec

File tree

7 files changed

+848
-848
lines changed

7 files changed

+848
-848
lines changed

‎llvm/docs/PDB/GlobalStream.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
=====================================
2-
The PDB Global Symbol Stream
3-
=====================================
1+
=====================================
2+
The PDB Global Symbol Stream
3+
=====================================

‎llvm/docs/PDB/HashTable.rst

+103-103
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,103 @@
1-
The PDB Serialized Hash Table Format
2-
====================================
3-
4-
.. contents::
5-
:local:
6-
7-
.. _hash_intro:
8-
9-
Introduction
10-
============
11-
12-
One of the design goals of the PDB format is to provide accelerated access to
13-
debug information, and for this reason there are several occasions where hash
14-
tables are serialized and embedded directly to the file, rather than requiring
15-
a consumer to read a list of values and reconstruct the hash table on the fly.
16-
17-
The serialization format supports hash tables of arbitrarily large size and
18-
capacity, as well as value types and hash functions. The only supported key
19-
value type is a uint32. The only requirement is that the producer and consumer
20-
agree on the hash function. As such, the hash function can is not discussed
21-
further in this document, it is assumed that for a particular instance of a PDB
22-
file hash table, the appropriate hash function is being used.
23-
24-
On-Disk Format
25-
==============
26-
27-
.. code-block:: none
28-
29-
.--------------------.-- +0
30-
| Size |
31-
.--------------------.-- +4
32-
| Capacity |
33-
.--------------------.-- +8
34-
| Present Bit Vector |
35-
.--------------------.-- +N
36-
| Deleted Bit Vector |
37-
.--------------------.-- +M ─╮
38-
| Key | │
39-
.--------------------.-- +M+4 │
40-
| Value | │
41-
.--------------------.-- +M+4+sizeof(Value) │
42-
... ├─ |Capacity| Bucket entries
43-
.--------------------. │
44-
| Key | │
45-
.--------------------. │
46-
| Value | │
47-
.--------------------. ─╯
48-
49-
- **Size** - The number of values contained in the hash table.
50-
51-
- **Capacity** - The number of buckets in the hash table. Producers should
52-
maintain a load factor of no greater than ``2/3*Capacity+1``.
53-
54-
- **Present Bit Vector** - A serialized bit vector which contains information
55-
about which buckets have valid values. If the bucket has a value, the
56-
corresponding bit will be set, and if the bucket doesn't have a value (either
57-
because the bucket is empty or because the value is a tombstone value) the bit
58-
will be unset.
59-
60-
- **Deleted Bit Vector** - A serialized bit vector which contains information
61-
about which buckets have tombstone values. If the entry in this bucket is
62-
deleted, the bit will be set, otherwise it will be unset.
63-
64-
- **Keys and Values** - A list of ``Capacity`` hash buckets, where the first
65-
entry is the key (always a uint32), and the second entry is the value. The
66-
state of each bucket (valid, empty, deleted) can be determined by examining
67-
the present and deleted bit vectors.
68-
69-
70-
.. _hash_bit_vectors:
71-
72-
Present and Deleted Bit Vectors
73-
===============================
74-
75-
The bit vectors indicating the status of each bucket are serialized as follows:
76-
77-
.. code-block:: none
78-
79-
.--------------------.-- +0
80-
| Word Count |
81-
.--------------------.-- +4
82-
| Word_0 | ─╮
83-
.--------------------.-- +8 │
84-
| Word_1 | │
85-
.--------------------.-- +12 ├─ |Word Count| values
86-
... │
87-
.--------------------. │
88-
| Word_N | │
89-
.--------------------. ─╯
90-
91-
The words, when viewed as a contiguous block of bytes, represent a bit vector with
92-
the following layout:
93-
94-
.. code-block:: none
95-
96-
.------------. .------------.------------.
97-
| Word_N | ... | Word_1 | Word_0 |
98-
.------------. .------------.------------.
99-
| | | | |
100-
+N*32 +(N-1)*32 +64 +32 +0
101-
102-
where the k'th bit of this bit vector represents the status of the k'th bucket
103-
in the hash table.
1+
The PDB Serialized Hash Table Format
2+
====================================
3+
4+
.. contents::
5+
:local:
6+
7+
.. _hash_intro:
8+
9+
Introduction
10+
============
11+
12+
One of the design goals of the PDB format is to provide accelerated access to
13+
debug information, and for this reason there are several occasions where hash
14+
tables are serialized and embedded directly to the file, rather than requiring
15+
a consumer to read a list of values and reconstruct the hash table on the fly.
16+
17+
The serialization format supports hash tables of arbitrarily large size and
18+
capacity, as well as value types and hash functions. The only supported key
19+
value type is a uint32. The only requirement is that the producer and consumer
20+
agree on the hash function. As such, the hash function can is not discussed
21+
further in this document, it is assumed that for a particular instance of a PDB
22+
file hash table, the appropriate hash function is being used.
23+
24+
On-Disk Format
25+
==============
26+
27+
.. code-block:: none
28+
29+
.--------------------.-- +0
30+
| Size |
31+
.--------------------.-- +4
32+
| Capacity |
33+
.--------------------.-- +8
34+
| Present Bit Vector |
35+
.--------------------.-- +N
36+
| Deleted Bit Vector |
37+
.--------------------.-- +M ─╮
38+
| Key | │
39+
.--------------------.-- +M+4 │
40+
| Value | │
41+
.--------------------.-- +M+4+sizeof(Value) │
42+
... ├─ |Capacity| Bucket entries
43+
.--------------------. │
44+
| Key | │
45+
.--------------------. │
46+
| Value | │
47+
.--------------------. ─╯
48+
49+
- **Size** - The number of values contained in the hash table.
50+
51+
- **Capacity** - The number of buckets in the hash table. Producers should
52+
maintain a load factor of no greater than ``2/3*Capacity+1``.
53+
54+
- **Present Bit Vector** - A serialized bit vector which contains information
55+
about which buckets have valid values. If the bucket has a value, the
56+
corresponding bit will be set, and if the bucket doesn't have a value (either
57+
because the bucket is empty or because the value is a tombstone value) the bit
58+
will be unset.
59+
60+
- **Deleted Bit Vector** - A serialized bit vector which contains information
61+
about which buckets have tombstone values. If the entry in this bucket is
62+
deleted, the bit will be set, otherwise it will be unset.
63+
64+
- **Keys and Values** - A list of ``Capacity`` hash buckets, where the first
65+
entry is the key (always a uint32), and the second entry is the value. The
66+
state of each bucket (valid, empty, deleted) can be determined by examining
67+
the present and deleted bit vectors.
68+
69+
70+
.. _hash_bit_vectors:
71+
72+
Present and Deleted Bit Vectors
73+
===============================
74+
75+
The bit vectors indicating the status of each bucket are serialized as follows:
76+
77+
.. code-block:: none
78+
79+
.--------------------.-- +0
80+
| Word Count |
81+
.--------------------.-- +4
82+
| Word_0 | ─╮
83+
.--------------------.-- +8 │
84+
| Word_1 | │
85+
.--------------------.-- +12 ├─ |Word Count| values
86+
... │
87+
.--------------------. │
88+
| Word_N | │
89+
.--------------------. ─╯
90+
91+
The words, when viewed as a contiguous block of bytes, represent a bit vector with
92+
the following layout:
93+
94+
.. code-block:: none
95+
96+
.------------. .------------.------------.
97+
| Word_N | ... | Word_1 | Word_0 |
98+
.------------. .------------.------------.
99+
| | | | |
100+
+N*32 +(N-1)*32 +64 +32 +0
101+
102+
where the k'th bit of this bit vector represents the status of the k'th bucket
103+
in the hash table.

‎llvm/docs/PDB/ModiStream.rst

+80-80
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,80 @@
1-
=====================================
2-
The Module Information Stream
3-
=====================================
4-
5-
.. contents::
6-
:local:
7-
8-
.. _modi_stream_intro:
9-
10-
Introduction
11-
============
12-
13-
The Module Info Stream (henceforth referred to as the Modi stream) contains
14-
information about a single module (object file, import library, etc that
15-
contributes to the binary this PDB contains debug information about. There
16-
is one modi stream for each module, and the mapping between modi stream index
17-
and module is contained in the :doc:`DBI Stream <DbiStream>`. The modi stream
18-
for a single module contains line information for the compiland, as well as
19-
all CodeView information for the symbols defined in the compiland. Finally,
20-
there is a "global refs" substream which is not well understood.
21-
22-
.. _modi_stream_layout:
23-
24-
Stream Layout
25-
=============
26-
27-
A modi stream is laid out as follows:
28-
29-
30-
.. code-block:: c++
31-
32-
struct ModiStream {
33-
uint32_t Signature;
34-
uint8_t Symbols[SymbolSize-4];
35-
uint8_t C11LineInfo[C11Size];
36-
uint8_t C13LineInfo[C13Size];
37-
38-
uint32_t GlobalRefsSize;
39-
uint8_t GlobalRefs[GlobalRefsSize];
40-
};
41-
42-
- **Signature** - Unknown. In practice only the value of ``4`` has been
43-
observed. It is hypothesized that this value corresponds to the set of
44-
``CV_SIGNATURE_xx`` defines in ``cvinfo.h``, with the value of ``4``
45-
meaning that this module has C13 line information (as opposed to C11 line
46-
information). A corollary of this is that we expect to only ever see
47-
C13 line info, and that we do not understand the format of C11 line info.
48-
49-
- **Symbols** - The :ref:`CodeView Symbol Substream <modi_symbol_substream>`.
50-
``SymbolSize`` is equal to the value of ``SymByteSize`` for the
51-
corresponding module's entry in the :ref:`Module Info Substream <dbi_mod_info_substream>`
52-
of the :doc:`DBI Stream <DbiStream>`.
53-
54-
- **C11LineInfo** - A block containing CodeView line information in C11
55-
format. ``C11Size`` is equal to the value of ``C11ByteSize`` from the
56-
:ref:`Module Info Substream <dbi_mod_info_substream>` of the
57-
:doc:`DBI Stream <DbiStream>`. If this value is ``0``, then C11 line
58-
information is not present. As mentioned previously, the format of
59-
C11 line info is not understood and we assume all line in modern PDBs
60-
to be in C13 format.
61-
62-
- **C13LineInfo** - A block containing CodeView line information in C13
63-
format. ``C13Size`` is equal to the value of ``C13ByteSize`` from the
64-
:ref:`Module Info Substream <dbi_mod_info_substream>` of the
65-
:doc:`DBI Stream <DbiStream>`. If this value is ``0``, then C13 line
66-
information is not present.
67-
68-
- **GlobalRefs** - The meaning of this substream is not understood.
69-
70-
.. _modi_symbol_substream:
71-
72-
The CodeView Symbol Substream
73-
=============================
74-
75-
The CodeView Symbol Substream. This is an array of variable length
76-
records describing the functions, variables, inlining information,
77-
and other symbols defined in the compiland. The entire array consumes
78-
``SymbolSize-4`` bytes. The format of a CodeView Symbol Record (and
79-
thusly, an array of CodeView Symbol Records) is described in
80-
:doc:`CodeViewSymbols`.
1+
=====================================
2+
The Module Information Stream
3+
=====================================
4+
5+
.. contents::
6+
:local:
7+
8+
.. _modi_stream_intro:
9+
10+
Introduction
11+
============
12+
13+
The Module Info Stream (henceforth referred to as the Modi stream) contains
14+
information about a single module (object file, import library, etc that
15+
contributes to the binary this PDB contains debug information about. There
16+
is one modi stream for each module, and the mapping between modi stream index
17+
and module is contained in the :doc:`DBI Stream <DbiStream>`. The modi stream
18+
for a single module contains line information for the compiland, as well as
19+
all CodeView information for the symbols defined in the compiland. Finally,
20+
there is a "global refs" substream which is not well understood.
21+
22+
.. _modi_stream_layout:
23+
24+
Stream Layout
25+
=============
26+
27+
A modi stream is laid out as follows:
28+
29+
30+
.. code-block:: c++
31+
32+
struct ModiStream {
33+
uint32_t Signature;
34+
uint8_t Symbols[SymbolSize-4];
35+
uint8_t C11LineInfo[C11Size];
36+
uint8_t C13LineInfo[C13Size];
37+
38+
uint32_t GlobalRefsSize;
39+
uint8_t GlobalRefs[GlobalRefsSize];
40+
};
41+
42+
- **Signature** - Unknown. In practice only the value of ``4`` has been
43+
observed. It is hypothesized that this value corresponds to the set of
44+
``CV_SIGNATURE_xx`` defines in ``cvinfo.h``, with the value of ``4``
45+
meaning that this module has C13 line information (as opposed to C11 line
46+
information). A corollary of this is that we expect to only ever see
47+
C13 line info, and that we do not understand the format of C11 line info.
48+
49+
- **Symbols** - The :ref:`CodeView Symbol Substream <modi_symbol_substream>`.
50+
``SymbolSize`` is equal to the value of ``SymByteSize`` for the
51+
corresponding module's entry in the :ref:`Module Info Substream <dbi_mod_info_substream>`
52+
of the :doc:`DBI Stream <DbiStream>`.
53+
54+
- **C11LineInfo** - A block containing CodeView line information in C11
55+
format. ``C11Size`` is equal to the value of ``C11ByteSize`` from the
56+
:ref:`Module Info Substream <dbi_mod_info_substream>` of the
57+
:doc:`DBI Stream <DbiStream>`. If this value is ``0``, then C11 line
58+
information is not present. As mentioned previously, the format of
59+
C11 line info is not understood and we assume all line in modern PDBs
60+
to be in C13 format.
61+
62+
- **C13LineInfo** - A block containing CodeView line information in C13
63+
format. ``C13Size`` is equal to the value of ``C13ByteSize`` from the
64+
:ref:`Module Info Substream <dbi_mod_info_substream>` of the
65+
:doc:`DBI Stream <DbiStream>`. If this value is ``0``, then C13 line
66+
information is not present.
67+
68+
- **GlobalRefs** - The meaning of this substream is not understood.
69+
70+
.. _modi_symbol_substream:
71+
72+
The CodeView Symbol Substream
73+
=============================
74+
75+
The CodeView Symbol Substream. This is an array of variable length
76+
records describing the functions, variables, inlining information,
77+
and other symbols defined in the compiland. The entire array consumes
78+
``SymbolSize-4`` bytes. The format of a CodeView Symbol Record (and
79+
thusly, an array of CodeView Symbol Records) is described in
80+
:doc:`CodeViewSymbols`.

0 commit comments

Comments
 (0)