modemwars/swiftlink/spec_uart.md

spec_uart.md - the hardware contract of the stock Modem Wars UART layer

Note on addresses. This report records a run made before the probe-hardening pass, which relocated six internal helpers. Addresses quoted below are the ones those routines had at the time of the run. See ADDRESS_CHANGES.md for the mapping onto the current source.

What this file is: the exact, verified behaviour of every routine in disassembly/game/modemDriverE000.s that touches the C64's hardware, written so the same routines can be rebuilt against a 6551 ACIA on a SwiftLink cartridge without any code above them noticing.

Every address, instruction boundary and caller below was checked against the listing disassembly/game/modemDriverE000.s and disassembly/XREF.txt. Where the shipped comments in the listing are wrong, this file says so and gives the correct behaviour.

0. Conventions

• "Range" gives the first byte of the routine and, after the dash, the address of the byte after its last - so $E534-$E540 means the routine occupies $E534..$E53F inclusive and the next routine starts at $E540. A replacement must fit in exactly that span or leave the tail padded.
• "Callers" lists the address of the JSR/JMP/branch, not the routine name only, so each can be checked.
• Flag names are the 6502's: N Z C V.
• "the frame tick" means the raster IRQ at $1129/$112C, which calls jump-table entry $E000 with X=0 and then entry $E00C, in that order, once per frame.

1. Where the seam actually is

Everything above the UART layer reaches the hardware through a very small number of doors. These are the complete set; if the replacement honours all of them, nothing above changes:

Door	Direction	Used by
queueByteForTransmit $E73C	byte out	$E7D2, $E81D, $E87C, $E92A
popUartRxRing $E4D2 (via thunk $E739)	byte in	$E743, $E799, $E80A, $E9E9
flushUartTxRing $E534	discard queued output	$E791, $E80F
uartPendingCount $E0A5	"how many bytes do I still owe the wire"	$E1EC, $E26E, $E628, $E76B, $E82D, $E860
linkStatus $E03C / linkStatusSample $E03D	carrier + activity	$E622, $E787, $E7E3, and the game at $1B4B, $1BAB, $1BB6, $56B1, $65BC
reportLinkError $E3BC -> countLinkError $E403	"that character was bad"	NMI only ($E724)
nmiSuspendRequest/nmiSuspendAck $E039/$E03A	disk-load handshake	game at $0F67/$0F6A and $0F78/$0F7B
ciaIcrShadow $E033	mask the game restores after banking I/O out	game at $588C, $58AB, $58D0
$E003 X=0/1/2/3 and the hot keys	open, init, stop, hang up, baud, DTR	$E29A dispatcher

No code outside the module references anything in $E048-$EBFF of the modem driver. (A scan of XREF.txt for external references into that window returns only trainerSetupEC00 and droneAiEE00 entries, which belong to the trainer overlay that shares those addresses, not to this module.) So the whole UART layer is free to be rewritten as long as the doors above keep their addresses and semantics, and the three frozen regions - $E000-$E017, $E01D-$E047, $EC00-$EFFF - come out byte-identical.

Note that the frozen constraint on $E01D-$E047 is on the disk image bytes, not on runtime meaning: $E039-$E047 is zeroed by clearLinkVars at run time anyway, and $E045/$E046/$E047 ship as the leftover ASCII D T H from the sector image. A replacement may give those bytes new runtime meanings; it may not change what is stored in the file.

2. Hardware the stock UART layer owns

Every CIA2 access in the whole module, with the address of the instruction:

Register	Read at	Written at	Role
CIA2_PRA $DD00	$E56D, $E66E, $E6BC	$E570, $E6C5	PA2 = TXD. Always read-modify-write, because PA0/PA1 are the VIC bank select
CIA2_PRB $DD01	$E32A, $E5F1, $E6F1	$E32D, $E568, $E577	PB0 = RXD, PB1 = RTS, PB2 = DTR, PB4 = DCD, PB5 = spare output
CIA2_DDRB $DD03	-	$E55F	$26: PB1, PB2, PB5 out
CIA2_TA_LO/HI $DD04/$DD05	-	$E547/$E542, $E65D/$E657 (X=0)	receive bit clock latch
CIA2_TB_LO/HI $DD06/$DD07	$E68D, $E695 (hi)	$E65D/$E657 (X=2)	transmit bit clock latch
CIA2_SDR $DD0C	-	$E559	one fixed pattern shifted out of SP2 (user-port pin 7); purpose unknown
CIA2_ICR $DD0D	$E596, $E690, $E69C	$E59B, $E67C, $E68A, $E6CA, $E702	NMI source mask / flags
CIA2_CRA $DD0E	-	$E54C, $E59E, $E6E9, $E729	timer A control
CIA2_CRB $DD0F	$E607	$E651, $E5A1, $E6AD	timer B control

Nothing in the module touches CIA2_DDRA; PA2 is already an output because the boot loader and fast loader set DDRA. A 6551 driver should touch none of the above except CIA2_ICR, and there only to keep it disabled (see section 5).

3. Routine contracts

$E353 loadBaudParameters - range $E353-$E362

Copies the three-byte baud entry baudParameterTable+X into the live bit-period and pacing bytes.

