modemwars/swiftlink/DESIGN_NOTES.md

Design notes found by inspection - these MUST be honoured by the SwiftLink driver

1. The NMI handler has to survive the I/O area being banked out

The game keeps its "game film" / saved-game buffer in the RAM underneath the I/O area, at $D000-$DFF0. readFilmByte ($5866) and writeFilmByte ($5893) in disassembly/game/mainProgram0800.s therefore do this around every single byte:

sei                     ; NMI is NOT blocked by this - see below
stx CIA2_ICR            ; disable every CIA2 interrupt source (written twice as a guard)
stx CIA2_ICR
ldx #$34                ; bank RAM in over the whole $D000-$DFFF I/O area
stx CPU_PORT
lda (filmPtr),y         ; touch the film buffer
inc CPU_PORT            ; back to $35, I/O visible again
ldx ciaIcrShadow        ; $E033 - the module's copy of the CIA2 mask it wants
stx CIA2_ICR            ; re-enable the modem's NMI sources
cli

For the stock driver this is airtight: its UART interrupt is a CIA2 interrupt, so disabling CIA2 sources really does stop it firing while the registers are hidden.

A SwiftLink interrupt is not a CIA2 interrupt. Nothing in that sequence stops the ACIA asserting NMI, and sei does not mask NMI. So the handler can and will fire while $01 = $34, at which point $DE00-$DE03 are ordinary RAM and the handler would read garbage, lose the received byte and possibly wedge the receiver.

Requirement: the SwiftLink NMI handler must be bank-safe. On entry save $01, force it to $35 so the ACIA is visible, do the work, then restore the saved value before RTI. Do this before touching any ACIA register. Remember $01 is also the 6510 port used for the tape motor and character-ROM banking, so save and restore the whole byte, do not just write $35 and $34 back.

Also: $E033 (ciaIcrShadow) is still written into CIA2_ICR by those two routines, so it must hold a value that is correct for this driver. This driver wants no CIA2 interrupts at all, so it should hold $7F (clear every CIA2 source). Set it at run time - its stored byte in the module image is inside the frozen region and must not change.

2. Prefer base $DE00, and never index into the ACIA page by accident

loadBaudParameters ($E353) in the stock module writes its three bytes with sta $DF59,y where Y is $FD/$FE/$FF, so the effective addresses are $E056-$E058. That is fine on the stock hardware, but an indexed store on a 6502 performs a dummy READ from the un-carried address first - here $DF56, $DF57 and $DF58. With a SwiftLink strapped to $DF00 those land on the ACIA's mirrored registers, and $DF58 mirrors the data register, whose read consumes a received byte and clears RDRF.

The replacement for loadBaudParameters must not use that trick. Address $E056-$E058 directly. More generally: default the driver to $DE00, and document that $DF00 is second choice.

3. The game also copies pages across $D000-$DF00

mapGenerator6F00.s walks a source and a destination page over $D000..$DF00 ($7F66, $816E) for the film snapshot. Those go through the same bank-out dance. Nothing extra to do, but it is another reason the handler must be bank-safe rather than relying on interrupts being masked.