xenia-rs/migration/project-root/ppc-manual/TEMPLATE.md

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:

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