# Page Template — Canonical Structure

This file is the **reference for every instruction page** in the manual.
It documents the section order, what each section is for, and the
formatting conventions that the Phase 1 generator emits and Phase 2
reviewers enhance.

Do **not** copy this file to create a new page. Instruction pages are
produced by `generator/generate_manual.py` and should stay under the
generator's control.

---

## Page anatomy (section order)

Every page follows this skeleton:

```markdown
# `<base-mnem>` — <Short description>

> **Category:** [<Group label>](../categories/<group>.md) · **Form:** [<FORM>](../forms/<FORM>.md) · **Opcode:** `0x........`

<!-- GENERATED: BEGIN -->

## Assembler Mnemonics
<table — runtime Rc/OE/LK variants + VMX128 siblings + memory u/x/ux siblings>

## Syntax
<fenced `asm` block with bracketed-modifier notation, one template per variant>

## Encoding
<per XML-entry subsection: opcode word, primary/extended, sync flag, bit-layout table>

## Operands
<field table — name, role per mnemonic, IBM-style description>

## Register Effects
<per-mnemonic: unconditional / conditional reads + writes>

## Status-Register Effects
<CR0/CR1/CR6, XER[CA/OV/SO], FPSCR, VSCR updates — only ones that apply>

## Operation (pseudocode)
<fenced PPC-style pseudocode block — IBM convention>

## C Translation Example
<fenced `c` block — minimal, idiomatic rendering a translator could emit>

## Implementation References
<xenia-canary XML / emit line, xenia-rs opcode / decoder / interpreter line range,
 plus a <details> block with the frozen interpreter body snapshot>

<!-- GENERATED: END -->

## Special Cases & Edge Conditions
<hand-written. RA0 / alignment / endian / reservation / SPR-remap / VMX128 fusion>

## Related Instructions
<hand-written. Cross-links to siblings that didn't land on the same page>

## IBM Reference
<optional. Link to IBM AIX PowerPC reference when it adds value>
```

### Sentinel markers

The `<!-- GENERATED: BEGIN -->` / `<!-- GENERATED: END -->` pair
separates machine-generated content from hand-written enhancement.

- **Inside the sentinels:** rewritten on every generator run. Do not
  edit — your changes will be overwritten.
- **Outside the sentinels:** preserved across regenerations. Put all
  Phase 2 enhancements there.

If a page's generated section is missing the `END` sentinel the
generator assumes a human has fully taken over and leaves the file
untouched.

---

## Writing conventions

### Pseudocode

Follow IBM's AIX reference style:

```
EA <- (RA|0) + EXTS(d)
RT <- ZEXT32_to_64(MEM(EA, 4))
```

- `<-` for assignment, `(X)` for "value of register X".
- `(RA|0)` for RA0 fields — literal 0 when the encoded register is 0.
- `EXTS(x)` = sign-extend, `ZEXT/SEXT<n>_to_<m>(x)` explicit when helpful.
- `||` for bit concatenation.
- `MEM(EA, n)` for an n-byte big-endian memory read.
- `CR[BF] <- ...` for CR field updates.
- Register bit numbering in pseudocode is **PowerPC big-endian** (bit 0
  is the MSB). `(RS)[56:63]` is the low byte of RS.

### C translation

- Use a pseudo-context of `r[]` (GPRs), `f[]` (FPRs), `v[]` (128-bit
  vectors), `cr[]` (CR fields), and scalars `xer`, `lr`, `ctr`, `pc`.
- Prefer `int64_t`/`uint64_t` for 64-bit ops; cast to `int32_t` for
  32-bit sub-word ops and explicitly sign/zero-extend.
- Use `mem_read_u32_be` / `mem_write_vec128_be` style helpers to make
  the big-endian memory model explicit.
- Show the base form always; add one annotated variant (e.g. `if
  (insn.Rc) ...`) only when it genuinely changes the translation.

### Bit ordering

PowerPC big-endian bit numbering is used throughout the manual (bit 0
is MSB). The same convention is used by IBM's reference and by the XML
source. Do not switch to Intel-style LSB-first numbering.

### Vector lane indexing

Altivec / VMX uses **big-endian lane indexing**: lane 0 is the
most-significant 16 bytes (or 4 words / 2 doublewords) of the vector.
On little-endian hosts (x86-64) byte-swap is applied at load/store to
preserve this invariant — call that out in the "Special Cases" section
when relevant.

---

## Example: fully-reviewed page

See `alu/addx.md` after Phase 2 review for the canonical look. It
demonstrates:

- Complete operand descriptions (not TODO stubs).
- Pseudocode with explicit CR/XER updates.
- C translation covering the base form plus Rc and OE variants.
- "Special Cases" calling out 32-bit vs 64-bit overflow tracking.
- Cross-links to `addcx`, `addex`, `subfx`.

---

## Golden-path spot-check list (Phase 2 review order)

These pages are reviewed first; they anchor the expected quality bar:

| Page | Reason |
| --- | --- |
| `alu/addx.md` | XO form with Rc+OE — representative ALU |
| `alu/addi.md` | D form with RA0 semantics — representative immediate |
| `memory/lwz.md` | D form load family (lwz/lwzu/lwzx/lwzux) |
| `memory/stvx.md` | Vector store with alignment mask |
| `memory/lvsl.md` | Permute-control generator |
| `branch/bclrx.md` | BO/BI conditional with LK |
| `branch/bx.md` | Absolute/relative branch |
| `control/mfspr.md` | SPR halves-swap encoding |
| `control/mtcrf.md` | CR field-mask update |
| `fpu/faddx.md` | Double-precision FPU + CR1 via Rc |
| `vmx/vaddfp.md` | VMX + VMX128 sibling on one page |
| `vmx/vperm.md` | Byte permute — lane-indexing discipline |
| `vmx128/vpkd3d128.md` | VMX128 orphan (no non-128 sibling) |