81 lines
3.1 KiB
ReStructuredText
81 lines
3.1 KiB
ReStructuredText
========================================
|
|
The PDB Info Stream (aka the PDB Stream)
|
|
========================================
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. _pdb_stream_header:
|
|
|
|
Stream Header
|
|
=============
|
|
At offset 0 of the PDB Stream is a header with the following layout:
|
|
|
|
|
|
.. code-block:: c++
|
|
|
|
struct PdbStreamHeader {
|
|
ulittle32_t Version;
|
|
ulittle32_t Signature;
|
|
ulittle32_t Age;
|
|
Guid UniqueId;
|
|
};
|
|
|
|
- **Version** - A Value from the following enum:
|
|
|
|
.. code-block:: c++
|
|
|
|
enum class PdbStreamVersion : uint32_t {
|
|
VC2 = 19941610,
|
|
VC4 = 19950623,
|
|
VC41 = 19950814,
|
|
VC50 = 19960307,
|
|
VC98 = 19970604,
|
|
VC70Dep = 19990604,
|
|
VC70 = 20000404,
|
|
VC80 = 20030901,
|
|
VC110 = 20091201,
|
|
VC140 = 20140508,
|
|
};
|
|
|
|
While the meaning of this field appears to be obvious, in practice we have
|
|
never observed a value other than ``VC70``, even with modern versions of
|
|
the toolchain, and it is unclear why the other values exist. It is assumed
|
|
that certain aspects of the PDB stream's layout, and perhaps even that of
|
|
the other streams, will change if the value is something other than ``VC70``.
|
|
|
|
- **Signature** - A 32-bit time-stamp generated with a call to ``time()`` at
|
|
the time the PDB file is written. Note that due to the inherent uniqueness
|
|
problems of using a timestamp with 1-second granularity, this field does not
|
|
really serve its intended purpose, and as such is typically ignored in favor
|
|
of the ``Guid`` field, described below.
|
|
|
|
- **Age** - The number of times the PDB file has been written. This can be used
|
|
along with ``Guid`` to match the PDB to its corresponding executable.
|
|
|
|
- **Guid** - A 128-bit identifier guaranteed to be unique across space and time.
|
|
In general, this can be thought of as the result of calling the Win32 API
|
|
`UuidCreate <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205(v=vs.85).aspx>`__,
|
|
although LLVM cannot rely on that, as it must work on non-Windows platforms.
|
|
|
|
Matching a PDB to its executable
|
|
================================
|
|
The linker is responsible for writing both the PDB and the final executable, and
|
|
as a result is the only entity capable of writing the information necessary to
|
|
match the PDB to the executable.
|
|
|
|
In order to accomplish this, the linker generates a guid for the PDB (or
|
|
re-uses the existing guid if it is linking incrementally) and increments the Age
|
|
field.
|
|
|
|
The executable is a PE/COFF file, and part of a PE/COFF file is the presence of
|
|
number of "directories". For our purposes here, we are interested in the "debug
|
|
directory". The exact format of a debug directory is described by the
|
|
`IMAGE_DEBUG_DIRECTORY structure <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680307(v=vs.85).aspx>`__.
|
|
For this particular case, the linker emits a debug directory of type
|
|
``IMAGE_DEBUG_TYPE_CODEVIEW``. The format of this record is defined in
|
|
``llvm/DebugInfo/CodeView/CVDebugRecord.h``, but it suffices to say here only
|
|
that it includes the same ``Guid`` and ``Age`` fields. At runtime, a
|
|
debugger or tool can scan the COFF executable image for the presence of
|
|
a debug directory of the correct type and verify that the Guid and Age match.
|