romdev-mcp 0.1.1

package/src/host/cpu-state.js

@@ -0,0 +1,422 @@
+// Cross-platform CPU register extraction.
+//
+// Implementation strategy: parse the libretro core's serialize_state blob.
+// Each core has a well-known savestate format; we locate the CPU register
+// block by its sentinel tag and decode the fields per-core.
+//
+// This avoids per-core retro_get_memory_data patches just for CPU regs and
+// works for every core that supports serialize_state (which is all of them
+// in our bundle).
+
+import { findSnes9xBlock } from "./snes9x-state.js";
+import { decodeGenesisM68k } from "./gpgx-state.js";
+
+/**
+ * Decode the SNES 65816 CPU register block from a snes9x savestate.
+ * Field order per src/snapshot.cpp SnapRegisters[]:
+ *   PB(u8), DB(u8), P.W(u16), A.W(u16), D.W(u16), S.W(u16), X.W(u16),
+ *   Y.W(u16), PCw(u16) — all uint16s big-endian per FreezeStruct.
+ *
+ * @param {Uint8Array} state
+ * @returns {ReturnType<typeof formatCpuState> | null}
+ */
+function decodeSnes9xCPU(state) {
+  const off = findSnes9xBlock(state, "REG");
+  if (off < 0) return null;
+  const u16be = (o) => (state[o] << 8) | state[o + 1];
+  const PB = state[off + 0];
+  const DB = state[off + 1];
+  const P  = u16be(off + 2);
+  const A  = u16be(off + 4);
+  const D  = u16be(off + 6);
+  const S  = u16be(off + 8);
+  const X  = u16be(off + 10);
+  const Y  = u16be(off + 12);
+  const PC = u16be(off + 14);
+  // P flags (low 8 bits, native mode):
+  // N V M X D I Z C
+  const p8 = P & 0xFF;
+  return formatCpuState({
+    pc: (PB << 16) | PC,
+    registers: { A, X, Y, D, S, DB, PB, P },
+    flags: {
+      N: !!(p8 & 0x80),
+      V: !!(p8 & 0x40),
+      M: !!(p8 & 0x20), // memory/accumulator width (1 = 8-bit)
+      X: !!(p8 & 0x10), // index width (1 = 8-bit)
+      D: !!(p8 & 0x08),
+      I: !!(p8 & 0x04),
+      Z: !!(p8 & 0x02),
+      C: !!(p8 & 0x01),
+    },
+    sp: S,
+  });
+}
+
+/**
+ * @typedef {Object} CPUState
+ * @property {number} pc Program counter (24-bit on 65816)
+ * @property {Record<string, number>} registers
+ * @property {Record<string, boolean>} flags
+ * @property {number} sp Stack pointer
+ */
+
+function formatCpuState(s) {
+  // Pass-through helper so future per-platform decoders share one shape.
+  return s;
+}
+
+/**
+ * Decode the SPC700 CPU state from snes9x's "SND" block.
+ *
+ * SND block layout (per snes9x src/apu/bapu/smp/smp_state.cpp save_state):
+ *   [0x10000]  apuram (64 KB)
+ *   [4 LE]     clock
+ *   [4 LE]     opcode_number
+ *   [4 LE]     opcode_cycle
+ *   [4 LE]     regs.pc        ← what we want
+ *   [4 LE]     regs.sp
+ *   [4 LE]     regs.B.a
+ *   [4 LE]     regs.x
+ *   [4 LE]     regs.B.y
+ *   [4 LE × 8] regs.p.{n,v,p,b,h,i,z,c}   each as 32-bit bool
+ *   ...
+ * Each field is INT32(...) = set_le32 = 4-byte little-endian.
+ *
+ * @param {Uint8Array} state
+ * @returns {ReturnType<typeof formatCpuState> | null}
+ */
+function decodeSnes9xSPC(state) {
+  const off = findSnes9xBlock(state, "SND");
+  if (off < 0) return null;
+  // The block starts with 64KB of ARAM, then 3 INT32s before PC.
+  const u32le = (o) => state[o] | (state[o + 1] << 8) | (state[o + 2] << 16) | (state[o + 3] << 24);
+  let p = off + 0x10000; // skip apuram
+  p += 4; // skip clock
+  p += 4; // skip opcode_number
+  p += 4; // skip opcode_cycle
+  const pc = u32le(p) & 0xFFFF;            p += 4;
+  const sp = u32le(p) & 0xFF;              p += 4;
+  const a  = u32le(p) & 0xFF;              p += 4;
+  const x  = u32le(p) & 0xFF;              p += 4;
+  const y  = u32le(p) & 0xFF;              p += 4;
+  const n  = !!u32le(p);                   p += 4;
+  const v  = !!u32le(p);                   p += 4;
+  const pf = !!u32le(p);                   p += 4; // direct page select (p flag)
+  const b  = !!u32le(p);                   p += 4;
+  const h  = !!u32le(p);                   p += 4;
+  const i  = !!u32le(p);                   p += 4;
+  const z  = !!u32le(p);                   p += 4;
+  const c  = !!u32le(p);                   p += 4;
+  return formatCpuState({
+    pc,
+    registers: { A: a, X: x, Y: y, SP: sp, YA: (y << 8) | a },
+    flags: { N: n, V: v, P: pf, B: b, H: h, I: i, Z: z, C: c },
+    sp,
+  });
+}
+
+/**
+ * Decode fceumm's X6502 struct from the nes_cpu_regs region (snapshot
+ * of the live struct memcpy'd into a stable buffer by our patch).
+ *
+ * Struct layout (28 bytes, wasm32 default alignment):
+ *   [0..3]   int32_t  tcount  (temporary cycle counter)
+ *   [4..5]   uint16_t PC
+ *   [6]      uint8_t  A
+ *   [7]      uint8_t  X
+ *   [8]      uint8_t  Y
+ *   [9]      uint8_t  S      (stack pointer; SP = 0x100 | S)
+ *   [10]     uint8_t  P      (NV-BDIZC flag register)
+ *   [11]     uint8_t  mooPI  (previous interrupt mask — fceumm internal)
+ *   [12]     uint8_t  jammed (illegal-opcode lock state)
+ *   [13..15] padding
+ *   [16..19] int32_t  count  (cycles remaining in slice)
+ *   [20..23] uint32_t IRQlow (pending IRQ source bitmask)
+ *   [24]     uint8_t  DB     (data bus latch)
+ *   [25..27] padding
+ *
+ * @param {Uint8Array} bytes 28-byte snapshot
+ * @returns {ReturnType<typeof formatCpuState> | null}
+ */
+function decode6502(bytes) {
+  if (!bytes || bytes.length < 25) return null;
+  const u16le = (o) => bytes[o] | (bytes[o + 1] << 8);
+  const u32le = (o) => (bytes[o] | (bytes[o + 1] << 8) | (bytes[o + 2] << 16) | (bytes[o + 3] << 24)) >>> 0;
+  const PC = u16le(4);
+  const A  = bytes[6];
+  const X  = bytes[7];
+  const Y  = bytes[8];
+  const S  = bytes[9];
+  const P  = bytes[10];
+  const tcount = u32le(0) | 0;
+  const count  = u32le(16) | 0;
+  const IRQlow = u32le(20);
+  const DB     = bytes[24];
+  const jammed = !!bytes[12];
+  // 6502 P flags: N V - B D I Z C  (bit 5 unused / always reads 1)
+  return formatCpuState({
+    pc: PC,
+    registers: { A, X, Y, S, P, DB, IRQlow, tcount, count },
+    flags: {
+      N: !!(P & 0x80),
+      V: !!(P & 0x40),
+      B: !!(P & 0x10),
+      D: !!(P & 0x08),
+      I: !!(P & 0x04),
+      Z: !!(P & 0x02),
+      C: !!(P & 0x01),
+      jammed,
+    },
+    sp: 0x100 | S,
+  });
+}
+
+/**
+ * Decode the Z80 CPU state from gpgx's `Z80_Regs` struct.
+ *
+ * Struct layout (little-endian, PAIR = 4 bytes union: byte 0 = L, byte 1 = H):
+ *   offset 0-3:   pc
+ *           4-7:  sp
+ *           8-11: af  (A at byte 9, F at byte 8)
+ *          12-15: bc  (B at 13, C at 12)
+ *          16-19: de  (D at 17, E at 16)
+ *          20-23: hl  (H at 21, L at 20)
+ *          24-27: ix
+ *          28-31: iy
+ *          32-35: wz  (memptr — internal)
+ *          36-39: af2 (shadow)
+ *          40-43: bc2
+ *          44-47: de2
+ *          48-51: hl2
+ *          52:    r
+ *          53:    r2
+ *          54:    iff1
+ *          55:    iff2
+ *          56:    halt
+ *          57:    im
+ *          58:    i
+ *          59-62: nmi_state, nmi_pending, irq_state, after_ei
+ *
+ * F flag bits (Z80 standard): SZ5H3PNC
+ *   bit 7 S  — sign
+ *   bit 6 Z  — zero
+ *   bit 5 Y  — undocumented
+ *   bit 4 H  — half-carry
+ *   bit 3 X  — undocumented
+ *   bit 2 PV — parity/overflow
+ *   bit 1 N  — add/subtract
+ *   bit 0 C  — carry
+ *
+ * @param {Uint8Array} bytes
+ * @returns {CPUState}
+ */
+function decodeZ80(bytes) {
+  const w = (off) => bytes[off] | (bytes[off + 1] << 8);
+  const pc = w(0);
+  const sp = w(4);
+  const af = w(8);
+  const bc = w(12);
+  const de = w(16);
+  const hl = w(20);
+  const ix = w(24);
+  const iy = w(28);
+  const af2 = w(36);
+  const bc2 = w(40);
+  const de2 = w(44);
+  const hl2 = w(48);
+  const r = bytes[52];
+  const r2 = bytes[53];
+  const iff1 = bytes[54];
+  const iff2 = bytes[55];
+  const halt = bytes[56];
+  const im = bytes[57];
+  const i = bytes[58];
+
+  const f = af & 0xFF;
+  const a = (af >> 8) & 0xFF;
+
+  return {
+    pc,
+    sp,
+    registers: {
+      A: a,
+      F: f,
+      B: (bc >> 8) & 0xFF,
+      C: bc & 0xFF,
+      D: (de >> 8) & 0xFF,
+      E: de & 0xFF,
+      H: (hl >> 8) & 0xFF,
+      L: hl & 0xFF,
+      AF: af,
+      BC: bc,
+      DE: de,
+      HL: hl,
+      IX: ix,
+      IY: iy,
+      AF_shadow: af2,
+      BC_shadow: bc2,
+      DE_shadow: de2,
+      HL_shadow: hl2,
+      I: i,
+      R: (r & 0x7F) | (r2 & 0x80),  // refresh — H bit from r2, low 7 from r
+    },
+    flags: {
+      S: !!(f & 0x80),
+      Z: !!(f & 0x40),
+      H: !!(f & 0x10),
+      PV: !!(f & 0x04),
+      N: !!(f & 0x02),
+      C: !!(f & 0x01),
+      raw: "0x" + f.toString(16).toUpperCase().padStart(2, "0"),
+    },
+    interrupts: {
+      iff1: !!iff1,
+      iff2: !!iff2,
+      mode: im,
+      halted: !!halt,
+    },
+  };
+}
+
+/**
+ * Get the running core's CPU state in a generic shape.
+ * Dispatches per-platform + per-CPU; returns null when not supported.
+ *
+ * @param {import("./LibretroHost.js").LibretroHost} host
+ * @param {string} platform
+ * @param {string} [cpu] "main" (default) or "spc700" for SNES
+ * @returns {CPUState | null}
+ */
+export function getCPUState(host, platform, cpu = "main") {
+  if (platform === "nes") {
+    const bytes = host.readMemory("nes_cpu_regs", 0, 28);
+    return decode6502(bytes);
+  }
+  if (platform === "snes") {
+    const state = host.serializeState();
+    if (cpu === "spc700") return decodeSnes9xSPC(state);
+    return decodeSnes9xCPU(state); // 65816
+  }
+  if (platform === "genesis") {
+    if (cpu === "z80") {
+      // gpgx runs ONE Z80 core for both SMS and Genesis — the global `Z80`
+      // struct the patch snapshots for the `sms_z80_regs` region (id 0x133)
+      // IS the Genesis sound Z80 when a Genesis ROM is loaded. So the same
+      // region + decoder works here; no separate genesis_z80_regs needed.
+      // (The Z80 is held in reset until the 68k releases it via $A11100/
+      // $A11200 — a freshly-booted ROM may show PC=0 / all-zero regs.)
+      const bytes = host.readMemory("sms_z80_regs", 0, 63);
+      return decodeZ80(bytes);
+    }
+    // Default "main" → m68k. The gpgx region exposes the live struct;
+    // we know the offsets from m68k.h (see gpgx-state.js comments).
+    const SIZE = 5560; // m68ki_cpu_core size on wasm32 (libretro+jmp_buf)
+    const bytes = host.readMemory("genesis_m68k", 0, SIZE);
+    return decodeGenesisM68k(bytes);
+  }
+  if (platform === "sms" || platform === "gg") {
+    // gpgx exposes the live Z80_Regs struct via sms_z80_regs.
+    // sizeof(Z80_Regs) on wasm32 ≈ 60 + 4 (cycles) + 12 (daisy ptr + irq cb)
+    // We only read the first 63 bytes (everything up through interrupt state).
+    const bytes = host.readMemory("sms_z80_regs", 0, 63);
+    return decodeZ80(bytes);
+  }
+  if (platform === "atari2600") {
+    const b = host.readMemory("a26_cpu_regs", 0, 7);
+    const pc = b[0] | (b[1] << 8);
+    const p = b[5];
+    return {
+      pc,
+      sp: 0x100 | b[6],
+      registers: { A: b[2], X: b[3], Y: b[4], P: p, SP: b[6] },
+      flags: {
+        N: !!(p & 0x80), V: !!(p & 0x40), B: !!(p & 0x10), D: !!(p & 0x08),
+        I: !!(p & 0x04), Z: !!(p & 0x02), C: !!(p & 0x01),
+        raw: "0x" + p.toString(16).toUpperCase().padStart(2, "0"),
+      },
+    };
+  }
+  if (platform === "atari7800") {
+    const b = host.readMemory("a78_cpu_regs", 0, 7);
+    const pc = b[0] | (b[1] << 8);
+    const p = b[5];
+    return {
+      pc,
+      sp: 0x100 | b[6],
+      registers: { A: b[2], X: b[3], Y: b[4], P: p, SP: b[6] },
+      flags: {
+        N: !!(p & 0x80), V: !!(p & 0x40), B: !!(p & 0x10), D: !!(p & 0x08),
+        I: !!(p & 0x04), Z: !!(p & 0x02), C: !!(p & 0x01),
+        raw: "0x" + p.toString(16).toUpperCase().padStart(2, "0"),
+      },
+    };
+  }
+  if (platform === "c64") {
+    const b = host.readMemory("c64_cpu_regs", 0, 7);
+    const pc = b[0] | (b[1] << 8);
+    const p = b[5];
+    // IO port at $0001 controls KERNAL/BASIC/CHAR-ROM banking. We read it
+    // from mem_ram[1], which is the underlying RAM cell. The EFFECTIVE
+    // port value lives in vice's pport.data_out struct (not exposed yet)
+    // and may differ from mem_ram[1] depending on DDR bits at mem_ram[0].
+    // Most agents care about the banking state — for that, the effective
+    // value matters more; we expose mem_ram[1] as a useful approximation.
+    const ioPort = host.readMemory("system_ram", 1, 1)[0];
+    return {
+      pc,
+      sp: 0x100 | b[6],
+      registers: { A: b[2], X: b[3], Y: b[4], P: p, SP: b[6] },
+      flags: {
+        N: !!(p & 0x80), V: !!(p & 0x40), B: !!(p & 0x10), D: !!(p & 0x08),
+        I: !!(p & 0x04), Z: !!(p & 0x02), C: !!(p & 0x01),
+        raw: "0x" + p.toString(16).toUpperCase().padStart(2, "0"),
+      },
+      ioPort: {
+        raw: "0x" + ioPort.toString(16).toUpperCase().padStart(2, "0"),
+        loram:    !!(ioPort & 0x01),  // BASIC ROM visible at $A000-$BFFF
+        hiram:    !!(ioPort & 0x02),  // KERNAL ROM visible at $E000-$FFFF
+        charen:   !!(ioPort & 0x04),  // 0 = char ROM at $D000, 1 = I/O at $D000
+        cassetteWrite: !!(ioPort & 0x08),
+        cassetteSwitch: !!(ioPort & 0x10),
+        cassetteMotor: !!(ioPort & 0x20),
+      },
+    };
+  }
+  if (platform === "gb" || platform === "gbc") {
+    // Patched gambatte exposes an 18-byte SM83 snapshot. Inline decoder
+    // — see src/platforms/gb/ppu.js#decodeSm83State for the doc'd layout.
+    const bytes = host.readMemory("gb_cpu_regs", 0, 18);
+    const u16 = (off) => bytes[off] | (bytes[off + 1] << 8);
+    const a = bytes[4], f = bytes[5];
+    const b = bytes[6], c = bytes[7];
+    const d = bytes[8], e = bytes[9];
+    const h = bytes[10], l = bytes[11];
+    return {
+      pc: u16(0),
+      sp: u16(2),
+      registers: {
+        A: a, F: f,
+        B: b, C: c,
+        D: d, E: e,
+        H: h, L: l,
+        AF: (a << 8) | f,
+        BC: (b << 8) | c,
+        DE: (d << 8) | e,
+        HL: (h << 8) | l,
+      },
+      flags: {
+        Z: !!(f & 0x80),
+        N: !!(f & 0x40),
+        H: !!(f & 0x20),
+        C: !!(f & 0x10),
+        raw: "0x" + f.toString(16).toUpperCase().padStart(2, "0"),
+      },
+      interrupts: {
+        ime: !!bytes[12],
+        halted: !!bytes[13],
+      },
+    };
+  }
+  return null;
+}

