xenia-rs/docs/functions

Function dossiers — persistent RE notes for Project Sylpheed (Sylpheed.xex)

What this is

One markdown file per guest function we've investigated during a kernel-bug audit. The dossier is a living, append-only record of what we know (and what we got wrong) about each function. The goal is two-fold:

1. Don't re-derive understanding. When an audit touches sub_821C4EB0, the next agent shouldn't have to re-walk the disasm — read sub_821C4EB0.md first.
2. Don't repeat misinterpretations. AUDIT-060 falsified two audits of work because we'd read MSVC EH FuncInfo metadata as if it were static call edges. The dossier captures both the corrected reading AND the falsified one — so future agents see the trap was already sprung once.

This system is agent-writable. Audit agents are expected to consult dossiers before probing, and to append (not rewrite) when a new audit produces evidence about a known function. Agents should create new dossiers for any function they perform non-trivial work on.

Layout

docs/functions/
  README.md           — this file
  INDEX.md            — one-line lookup table, sorted by address
  sub_XXXXXXXX.md     — per-function dossier (one per function, address in UPPERCASE hex)

Filename convention: sub_ + 8-hex-uppercase + .md. Match the name used in sylpheed.db.functions.name. If the function has a symbol (e.g. GamePart_Title::UImpl::ctor), still use the address-based filename; record the symbol inside.

Schema

Each dossier follows this shape:

---
address: 0xXXXXXXXX
classification: <one-word category — see below>
confidence: <high | medium | low | refuted>
last_audit: NNN
aliases:
  - "human-readable name or prior misnomer (status)"
---

# sub_XXXXXXXX

## Synopsis

One short paragraph: the current best understanding. ONLY the latest consensus —
old interpretations live in the audit log.

## Evidence

Hard facts only. Disasm patterns, .rdata/.pdata references, runtime fires from
instrumentation, byte-level dumps. No inference here; that goes in Activation
or Notes.

## Activation

When/how this function runs:
- direct bl from caller X at PC Y
- indirect via fnptr-array slot N at 0x...
- vtable dispatch from class C, slot K (vtable at 0x...)
- C++ EH catch-handler dispatch (FuncInfo @ 0x...)
- thread_proc entry point (registered via ExCreateThread call site PC Z)

## Static graph

- Callers (from sylpheed.db `xrefs` table, source_func column — never source per AUDIT-045):
  - PC `0xCCCCCCCC` inside `sub_DDDDDDDD`
- Callees:
  - bl `sub_EEEEEEEE` at PC `0x...`
  - bctrl (computed) at PC `0x...` — candidates: ...

## Audit log

Append-only. Most recent FIRST. Each entry pairs (audit-NNN, date, observation,
status). Status options: confirmed | falsified | superseded-by-NNN.

- **AUDIT-NNN (YYYY-MM-DD)** — observation + relevant data point [STATUS]
- **AUDIT-MMM (YYYY-MM-DD)** — earlier observation [STATUS: falsified by NNN — reason]

## Open questions

Future-work bullets:
- Specific PC to probe
- Hypothesis to test
- Cross-reference to verify

## Cross-references

- Related dossiers: [sub_XXXXX](sub_XXXXX.md) (relationship)
- Audit memory entries: `project_xenia_rs_audit_NNN_*.md`
- Trace artifacts: `audit-runs/audit-NNN-*/...`

Classification vocabulary

Pick the most specific that fits. Add new ones if needed but don't bloat the list.

