From 124b9a1561dc238082756992ce6bdb66738c176d Mon Sep 17 00:00:00 2001 From: sim Date: Wed, 16 Sep 2026 20:37:08 +0200 Subject: [PATCH] docs: stop telling people to use the retired xenia-rs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- crates/sylpheed-formats/src/hash.rs | 2 +- crates/sylpheed-xex/src/vfs/disc_image.rs | 2 +- crates/sylpheed-xexdb/SCHEMA.md | 6 +++--- crates/sylpheed-xexdb/src/bin/sylph-xexdb.rs | 4 ++-- crates/sylpheed-xexdb/src/db.rs | 2 +- crates/sylpheed-xexdb/src/formatter.rs | 2 +- docs/re/README.md | 19 +++++++++++-------- docs/re/challenge-mission-gate.md | 6 +++--- docs/re/structures/achievements.md | 4 ++-- 9 files changed, 25 insertions(+), 22 deletions(-) diff --git a/crates/sylpheed-formats/src/hash.rs b/crates/sylpheed-formats/src/hash.rs index 82ac0843..b216eb80 100644 --- a/crates/sylpheed-formats/src/hash.rs +++ b/crates/sylpheed-formats/src/hash.rs @@ -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("")` -/// (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`). diff --git a/crates/sylpheed-xex/src/vfs/disc_image.rs b/crates/sylpheed-xex/src/vfs/disc_image.rs index 90142aa4..47981766 100644 --- a/crates/sylpheed-xex/src/vfs/disc_image.rs +++ b/crates/sylpheed-xex/src/vfs/disc_image.rs @@ -182,7 +182,7 @@ impl VfsDevice for DiscImageDevice { fn list_root(&self) -> Result, 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()) } diff --git a/crates/sylpheed-xexdb/SCHEMA.md b/crates/sylpheed-xexdb/SCHEMA.md index 5fc52f46..a9179e07 100644 --- a/crates/sylpheed-xexdb/SCHEMA.md +++ b/crates/sylpheed-xexdb/SCHEMA.md @@ -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 --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`. --- diff --git a/crates/sylpheed-xexdb/src/bin/sylph-xexdb.rs b/crates/sylpheed-xexdb/src/bin/sylph-xexdb.rs index 48fda0de..6840b5bc 100644 --- a/crates/sylpheed-xexdb/src/bin/sylph-xexdb.rs +++ b/crates/sylpheed-xexdb/src/bin/sylph-xexdb.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))?; diff --git a/crates/sylpheed-xexdb/src/db.rs b/crates/sylpheed-xexdb/src/db.rs index 6f3ba5f7..6264b6ce 100644 --- a/crates/sylpheed-xexdb/src/db.rs +++ b/crates/sylpheed-xexdb/src/db.rs @@ -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: diff --git a/crates/sylpheed-xexdb/src/formatter.rs b/crates/sylpheed-xexdb/src/formatter.rs index fe6f3dcc..09ee871d 100644 --- a/crates/sylpheed-xexdb/src/formatter.rs +++ b/crates/sylpheed-xexdb/src/formatter.rs @@ -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}")?; } diff --git a/docs/re/README.md b/docs/re/README.md index 26a6efca..de4513da 100644 --- a/docs/re/README.md +++ b/docs/re/README.md @@ -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 `, +- **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 --db sylpheed.db --analyze sql --quiet`, then re-stamp names with + `tools/apply_re_symbols.sql`). Query with `tools/zq.py` — `zq.py grep `, `zq.py xref `, `zq.py dis `, `zq.py fn `. 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). diff --git a/docs/re/challenge-mission-gate.md b/docs/re/challenge-mission-gate.md index 4d154ab7..32ab2e77 100644 --- a/docs/re/challenge-mission-gate.md +++ b/docs/re/challenge-mission-gate.md @@ -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 -- cargo run --release -q -p sylpheed-formats --example challenge_screen -- -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 diff --git a/docs/re/structures/achievements.md b/docs/re/structures/achievements.md index b3a25a00..8834526e 100644 --- a/docs/re/structures/achievements.md +++ b/docs/re/structures/achievements.md @@ -177,6 +177,6 @@ made rather than after. ```bash python3 tools/xach_dump.py "/…/Project Sylpheed ….pe" cargo run --release -q -p sylpheed-formats --example achievements_map -- -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 ```