• In: X = 0 (300 baud) or 3 (1200 baud). Y is loaded internally.
• Reads: $E059+X, $E059+X+1, $E059+X+2.
• Writes: $E056 bitPeriodLo, $E057 bitPeriodHi, $E058 txPaceReload.
• Out: A = $FF (N=1, Z=0), X = X_in+3, Y = $00, C unchanged, memory as above. The A = $FF return value is load bearing: the C=+3 / C=+1 hot keys fall into this routine and use its return as the "key swallowed" answer to the game.
• Callers: JSR $E2C9 (openCommLink), JSR $E7B2 (switchTo1200Baud, on a CONNECT 1200 result code); fall-through from $E350 (STX baudIndex) on the C=+3 and C=+1 hot keys. XREF.txt lists only the two JSRs because the third path is a fall-through.
• Trap for a 6551 build: the loop stores with STA $DF59,Y ($E358), abusing $DF59+$FD = $E056 so one register both counts and indexes. STA abs,Y always performs a dummy read at (base AND $FF00) OR ((baseLo+Y) AND $FF), i.e. at $DF56, $DF57 and $DF58. On a SwiftLink strapped to $DF00, $DF58 AND 3 = 0 is the data register: that dummy read silently consumes a received byte and clears RDRF. This is the only instruction in the entire game that names an address in the $DE00/$DF00 I/O windows, so rewriting these three stores as plain absolute STAs removes the whole class of problem.

$E534 flushUartTxRing - range $E534-$E540

Throws away everything queued for transmission and resynchronises the pending count with reality.

• In: the UART transmit ring, txCharActive $E5BB.
• Reads: uartTxCount $E414, uartTxReadIndex $E415, uartTxRing $E417..$E42C, $E5BB.
• Writes: $E414 to 0, $E415 walked down to match, uartPendingCount $E0A5 = $E5BB (1 if a character is still being shifted out, 0 if not).
• Out: A = the value written to $E0A5, X = clobbered, C = 1 (left set by the final empty popUartTxRing), N/Z from the LDA txCharActive.
• Callers: JSR $E791 (enterTerminalMode), JSR $E80F (restartByteSync); self-loop branch at $E537.
• 6551 note: the "1 if a character is still shifting" rule exists so the packet layer's $E0A5-reaches-zero test stays honest across a flush. With a 6551 the equivalent is "1 if a byte has been written to the data register whose TDRE has not come back yet, else 0".

$E540 configureUserPortLines - range $E540-$E574

Programs CIA2 for the user-port serial link and asserts the modem control lines.

• In: isOriginateMode $E011, baudIndex $E055, userPortDdrbValue $E04D ($26), userPortIdleTable $E04F (both entries $26), serialShiftPatternTable $E051 ($27 $2F $3F $37).
• Writes, in order: CIA2_TA_HI = 0, CIA2_TA_LO = 3 (latch $0003), CIA2_CRA = $51 (timer A continuous, serial port in output mode), CIA2_SDR = pattern selected by (3 AND isOriginateMode) EOR baudIndex, CIA2_DDRB = $26, CIA2_PRB = $26 (RTS, DTR, PB5 all asserted), CIA2_PRA |= $04 (TXD to the idle mark level, read-modify-write so the VIC bank bits survive).
• Out: A = the value written to CIA2_PRA, X = isOriginateMode, Y unchanged, N/Z from the ORA CIA2_PRA, C unchanged.
• Callers: JSR $E2D5 (openCommLink, on every open including a re-open), JSR $E387 (the C=+A / C=+O answer/originate hot keys).
• Its tail $E56B-$E573 is a separate entry: setCiaNmiMask ends with JMP $E56B. Any replacement must keep a valid three-instruction "raise TXD / RTS" tail at $E56B or repoint that JMP.
• 6551 equivalent: program the control register ($10 OR rateBits, 8N1, internal clock) and the command register ($09 = DTR on, receiver IRQ enabled, RTS low, no transmit IRQ; or $0D when the transmit interrupt is wanted). The CIA2_SDR write, the timer A latch and the CIA2_PRA bit are all dead.

$E574 dropDtrLine - range $E574-$E57B

• In: userPortDtrDropped $E04E = $22.
• Writes: CIA2_PRB = $22 - PB2 (DTR) low, PB1 (RTS) and PB5 still high. Dropping DTR is what makes a Hayes modem let go of the line.
• Out: A = $22 (N=0, Z=0), X/Y/C unchanged.
• Callers: JSR $E38D (hangUpModem, itself reached from $E2A2 for $E003 X>=3 and from the C=+P hot key at $E376).
• 6551 equivalent: write the command register with bit 0 = 0. Note that on the 6551 clearing bit 0 also disables the receiver and all ACIA interrupts, which is the desired behaviour here.

$E57B installCommNmiVector - range $E57B-$E586

