docs: stop telling people to use the retired xenia-rs
Instructions and generated text that still sent readers to `xenia-rs`, which is
archived and deleted locally. Provenance and dated research records are left as
they are — "lifted from xenia-rs", or a finding stating what database it was
measured against, is still true, and rewriting it would falsify the record.
Changed, because each one tells someone what to do today or writes stale text:
docs/re/README.md the RE toolchain guide queried `xenia-rs/sylpheed.db`
with `xenia-rs/zq.py`, and its "Dynamic" bullet said
to prefer xenia-rs's probe suite OVER Canary. Now:
`sylpheed.db` at the repo root (how to build it and
re-stamp names), `tools/zq.py`, dynamic = Canary, and
`.rdata` reads from the `.pe` (offset = VA - 0x82000000)
in place of `--dump-addr`.
challenge-mission-gate.md, structures/achievements.md
reproduction commands `python3 xenia-rs/zq.py dis …`
crates/sylpheed-xexdb/SCHEMA.md
titled after the retired `xenia-analysis` crate,
citing `xenia-rs dis`, pointing at a `xenia-analysis`
source path
sylpheed-xexdb/src/formatter.rs
WROTE "generated by xenia-rs" into every disassembly
it produced (no test pins the banner)
sylph-xexdb.rs, db.rs "SQLite" / "DuckDB writer for xenia-rs"
sylpheed-formats/src/hash.rs
pointed at `xenia-rs/RE_SYMBOLS.md`, now at
`docs/re/RE_SYMBOLS.md`
Verified: every rewritten reproduction command was extracted from the doc and
run as written against the regenerated database — all 5 exit 0 and return the
disassembly they describe. The README's function count (25 676) is the database's
own. `cargo fmt --all -- --check` clean.
Not changed, deliberately: the README's Oracle bullet says Canary's native Linux
ELF "crashes / does not run". That is about Canary, not xenia-rs, and it conflicts
with a July note that the native build works — unverified either way here.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
sim
@@ -80,7 +80,7 @@ pub fn name_hash(name: &str) -> u32 {
|
||||
|
||||
/// Confirmed TOC key path schemes, as `(prefix, suffix)` around an entry's
|
||||
/// internal identity string. The key is `name_hash("<prefix><id><suffix>")`
|
||||
/// (backslash separators). Recovered by RE — see `xenia-rs/RE_SYMBOLS.md`.
|
||||
/// (backslash separators). Recovered by RE — see `docs/re/RE_SYMBOLS.md`.
|
||||
///
|
||||
/// - `("", ".tbl")` — root manifests / DefTables resource entries (`files.tbl`).
|
||||
/// - `("unit\\", ".tbl")` — craft/ship definitions (`unit\UN_f001_…_EX5.tbl`).
|
||||
|
||||
@@ -182,7 +182,7 @@ impl VfsDevice for DiscImageDevice {
|
||||
|
||||
fn list_root(&self) -> Result<Vec<VfsEntry>, VfsError> {
|
||||
// Return the full flattened tree. Callers of this method are
|
||||
// dump/debug paths (see `xenia-rs dumpxiso`), which want to see
|
||||
// dump/debug paths (the retired `xenia-rs dumpxiso` was one), which want to see
|
||||
// every file — root-only was the old flat-enumeration bug.
|
||||
Ok(self.entries.clone())
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# `xenia-analysis` schema reference
|
||||
# `sylph-xexdb` 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
|
||||
`sylph-xexdb dis <xex|iso> --db sylpheed.db --analyze sql`. Track schema changes here alongside any
|
||||
update to the `db_schema_golden` test fixture.
|
||||
|
||||
The base + disasm tables (`metadata`, `sections`, `imports`, `functions`,
|
||||
@@ -162,7 +162,7 @@ or `XENIA_PROBE_DB`; default is `sylpheed.db` next to the .iso when present.
|
||||
Resolution happens BEFORE guest exec begins, so it cannot affect the
|
||||
lockstep digest.
|
||||
|
||||
See `crates/xenia-analysis/src/lookup.rs`.
|
||||
See `crates/sylpheed-xexdb/src/lookup.rs`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -496,7 +496,7 @@ fn cmd_extract(path: &str, output_dir: Option<&str>, db_path: Option<&str>) -> R
|
||||
);
|
||||
}
|
||||
|
||||
// Write base tables to SQLite if requested
|
||||
// Write base tables to DuckDB if requested
|
||||
if let Some(db) = db_path {
|
||||
let disasm_info = sylpheed_xexdb::formatter::DisasmInfo {
|
||||
image_base: base,
|
||||
@@ -871,7 +871,7 @@ fn cmd_dis(
|
||||
xex_header: Some(&header),
|
||||
};
|
||||
|
||||
// SQLite database output (base + ingest + analyze layers)
|
||||
// DuckDB database output (base + ingest + analyze layers)
|
||||
if let Some(db) = db_path {
|
||||
info!(db = %db, analyze = ?analyze, "writing database");
|
||||
let mut w = sylpheed_xexdb::DbWriter::open_fresh(std::path::Path::new(db))?;
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
//! DuckDB writer for xenia-rs.
|
||||
//! DuckDB writer for `sylph-xexdb`.
|
||||
//!
|
||||
//! Layered, streaming writes shared by `extract`, `dis`, and `exec`.
|
||||
//! Each command's output is a superset of the previous:
|
||||
|
||||
@@ -46,7 +46,7 @@ pub fn write_asm(
|
||||
out,
|
||||
"; ============================================================================"
|
||||
)?;
|
||||
writeln!(out, "; Xbox 360 Disassembly — generated by xenia-rs")?;
|
||||
writeln!(out, "; Xbox 360 Disassembly — generated by sylph-xexdb")?;
|
||||
if let Some(name) = info.original_pe_name {
|
||||
writeln!(out, "; Original PE: {name}")?;
|
||||
}
|
||||
|
||||
@@ -22,7 +22,7 @@ This mirrors the project method — *measure the oracle, never infer; refute bef
|
||||
|
||||
- ✅ Allowed: behaviour descriptions, field offsets/types, formulas, state machines,
|
||||
observed input→output pairs, and **references** to the original by address
|
||||
(`sub_821B68C0`) or to `xenia-rs/sylpheed.db`.
|
||||
(`sub_821B68C0`) or to `sylpheed.db`.
|
||||
- ❌ Forbidden here and in `crates/`: pasted decompiled C/C++ or verbatim disassembled
|
||||
function bodies presented as the thing to reimplement. Cite the address; describe the
|
||||
behaviour in your own words. Disassembly is a tool for *understanding*, not a source to copy.
|
||||
@@ -90,18 +90,21 @@ Use the templates: [`_TEMPLATE.function.md`](_TEMPLATE.function.md),
|
||||
Everything joins on the **guest virtual address (PC)** — code addresses are fixed by the
|
||||
XEX load, identical across our emulator and canary.
|
||||
|
||||
- **Static (cheap, try first):** `xenia-rs/sylpheed.db` (DuckDB: 25 481 functions, xrefs,
|
||||
strings, vtables, imports). Query with `xenia-rs/zq.py` — `zq.py grep <str>`,
|
||||
- **Static (cheap, try first):** `sylpheed.db` at the repository root (DuckDB: 25 676
|
||||
functions, xrefs, strings, vtables, imports; git-ignored — build it with
|
||||
`sylph-xexdb dis <ISO> --db sylpheed.db --analyze sql --quiet`, then re-stamp names with
|
||||
`tools/apply_re_symbols.sql`). Query with `tools/zq.py` — `zq.py grep <str>`,
|
||||
`zq.py xref <addr>`, `zq.py dis <lo> <hi>`, `zq.py fn <pc>`. Entry points are usually a
|
||||
**string** (`zq.py grep MSG_DEMO`) or an **import** (movie/XMA API) xref'd back to the loader.
|
||||
- **Dynamic (when static is ambiguous):** run `xenia-rs` with its probe suite —
|
||||
`--pc-probe` / `--audit-pc-probe-hex` (fires at block entry), `--mem-watch` (mid-block
|
||||
reads/writes of a VA), `--lr-trace` (call/return chains), `--trace-instructions`,
|
||||
`--dump-addr` (read guest memory). These already exist; prefer them over hacking canary.
|
||||
- **Dynamic (when static is ambiguous):** Xenia Canary, below. The `xenia-rs` probe suite
|
||||
this bullet used to recommend (`--pc-probe`, `--mem-watch`, `--lr-trace`,
|
||||
`--dump-addr`) went with that emulator when it was retired on 2026-09-16. For static
|
||||
`.rdata` reads that `--dump-addr` served, read the `.pe` directly: it is a flat VA dump,
|
||||
file offset = `VA − 0x82000000`.
|
||||
- **Oracle (correctness ground truth):** canary — the **Wine cross-build**
|
||||
`xenia-canary/build-cross/bin/Windows/Debug/xenia_canary.exe` (the native Linux ELF
|
||||
**crashes / does not run** — do not use it). This is the only emulator that reaches the
|
||||
in-game menu; our `xenia-rs` never got past the intro video. Use canary to *observe output*
|
||||
in-game menu; our retired `xenia-rs` never got past the intro video. Use canary to *observe output*
|
||||
(capture its framebuffer for texture colours), not usually to instrument code — though its
|
||||
`build-cross` toolchain does compile, so small C++ probes + rebuild are possible when needed.
|
||||
Run **muted, one emulator process at a time**, point it at the real ISO (not the symlink).
|
||||
|
||||
@@ -453,9 +453,9 @@ rest are not in any stage roster table and need a different lever.
|
||||
```bash
|
||||
cargo run --release -q -p sylpheed-formats --example challenge_map -- <disc-root>
|
||||
cargo run --release -q -p sylpheed-formats --example challenge_screen -- <disc-root>
|
||||
python3 xenia-rs/zq.py dis 0x82184df0 0x82184e30 # the three-way section switch
|
||||
python3 xenia-rs/zq.py dis 0x82185ed0 0x82185f10 # the same switch, second site
|
||||
python3 xenia-rs/zq.py dis 0x82189860 0x821899f0 # the challenge availability gate
|
||||
python3 tools/zq.py dis 0x82184df0 0x82184e30 # the three-way section switch
|
||||
python3 tools/zq.py dis 0x82185ed0 0x82185f10 # the same switch, second site
|
||||
python3 tools/zq.py dis 0x82189860 0x821899f0 # the challenge availability gate
|
||||
```
|
||||
|
||||
### 5.4 ✅ CLOSED — the exact pairing, read from the record's own fields
|
||||
|
||||
@@ -177,6 +177,6 @@ made rather than after.
|
||||
```bash
|
||||
python3 tools/xach_dump.py "<disc>/…/Project Sylpheed ….pe"
|
||||
cargo run --release -q -p sylpheed-formats --example achievements_map -- <disc-root>
|
||||
python3 xenia-rs/zq.py dis 0x8218f9a8 0x8218fa60 # the requirement walk
|
||||
python3 xenia-rs/zq.py dis 0x8218f888 0x8218f990 # the XACHIEVEMENT_DETAILS scan
|
||||
python3 tools/zq.py dis 0x8218f9a8 0x8218fa60 # the requirement walk
|
||||
python3 tools/zq.py dis 0x8218f888 0x8218f990 # the XACHIEVEMENT_DETAILS scan
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user