Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ activate it first and drop the override):
| corpus audit | `.venv/bin/python dev/audit_corpus.py <dir>` (every listing over every file, escapes and undecoded kinds tallied) |
| OMAP vs Windows | `.venv/bin/python dev/validate_omap_against_windows.py <dll-dir> --fetch` (needs Windows DLLs and network; nothing is redistributed) |

Expected state on a clean tree: **632 tests pass**, `ruff check` and `ty check`
Expected state on a clean tree: **636 tests pass**, `ruff check` and `ty check`
both clean, and the fuzzer reports no escaped exception. Run tests, lint *and*
a quick fuzz pass before considering work complete.

Expand Down
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,14 @@ resolve *differently* would be breaking, and would say so here.
size cannot be less than what was just read out of the block, so the bytes
consumed are now the floor; a damaged size landing inside the entries used
to report lines made of line-record bytes.
- A module stream signed C7 (`0`) or C11 (`1`) has its signature stripped like
a C13 one. Only C13 was recognised, so the other two left the signature word
on the front of the records, where it was read as a record header and every
record after it was walked at the wrong alignment -- silently, with no error
and no warning. A first word that is none of the three is no longer parsed
as records at all: the module contributes no symbols, and
`Diagnostics.unrecognised_signatures` counts it by the value found, which
the new `diagnose()` warning names.

## [0.5.0] - 2026-08-28

Expand Down
42 changes: 36 additions & 6 deletions purepdb/pdb.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,10 @@
STREAM_IPI = 4

# CodeView signature that prefixes each module symbol substream, and its size.
CV_SIGNATURE_C7 = 0
CV_SIGNATURE_C11 = 1
CV_SIGNATURE_C13 = 4
CV_SIGNATURES = frozenset({CV_SIGNATURE_C7, CV_SIGNATURE_C11, CV_SIGNATURE_C13})
CV_SIGNATURE_SIZE = 4

# The fixed header of the PDB Info stream: version, signature, age, GUID. It
Expand Down Expand Up @@ -337,6 +340,11 @@ class Diagnostics:
files teaches a reader to skip the list, which costs the entries that do
matter. The count and the note beside it in `purepdb diagnose` are the
explanation, in the report rather than in the alarm channel."""
unrecognised_signatures: dict[int, int] = field(default_factory=dict)
"""Module streams whose first word is not a CodeView signature (C7, C11 or
C13), counted by that word. Their records are not read: the layout after
an unknown signature is not known, and parsing the word as a record header
would misalign every record after it."""

@property
def truncated_streams(self) -> int:
Expand Down Expand Up @@ -450,6 +458,14 @@ def warnings(self) -> list[str]:
f"records. This is what /DEBUG:FASTLINK and some pre-2010 "
f"toolchains produce"
)
if self.unrecognised_signatures:
found = ", ".join(f"{sig:#x}x{n}" for sig, n in
sorted(self.unrecognised_signatures.items()))
out.append(
f"{sum(self.unrecognised_signatures.values())} module "
f"stream(s) begin with a word that is not a CodeView signature "
f"(found: {found}); their symbols were not read"
)
if self.public_records == 0:
out.append(
"no public records in the symbol-record stream; thunks and "
Expand Down Expand Up @@ -829,15 +845,25 @@ def module_symbol_bytes(self, mod) -> bytes:
info`, and only the first region holds symbol records. `sym_byte_size`
bounds it *including* the 4-byte signature, so parsing past it walks
line-info bytes as if they were records. Returns b"" when the module
has no symbols.
has no symbols, or when its first word is not a signature purepdb
recognises -- `Diagnostics.unrecognised_signatures` counts those.
"""
return self._module_symbols(mod)[1]

def _module_symbols(self, mod) -> tuple[int | None, bytes]:
"""`module_symbol_bytes` and the unrecognised signature, if any."""
if not mod.has_symbols or not self.msf.is_valid_stream(mod.sym_stream):
return b""
return None, b""
raw = self.msf.read_stream(mod.sym_stream)
end = min(mod.sym_byte_size, len(raw))
if len(raw) >= 4 and struct.unpack_from("<I", raw, 0)[0] == CV_SIGNATURE_C13:
return raw[4:end]
return raw[:end]
# Too short to hold a signature: left for the record walk to report
# as a truncation.
if len(raw) < 4:
return None, raw[:end]
signature = struct.unpack_from("<I", raw, 0)[0]
if signature not in CV_SIGNATURES:
return signature, b""
return None, raw[4:end]

