c64-kb 0.17.0

package/templates/_harness/meter/frame_meter.asm

@@ -0,0 +1,311 @@
+// frame_meter.asm: the CIA2 timer A frame meter for KickAssembler starters.
+// The same contract as frame_meter.h (read that header's comment):
+// frames recorded stop at `hold` (1 to 255: the script's play frames);
+// worst = the largest recorded frame; typical = the median of the recorded
+// frames, computed when recording stops (0 until then). The readout is
+// "F00144 W01234 T01100", 20 cells.
+//
+//   #import "frame_meter.asm"          // -libdir <harness>/meter
+//   ...
+//   FrameMeterInit()                   // once, before the loop
+// loop:
+//   (wait for the frame)
+//   FrameMeterStart()
+//   (one frame of work)
+//   FrameMeterStop()                   // records the frame
+//   (grading, logging: outside the bracket)
+//   FrameMeterPrint()
+//   jmp loop
+//   ...
+// frame_meter:                        // this label is required: the macros jsr into it
+//   FrameMeterCode($0400, 24, 20, 1, 144)   // screen, row, column, colour, hold
+//
+// Work split over a frame is summed: FrameMeterStart() ... FrameMeterPause()
+// as often as needed, then FrameMeterStop() (or FrameMeterEnd() after a
+// Pause) once a frame. Brackets must not nest.
+//
+// It uses no zero page: A, X and Y are clobbered by Init, Pause, Stop, End and
+// Print; Start clobbers A. The flags are not preserved.
+// Unless AUTOPILOT or FRAME_METER is defined (KickAssembler -define), every
+// macro emits nothing, so a release build carries none of it.
+
+#if AUTOPILOT || FRAME_METER
+
+.macro FrameMeterInit() { jsr frame_meter.fm_init }
+.macro FrameMeterStart() {
+    lda #$11                    // force-load $FFFF, start, count phi2
+    sta $dd0e
+}
+.macro FrameMeterPause() { jsr frame_meter.fm_pause }
+.macro FrameMeterStop() { jsr frame_meter.fm_stop }
+.macro FrameMeterEnd() { jsr frame_meter.fm_frame }
+.macro FrameMeterPrint() { jsr frame_meter.fm_print }
+
+// Stops timer A, then raw = $FFFF - count; saturates at $FFFF when the
+// timer passed zero (bit 0 of $DD0D, cleared by the read).
+.macro fm_stop_and_read(fm_raw) {
+    lda #$00
+    sta $dd0e
+    sec
+    lda #$ff
+    sbc $dd04
+    sta fm_raw
+    lda #$ff
+    sbc $dd05
+    sta fm_raw+1
+    lda $dd0d
+    and #$01
+    beq !+
+    lda #$ff
+    sta fm_raw
+    sta fm_raw+1
+!:
+}
+
+.macro FrameMeterCode(screen, row, col, colour, hold) {
+    .errorif (hold < 1 || hold > 255), "FrameMeterCode: hold must be 1 to 255 frames"
+    .var cell = screen + 40*row + col
+    .var tint = $d800 + 40*row + col
+
+fm_init:
+    ldx #19
+    lda #colour
+!:  sta tint,x
+    dex
+    bpl !-
+    lda #$01                    // mask timer A's NMI (bit 7 clear: clear this mask bit only)
+    sta $dd0d
+    lda #$00
+    sta $dd0e
+    lda #$ff                    // the latch every FrameMeterStart reloads
+    sta $dd04
+    sta $dd05
+    sta fm_zero
+    sta fm_zero+1
+    lda $dd0d                   // clear a stale underflow flag
+    php                         // no interrupt inside the calibration
+    sei
+    lda #4                      // the empty bracket, four times at line 0 (no DMA there);
+    sta fm_try                  // the least count is the bracket's own cost
+fm_cal:
+!:  lda $d012
+    beq !-
+!:  lda $d012
+    bne !-
+    lda #$11                    // the same code as Start and Stop
+    sta $dd0e
+    jsr fm_read
+    lda fm_raw
+    cmp fm_zero
+    lda fm_raw+1
+    sbc fm_zero+1
+    bcs !+
+    lda fm_raw
+    sta fm_zero
+    lda fm_raw+1
+    sta fm_zero+1
+!:  dec fm_try
+    bne fm_cal
+    plp
+    lda #0
+    ldx #fm_vars_end - fm_vars - 1
+!:  sta fm_vars,x
+    dex
+    bpl !-
+    rts
+
+fm_read:
+    fm_stop_and_read(fm_raw)
+    rts
+
+// acc += raw - zero, saturating at $FFFF: a frame whose brackets sum past
+// 65,535 cycles reads 65,535, not the sum modulo 65,536
+fm_pause:
+    fm_stop_and_read(fm_raw)
+fm_accumulate:
+    sec
+    lda fm_raw
+    sbc fm_zero
+    tax
+    lda fm_raw+1
+    sbc fm_zero+1
+    tay
+    clc
+    txa
+    adc fm_acc
+    sta fm_acc
+    tya
+    adc fm_acc+1
+    sta fm_acc+1
+    bcc !+
+    lda #$ff
+    sta fm_acc
+    sta fm_acc+1
+!:  rts
+
+fm_stop:
+    fm_stop_and_read(fm_raw)
+    jsr fm_accumulate
+// Records the frame's sum, once a frame.
+fm_frame:
+    lda fm_frames
+    cmp #hold
+    bcs fm_clear                // recording stopped
+    tax
+    lda fm_acc
+    sta fm_lo,x
+    sta fm_last
+    lda fm_acc+1
+    sta fm_hi,x
+    sta fm_last+1
+    lda fm_worst+1              // worst = max(worst, last)
+    cmp fm_last+1
+    bcc fm_newworst
+    bne fm_count
+    lda fm_worst
+    cmp fm_last
+    bcs fm_count
+fm_newworst:
+    lda fm_last
+    sta fm_worst
+    lda fm_last+1
+    sta fm_worst+1
+fm_count:
+    inc fm_frames
+    lda fm_frames
+    cmp #hold
+    bne fm_clear
+    jsr fm_sort                 // recording ends: typical = the median
+    ldx #hold/2
+    lda fm_lo,x
+    sta fm_typical
+    lda fm_hi,x
+    sta fm_typical+1
+fm_clear:
+    lda #0
+    sta fm_acc
+    sta fm_acc+1
+    rts
+
+// Insertion sort of fm_lo/fm_hi[0 .. hold-1], ascending.
+fm_sort:
+    ldx #1
+fm_si:
+    cpx #hold
+    bcs fm_sorted
+    lda fm_lo,x
+    sta fm_klo
+    lda fm_hi,x
+    sta fm_khi
+    txa
+    tay
+fm_sj:
+    cpy #0
+    beq fm_ins
+    lda fm_klo                  // key >= a[j-1]: insert here
+    cmp fm_lo-1,y
+    lda fm_khi
+    sbc fm_hi-1,y
+    bcs fm_ins
+    lda fm_lo-1,y
+    sta fm_lo,y
+    lda fm_hi-1,y
+    sta fm_hi,y
+    dey
+    jmp fm_sj
+fm_ins:
+    lda fm_klo
+    sta fm_lo,y
+    lda fm_khi
+    sta fm_hi,y
+    inx
+    jmp fm_si
+fm_sorted:
+    rts
+
+fm_print:
+    ldy #0
+    lda #6                      // screen code 6 = F
+    ldx #0                      // frames
+    jsr fm_put5
+    lda #23                     // W
+    ldx #2                      // worst
+    jsr fm_put5
+    lda #20                     // T
+    ldx #4                      // typical
+    jsr fm_put5
+    rts
+
+// A = letter, X = offset of the value in fm_shown, Y = cell index.
+// Writes letter, five digits and a space; Y advances by 7.
+fm_put5:
+    sta cell,y
+    iny
+    lda fm_shown,x
+    sta fm_v
+    lda fm_shown+1,x
+    sta fm_v+1
+    ldx #0
+fm_digit:
+    lda #$30
+    sta fm_d
+!:  lda fm_v                    // while v >= pow10[x]: v -= pow10[x]; d++
+    cmp fm_p10_lo,x
+    lda fm_v+1
+    sbc fm_p10_hi,x
+    bcc !+
+    sta fm_v+1
+    lda fm_v
+    sbc fm_p10_lo,x
+    sta fm_v
+    inc fm_d
+    jmp !-
+!:  lda fm_d
+    sta cell,y
+    iny
+    inx
+    cpx #4
+    bne fm_digit
+    lda fm_v
+    ora #$30
+    sta cell,y
+    iny
+    cpy #20
+    bcs !+
+    lda #$20
+    sta cell,y
+    iny
+!:  rts
+
+fm_p10_lo: .byte <10000, <1000, <100, <10
+fm_p10_hi: .byte >10000, >1000, >100, >10
+fm_raw:    .word 0
+fm_zero:   .word 0
+fm_v:      .word 0
+fm_d:      .byte 0
+fm_try:    .byte 0
+fm_klo:    .byte 0
+fm_khi:    .byte 0
+fm_vars:
+fm_shown:
+fm_frames:  .word 0
+fm_worst:   .word 0
+fm_typical: .word 0
+fm_last:    .word 0
+fm_acc:     .word 0
+fm_vars_end:
+fm_lo:      .fill hold, 0
+fm_hi:      .fill hold, 0
+}
+
+#else
+
+.macro FrameMeterInit() {}
+.macro FrameMeterStart() {}
+.macro FrameMeterPause() {}
+.macro FrameMeterStop() {}
+.macro FrameMeterEnd() {}
+.macro FrameMeterPrint() {}
+.macro FrameMeterCode(screen, row, col, colour, hold) {}
+
+#endif

