e6d43a23ac
Bundles state that lives OUTSIDE the xenia-rs repo so a fresh clone on
another machine can be brought up to identical configuration via
migration/setup.sh:
- claude-memory/ ~/.claude/projects/-home-fabi-RE-Project-Sylpheed/memory/
(103 files, 1.1 MB - MEMORY.md + every
project_xenia_rs_*.md from audits
addis_signext through audit-058)
- project-root/dot-claude/ <project-root>/.claude/settings.json
(Stop hook + permissions)
- project-root/ppc-manual/ <project-root>/ppc-manual/
(PowerPC reference docs, 397 files, 3.7 MB)
- project-root/run-canary.sh <project-root>/run-canary.sh
- README.md Human-readable setup checklist
- setup.sh Idempotent installer (also reclones
xenia-canary at pinned HEAD 6de80dffe)
- MANIFEST.md Per-file mapping + per-file-not-bundled
restoration recipe
Excluded from bundle (not shippable via git):
- Sylpheed ISO (7.8 GB; copyright; manual copy required)
- sylpheed.db (395 MB; regenerable from XEX via analysis tooling)
- target/ build artifacts (rebuild on target)
- audit-runs probe firehoses (.log/.stdout/.stderr ~11 GB; rerun if needed)
- audit-runs memory dumps (.bin ~4.5 GB; rerun audit-026/027/029 if needed)
- xenia-canary checkout (setup.sh reclones from
git.mc02.dev/fabi/Xenia-Canary.git at HEAD 6de80dffe)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
160 lines
5.3 KiB
Markdown
160 lines
5.3 KiB
Markdown
# 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) |
|