romdevtools 0.13.0

package/src/platforms/lynx/lib/c/lynx_music.h

@@ -0,0 +1,16 @@
+/* lynx_music.h — demo music bytestream for cc65's lynx_snd_play.
+ *
+ * Note: cc65 declares `void __fastcall__ lynx_snd_play(unsigned char ch,
+ * unsigned char *music)` — the second arg is NON-const. Marking
+ * `demo_music` as `const` causes a "discards qualifiers" warning at
+ * every call site. We keep it non-const here so it matches the cc65
+ * signature; the bytestream is logically read-only (lives in ROM) but
+ * the cc65 API wants a writable pointer. (R56 fix; was const pre-r56.)
+ */
+
+#ifndef LYNX_MUSIC_H
+#define LYNX_MUSIC_H
+
+extern unsigned char demo_music[];
+
+#endif

package/src/platforms/lynx/lib/c/lynx_sfx.c

@@ -0,0 +1,147 @@
+/* lynx_sfx.c — MIKEY 4-voice audio driver for Lynx scaffolds.
+ *
+ * Each MIKEY voice occupies 8 bytes starting at $FD20:
+ *   +0  VOLCNTRL      signed output volume (-128..127)
+ *   +1  FEEDBACK      LFSR feedback taps (which bits XOR back)
+ *   +2  OUTPUT        current LFSR output bit
+ *   +3  SHIFT         LFSR shift register (low 8 bits)
+ *   +4  BACKUP        timer reload value (period)
+ *   +5  CTRL          timer/LFSR control bits
+ *                       bits 0-2 = clock source (000=16us, 111=link)
+ *                       bit 3    = ENABLE_COUNT  ← writing 1 here triggers
+ *                                                   handy to reschedule
+ *                                                   the next timer event
+ *                                                   to NOW (see R57 fix
+ *                                                   below)
+ *                       bit 4    = ENABLE_RELOAD
+ *                       bit 5    = integrate
+ *                       bit 6    = reset done flag
+ *                       bit 7    = waveshaper feedback bit
+ *   +6  COUNTER       current timer value
+ *   +7  OTHER         LFSR shift bits 8..11 + feedback enable
+ *
+ * Voice base: $FD20 + voice*8.
+ *
+ * STEREO ($FD50) bit pattern: bits 0-3 mute left for voice 0-3,
+ *                              bits 4-7 mute right for voice 0-3.
+ *                              Set to 0 = all voices to both speakers.
+ *
+ * ─── R57 fix: defer voice-enable writes to vblank ───────────────────
+ *
+ * Round 29 friction report: calling sfx_tone() during the active frame
+ * intermittently corrupted TGI playfield rendering ("basket + coins
+ * invisible, HUD + score fine"). Reproduces with sfx_init alone in
+ * some builds, deterministically with any sfx_tone call. The agent
+ * tried clearing what they thought was the IRQ bit (bit 3 → bit 4) —
+ * didn't help.
+ *
+ * Root cause (handy mikie.cpp:1668-1680): when a CTL write sets bit 3
+ * (ENABLE_COUNT) OR bit 6 (RESET_DONE), handy executes
+ *   gNextTimerEvent = gSystemCycleCount;
+ * which forces a SYNCHRONOUS timer-event sweep at the next CPU
+ * instruction boundary. That sweep can land mid-Suzy-blit and the
+ * partially-blitted sprite gets clobbered. Result: some draws abort.
+ *
+ * The fix is structural: stage the voice config in shadow RAM
+ * (sfx_pending_*[]) and have sfx_update() write to hardware. Callers
+ * MUST call sfx_update() during vblank — when the blitter is idle —
+ * so the synchronous timer-event sweep lands during vblank with no
+ * visible damage. This matches the cross-platform shape we use
+ * everywhere (sfx_update called once per frame after the wait_vblank).
+ */
+
+#include "lynx_sfx.h"
+
+#define MIKEY_BASE      0xFD00
+#define VOICE_BASE(n)   (0xFD20 + (n) * 8)
+#define MIKEY_STEREO    (*(volatile uint8_t*)0xFD50)
+
+#define POKE(addr, val) (*(volatile uint8_t*)(addr) = (val))
+
+static uint8_t sfx_remaining[4];
+
+/* R57: shadow-RAM trigger queue. sfx_tone / sfx_noise stage their
+ * config here; sfx_update flushes the staged channels to hardware
+ * during the (caller's) vblank window. */
+static uint8_t sfx_pending_kind[4];   /* 0 = no change, 1 = tone, 2 = noise */
+static uint8_t sfx_pending_period[4];
+
+void sfx_init(void) {
+  uint8_t i;
+  MIKEY_STEREO = 0;  /* all voices to both speakers */
+  for (i = 0; i < 4; i++) {
+    POKE(VOICE_BASE(i) + 0, 0);    /* volume 0 */
+    POKE(VOICE_BASE(i) + 5, 0);    /* CTRL off (bit 3 = 0 → no trigger) */
+    sfx_remaining[i] = 0;
+    sfx_pending_kind[i] = 0;
+    sfx_pending_period[i] = 0;
+  }
+}
+
+void sfx_tone(uint8_t channel, uint8_t period, uint8_t length_frames) {
+  if (channel > 3) return;
+  /* Stage only — actual hardware writes happen in sfx_update() during
+   * the caller's vblank, NOT now. See R57 comment block above. */
+  sfx_pending_kind[channel] = 1;
+  sfx_pending_period[channel] = period;
+  sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* Voice 3 reserved for noise. Same staging discipline. */
+  sfx_pending_kind[3] = 2;
+  sfx_remaining[3] = length_frames;
+}
+
+/* Apply any staged voice config to hardware. Call during vblank
+ * (immediately after tgi_updatedisplay or wait_vblank). */
+static void sfx_flush_pending(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    if (sfx_pending_kind[i] == 1) {
+      /* Tone: pure repeating bit, period from staged value. */
+      POKE(VOICE_BASE(i) + 1, 0x80);     /* feedback off */
+      POKE(VOICE_BASE(i) + 4, sfx_pending_period[i]);
+      POKE(VOICE_BASE(i) + 5, 0x18);     /* RELOAD + COUNT + 16us clock */
+      POKE(VOICE_BASE(i) + 0, 64);       /* volume */
+    } else if (sfx_pending_kind[i] == 2) {
+      /* Noise on voice 3. */
+      POKE(VOICE_BASE(i) + 7, 0x01);     /* 12-bit LFSR */
+      POKE(VOICE_BASE(i) + 1, 0x95);     /* classic noise feedback */
+      POKE(VOICE_BASE(i) + 4, 40);
+      POKE(VOICE_BASE(i) + 5, 0x18);
+      POKE(VOICE_BASE(i) + 0, 64);
+    }
+    sfx_pending_kind[i] = 0;
+  }
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  /* R57: flush any sfx_tone/sfx_noise requests from THIS frame. The
+   * caller is expected to have just returned from tgi_updatedisplay
+   * (or wait_vblank), so the synchronous timer-event sweep that handy
+   * triggers on the ENABLE_COUNT write lands during vblank where it
+   * can't damage in-flight Suzy blits. */
+  sfx_flush_pending();
+
+  /* Tick auto-silence countdowns for active voices. */
+  for (i = 0; i < 4; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        POKE(VOICE_BASE(i) + 0, 0);  /* silence */
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    POKE(VOICE_BASE(i) + 0, 0);
+    POKE(VOICE_BASE(i) + 5, 0);    /* CTRL=0 — bit 3 clear, no trigger */
+    sfx_remaining[i] = 0;
+    sfx_pending_kind[i] = 0;
+  }
+}

