# 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)

1. Parse the 32-bit instruction word and identify the mnemonic. Resolve it
   through [`index.json`](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** | 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 `<!-- GENERATED: BEGIN -->` and `<!-- GENERATED: END -->`
sentinels are produced by [`generator/generate_manual.py`](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](categories/alu.md) | 70 | 70 | Fixed-point add/sub/multiply/divide, logical, rotate, shift, compare, count-leading-zeros, sign-extension, trap-on-condition. |
| [Branch & System](categories/branch.md) | 9 | 9 | Unconditional / conditional branches, branch to LR/CTR, traps, system call. |
| [Control / CR / SPR](categories/control.md) | 26 | 26 | Condition-register logical ops, CR field moves, mfspr/mtspr/mtcrf, time-base reads, synchronisation (sync, isync, eieio). |
| [Floating-Point](categories/fpu.md) | 33 | 33 | IEEE-754 add/sub/mul/div/sqrt, fused multiply-add, conversions, compares, FPSCR moves. |
| [Memory](categories/memory.md) | 56 | 112 | Loads/stores for byte, half, word, doubleword, float, multiple and string; cache management (dcbt, dcbf, dcbz); reservation pair lwarx/stwcx. |
| [VMX (Altivec)](categories/vmx.md) | 144 | 193 | 128-bit SIMD over 32 registers V0–V31. Integer/float arithmetic, logical, compare, permute/merge, pack/unpack, saturation helpers. |
| [VMX128](categories/vmx128.md) | 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](forms/A.md) |
| `B` | 1 | [forms/B.md](forms/B.md) |
| `D` | 40 | [forms/D.md](forms/D.md) |
| `DCBZ` | 2 | [forms/DCBZ.md](forms/DCBZ.md) |
| `DS` | 5 | [forms/DS.md](forms/DS.md) |
| `I` | 1 | [forms/I.md](forms/I.md) |
| `M` | 3 | [forms/M.md](forms/M.md) |
| `MD` | 4 | [forms/MD.md](forms/MD.md) |
| `MDS` | 2 | [forms/MDS.md](forms/MDS.md) |
| `SC` | 1 | [forms/SC.md](forms/SC.md) |
| `VA` | 14 | [forms/VA.md](forms/VA.md) |
| `VC` | 13 | [forms/VC.md](forms/VC.md) |
| `VX` | 117 | [forms/VX.md](forms/VX.md) |
| `VX128` | 34 | [forms/VX128.md](forms/VX128.md) |
| `VX128_1` | 16 | [forms/VX128_1.md](forms/VX128_1.md) |
| `VX128_2` | 1 | [forms/VX128_2.md](forms/VX128_2.md) |
| `VX128_3` | 15 | [forms/VX128_3.md](forms/VX128_3.md) |
| `VX128_4` | 2 | [forms/VX128_4.md](forms/VX128_4.md) |
| `VX128_5` | 1 | [forms/VX128_5.md](forms/VX128_5.md) |
| `VX128_P` | 1 | [forms/VX128_P.md](forms/VX128_P.md) |
| `VX128_R` | 5 | [forms/VX128_R.md](forms/VX128_R.md) |
| `X` | 117 | [forms/X.md](forms/X.md) |
| `XFL` | 1 | [forms/XFL.md](forms/XFL.md) |
| `XFX` | 4 | [forms/XFX.md](forms/XFX.md) |
| `XL` | 12 | [forms/XL.md](forms/XL.md) |
| `XO` | 21 | [forms/XO.md](forms/XO.md) |
| `XS` | 1 | [forms/XS.md](forms/XS.md) |

## Regenerating this manual

```bash
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.