fabi/xenia-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add migration/ bundle for cross-machine setup

Browse Source 
Bundles state that lives OUTSIDE the xenia-rs repo so a fresh clone on
another machine can be brought up to identical configuration via
migration/setup.sh:

  - claude-memory/             ~/.claude/projects/-home-fabi-RE-Project-Sylpheed/memory/
                               (103 files, 1.1 MB - MEMORY.md + every
                                project_xenia_rs_*.md from audits
                                addis_signext through audit-058)
  - project-root/dot-claude/   <project-root>/.claude/settings.json
                               (Stop hook + permissions)
  - project-root/ppc-manual/   <project-root>/ppc-manual/
                               (PowerPC reference docs, 397 files, 3.7 MB)
  - project-root/run-canary.sh <project-root>/run-canary.sh
  - README.md                  Human-readable setup checklist
  - setup.sh                   Idempotent installer (also reclones
                               xenia-canary at pinned HEAD 6de80dffe)
  - MANIFEST.md                Per-file mapping + per-file-not-bundled
                               restoration recipe

Excluded from bundle (not shippable via git):
  - Sylpheed ISO (7.8 GB; copyright; manual copy required)
  - sylpheed.db (395 MB; regenerable from XEX via analysis tooling)
  - target/ build artifacts (rebuild on target)
  - audit-runs probe firehoses (.log/.stdout/.stderr ~11 GB; rerun if needed)
  - audit-runs memory dumps (.bin ~4.5 GB; rerun audit-026/027/029 if needed)
  - xenia-canary checkout (setup.sh reclones from
    git.mc02.dev/fabi/Xenia-Canary.git at HEAD 6de80dffe)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-05-10 21:38:38 +02:00
parent 8e709b0a24
commit e6d43a23ac
505 changed files with 86028 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
migration/claude-memory/project_xenia_rs_cli.md Normal file
View File