package/src/platforms/lynx/lib/c/lynx_sfx.h

@@ -0,0 +1,59 @@
+/* lynx_sfx.h — minimal Atari Lynx MIKEY sound-effects wrapper.
+ *
+ * Lynx audio = MIKEY's 4 audio voices ($FD20-$FD3F). Each voice is a
+ * linear-feedback shift register (LFSR) producing pulse/tone/noise
+ * output, with manual volume, period, and LFSR feedback configuration.
+ * No automatic envelope — sfx_update silences after the countdown.
+ *
+ * Same 5-function cross-platform shape:
+ *   sfx_init()
+ *   sfx_tone(channel, period, length_frames)
+ *   sfx_noise(length_frames)
+ *   sfx_update()       — call once per frame DURING VBLANK (mandatory)
+ *   sfx_off()
+ *
+ * channel = 0..3 (4 voices).
+ *
+ * period is the 8-bit timer reload value. Lower = higher pitch.
+ * Hz ≈ 16000000 / 16 / (period+1) / 2.
+ *   period =  80  → ~6 kHz (high pew)
+ *   period = 160  → ~3 kHz (mid blip)
+ *   period = 200  → ~2 kHz (low thump)
+ *
+ * ─── R57 IMPORTANT — call sfx_update() DURING VBLANK ───────────────
+ *
+ * sfx_tone / sfx_noise stage their config in shadow RAM and do NOT
+ * write to MIKEY hardware until sfx_update() runs. The actual MIKEY
+ * writes have to land during vblank because the timer-event
+ * rescheduling triggered by writing the voice CTL register (handy's
+ * `gNextTimerEvent = NOW` on bit 3 / bit 6) can preempt an in-flight
+ * Suzy blit and corrupt the playfield render mid-frame.
+ *
+ * Canonical loop:
+ *
+ *   for (;;) {
+ *     // ... build frame ...
+ *     tgi_updatedisplay();   // waits for vblank, swaps pages
+ *     sfx_update();          // ← MIKEY writes happen here (in vblank)
+ *
+ *     pad = joy_read(JOY_1);
+ *     // ... game logic, may call sfx_tone(...) — STAGED only ...
+ *   }
+ *
+ * Round 29 friction reported "audio APIs wedge TGI rendering" —
+ * confirmed: pre-R57 sfx_tone wrote MIKEY synchronously which
+ * interrupted Suzy blits. The defer-to-update pattern fixes it.
+ */
+
+#ifndef LYNX_SFX_H
+#define LYNX_SFX_H
+
+#include <stdint.h>
+
+void sfx_init(void);
+void sfx_tone(uint8_t channel, uint8_t period, uint8_t length_frames);
+void sfx_noise(uint8_t length_frames);
+void sfx_update(void);
+void sfx_off(void);
+
+#endif

