llvm.org GIT mirror llvm / 3b7c9b9
[PDB] Add documentation for the PDB Stream. https://reviews.llvm.org/D26516 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@286852 91177308-0d34-0410-b5e6-96231b3b80d8 Zachary Turner 2 years ago
1 changed file(s) with 80 addition(s) and 3 deletion(s). Raw diff Collapse all Expand all
None ========================================
1 The PDB Info Stream (aka the PDB Stream)
2 ========================================
0 ========================================
1 The PDB Info Stream (aka the PDB Stream)
2 ========================================
3
4 .. contents::
5 :local:
6
7 .. _pdb_stream_header:
8
9 Stream Header
10 =============
11 At offset 0 of the PDB Stream is a header with the following layout:
12
13
14 .. code-block:: c++
15
16 struct PdbStreamHeader {
17 ulittle32_t Version;
18 ulittle32_t Signature;
19 ulittle32_t Age;
20 Guid UniqueId;
21 };
22
23 - **Version** - A Value from the following enum:
24
25 .. code-block:: c++
26
27 enum class PdbStreamVersion : uint32_t {
28 VC2 = 19941610,
29 VC4 = 19950623,
30 VC41 = 19950814,
31 VC50 = 19960307,
32 VC98 = 19970604,
33 VC70Dep = 19990604,
34 VC70 = 20000404,
35 VC80 = 20030901,
36 VC110 = 20091201,
37 VC140 = 20140508,
38 };
39
40 While the meaning of this field appears to be obvious, in practice we have
41 never observed a value other than ``VC70``, even with modern versions of
42 the toolchain, and it is unclear why the other values exist. It is assumed
43 that certain aspects of the PDB stream's layout, and perhaps even that of
44 the other streams, will change if the value is something other than ``VC70``.
45
46 - **Signature** - A 32-bit time-stamp generated with a call to ``time()`` at
47 the time the PDB file is written. Note that due to the inherent uniqueness
48 problems of using a timestamp with 1-second granularity, this field does not
49 really serve its intended purpose, and as such is typically ignored in favor
50 of the ``Guid`` field, described below.
51
52 - **Age** - The number of times the PDB file has been written. This can be used
53 along with ``Guid`` to match the PDB to its corresponding executable.
54
55 - **Guid** - A 128-bit identifier guaranteed to be unique across space and time.
56 In general, this can be thought of as the result of calling the Win32 API
57 `UuidCreate `__,
58 although LLVM cannot rely on that, as it must work on non-Windows platforms.
59
60 Matching a PDB to its executable
61 ================================
62 The linker is responsible for writing both the PDB and the final executable, and
63 as a result is the only entity capable of writing the information necessary to
64 match the PDB to the executable.
65
66 In order to accomplish this, the linker generates a guid for the PDB (or
67 re-uses the existing guid if it is linking incrementally) and increments the Age
68 field.
69
70 The executable is a PE/COFF file, and part of a PE/COFF file is the presence of
71 number of "directories". For our purposes here, we are interested in the "debug
72 directory". The exact format of a debug directory is described by the
73 `IMAGE_DEBUG_DIRECTORY structure `__.
74 For this particular case, the linker emits a debug directory of type
75 ``IMAGE_DEBUG_TYPE_CODEVIEW``. The format of this record is defined in
76 ``llvm/DebugInfo/CodeView/CVDebugRecord.h``, but it suffices to say here only
77 that it includes the same ``Guid`` and ``Age`` fields. At runtime, a
78 debugger or tool can scan the COFF executable image for the presence of
79 a debug directory of the correct type and verify that the Guid and Age match.