Files

sim dedcf37867 docs(ppc-manual): quote Canary and our own decoder, not the retired xenia-rs

The generator had not been able to run correctly since the manual moved into
`tools/ppc-manual/`: it computed the repository root as `HERE.parent.parent`,
which now names `tools/`, so the XML, Canary's emitters and xenia-rs all stopped
resolving — silently, because both scrapers skipped what they could not find.
Every page's references had been pointing at paths that exist nowhere.

What each source contributed, measured on the 350 pages before this change:

  Operation (pseudocode)  251 pages: fixed boilerplate "derives from the xenia-rs
                          interpreter"; 99 carry real hand-written seeds
  C translation           337 pages: the same kind of boilerplate
  xenia-rs snapshot       336 pages: the interpreter arm, pasted in — the only
                          per-instruction semantics on unseeded pages
  links                   xenia-rs opcode/decoder/interpreter + Canary emitter

Now:

  * semantics come from **Xenia Canary**, the reference emulator, read through
    `git show` at a pinned upstream commit (`origin/canary_experimental`,
    f21ebd49e9). Not our checkout: it carries instrumentation and lacked
    upstream's `mcrf` fix, so it would have published probes and a wrong `mcrf`.
    Each page embeds the emitter (`InstrEmit_<mnem>`), and for the 128 pure
    one-line delegations also the helper that holds the semantics.
  * decode references point at `crates/sylpheed-ppc` — the decoder that
    produces `sylpheed.db` — as in-repo relative links.
  * the boilerplate now says what is true, and the C translation guide maps
    Canary's actual HIR calls, checked against `ppc_hir_builder.h` (including
    that `UpdateCR(n, v)` truncates to 32 bits).
  * `rust_scraper.py` -> `decoder_scraper.py` (interpreter half dropped);
    missing sources are now errors, not empty results.

