fabi/Sylpheed
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ppc-manual): check every xenia-rs claim against Canary's source #45

Merged
fabi merged 1 commits from docs/ppc-manual-canary-claims into main 2026-09-16 20:03:05 +00:00
Conversation 0 Commits 1 Files Changed 254 +491 -494
fabi commented 2026-09-16 19:53:03 +00:00
Owner
Copy Link

#42 moved the manual's generated sections onto Canary. The hand-written sections below them still described the retired xenia-rs interpreter (its snapshots, Rust casts, vmx.rs helpers). This PR checks each of those statements, 490 across 254 pages, against Canary's emitters and x64 backend at the pinned commit f21ebd49e. Each one is either restated as what Canary does or dropped.

Claims that were wrong, not just outdated

Area The manual said Canary / spec
VSCR[SAT] (all v*s saturating ops, mfvscr, mtvscr) set stickily, readable never modelled: x64 DID_SATURATE always yields 0, and mfvscr reads vscr_vec, which only mtvscr writes
lswi lswx stswi stswx dcbi mtfsb0 mtfsb1 vmsum* vmhaddshs vupkhpx vupklpx, most SPRs implemented XEINSTRNOTIMPLEMENTED, which breaks by default
td tdi tw twi every trap fires TO is evaluated, and TO = 0 emits nothing
stvebx stvehx stvewx write 16 bytes write one element
mtmsrd writes the whole MSR writes only EE (0x8000)
lwarx/stwcx. (and the 64-bit pair) per-address reservation 64 KiB block bitmap plus a value compare; a second reservation hits int3
fres / frsqrte precision "12–14 bits" spec: one part in 256 / one part in 32 (AIX reference); Canary's frsqrte and vrsqrtefp are table-driven estimates
stfs rounds under RN, can set FPSCR bits the store conversion is bit selection, and the AIX reference says stfs does not affect FPSCR
fctidz saturation PPC returns 0x8000… for both signs PPC saturates in both directions, and Canary's x64 fix-up reproduces that
rounding (fctid, fctiw, frsp, fcfid) RN ignored honoured through the host MXCSR that mtfsf/mtfsfi load
vcmpbfp with NaN both bits set Canary's comment says both bits, but its code sets only 0x40000000
mftb, mfspr/mtspr tables, mfocrf/mtocrf, vpkd3d128, vupkd3d128, dot products xenia-rs behaviour rewritten to Canary's behaviour

Marked unverified instead of asserted

  • Whether Xenon boots with FPSCR[NI]=1 or VSCR[NJ]=1. Canary starts the FPU in IEEE mode and VMX in flush-to-zero mode, and its own init comment says the startup state was never checked.
  • vmaddcfp128 operand order. Canary computes VA*VD + VB; the page claimed VD*VB + VA. Project Sylpheed uses this instruction 47 times (sylpheed.db), so this one matters.
  • Whether Canary's reciprocal estimates match Xenon bit for bit.

Checks

  • Every replacement matched exactly once, outside the generated sections, and the generated sections are byte-identical.
  • Re-running generate_manual.py changes nothing: 0 pages updated, 350 unchanged.
  • No relative link added by this PR is broken. Links to mfvscr/mtvscr/mffsx/mtfsfx now point into control/, and the dead vmulfp.md links now point to vmx128/vmulfp128.md.
  • A sweep for xenia, interpreter, snapshot and .rs outside the generated sections leaves only the README title and Canary-specific mentions.

Not fixed here

  • The manual already had 524 broken relative links (442 targets) before this PR. Most are generated form pages linking ../vmx128/<x>.md for instructions whose page lives in vmx/.
  • None of Canary's unimplemented instructions appear in Sylpheed's disassembly. mfmsr (612) and mtmsrd (1,239) do, so the mfmsr page no longer says titles never use it.

🤖 Generated with Claude Code