def module_c13_bytes(self, mod) -> bytes:
"""The C13 line-info region of one module's stream.
Expand Down Expand Up @@ -1374,6 +1400,7 @@ def diagnose(self) -> Diagnostics:
malformed = 0
malformed_inline = 0
line_bytes = 0
signatures: dict[int, int] = {}
proc_records = 0
placed_sites = 0
unnamed_sites = 0
Expand All @@ -1388,7 +1415,9 @@ def diagnose(self) -> Diagnostics:
# only the records `parse_proc` raises on.
for mod in self.dbi.modules:
line_bytes += len(self.module_c13_bytes(mod))
body = self.module_symbol_bytes(mod)
signature, body = self._module_symbols(mod)
if signature is not None:
signatures[signature] = signatures.get(signature, 0) + 1
if not body:
continue
with_symbols += 1
Expand Down Expand Up @@ -1501,6 +1530,7 @@ def diagnose(self) -> Diagnostics:
private_symbols_stripped=self.dbi.is_stripped,
linker_version=self.dbi.toolchain_version,
thread_local_records=thread_locals,
unrecognised_signatures=signatures,
)

def _is_code(self, segment: int) -> bool:
Expand Down
4 changes: 2 additions & 2 deletions tests/_synth.py
Original file line number Diff line number Diff line change
Expand Up @@ -343,9 +343,9 @@ def section_header(name: str, vaddr: int, vsize: int = 0x1000,
)


def module_sym_stream(records: bytes) -> bytes:
def module_sym_stream(records: bytes, signature: int = 4) -> bytes:
"""A module symbol substream: 4-byte CV signature + records."""
return struct.pack("<I", 4) + records
return struct.pack("<I", signature) + records


def publics_hash_stream(record_offsets: list[int]) -> bytes:
Expand Down
32 changes: 30 additions & 2 deletions tests/test_diagnose.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

import struct

import pytest

from purepdb import PDB
from tests._synth import (
build_msf,
Expand All @@ -24,9 +26,10 @@
UNKNOWN_KIND = 0x1FFF


def _pdb(*, module_records=b"", pub_records=(), section_stream=6, flags=0):
def _pdb(*, module_records=b"", pub_records=(), section_stream=6, flags=0,
signature=4):
symrecords = b"".join(pub_records)
module_syms = module_sym_stream(module_records)
module_syms = module_sym_stream(module_records, signature)
mods = module_info("main.obj", "main.obj", sym_stream=5,
sym_byte_size=len(module_syms))
streams = [
Expand Down Expand Up @@ -120,6 +123,31 @@ def test_line_info_after_the_symbols_is_not_parsed_as_records():
assert names == ["real"], "must stop at sym_byte_size"


@pytest.mark.parametrize("signature", [0, 1, 4], ids=["C7", "C11", "C13"])
def test_every_codeview_signature_is_stripped(signature):
pdb = _pdb(module_records=gproc32("main", 1, 0x10),
pub_records=[pub32("main", 1, 0x10)], signature=signature)
assert [p.name for p in pdb.module_procs()] == ["main"]
d = pdb.diagnose()
assert d.unrecognised_signatures == {}
assert d.warnings == []


def test_an_unrecognised_signature_is_not_parsed_as_a_record():
# 0x1110_0010 read as a header is a 16-byte S_GPROC32, so a reader that
# walked past the unknown word would find a record in it.
pdb = _pdb(module_records=gproc32("main", 1, 0x10),
pub_records=[pub32("main", 1, 0x10)], signature=0x1110_0010)
assert pdb.module_procs() == []
d = pdb.diagnose()
assert d.modules_with_symbols == 0
assert d.malformed_records == 0
assert d.unrecognised_signatures == {0x1110_0010: 1}
warning = "\n".join(d.warnings)
assert "0x11100010" in warning, "the value found must be named"
assert "not a CodeView signature" in warning


def _publics_only(*, flags=0, build_number=0, modules=1):
"""The stripped shape: publics, section headers, and modules with no
symbol stream -- or no modules at all."""
Expand Down