package/templates/_harness/meter/frame_meter.c

@@ -0,0 +1,155 @@
+// frame_meter.c: see frame_meter.h for the contract.
+#include "frame_meter.h"
+#include <c64/vic.h>
+
+unsigned meter_last, meter_worst, meter_typical, meter_frames, meter_zero;
+
+#if FRAME_METER
+
+static unsigned sample[255];                    // one per recorded frame
+static unsigned acc;                            // this frame's sum so far
+static char hold_at;
+static char *cell;                              // first screen cell of the readout
+
+// Stops the timer before reading, so the two byte reads cannot straddle a
+// borrow. Bit 0 of $DD0D says the timer passed zero since the last read:
+// more than 65,535 cycles, so the count saturates. Reading $DD0D clears it.
+__noinline unsigned meter_read(void)
+{
+    cia2.cra = 0x00;
+    unsigned t = 0xffff - cia2.ta;
+    if (cia2.icr & 0x01)
+        t = 0xffff;
+    return t;
+}
+
+void meter_init(unsigned screen, char row, char col, char colour, char hold)
+{
+    unsigned off = 40 * row + col;
+    cell = (char *)(screen + off);
+    char *tint = (char *)(0xd800 + off);
+    for (char i = 0; i < 20; i++)
+        tint[i] = colour;
+    hold_at = hold ? hold : 1;
+    cia2.icr = 0x01;                            // mask timer A's NMI (bit 7 clear: clear this mask bit only)
+    cia2.cra = 0x00;
+    cia2.ta = 0xffff;                           // the latch every METER_START reloads
+    acc = cia2.icr;                             // read to clear a stale underflow flag
+    meter_zero = 0xffff;
+    __asm volatile { php
+                     sei }                      // no interrupt inside the calibration
+    for (char k = 0; k < 4; k++)                // the empty bracket, at line 0: no DMA there
+    {
+        while (vic.raster == 0) ;
+        while (vic.raster != 0) ;
+        METER_START;
+        unsigned z = meter_read();
+        if (z < meter_zero)
+            meter_zero = z;
+    }
+    __asm volatile { plp }
+    meter_last = meter_worst = meter_typical = meter_frames = 0;
+    acc = 0;
+}
+
+// Saturates at 65,535: a frame whose brackets sum past it reads 65,535,
+// not the sum modulo 65,536.
+void meter_add(unsigned raw)
+{
+    unsigned d = raw - meter_zero;
+    if (acc > 65535u - d)
+        acc = 65535u;
+    else
+        acc += d;
+}
+
+// The median of the recorded frames by selection (Wirth's FIND, a
+// quicksort that follows only the half holding the middle): a few hundred
+// compares for 255 frames. The insertion sort it replaces took n * n / 4 and
+// held a platformer's main loop for about 94 frames (1.85M cycles) at the
+// moment recording stopped. Same value: the element a full sort would put
+// in the middle.
+static unsigned select_median(void)
+{
+    int lo = 0, hi = hold_at - 1, k = hold_at >> 1;
+    while (lo < hi)
+    {
+        unsigned x = sample[k];
+        int i = lo, j = hi;
+        do
+        {
+            while (sample[i] < x)
+                i++;
+            while (x < sample[j])
+                j--;
+            if (i <= j)
+            {
+                unsigned t = sample[i];
+                sample[i] = sample[j];
+                sample[j] = t;
+                i++;
+                j--;
+            }
+        } while (i <= j);
+        if (j < k)
+            lo = i;
+        if (k < i)
+            hi = j;
+    }
+    return sample[k];
+}
+
+void meter_frame(void)
+{
+    unsigned t = acc;
+    acc = 0;
+    if (meter_frames >= hold_at)
+        return;
+    meter_last = t;
+    if (t > meter_worst)
+        meter_worst = t;
+    sample[meter_frames++] = t;
+    if (meter_frames == hold_at)
+        meter_typical = select_median();
+}
+
+void meter_stop(unsigned raw)
+{
+    meter_add(raw);
+    meter_frame();
+}
+
+static const unsigned pow10[4] = {10000, 1000, 100, 10};
+
+static char *put5(char *p, char letter, unsigned v)
+{
+    *p++ = letter;
+    for (char i = 0; i < 4; i++)
+    {
+        char d = 0x30;
+        while (v >= pow10[i]) { v -= pow10[i]; d++; }
+        *p++ = d;
+    }
+    *p++ = 0x30 + (char)v;
+    return p;
+}
+
+void meter_print(void)
+{
+    char *p = put5(cell, 6, meter_frames);      // screen code 6 = F
+    *p++ = 0x20;
+    p = put5(p, 23, meter_worst);               // 23 = W
+    *p++ = 0x20;
+    put5(p, 20, meter_typical);                 // 20 = T
+}
+
+#else
+
+unsigned meter_read(void) { return 0; }
+void meter_init(unsigned screen, char row, char col, char colour, char hold) {}
+void meter_add(unsigned raw) {}
+void meter_frame(void) {}
+void meter_stop(unsigned raw) {}
+void meter_print(void) {}
+
+#endif