Verified:

  consistency checks        455 XML entries, 350 families, 598 index keys
  hand-written tails        386/386 byte-identical after regeneration
  xenia-rs in generated     0
  pages with a snapshot     349/350 (was 336) — `dcbi` has no Canary emitter at all
  in-repo decoder links     910/910 resolve to a line holding the identifier
  emitter boundaries        brace counter == column-0 `}` rule on 521/521;
                            preprocessor model unit-tested (#if 0/#else/#elif)
  idempotency               re-run: 0 pages updated, 0 working-tree changes

Hand-written notes (outside the generated regions) are not rewritten here:

  * 110 links into `../../xenia-rs/...` were dead; they now point at the file in
    the archived repository (git.mc02.dev/fabi/xenia-rs @ 8401d4d). Line anchors
    were dropped because the notes predate that commit — 0 of 441 old line
    ranges match it — and a precise-looking wrong anchor is worse than none. The
    link text, which carries the author's line numbers, is unchanged.
  * 140 prose claims about xenia-rs's behaviour remain. 23 are verified to hold
    for Canary too (the 32-bit CR0 truncation, OE left unimplemented); the other
    114 need checking one by one, and some invert — e.g. `divdx` notes a correct
    64-bit CR0 update in xenia-rs where Canary's `UpdateCR` truncates. Left for
    a deliberate pass rather than a blind substitution.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-16 20:34:34 +02:00

6.5 KiB

Raw Permalink Blame History

PowerPC Instruction Manual (Xenia Xbox 360 Subset)

A reference for the Xenon PowerPC dialect used by the Xbox 360. Its primary audience is an AI agent translating PPC assembly functions into equivalent C. The content is derived from Xenia Canary — the reference emulator: its instruction table and its PPC emitters, quoted at a pinned upstream commit — and from Sylpheed's own decoder, crates/sylpheed-ppc, which produces the disassembly in sylpheed.db. It may be deepened with the IBM AIX PowerPC reference.

455 distinct XML-level instructions (one page each).
350 instruction family pages (VMX128 siblings folded).
598 assembly mnemonics once runtime Rc/OE/LK variants are expanded — all resolvable through index.json.

How to use this manual (translation agent)

Parse the 32-bit instruction word and identify the mnemonic. Resolve it through index.json: every assembly form (including add., addo., bclrl, …) is a top-level key pointing at a page.
Open the page referenced by index.json[mnem].page. The page is in a fixed format — see the "Page anatomy" section below.
Emit a C translation consistent with the page's pseudocode, the registers-affected list, and the status-register effects.

Page anatomy

Every instruction page has the same sections, in this order:

Section	Purpose
Assembler Mnemonics	Table of every runtime variant (Rc/OE/LK) the base XML entry covers, plus VMX128 siblings.
Syntax	Canonical assembly template with `[OE]`/`[Rc]`/`[LK]` bracketed-modifier notation.
Encoding	Form name, opcode word, primary/extended opcodes, and bit-layout table.
Operands	Every bit-field operand, its role per variant, and its meaning.
Register Effects	Unconditional vs. conditional reads and writes, per variant.
Status-Register Effects	CR0/CR1/CR6, XER[CA/OV/SO], FPSCR, VSCR updates.
Operation	PPC-style pseudocode (`RT <- …`, `EXTS(…)`, `MEM(EA, n)`).
C Translation Example	Minimal idiomatic C rendering a translator could emit.
Implementation References	Canary's XML entry and emitter (linked at the pinned commit, with a frozen snapshot of the emitter), and Sylpheed's opcode/decoder lines.
Special Cases & Edge Conditions	RA=0, alignment, endian byte-reverse, reservation, SPR remapping, VMX128 fusion.
Related Instructions	Sibling cross-links.
IBM Reference	Optional link to IBM AIX PPC reference for canonical pseudocode.

Sections between the  and  sentinels are produced by generator/generate_manual.py and re-generated on every run. Sections outside the sentinels are hand-written and preserved across re-runs.

Conventions

Bit numbering follows PowerPC (big-endian, bit 0 = MSB).
GPRs are 64-bit. 32-bit operations operate on bits [32:63] and conventionally write the low 32 bits with zero- or sign-extension into the high 32 bits. Page pseudocode makes this explicit when it matters.
Vector registers are 128-bit with lane 0 at the most-significant byte (big-endian lane indexing). On x86 hosts byte-swap is applied at load/store to preserve this invariant.
CR is 8 × 4-bit fields CR0..CR7, each {LT, GT, EQ, SO}. The record form of arithmetic instructions writes CR0 (integer) or CR1 (FPU); the record form of vector compare writes CR6 = {all-true, 0, all-false, 0}.
XER holds SO, OV, and CA at bits 32, 33, 34 respectively (PPC bit numbering), plus a 7-bit string length used by lswi/stswi.

Category	Families	XML entries	Description
Integer ALU	70	70	Fixed-point add/sub/multiply/divide, logical, rotate, shift, compare, count-leading-zeros, sign-extension, trap-on-condition.
Branch & System	9	9	Unconditional / conditional branches, branch to LR/CTR, traps, system call.
Control / CR / SPR	26	26	Condition-register logical ops, CR field moves, mfspr/mtspr/mtcrf, time-base reads, synchronisation (sync, isync, eieio).
Floating-Point	33	33	IEEE-754 add/sub/mul/div/sqrt, fused multiply-add, conversions, compares, FPSCR moves.
Memory	56	112	Loads/stores for byte, half, word, doubleword, float, multiple and string; cache management (dcbt, dcbf, dcbz); reservation pair lwarx/stwcx.
VMX (Altivec)	144	193	128-bit SIMD over 32 registers V0–V31. Integer/float arithmetic, logical, compare, permute/merge, pack/unpack, saturation helpers.
VMX128	12	12	Xbox-360-specific Altivec extension that widens the vector register file to 128 registers (V0–V127). Register IDs are encoded with bit-fusion across non-contiguous fields.

Forms

Form	Count	Page
`A`	21	forms/A.md
`B`	1	forms/B.md
`D`	40	forms/D.md
`DCBZ`	2	forms/DCBZ.md
`DS`	5	forms/DS.md
`I`	1	forms/I.md
`M`	3	forms/M.md
`MD`	4	forms/MD.md
`MDS`	2	forms/MDS.md
`SC`	1	forms/SC.md
`VA`	14	forms/VA.md
`VC`	13	forms/VC.md
`VX`	117	forms/VX.md
`VX128`	34	forms/VX128.md
`VX128_1`	16	forms/VX128_1.md
`VX128_2`	1	forms/VX128_2.md
`VX128_3`	15	forms/VX128_3.md
`VX128_4`	2	forms/VX128_4.md
`VX128_5`	1	forms/VX128_5.md
`VX128_P`	1	forms/VX128_P.md
`VX128_R`	5	forms/VX128_R.md
`X`	117	forms/X.md
`XFL`	1	forms/XFL.md
`XFX`	4	forms/XFX.md
`XL`	12	forms/XL.md
`XO`	21	forms/XO.md
`XS`	1	forms/XS.md

Regenerating this manual

python3 generator/generate_manual.py

Re-running the generator is safe — it only rewrites sections between  /  sentinels. Add your hand-written content below the END marker and it will be preserved.

6.5 KiB Raw Permalink Blame History Unescape Escape