package/src/platforms/lynx/lib/cc65-src/bllhdr.s

@@ -0,0 +1,18 @@
+;
+; Karri Kaksonen, 2011
+;
+; This header is required for BLL builds.
+;
+        .import         __BSS_LOAD__
+        .import         __MAIN_START__
+        .export         __BLLHDR__: absolute = 1
+
+; ------------------------------------------------------------------------
+; BLL header (BLL header)
+
+        .segment "BLLHDR"
+        .word   $0880
+        .dbyt   __MAIN_START__
+        .dbyt   __BSS_LOAD__ - __MAIN_START__ + 10
+        .byte   $42,$53
+        .byte   $39,$33

package/src/platforms/lynx/lib/cc65-src/bootldr.s

@@ -0,0 +1,195 @@
+;
+; Karri Kaksonen, 2011
+;
+; This bootloader creates a signed binary so that the Lynx will accept it.
+;
+        .include "lynx.inc"
+        .include "extzp.inc"
+        .import         __BANK0BLOCKSIZE__
+        .export         __BOOTLDR__: absolute = 1
+
+
+; ------------------------------------------------------------------------
+; Bootloader
+
+        .segment "BOOTLDR"
+;**********************************
+; Here is the bootloader in plaintext
+; The idea is to make the smallest possible encrypted loader as decryption
+; is very slow. The minimum size is 49 bytes plus a zero byte.
+;**********************************
+;                  EXE = $fb68
+;
+;                  .org $0200
+;
+;                  ; 1. force Mikey to be in memory
+; 9C F9 FF         stz MAPCTL
+;
+;                  ; 2. clear palette
+; A0 1F            ldy #31
+; A9 00            lda #0
+; 99 A0 FD nextc:  sta GCOLMAP, y
+; 88               dey
+; 10 FA            bpl nextc
+;
+;                  ; 3. set ComLynx to open collector
+; A9 04            lda #4          ; a = 00000100
+; 8D 8C FD         sta SERCTL      ; set the ComLynx to open collector
+;
+;                  ; 4. set AUDIN to output
+; A9 1A            lda #$1a        ; audin = out, rest = out,
+;                                  ; noexp = in, cart addr = out, ext pwd = in
+; 8D 8A FD         sta IODIR
+;
+;                  ; 5. set AUDIN to LOW
+; A9 0B            lda #$0B        ; Set AUDIN low
+; 85 1A            sta $1a         ; Save local copy to ZP
+; 8D 8B FD         sta IODAT
+;
+;                  ; 6. read in secondary exe + 8 bytes from the cart
+;                  ; and store it in $f000
+; A2 00            ldx #0          ; x = 0
+; A0 97            ldy #$97        ; y = secondary loader size (151 bytes)
+; AD B2 FC rloop1: lda RCART0      ; read a byte from the cart
+; 9D 68 FB         sta EXE,X       ; EXE[X] = a
+; E8               inx             ; x++
+; 88               dey             ; y--
+; D0 F6            bne rloop1      ; loops until y wraps
+;
+;                  ; 7. jump to secondary loader
+; 4C 68 FB         jmp EXE
+; 00 00 00 00      ; spares
+; 00               ; End of encrypted header mark
+;
+;   .reloc
+;**********************************
+; After compilation, encryption and obfuscation it turns into this.
+;**********************************
+        .byte $ff, $b6, $bb, $82, $d5, $9f, $48, $cf
+        .byte $23, $37, $8e, $07, $38, $f5, $b6, $30
+        .byte $d6, $2f, $12, $29, $9f, $43, $5b, $2e
+        .byte $f5, $66, $5c, $db, $93, $1a, $78, $55
+        .byte $5e, $c9, $0d, $72, $1b, $e9, $d8, $4d
+        .byte $2f, $e4, $95, $c0, $4f, $7f, $1b, $66
+        .byte $8b, $a7, $fc, $21
+
+;**********************************
+; Now we have the secondary loader
+;**********************************
+        .org $fb68
+        ; 1. Read in the 1st File-entry (main exe) in FileEntry
+        ldx #$00
+        ldy #8
+rloop:  lda RCART0      ; read a byte from the cart
+        sta _FileEntry,X ; EXE[X] = a
+        inx
+        dey
+        bne rloop
+
+        ; 2. Set the block hardware to the main exe start
+        lda     _FileStartBlock
+        sta     _FileCurrBlock
+        jsr     seclynxblock
+
+        ; 3. Skip over the block offset
+        lda     _FileBlockOffset+1
+        eor     #$FF
+        tay
+        lda     _FileBlockOffset
+        eor     #$FF
+        tax
+        jsr     seclynxskip0
+
+        ; 4. Read in the main exe to RAM
+        lda     _FileDestAddr
+        ldx     _FileDestAddr+1
+        sta     _FileDestPtr
+        stx     _FileDestPtr+1
+        lda     _FileFileLen+1
+        eor     #$FF
+        tay
+        lda     _FileFileLen
+        eor     #$FF
+        tax
+        jsr     seclynxread0
+
+        ; 5. Jump to start of the main exe code
+        jmp     (_FileDestAddr)
+
+;**********************************
+; Skip bytes on bank 0
+; X:Y count (EOR $FFFF)
+;**********************************
+seclynxskip0:
+        inx
+        bne @0
+        iny
+        beq exit
+@0:     jsr secreadbyte0
+        bra seclynxskip0
+
+;**********************************
+; Read bytes from bank 0
+; X:Y count (EOR $ffff)
+;**********************************
+seclynxread0:
+        inx
+        bne @1
+        iny
+        beq exit
+@1:     jsr secreadbyte0
+        sta (_FileDestPtr)
+        inc _FileDestPtr
+        bne seclynxread0
+        inc _FileDestPtr+1
+        bra seclynxread0
+
+;**********************************
+; Read one byte from cartridge
+;**********************************
+secreadbyte0:
+        lda RCART0
+        inc _FileBlockByte
+        bne exit
+        inc _FileBlockByte+1
+        bne exit
+
+;**********************************
+; Select a block
+;**********************************
+seclynxblock:
+        pha
+        phx
+        phy
+        lda __iodat
+        and #$fc
+        tay
+        ora #2
+        tax
+        lda _FileCurrBlock
+        inc _FileCurrBlock
+        sec
+        bra @2
+@0:     bcc @1
+        stx IODAT
+        clc
+@1:     inx
+        stx SYSCTL1
+        dex
+@2:     stx SYSCTL1
+        rol
+        sty IODAT
+        bne @0
+        lda __iodat
+        sta IODAT
+        stz _FileBlockByte
+        lda #<($100-(>__BANK0BLOCKSIZE__))
+        sta _FileBlockByte+1
+        ply
+        plx
+        pla
+
+exit:   rts
+
+        .reloc
+

