romdev-mcp 0.1.1

package/src/platforms/lynx/TROUBLESHOOTING.md

@@ -0,0 +1,105 @@
+# Atari Lynx — troubleshooting
+
+Read MENTAL_MODEL.md first (`getPlatformDoc({platform:"lynx",
+name:"mental_model"})`).
+
+## "ROM loads but screen is black / no display"
+
+You probably forgot `tgi_install` + `tgi_init`. cc65's TGI driver
+must be installed before any `tgi_*` call. The canonical opener:
+
+```c
+tgi_install(&lynx_160_102_16_tgi);
+tgi_init();
+```
+
+Without `tgi_init` the framebuffer pointer isn't set; without
+`tgi_install` the TGI dispatcher has no driver to call.
+
+## "Screen stays blank even though tgi_install/tgi_init ran + I'm drawing"
+
+The other blank-screen cause: a bad render-loop order. The reliable
+Lynx loop is a FULL REDRAW every frame in this exact order:
+
+```c
+for (;;) {
+    while (tgi_busy()) { }            /* 1. wait for the Suzy blitter to
+                                       *    finish the LAST frame — drawing
+                                       *    while it's busy loses the frame */
+    tgi_setcolor(COLOR_BLACK);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());  /* 2. full-screen clear */
+    /* 3. draw all your objects with tgi_bar / tgi_line ... */
+    tgi_updatedisplay();              /* 4. push the frame */
+}
+```
+
+Two things that trip agents up:
+- **`while (tgi_busy()) { }` is required** before drawing the next frame.
+  Skipping it is the #1 "Lynx is blank" trap.
+- **Don't rely on `tgi_clear()`** to blank the screen in this
+  toolchain/emulator path — use a full-screen `tgi_bar(0,0,maxx,maxy)`
+  in the background colour instead. The bundled `shmup` scaffold uses
+  this exact loop; copy it.
+
+## "tgi_outtextxy renders nothing"
+
+cc65's default TGI on Lynx ships without a font. Either:
+1. Load one: `tgi_load_vectorfont("lynx_a.fnt", ...)` — fontfiles
+   live in `$cc65_share/target/lynx/fonts/`.
+2. Draw your own glyphs with `tgi_bar`/`tgi_line`.
+
+The bundled scaffolds work around this by using simple rectangles
+for game content + only short text strings. For game UI text, embed
+a bitmap font directly in your code.
+
+## "Joystick reads return 0"
+
+`joy_install(&lynx_stdjoy_joy)` is required before `joy_read(JOY_1)`.
+The Lynx joystick driver maps the hardware switch register at $FCB0
+into cc65's JOY_* macros.
+
+## "MIKEY audio silent — sfx_init was called but I hear nothing"
+
+Three things to check:
+1. **Volume sign**: MIKEY's volume register is SIGNED 8-bit. 64 =
+   audible, 0 = silent, -1 (0xFF) = also audible but inverted phase.
+   sfx_init sets volume to 0 (silent) — you must call sfx_tone or
+   sfx_noise to get audio.
+2. **STEREO routing**: `$FD50` controls which voices output to which
+   speaker. Bits 0-3 *mute* left for voice 0-3; bits 4-7 mute right.
+   sfx_init sets it to 0 (all voices to both speakers). If you've
+   written non-zero values to $FD50, voices may be muted.
+3. **sfx_update**: without it, notes never silence. Probably not
+   "silent" but "the same note plays forever and gets ignored as
+   background noise."
+
+## "ROM works in handy emulator but not in mednafen/etc."
+
+Other Lynx emulators sometimes expect the 64-byte `.lnx` header that
+cc65's default config doesn't emit. Either:
+1. Stick with handy (romdev ships this).
+2. Wrap your ROM in a `.lnx` header — handy itself can produce one
+   via `lyxx -i raw.bin -o game.lnx`.
+
+## "cc65 complains about C99 features"
+
+cc65 is C89. No mixed declarations + code, no inline `for (uint8_t i
+= 0; ...)`, no compound literals, no // comments in some configs.
+Declare all variables at the top of each block.
+
+The bundled Lynx scaffolds are C89-clean — copy that pattern.
+
+## "Compile fails: no rule to make target lynx-bll.cfg"
+
+You probably tried passing `linkerConfig: "lynx-bll"` — that's the
+"bootloader-loaded" config for multi-image ROMs. For a single-image
+ROM let cc65 use the default `lynx.cfg`. Drop the linkerConfig arg.
+
+## "Game runs but at wrong speed"
+
+Lynx framerate is configurable via Mikey timer 0. cc65's tgi defaults
+to ~60 fps via `tgi_setframerate(60)`. Lower it to 30 for slow games:
+`tgi_setframerate(30);` after tgi_init.
+
+Don't bother adjusting if you're just iterating in the emulator —
+gpgx and handy both run at the rate the ROM requests.

