dedcf37867
The generator had not been able to run correctly since the manual moved into
`tools/ppc-manual/`: it computed the repository root as `HERE.parent.parent`,
which now names `tools/`, so the XML, Canary's emitters and xenia-rs all stopped
resolving — silently, because both scrapers skipped what they could not find.
Every page's references had been pointing at paths that exist nowhere.
What each source contributed, measured on the 350 pages before this change:
Operation (pseudocode) 251 pages: fixed boilerplate "derives from the xenia-rs
interpreter"; 99 carry real hand-written seeds
C translation 337 pages: the same kind of boilerplate
xenia-rs snapshot 336 pages: the interpreter arm, pasted in — the only
per-instruction semantics on unseeded pages
links xenia-rs opcode/decoder/interpreter + Canary emitter
Now:
* semantics come from **Xenia Canary**, the reference emulator, read through
`git show` at a pinned upstream commit (`origin/canary_experimental`,
f21ebd49e9). Not our checkout: it carries instrumentation and lacked
upstream's `mcrf` fix, so it would have published probes and a wrong `mcrf`.
Each page embeds the emitter (`InstrEmit_<mnem>`), and for the 128 pure
one-line delegations also the helper that holds the semantics.
* decode references point at `crates/sylpheed-ppc` — the decoder that
produces `sylpheed.db` — as in-repo relative links.
* the boilerplate now says what is true, and the C translation guide maps
Canary's actual HIR calls, checked against `ppc_hir_builder.h` (including
that `UpdateCR(n, v)` truncates to 32 bits).
* `rust_scraper.py` -> `decoder_scraper.py` (interpreter half dropped);
missing sources are now errors, not empty results.
Verified:
consistency checks 455 XML entries, 350 families, 598 index keys
hand-written tails 386/386 byte-identical after regeneration
xenia-rs in generated 0
pages with a snapshot 349/350 (was 336) — `dcbi` has no Canary emitter at all
in-repo decoder links 910/910 resolve to a line holding the identifier
emitter boundaries brace counter == column-0 `}` rule on 521/521;
preprocessor model unit-tested (#if 0/#else/#elif)
idempotency re-run: 0 pages updated, 0 working-tree changes
Hand-written notes (outside the generated regions) are not rewritten here:
* 110 links into `../../xenia-rs/...` were dead; they now point at the file in
the archived repository (git.mc02.dev/fabi/xenia-rs @ 8401d4d). Line anchors
were dropped because the notes predate that commit — 0 of 441 old line
ranges match it — and a precise-looking wrong anchor is worse than none. The
link text, which carries the author's line numbers, is unchanged.
* 140 prose claims about xenia-rs's behaviour remain. 23 are verified to hold
for Canary too (the 32-bit CR0 truncation, OE left unimplemented); the other
114 need checking one by one, and some invert — e.g. `divdx` notes a correct
64-bit CR0 update in xenia-rs where Canary's `UpdateCR` truncates. Left for
a deliberate pass rather than a blind substitution.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
161 lines
5.4 KiB
Markdown
161 lines
5.4 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
|
|
<Canary XML entry + emitter line (linked at the pinned upstream commit), Sylpheed
|
|
opcode / decoder lines (crates/sylpheed-ppc), plus a <details> block with the
|
|
frozen Canary emitter snapshot — and the helper it calls, if it only delegates>
|
|
|
|
<!-- 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) |
|