drwily/Dragon-s-Lair-X68k
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Pace the ring, then read the DMAC config out of the IPL ROM: audio is cheap and the disk is not

Browse Source 
Two sessions that were never separated in the working tree, so they land as one
commit. check.sh ALL GREEN before and after both.

SESSION 19 -- the ring rig gets a frame clock (FINDINGS 51).

src/player/stream.s had no frame clock: it asked for record i the instant it
finished i-1, outran any finite pipe, and never let the ring back up. The 49.1
sweep passing at 48 KB was therefore a wrap-correctness result and nothing else.
PACE/PACEON ($18034/$18038) hold the decoder to 12 fps, so FR_HEAD-FR_TAIL
finally means what it reads as: whole frames the decoder could still draw with
delivery stopped dead. PACEON=0 free-runs and is what the wrap gate still uses,
so every figure in 49 is unmoved.

Paced, on the gate container: 64 KB holds 2 frames, 256 KB holds 7-8, 512 KB
holds 14-15, all pixel-exact. Tolerance is ceiling-1, measured by cutting the
pipe: 256 KB buys 500 ms of dead pipe, not 583.

SLACK IS ACCUMULATED, NOT OWNED. It is built out of pipe-wire and a seek spends
all of it. At 488 KB/s a 256 KB ring needs 4.83 s of play to reach its ceiling
from empty; 512 KB needs 8.42 s to reach 14. A bigger ring raises the ceiling
AND lengthens the climb, so a branch point does not ask "is the buffer big
enough" but "has there been enough play since the last one" -- and Dragon's
Lair's decision points are seconds apart. The rig now also says WHICH resource
is binding: at 460 KB/s every ring from 192 KB to 512 KB is rate-bound at
ceiling 4 and never fills, so larger rings are dead RAM in that scene.
20_seek_slack.py is the same model rewritten in Python from record sizes,
sharing no code with the Lua producer: 35/35 ceilings inside its bracket.

SESSION 20 -- the DMAC configuration was in the IPL ROM the whole time
(FINDINGS 52).

ROADMAP's "do this first" was to put the ADPCM stream on the bus. That needs a
clocks-per-byte figure for the audio channel, and 11_cpu_budget.py was charging
audio the DISK's rate -- 5 clk/B, its own help text calling it "single-address,
bus held". Audio was being charged the favourable end of B3, a 242 KB/s open
question.

It never had to be a guess. The IPL ROM programs all four HD63450 channels
itself and MAME boots the rig with it, so 21_iplrom_dmac.py reads the
configuration out of the image and decodes the MC68450 fields. Eight
(address, expected bytes, meaning) sites; a mismatch or an unknown revision
exits non-zero. In check.sh, no emulator, milliseconds.

ch3 DCR=$80, OCR=$32: dual address, 8-bit port, cycle steal WITHOUT hold,
REQG=10 external request. The DMAC arbitrates once per byte with no burst to
amortise the 5..8 + 2 over, so an audio byte is 16..19 clocks, not 5 -- the old
debit was 3.2x..3.8x small. And on the bus it is still nothing: 651 B/frame is
1.25%..1.48% of a frame, about 4% of what the decoder leaves. P6's bus risk
does not materialise. The unit worry was worth checking and nearly right: 15.6
kHz is 8 MHz/512 = 15,625 samples/s, two 4-bit samples to a byte = 7,812.5 B/s
exactly, and AUDIO_KBPS=7.8 is that in decimal kB while the tool multiplied by
1024.

THE DISK CHANNEL IS PROGRAMMED IDENTICALLY. ch1 (SASI) is DCR=$80 too, and so
is ch0. That is 16..19 clocks per delivered byte, where 42.4 brackets W at 5..12
and 42.5 has W=8 already missing 47/120 frames. The only worked example of a
disk DMA configuration on this machine sits above the entire bracket, and at
that price nothing fits at any container size. It is not scsiexrom.bin so B3
stays open -- what changed is that a cheap configuration is now the thing that
has to be SHOWN. W <= 12 is a requirement on the player's DMAC programming, not
a range the hardware hands us, and it is now the largest open number in the
project, ahead of the rate.

An unforced cross-check fell out: 15_bus_occupancy.py's new W sweep puts W=8 at
105.7% of the frame, agreeing with 42.5's 47/120, from mode histograms and bus
clocks respectively, two models sharing no code.

Also: ADPCM outranks the disk at the arbiter (CPR 1 against 2), so an audio byte
never waits and a video byte does -- relevant to 51's smooth-rate delivery model.

