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
src/player/decode.s
+2 -194
View File
@@ -88,18 +88,8 @@ FPTR = $18010 ; -> first frame record
SCR_N = $18014 ; frames remaining this pass
SCR_END = $18018 ; expected end of the current payload
CB1 = $20000 ; expanded 4x4 codebook
CB4 = $22000 ; expanded 2x2 codebook
include "src/player/geom.i"
DST0 = $C08000 ; GVRAM + 32*1024 (first picture row)
DSTE = $C38000 ; GVRAM + 224*1024 (one past last)
BROW = 4096 ; bytes per block row (4 picture rows)
ROWLEN = 512 ; bytes per block row of blocks (64 * 8)
MODEB = 768 ; packed mode header, 3072 blocks * 2 bits
SPCU = 12 ; bytes of code per COARSE span unit (24 px)
SPCN = 11 ; coarse units: 11*24 = 264 px >= one row
SPFU = 2 ; bytes of code per FINE span unit (2 px)
SPFN = 11 ; fine units: 11*2 = 22 px > one coarse unit
org $10000
start:
@@ -130,186 +120,4 @@ hold: bra.s hold
desync: move.l #$EE,FLAG.l
bra.s hold
; ---------------------------------------------------------------- one block
; \1 = right-shift needed to bring this block's 2 mode bits to bits 1-0.
BLOCK macro
move.b (a1),d0
ifne \1
lsr.b #\1,d0
endc
and.w #3,d0
beq .sk\@ ; 00 SKIP -- the median block
subq.w #1,d0
beq .v1\@ ; 01 V1
subq.w #1,d0
bne .rw\@ ; 11 RAW, else 10 V4
; -- V4: four 2x2 codewords, sub-block order TL TR BL BR (vq_hybrid.paint)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,(a4)
move.l d1,1024(a4)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,4(a4)
move.l d1,1028(a4)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,2048(a4)
move.l d1,3072(a4)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,2052(a4)
move.l d1,3076(a4)
bra .sk\@
; -- V1: one 4x4 codeword, 32 bytes, straight out of the expanded codebook
.v1\@:
moveq #0,d0
move.b (a0)+,d0
lsl.w #5,d0
movem.l (a2,d0.w),d0-d7 ; EA is resolved before the load
movem.l d0-d1,(a4)
movem.l d2-d3,1024(a4)
movem.l d4-d5,2048(a4)
movem.l d6-d7,3072(a4)
bra .sk\@
; -- RAW: 16 literal palette indices. Two indices are assembled into one long
; via swap, so each pair of pixels costs one write instead of two; the high
; byte of each word is left as zero because the hardware discards it anyway.
.rw\@:
RAWPAIR 0
RAWPAIR 4
RAWPAIR 1024
RAWPAIR 1028
RAWPAIR 2048
RAWPAIR 2052
RAWPAIR 3072
RAWPAIR 3076
.sk\@:
addq.l #8,a4
endm
RAWPAIR macro
moveq #0,d0
move.b (a0)+,d0
swap d0
move.b (a0)+,d0
move.l d0,\1(a4)
endm
; ------------------------------------------------------- the span section
; in: a0 = span section, a1 = mode header (preserved across the call)
; out: a0 = one past the section, i.e. the block payload
;
; This is tools/bench/blit.s v7 verbatim, and deliberately so: the 66.0 clocks
; per span + 9.143 per coarse pixel + 9.978 per fine pixel of FINDINGS 40 were
; measured on exactly this instruction sequence, over thirteen span lengths, and
; a "tidier" rewrite here would silently invalidate every span figure in
; FINDINGS 39/40 and in tools/analysis/14_dmac_chain.py.
;
; The fine chain is entered by FALLING OUT of the coarse one, so a span with no
; coarse units enters at v7cx with d0 already reloaded -- which is why the
; coarse displacement for c=0 is SPCN*SPCU, one past the last coarse unit,
; rather than a special case.
paint_spans:
move.w (a0)+,d7 ; spans in this frame
subq.w #1,d7
bmi spnone ; a frame may legitimately have none (the
; chain is far past a short branch)
move.l a1,-(sp) ; a1 is a payload register below
spspan: move.l (a0)+,a2 ; absolute GVRAM destination
move.w (a0)+,d0 ; (SPCN - coarse) * SPCU
jmp spch(pc,d0.w)
spch:
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
spcx: move.w (a0)+,d0 ; (SPFN - fine) * SPFU, from mid-stream
jmp spfh(pc,d0.w)
spfh:
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
dbra d7,spspan
move.l (sp)+,a1
spnone: rts
; ------------------------------------------------------------- one frame
; in: a0 = payload, a1 = packed mode header
; out: a0 = one past the last payload byte consumed
decode_frame:
lea CB1,a2
lea CB4,a3
lea DST0,a6
rowloop:
move.l a6,a4
lea ROWLEN(a6),a5
byteloop:
tst.b (a1) ; four SKIPs in one test
beq allskip
BLOCK 6
BLOCK 4
BLOCK 2
BLOCK 0
addq.l #1,a1
cmpa.l a5,a4
bne byteloop
bra rowdone
allskip:
addq.l #1,a1
lea 32(a4),a4
cmpa.l a5,a4
bne byteloop
rowdone:
lea BROW(a6),a6
cmpa.l #DSTE,a6
bne rowloop
rts
include "src/player/frame.i"
src/player/frame.i
+183
View File
@@ -0,0 +1,183 @@
; ---------------------------------------------------------------- one block
; \1 = right-shift needed to bring this block's 2 mode bits to bits 1-0.
BLOCK macro
move.b (a1),d0
ifne \1
lsr.b #\1,d0
endc
and.w #3,d0
beq .sk\@ ; 00 SKIP -- the median block
subq.w #1,d0
beq .v1\@ ; 01 V1
subq.w #1,d0
bne .rw\@ ; 11 RAW, else 10 V4
; -- V4: four 2x2 codewords, sub-block order TL TR BL BR (vq_hybrid.paint)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,(a4)
move.l d1,1024(a4)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,4(a4)
move.l d1,1028(a4)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,2048(a4)
move.l d1,3072(a4)
moveq #0,d0
move.b (a0)+,d0
lsl.w #3,d0
movem.l (a3,d0.w),d0-d1
move.l d0,2052(a4)
move.l d1,3076(a4)
bra .sk\@
; -- V1: one 4x4 codeword, 32 bytes, straight out of the expanded codebook
.v1\@:
moveq #0,d0
move.b (a0)+,d0
lsl.w #5,d0
movem.l (a2,d0.w),d0-d7 ; EA is resolved before the load
movem.l d0-d1,(a4)
movem.l d2-d3,1024(a4)
movem.l d4-d5,2048(a4)
movem.l d6-d7,3072(a4)
bra .sk\@
; -- RAW: 16 literal palette indices. Two indices are assembled into one long
; via swap, so each pair of pixels costs one write instead of two; the high
; byte of each word is left as zero because the hardware discards it anyway.
.rw\@:
RAWPAIR 0
RAWPAIR 4
RAWPAIR 1024
RAWPAIR 1028
RAWPAIR 2048
RAWPAIR 2052
RAWPAIR 3072
RAWPAIR 3076
.sk\@:
addq.l #8,a4
endm
RAWPAIR macro
moveq #0,d0
move.b (a0)+,d0
swap d0
move.b (a0)+,d0
move.l d0,\1(a4)
endm
; ------------------------------------------------------- the span section
; in: a0 = span section, a1 = mode header (preserved across the call)
; out: a0 = one past the section, i.e. the block payload
;
; This is tools/bench/blit.s v7 verbatim, and deliberately so: the 66.0 clocks
; per span + 9.143 per coarse pixel + 9.978 per fine pixel of FINDINGS 40 were
; measured on exactly this instruction sequence, over thirteen span lengths, and
; a "tidier" rewrite here would silently invalidate every span figure in
; FINDINGS 39/40 and in tools/analysis/14_dmac_chain.py.
;
; The fine chain is entered by FALLING OUT of the coarse one, so a span with no
; coarse units enters at v7cx with d0 already reloaded -- which is why the
; coarse displacement for c=0 is SPCN*SPCU, one past the last coarse unit,
; rather than a special case.
paint_spans:
move.w (a0)+,d7 ; spans in this frame
subq.w #1,d7
bmi spnone ; a frame may legitimately have none (the
; chain is far past a short branch)
move.l a1,-(sp) ; a1 is a payload register below
spspan: move.l (a0)+,a2 ; absolute GVRAM destination
move.w (a0)+,d0 ; (SPCN - coarse) * SPCU
jmp spch(pc,d0.w)
spch:
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
movem.l (a0)+,d0-d6/a1/a3-a6
movem.l d0-d6/a1/a3-a6,(a2)
lea 48(a2),a2
spcx: move.w (a0)+,d0 ; (SPFN - fine) * SPFU, from mid-stream
jmp spfh(pc,d0.w)
spfh:
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
move.l (a0)+,(a2)+
dbra d7,spspan
move.l (sp)+,a1
spnone: rts
; ------------------------------------------------------------- one frame
; in: a0 = payload, a1 = packed mode header
; out: a0 = one past the last payload byte consumed
decode_frame:
lea CB1,a2
lea CB4,a3
lea DST0,a6
rowloop:
move.l a6,a4
lea ROWLEN(a6),a5
byteloop:
tst.b (a1) ; four SKIPs in one test
beq allskip
BLOCK 6
BLOCK 4
BLOCK 2
BLOCK 0
addq.l #1,a1
cmpa.l a5,a4
bne byteloop
bra rowdone
allskip:
addq.l #1,a1
lea 32(a4),a4
cmpa.l a5,a4
bne byteloop
rowdone:
lea BROW(a6),a6
cmpa.l #DSTE,a6
bne rowloop
rts
src/player/geom.i
+27
View File
@@ -0,0 +1,27 @@
; Geometry and codebook constants shared by every front-end in src/player/.
;
; Split out of decode.s in session 18 so that decode.s (the preloaded-stream
; rig, gated by tools/bench/check.sh) and stream.s (the ring-buffer streaming
; rig, FINDINGS 49) assemble from LITERALLY THE SAME BYTES for the block loop
; and the span chain. Those bytes are not incidental: the 66.0 clocks/span,
; 9.143 clocks/coarse pixel and 9.978 clocks/fine pixel of FINDINGS 40, and
; every per-block constant in FINDINGS 24/30/41, are fitted to this exact
; instruction sequence. Two hand-maintained copies of it would drift, and the
; drift would be invisible -- both would still decode correctly, and only the
; cost model would be wrong.
;
; The split is a no-op by construction: tools/bench/check.sh asserts that
; decode.s still assembles to the same 1,296 bytes it did before it.
CB1 = $20000 ; expanded 4x4 codebook
CB4 = $22000 ; expanded 2x2 codebook
DST0 = $C08000 ; GVRAM + 32*1024 (first picture row)
DSTE = $C38000 ; GVRAM + 224*1024 (one past last)
BROW = 4096 ; bytes per block row (4 picture rows)
ROWLEN = 512 ; bytes per block row of blocks (64 * 8)
MODEB = 768 ; packed mode header, 3072 blocks * 2 bits
SPCU = 12 ; bytes of code per COARSE span unit (24 px)
SPCN = 11 ; coarse units: 11*24 = 264 px >= one row
SPFU = 2 ; bytes of code per FINE span unit (2 px)
SPFN = 11 ; fine units: 11*2 = 22 px > one coarse unit
src/player/stream.s
+184
View File
@@ -0,0 +1,184 @@
; DLX3 frame decoder, RING-BUFFER front-end -- STATUS item 3, FINDINGS 49.
;
; src/player/decode.s decodes a stream that is ALREADY WHOLLY IN RAM: the rig
; preloads 5,261,814 bytes at $30000 and walks a0 forward through all of it.
; That gate proves the decoder is pixel-exact over a 120-frame window
; (FINDINGS 45) and says NOTHING about how the bytes got there. The shipping
; player never holds a window at once; it streams from a SCSI disk into a ring
; a fraction of the size. Nothing in this tree has ever tested that path.
;
; WHAT IS ACTUALLY HARD ABOUT IT. The block loop and the span chain read the
; stream with a monotonically increasing a0 and no bounds check anywhere --
; `move.l (a0)+,d0`, `lea MODEB(a0),a0`, eleven unrolled `movem.l (a0)+`, a
; `move.b (a0)+` per block index. None of it can survive an address that wraps
; mid-record. So the ring does not merely need ENOUGH BYTES resident by the
; deadline -- 09_buffer_sim.py's question, and FINDINGS 21's answer -- it needs
; the WHOLE NEXT RECORD resident and CONTIGUOUS.
;
; THE WRAP POLICY IS `aligned`, and it was chosen on measurement, not taste
; (tools/analysis/19_ring_stream.py). The producer refuses to start a record it
; cannot finish before the end of the ring: it leaves a hole and restarts at 0.
;
; aligned costs RAM -- a mean hole of 23.4 KB in a 256 KB ring, 9.1% of it --
; and ZERO CPU.
; split lets records wrap and mirrors the ring's first MAXREC bytes into a
; shadow past its end, so any record start reads linearly. Costs
; zero RAM and 46,394 clocks/frame of memcpy -- 5.57% of the frame
; budget, forever.
;
; Both figures are for s14_d5_all1500, the shipping candidate, in a 256 KB ring;
; they scale with record size, so they are per container, not universal. The
; lighter gate container makes it 5.7% of the ring against 3.64% of the budget --
; same direction, same verdict.
;
; The decoder already spends 77.0% of the budget on the mean frame and 91.1% at
; p90 (FINDINGS 45). 5.57% more puts p90 at 96.7%. RAM is the resource this
; machine has 2 MB of and clocks are the one it has none of, so the trade is not
; close. `aligned` also needs a per-record INDEX on the fill side, which a
; BRANCHING laserdisc game needs anyway to seek to a branch point -- so the
; policy that costs no clocks also reuses a structure the player cannot avoid.
;
; The third option -- teach the block loop to wrap its own reads -- is the
; expensive one and not because of the branch. A bounds test lands INSIDE the
; instruction sequences FINDINGS 30.4 and 40 fitted their constants to, so it
; does not cost a compare, it costs every span and per-block figure in the tree
; being re-measured.
;
; THE PRODUCER IS OUTSIDE THIS FILE. Here it is tools/bench/stream.lua playing
; a SCSI disk at a modelled byte rate; in the player it is the MB89352 and a
; DMAC channel. The handshake is deliberately the same either way:
;
; producer -> FR_HEAD count of records made wholly resident (monotonic)
; DESC[] ring of record base addresses, DESCN entries
; decoder -> FR_TAIL count of records consumed (monotonic)
; RD_PTR one past the last byte read; everything below is free
;
; Two monotonic counters and a released-to pointer -- no lock, no shared cursor,
; single reader and single writer, so it is correct on a 68000 with no atomics
; provided each side only ever writes its own words. That is why FR_TAIL is
; the decoder's and FR_HEAD is the producer's rather than one shared index.
;
; STALLS ARE COUNTED, NOT HIDDEN. A frame whose record is not resident when the
; decoder wants it spins in `waitrec`, and STALLS counts the FRAMES that had to
; wait at all (not the polls). A rig that silently absorbed an underrun would
; report a pixel-exact decode of a stream that arrived late, which is precisely
; the failure this front-end exists to make visible. The spin is bounded:
; SPINMAX polls without progress sets FLAG=$E1, so a wedged producer fails as a
; wedged producer instead of as a MAME timeout with no diagnosis (FINDINGS 34.1).
FLAG = $18000 ; 0 idle / 1 running / $FF done / $EE desync
; / $E1 producer stalled out
ITER = $18008 ; outer repeat count, written by Lua
NFR = $1800C ; frames per pass
SCR_N = $18014 ; frames remaining this pass
SCR_END = $18018 ; expected end of the current payload
RD_PTR = $18020 ; decoder -> producer: released up to here
FR_HEAD = $18024 ; producer -> decoder: records resident
FR_TAIL = $18028 ; decoder -> producer: records consumed
STALLS = $1802C ; frames that had to wait for their record
SPINS = $18030 ; total poll iterations spent waiting
PACE = $18034 ; producer -> decoder: frame ticks elapsed since
; release. Frame i may not START before tick i.
PACEON = $18038 ; 1 = obey PACE. 0 leaves the loop free-running,
; byte for byte the loop FINDINGS 49 measured.
DESC = $18100 ; DESCN x u32, record base addresses
DESCN = 64 ; power of two; the index is masked, not compared
DESCM = (DESCN-1)*4 ; mask for a BYTE offset into DESC
SPINMAX = 2000000 ; polls with no progress before giving up
include "src/player/geom.i"
org $10000
start:
move.l #1,FLAG.l ; timer starts here
outer:
move.l NFR.l,SCR_N.l
clr.l FR_TAIL.l
clr.l STALLS.l
clr.l SPINS.l
frameloop:
; ---- PACE GATE (FINDINGS 49.7.2, and it is the whole point of this session).
; Free-running, this loop asks for record i the instant it finishes record i-1,
; so it outruns any finite pipe, the ring NEVER backs up, and the producer's
; overlap test never refuses a placement. A ring-size sweep under those
; conditions tests WRAP CORRECTNESS at each size and nothing about BUFFERING:
; 48 KB passes while holding one record. A shipping player does not do this --
; it draws frame i, waits for its slot, and spends the rest of the frame time
; idle while the disk fills the ring behind it.
;
; So the rig gets a frame clock. PACE is bumped by the producer (in the player,
; vblank or an MFP timer) and frame i is forbidden to start before tick i. With
; the decoder held to 12 fps the ring fills, the producer starts hitting its own
; overlap test, and FR_HEAD-FR_TAIL becomes what it claims to be: the number of
; whole frames the decoder could run on if delivery stopped dead -- which is the
; branch-point seek question stated in frames.
;
; It also makes STALLS mean something. Free-running, a stall is EARLINESS
; (49.6); paced, a frame that has to wait for its record is a real underrun.
tst.l PACEON.l
beq.s nopace
pacewait:
move.l PACE.l,d0
cmp.l FR_TAIL.l,d0 ; d0 - FR_TAIL; carry = tick not reached
bcs.s pacewait
nopace:
; ---- wait until the producer has made this record wholly resident.
; d1 counts polls for this frame; a nonzero d1 on exit means the frame stalled.
moveq #0,d1
move.l FR_TAIL.l,d2
waitrec:
move.l FR_HEAD.l,d0
cmp.l d2,d0
bhi.s gotrec ; HEAD > TAIL: at least one record ready
addq.l #1,d1
cmp.l #SPINMAX,d1
bcs.s waitrec
move.l #$E1,FLAG.l ; producer never delivered
bra hold
gotrec:
tst.l d1
beq.s nostall
addq.l #1,STALLS.l
add.l d1,SPINS.l
nostall:
; ---- pop the descriptor. DESCN is a power of two, so the wrap is an and.
move.l d2,d0
lsl.l #2,d0
and.w #DESCM,d0
lea DESC,a1 ; DESC is absolute; (d0.w) needs a base
move.l (a1,d0.w),a0 ; a1 is reloaded from a0 two lines below
; ---- from here to the release, byte for byte what decode.s does. a0 is
; inside the ring rather than inside a preloaded blob, and the block loop
; cannot tell the difference -- which is the whole claim being tested.
move.l (a0)+,d0 ; u32 payload length, big-endian
lea 0(a0,d0.l),a1
move.l a1,SCR_END.l ; where the payload must end
move.l a0,a1 ; a1 = packed mode header
lea MODEB(a0),a0 ; a0 = span section
bsr paint_spans ; -> a0 = block payload, a1 preserved
bsr decode_frame
cmpa.l SCR_END.l,a0 ; bitstream desync is silent otherwise
bne desync
; ---- release. Round up to 4 the same way decode.s does: the producer lays
; records on 4-byte boundaries, so the byte one past this record's padded
; end is the first byte the producer may reuse.
move.l a0,d0
addq.l #3,d0
and.b #$FC,d0
move.l d0,RD_PTR.l
addq.l #1,FR_TAIL.l
subq.l #1,SCR_N.l
bne frameloop
subq.l #1,ITER.l
bne outer
move.l #$FF,FLAG.l ; timer stops here
hold: bra.s hold
desync: move.l #$EE,FLAG.l
bra.s hold
include "src/player/frame.i"