@@ -0,0 +1,178 @@
---
name: xenia-rs CLI Reference
description: Complete CLI commands, arguments, and environment variables for the xenia-rs tool — update this when CLI changes
type: project
originSessionId: 08576735-74b4-4180-994a-2eb93dc60997
---
> **Update trigger**: Whenever the xenia-rs CLI changes (new commands, flags, env vars), update this file and the MEMORY.md index entry. Last documented: 2026-04-22 (added `exec --halt-on-deadlock` + `XENIA_HALT_ON_DEADLOCK` env var for deadlock investigation — bypasses the force-wake recovery path so the ctx snapshot survives).
## Binary
`xenia-rs` — Xbox 360 XEX/XISO reverse-engineering toolchain
**CLI framework**: Clap 4.x with derive macros
**Entry point**: `xenia-rs/crates/xenia-app/src/main.rs`
**Observability module**: `xenia-rs/crates/xenia-app/src/observability.rs`
---
## Global flags (apply to every subcommand)
| Flag | Type | Effect |
|------|------|--------|
| `--log-json` | bool | Force JSON on the console fmt layer (default is compact text, stderr) |
| `--log-file <PATH>` | path | Additionally write logs to file via non-blocking appender. `.json` extension → JSON formatter; else text |
| `--log-filter <DIRECTIVES>` | env-filter | Overrides `RUST_LOG`. Precedence: `--log-filter` > `RUST_LOG` > default (`warn` for `exec --quiet`, else `info`) |
| `--trace-chrome <PATH>` | path | Emit Chrome `about:tracing` JSON of all spans (uses `tracing-chrome`). Loadable in `chrome://tracing` / Perfetto |
| `--profile <PATH>` | path | Start pprof sampling profiler at 100 Hz. `.svg` → flamegraph; `.pb` → pprof protobuf. Requires `profiling` Cargo feature (on by default) |
**Cargo features** on `xenia-app`:
- `profiling` (default): pulls `pprof = { features = ["flamegraph", "protobuf-codec"] }`. Disable with `--no-default-features` for minimal release builds; `--profile` then fails at startup with a clear error.
---
## Commands
### `disasm` — Disassemble XEX from entry point
```
xenia-rs disasm <PATH> [-n <COUNT>]
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XEX file |
| `-n, --count` | usize | 64 | Number of instructions to disassemble |
---
### `exec` — Load and execute XEX with tracing
```
xenia-rs exec <PATH> [-n <MAX>] [--ips-limit <N>] [--db <DB>] [--trace-instructions] [--trace-imports] [--trace-branches] [--quiet] [--ui] [--halt-on-deadlock]
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XEX file |
| `-n, --max-instructions` | Option\<u64\> | none | Max instructions before stop (unlimited if omitted) |
| `--ips-limit` | Option\<u64\> | none | Throttle to N instructions per second (unlimited if omitted). Check runs once per scheduler round at `run_execution`'s outer loop — anchor is `Instant::now()` at function entry |
| `--db` | Option\<String\> | none | SQLite DB path; includes full static analysis + opt-in trace tables |
| `--trace-instructions` | bool flag | false | Log each instruction to `exec_trace` table |
| `--trace-imports` | bool flag | false | Log kernel/import calls to `import_calls` table |
| `--trace-branches` | bool flag | false | Log taken branches to `branch_trace` table |
| `--quiet` | bool flag | false | Suppress banners, kernel logs, register dump |
| `--ui` | bool flag | false | Open winit+wgpu window for dynamic analysis; backs XamInputGetState with gilrs; presents guest frontbuffer on VdSwap; CPU runs on worker thread. HUD shows swap count + last frontbuffer addr + pad state. Phase 1: no PM4/shader execution, so the frontbuffer is typically black for real games — HUD remains live. |
| `--halt-on-deadlock` | bool flag | false | At the hard-deadlock branch in `run_execution` (all live HW threads `Blocked` on handle waits, no pending timer), emit a per-HW-slot `warn!` with `tid`/`state`/`pc`/`lr`/`sp` and break instead of force-waking waiters with `STATUS_TIMEOUT`. Increments `scheduler.deadlock_halts` metric; sets the UI shutdown flag so the window closes alongside the worker. Default is force-wake (preserved probe-run behaviour — counts as `scheduler.deadlock_recoveries`). Also settable via `XENIA_HALT_ON_DEADLOCK=1`. |
---
### `browse` — Browse XISO disc image contents
```
xenia-rs browse <PATH>
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XISO file |
---
### `info` — Display XEX header information
```
xenia-rs info <PATH>
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XEX file |
---
### `extract` — Extract PE image and metadata from XEX
```
xenia-rs extract <PATH> [-o <OUTPUT>] [--db <DB>]
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XEX or ISO file |
| `-o, --output` | Option\<String\> | input dir | Output directory |
| `--db` | Option\<String\> | none | SQLite DB; writes `metadata`, `sections`, `imports` tables |
---
### `dis` — Full disassembly with function detection and xrefs
```
xenia-rs dis <PATH> [-o <OUTPUT>] [--db <DB>] [--quiet]
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XEX or ISO file |
| `-o, --output` | Option\<String\> | stdout | Output .asm file |
| `--db` | Option\<String\> | none | SQLite DB; includes extract tables + `functions`, `labels`, `instructions`, `xrefs` |
| `--quiet` | bool flag | false | Suppress assembly text output (DB-only mode) |
---
### `check` — Deterministic run digest + golden-diff regression detector (P8)
```
xenia-rs check <PATH> [-n <INSTRS>] [--out <PATH>] [--expect <PATH>]
```
| Arg | Type | Default | Description |
|-----|------|---------|-------------|
| `path` | String (positional) | — | Path to XEX or ISO file |
| `-n, --max-instructions` | u64 | 2_000_000 | Instructions to execute before computing the digest |
| `--out` | Option\<String\> | stdout | Write the 14-field JSON digest to this path |
| `--expect` | Option\<String\> | none | Golden digest JSON; byte-for-byte (trimmed) diff against the run's output. Exits non-zero on mismatch with `expected vs actual` on stderr |
**Digest fields** (stable order, one `u64` per line): `path`, `instructions`, `imports`, `unimpl`, `packets`, `draws`, `swaps`, `resolves`, `unique_render_targets`, `shader_blobs_live`, `interrupts_delivered`, `interrupts_dropped`, `texture_cache_entries`, `texture_decodes`.
**Typical use**: Run once on a known-good build → commit the output as `run.digest.json`. CI re-runs `xenia-rs check … --expect run.digest.json`; non-zero exit blocks the PR on drift.
---
## Environment Variables
### `XENIA_DB_BATCH_SIZE`
- **Source**: `xenia-rs/crates/xenia-analysis/src/db.rs` (lines 35-45)
- **Type**: u64
- **Default**: `100_000`
- **Validation**: Must be > 0; invalid values fall back to default
- **Effect**: Rows per streaming commit / trace buffer flush. `import_calls` always flushes at 1,000 (not configurable).
### `RUST_LOG`
- **Source**: standard `tracing-subscriber` env filter
- **Default behavior**: `"warn"` when `exec --quiet`, otherwise `"info"`
- **Override**: Set to any tracing filter string (e.g. `debug`, `xenia_analysis=trace`)
- **Note**: `--log-filter` takes precedence over `RUST_LOG`.
### `XENIA_FAKE_PAD`
- **Source**: `xenia-rs/crates/xenia-ui/src/input.rs` (`fake_pad_policy`)
- **Default**: enabled (simulated pad when no physical controller)
- **Disable with**: `XENIA_FAKE_PAD=0` (or `false` / `off`)
- **Effect**: when no gilrs pad is attached, `XamInputGetState` still returns `STATUS_SUCCESS` with an all-zero `X_INPUT_STATE` so games don't bail with `ERROR_DEVICE_NOT_CONNECTED`. Set to `0` to get truthful "no controller" reporting.
### `XENIA_SCHED_ORDER` / `XENIA_SCHED_SEED`
- **Source**: `xenia-rs/crates/xenia-cpu/src/scheduler.rs` (`OrderMode::from_env`)
- **Default**: fixed 0..=5
- **Effect**: `random` (with optional u64 `XENIA_SCHED_SEED`) shuffles round order for fuzzing thread interleavings.
### `XENIA_HALT_ON_DEADLOCK`
- **Source**: `xenia-rs/crates/xenia-app/src/main.rs` (resolved at the top of `run_execution`)
- **Values**: `1` or `true` (case-insensitive) to enable; anything else = disabled
- **Default**: disabled (force-wake waiters with `STATUS_TIMEOUT`, increment `scheduler.deadlock_recoveries`)
- **Effect**: equivalent to `exec --halt-on-deadlock`. OR'd with the flag — either source is sufficient to trip the halt path. Use from shells / recipes without rewiring CLI args.
### `RUST_LOG_SPAN_EVENTS`
- **Source**: parsed by `observability::parse_span_events`
- **Values**: `full | close | active | enter | exit | new` (anything else = none)
- **Effect**: Controls the `FmtSpan` setting on fmt layers. `close` is the most useful — every span emits a line with `time.busy`/`time.idle` elapsed, giving per-phase timing in the console without reading a Chrome trace.
---
## Database Table Layering
| Command | Tables |
|---------|--------|
| `extract --db` | `metadata`, `sections`, `imports` |
| `dis --db` | above + `functions`, `labels`, `instructions`, `xrefs` |
| `exec --db` | above + `exec_trace`*, `import_calls`*, `branch_trace`* |
*Only written when corresponding `--trace-*` flag is passed to `exec`.
**Why:** Cumulative schema lets analysis tools query across all levels without joining separate DBs.
**How to apply:** When suggesting DB workflows, recommend the appropriate command tier for the user's analysis goal.