xenia-rs/crates/xenia-analysis/SCHEMA.md

xenia-analysis schema reference

Authoritative documentation for the DuckDB tables and SQL views produced by xenia-rs dis --db sylpheed.db. Track schema changes here alongside any update to the db_schema_golden test fixture.

The base + disasm tables (metadata, sections, imports, functions, labels, instructions, xrefs, opt-in exec_trace / import_calls / branch_trace) are documented inline in src/db.rs doc comment. This file collects layered analysis additions and forward-work notes.

---

Layer M1 — .pdata boundary correction (landed)

Schema additions

• functions.pdata_validated BOOLEAN NOT NULL — true when the row's address matches a RUNTIME_FUNCTION.BeginAddress from .pdata. Linker ground truth.
• functions.pdata_length BIGINT NULL — function_length (bytes) from the matching pdata entry; NULL when the row is prologue-only.
• New table pdata_entries(begin_address BIGINT PRIMARY KEY, end_address BIGINT, function_length BIGINT, prolog_length BIGINT, flags BIGINT) — every parsed .pdata RUNTIME_FUNCTION entry (raw, before any merge with prologue analysis).
• Index idx_functions_pdata_validated on functions(pdata_validated).

What this layer does

• Parses .pdata 8-byte RUNTIME_FUNCTION entries (PowerPC PE32 layout): word 0 BeginAddress (absolute VA), word 1 packed {prolog_length:8, function_length:22, flags:2}, both big-endian.
• Unions pdata BeginAddress values into the function-candidate set fed to the prologue walker, so functions our prologue heuristic missed still get rows.
• When pdata supplies a longer function_length than the prologue walk found, extends end_address to the pdata-implied end (catches mis-split where the walker stopped at an early blr).
• After the walker, performs a forward pass that trims function.end to the next start when they overlap (catches mis-merge where one row spanned two prologues — the audit-031 sub_824D23B0 / sub_824D29F0 case).

What this layer does NOT do

• Does not adjust prolog-derived frame_size / saved_gprs from .pdata's prolog_length field — those remain prologue-only inferences.
• Does not classify functions further than the existing is_leaf / is_saverestore columns. Class membership is M3.
• Does not detect functions whose entries are missing from BOTH .pdata and the bl-target scan (extremely rare; would require executable-byte linear sweep).

Reference docs

• Microsoft PE32+ exception data spec for PowerPC RUNTIME_FUNCTION.
• xenia-canary src/xenia/cpu/xex_module.cc:1570-1587 — canary's reference parser (extracts BeginAddress only; we additionally decode word 1).

Validation queries

-- All pdata entries found
SELECT COUNT(*) FROM pdata_entries;            -- ~23073 for Sylpheed
-- Functions cross-validated against pdata
SELECT COUNT(*) FROM functions WHERE pdata_validated;
-- Functions detected ONLY by prologue (orphans of pdata)
SELECT COUNT(*) FROM functions WHERE NOT pdata_validated;
-- Pdata orphans NOT yet in functions (should be 0 after this layer)
SELECT COUNT(*) FROM pdata_entries p
LEFT JOIN functions f ON f.address = p.begin_address
WHERE f.address IS NULL;
-- Audit-031 mis-merge resolved: 0x824D29F0 should have its own row
SELECT name FROM functions WHERE address = 2186674160;  -- 0x824D29F0

---

Layer M2 — MSVC C++ name demangler (landed)

Schema additions

• New table demangled_names(address BIGINT NULL, mangled VARCHAR NOT NULL, raw_demangled VARCHAR NOT NULL, namespace_path VARCHAR NULL, class_name VARCHAR NULL, method_name VARCHAR NULL, params_signature VARCHAR NULL).
• Indices on address, class_name, method_name.

What this layer does

• Wraps msvc_demangler::demangle (a Rust port of LLVM's MicrosoftDemangle.cpp) and splits the formatted output into structured fields via a heuristic top-level parser (handles templates and nested parens correctly).
• Populates demangled_names from any label whose name starts with ? plus any import name that happens to be mangled (defensive — typical kernel imports use C names).

What this layer does NOT do

• Does not parse the AST returned by msvc_demangler::parse — uses the formatted string and a heuristic split. Adequate for typical class member functions and RTTI strings; exotic template / lambda forms still get raw_demangled populated but may have NULL structured fields.
• Does not yet ingest RTTI strings discovered in .rdata — that's M3's job; M3 will append rows to this table at the addresses where it finds RTTI TypeDescriptors.

Reference docs

• msvc-demangler crate (https://docs.rs/msvc-demangler/0.11).
• LLVM MicrosoftDemangle.cpp (the parser this crate ports).

Layer M3 — Vtable + RTTI detection (planned)

Adds vtables, methods, classes tables. Heuristic vtable scan over .rdata + .data, optional MSVC RTTI CompleteObjectLocator → TypeDescriptor walk, anonymous-class fallback when RTTI is stripped. See crates/xenia-analysis/src/vtables.rs (when landed).

Layer M4 — Class-aware probe targeting (planned)

CLI extension only — no schema changes. --pc-probe=Class::method and --pc-probe-class=ClassName resolve via M3's tables. See crates/xenia-analysis/src/lookup.rs (when landed).

---

Forward work (M5–M12, not yet landed)

• M5 — indirect-dispatch reachability via vtable+CTR dataflow.
• M6 — extended xrefs.kind='write' for indexed/byte-reverse/multiword/VMX/DCBZ/atomic stores with addr_mode column.
• M7 — .rdata ASCII / UTF-16 string pool detection cross-referenced with PCs.
• M8 — dispatch-table heuristics beyond vtables (e.g. function-pointer arrays in .data).
• M9 — __CxxFrameHandler exception scope-table parsing.
• M10 — .tls section / TLS slot tracking.
• M11 — __xc_a / __xc_z static-initializer driver detection.
• M12 — comparative-PC-trace mode for canary diff (runtime side, not analyzer).