Files
Dragon-s-Lair-X68k/tools/analysis/17_span_delivered.py
T
prosolis b49bbdc939 Build v7 into the player, and find the cost model 18% wrong on the block it made commonest
src/player/decode.s now paints v7 literal spans, pixel-exact under MAME and
px68k's C68K core over a container where every frame carries 128-216 spans
covering up to 38% of the picture. The span pass is blit.s v7 verbatim: the
66.0/9.143/9.978 fit was measured on that instruction sequence.

The container is DLX3 -- a span section between the mode header and the block
payload, since that is the only place the 68000 can reach without first parsing
something of variable length. 16_span_roundtrip.py gates it in check.sh, and
asserts it emitted enough spans to have tested anything.

Two synthetic all-SPAN anchors price v7 inside decode.s at 151.2 and 225.6
clocks per 4x4 block, against FINDINGS 40's table of 151 and 226 -- 0.2% on
both emulators. The measured mode costs what it was said to cost.

Two things that were not on the list:

TWO BYTE BUDGETS. FINDINGS 40's 18/120 was scored against the 488 KB/s PIPE,
not the 280 KB/s profile, and at the profile rate the lam search has already
spent the allowance -- spans fired on 5 frames of 120 and looked like a
regression. The profile is a chosen quality rate point; the pipe is hardware.
--kbps and --span-kbps are now separate and spans run before mu, because a span
pays in bytes and mu pays in picture. Delivered: 86/120 over budget without
spans, 77/120 at the profile budget, 34/120 on the pipe for +0.36 dB.

C_SKIP_MIXED WAS NEVER MEASURED, and it was 18% low -- 45.0, now 55.0. It is
the one constant in the table that came from a derivation, because the
synthetic frame that would measure it cannot exist: a byte needs a coded block
for its SKIP to be mixed. Four bracketing anchors measure it on both emulators
with the header byte rotated through all four positions, and the partner mode
solves back to its own anchored value to 0.2%. With it corrected the model
predicts a real spanned decode to -0.06% mean / 0.09% worst, against -2.99% /
4.30%. It matters because a span marks its run SKIP, so mixed SKIPs dominate
exactly the frames spans are judged on.

Also: the rig had been writing its synthetic timing frames 26 KB past the top
of a 2 MB machine, and got away with it because the modes it overran are
data-independent. A span's jump displacements come out of the stream, so it is
not. And frames-over-budget is no longer a safe headline -- the controller aims
at the deadline, so 55 of 120 frames sit within 5% of it and a 1% cost shift
moves 22 frames.

FINDINGS 41. check.sh ALL GREEN, now gating on a span-heavy DLX3 container.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
2026-08-23 20:02:03 -07:00

101 lines
4.2 KiB
Python

#!/usr/bin/env python3
"""What do the spans the ENCODER actually emitted cost, and what do they buy?
python3 tools/analysis/17_span_delivered.py a.dlx [b.dlx ...] [--bus 488]
Every span figure before this one -- FINDINGS 29 through 40, and
tools/analysis/12 and 14 -- was scored by SIMULATING span selection over mode
maps that were chosen without spans available. FINDINGS 39.3 flagged that as a
lower bound on what a span-aware encoder would find, and docs/STATUS.md's item 2
asks for the figures to be re-run "against a container the encoder actually
emits with spans in it". This is that script: it reads the span section out of
a DLX3 container and prices exactly those spans, with no selection model at all.
THE MODEL IS 14_dmac_chain.py's, deliberately unchanged, so the columns are
comparable:
frame clocks = block decode + span painting + disk DMA
additive, because a 68000 has no cache and a two-word prefetch queue and stalls
the moment another master takes the bus (FINDINGS 38.3). Block cost is
vq_hybrid.cycles(), which reads a spanned block as SKIP -- correct, because the
span section is what paints it, and its cost is the second term.
The span term is the MEASURED v7 fit (FINDINGS 40), and as of session 12 that
fit is confirmed inside src/player/decode.s itself rather than only in
tools/bench/blit.s: the synthetic all-SPAN anchors of tools/bench/prep_dlx.py
reproduce it to 0.23% on both emulators (FINDINGS 41.3).
"""
import argparse, os, sys
sys.path.insert(0, "tools/encoder")
sys.path.insert(0, "tools/analysis")
import numpy as np
import vq_hybrid as H
import spans as SP
import buscost as B
from dlx import DLX
FRAME_CYC = 833333.0
AUDIO_KBPS = 7.8
ap = argparse.ArgumentParser()
ap.add_argument("containers", nargs="+")
ap.add_argument("--bus", type=float, default=488.0, help="SCSI pipe, KB/s")
ap.add_argument("--fps", type=float, default=12.0)
ap.add_argument("--disk-clk-word", type=float, default=8.0,
help="clocks the SCSI DMA steals per word (FINDINGS 39.7 "
"brackets it at 5..12; 8 is the midpoint)")
a = ap.parse_args()
def score(path):
d = DLX(path)
rows = []
for f in range(d.nframes):
mode = d.modes(f)
sp, _ = d.spans(f)
_, n = d.frames[f]
blk = H.cycles(mode)
spc = sum(SP.clocks(len(p)) for _, _, p in sp)
disk = n / 2.0 * a.disk_clk_word
rows.append((blk, spc, disk, n, len(sp),
sum(len(p) for _, _, p in sp)))
return d, np.array(rows).T
print(f"{'container':<34}{'KB/s':>8}{'spans':>9}{'span px':>9}"
f"{'median':>9}{'worst':>9}{'over':>9}")
print(f"{'':<34}{'':>8}{'/frame':>9}{'%':>9}"
f"{'% frame':>9}{'% frame':>9}{'budget':>9}")
for path in a.containers:
if not os.path.exists(path):
print(f"{path:<34} missing"); continue
d, r = score(path)
blk, spc, disk, byt, nsp, spx = r
tot = blk + spc + disk
kbps = byt.mean() * a.fps / 1024 + AUDIO_KBPS
print(f"{os.path.basename(path):<34}{kbps:>8.1f}{nsp.mean():>9.0f}"
f"{100*spx.mean()/(d.W*d.H):>9.1f}"
f"{100*np.median(tot)/FRAME_CYC:>9.1f}"
f"{100*tot.max()/FRAME_CYC:>9.1f}"
f"{int((tot > FRAME_CYC).sum()):>6}/{d.nframes:<3}")
print(f"\n ADDITIVE: frame = block decode + span painting + disk DMA, the model"
f"\n of 14_dmac_chain.py. Disk debited at {a.disk_clk_word:g} clocks/word "
f"over the\n container's own byte count; CPU budget {FRAME_CYC:,.0f} "
f"clocks at {a.fps:g} fps.")
# The decomposition is the point: a span moves work out of the block loop and
# into the span section, and it pays for it in bytes -- which the disk term
# then charges back. A design that only counted the CPU would show a win that
# the I/O it created takes away again (docs/FINDINGS.md 33).
print(f"\nWHERE EACH FRAME'S CLOCKS GO, mean over the container")
print(f" {'container':<34}{'blocks':>12}{'spans':>12}{'disk':>12}{'total':>12}")
for path in a.containers:
if not os.path.exists(path):
continue
d, r = score(path)
blk, spc, disk = r[0], r[1], r[2]
print(f" {os.path.basename(path):<34}{blk.mean():>12,.0f}{spc.mean():>12,.0f}"
f"{disk.mean():>12,.0f}{(blk+spc+disk).mean():>12,.0f}")