README MEDIA.

stream.lua gains DLX_SNAP_EVERY=1 (needs DLX_PACE, off by default, on no path
check.sh takes) and tools/media/make_readme_media.py turns the PNGs into
docs/img/. The stills and both clips are MAME's own screen pixels.

Building it turned up something worth recording. 116 of 119 captured frames are
pixel-exact against dlx.py; three are TORN -- frame n on top, frame n-1 below
the tear line -- because MAME captured the screen while the block loop was
partway down it. decode.s writes straight to the displayed page (one display
path, 28.1), so a real player tears the same way, and this is the first time
that consequence has been visible rather than argued. The script ASSERTS the
tear and refuses to build otherwise, rather than trimming three frames and
reporting "every frame I kept is exact". Second correction the capture forced:
the snapshot fires before frame n is decoded, so the obvious reading is that it
holds frame n-1 -- it does not, because MAME renders the screen at the end of
the machine frame, by which time the 68000 has finished frame n.

11_cpu_budget.py's "validated to within 1 pt" line is also corrected: the model
reads 2..10 pt HIGH and by more as the frame gets harder, which was already true
before either session.

src/player/decode.s is unchanged; decode.bin is still 1,296 B at the same MD5.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
This commit is contained in:
prosolis
2026-08-24 18:14:01 -07:00
parent b49bbdc939
commit 2f9f5cc995
49 changed files with 6276 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+143 -6
View File
@@ -6,6 +6,56 @@ This is fundamentally a **video codec problem**, not a game-logic problem: the
game logic is a scene table with branching input windows; the difficulty is
pushing ~22 minutes of Don Bluth animation through a 10MHz 68000.
---
## What it looks like
![Blu-ray source next to the 68000's output](docs/img/source-vs-decoded.png)
Left, the Blu-ray frame cropped to 256x192. Right, **the same frame as the
emulated 68000 actually drew it** — 256 colours out of the X68000's 65536, one
16-colour-per-4x4-block codebook, decoded by `src/player/decode.s` from the
container. Not a re-render: these are the pixels MAME had on screen, extracted
from its own snapshot. 2x nearest-neighbour, no filtering.
**The player, running.** 119 frames out of a **256 KB ring buffer on an emulated
stock 2 MB X68000**, paced to a 12 fps frame clock, streamed from a host file at
488 KB/s — `src/player/stream.s`, no Lua in the decode path. Source on the left,
the machine's screen on the right.
<video src="docs/img/player.webm" controls muted loop width="100%"></video>
[`docs/img/player.webm`](docs/img/player.webm) — 119 frames, 12 fps, VP9
116 of those 119 frames are **pixel-exact** against `tools/encoder/dlx.py`'s
reference reconstruction. The other three are **torn** — the top of the picture
is frame *n* and the bottom still holds frame *n-1*, because MAME captured the
screen while the block loop was partway down it. That is not a rig artefact:
`decode.s` writes straight to the displayed page (one display path, FINDINGS
28.1 — the dual-path plan is kept runnable as a counterexample precisely because
it corrupts frames), so a real player tears the same way.
`tools/media/make_readme_media.py` asserts the tear rather than trimming it —
every differing pixel has to come from the previous frame, or it refuses to
build.
**What the decoder is actually doing.** The same window with the block-mode map
beside it: **black = SKIP** (costs nothing, draws nothing — the previous frame
stands), **blue = V1** (one codebook index for a whole 4x4 block), **amber = V4**
(four indices), **red = RAW** (sixteen bytes verbatim). The mode mix is what
every cost table in `docs/FINDINGS.md` is really about — V4 costs 1.5x V1, and
since session 8 the mode decision is charged both bytes *and* cycles, which is
why a byte-rich profile buys its way out to RAW instead of V4.
<video src="docs/img/modes.webm" controls muted loop width="100%"></video>
[`docs/img/modes.webm`](docs/img/modes.webm) — the same 119 frames with the mode map
**Name the layer:** everything above is **emulated** (MAME 0.277 `x68000`,
`-bios ipl10`, stock 10 MHz / 2 MB), cross-checked frame-for-frame on a second
CPU core (px68k's C68K). Nothing in this project has run on real hardware yet.
---
**And the binding resource is the 68000's local BUS, not its clock.** The
decoder occupies 86.7% of it once instruction prefetch is counted, and 52 of the
53 frames that miss the 12fps budget miss it on the bus, not the CPU
@@ -15,11 +65,60 @@ The **literal span with a fine tail** (v7) is now IN the player: `decode.s`
paints it, pixel-exact under both CPU cores, and it costs inside the decoder
what `blit.s` said it would to 0.2% (FINDINGS 41).
**It only pays if the stream is allowed to run near the pipe.** Spans buy the
68000's deadline with bytes, and at the 280 KB/s profile the mode decision has
already spent them: 77/120 frames over budget against 86 without spans. Given
the full 488 KB/s pipe it is **34/120, and 0.36 dB better** — so the next
decision is a rate point, not an optimisation (FINDINGS 41.2, docs/STATUS.md).
**The delivery path is built and tested too** (FINDINGS 49). `src/player/stream.s`
decodes the whole 120-frame window **out of a 256 KB ring on a stock 2 MB
machine**, final frame pixel-exact, with the container in a host file rather than
preloaded into RAM. The constraint turned out to be **contiguity, not byte
count** — the block loop reads with a monotonically increasing `a0` and no bounds
check, so the ring needs the whole next record resident *and contiguous*, which
is a condition no byte-counting buffer simulation can see.
**And building it caught a live defect**, then cost the project a constant.
The shipping candidate is 496.7 KB/s; the pipe figure the design had been
simulated against since session 2 was smaller, and nothing in the tree was
comparing the two — the rate controller binds on clocks and has no pipe term at
all, while the buffer sizing kept standing on a constant the design had stopped
enforcing.
**So the pipe constant is retired (session 18, USER DECISION).** It was never a
bus measurement — user-supplied, no provenance, 10% of SCSI-1's asynchronous
rating (FINDINGS 42.1). It is gone as a default from every analysis tool and
from `stream.lua`; `--bus` / `--kbps` / `DLX_STREAM_KBPS` are now **required
arguments**, so no table can be scored against a rate its own output does not
state. **There is no working delivery figure, and that is the honest state.**
What replaces it is a requirement rather than a constant:
`tools/analysis/19_ring_stream.py` reports the **zero-prefill pipe**, the rate a
medium must clear for a container to need no prefill. For the candidate that is
**513.2 KB/s** — a hardware acceptance test to measure a BlueSCSI against.
**Bytes are not free, and the number that said they were was in the wrong
unit.** Session 13 found the pipe figure the design was built against was never
a bus figure (SCSI-1 is 1.5 MB/s asynchronous) and concluded the span pass
saturates at ~837 KB/s, 0/120 frames over budget. Session 14 found the disk
debit behind that was charged **per word of stream to a byte-wide port** — the
MB89352 is an 8-bit SPC, so the DMAC pays per BYTE, and the debit is 2x every
table since FINDINGS 5. No 68000 bus cycle is shorter than four clocks, so the
old figure was below a physical floor.
**What survives, re-encoded honestly: 496.7 KB/s at 29.19 dB, 1 frame of 120
over the 12fps budget** — and that one is frame 0, the intra frame, late on
purpose. The remaining lever is not ours: **whether the CZ-6BS1 wires the SPC's
DACK to the bus's `#EXACK`**, which decides 5 clocks/byte against 9, and with
it 242 KB/s and 0.69 dB. Read FINDINGS 43 before quoting any rate figure.
**And session 20 read the answer the machine already had.** The X68000's IPL ROM
programs all four HD63450 channels itself, and MAME boots the rig with it, so
`tools/analysis/21_iplrom_dmac.py` decodes the configuration straight out of the
image and gates on the bytes still being there. The audio channel is
dual-address, 8-bit port, cycle steal **without hold**, one external request per
byte: **16..19 clocks a byte, not 5** — which prices the ADPCM stream at
1.25%..1.48% of a frame and closes ROADMAP's "do this first" item. The disk
channel is programmed **identically**. That is 16..19 clocks per delivered byte,
above the whole 5..12 bracket the project costs the transport in, and at that
price nothing fits. It is SASI and not the MB89352, so it does not settle the
question — but **a cheap configuration is now the thing that has to be shown,
not the thing assumed.** FINDINGS 52.
**Green-light check:** `./tools/bench/check.sh` (~3 min, needs the Blu-ray
mounted) re-runs both display regression tests, the rate-control drift test, the
@@ -33,6 +132,9 @@ display-path coherency counterexample and a 120-frame 68000 decode, then prints
- **`docs/STATUS.md`** — current state, working setup, blockers, next steps.
**Start here.** It also lists what has been explicitly abandoned, so old ideas
do not get re-proposed.
- **`docs/ROADMAP.md`** — the remaining work to a completion target, and which
milestone that target is. Read it with STATUS, not instead of it: STATUS holds
the measurements, ROADMAP holds the shape and goes stale first.
- **`docs/BENCHMARK.md`** — how to measure the storage subsystem, and why a
bandwidth figure out of MAME would be meaningless.
- **`docs/HARDWARE.md`** — X68000 GVRAM/CRTC reference.
@@ -70,6 +172,17 @@ tools/analysis/ measurement scripts, numbered in the order they were written
emitted too few spans to have tested anything. 17 prices the
spans the encoder ACTUALLY emitted, with no selection model,
which is what 12 and 14 could only simulate.
18 measures what a 16-colour text-plane literal would cost in
dB, and closes that direction (FINDINGS 46.3).
19 is the RING-BUFFER simulation, and it supersedes 09_buffer_
sim.py's question rather than repeating it: it models the ring's
ADDRESSES, because src/player/ needs each record contiguous and
not merely resident. It reports the ZERO-PREFILL PIPE -- the
rate a medium must clear for a container to need no prefill --
and warns explicitly when demand exceeds supply on the MEAN,
where a "required prefill" figure would flatter a sustained
overrun. Its wrap count and hole size match tools/bench/
stream.lua's, measured on a real 68000, to the digit.
buscost.py is the shared bus-cycle table both import; the
per-BLOCK constants live in tools/encoder/vq_hybrid.py and are
imported, never copied (session 12 corrected one of them).
@@ -90,6 +203,12 @@ tools/bench/ MAME Lua injection harness + 68000 benchmark sources.
and R20 — do not write CRTC values anywhere else.
`prep_dlx.py`/`decode.lua`/`verify_decode.py` load, time and
verify `src/player/decode.s`; the verify pass is in check.sh.
`prep_stream.py`/`stream.lua` do the same for `stream.s`, but
lay the container out as a DISK in a host file and feed it
through a bounded ring at a modelled pipe rate -- so the rig is
no longer bounded by the emulated machine's RAM, and a stock
2 MB machine runs the whole window. `dlxload.py` holds the
codebook/palette load-time maths both preps share.
tools/bench/c68k/ headless px68k C68K harness -- a SECOND emulator for every
68000 cycle figure (FINDINGS 37). Links only px68k's CPU core:
no SDL, no ROMs, no emulated machine. `make PX68K=~/src/px68k`
@@ -107,7 +226,13 @@ tools/encoder/ hybrid VQ encoder + DLX3 container writer (working).
DLX2 4-byte-aligns every frame record: an odd `move.l` is an
ADDRESS ERROR on a 68000, not a slow read (FINDINGS 28.3).
dlx.py is the reference DECODER -- ground truth for the 68000.
src/player/ decode.s: the 68000 DLX3 decoder. Pixel-exact under MAME and
src/player/ decode.s: the 68000 DLX3 decoder, PRELOADED-stream front-end.
stream.s: the same decoder behind a bounded RING (FINDINGS 49).
Both include frame.i (the block loop and span chain) and geom.i
(the constants) so there is exactly ONE copy of the bytes every
cycle constant in FINDINGS 24/30/40/41 is fitted to. check.sh
asserts decode.s still assembles to the same 1,296 bytes.
decode.s: the 68000 DLX3 decoder. Pixel-exact under MAME and
px68k's C68K core, blocks and v7 literal spans both. The span
pass is blit.s v7 verbatim -- the same instruction sequence the
66.0/9.143/9.978 fit was measured on, so do not tidy it.
@@ -140,6 +265,18 @@ The profile bitrate is a **ceiling**: lam is bisected per frame under a leaky
bucket, so the profile's `lam` is a quality floor rather than a setting
(`--fixed-lam` opts out).
**But at `--spans all` none of that binds.** A 32-frame bucket emits the same
container byte for byte as an 8-frame one, and `lam` never leaves its floor on
any frame of the reference window: the rate is set by the span pass and by `mu`,
not by `--kbps` or the bucket (FINDINGS 44.3). Two known unit inconsistencies on
that side are implemented and default OFF because they measure as a wash --
`--joint-decide` (the per-block lagrangian prices a byte at `lam + mu*c` rather
than `lam`) and `--joint-bucket` (the bucket may not lend clocks it cannot
repay). FINDINGS 44.
An encode is ~95% k-means; a 120-frame window is ~29 s, of which ~22 s is
training the two codebooks (FINDINGS 44.5).
There are **two** ceilings, on two different axes. The second is the 68000's
decode budget: `mu` is bisected per frame against 833,333 cycles so the frame
also *decodes* in time, which takes the worst sustained window from 37 frames