package/src/platforms/lynx/lib/cc65-src/cgetc.s

@@ -0,0 +1,69 @@
+;
+; Karri Kaksonen, Harry Dodgson 2006-01-07
+;
+; char cgetc (void);
+;
+
+        .export         _cgetc
+        .import         _kbhit
+        .import         KBEDG
+        .import         KBSTL
+
+; --------------------------------------------------------------------------
+; The Atari Lynx has a very small keyboard - only 3 keys
+; Opt1, Opt2 and Pause.
+; But the designers have decided that pressing Pause and Opt1 at the
+; same time means Restart and pressing Pause and Opt2 means Flip screen.
+
+; For "easter egg" use I have also included all three keys pressed '?'
+; and Opt1 + Opt2 pressed '3'.
+; So the keyboard returns '1', '2', '3', 'P', 'R', 'F' or '?'.
+
+_cgetc:
+        jsr     _kbhit          ; Check for char available
+        beq     _cgetc
+        ora     KBSTL
+        ldx     #0
+        and     #1
+        beq     @L5
+        lda     KBEDG           ; Pause button is pressed
+        and     #$0c
+        beq     @L2
+        ora     KBSTL
+@L1:
+        bit     #$04
+        beq     @L3                     ; Pause + Opt 1 = Reset
+        bit     #$08
+        beq     @L4                     ; Pause + Opt 2 = Flip
+        lda     #'?'                    ; All buttons pressed
+        bra     reset_and_exit
+@L2:
+        lda     KBSTL           ; Pause alone was the last placed button
+        and     #$0c
+        bne     @L1
+        lda     #'P'                    ; Pause pressed
+        bra     reset_and_exit
+@L3:
+        lda     #'R'                    ; Reset pressed
+        bra     reset_and_exit
+@L4:
+        lda     #'F'                    ; Flip pressed
+        bra     reset_and_exit
+@L5:
+        lda     KBEDG           ; No Pause pressed
+        ora     KBSTL
+        bit     #$08
+        beq     @L7
+        bit     #$04
+        beq     @L6
+        lda     #'3'                    ; opt 1 + opt 2 pressed
+        bra     reset_and_exit
+@L6:
+        lda     #'1'                    ; opt 1 pressed
+        bra reset_and_exit
+@L7:
+        lda     #'2'                    ; opt 2 pressed
+
+reset_and_exit:
+        stz     KBEDG
+        rts

