10dc260f0c
CONSOLIDATION.md Phase 6. Both lived untracked in the project root -- on one
disk, backed up by nothing.
tools/ppc-manual/ 393 files, 3.7 MB. 455 instructions, 350 family pages,
598 mnemonics resolvable through index.json, plus the
generator that produced them.
tools/run-canary.sh the oracle launcher.
🔴 THE LAUNCHER WAS BROKEN IN TWO WAYS AND IS REWRITTEN, not copied:
* it pointed at `xenia-rs/sylpheed.iso`, a SYMLINK. Wine cannot resolve one
and says "path invalid", which reads as a corrupt image rather than a path
problem -- it has cost a session before. It now points at the real file and
warns if handed a symlink.
* it hardcoded one machine's absolute paths, and named `xenia-rs`, which this
consolidation retires. Now derived from the script's own location, with
SYLPH_CANARY_BIN / SYLPH_ISO overrides and a check that each exists.
The standing constraints are in its header where someone will read them: one
emulator at a time, Canary runs MUTED, and never judge a crash or a hang from
a Bash-launched run -- a SIGKILL that looked like the binary was the editor's
process supervisor.
⚠️ The manual's GENERATOR reads the xenia-rs source tree, which is going away.
Its decoder now lives here as crates/sylpheed-ppc, so the generator must be
repointed before it is run again. Recorded in the README rather than left for
someone to discover; the manual's content is checked in and regenerates from
nothing implicitly.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
267 lines
10 KiB
Python
267 lines
10 KiB
Python
"""
|
||
Canonical bit layout per PPC instruction form.
|
||
|
||
Tables derived from xenia-canary/src/xenia/cpu/ppc/ppc_instr.h (struct
|
||
PPCOpcodeBits union). In PPC notation bit 0 is the MSB of the 32-bit
|
||
word (big-endian bit numbering).
|
||
|
||
Each entry is a list of (bit_start, bit_end_inclusive, field_name,
|
||
notes) tuples laid out from MSB (bit 0) to LSB (bit 31).
|
||
"""
|
||
|
||
|
||
# NOTE: bit ranges use PPC big-endian numbering (0 = MSB, 31 = LSB).
|
||
|
||
FORM_LAYOUTS: dict[str, list[tuple[int, int, str, str]]] = {
|
||
"I": [
|
||
(0, 5, "OPCD", "primary opcode"),
|
||
(6, 29, "LI", "signed 24-bit word-offset target"),
|
||
(30, 30, "AA", "absolute-address flag"),
|
||
(31, 31, "LK", "link flag (bl/ba/bla)"),
|
||
],
|
||
"B": [
|
||
(0, 5, "OPCD", "primary opcode"),
|
||
(6, 10, "BO", "branch options"),
|
||
(11, 15, "BI", "CR bit to test"),
|
||
(16, 29, "BD", "signed 14-bit word-offset target"),
|
||
(30, 30, "AA", "absolute-address flag"),
|
||
(31, 31, "LK", "link flag"),
|
||
],
|
||
"SC": [
|
||
(0, 5, "OPCD", "primary opcode (17)"),
|
||
(6, 19, "—", "reserved"),
|
||
(20, 26, "LEV", "exception level"),
|
||
(27, 29, "—", "reserved"),
|
||
(30, 30, "1", "fixed 1"),
|
||
(31, 31, "—", "reserved"),
|
||
],
|
||
"D": [
|
||
(0, 5, "OPCD", "primary opcode"),
|
||
(6, 10, "RT", "destination GPR (or RS when storing)"),
|
||
(11, 15, "RA", "source GPR (0 ⇒ literal 0 for RA0 forms)"),
|
||
(16, 31, "D/SI/UI", "16-bit signed or unsigned immediate"),
|
||
],
|
||
"DS": [
|
||
(0, 5, "OPCD", "primary opcode"),
|
||
(6, 10, "RT", "destination GPR (or RS)"),
|
||
(11, 15, "RA", "source GPR (0 ⇒ literal 0)"),
|
||
(16, 29, "DS", "14-bit signed word-scaled displacement"),
|
||
(30, 31, "XO", "extended opcode"),
|
||
],
|
||
"X": [
|
||
(0, 5, "OPCD", "primary opcode"),
|
||
(6, 10, "RT/FRT/VRT", "destination"),
|
||
(11, 15, "RA/FRA/VRA", "source A"),
|
||
(16, 20, "RB/FRB/VRB", "source B"),
|
||
(21, 30, "XO", "extended opcode (10 bits)"),
|
||
(31, 31, "Rc", "record-form flag"),
|
||
],
|
||
"XL": [
|
||
(0, 5, "OPCD", "primary opcode (19)"),
|
||
(6, 10, "BT/BO", "target / branch options"),
|
||
(11, 15, "BA/BI", "source A / CR bit to test"),
|
||
(16, 20, "BB", "source B"),
|
||
(21, 30, "XO", "extended opcode (10 bits)"),
|
||
(31, 31, "LK", "link flag"),
|
||
],
|
||
"XFX": [
|
||
(0, 5, "OPCD", "primary opcode (31)"),
|
||
(6, 10, "RT", "destination / source GPR"),
|
||
(11, 20, "spr/tbr/FXM", "SPR/TBR number (byte-swapped halves) or CR field mask"),
|
||
(21, 30, "XO", "extended opcode"),
|
||
(31, 31, "—", "reserved"),
|
||
],
|
||
"XFL": [
|
||
(0, 5, "OPCD", "primary opcode (63)"),
|
||
(6, 6, "L", "field-select behaviour"),
|
||
(7, 14, "FM", "FPSCR field mask"),
|
||
(15, 15, "W", "immediate-value flag"),
|
||
(16, 20, "FRB", "source FPR"),
|
||
(21, 30, "XO", "extended opcode"),
|
||
(31, 31, "Rc", "record-form flag (updates CR1)"),
|
||
],
|
||
"XS": [
|
||
(0, 5, "OPCD", "primary opcode (31)"),
|
||
(6, 10, "RS", "source GPR"),
|
||
(11, 15, "RA", "destination GPR"),
|
||
(16, 20, "sh", "shift amount low 5 bits"),
|
||
(21, 29, "XO", "extended opcode (9 bits)"),
|
||
(30, 30, "sh5", "shift amount high bit"),
|
||
(31, 31, "Rc", "record-form flag"),
|
||
],
|
||
"XO": [
|
||
(0, 5, "OPCD", "primary opcode (31)"),
|
||
(6, 10, "RT", "destination GPR"),
|
||
(11, 15, "RA", "source A"),
|
||
(16, 20, "RB", "source B"),
|
||
(21, 21, "OE", "overflow-enable flag"),
|
||
(22, 30, "XO", "extended opcode (9 bits)"),
|
||
(31, 31, "Rc", "record-form flag"),
|
||
],
|
||
"A": [
|
||
(0, 5, "OPCD", "primary opcode (59 or 63)"),
|
||
(6, 10, "FRT", "destination FPR"),
|
||
(11, 15, "FRA", "source A FPR"),
|
||
(16, 20, "FRB", "source B FPR"),
|
||
(21, 25, "FRC", "source C FPR (multiplier for madd-style ops)"),
|
||
(26, 30, "XO", "extended opcode (5 bits)"),
|
||
(31, 31, "Rc", "record-form flag (updates CR1)"),
|
||
],
|
||
"M": [
|
||
(0, 5, "OPCD", "primary opcode"),
|
||
(6, 10, "RS", "source GPR"),
|
||
(11, 15, "RA", "destination GPR"),
|
||
(16, 20, "SH/RB", "shift amount or source B"),
|
||
(21, 25, "MB", "mask begin"),
|
||
(26, 30, "ME", "mask end"),
|
||
(31, 31, "Rc", "record-form flag"),
|
||
],
|
||
"MD": [
|
||
(0, 5, "OPCD", "primary opcode (30)"),
|
||
(6, 10, "RS", "source GPR"),
|
||
(11, 15, "RA", "destination GPR"),
|
||
(16, 20, "sh", "shift amount low 5 bits"),
|
||
(21, 26, "mb/me", "6-bit mask field (swapped halves)"),
|
||
(27, 29, "XO", "extended opcode"),
|
||
(30, 30, "sh5", "shift amount high bit"),
|
||
(31, 31, "Rc", "record-form flag"),
|
||
],
|
||
"MDS": [
|
||
(0, 5, "OPCD", "primary opcode (30)"),
|
||
(6, 10, "RS", "source GPR"),
|
||
(11, 15, "RA", "destination GPR"),
|
||
(16, 20, "RB", "source B GPR"),
|
||
(21, 26, "mb/me", "6-bit mask field (swapped halves)"),
|
||
(27, 30, "XO", "extended opcode"),
|
||
(31, 31, "Rc", "record-form flag"),
|
||
],
|
||
"DCBZ": [
|
||
(0, 5, "OPCD", "primary opcode (31)"),
|
||
(6, 10, "—", "reserved"),
|
||
(11, 15, "RA", "base register (0 ⇒ literal 0)"),
|
||
(16, 20, "RB", "offset register"),
|
||
(21, 30, "XO", "extended opcode (1014 for dcbz / 1010 for dcbz128)"),
|
||
(31, 31, "—", "reserved"),
|
||
],
|
||
"VX": [
|
||
(0, 5, "OPCD", "primary opcode (4)"),
|
||
(6, 10, "VRT/VD", "destination vector register"),
|
||
(11, 15, "VRA/VA", "source A vector register"),
|
||
(16, 20, "VRB/VB", "source B vector register"),
|
||
(21, 31, "XO", "extended opcode (11 bits)"),
|
||
],
|
||
"VA": [
|
||
(0, 5, "OPCD", "primary opcode (4)"),
|
||
(6, 10, "VRT", "destination vector register"),
|
||
(11, 15, "VRA", "source A"),
|
||
(16, 20, "VRB", "source B"),
|
||
(21, 25, "VRC", "source C / shift"),
|
||
(26, 31, "XO", "extended opcode (6 bits)"),
|
||
],
|
||
"VC": [
|
||
(0, 5, "OPCD", "primary opcode (4)"),
|
||
(6, 10, "VRT", "destination vector register"),
|
||
(11, 15, "VRA", "source A"),
|
||
(16, 20, "VRB", "source B"),
|
||
(21, 21, "Rc", "record-form flag (updates CR6)"),
|
||
(22, 31, "XO", "extended opcode (10 bits)"),
|
||
],
|
||
"VX128": [
|
||
(0, 5, "OPCD", "primary opcode (4 or 5)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "VA128l", "source A low 5 bits"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 21, "VA128H", "source A high bit"),
|
||
(22, 22, "—", "reserved"),
|
||
(23, 25, "VC", "optional VC / XO sub-field"),
|
||
(26, 26, "VA128h", "source A middle bit"),
|
||
(27, 27, "—", "reserved"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
"VX128_1": [
|
||
(0, 5, "OPCD", "primary opcode (4)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "RA", "address register"),
|
||
(16, 20, "RB", "offset register"),
|
||
(21, 27, "XO", "extended opcode"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "—", "reserved"),
|
||
],
|
||
"VX128_2": [
|
||
(0, 5, "OPCD", "primary opcode (5)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "VA128l", "source A low 5 bits"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 21, "VA128H", "source A high bit"),
|
||
(23, 25, "VC", "source C 3-bit field"),
|
||
(26, 26, "VA128h", "source A middle bit"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
"VX128_3": [
|
||
(0, 5, "OPCD", "primary opcode (6)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "IMM", "5-bit immediate"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 27, "XO", "extended opcode"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
"VX128_4": [
|
||
(0, 5, "OPCD", "primary opcode (6)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "IMM", "5-bit immediate"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 23, "XO", "extended opcode"),
|
||
(24, 25, "z", "sub-operation selector"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
"VX128_5": [
|
||
(0, 5, "OPCD", "primary opcode (4)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "VA128l", "source A low 5 bits"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 21, "VA128H", "source A high bit"),
|
||
(22, 25, "SH", "4-bit shift amount"),
|
||
(26, 26, "VA128h", "source A middle bit"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
"VX128_P": [
|
||
(0, 5, "OPCD", "primary opcode (6)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "PERMl", "permute selector low 5 bits"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 22, "—", "reserved"),
|
||
(23, 25, "PERMh", "permute selector high 3 bits"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
"VX128_R": [
|
||
(0, 5, "OPCD", "primary opcode (4)"),
|
||
(6, 10, "VD128l", "destination low 5 bits"),
|
||
(11, 15, "VA128l", "source A low 5 bits"),
|
||
(16, 20, "VB128l", "source B low 5 bits"),
|
||
(21, 21, "VA128H", "source A high bit"),
|
||
(22, 25, "XO", "extended opcode (compare)"),
|
||
(26, 26, "VA128h", "source A middle bit"),
|
||
(27, 27, "Rc", "record-form flag (updates CR6)"),
|
||
(28, 29, "VD128h", "destination high 2 bits"),
|
||
(30, 31, "VB128h", "source B high 2 bits"),
|
||
],
|
||
}
|
||
|
||
|
||
def render_bit_table(form: str) -> str:
|
||
"""Return a markdown table of the form's bit layout."""
|
||
layout = FORM_LAYOUTS.get(form)
|
||
if not layout:
|
||
return f"_Unknown form_ `{form}` _— see `forms/` for details._"
|
||
rows = ["| Bits | Field | Meaning |", "| --- | --- | --- |"]
|
||
for start, end, name, notes in layout:
|
||
span = f"{start}" if start == end else f"{start}–{end}"
|
||
rows.append(f"| {span} | `{name}` | {notes} |")
|
||
return "\n".join(rows)
|