package/src/host/dsp-state.js

@@ -0,0 +1,188 @@
+// SNES S-DSP state introspection.
+//
+// Per the rom-games agent's audio-debugging asks: distinguish "voice
+// never produced output" (BRR/envelope issue) from "voice produced
+// output but mixer muted it" (master volume issue). The data lives in
+// the savestate's "SND" block, AFTER the SMP::save_state region. We
+// parse it the same way as cpu-state.js parses the SMP block.
+//
+// SND block layout (cumulative):
+//   [0x10000]                      apuram (SMP::save_state)
+//   [4 × 14 = 56 bytes]            SMP regs (clock + opcode + PC + SP + A + X + Y + 8 P flags)
+//   [...status + timer fields...]
+//   [DSP::save_state begins here]
+//     [128 bytes]                  m.regs (DSP register file)
+//     [per voice × 8]
+//       [12 × int16 = 24 bytes]    v.buf (BRR sample ring)
+//       [uint16]                   v.interp_pos
+//       [uint16]                   v.brr_addr
+//       [uint16]                   v.env       ← THE KEY FIELD
+//       [int16]                    v.hidden_env
+//       [uint8]                    v.buf_pos
+//       [uint8]                    v.brr_offset
+//       [uint8]                    v.kon_delay
+//       [uint8]                    v.env_mode
+//       [uint8]                    v.t_envx_out
+//       [extra: 1 byte N + N bytes pad]
+//     [...echo history, misc...]
+//
+// All multi-byte fields are little-endian (host byte order on wasm32).
+// SPC_DSP::copy_state uses memcpy (no endian flip).
+
+import { findSnes9xBlock } from "./snes9x-state.js";
+
+// Where the DSP block starts within "SND", measured from the start of
+// the SMP region. Sum of every INT32(...) call in SMP::save_state:
+//   apuram(0x10000) + clock(4) + opcode_number(4) + opcode_cycle(4)
+//   + pc(4) + sp(4) + a(4) + x(4) + y(4)
+//   + p.n/v/p/b/h/i/z/c (8 × 4 = 32)
+//   + iplrom_enable(4) + dsp_addr(4)
+//   + ram00f8(4) + ram00f9(4)
+//   + timer0.{enable,target,stage1,stage2,stage3} (5 × 4 = 20)
+//   + timer1 (5 × 4 = 20)
+//   + timer2 (5 × 4 = 20)
+//   + rd(4) + wr(4) + dp(4) + sp(4) + ya(4) + bit(4) = 24
+const SMP_BLOCK_BYTES =
+  0x10000 + // apuram
+  3 * 4 +   // clock + opcode_number + opcode_cycle
+  5 * 4 +   // pc + sp + a + x + y
+  8 * 4 +   // p flags (n v p b h i z c)
+  4 * 4 +   // iplrom_enable + dsp_addr + ram00f8 + ram00f9
+  3 * 5 * 4 + // 3 timers × 5 fields
+  6 * 4;    // rd + wr + dp + sp + ya + bit
+
+/**
+ * Decode SNES S-DSP voice state + key register slices.
+ *
+ * @param {Uint8Array} state full savestate buffer
+ * @returns {{
+ *   regs: Uint8Array,                       // 128-byte DSP register file
+ *   masterVolume: { l: number, r: number }, // signed -128..127
+ *   echoVolume: { l: number, r: number },
+ *   flg: number,                            // FLG register: bit 6 = mute, bit 7 = reset
+ *   kon: number,                            // last KON write (bitmask of voices keyed on)
+ *   koff: number,                           // last KOFF write
+ *   endx: number,                           // ENDX (voices whose samples have ended)
+ *   voices: Array<{
+ *     slot: number,
+ *     vol: { l: number, r: number },        // signed -128..127
+ *     pitch: number,                        // 14-bit unsigned
+ *     srcn: number,                         // sample directory index
+ *     adsr: { adsr1: number, adsr2: number },
+ *     gain: number,
+ *     envx: number,                         // RAW DSP register (snapshot at last sample)
+ *     outx: number,                         // RAW DSP register (snapshot)
+ *     env: number,                          // INTERNAL envelope value (gates output)
+ *     hiddenEnv: number,                    // ADSR rate counter / GAIN internal
+ *     envMode: number,                      // 0=release, 1=attack, 2=decay, 3=sustain
+ *     bufLastSamples: number[],             // last 12 BRR-decoded samples (int16)
+ *     bufPos: number,
+ *   }>
+ * } | null}
+ */
+export function decodeSnes9xDSP(state) {
+  const off = findSnes9xBlock(state, "SND");
+  if (off < 0) return null;
+  let p = off + SMP_BLOCK_BYTES;
+
+  // DSP register file (128 bytes)
+  const regs = state.slice(p, p + 128);
+  p += 128;
+
+  // 8 voices
+  const voices = [];
+  for (let i = 0; i < 8; i++) {
+    const bufStart = p;
+    const bufLastSamples = [];
+    for (let j = 0; j < 12; j++) {
+      const lo = state[bufStart + j * 2];
+      const hi = state[bufStart + j * 2 + 1];
+      // Sign-extend 16-bit
+      const u = lo | (hi << 8);
+      bufLastSamples.push(u >= 0x8000 ? u - 0x10000 : u);
+    }
+    p += 24;
+    const interpPos = state[p] | (state[p + 1] << 8); p += 2;
+    const brrAddr = state[p] | (state[p + 1] << 8); p += 2;
+    const env = state[p] | (state[p + 1] << 8); p += 2;
+    const hiddenEnvU = state[p] | (state[p + 1] << 8); p += 2;
+    const hiddenEnv = hiddenEnvU >= 0x8000 ? hiddenEnvU - 0x10000 : hiddenEnvU;
+    const bufPos = state[p++];
+    /* brrOffset */ p++;
+    /* konDelay */ p++;
+    const envMode = state[p++];
+    /* t_envx_out */ p++;
+    // copier.extra(): uint8 N then N bytes pad
+    const extraN = state[p++];
+    p += extraN;
+
+    // Voice DSP regs: base = voice<<4, fields:
+    //   $X0 VOLL, $X1 VOLR, $X2 PITCHL, $X3 PITCHH, $X4 SRCN,
+    //   $X5 ADSR1, $X6 ADSR2, $X7 GAIN, $X8 ENVX, $X9 OUTX
+    const base = i << 4;
+    const vol = {
+      l: regs[base] > 0x7F ? regs[base] - 256 : regs[base],
+      r: regs[base + 1] > 0x7F ? regs[base + 1] - 256 : regs[base + 1],
+    };
+    const pitch = regs[base + 2] | ((regs[base + 3] & 0x3F) << 8);
+    voices.push({
+      slot: i,
+      vol,
+      pitch,
+      srcn: regs[base + 4],
+      adsr: { adsr1: regs[base + 5], adsr2: regs[base + 6] },
+      gain: regs[base + 7],
+      envx: regs[base + 8],
+      outx: regs[base + 9],
+      env,
+      hiddenEnv,
+      envMode,
+      bufLastSamples,
+      bufPos,
+    });
+    // Discard interpPos, brrAddr — agent rarely needs them; available
+    // via savestate if they do.
+  }
+
+  // CAREFUL: the DSP register file (m.regs) holds the LAST VALUE WRITTEN
+  // to each address, not necessarily a useful runtime state. Reading
+  // regs[KON] tells you "what KON byte the driver wrote most recently",
+  // not "which voices are currently keying on" — the DSP consumes KON
+  // every sample and clears its internal new_kon shadow. Same for KOFF.
+  // ENDX is special: the DSP auto-clears regs[ENDX] on every write
+  // regardless of the data byte.
+  //
+  // Surface these as `regs4C` / `regs5C` / `regs7C` (raw byte names)
+  // rather than `kon` / `koff` / `endx` (state names) so callers don't
+  // mistake the byte for a live interpretation. Field names are still
+  // memorable (the address IS the canonical DSP register name) but
+  // semantically honest about what you're reading.
+  //
+  // Source: snes9x/src/apu/bapu/dsp/SPC_DSP.h r_* constants; .cpp KON/
+  // ENDX special-case write handling at lines 285-291.
+  return {
+    regs,
+    masterVolume: {
+      l: regs[0x0C] > 0x7F ? regs[0x0C] - 256 : regs[0x0C],
+      r: regs[0x1C] > 0x7F ? regs[0x1C] - 256 : regs[0x1C],
+    },
+    echoVolume: {
+      l: regs[0x2C] > 0x7F ? regs[0x2C] - 256 : regs[0x2C],
+      r: regs[0x3C] > 0x7F ? regs[0x3C] - 256 : regs[0x3C],
+    },
+    flg: regs[0x6C], // bit 6 = mute, bit 7 = reset — direct register, no shadow
+    regs4C: regs[0x4C], // last KON write (not "currently keying on" — DSP consumes per sample)
+    regs5C: regs[0x5C], // last KOFF write
+    regs7C: regs[0x7C], // ENDX register — auto-cleared by DSP on every write
+    voices,
+  };
+}
+
+/**
+ * @param {import("./LibretroHost.js").LibretroHost} host
+ * @param {string} platform
+ */
+export function getDspState(host, platform) {
+  if (platform !== "snes") return null;
+  return decodeSnes9xDSP(host.serializeState());
+}