c64-kb 0.17.0

package/templates/demo/src/config.asm

@@ -0,0 +1,80 @@
+// config.asm: every constant the demo's layout and timeline hang on.
+// tools/gen_expect.py reads the plain `.const NAME = number` lines of this
+// file, recomputes the picture from them in Python and writes expect.json.
+// Change a number here, then run `python3 tools/gen_expect.py`.
+
+.const SCREEN       = $0400
+.const COLOUR       = $d800
+.const RESULT       = $02ff            // $01 pass, $02 fail, $00 not reached
+.const SPRITE_BLOCK = 13               // $0340, the tape buffer
+
+// ---- timeline -------------------------------------------------------------
+.const TITLE_FRAMES = 60               // the title card's play frames
+.const WIPE_COLS    = 2                // columns the wipe clears each frame
+.const FREEZE_UPDATES = 156            // AUTOPILOT: the main part's updates before
+                                       // it freezes; 156 = 8 x 19 + 4 leaves XSCROLL 3,
+                                       // so a missing $D016 write shows in the picture
+.const HOLD         = 232              // frames the meter records (all before the freeze)
+
+// ---- raster layout: the same line numbers on PAL and NTSC ------------------
+.const FRAME_LINE   = 236              // the frame slot, last row of every chain
+.const SCROLL_LINE  = 224              // XSCROLL on for row 22 (lines 227-234)
+.const BARS_SLOT_LINE = 148            // the stable entry: irq2 fires STABLE_LINES later
+.const STABLE_LINES = 4
+.const LATE_LINES   = 3                // a slot entered this many lines after its line is late
+.const BARS_TOP     = 155              // first bar line (measured lead, see main part)
+.const BARS_LINES   = 56               // bar lines 155-210; rows 13-19 must stay blank
+.const BAR_H        = 12
+.const SCROLL_ROW   = 22
+
+// ---- sprite chain (lines 101-145: clear of the bars' lines) ---------------
+.const CHAIN_X0     = 48               // sprite n's centre X: CHAIN_X0 + n * CHAIN_DX
+.const CHAIN_DX     = 36
+.const CHAIN_AX     = 16               // X swing, +-
+.const CHAIN_Y0     = 112              // Y register centre
+.const CHAIN_AY     = 12               // Y swing, +-: Y 100-124, lines 101-145
+.const CHAIN_PX     = 16               // sine steps between sprites, X
+.const CHAIN_PY     = 24               // and Y
+.const CHAIN_SX     = 2                // sine steps a frame, X
+.const CHAIN_SY     = 3                // and Y
+.const CHAIN_COL_A  = 13               // even sprites: light green
+.const CHAIN_COL_B  = 3                // odd sprites: cyan
+// Each bar chunk is a fixed 63 or 65 cycles: sprite DMA on any line from the
+// stable slot to the last bar delays that chunk and every later one until a
+// badline resyncs them, and tears the bars. Keep the chain clear of 148-211.
+.errorif (CHAIN_Y0 + CHAIN_AY + 21 >= BARS_SLOT_LINE && CHAIN_Y0 - CHAIN_AY + 1 <= BARS_TOP + BARS_LINES), "the sprite chain reaches the stable slot or the bar lines"
+
+// ---- bars -------------------------------------------------------------------
+.const BARS_CENTRE  = 22               // top of a bar at rest: (56 - 12) / 2
+.const BARS_AMP     = 22               // +- lines
+.const BAR_STEP     = 40               // sine steps between bars
+.const BAR_SPEED    = 2                // sine steps a frame
+// The four bars' colours, top line to bottom (tables.asm emits them).
+.var bar_ramps = List().add(
+    List().add(9, 2, 8, 10, 15, 1, 1, 15, 10, 8, 2, 9),       // red
+    List().add(6, 6, 14, 14, 3, 1, 1, 3, 14, 14, 6, 6),       // blue
+    List().add(11, 5, 5, 13, 13, 1, 1, 13, 13, 5, 5, 11),     // green
+    List().add(11, 12, 12, 15, 15, 1, 1, 15, 15, 12, 12, 11)) // grey
+
+// ---- the stable entry: cycles of padding before irq2's two $D012 reads ----
+// Measured in VICE x64sc 3.10 with the PROBE build (README, "The stable
+// entry and the bars"): with these the bar kernel's stores land in one
+// column on every line of six shots a model; one more or one less splits
+// them into two columns 8 pixels apart.
+.const SYNC_PAD_PAL  = 2
+.const SYNC_PAD_NTSC = 6
+// The column, in the PROBE build's shots, where every bar line's $D021
+// store must land on both models: tools/probe.py fails on any other, so a
+// wrong pad that still gives one column (NTSC 5 gives 89) fails too.
+.const PROBE_COLUMN = 97
+
+// ---- the running order (parts.asm holds the table) --------------------------
+.const PART_COUNT   = 2
+.const LOOP_PART    = 1                // after the last part: play this one again
+.const MAIN_PART    = 1                // the part the AUTOPILOT build freezes and grades
+
+#if FORCE_FAULT
+.const CHAIN_FAULT  = 16               // the chain starts sixteen sine steps ahead
+#else
+.const CHAIN_FAULT  = 0
+#endif

