Sylpheed/tools/ppc-manual

📌 Adopted 2026-09-13 from an untracked directory in the project root, where it had lived on one disk since April — see docs/agents/CONSOLIDATION.md.

⚠️ The generator's inputs have moved. generator/generate_manual.py reads xenia-canary/tools/ppc-instructions.xml and the xenia-rs source tree. That emulator is retired: its decoder now lives here as crates/sylpheed-ppc, and the generator must be repointed before it is run again. The manual's content is unaffected — it is checked in, and nothing regenerates it implicitly.

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 the two authoritative sources in this repository — xenia-canary (C++ emulator) and xenia-rs (Rust rewrite) — and 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)

1. 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.
2. Open the page referenced by index.json[mnem].page. The page is in a fixed format — see the "Page anatomy" section below.
3. 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	Direct links into xenia-canary/ and xenia-rs/ with line numbers.
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 <!-- GENERATED: BEGIN --> and <!-- GENERATED: END --> 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.

Categories

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 <!-- GENERATED: BEGIN --> / <!-- GENERATED: END --> sentinels. Add your hand-written content below the END marker and it will be preserved.