package/templates/_harness/meter/frame_meter.h

@@ -0,0 +1,80 @@
+// frame_meter.h: CIA2 timer A frame meter for Oscar64 starters.
+//
+//   meter_init(0x0400, 24, 20, 1, 144);   // screen, row, column, colour, frames to record
+//   for (;;) {
+//       wait_frame();
+//       METER_START;
+//       ... one frame of work ...
+//       METER_STOP;                        // records this frame
+//       ... grading, logging: outside the bracket ...
+//       meter_print();
+//   }
+//
+// Work split over several places in a frame (a main loop and IRQ handlers)
+// is summed: METER_START ... METER_PAUSE as often as needed, and
+// METER_STOP (or meter_frame()) once, to record the frame's sum. Brackets
+// must not nest: an IRQ that brackets its own work must not land inside
+// another bracket.
+//
+// It times with CIA2 timer A counting phi2 cycles, so a figure is wall
+// time: badline and sprite DMA steals and any interrupt that lands inside a
+// bracket are counted. The empty bracket's own count is measured at init
+// (the least of four tries, each at raster line 0, where no DMA falls) and
+// subtracted from every bracket.
+//
+// frames  = frames recorded. Recording stops at `hold` (1 to 255): make hold
+//           the play frames of the autopilot script, so no idle frame counts.
+// worst   = the largest recorded frame.
+// typical = the median of the recorded frames, found by selection when recording
+//           stops (0 until then): a cost some play frame actually took, with
+//           at least half the frames at or under it. This is the KB's
+//           cycles_per_frame_typical (CONVENTIONS-techniques.md) when the
+//           recorded frames are play.
+//
+// meter_print writes "F00144 W01234 T01100" (20 cells) at the row and column
+// given; the character set in use must hold 0-9, F, W and T at their screen
+// codes. check.py reads it back.
+//
+// Timer choice: CIA2 timer A. The KERNAL IRQ uses CIA1 timer A and the KERNAL
+// serial (disk) routines write CIA1 timer B (issue #35), so neither collides.
+// CIA2 timer A is the KERNAL's RS-232 bit timer: do not open device 2 while
+// the meter runs. meter_init masks timer A's NMI only ($DD0D = $01) and
+// leaves CIA2's other sources as they were.
+//
+// FRAME_METER defaults to AUTOPILOT: in a build without it the macros and
+// meter_print compile to nothing and the release carries none of it. Build
+// with -dFRAME_METER=1 to keep the meter in a manual build.
+#ifndef FRAME_METER_H
+#define FRAME_METER_H
+
+#include <c64/cia.h>
+
+#ifndef AUTOPILOT
+#define AUTOPILOT 0
+#endif
+#ifndef FRAME_METER
+#define FRAME_METER AUTOPILOT
+#endif
+
+extern unsigned meter_last, meter_worst, meter_typical, meter_frames, meter_zero;
+
+void meter_init(unsigned screen, char row, char col, char colour, char hold);
+unsigned meter_read(void);
+void meter_add(unsigned raw);
+void meter_frame(void);
+void meter_stop(unsigned raw);
+void meter_print(void);
+
+#if FRAME_METER
+#define METER_START (cia2.cra = 0x11)          // force-load $FFFF, start, count phi2
+#define METER_PAUSE meter_add(meter_read())    // add this bracket to the frame's sum
+#define METER_STOP  meter_stop(meter_read())   // add it, then record the frame
+#else
+#define METER_START
+#define METER_PAUSE
+#define METER_STOP
+#endif
+
+#pragma compile("frame_meter.c")
+
+#endif