package/templates/demo/src/framework.asm

@@ -0,0 +1,390 @@
+// framework.asm: the part sequencer, the table-driven IRQ chain, the
+// stable entry, model detection, the once-a-frame slot and the wipe.
+// Nothing here knows what a part draws. Parts are rows of parts.asm.
+//
+// One frame, main part (PAL and NTSC use the same lines):
+//   148  bars_slot    stabilise, then the bar kernel (lines 155-210)
+//   224  scroll_slot  XSCROLL for row 22
+//   236  frame_slot   music, the part's update, the sequencer (every chain ends here)
+//
+// All IRQs enter through the KERNAL's $FF48 and $0314 and leave through
+// $EA81 (registers back, RTI; no KERNAL housekeeping). CIA1's interrupt is
+// off, so every IRQ is a raster match.
+
+// ---- Delay(n): exactly n cycles of straight-line code (n = 0 or n >= 2) ----
+// n >= 11 is a DEX loop, unless its branch would cross a page (a taken
+// branch that crosses costs a cycle more: pitfall
+// branch_page_cross_extra_cycle); then it is NOPs. The assert checks it.
+.macro Delay(n) {
+    .errorif (n == 1 || n < 0), "Delay: n must be 0 or at least 2"
+    .var crosses = (>(* + 2)) != (>(* + 5))
+    .if (n >= 11 && !crosses) {
+        .var k = floor((n - 1) / 5)
+        .var r = n - (5 * k + 1)
+        .if (r == 1) {
+            .eval k = k - 1
+            .eval r = r + 5
+        }
+        ldx #k
+    !:  dex
+        bne !-
+        .errorif (>(*)) != (>(!-)), "Delay: the loop branch crosses a page"
+        Pad(r)
+    } else {
+        Pad(n)
+    }
+}
+.macro Pad(n) {
+    .if ((n & 1) == 1) {
+        bit $ea                        // 3 cycles, a zero-page read
+        .for (var i = 0; i < (n - 3) / 2; i++) { nop }
+    } else {
+        .for (var i = 0; i < n / 2; i++) { nop }
+    }
+}
+
+// A chain row: the raster line, the handler, and whether the chain wraps
+// after it. Rows of one chain are consecutive and in rising line order; the
+// last row of every chain is the frame slot.
+.const ROW = 5
+.macro Slot(line, handler, last) {
+    .errorif (line > 311), "Slot: line past PAL's last line"
+    .byte <line, (line >> 8) << 7, <handler, >handler, last ? $80 : $00
+}
+// A row whose handler calls stabilise: its second IRQ fires STABLE_LINES
+// later, and stabilise arms that line with RST8 clear.
+.macro StableSlot(line, handler, last) {
+    .errorif (line + STABLE_LINES > 255), "StableSlot: stabilise's second IRQ must fire below line 256"
+    Slot(line, handler, last)
+}
+
+// ---- the dispatcher, behind $0314 ------------------------------------------
+// Acknowledge, arm the next row, call this row's handler, advance. The next
+// row is armed before the handler runs, so a handler that overruns makes the
+// next slot late instead of losing it (irq-chain.md measures this).
+// It also keeps three counters the verdict grades (all saturate at 255):
+//   irq_late     entries that began LATE_LINES or more lines after their row's line
+//   irq_bad      chains whose last row was not entry number (rows in the chain)
+//   frame_late   frame slots that ended past the next chain's first line
+//                (counted in frame_slot)
+// The first chain after the IRQs start is not judged (pitfall
+// raster_irq_first_line_jitter).
+irq:
+        FrameMeterStart()              // AUTOPILOT: this IRQ's work is timed
+        cld                            // pitfall decimal_mode_in_irq_handler
+        lda #$01
+        sta $d019
+        ldx slot
+        lda $d012                      // lines since this row's line (low bytes)
+        sec
+        sbc slots+0,x
+        cmp #LATE_LINES
+        bcc !+
+        lda watching
+        beq !+
+        inc irq_late
+        bne !+
+        dec irq_late
+!:      inc irq_entries
+        ldy chain_first                // the last row wraps to the current chain
+        lda slots+4,x
+        bmi !wrap+
+        txa
+        clc
+        adc #ROW
+        tay
+        jmp !arm+
+!wrap:  txa                            // rows in this chain x ROW
+        sec
+        sbc chain_run
+        clc
+        adc #ROW
+        sta irq_tmp
+        lda irq_entries                // entries since the last wrap x ROW
+        asl
+        asl
+        adc irq_entries
+        cmp irq_tmp
+        beq !+
+        lda watching
+        beq !+
+        inc irq_bad
+        bne !+
+        dec irq_bad
+!:      lda #0
+        sta irq_entries
+        sty chain_run
+        lda #1                         // judged from the second chain on
+        sta watching
+!arm:   sty next
+        lda slots+0,y                  // arm all nine bits of the next row's line
+        sta $d012
+        lda $d011
+        and #$7f
+        ora slots+1,y
+        sta $d011
+        lda slots+2,x
+        sta call+1
+        lda slots+3,x
+        sta call+2
+call:   jsr $ffff
+        lda next
+        sta slot
+        FrameMeterPause()
+        jmp $ea81
+
+// ---- stabilise: a slot handler's JSR returns on a fixed cycle --------------
+// The double IRQ of stable-raster-irq.md, as a subroutine. Arms a second
+// raster IRQ STABLE_LINES below this row's line and slides through NOPs; the
+// second IRQ lands in a NOP (0 or 1 cycle late), the two $D012 reads absorb
+// that cycle, and the table's own next line is put back before the RTS.
+// The slot's line must be below 256 - STABLE_LINES.
+stabilise:
+        lda #<irq2
+        sta $0314
+        lda #>irq2
+        sta $0315
+        ldx slot
+        lda slots+0,x
+        clc
+        adc #STABLE_LINES
+        sta $d012
+        lda $d011                      // this line is below 256: RST8 off
+        and #$7f
+        sta $d011
+        lda #$01
+        sta $d019
+        tsx                            // the KERNAL's $FF48 does TSX itself: keep
+        stx saved_sp                   // the stack pointer in memory (the recipe's trap)
+        cli
+        .fill 90, NOP                  // irq2 is always taken inside this slide
+
+irq2:   ldx saved_sp                   // drop irq2's own stack frame: back in the
+        txs                            // slot handler's JSR to stabilise
+        lda model
+        bne irq2_ntsc
+        .errorif (>(*)) != (>irq2_ntsc), "irq2: the model branch crosses a page"
+        Delay(SYNC_PAD_PAL)
+        jmp irq2_sync
+irq2_ntsc:
+        Delay(SYNC_PAD_NTSC)
+irq2_sync:
+        lda $d012                      // the two reads straddle the line's end in one
+        cmp $d012                      // of the two entry phases; BEQ costs 3 when
+        beq !+                         // they match and 2 when not (offset 0: no
+!:                                     // page crossing is possible)
+        lda #<irq
+        sta $0314
+        lda #>irq
+        sta $0315
+        ldy next                       // the line the dispatcher armed
+        lda slots+0,y
+        sta $d012
+        lda $d011
+        ora slots+1,y
+        sta $d011
+        lda #$01
+        sta $d019
+        rts                            // the caller goes on at cycle 51 of line L + 5
+
+// ---- the frame slot: the last row of every chain ---------------------------
+frame_slot:
+        lda #$c8                       // 40 columns, XSCROLL 0: the whole value,
+        sta $d016                      // never a read-modify-write
+        jsr music_frame
+        inc frames
+        bne !+
+        inc frames+1
+!:      jsr sequencer
+        // Late if this ended at or past the next chain's first line (and
+        // before this slot's own line): that row fired while it ran, so a
+        // split came late or a stable entry lost its line. Lines 256 up have
+        // $D011 bit 7 set and are on time.
+        ldy next
+        lda $d011
+        bmi !+
+        lda $d012
+        cmp slots+0,y
+        bcc !+
+        cmp #FRAME_LINE
+        bcs !+
+        inc frame_late
+        bne !+
+        dec frame_late
+!:      inc frame_flag                 // the main loop's once-a-frame point
+        rts
+
+// PAL: play every frame. NTSC: skip every sixth call, so a tune written for
+// 50 Hz keeps its tempo at 60 (pitfall pal_ntsc_tempo_mismatch).
+music_frame:
+        lda model
+        beq !play+
+        inc ntsc_div
+        lda ntsc_div
+        cmp #6
+        bne !play+
+        lda #0
+        sta ntsc_div
+        inc music_skips
+        bne !+
+        inc music_skips+1
+!:      rts
+!play:  jsr MUSIC_PLAY
+        inc music_calls
+        bne !+
+        inc music_calls+1
+!:      rts
+
+// ---- the part sequencer ------------------------------------------------------
+// PLAY: the part's update each frame; when its frame count runs out, OUT.
+// OUT: update and the part's out-transition step each frame until the step
+// returns carry set; then the idle chain (the frame slot alone) and SWITCH.
+// SWITCH: the main loop runs the teardown and the next part's init.
+.const PLAY   = 0
+.const OUT    = 1
+.const SWITCH = 2
+
+sequencer:
+        lda seq_state
+        beq !play+
+        cmp #OUT
+        beq !out+
+        rts                            // SWITCH: the main loop owns it
+!play:  jsr call_update
+        lda frozen                     // AUTOPILOT's graded frame: time stands still
+        bne !done+
+        lda part_timer                 // 0 from the start: the part runs forever
+        ora part_timer+1
+        beq !done+
+        lda part_timer
+        bne !+
+        dec part_timer+1
+!:      dec part_timer
+        lda part_timer
+        ora part_timer+1
+        bne !done+
+        lda #0
+        sta tr_step
+        lda #OUT
+        sta seq_state
+!done:  rts
+!out:   jsr call_update
+        lda frozen
+        bne !done-
+        jsr call_out
+        bcc !done-
+        lda #chain_idle - slots
+        sta chain_first                // one byte: the dispatcher reads it at the wrap
+        lda #SWITCH
+        sta seq_state
+        rts
+
+.macro CallPart(lo, hi) {
+        ldx part
+        lda lo,x
+        sta jump+1
+        lda hi,x
+        sta jump+2
+jump:   jmp $ffff
+}
+call_init:     CallPart(part_init_lo, part_init_hi)
+call_update:   CallPart(part_update_lo, part_update_hi)
+call_out:      CallPart(part_out_lo, part_out_hi)
+call_teardown: CallPart(part_teardown_lo, part_teardown_hi)
+
+// Starts the part in `part`: init, its frame count, its chain, PLAY.
+// Called before the IRQs start (part 0) and from the main loop.
+start_part:
+        jsr call_init
+        ldx part
+        lda part_frames_lo,x
+        sta part_timer
+        lda part_frames_hi,x
+        sta part_timer+1
+        lda part_chain,x
+        sta chain_first
+        lda #PLAY                      // last: the frame slot reads seq_state
+        sta seq_state
+        rts
+
+// Main loop: once the out-transition has finished, tear the part down and
+// start the next. The idle chain keeps the music playing meanwhile.
+switch_parts:
+        lda seq_state
+        cmp #SWITCH
+        bne !+
+        jsr call_teardown
+        ldx part
+        inx
+        cpx #PART_COUNT
+        bne !next+
+        ldx #LOOP_PART
+!next:  stx part
+        jsr start_part
+!:      rts
+
+// ---- model detection, interrupts off ----------------------------------------
+// The last raster line before the wrap: $37 (311) on PAL, $06 (262) on the
+// 6567R8, $05 (261) on the 6567R56A. model = 0 PAL, 1 NTSC.
+detect_model:
+!w1:    lda $d012
+!w2:    cmp $d012
+        beq !w2-
+        bmi !w1-                       // the line went up by one: keep looking
+        ldx #0
+        cmp #$20
+        bcs !+
+        inx
+!:      stx model
+        rts
+
+// ---- the wipe: an out-transition any part can name ---------------------------
+// Clears WIPE_COLS columns of screen RAM a frame, left to right; carry set
+// once all 40 are clear. Colour RAM is left alone.
+wipe_columns:
+        ldy #WIPE_COLS
+!col:   ldx tr_step
+        lda #$20
+        .for (var r = 0; r < 25; r++) {
+            sta SCREEN + r * 40, x
+        }
+        inx
+        stx tr_step
+        cpx #40
+        bcs !+                         // carry set: finished
+        dey
+        bne !col-
+        clc
+!:      rts
+
+// An update or teardown with nothing to do names no_op. An `out` step
+// that returns at once names hard_cut: carry set ends the part this frame.
+// (An out step that always returns carry clear never ends its part.)
+no_op:  rts
+hard_cut:
+        sec
+        rts
+
+// ---- the framework's state ---------------------------------------------------
+slot:        .byte 0                   // the row the next IRQ runs
+next:        .byte 0
+chain_first: .byte 0                   // the current chain's first row
+saved_sp:    .byte 0
+model:       .byte 0
+seq_state:   .byte PLAY
+part:        .byte 0
+part_timer:  .word 0
+tr_step:     .byte 0                   // the transition's own counter
+frame_flag:  .byte 0
+irq_entries: .byte 0                   // dispatcher entries since the last wrap
+irq_tmp:     .byte 0
+chain_run:   .byte 0                   // the chain that started at the last wrap
+watching:    .byte 0
+irq_late:    .byte 0
+irq_bad:     .byte 0
+frame_late:  .byte 0
+frozen:      .byte 0                   // AUTOPILOT: set once the graded frame is reached
+frames:      .word 0                   // frame slots since the start
+ntsc_div:    .byte 0
+music_calls: .word 0
+music_skips: .word 0

