c64-kb 0.17.0

package/docs/recipes/kickassembler/cia-revision-detect.md

@@ -0,0 +1,366 @@
+---
+recipe: cia-revision-detect
+toolchain: kickassembler
+output_format: PRG
+region: both
+techniques: []
+file_formats: [PRG]
+uses_registers: [DC04, DC05, DC06, DC07, DC0D, DC0E, DC0F, D011, D012, D020]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# KickAssembler — Detect the CIA revision from its interrupt latency
+
+## Synopsis
+
+Tells an old 6526 from a 6526A or 8521 at CIA1 by measuring how many
+cycles pass between a Timer A underflow and the first instruction of the
+interrupt handler. Timer B free-runs from `$FFFF` as the clock; the
+handler's first instruction reads it. The old part raises its interrupt
+one cycle later than the new one, and against a run of 2-cycle `NOP`s
+that shows as a pair of readings the program can classify. The result
+goes to `$02FE` (`00` old 6526, `01` new 8521 or 6526A, `FF` neither
+signature) and the verdict to `$02FF` and the border. Use it once at
+start-up, before a raster routine or a loader that counts on the CIA's
+cycle-exact interrupt timing. The pitfall it serves is
+`cia_revision_irq_one_cycle_late` in `pitfalls/cia.md`.
+
+## Source
+
+```asm
+// cia-revision-detect.asm
+// Detects which CIA revision sits at CIA1 by measuring how many cycles
+// pass between a Timer A underflow and the first instruction of the IRQ
+// handler. Timer B free-runs from $FFFF as the clock. The test runs at
+// two phases (Timer A latch $40 and $41) against a run of 2-cycle NOPs:
+// on VICE's old 6526 the pair reads $12/$11, on its new 8521 $10/$11.
+// Result byte at $02FE: 0 = old 6526, 1 = new 8521 / 6526A, $FF = neither
+// signature. $02FF = 1 and a green border when a signature matched,
+// 2 and red otherwise.
+.encoding "screencode_upper"
+
+.const SCREEN   = $0400
+.const BASE     = $40
+.const REVISION = $02fe
+.const RESULT   = $02ff
+.const zp_ph    = $fb        // phase index 0 or 1
+.const zp_flag  = $fc        // handler sets to 1
+.const txt_ptr  = $fd        // verdict text pointer
+
+BasicUpstart2(start)
+
+* = $0900 "code"
+
+start:
+    sei
+    lda #$35
+    sta $01                  // I/O in, KERNAL and BASIC out
+    lda #<irq
+    sta $fffe
+    lda #>irq
+    sta $ffff
+    lda #<nmi
+    sta $fffa
+    lda #>nmi
+    sta $fffb
+    lda #$7f
+    sta $dc0d
+    sta $dd0d
+    lda $dc0d
+    lda $dd0d
+    lda #$00
+    sta $d01a
+    lda #$ff
+    sta $d019
+    lda #$00
+    sta $d015
+    lda #$0b
+    sta $d011                // DEN = 0: no badlines while measuring
+    lda #$00
+    sta $d020
+    sta $d021
+    jsr clear_screen
+    jsr wait_frame
+    jsr wait_frame
+
+    lda #$00
+    sta zp_ph
+phase_loop:
+    jsr arm_timers
+    lda zp_ph
+    clc
+    adc #BASE
+    sta $dc04                // Timer A latch = $40 + phase
+    lda #$00
+    sta $dc05
+    sta zp_flag
+    lda #$81
+    sta $dc0d                // Timer A may interrupt
+    lda #$40
+sync:
+    cmp $d012
+    bne sync
+    cli
+    lda #$11
+    ldx #$19
+    sta $dc0f                // Timer B: continuous, load, start
+    stx $dc0e                // Timer A: one-shot, load, start, 4 cycles later
+    .fill 200, $ea           // the IRQ lands in these NOPs
+    sei
+    lda zp_flag
+    beq unknown
+    inc zp_ph
+    lda zp_ph
+    cmp #$02
+    beq classify
+    jmp phase_loop
+
+classify:
+    // lat[k] = ($FF - TBlo) - ($40 + k): the phase-0 value decides
+    lda #$ff
+    sec
+    sbc tb_lo
+    sec
+    sbc #BASE
+    sta lat
+    lda #$ff
+    sec
+    sbc tb_lo+1
+    sec
+    sbc #BASE+1
+    sta lat+1
+    cmp #$11
+    bne unknown              // the odd phase reads $11 on both models
+    lda lat
+    cmp #$12
+    beq old_cia
+    cmp #$10
+    bne unknown
+    lda #$01
+    sta REVISION
+    ldx #<txt_new
+    ldy #>txt_new
+    jmp report
+old_cia:
+    lda #$00
+    sta REVISION
+    ldx #<txt_old
+    ldy #>txt_old
+    jmp report
+unknown:
+    lda #$ff
+    sta REVISION
+    ldx #<txt_unknown
+    ldy #>txt_unknown
+    jsr show
+    lda #$02
+    sta $d020
+    sta RESULT
+    jmp hang
+report:
+    jsr show
+    lda #$05
+    sta $d020
+    lda #$01
+    sta RESULT
+hang:
+    jmp hang
+
+irq:
+    lda $dc06                // the read is this instruction's 4th cycle
+    ldx zp_ph
+    sta tb_lo,x
+    lda $dc0d                // acknowledge
+    lda #$01
+    sta zp_flag
+    rti
+
+nmi:
+    rti
+
+arm_timers:
+    lda #$00
+    sta $dc0e
+    sta $dc0f
+    lda #$7f
+    sta $dc0d
+    lda $dc0d
+    lda #$ff
+    sta $dc06
+    sta $dc07                // Timer B latch $FFFF
+    rts
+
+wait_frame:
+    lda $d012
+    bne wait_frame
+    lda $d011
+    bmi wait_frame
+!:  lda $d012
+    beq !-
+    rts
+
+clear_screen:
+    ldx #$00
+    lda #$20
+!:  sta SCREEN,x
+    sta SCREEN+$100,x
+    sta SCREEN+$200,x
+    sta SCREEN+$300,x
+    inx
+    bne !-
+    ldx #$00
+    lda #$01
+!:  sta $d800,x
+    sta $d900,x
+    sta $da00,x
+    sta $db00,x
+    inx
+    bne !-
+    rts
+
+// X/Y = verdict text. Row 0: title. Row 2: the two latency bytes.
+// Row 4: the verdict.
+show:
+    stx txt_ptr
+    sty txt_ptr+1
+    lda #$1b
+    sta $d011                // display back on
+    ldx #$00
+!:  lda txt_title,x
+    beq !+
+    sta SCREEN,x
+    inx
+    bne !-
+!:  lda lat
+    ldy #$00
+    jsr put_hex
+    lda lat+1
+    ldy #$03
+    jsr put_hex
+    ldy #$00
+!:  lda (txt_ptr),y
+    beq !+
+    sta SCREEN+160,y
+    iny
+    bne !-
+!:  rts
+
+put_hex:                     // A = byte, Y = column on row 2
+    pha
+    lsr
+    lsr
+    lsr
+    lsr
+    tax
+    lda hexdig,x
+    sta SCREEN+80,y
+    iny
+    pla
+    and #$0f
+    tax
+    lda hexdig,x
+    sta SCREEN+80,y
+    rts
+
+hexdig:      .text "0123456789ABCDEF"
+txt_title:   .text "CIA1 IRQ LATENCY, PHASES 0 AND 1:"
+             .byte 0
+txt_old:     .text "OLD 6526: IRQ ONE CYCLE LATER (02FE=00)"
+             .byte 0
+txt_new:     .text "NEW 8521 OR 6526A (02FE=01)"
+             .byte 0
+txt_unknown: .text "NO KNOWN SIGNATURE (02FE=FF)"
+             .byte 0
+tb_lo:       .byte 0, 0
+lat:         .byte 0, 0
+```
+
+## Build
+
+```bash
+java -jar $KICKASS_JAR cia-revision-detect.asm -o cia-revision-detect.prg
+```
+
+KickAssembler 5.25 produces a 1,019-byte PRG; the code segment runs
+`$0900` to `$0BF9`.
+
+Pinned VICE run (both models, `docs/recipes/runs.json`):
+
+```bash
+GSETTINGS_SCHEMA_DIR=/opt/homebrew/share/glib-2.0/schemas \
+x64sc -default -warp +sound +autostart-delay-random -autostartprgmode 1 \
+      -limitcycles 8000000 -ciamodel 0 \
+      -exitscreenshot cia-revision-detect.png -autostart cia-revision-detect.prg
+```
+
+Add `-model ntsc` for the second picture. `-ciamodel 0` selects VICE's
+old 6526 for both CIAs (`1` is the new 8521; the names and values are
+from `x64sc -help`, VICE 3.10). The pin uses the old part because it is
+not the PAL default: a run with no `-ciamodel` flag reads as the new
+part on the PAL default (VICE's C64C) and on `-model c64c`, so a picture
+of it would not show the flag doing anything. The default depends on the
+model: with no flag, `-model c64` and `-model ntsc` read `12 11`, the old
+part, and `-model newntsc` reads `10 11`, the new one (measured in VICE
+x64sc 3.10). An earlier version of this paragraph
+said a run with no flag reads as the new part, without naming the model.
+
+## Expected output
+
+Green border, black background, white text:
+
+```text
+row 0  CIA1 IRQ LATENCY, PHASES 0 AND 1:
+row 2  12 11
+row 4  OLD 6526: IRQ ONE CYCLE LATER (02FE=00)
+```
+
+`recipes/kickassembler/screenshots/cia-revision-detect.png` (PAL, 384 by
+272) and `cia-revision-detect-ntsc.png` (NTSC, 384 by 247) were each
+produced three times by the pinned command with identical bytes, and
+decoded by matching every 8 by 8 cell against `chargen-901225-01.bin`
+(measured in VICE x64sc 3.10, rung 1). With `-ciamodel 1` instead, on
+either model, row 2 reads `10 11` and row 4 `NEW 8521 OR 6526A
+(02FE=01)`, border green. `$02FF` is `01` in all four cases. The
+verdict is internal: the pair of readings matched one of the two
+signatures. Which one it matched is what the command line set, and the
+picture shows it.
+
+Row 2 is the number of Timer B counts between the start of the test and
+the handler's read, less the Timer A latch, for the latch `$40` and then
+`$41`. The two models differ at the even phase by two cycles and agree
+at the odd one; averaged over both phases the old part is one cycle
+later, which is the mechanism, and the 2-cycle `NOP` boundary is why it
+shows as 0 or 2 rather than 1. The eight-phase form of the same
+measurement is in `pitfalls/cia.md`, `cia_revision_irq_one_cycle_late`.
+
+## Why this works
+
+The measurement needs a fixed instruction stream from the timer start
+to the handler's first read, so nothing may steal a cycle: the display
+is blanked (`$D011` bit 4 clear) two frames ahead so no badline occurs,
+sprites are off, and the KERNAL is banked out so the hardware vector at
+`$FFFE` goes straight to the handler with no dispatcher in the way. The
+`$D012` wait only orders the test within the frame; with no badlines
+the CIA figures do not depend on the raster position, and the PAL and
+NTSC pictures agree.
+
+Two writes start the clocks four cycles apart: `sta $DC0F` starts Timer
+B counting down from `$FFFF`, `stx $DC0E` starts Timer A one-shot from
+the latch. When Timer A underflows the chip sets ICR bit 0 and, with
+the mask set, pulls `/IRQ`. The 6510 finishes the `NOP` it is in, runs
+its seven-cycle interrupt sequence and fetches the handler's `lda
+$DC06`, whose fourth cycle reads the low byte of Timer B. `$FF` less
+that byte, less the latch, is the figure on screen. Everything in that
+path is fixed except the CIA's own delay between underflow and `/IRQ`,
+and the 6510 samples `/IRQ` once per instruction, so a one-cycle change
+in the CIA either changes nothing or costs a whole `NOP`. Running two
+latches one apart puts one test on each side of that boundary, which
+is why the odd phase reads the same on both parts and the even one
+tells them apart.
+
+The classifier compares against the two pairs measured in VICE. A pair
+that matches neither reports `$FF`; on hardware this recipe has not
+been run, and a machine that gives a third pair is telling you
+something this page does not know.

package/docs/recipes/kickassembler/colour-cycling.md

@@ -0,0 +1,343 @@
+---
+recipe: colour-cycling
+toolchain: kickassembler
+output_format: PRG
+region: both
+techniques: [colour_cycling]
+file_formats: [PRG]
+uses_registers: [D012, D020, D021, DC04, DC05, DC0D, DC0E]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# KickAssembler — Colour Cycling
+
+## Synopsis
+
+Eight text rows of reverse spaces whose colour RAM is rewritten every second
+frame from a rotating eight-colour table, so a blue, light blue, cyan and
+white band runs down the screen without a screen-RAM write. The rewrite is
+320 stores, landed in the lower border by a busy-wait on $D012, and CIA1
+timer A times it; the last cost is printed on row 0 in hex beside the
+current phase. After 100 frames the program grades itself: `$02FF` is `$01`
+with a green border if the phase is the one 100 frames must produce and no
+rewrite went over 4,000 cycles, else `$02` with a red border. The cycling
+carries on after the verdict, so the pinned screenshot shows the band in
+mid-rotation under a green border. Use it as the template for water, a
+conveyor or a glow, or to cycle sprite colours or a `$D021` triple instead
+of colour RAM.
+
+## Source
+
+```asm
+// colour-cycling.asm
+// Eight text rows of reverse spaces whose colour RAM is rewritten every
+// second frame from a rotating eight-colour table, so a band of colour
+// runs down the screen. CIA1 timer A times each rewrite; the cost of the
+// last one is printed on row 0 in hex, with the current phase. After
+// FRAMES frames the program grades itself: $02FF is $01 with a green
+// border if the phase is the one that many frames must produce and no
+// rewrite took more than BUDGET cycles, else $02 with a red border. The
+// cycling carries on after the verdict, so a late screenshot shows the
+// effect in progress under the verdict border.
+
+.const SCREEN          = $0400
+.const COLOUR          = $d800
+.const SYNC_LINE       = 251         // first line of the lower border, both models
+.const FRAMES_PER_STEP = 2
+.const BAND_TOP        = 8           // first band row
+.const BAND_ROWS       = 8
+.const FRAMES          = 100         // verdict after this many frames
+.const EXPECT_PHASE    = (FRAMES / FRAMES_PER_STEP) & 7
+.const BUDGET          = 4000        // cycles one rewrite may take
+.const RESULT          = $02ff       // verdict byte read by a harness
+.const COST_COL        = 21          // "$xxxx" on row 0
+.const PHASE_COL       = 34
+
+BasicUpstart2(start)
+
+// CIA1 timer A as a stopwatch, phi2 clock, counting down from $FFFF.
+.macro t_start() {
+    lda #$00
+    sta $dc0e
+    lda #$ff
+    sta $dc04
+    sta $dc05
+    lda #$11                         // force load, start, count phi2
+    sta $dc0e
+}
+.macro t_stop(addr) {
+    lda #$00
+    sta $dc0e
+    sec
+    lda #$ff
+    sbc $dc04
+    sta addr
+    lda #$ff
+    sbc $dc05
+    sta addr + 1
+}
+
+* = $0900
+start:
+    sei                              // no KERNAL IRQ: the rewrite must not be interrupted
+    lda #$7f
+    sta $dc0d                        // no CIA1 interrupts: timer A is the stopwatch
+    lda $dc0d
+    lda #$00
+    sta $d020
+    sta $d021
+
+    ldx #$00
+    lda #$20
+!:  sta SCREEN, x                    // clear the screen
+    sta SCREEN + $100, x
+    sta SCREEN + $200, x
+    sta SCREEN + $300, x
+    inx
+    bne !-
+
+    ldx #39                          // caption on row 0, white
+!:  lda caption, x
+    sta SCREEN, x
+    lda #$01
+    sta COLOUR, x
+    dex
+    bpl !-
+
+    lda #$a0                         // the band: reverse spaces, colour RAM shows
+    .for (var r = 0; r < BAND_ROWS; r++) {
+        ldx #39
+    !:  sta SCREEN + (BAND_TOP + r) * 40, x
+        dex
+        bpl !-
+    }
+
+mainloop:
+    lda #SYNC_LINE                   // first leave the sync line: a short pass
+!:  cmp $d012                        // would otherwise fall through twice in it
+    beq !-
+!:  cmp $d012
+    bne !-
+
+    inc frame
+    inc sub
+    lda sub
+    cmp #FRAMES_PER_STEP
+    beq step
+    jmp check
+step:
+    lda #$00
+    sta sub
+    inc phase
+    lda phase
+    and #$07
+    sta phase
+
+    // Rewrite the band: row r takes colour (r + phase) & 7 from the table.
+    t_start()
+    ldy phase
+    .for (var r = 0; r < BAND_ROWS; r++) {
+        lda palette, y                   // palette is 16 long, so no masking
+        ldx #39
+    !:  sta COLOUR + (BAND_TOP + r) * 40, x
+        dex
+        bpl !-
+        iny
+    }
+    t_stop(cost)
+
+    // Keep the largest cost seen.
+    lda cost + 1
+    cmp maxcost + 1
+    bcc show
+    bne newmax
+    lda cost
+    cmp maxcost
+    bcc show
+newmax:
+    lda cost
+    sta maxcost
+    lda cost + 1
+    sta maxcost + 1
+
+show:
+    lda cost + 1                     // "$xxxx": the last rewrite in hex
+    jsr hex_hi
+    sta SCREEN + COST_COL + 1
+    lda cost + 1
+    jsr hex_lo
+    sta SCREEN + COST_COL + 2
+    lda cost
+    jsr hex_hi
+    sta SCREEN + COST_COL + 3
+    lda cost
+    jsr hex_lo
+    sta SCREEN + COST_COL + 4
+    lda phase
+    ora #$30
+    sta SCREEN + PHASE_COL
+
+check:
+    lda done
+    bne back
+    lda frame
+    cmp #FRAMES
+    bne back
+    inc done
+    jmp verdict
+back:
+    jmp mainloop
+
+verdict:
+
+    // Verdict: the phase FRAMES frames must give, and no rewrite over budget.
+    lda phase
+    cmp #EXPECT_PHASE
+    bne fail
+    lda maxcost + 1
+    cmp #>BUDGET
+    bcc pass
+    bne fail
+    lda maxcost
+    cmp #<BUDGET
+    bcs fail
+pass:
+    lda #$01
+    sta RESULT
+    lda #$05
+    sta $d020
+    jmp mainloop
+fail:
+    lda #$02
+    sta RESULT
+    lda #$02
+    sta $d020
+    jmp mainloop
+
+hex_hi:                              // A = byte -> screen code of its high nibble
+    lsr
+    lsr
+    lsr
+    lsr
+hex_lo:                              // A = byte -> screen code of its low nibble
+    and #$0f
+    cmp #$0a
+    bcc !+
+    sbc #$09                         // 10..15 -> screen codes 1..6, "A".."F"
+    rts
+!:  ora #$30                         // 0..9 -> "0".."9"
+    rts
+
+// The eight band colours, written twice so an index of phase + row never
+// needs masking: blue, light blue, cyan, white, cyan, light blue, blue, black.
+palette: .byte 6, 14, 3, 1, 3, 14, 6, 0
+         .byte 6, 14, 3, 1, 3, 14, 6, 0
+
+caption: .text "colour cycling  cost $0000  phase 0     "
+
+frame:   .byte 0
+sub:     .byte 0
+phase:   .byte 0
+done:    .byte 0
+cost:    .word 0
+maxcost: .word 0
+```
+
+## Build
+
+```bash
+java -jar KickAss.jar colour-cycling.asm -o colour-cycling.prg
+```
+
+`-showmem` reports one block at $0900-$0B0C: code, then the sixteen-byte
+palette, the caption and the counters. The PRG is 782 bytes.
+
+## Expected output
+
+Black screen with the caption `COLOUR CYCLING  COST $0CC1  PHASE n` in
+white on row 0. Rows 8 to 15 are each one solid colour across all forty
+columns: row `8 + r` shows `palette[(r + phase) & 7]` where the palette is
+blue, light blue, cyan, white, cyan, light blue, blue, black. Every second
+frame the phase goes up by one, so the band slides up a row: on PAL a full
+turn of eight steps takes sixteen frames, 0.32 s, on NTSC 0.27 s
+(arithmetic from 19,656 and 17,095 cycles a frame). The cost readout is the
+cycles CIA1 timer A counted for the last rewrite, 3,265, the same on both
+models. The border is black until frame 100 and green from then on.
+
+The pinned run is 6,030,000 cycles on both models. Both show phase 5: rows
+8 to 15 are light blue, blue, black, blue, light blue, cyan, white, cyan,
+the border is green and the cost reads `$0CC1`. Measured: every pixel of
+the 24 rows below the caption is the colour that phase gives its cell, no
+mismatches in 61,440 pixels on either model, and the caption decodes cell
+by cell against the char ROM. The verdict store is at cycle 4,933,399 on
+PAL and 4,806,500 on NTSC in the `-moncommands` trace (route 2 of
+`runtime/vice-reference.md`, "Verifying a run without a human"), which put
+the program's first frame near 2,968,000 and 3,097,000 cycles, inside the
+bracket the `colour-fade` recipe measured for the start of a program this
+size.
+
+Why that count. A shot lands in a partly drawn frame, so on a step frame a
+count that puts the beam between the caption and the band shows the new
+phase in the caption over the previous phase in the band. At 6,000,000 PAL
+did exactly that, caption 2 over a band at 1; a sweep in 10,000-cycle
+steps found 6,030,000 consistent on both models, and it is what is pinned.
+A count that lands on a step frame with the beam inside the band would
+tear the band itself; none of the sweep's shots did.
+
+An earlier draft of this listing waited for line 251 with a single
+compare loop. On a frame with no step the work after the wait is under a
+raster line, so the loop fell straight through a second time in the same
+line and the frame counter went up by two: the band stepped every frame,
+not every second one, and the verdict, which counts frames, was taken
+early. The listing now waits to leave line 251 before waiting to reach
+it. That draft's rewrite also read `$0CE8`, 3,304 cycles, against 3,265
+now; the two builds run the same store loop and the 39-cycle difference is
+not established here.
+
+Verified: assembled with KickAssembler 5.25, run in VICE x64sc 3.10 with
+the pinned command twice on each model with byte-identical PNGs, the
+verdict read from a `-moncommands` trace, and the PNGs checked cell by
+cell against the palette formula.
+
+Screenshots from the VICE runs this page describes:
+`screenshots/colour-cycling.png` (PAL) and
+`screenshots/colour-cycling-ntsc.png` (NTSC).
+
+## Why this works
+
+### The rewrite
+
+Each band row is one `STA COLOUR + row * 40, X` loop of forty stores, ten
+cycles a cell, unrolled over the eight rows by a `.for` at assembly time.
+The colour comes from `palette, Y` with `Y` starting at the phase and going
+up by one per row; the table is written twice so `phase + 7` never runs off
+its end. Eight rows are 3,265 cycles by the CIA, about 52 raster lines.
+Started on line 251 the rewrite ends on line 303 on PAL and on line 38 of
+the next frame on NTSC, both before the badline that fetches row 8 on line
+115, so the VIC never reads a half-written band. The same loop over all
+twenty-five rows would take about 10,200 cycles (arithmetic) and cross the
+top of the display on both models: that is the case
+`full_field_redraw_exceeds_vblank` describes.
+
+### The stopwatch and the verdict
+
+CIA1 timer A is loaded with $FFFF and started on the phi2 clock just before
+the rewrite and stopped just after it; $FFFF less the count is the cost.
+CIA1 interrupts are masked first so the timer is only a counter. The
+verdict has two conditions: the phase after 100 frames must be 50 steps
+modulo eight, which is 2, and the largest cost seen must be under the
+4,000-cycle budget. A frame counter that runs fast, as the earlier draft's
+did, fails the first; a rewrite interrupted or stalled fails the second.
+
+### Timing
+
+Interrupts are off and the frame is paced by a busy-wait on line 251, the
+first line of the lower border on both models. The wait is two loops: leave
+the line, then reach it, because the work between waits on a frame with no
+step is shorter than a line. The KERNAL IRQ is left off so no interrupt
+can land inside the rewrite and push its tail into the display. Step
+timing is in frames, so PAL and NTSC show the same phase for a given frame
+and different phases for a given cycle count; 6,030,000 happens to give
+both phase 5.