#42 moved the manual's generated sections onto Canary. The hand-written sections below them still described the retired xenia-rs interpreter (its snapshots, Rust casts, `vmx.rs` helpers). This PR checks each of those statements, 490 across 254 pages, against Canary's emitters and x64 backend at the pinned commit `f21ebd49e`. Each one is either restated as what Canary does or dropped. ## Claims that were wrong, not just outdated | Area | The manual said | Canary / spec | | --- | --- | --- | | `VSCR[SAT]` (all `v*s` saturating ops, `mfvscr`, `mtvscr`) | set stickily, readable | never modelled: x64 `DID_SATURATE` always yields 0, and `mfvscr` reads `vscr_vec`, which only `mtvscr` writes | | `lswi` `lswx` `stswi` `stswx` `dcbi` `mtfsb0` `mtfsb1` `vmsum*` `vmhaddshs` `vupkhpx` `vupklpx`, most SPRs | implemented | `XEINSTRNOTIMPLEMENTED`, which breaks by default | | `td` `tdi` `tw` `twi` | every trap fires | `TO` is evaluated, and `TO = 0` emits nothing | | `stvebx` `stvehx` `stvewx` | write 16 bytes | write one element | | `mtmsrd` | writes the whole MSR | writes only `EE` (`0x8000`) | | `lwarx`/`stwcx.` (and the 64-bit pair) | per-address reservation | 64 KiB block bitmap plus a value compare; a second reservation hits `int3` | | `fres` / `frsqrte` precision | "12–14 bits" | spec: one part in 256 / one part in 32 (AIX reference); Canary's `frsqrte` and `vrsqrtefp` are table-driven estimates | | `stfs` | rounds under `RN`, can set FPSCR bits | the store conversion is bit selection, and the AIX reference says `stfs` does not affect FPSCR | | `fctidz` saturation | PPC returns `0x8000…` for both signs | PPC saturates in both directions, and Canary's x64 fix-up reproduces that | | rounding (`fctid`, `fctiw`, `frsp`, `fcfid`) | `RN` ignored | honoured through the host MXCSR that `mtfsf`/`mtfsfi` load | | `vcmpbfp` with NaN | both bits set | Canary's comment says both bits, but its code sets only `0x40000000` | | `mftb`, `mfspr`/`mtspr` tables, `mfocrf`/`mtocrf`, `vpkd3d128`, `vupkd3d128`, dot products | xenia-rs behaviour | rewritten to Canary's behaviour | ## Marked unverified instead of asserted - Whether Xenon boots with `FPSCR[NI]=1` or `VSCR[NJ]=1`. Canary starts the FPU in IEEE mode and VMX in flush-to-zero mode, and its own init comment says the startup state was never checked. - `vmaddcfp128` operand order. Canary computes `VA*VD + VB`; the page claimed `VD*VB + VA`. Project Sylpheed uses this instruction 47 times (`sylpheed.db`), so this one matters. - Whether Canary's reciprocal estimates match Xenon bit for bit. ## Checks - Every replacement matched exactly once, outside the generated sections, and the generated sections are byte-identical. - Re-running `generate_manual.py` changes nothing: 0 pages updated, 350 unchanged. - No relative link added by this PR is broken. Links to `mfvscr`/`mtvscr`/`mffsx`/`mtfsfx` now point into `control/`, and the dead `vmulfp.md` links now point to `vmx128/vmulfp128.md`. - A sweep for `xenia`, `interpreter`, `snapshot` and `.rs` outside the generated sections leaves only the README title and Canary-specific mentions. ## Not fixed here - The manual already had 524 broken relative links (442 targets) before this PR. Most are generated form pages linking `../vmx128/<x>.md` for instructions whose page lives in `vmx/`. - None of Canary's unimplemented instructions appear in Sylpheed's disassembly. `mfmsr` (612) and `mtmsrd` (1,239) do, so the `mfmsr` page no longer says titles never use it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
fabi added 1 commit 2026-09-16 19:53:03 +00:00
docs(ppc-manual): check every xenia-rs claim against Canary's source
All checks were successful
CI / Native — linux (pull_request) Successful in 2h1m57s
Details
CI / WASM — Web (pull_request) Successful in 28m8s
Details
CI / Formatting (pull_request) Successful in 1m26s
Details
84856fc081 
The hand-written parts of the manual still described how the retired
xenia-rs interpreter behaved: its snapshots, Rust casts and helpers. Each of
those 490 statements is now either restated as what Canary's emitters and
x64 backend actually do (at the pinned canary_experimental commit), or
dropped where it only made sense for xenia-rs.

Checking them turned up claims that were wrong, not just outdated:

- VSCR[SAT] is never modelled in Canary (DID_SATURATE is a stub and mfvscr
  cannot see it); the pages said saturating ops set it stickily.
- Canary does not implement lswi/lswx/stswi/stswx, dcbi, mtfsb0/mtfsb1,
  vmsum*, vmhaddshs, vupkhpx/vupklpx, and most SPRs; pages described them
  as working.
- Traps evaluate TO in Canary; stvebx/stvehx/stvewx store one element, not
  16 bytes; mtmsrd writes only EE; fres/frsqrte/vrsqrtefp precision claims
  and the stfs "rounds under RN / sets FPSCR" claim contradicted the spec.
- Reservations are a 64 KiB block bitmap plus a value compare, not
  per-address tracking.

Claims that neither Canary's source nor a public spec settles are marked
unverified (NI at boot, vmaddcfp128 operand order, estimate bit-exactness).

Generated regions are untouched; re-running the generator changes nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
fabi merged commit 4f70042a2d into main 2026-09-16 20:03:05 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
agent/decoder
Owned by the Decoder (disc to meaning; runs the emulator)
 agent/port
Owned by the Port (disc to playable; no RE)
 kind/ask
One agent asking the other for something it cannot answer in role
 kind/bundle
A bundle the human defined; agents decompose it into items
 kind/defect
Found by a play-test or a check
 kind/item
One unit of work, small enough to finish in a single session
 state/approved
Human approved the shape; an agent may start
 state/blocked
Waiting on another item; use the Depends-On field, not prose
 state/in-progress
An agent is working it now
 state/needs-human
Done as far as an agent can tell -- a person must look. The body says what to look at
 state/proposed
Agent proposed this item; awaiting the human's approval to start
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
sylph-decoder sylph-pi sylph-port fabi
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: fabi/Sylpheed#45
Delete Branch "docs/ppc-manual-canary-claims"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?