# 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`](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`](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.