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

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

tools/analysis/11_cpu_budget.py

@@ -24,7 +24,13 @@ import numpy as np
 from dlx import DLX
 import vq_hybrid as H
 import ratectl as RC
-RC_AUDIO_BPS = RC.AUDIO_KBPS * 1024
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import buscost as B
+# The audio byte rate is now DERIVED, not restated: 15.6 kHz mono MSM6258V is
+# 15,625 4-bit samples/s, two to a byte. RC.AUDIO_KBPS's 7.8 is that figure in
+# DECIMAL kB, and was being multiplied by 1024 here -- a 2.4% overstatement,
+# harmless, but it hid which unit the constant was in.
+RC_AUDIO_BPS = B.ADPCM_BYTES_PER_S
 
 # Machine clocks, confirmed from MAME 0.277 src/mame/sharp/x68k.cpp:1133/1194/
 # 1200 -- not recalled. x68000 and x68ksupr are BOTH 40_MHz_XTAL/4 = 10 MHz;
@@ -58,8 +64,26 @@ ap.add_argument("--dma-clocks-per-word", type=float, default=8.0,
                 help="HD63450 cycle-steal. ESTIMATE from FINDINGS 5, NEVER "
                      "MEASURED, and the most load-bearing unmeasured number "
                      "in the project (FINDINGS 35.3)")
+ap.add_argument("--dma-clocks-per-byte", type=float, default=5.0,
+                help="what the SCSI DMA costs per DELIVERED BYTE. The MB89352 "
+                     "is an 8-bit port, so the DMAC pays per byte and the "
+                     "per-word denominator of FINDINGS 5/39.7 was half the "
+                     "real debit (FINDINGS 43). 5 = single-address, bus held, "
+                     "no drive wait; 9 = dual-address")
 ap.add_argument("--pio-clocks-per-byte", type=float, default=12.0,
                 help="hand-derived floor for a 68000 register-to-RAM copy")
+# Audio is NOT the disk, and charging it the disk's rate was charging it the
+# favourable side of an open question. tools/analysis/21_iplrom_dmac.py reads
+# the IPL ROM's own HD63450 setup: channel 3 is dual address, 8-bit port, cycle
+# steal WITHOUT hold, external request -- one full arbitration per byte, no
+# burst to amortise it over. 16 is the datasheet best case, 19 the worst.
+ap.add_argument("--adpcm-clocks-per-byte", type=float,
+                default=B.ADPCM_CLK_BYTE_BEST,
+                help="what an ADPCM byte costs. READ OUT OF THE IPL ROM's DMAC "
+                     "configuration (21_iplrom_dmac.py), not assumed: dual "
+                     "address + per-byte arbitration = 16 best, 19 worst. The "
+                     "audio stream always DMAs, whatever --io says about the "
+                     "disk")
 a = ap.parse_args()
 CPUHZ = CLOCKS[a.machine] * 1e6
 FPS = a.fps
@@ -72,13 +96,15 @@ d = DLX(a.container)
 # --- what the transfer costs, from the container's own byte rate
 vid_bps = sum(n + 4 for (_, n) in d.frames) / d.nframes * d.fps
 io_bps = vid_bps + RC_AUDIO_BPS
+aud_cycles_per_s = RC_AUDIO_BPS * a.adpcm_clocks_per_byte
 if a.io == "dma":
-    io_cycles_per_s = (io_bps / 2) * a.dma_clocks_per_word
+    io_cycles_per_s = vid_bps * a.dma_clocks_per_byte + aud_cycles_per_s
 elif a.io == "pio":
-    io_cycles_per_s = io_bps * a.pio_clocks_per_byte
+    io_cycles_per_s = vid_bps * a.pio_clocks_per_byte + aud_cycles_per_s
 else:
     io_cycles_per_s = 0.0
 io_pct = 100 * io_cycles_per_s / CPUHZ
+aud_pct = 100 * aud_cycles_per_s / CPUHZ
 FRAME_NET = FRAME * (1 - io_pct / 100)
 
 modes = [d.modes(f) for f in range(d.nframes)]
@@ -91,9 +117,20 @@ print(f"budget: {a.machine} @ {CLOCKS[a.machine]:.2f} MHz, {FPS:g} fps "
       f"-> {FRAME:,.0f} cycles/frame")
 print(f"  I/O ({a.io}): {io_bps/1024:.1f} KB/s costs {io_pct:.1f}% of the CPU "
       f"-> {FRAME_NET:,.0f} cycles/frame left for decoding")
+if a.io != "none":
+    print(f"    video {vid_bps/1024:6.1f} KB/s x "
+          f"{(a.dma_clocks_per_byte if a.io=='dma' else a.pio_clocks_per_byte):g}"
+          f" clk/B = {io_pct-aud_pct:5.2f}%   "
+          f"(W: still open, ROADMAP B3 / FINDINGS 42.4)\n"
+          f"    audio {RC_AUDIO_BPS/1024:6.2f} KB/s x {a.adpcm_clocks_per_byte:g}"
+          f" clk/B = {aud_pct:5.2f}%   "
+          f"(SETTLED: read out of the IPL ROM, FINDINGS 52)")
 if a.io == "dma":
-    print(f"  {a.dma_clocks_per_word:g} clocks/word is an ESTIMATE (FINDINGS 5), "
-          f"never measured -- see FINDINGS 35.3")
+    print(f"  {a.dma_clocks_per_byte:g} clocks/BYTE, the MC68450 datasheet "
+          f"floor for an 8-bit port (FINDINGS 43).\n  It is not measured on "
+          f"hardware; what IS settled is that the per-word denominator this\n"
+          f"  used before session 14 was physically impossible -- 2.5 "
+          f"clocks/byte is below\n  the 68000's 4-clock minimum bus cycle.")
 elif a.io == "none":
     print("  WARNING: --io none scores the decoder as if the disk were free. "
           "That is the\n  premise FINDINGS 35 overturned; every 'N frames miss' "
@@ -114,15 +151,20 @@ TIMED_FRAMES = (("min non-SKIP", 15.4, 31.5), ("median", 48.1, 73.8),
                 ("p90", 82.5, 116.4), ("max non-SKIP", 100.0, 135.8))
 if (os.path.abspath(a.container) == os.path.abspath(TIMED)
         and a.machine == "stock" and a.fps == 12):
-    print("model vs the frames actually timed on the 68000:")
+    print("model vs the frames actually timed on the 68000 "
+          "(the model reads HIGH, and by more\n as the frame gets harder -- "
+          "so a 'does not fit' from it is the safe direction):")
     for label, frac, meas in TIMED_FRAMES:
         i = int(np.argmin(abs(ns - frac)))
         print(f"  {label:<14} non-SKIP {ns[i]:5.1f}%   model {pct[i]:6.1f}%   "
               f"measured {meas:5.1f}%   error {pct[i]-meas:+.1f} pt")
 else:
-    print(f"(no 68000 timings for this container/machine -- the model was "
-          f"validated to\n within 1 pt on {TIMED} at stock/12fps;\n"
-          f" run tools/bench/decode.lua to time another container)")
+    print(f"(no 68000 timings for this container/machine. The model is "
+          f"validated against four\n frames timed on the 68000, and only on "
+          f"{TIMED}\n at stock/12fps -- run it on that container to see the "
+          f"errors, which are a few points\n CONSERVATIVE and grow with the "
+          f"non-SKIP fraction. Run tools/bench/decode.lua to\n time another "
+          f"container.)")
 
 print(f"\nper-frame cost, % of a {FPS:g}fps frame budget:")
 print(f"  measured-cost model: median {np.median(pct):5.1f}  "