Class	Meaning
normal_callee	Plain function reached by direct bl. The default.
vtable_method	Virtual method dispatched via bctrl from a class vtable.
thread_proc	Entry point registered via ExCreateThread / KeInitializeThread. 0 static callers is correct; check for lr=0xbcbcbcbc thread-entry sentinel at first fire.
msvc_eh_catch_handler	MSVC C++ catch handler. Prolog subi r31, r12, N; mflr r12; .... Referenced from .rdata FuncInfo (magic 0x19930520..22). 0 static callers; dispatched by EH runtime only. Do not treat its .rdata references as call edges.
msvc_eh_state_handler	MSVC EH state/unwind handler. Similar to above but no subi r31, r12 prolog.
import_thunk	Wraps an xboxkrnl import (e.g. NtCreateEvent at thunk 0x8284DF1C). Behavior is host-side.
wrapper	Thin wrapper around a kernel import or library call.
crt_init_driver	CRT-style iterator that walks an array of fn pointers / vtables (e.g. sub_824ACB38).
fnptr_array_entry	Function reached only via enumeration by a crt_init_driver.
dispatch_table_method	Function installed into a runtime dispatch table by a ctor; reached via indirect call only.
synchronization_primitive	Function that wraps Nt/Ke wait/set/release calls.
unknown	Not yet investigated. Synopsis describes what little we know.

Confidence levels

Confidence	Meaning
high	Multiple converging evidence sources (disasm + runtime instrumentation + cross-engine probe).
medium	One strong source (e.g. disasm alone or one canary trace). Plausible but not cross-checked.
low	Inference from static call graph or one observation; should be probed if it becomes load-bearing.
refuted	An earlier claim was falsified. Keep the dossier; document what the function actually is in synopsis + put the refuted claim in audit log with status falsified.

Golden rules — for agents and humans

1. Append, don't overwrite. New audits add entries to "Audit log". Old entries stay with their original wording so future readers can see the evolution.
2. Falsify, don't delete. If a later audit disproves an earlier claim, mark the old audit-log entry [STATUS: falsified by AUDIT-NNN — reason]. The earlier interpretation taught us something (often that a class of disasm pattern is ambiguous) — preserve it.
3. Cite the source. Every claim ties to either (a) an audit number + trace artifact path, or (b) a static-DB query you can reproduce. "X is a thread_proc" without a basis is unacceptable.
4. Distinguish fact from inference. "Fires 5× at -n 500M with lr=0x8246020C all five times" is a fact. "Therefore it's a vptr installer for slot 1 of dispatch_table 0x820B5830" is an inference. Put facts in Evidence; inferences in Synopsis/Activation/Notes — and label inferences as such.
5. Update INDEX.md. When you create a new dossier or change a classification, add/update the corresponding row in INDEX.md.
6. Update the last_audit frontmatter. Reflects the most recent audit that touched the dossier.
7. One function per file. If you find a fn is structurally a wrapper for another, write two dossiers and link them.

Anti-patterns to avoid

• Reading EH metadata as call edges. .rdata references to a fn inside an MSVC FuncInfo struct (magic 0x19930520..22 nearby) are unwind-handler bindings, NOT bl call sites. Pattern: catch-handler prolog subi r31, r12, N; mflr r12; stwu r1, .... See sub_821B6DF4.md for the canonical falsified example.
• "0 static callers" = "dead in ours". Three legitimate reasons a fn has 0 static callers and still runs: thread_proc (ExCreateThread), fnptr_array_entry (enumerated by crt_init_driver), msvc_eh_*_handler (dispatched by EH runtime). Always check.
• Comparing fire counts at fixed instruction horizons across engines. Canary @ 60s wallclock and ours @ -n 500M are different time bases. State (i) and state (ii) data points must be normalized — either both at the same wallclock or both at the same boot milestone.
• Trusting handle IDs across runs. KernelState::alloc_handle is monotonic; handles drift run-to-run. Function-context names (e.g. "sub_821CB030+0x128 creator") are stable; handle IDs are not.
• Quoting xrefs.source instead of xrefs.source_func. See AUDIT-045 reading-error #12. Use source_func for caller-set queries.

Backfill status

Initial set (created in AUDIT-060 retrospective backfill, 2026-05-12):

• The 10 most-cited fns from AUDIT-049–060.

Future audits should extend coverage as they touch new fns. Backfilling earlier audit fns (AUDIT-030–048) is a nice-to-have but not blocking.