• In: none.
• Writes: $FFFA = $85, $FFFB = $E6 - i.e. the RAM NMI vector points at commNmiHandler $E685. The KERNAL ROM is banked out ($01 = $35), so $FFFA/$FFFB really is RAM.
• Out: A = $85, X = $E6, N=1 Z=0 (from LDX #$E6), C unchanged.
• Callers: JSR $E2CC (openCommLink, only on a cold open when isLinkActive was 0).
• 6551 note: the constants $85/$E6 are the only thing that has to change if the handler moves, but it must not move: nothing else does, and keeping it at $E685 keeps this routine two bytes.

$E586 restartUart - range $E586-$E593 (falls into setCiaNmiMask)

(Re)starts the software UART.

• In: none.
• Calls: clearUartState $E5B6, which zeroes $E5BB-$E5C0 and returns here normally.
• Writes: $E5BB-$E5C0 = 0; uartRestartRequest $E042 = $01 ("re-evaluate the connection", as opposed to $FF which forces phase 0); carrierSampleTimer $E045 = $92.
• Falls through into setCiaNmiMask with A = $92, which arms the CIA2 FLAG line (the RXD start-bit edge) and timer B, and as a side effect writes $00 to both nmiSuspendRequest $E039 and nmiSuspendAck $E03A.
• Out: as setCiaNmiMask - A = the CIA2_PRA value, X = 0.
• Callers: JSR $E2CF (openCommLink), JSR $E5E1 (serviceCarrierAndSuspendRequest, the resume half of the disk-load handshake).
• Load-bearing side effects for the layer above: $E042 = 1 and $E039/$E03A = 0. A 6551 build must still produce exactly those, because runModemStateMachine $E758 consumes $E042 and the game's resumeCommModule $0F7B spins until $E03A bit 7 is clear.

$E593 setCiaNmiMask - range $E593-$E5B6

The single point where the module's interrupt sources are armed or disarmed.

• In: A = a CIA2 ICR command byte. Only three values are ever passed: $92 (set FLAG + timer B), $83 (set timer A + timer B - written by the NMI into the shadow, not through here) and $7F (clear every source).
• Reads: CIA2_ICR (the BIT at $E596 clears any pending flags), ciaIcrShadow $E033.
• Writes: ciaIcrShadow $E033 = A; CIA2_ICR = A; CIA2_CRA = 0 and CIA2_CRB = 0 (stopping both timers); then nmiSuspendRequest $E039 and nmiSuspendAck $E03A both set to (A EOR $FF) AND $80 - which is $00 for $92/$83 and $80 for $7F.
• Retry loop: CMP ciaIcrShadow / BCC $E593. If the NMI overwrote the shadow with a larger mask while we were storing ($83 or $92 over a $7F), the whole routine repeats. This is a real race, not decoration.
• Out: exits through JMP $E56B, so A = the value written to CIA2_PRA, X = 0, C set by the final AND #$80, N/Z from the ORA CIA2_PRA.
• Callers: JSR $E5CA (stopCommNmi), fall-through from restartUart $E590, self-branch $E5A7.
• 6551 equivalent: "enable" writes the command register with the receive interrupt on; "disable" writes it with bit 1 set (receiver IRQ disabled) and bits 3-2 = 00. The $E039/$E03A and $E033 writes must be kept exactly as they are - see section 5 for why $E033 matters even to a 6551 build.

$E5B6 clearUartState - range $E5B6-$E5C1 (code $E5B6-$E5BA, data $E5BB-$E5C0)

LDX #$06 / JSR clearInlineVarBlock, followed by the six-byte block it clears. clearInlineVarBlock eats its own return address and plants it in a self-modified STA abs,X, so the RTS returns to clearUartState's caller: from the caller's point of view this behaves as an ordinary subroutine.

• In: none.
• Writes: $E5BB-$E5C0 = 0.
• Out: A = 0, X = 0, Z=1 N=0, C unchanged; control returns to restartUart.
• Callers: JSR $E586 (restartUart) only.
• 6551 note: the six bytes are pure bit-bang state (section 4). A 6551 build still wants a routine here that zeroes whatever it keeps in that space, because restartUart calls it and flushUartTxRing reads $E5BB.

$E5C1 suspendUartIfRunning - range $E5C1-$E5C3

Two bytes: BCS $E5D5. It sits between the UART state block and stopCommNmi so the suspend path can fall into the stop path.

• In: C = bit 7 of nmiSuspendAck, shifted out by the ASL at $E5D9.
• Out: if C=1 (already suspended) it branches to the RTS at $E5D5 inside stopCommNmi and nothing happens; if C=0 it falls into stopCommNmi.
• Callers: branch BMI $E5DD in serviceCarrierAndSuspendRequest. Never called with JSR.

$E5C3 stopCommNmi - range $E5C3-$E5D6

Tears the UART down.

• In: txCharActive $E5BB.
• Writes: uartRestartRequest $E042 = $FF (forces connectionPhase back to 0 when the state machine next runs); calls setCiaNmiMask with $7F, so CIA2_ICR is cleared, both timers stopped, $E033 = $7F and $E039 = $E03A = $80; then, if a character was half-way out, DEC uartPendingCount $E0A5 because that character will never finish.
• Out: A = 0 or $E5BB's value, X = 0, RTS at $E5D5.
• Callers: JSR $E2AB (commLinkControlDispatch, reached for $E003 X=2 and, after the hang-up string has drained, X>=3), fall-through from suspendUartIfRunning.
• Ordering that matters: $E042 = $FF is written before the mask is cleared, and the uartPendingCount fix-up happens after. A 6551 build must keep all three effects, because the disk-load suspend goes through this same path and the game spins on $E03A.

$E607 startNextTxChar - body $E607-$E654, exits at the RTS $E662

Starts shifting the next character out. It is reached two ways: from the NMI (JSR $E673) and by fall-through from $E604, the tail of the carrier sampler - so it is retried once per frame from jump-table entry $E00C as well as from the NMI. That frame-rate retry is not optional: when the transmitter goes idle, timer B stops, no more transmit NMIs arrive, and the frame tick is the only thing that can start the machine again.

Guards, in order:

1. LDA CIA2_CRB / ORA txCharActive / LSR - give up if timer B's START bit is set or a character is already in flight.
2. If connectionPhase $E040 == 1 (modem command / terminal mode), skip guards 3 and 4 entirely: terminal-mode characters go out unpaced and without carrier.
3. DEC txPaceCounter $E044; give up unless it reached 0. On the frame it reaches 0 it is reloaded with 1 so the attempt repeats next frame.
4. LDA linkStatusSample $E03D / AND linkStatus $E03C / ASL - give up unless bit 6 (carrier) is set in both. The module refuses to transmit into a dead line.
5. LDA uartPendingCount $E0A5 - give up if zero.
6. JSR popUartTxRing; if the ring was empty although the count said otherwise, force $E0A5 = 0 and give up (this is the self-healing path for a lost decrement).

Then: INC txCharActive, STA txShiftRegister, txBitCountReload = 9, txPaceCounter = txPaceReload $E058, program timer B with a deliberately short first interval (A = $01 as the high byte, bitPeriodLo as the low byte) and CIA2_CRB = $11 (force load + start, continuous), then fall through into setBitPeriodFull so every following underflow is a whole bit time. The RTS at $E662 is the common exit for all six give-up paths and for the success path.

• Out: A = $11 on the success path, A/flags meaningless on the give-up paths (every one of them branches to $E662). X = 2 on success.
• Callers: JSR $E673 (nmiStartNextChar), fall-through from $E606.
• 6551 equivalent: most of this evaporates. What must survive is the policy: do not transmit unless $E0A5 is non-zero and, outside phase 1, only with carrier. Guard 4 is the reason a null-modem player needs the C=+C carrier override ($E04A bit 6) - or, with a 6551, a real DCD from the other end's DTR. Guard 3 (frame pacing) becomes pointless at 9600+ and can be reduced to a no-op, but the byte $E044 must still tolerate beginByteSyncPhase forcing bit 1 into it at $E820-$E825.

$E654 setBitPeriodFull - range $E654-$E657

Three bytes: LDA bitPeriodHi $E057, then falls into setBitPeriod.

• In: X = 0 (timer A) or 2 (timer B).
• Callers: JSR $E6EC (the NMI, immediately after the half-bit start-bit delay), fall-through from startNextTxChar $E653.

$E657 setBitPeriod - range $E657-$E663

• In: A = high byte of the interval, X = 0 or 2, bitPeriodLo $E056.
• Writes: CIA2_TA_HI,X then CIA2_TA_LO,X, i.e. $DD05/$DD04 for X=0 and $DD07/$DD06 for X=2. The low byte is always the full bitPeriodLo; only the high byte varies (the caller passes $01 for the short first transmit interval and bitPeriodHi >> 1 for the half-bit start-bit delay).
• Out: A = $11 - the "force load + start" byte the caller stores into CIA2_CRA or CIA2_CRB. X unchanged, N=0 Z=0.
• Callers: JSR $E64E (startNextTxChar), JSR $E6E6 (the NMI's start-bit path), fall-through from setBitPeriodFull.
• 6551 note: entirely dead. Baud is a control-register write, once, at open time.

$E663 nmiStartNextChar - range $E663-$E679

The timer B path of the NMI once txBitCounter has gone negative.

• In: txCharActive $E5BB, txBitCountReload $E5BC, CIA2_PRA.
• If a character is active: reload txBitCounter $E5BD from $E5BC (9), then read CIA2_PRA and branch to $E6C3 to clear bit 2 - the start bit. The BNE $E671 is an unconditional branch in practice because CIA2_PRA can never read 0 (the VIC bank bits are in it).
• If not: JSR startNextTxChar, then CLC / BCC $E6C8 into the receive half.
• Out: falls into the shared NMI tail; nothing returns to a caller.
• Callers: branch BMI $E6A7 in the NMI only.

$E685 commNmiHandler - range $E685-$E733, plus the "not mine" exit at $E679-$E685

The module's NMI handler. See section 5 for the dispatch and chaining rules, which the replacement must copy exactly. Structure:

Address	What happens
$E685-$E687	PHA / TXA / PHA - A then X saved. Y is never saved and never used.
$E688-$E68C	CIA2_ICR = $7F - mask every CIA2 source while we work
$E68D-$E68F	sample CIA2_TB_HI
$E690-$E692	read CIA2_ICR (which also clears its flags)
$E693-$E694	BPL $E679 - bit 7 clear means this NMI was not CIA2's
$E695-$E69B	if timer B's high byte fell between the two reads, OR in the timer B flag by hand
$E69C-$E69E	nmiMergeIcrFlags: OR in anything that arrived meanwhile
$E69F-$E6C7	transmit half: DEC txBitCounter; negative -> nmiStartNextChar; zero -> stop timer B with CIA2_CRB = $09, DEC uartPendingCount $E0A5, clear txCharActive; then SEC / ROR txShiftRegister and drive PA2 with the bit
$E6C8-$E6D7	CIA2_ICR = $82 (re-enable timer B); recover the flag byte, AND ciaIcrShadow, LSR -> C = timer A, bit 3 = the FLAG line
$E6D8-$E6F0	FLAG line = an RXD start-bit edge: ciaIcrShadow = $83, rxBitCounter = $83 (any negative value), arm timer A at half a bit time, start it, then reload the latch with a whole bit time
$E6F1-$E6FE	timer A tick: sample CIA2_PRB bit 0, DEC rxBitCounter; negative = start bit, zero = stop bit, else ROR rxShiftRegister
$E6FF-$E708	shared exit: CIA2_ICR = ciaIcrShadow, PLA / TAX / PLA / RTI
$E709-$E711	start bit must be low; if high -> reportLinkError. Otherwise rxBitCounter = 9
$E712-$E723	stop bit must be high; if low -> reportLinkError. Otherwise clear the stall counter $EB00 and carrierSampleTimer $E045, then pushUartRxRing
$E724-$E726	JSR reportLinkError - framing error, bad stop bit, or receive-ring overflow (C=1 from pushUartRxRing)
$E727-$E732	stop timer A (CIA2_CRA = 0), ciaIcrShadow = $92 (back to waiting for a start bit), branch to the shared exit

• Reads: CIA2_ICR, CIA2_TB_HI, CIA2_PRA, CIA2_PRB, ciaIcrShadow $E033, $E5BB-$E5C0.
• Writes: CIA2_ICR, CIA2_CRA, CIA2_CRB, CIA2_PRA bit 2, $E5BB-$E5C0, uartPendingCount $E0A5, ciaIcrShadow $E033, carrierSampleTimer $E045, the stall counter $EB00, and the UART receive ring $E42D/$E42F/$E430..$E443 through pushUartRxRing.
• Callers: the CPU NMI vector, once installCommNmiVector has written $FFFA/$FFFB.
• A correction to the shipped comment: the listing calls CIA2_CRB = $09 at $E6AD "stop timer B". $09 is START | RUNMODE(one-shot): it runs one more bit period - the stop bit - and then the CIA clears the START bit itself. That final underflow is the interrupt that drives txBitCounter negative and reaches nmiStartNextChar, which is how back-to-back characters are chained without waiting for the frame tick.

$E69C nmiMergeIcrFlags - range $E69C-$E69F

Three bytes: ORA CIA2_ICR. The tail of the timer B race workaround.

• In: A = the interrupt flags read so far.
• Out: A = those flags plus anything that arrived between the handler's two reads.
• Callers: fall-through from $E69A in this build. (XREF.txt shows a call:E444 for this address, but that entry belongs to trainerAiE000, a different overlay at the same address.)

$E73C queueByteForTransmit - range $E73C-$E743

The single door for outbound bytes.

• In: A = byte to transmit.
• Calls: pushUartTxRing $E51B, which silently drops the byte when the 22-byte ring already holds 22 and returns C=1 in that case.
• Writes: uartTxRing $E417, uartTxCount $E414, uartTxWriteIndex $E416; then INC uartPendingCount $E0A5 - unconditionally, even when the push overflowed. The design relies on startNextTxChar $E632 and flushUartTxRing $E53C to resynchronise $E0A5 when it drifts.
• Out: A preserved (callers such as sendNextModemCommandChar $E7D5 test what they just sent), X clobbered, Y unchanged, C = 0 if the byte was stored and 1 if it was dropped (no caller looks).
• Callers: JSR $E7D2 (sendNextModemCommandChar), $E81D (queueSyncByte), $E87C (queueRawSyncByte), $E92A (transmitPacketLoop inside sendPacket).
• 6551 note: A preserved and X clobbered are both relied on - transmitPacketLoop parks its index in $EAFE across the call precisely because X does not survive.

Addendum: hardware-touching code outside the requested list

Three more places touch the hardware and must be reimplemented or neutralised, even though they were not in the list:

• $E5D6 serviceCarrierAndSuspendRequest (range $E5D6-$E5FF) and $E5FF rearmCarrierTimer (range $E5FF-$E607). This is where carrier detect is actually read: EOR CIA2_PRB / AND #$10 / ADC #$F0 at $E5F1-$E5F7 turns PB4 into A=$F0 C=0 when DCD is low (carrier) and A=$00 C=1 when it is high, then SEC / ROR produces $F8 (carrier) or $80 (no carrier) in linkStatusSample $E03D. Bit 6 is the carrier flag, bit 7 the "data is flowing" flag. INC carrierSampleTimer $E045 / BPL keeps bit 7 only while a character has arrived within the last ~127 frames; otherwise rearmCarrierTimer re-parks the sample in $E045 (so the timer stays pinned negative) and strips bit 7. It also runs the suspend handshake at $E5D6-$E5E3 and falls straight into startNextTxChar. A 6551 build reads DCD from status bit 5 instead of CIA2_PRB bit 4 and must produce the identical $80/$F8 sample values, because pollCarrierState $E3CB debounces them against linkStatus over 240 frames and the game reads both bytes.
• $E327-$E331, inside readKeyAndHandleModemHotkeys. The C=+H hot key does LDA dtrToggleMask $E04C / EOR CIA2_PRB / STA CIA2_PRB, toggling PB2 (DTR) and PB5 directly. On a 6551 this becomes a toggle of command-register bit 0.
• The four raw ring primitives $E4D2 popUartRxRing, $E4EA popUartTxRing, $E502 pushUartRxRing, $E51B pushUartTxRing. Not hardware, but owned by this layer and called from the NMI. Their contracts (C=1 = empty / overflow, A = byte, X clobbered) are relied on by receiveByteTrackZeros $E743, beginByteSyncPhase $E80A, receivePacket $E9E9 and runModemStateMachine $E799.

4. Module RAM owned by the UART layer

Frozen? means the byte is inside $E01D-$E047 and so its disk value must not change, whatever its runtime meaning becomes.

Address	Name	Meaning in the stock driver	Frozen?	Needed by a 6551 build
$E033	ciaIcrShadow	The CIA2 ICR command byte the module currently wants: $92 idle, $83 while receiving a character, $7F when suspended. Written at $E593, $E6DA, $E72E; read at $E5A4, $E679, $E6CE, $E6FF - and by the main program at $5889, $58A8, $58CD, which stores it back into CIA2_ICR after banking the I/O area out	yes (disk value $90)	Keep, and pin it to $7F at run time. It is the only byte of this layer the game outside the module reads. If it holds $92, the game will re-enable the CIA2 FLAG NMI after every film-buffer access
$E039	nmiSuspendRequest	$C0 from the game before a disk load, 0 after; also written $00/$80 by setCiaNmiMask	yes	Keep, unchanged semantics
$E03A	nmiSuspendAck	$80 when the module's interrupt really is off, 0 when running. The game spins on this at $0F6A and $0F7B	yes	Keep, unchanged semantics
$E03C	linkStatus	Debounced: bit 6 carrier, bit 7 "characters still arriving". Read by the game at $1B4B (waits for bit 7 to clear before hanging up), $1BB6, $56B1, $65BC	yes	Keep, unchanged semantics
$E03D	linkStatusSample	The raw per-frame sample: $80 no carrier, $F8 carrier, bit 7 = data flowing. Read by the game at $1BAB	yes	Keep; source DCD from ACIA status bit 5
$E042	uartRestartRequest	1 = re-evaluate the connection, $FF = force connectionPhase to 0	yes	Keep, unchanged semantics
$E043	carrierDebounceCount	Consecutive frames the sample disagreed with linkStatus; 240 accepts the change	yes	Keep (it lives in pollCarrierState, above the seam)
$E044	txPaceCounter	Frames between transmitted characters. Decremented in startNextTxChar $E617, reloaded at $E61C/$E647; beginByteSyncPhase $E820-$E825 forces bit 1 on to space the sync bytes	yes	Effectively dead. The byte must survive because $E820 writes it, but the pacing gate can become a no-op
$E045	carrierSampleTimer	Zeroed by the NMI ($E719) on every good character; INCed once per frame; while it is negative the link counts as quiet. This is what produces bit 7 of linkStatus	yes	Keep. Same job, driven by "a byte arrived" instead of "a stop bit was good"
$E047	linkErrorCount	Bumped by countLinkError $E403 from the NMI receiver; non-zero makes runLinkStateMachine $E7FD restart the byte sync	yes	Keep. Feed it from the ACIA's framing/parity/overrun status bits
$E04A	carrierOverrideFlags	Bit 6 = "pretend carrier is present" (the C=+C hot key), for a direct cable with no DCD	no	Keep - it is the only way to play over a three-wire null-modem lead
$E04B	carrierOverrideToggleMask	$40, the bit C=+C toggles	no	Keep
$E04C	dtrToggleMask	$24 = the CIA2_PRB bits C=+H toggles (PB2 DTR + PB5)	no	Repurpose as the command-register DTR bit
$E04D	userPortDdrbValue	$26 - DDRB pattern	no	Dead
$E04E	userPortDtrDropped	$22 - PRB with DTR low	no	Repurpose as the "DTR dropped" command byte
$E04F-$E050	userPortIdleTable	Two entries, both $26 - PRB idle pattern by answer/originate	no	Dead (or repurpose as the idle command byte)
$E051-$E054	serialShiftPatternTable	$27 $2F $3F $37 - written to CIA2_SDR; purpose never established	no	Dead
$E055	baudIndex	0 = 300, 3 = 1200; also the stride into baudParameterTable	no	Keep as the index; the table it selects changes meaning
$E056	bitPeriodLo	Low byte of the CIA timer latch for one bit time	no	Dead as a timer latch. Natural replacement: the 6551 control-register byte
$E057	bitPeriodHi	High byte; $0D50 = 3408 cycles = 300.1 baud, $0353 = 851 = 1201.8 baud on NTSC	no	Dead
$E058	txPaceReload	Frames between transmitted characters: 1 at 300, 2 at 1200	no	Dead (see $E044)
$E059-$E05E	baudParameterTable	Two 3-byte entries {periodLo, periodHi, pacing}	no	Repurpose as {controlByte, spare, spare} per speed
$E0A4	frameInFlightFlag	The $E0A5 value the frame layer saw when it queued a frame; serviceLinkTick $E76E compares the two	no (protocol block)	Keep, untouched - it is above the seam
$E0A5	uartPendingCount	Characters queued for the UART that have not finished transmitting. INC at $E73F; DEC at $E6B0 (character finished) and $E5D2 (character abandoned); forced to 0 at $E634; set to txCharActive at $E53C	no (protocol block)	Keep - this is the single most important byte of the whole seam. Everything above waits on it: $E1EC, $E26E, $E628, $E76B, $E82D, $E860
$E0A6	packetInFlightCount	The byte count of the frame the packet layer handed over	no	Keep untouched. Structural constraint: sendPacketFsm addresses it as uartPendingCount,X with X = inFlightSlotIndex $E0A8 = 1 at $E1EC, $E265 and $E26E, so $E0A5 and $E0A6 must stay adjacent, in that order. (XREF.txt misses the write at $E265 because it is indexed, and the listing's claim that $E0A6 is only ever written with 0 is wrong for the same reason.)
$E414	uartTxCount	Bytes in the 22-byte transmit ring	no	Keep - the ring is the natural 6551 output queue
$E415/$E416	uartTxReadIndex / uartTxWriteIndex	Descending indices	no	Keep
$E417-$E42C	uartTxRing	22-byte descending circular buffer	no	Keep. It must hold a whole packet: sendPacket $E922-$E934 queues packetLength+1 bytes in one burst, gated only by $E860's "fewer than 2 pending" test
$E42D	uartRxCount	Bytes in the 20-byte receive ring	no	Keep
$E42E/$E42F	uartRxReadIndex / uartRxWriteIndex	Descending indices	no	Keep
$E430-$E443	uartRxRing	20-byte descending circular buffer, filled only by the NMI at $E71F	no	Keep. 20 bytes is the whole receive budget between frame ticks - see the hazards in section 7
$E5BB	txCharActive	Non-zero while a character is being shifted out. Read at $E539, $E5CD, $E60A, $E663; written at $E639, $E6B5	no	Keep, redefined as "a byte is sitting in the ACIA transmit register waiting for TDRE". flushUartTxRing and stopCommNmi both depend on it
$E5BC	txBitCountReload	9 = 8 data bits plus the stop bit	no	Dead
$E5BD	txBitCounter	Bits left in the character being sent	no	Dead
$E5BE	txShiftRegister	The character being shifted out, LSB first	no	Dead
$E5BF	rxBitCounter	Negative = awaiting the start-bit sample, 9..1 = data bits, 0 = stop bit	no	Dead
$E5C0	rxShiftRegister	The character being shifted in	no	Dead
$EB00	stall counter	Zeroed by the NMI at $E716 on every good character; noteIdlePoll $E997 counts dead service ticks and forces a resync at 16	no (ARQ block)	Keep the NMI's zeroing of it. It is the only other thing the receive path owes the layer above

Summary for a 6551 build: $E5BC-$E5C0 (five of the six software-UART bytes), $E056, $E057, $E058, $E04D, $E04F-$E054 and the pacing behaviour of $E044 all become dead. Everything else in the table stays, and $E0A5, $E5BB, $E045, $E03C, $E03D, $E039, $E03A, $E033, $E047 and $EB00 must behave exactly as they do now.

5. How the NMI decides an interrupt is not its own, and how it chains

This is the part the replacement has to copy instruction for instruction in spirit, because the C64's /NMI line is a wired-OR of the RESTORE key, CIA2's /IRQ and the expansion port's /NMI, and the game installs a handler of its own behind this module.

The test. At $E690 the handler does LDA CIA2_ICR. On a 6526, bit 7 of the interrupt data register is set when any enabled source has fired since the register was last read, and reading it clears all the flags. BPL $E679 at $E693 therefore means exactly "no enabled CIA2 source fired - this NMI belongs to someone else". Note the ordering: CIA2_ICR is written with $7F first ($E688-$E68C) to mask every source while the handler works, then CIA2_TB_HI is sampled, then the register is read. The mask write does not clear pending flags; only the read does.

The chain. $E679-$E684, which sits immediately before the handler entry:

E679  LDA ciaIcrShadow      ; $E033 - the mask this module wants
E67C  STA CIA2_ICR          ; undo the $7F we wrote at $E68A
E67F  PLA
E680  TAX                   ; restore X
E681  PLA                   ; restore A
E682  JMP (nmiChainVector)  ; $E031/$E032

Four properties the replacement must preserve:

1. A and X are restored before the chain, and Y is never touched at all. The handler saves A then X (PHA / TXA / PHA at $E685-$E687) and both exits pop them in the reverse order. Y is neither saved nor used anywhere in the handler, so the chained handler inherits the interrupted Y.
2. The chain is a JMP (abs), not a JSR and not an RTI. The CPU's NMI stack frame (P, PCH, PCL) is still intact and untouched, so the chained handler owns it and ends with its own RTI.
3. The vector is $E031/$E032, inside the frozen block. On disk it is $E010, a bare RTI opcode inside the jump table's constant pool. initInterruptVectors at $0BF3/$0BFB patches it to $1298, which is irqRti, a bare RTI in the main program. A replacement must read the vector from $E031/$E032 at run time and must not assume $1298.
4. The module's own interrupt mask is restored on both exits - $E67C on the chain path and $E702 on the normal path - from ciaIcrShadow $E033.

The 6551 version of the same test. Bit 7 of the ACIA status register at base+1 is the ACIA's IRQ flag, and reading the status register clears it - the direct analogue of reading CIA2_ICR. So:

        PHA
        TXA
        PHA
        LDA base+1            ; status; reading it clears the ACIA IRQ flag
        BPL notMine           ; bit 7 clear - not the ACIA's interrupt
        ... service TDRE (bit 4), RDRF (bit 3), and the error bits 2/1/0 ...
        LDA $E033
        STA CIA2_ICR          ; keep CIA2 masked exactly as the stock code does
        PLA
        TAX
        PLA
        RTI
notMine:
        LDA $E033
        STA CIA2_ICR
        PLA
        TAX
        PLA
        JMP ($E031)

with two additions that the stock design did not need:

• Do not write $7F to CIA2_ICR on entry and then restore $E033 unless $E033 is itself $7F. Simplest correct policy: set $E033 = $7F once at open time and never change it; then both the handler and the main program's $588C/$58AB/$58D0 restores keep CIA2 permanently silent, and the only NMI source left is the cartridge.
• Bank the I/O area in yourself. readFilmByte $5874, writeFilmByte $5893 and copyPageUnderIo $58B2 run with SEI and $01 = $34, which removes $D000-$DFFF - including the SwiftLink - from the address space. SEI does not mask NMI, and writing $7F to CIA2_ICR (which is what those routines do to silence the stock driver) has no effect on an expansion-port NMI. copyPageUnderIo holds that state for a 256-byte copy loop, roughly 2600 cycles, which at 38400 baud is about ten character times. The replacement handler must therefore save $01, force it to $35, do its work, and restore $01 before either exit. This is not optional: $EE4A loadFilmStartSnapshot, in the frozen tail of this very module, calls copyPageUnderIo twice.

One thing the stock handler does that is easy to miss: on every successfully received character it zeroes both carrierSampleTimer $E045 ($E719) and the stall counter $EB00 ($E716). The first feeds bit 7 of linkStatus, which the game waits on at $1B4B; the second is what stops noteIdlePoll $E997 from tearing the connection down after sixteen dead service ticks. A 6551 receive path that forgets either one will produce a link that hangs up on itself.

6. The SwiftLink baud rate doubling - verified

Claim under test: SwiftLink fits a 3.6864 MHz crystal, twice what the 6551 expects, so every rate in the control register's low nibble comes out doubled.

Conclusion: the claim is correct, and the mapping given in the task brief is right.

Second source: cc65's own SwiftLink serial driver, libsrc/c64/ser/c64-swlink.s, whose BaudTable maps the requested rate to the control-register value the hardware needs:

Requested	cc65 control value	6551 nominal rate for that value	doubled
150	$02	75	150
300	$05	150	300
600	$06	300	600
1200	$07	600	1200
2400	$08	1200	2400
3600	$09	1800	3600
4800	$0A	2400	4800
7200	$0B	3600	7200
9600	$0C	4800	9600
19200	$0E	9600	19200
38400	$0F	19200	38400

Every row is exactly 2x the nominal 6551 rate, with no exceptions, which is only consistent with a doubled reference clock. ($0D, nominal 7200, would give 14400; cc65 has no constant for it and leaves it unused - that is the only gap, and it is a gap in cc65's table, not in the hardware.) Corroborating hardware documentation: the GLINK232 and Turbo232 cartridges both state that they use a 3.6864 MHz oscillator, "double the standard for a 6551", specifically in order to match the SwiftLink baud rate table.

So: control byte = $10 OR rateBits (bit 4 = internal baud rate generator, bits 6-5 = 00 = 8 data bits, bit 7 = 0 = 1 stop bit), with $05 = 300, $07 = 1200, $08 = 2400, $0C = 9600, $0E = 19200, $0F = 38400.

Two caveats worth carrying into the implementation:

• Some SwiftLinks were rebuilt with the standard 1.8432 MHz crystal (cc65's header calls these the "hacked" SwiftLink). On those the table is the plain 6551 one and every rate is half of the above. If the driver ends up with a user-visible speed setting, it is worth documenting which crystal the numbers assume.
• The doubling is a property of the crystal, not of the chip, so it applies identically to a Turbo232 in SwiftLink-compatible mode. Turbo232's extra rates come from a separate register and are not reachable through the control register's low nibble.

7. Hazards checklist for the 6551 implementation

Two notes from later measurement. Hazard 2's "at 38400 baud a frame is about 200 character times" is wrong: at 3840 characters a second and 59.826 frames a second it is 64.2 (highRateReport.md section 1). The conclusion the hazard draws is unaffected - the 20-byte ring is still outrun - but the problem is three times smaller than the sentence implies, which is why 19200 survives. Hazard 8's "same 8N1 framing" is now true only of the data bits: the driver adopts the port's own rate, stop bits and clock source, forcing eight data bits and nothing else, so two SwiftLink ends agree on whatever their control registers hold while a stock user-port peer can only ever be 8N1 (portCompatReport.md sections 5 to 8, testReport.md sections 11.4 and 11.5). Parity is not adopted, because it lives in the command register the driver rewrites from constants. The text below is left as it was written.

1. $E0A5 is the heartbeat. Increment it in queueByteForTransmit, decrement it when the ACIA takes the byte, and make sure it can reach 0. If it never reaches 0, serviceLinkTick $E76E never clears $E0A4/$E0A6, sendPacketFsm $E26E never completes an exchange, and the game locks in lock-step forever. Note that on a 6551, "TDRE came back" means the holding register is free, one byte ahead of the wire - harmless here, since nothing above measures real wire time.
2. The receive ring is 20 bytes, only the frame tick drains it, and 17 of those bytes can be spoken for at once. awaitWholePacket $E9D9 does CPX uartRxCount / BCS countStalledPoll: it refuses to copy a packet body until the whole payload plus its check byte is already sitting in the ring. The length-code search at $E9CC yields a payload length of 1..16, so up to 17 bytes must be resident simultaneously and only 3 bytes of the 20-byte ring are genuine headroom. At 300 baud a frame holds at most one character; at 38400 baud a frame is about 200 character times. Either the driver must throttle (drop RTS by writing the command register with bits 3-2 = 00) or the ring has to be enlarged - and it cannot be enlarged in place without moving $E444 onwards. Practical answer: keep RTS handshaking honest, and only advertise rates the frame-tick drain rate can sustain.
3. Overrun, framing and parity (status bits 2, 1, 0) must reach reportLinkError $E3BC. That is the only thing that sets linkErrorCount $E047, and that is the only thing that makes runLinkStateMachine $E7FD restart the byte sync after a disk load has eaten part of a packet.
4. The disk-load suspend really must stop the interrupt. The fast loader at $0804 is cycle-exact. $E039/$E03A is the handshake; stopCommNmi is the routine; the 6551 equivalent is a command-register write with receiver IRQ disabled. Bytes arriving during the load are lost, and the ARQ layer is expected to recover - that is how the stock driver behaves too.
5. STA $DF59,Y at $E358 must go. See loadBaudParameters above: its dummy read hits $DF58 = the data register on a $DF00-strapped SwiftLink.
6. Do not touch CIA2_PRA. PA0/PA1 are the VIC bank select and PA3-PA5 are the serial bus. The stock code only ever read-modify-writes bit 2; a 6551 build should leave the register alone entirely and make $E56B (the tail setCiaNmiMask jumps to) a plain RTS or a harmless equivalent.
7. $E033 must end up holding $7F at run time while keeping its $90 disk byte, so that the main program's post-film-access restores at $588C, $58AB and $58D0 do not re-arm a CIA2 NMI source behind the driver's back.
8. Wire compatibility. Nothing above the seam changes, so the module stays byte-for-byte compatible with the stock driver on the wire at the same line rate: same 8N1 framing, same $00/ $FF byte-sync handshake, same length/control/sequence/checksum frame, same retransmit rules. Two machines can only talk if both ends use the same speed, because the speed is not negotiated (the only automatic change is the CONNECT 1200 sniff at $E7A9, which is a Hayes-modem behaviour).
9. W65C51N replicas. Real SwiftLinks use a 6551 whose TDRE bit works. Some modern rebuilds use a WDC W65C51N, on which TDRE reads as permanently set; a driver that polls TDRE will overrun the transmitter on those boards and needs a timed delay per character instead. Worth a note in the final driver's comments even if the target is a genuine cartridge or VICE's emulation.