package/src/platforms/lynx/UPSTREAM_SOURCES.md

@@ -0,0 +1,66 @@
+# Lynx — source you can read
+
+When the bundled examples + MENTAL_MODEL.md aren't enough and you
+need to grep around the actual implementation. Trust hierarchy:
+
+1. **Bundled examples** (`examples/lynx/templates/*.c`) — verified to
+   compile and (mostly) work. Start here.
+2. **Bundled runtime source** (`src/platforms/lynx/lib/`) — our thin
+   wrappers (lynx_sfx.c, lynx_music.c). Read these when an API call
+   isn't doing what you expect.
+3. **cc65 lynx libsrc** — shipped at `src/platforms/lynx/lib/cc65-src/`.
+   The complete cc65 Lynx target source: TGI graphics driver (`tgi/
+   lynx-160-102-16.s`), joystick driver, conio, header builder, sound
+   engine (`lynx-snd.s`), etc. Read this when "tgi_bar does X — why?".
+4. **Compiler + emulator GitHub** (links below) — for anything below
+   our thin wrappers and beyond cc65's source. We don't bundle these
+   because they're big and the agent can't rebuild them anyway, but
+   you can fetch them on demand when chasing a deep bug.
+5. **Found a real bug in romdev?** Open an issue at
+   https://github.com/monteslu/romdev/issues with repro details.
+
+## Local source paths (in your project after `npm install`)
+
+| What | Where |
+|---|---|
+| Our lynx_sfx wrapper | `src/platforms/lynx/lib/c/lynx_sfx.c` |
+| Our lynx_music wrapper | `src/platforms/lynx/lib/c/lynx_music.c` |
+| cc65 TGI driver | `src/platforms/lynx/lib/cc65-src/tgi/lynx-160-102-16.s` |
+| cc65 lynx_snd music engine | `src/platforms/lynx/lib/cc65-src/lynx-snd.s` |
+| cc65 joystick driver | `src/platforms/lynx/lib/cc65-src/joy/lynx-stdjoy.s` |
+| cc65 conio | `src/platforms/lynx/lib/cc65-src/conio.s` |
+| cc65 header builder | `src/platforms/lynx/lib/cc65-src/header.s` |
+
+When you grep, start in `cc65-src/` — it's the most likely place
+your "why doesn't tgi_X work?" question gets answered.
+
+## Upstream sources (NOT bundled — fetch on demand if needed)
+
+| What | Upstream | Why not bundled |
+|---|---|---|
+| cc65 compiler + libsrc | https://github.com/cc65/cc65 | We bundle the WASM compiler + lynx libsrc separately; full tree is ~50 MB |
+| handy libretro core | https://github.com/libretro/libretro-handy | C++ emulator source, ~5 MB. Read when MCP behavior diverges from real hardware. |
+| handy mikie/susie (deeper) | Same repo, `src/lynx/mikie.cpp` + `susie.cpp` | Contains the exact emulation of MIKEY timers + Suzy blitter. Where round-29's audio-vs-TGI bug was diagnosed. |
+
+## Lynx hardware docs
+
+| What | Where |
+|---|---|
+| Atari Lynx Programmer's Manual | https://atarihq.com/danb/files/Atari_Lynx_Programmer_s_Manual.pdf |
+| Lynx Bluebook (epyx engineer notes) | https://archive.org/details/lynx_bluebook |
+| Copetti architecture writeup | https://www.copetti.org/writings/consoles/atari-lynx/ |
+
+The Programmer's Manual is the canonical reference for everything
+MIKEY + Suzy. Read sections 5 (MIKEY) and 6 (Suzy) before
+attempting anything beyond `tgi_bar`.
+
+## When to use what
+
+- "How does `tgi_bar` work internally?" → `cc65-src/tgi/lynx-160-102-16.s`
+- "What does the MIKEY timer chain do?" → handy `mikie.cpp` + Programmer's Manual section 5
+- "Why does Suzy stop rendering after N frames?" → handy `susie.cpp`
+  `PaintSprites()` + check `mSUZYBUSEN` + `mSPRGO`
+- "What's the actual audio register layout?" → `cc65-src/lynx-snd.s`
+  + Programmer's Manual section 5.6
+- "Does the bundled lynx_sfx wrap MIKEY correctly?" → our
+  `lynx_sfx.c` source (it's tiny — 100 lines, fully readable)

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

@@ -0,0 +1,63 @@
+/* lynx_music.c — hand-authored music bytestream for cc65's lynx_snd_play.
+ *
+ * cc65 ships a 4-channel music engine on the Atari Lynx (see
+ * build/cc65/src/libsrc/lynx/lynx-snd.s). Driver is started with:
+ *
+ *     lynx_snd_init();                       // 240Hz IRQ + voice reset
+ *     lynx_snd_play(channel, demo_music);    // begin streaming on channel
+ *
+ * Stream byte format (parsed in SndGetCmd):
+ *
+ *   byte < $80  → NOTE+LENGTH pair. byte0 is the note index (1..127),
+ *                 byte1 is the delay/length in 240Hz ticks. The driver
+ *                 looks up note -> prescaler + reload from internal
+ *                 tables (SndPrescaler / SndReload in lynx-snd.s). Note 0
+ *                 terminates the stream (SndStop). Notes roughly form a
+ *                 chromatic scale; ~12-13 = ~middle C, +12 per octave.
+ *                 Two bytes consumed.
+ *
+ *   byte $80..$ff → COMMAND. The low 7 bits index a function table:
+ *      $80 SndLoop           start loop (next byte = loop count)
+ *      $81 SndDo             end-of-loop marker (jumps back to $80)
+ *      $82 SndPause          rest for N ticks (next byte = N)
+ *      $83 SndNoteOff        release current note (envelope tail)
+ *      $84 SndSetInstr       set channel instrument (5 bytes follow)
+ *      $85 SndNewNote2       explicit reload+prescale note (3 bytes)
+ *      $86 SndCallPattern    call sub-pattern (2-byte addr)
+ *      $87 SndRetToSong      return from sub-pattern
+ *      $88..$8d envelope setup (define + select vol/frq/wave)
+ *      $8e SndSetStereo      stereo mute mask (1 byte)
+ *      $91 SndPlayerFreq     change tempo (2 bytes)
+ *      $92 SndReturnAll      end-of-track sentinel
+ *
+ *   Command's Y register on return tells the driver how many bytes to
+ *   advance past (low 7 bits of Y; high bit means "loop again same tick").
+ *
+ * The demo below plays a short C-major-arpeggio-like motif on one channel
+ * so you can audibly verify the driver is wired and the IRQ is firing.
+ * Each note is roughly an 8th-note at the default 240Hz player rate.
+ *
+ * NOTE numbers picked by ear from SndReload table — the driver doesn't
+ * publish a "midi number" mapping, so values 24/28/31/36 sit in a
+ * comfortable musical range and demonstrate distinct pitches. Adjust
+ * freely; values 1..127 are all valid.
+ */
+
+#include "lynx_music.h"
+
+/* Non-const because cc65's lynx_snd_play signature wants a writable
+ * pointer — see lynx_music.h. The bytes live in ROM (cc65 puts read-
+ * only globals there) so attempting to write through this would crash;
+ * the cc65 driver never writes, just reads. */
+unsigned char demo_music[] = {
+  /* note, length(ticks) — length 30 @ 240Hz ≈ 125 ms per note */
+  24, 30,   /* low  */
+  28, 30,
+  31, 30,
+  36, 30,   /* high */
+  31, 30,
+  28, 30,
+  24, 60,   /* longer trailing note */
+  0x82, 30, /* SndPause: rest 30 ticks before looping the engine restart */
+  0         /* SndStop — terminate stream */
+};

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
+