# Status & next-session handoff — end of session 1 (2026-08-23)

## Decisions locked

| decision | value | why |
|---|---|---|
| Target CPU | 68000 @ 10MHz (stock) | hardest honest constraint |
| Display mode | 256 colors, 256x192 in 256x256 CRTC mode | every mode is 1 word-access/pixel, so 256c is free vs 16c |
| Double buffer | **none** — page 1 sacrificed | enables `movem.l` 24px bursts; delta coding needs a RAM reference frame anyway |
| Codec | 4x4 vector quantization, per-scene codebook + block delta | CPU is idle, I/O is the ceiling — spend cycles to buy bandwidth |
| Framerate | 12 fps, **explicit decimation** | source has zero duplicate frames; no free "twos" win |
| Medium | SCSI HDD image (.hds) | but see SASI/SCSI split below |
| Emulator | MAME 0.277 x68000 | accurate enough that measured cycles mean something |

**OPEN QUESTION for the user:** stock 10MHz machines are **SASI**, not SCSI.
Three options, not yet chosen:
1. Stock 10MHz + SASI (purist) — VQ becomes mandatory
2. Stock 10MHz + CZ-6BS1 SCSI board — relieves I/O, keeps CPU honest
3. Super/XVI baseline — built-in SCSI, still a 10MHz 68000

Recommendation: make the codec's bitrate ceiling a **build parameter**, so one
encoder serves all three and the target is chosen at package time.

---

## Working setup

**MAME ROMs** — `~/mame/roms/x68000.zip` (present, working).
Must pass **`-bios ipl10`**; the default BIOS is `cz600ce`, whose split
even/odd IPL halves (`rh-ix0897cezz.ic12` / `rh-ix0898cezz.ic11`) are absent.
`-verifyroms` will still report those two as missing — this is expected and harmless.

Boots headless at ~430-480% speed:
```
mame x68000 -bios ipl10 -video none -sound none -nothrottle -seconds_to_run 3
```

**Assembler** — vasm built from source, binary at `tools/vasm/vasmm68k_mot`
(source tarball alongside it). Verified correct 68000 output.
```
tools/vasm/vasmm68k_mot -Fbin -o out.bin in.s
```

**Blu-ray** — mount with:
```
udisksctl loop-setup -r -f DRAGONS_LAIR.iso     # -> /media/reala-misaki/BDROM
```
NOTE: this loop mount is still active from session 1. Re-mount if the machine rebooted.

---

## MAME Lua harness — WORKING, reusable

`tools/bench/*.lua` inject 68000 machine code straight into emulated RAM and time
it against the emulated clock. No bootable disk or OS required. This is the
measurement rig for all future cycle-cost work (blit timing, decoder benchmarks).

Pattern:
```
mame x68000 -bios ipl10 -video none -sound none -nothrottle \
     -seconds_to_run 30 -plugins -autoboot_script yourscript.lua
```

### Three MAME Lua gotchas — all cost real time, all now solved
1. **Retain the notifier subscription.** `emu.add_machine_frame_notifier()` returns
   a token; if you drop it into a chunk-local it is garbage-collected and the
   callback **silently stops firing**. Assign it to a **global** (`SUB = ...`).
2. **The stack pointer is `SP`, not `A7`** in `cpu.state[...]`.
   Full list: A0-A6, D0-D7, PC, SP, SR, USP, CURPC, CURFLAGS, IR.
3. **`autoboot_script` fires at time=0, before boot** (PC=0). Wait until
   `machine.time` >= ~5s before injecting, or IOCS is not yet initialised.

Also: piping MAME through `grep` block-buffers output — write raw to a file when
backgrounding, or you will see an empty log and assume a hang.
And never `pkill -f 'mame x68000'` — the pattern matches your own shell and kills it
(exit 144). Use `pkill -x mame`.

---

## BLOCKED: disk throughput benchmark

**Goal:** measure real SASI/SCSI KB/s to replace the folklore figures in FINDINGS.md §5.

**Status:** harness fully working; the IOCS call itself fails.

`IOCS _B_READ` ($46 via `TRAP #15`; d1.hb=PDA, d2.l=position, d3.l=bytes, a1=buffer)
returns **`FFFFFFFF` (-1), zero reads**, uniformly across:
- all 16 PDA values $80-$8F
- both d1 encodings (PDA in bits 31-24 and bits 15-8)
- image sizes 10MB / 20MB / 40MB

The uniformity is the diagnostic: calls are **dispatched and cleanly rejected**,
so `TRAP #15` and IOCS are reachable. MAME does mount the image
(`:x68k_hdc: opened image file bench.hdf`).

**Untested hypotheses, in rough order of likelihood:**
1. The raw image has no X68000 SASI format, so the IPL's boot scan never registered
   a usable drive and IOCS refuses. Would need Human68k to format one — **we have
   no Human68k image on this system.**
2. MAME's `x68k_hdc` SASI implementation may be too partial for IOCS-level reads.
3. `SP=$8000` may put the injected stack on top of the IOCS work area in low RAM.
   Try a much higher stack.
4. The **SCSI path was never tried** — this is the obvious next move and is more
   relevant to the target anyway:
   `-exp1 cz6bs1 -hard disk.chd` with `exp1:cz6bs1:scsi:0 harddisk`
   (`-listmedia` gains a `harddisk` slot accepting .chd/.hd/.hdv/.2mg/.hdi).

**Honest assessment: this benchmark is NOT on the critical path.** The VQ codec
(~30 KB/s) is correct whether SASI does 300 or 600 KB/s. Do not let it block the
encoder. Its real value is deciding whether the *simpler* row-span codec could
have sufficed.

Caveat if resumed: MAME idealizes drive seek latency. That's acceptable because the
realistic deployment is BlueSCSI/SCSI2SD (SD-backed, no mechanical seek), so what
gets measured is the bus/DMAC/controller path — the genuine ceiling. The caveat
only bites for a real period spinning drive.

---

## Next steps, in priority order

1. **Build the VQ encoder** (`tools/encoder/`) — 4x4 blocks, per-scene codebook,
   block delta. Emit sample PNGs for visual evaluation. **The open question is
   whether VQ softens Bluth's ink linework unacceptably — decide by eye before
   committing to the architecture.**
2. **Full-disc survey** — all 224 streams, not 5s samples, to firm up bitrate
   (current numbers are +/-30%) and map streams onto the arcade scene graph.
3. **Check the SNES project's license**, then evaluate reusing `data/events/`
   (516 chapters / 29 scenes) as the scene-graph and input-timing layer.
4. Resolve the SASI/SCSI target question with the user.
5. Optionally unblock the disk benchmark via the SCSI path.
6. 68000 player skeleton: CRTC init for 256x192x256c, `movem.l` blitter,
   ADPCM via HD63450 DMA.

## Not yet started
- Any 68000 player code
- ADPCM audio extraction/encoding (MSM6258, 15.6kHz mono, ~7.8 KB/s, ~10MB for 22min)
- Disk image packaging / container format
- Game logic (scene branching, input windows, death clips)