package/templates/demo/src/main.asm

@@ -0,0 +1,139 @@
+// main.asm: the demo starter. Start-up, the main loop and the memory map.
+//
+//   framework.asm   dispatcher, stable entry, sequencer, frame slot, wipe
+//   parts.asm       the running order and every part's IRQ chain
+//   part_title.asm  part 0: the title card
+//   part_main.asm   part 1: logo, sprite chain, bars kernel, scroller
+//   tables.asm      part 1's sines, ramps, sprite, logo and message
+//   music.asm       the tune and its player, $1000 init / $1003 play
+//   verdict.asm     AUTOPILOT: grades the frozen frame
+//
+// -define AUTOPILOT: the frame meter runs (row 24, columns 20-39) and the
+// main part freezes after FREEZE_UPDATES updates for the verdict.
+// -define FORCE_FAULT: the sprite chain starts sixteen sine steps ahead; the
+// verdict and the screenshot checks must both fail.
+// -define PROBE: the bar kernel's stores move 20 cycles right, into the
+// visible line, to measure where they land (README, "The stable entry and the bars").
+#import "frame_meter.asm"              // templates/_harness/meter, via -libdir
+#import "config.asm"
+
+BasicUpstart2(start)
+
+* = $0810 "code"
+start:
+        sei
+        lda #$7f
+        sta $dc0d                      // CIA1: no interrupts; every IRQ is a raster match
+        lda $dc0d                      // drop one already flagged
+        lda #0
+        sta $d015
+        sta $d01a
+        jsr detect_model
+        lda model
+        beq !+
+        lda #<kernel_ntsc              // the NTSC kernel's lines are 65 cycles
+        sta kernel_call+1
+        lda #>kernel_ntsc
+        sta kernel_call+2
+!:      ldx #63                        // the sprite image to block 13
+!:      lda sprite_image,x
+        sta SPRITE_BLOCK * 64,x
+        dex
+        bpl !-
+        lda #0                         // the tune: subtune 0, X = this model's pitch
+        ldx model
+        jsr MUSIC_INIT
+        lda #0
+        sta part
+        jsr start_part                 // part 0's init, frame count and chain
+        FrameMeterInit()               // after the init: the meter tints its own cells
+        lda chain_first                // arm the chain's first row
+        sta slot
+        sta chain_run
+        tax
+        lda slots+0,x
+        sta $d012
+        lda $d011
+        and #$7f
+        ora slots+1,x
+        sta $d011
+        lda #<irq
+        sta $0314
+        lda #>irq
+        sta $0315
+        lda #$01
+        sta $d01a
+        sta $d019
+        cli
+
+// The main loop: everything that is not tied to a raster line. Once a
+// frame: record the meter, start the next part when the sequencer asks, and
+// give the loader its turn.
+main_loop:
+#if PROBE
+        // PROBE only: the IRQs must land in every phase of the instruction
+        // they interrupt, or a wrong SYNC_PAD looks right. A frozen frame
+        // repeats exactly, so each pass waits 5 x n cycles (n = 1 to 19, one
+        // more each frame) and then spins in a 19-cycle loop with a 6-cycle
+        // instruction in it; 19 is prime and divides neither frame length.
+        inc probe_n
+        lda probe_n
+        cmp #20
+        bcc !+
+        lda #1
+        sta probe_n
+!:      tax
+!:      dex
+        bne !-
+!:      lda frame_flag                 // 4
+        bne !+                         // 2
+        inc probe_spin                 // 6
+        nop                            // 2
+        nop                            // 2
+        jmp !-                         // 3
+!:
+#else
+        lda frame_flag
+        beq main_loop
+#endif
+        lda #0
+        sta frame_flag
+        FrameMeterEnd()                // the frame's IRQ work, summed, is one sample
+        FrameMeterPrint()
+        jsr switch_parts
+        jsr loader_hook
+#if AUTOPILOT
+        lda verdict_done               // grading is bookkeeping: outside every bracket
+        bne !+
+        lda frozen
+        beq !+
+        jsr verdict
+!:
+#endif
+        jmp main_loop
+
+// The loader hook. A real demo loads its next part here while this one
+// plays, with an IRQ loader (Sparkle, Spindle or Krill: see c64-kb's
+// loader techniques). It runs outside every IRQ, so the chain keeps its
+// lines. Not the KERNAL's LOAD: its serial routines run with interrupts
+// masked for whole bytes, which moves the bars, and end in CLI.
+loader_hook:
+        rts
+
+probe_spin: .byte 0
+probe_n:    .byte 0
+
+#import "framework.asm"
+#import "parts.asm"
+#import "part_title.asm"
+
+#import "music.asm"                    // * = $1000
+
+* = $1400 "main part"
+#import "part_main.asm"
+#if AUTOPILOT
+#import "verdict.asm"
+#endif
+frame_meter:                           // the meter's macros jsr into this label
+        FrameMeterCode(SCREEN, 24, 20, 1, HOLD)
+#import "tables.asm"                   // page-aligned