package/src/platforms/lynx/lib/cc65-src/clock.s

@@ -0,0 +1,87 @@
+;
+; 2003-04-13, Ullrich von Bassewitz
+; 2012-02-06, Greg King
+;
+; clock_t clock (void);
+; clock_t __clocks_per_sec (void);
+;
+; clocks_per_sec()'s test-values are based on the numbers in "set_tv.s".
+; If you change the numbers there, then change them here, too.
+;
+
+        .export         _clock, ___clocks_per_sec, clock_count
+        .interruptor    update_clock, 2 ; (low priority)
+        .constructor    init_clock
+
+        .import         sreg: zp
+        .include        "lynx.inc"
+
+        .macpack        generic
+
+
+        .proc   _clock
+        php
+        sei                     ; Disable interrupts
+
+; Read the clock counter.
+
+        lda     clock_count
+        ldx     clock_count+1
+        ldy     clock_count+2
+
+        plp                     ; Re-enable interrupts
+        sty     sreg
+        stz     sreg+1          ; Promote 24 bits up to 32 bits
+        rts
+        .endproc
+
+;-----------------------------------------------------------------------------
+; Return the number of clock ticks in one second.
+;
+___clocks_per_sec:
+        ldx     #$00            ; >50, >60, >75
+        ldy     PBKUP
+        lda     #<75
+        cpy     #$20 + 1
+        blt     @ok
+        lda     #<60
+        cpy     #$29 + 1
+        blt     @ok
+        lda     #<50
+@ok:    stz     sreg            ; return 32 bits
+        stz     sreg+1
+        rts
+
+;-----------------------------------------------------------------------------
+; This interrupt handler increments a 24-bit counter at every video
+; vertical-blanking time.
+;
+        .segment        "LOWCODE"
+update_clock:
+        lda     INTSET
+        and     #%00000100
+        beq     @NotVBlank      ; Not vertical-blank interrupt
+
+        inc     clock_count
+        bne     @L1
+        inc     clock_count+1
+        bne     @L1
+        inc     clock_count+2
+@L1:    ;clc                    ; General interrupt was not reset
+@NotVBlank:
+        rts
+
+;-----------------------------------------------------------------------------
+; Enable the interrupt that update_clock needs.
+;
+        .segment        "ONCE"
+init_clock:
+        lda     #%10000000
+        tsb     VTIMCTLA
+        rts
+
+;-----------------------------------------------------------------------------
+;
+        .bss
+clock_count:
+        .res    3