package/templates/_harness/zp-used.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""zp-used.py: the zero-page addresses an Oscar64 program's code touches.
+
+usage: zp-used.py build/NAME.asm [--claim '$02-$52']
+
+Reads the listing Oscar64 writes beside the PRG. Every instruction there is
+a line "addr : b0 b1 b2 MNEMONIC operand"; one whose third byte is "__" is
+two bytes long, and a two-byte instruction that is not immediate ("#") and
+not a branch addresses zero page through its second byte (zp, zp,x, zp,y,
+(zp,x), (zp),y). The BASIC stub at $0801-$080C decodes as instructions and
+is skipped.
+
+Why a measurement and not a constant: Oscar64 places its fixed registers at
+$02-$26 and each function's temporaries from $43 up by that function's temp
+count (oscar64/MachineTypes.cpp and InterCode.cpp, read); temps past
+BC_REG_TMP_SAVED ($53) are saved and restored around calls, but they are
+still zero page. So the top of the range grows with the largest function,
+and only the program's own listing says where it is.
+
+It sees the compiled C and inline __asm only: bytes embedded from a
+KickAssembler blob are data in the listing (BYT lines), so a blob's zero
+page is whatever its own source uses.
+
+$00 and $01 are the 6510's own port (direction and data), not work bytes;
+they are listed on their own line and never judged against a claim. The
+startup's zero-page clear is a store indexed from $00, which is why $00
+shows up in every build.
+
+With --claim, exits 1 when the program touches an address from $02 up
+outside the claimed ranges (comma-separated $lo-$hi or $addr), and names
+them.
+"""
+import re
+import sys
+
+LINE = re.compile(r"^\s*([0-9a-f]{4}) : ([0-9a-f]{2}) ([0-9a-f]{2}|__) (__|[0-9a-f]{2}) ([A-Z]{3})\b\s*(.*)$")
+BRANCHES = {"BPL", "BMI", "BVC", "BVS", "BCC", "BCS", "BNE", "BEQ"}
+STUB_END = 0x080D
+
+
+def used(path):
+    out = {}
+    for line in open(path, encoding="latin-1"):
+        m = LINE.match(line)
+        if not m:
+            continue
+        addr, _op, b1, b2, mnem, operand = m.groups()
+        if int(addr, 16) < STUB_END or b2 != "__" or b1 == "__":
+            continue
+        if mnem in BRANCHES or operand.startswith("#"):
+            continue
+        out.setdefault(int(b1, 16), mnem)
+    return out
+
+
+def ranges(addrs):
+    rs, start, prev = [], None, None
+    for a in sorted(addrs):
+        if start is None:
+            start = prev = a
+        elif a == prev + 1:
+            prev = a
+        else:
+            rs.append((start, prev))
+            start = prev = a
+    if start is not None:
+        rs.append((start, prev))
+    return rs
+
+
+def parse_claim(text):
+    claimed = set()
+    for part in text.split(","):
+        part = part.strip().replace("$", "")
+        if not part:
+            continue
+        lo, _, hi = part.partition("-")
+        claimed.update(range(int(lo, 16), int(hi or lo, 16) + 1))
+    return claimed
+
+
+def main(argv):
+    if not argv:
+        print(__doc__.strip().splitlines()[2], file=sys.stderr)
+        return 2
+    found = used(argv[0])
+    port = sorted(a for a in found if a < 2)
+    addrs = {a: m for a, m in found.items() if a >= 2}
+    text = ", ".join(f"${a:02X}" if a == b else f"${a:02X}-${b:02X}" for a, b in ranges(addrs))
+    print(f"zero page used by the code in {argv[0]}: {text or '(none)'}")
+    if port:
+        print("6510 port (not judged): " + ", ".join(f"${a:02X} ({found[a]})" for a in port))
+    if "--claim" in argv:
+        claim = argv[argv.index("--claim") + 1]
+        outside = sorted(set(addrs) - parse_claim(claim))
+        if outside:
+            print("outside the claim " + claim + ": " + ", ".join(f"${a:02X} ({addrs[a]})" for a in outside))
+            return 1
+        print(f"all inside the claim {claim}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/templates/action-puzzle/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "h=\"$CLAUDE_PROJECT_DIR/harness/hooks/plan-gate.py\"; [ -f \"$h\" ] || h=\"$CLAUDE_PROJECT_DIR/../_harness/hooks/plan-gate.py\"; exec python3 \"$h\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/action-puzzle/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "c64-kb": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["../../dist/cli.js", "serve"],
+      "env": {}
+    }
+  }
+}