# spec_link.md - what surrounds the UART in the $E000 opponent module

Reference for the SwiftLink replacement of the bit-banged user-port UART in
`disassembly/game/modemDriverE000.s`.  Everything here was read out of the listings in
`disassembly/game/` (mainly `modemDriverE000.s` and `mainProgram0800.s`); every address quoted was
checked against them.  Nothing in this document proposes changing the layers above the UART - the
point of the exercise is that they stay bit-for-bit the same so the two builds remain wire
compatible at the same line speed.

Read `docs/overview.md` section 9 first for the shape of the module.


## 0. The layer boundary

`swiftlink/checkAbi.py` freezes three regions: `$E000-$E017` (the jump table), `$E01D-$E047`
(variables the game reads and writes) and `$EC00-$EFFF` (utilities the map generator overlay calls).
The rest is ours, but only the following is genuinely hardware specific.

| Range | Routine(s) | Bytes | Keep the entry address? |
|---|---|---|---|
| `$E534-$E53F` | `flushUartTxRing` | 12 | yes - called from `$E791` and `$E80F` |
| `$E540-$E573` | `configureUserPortLines` | 52 | yes - called from `$E2D5` and `$E387` |
| `$E574-$E57A` | `dropDtrLine` | 7 | yes - called from `$E38D` |
| `$E57B-$E585` | `installCommNmiVector` | 11 | yes - called from `$E2CC` |
| `$E586-$E592` | `restartUart` | 13 | yes - called from `$E2CF` and `$E5E1` |
| `$E593-$E5B5` | `setCiaNmiMask` | 35 | internal (only `$E590` fall-through and `$E5CA`) |
| `$E5B6-$E5C0` | `clearUartState` + its 6 inline data bytes | 11 | internal |
| `$E5C1-$E5C2` | `suspendUartIfRunning` | 2 | internal (`$E5DD`) |
| `$E5C3-$E5D5` | `stopCommNmi` | 19 | yes - called from `$E2AB` |
| `$E5D6-$E5FE` | `serviceCarrierAndSuspendRequest` | 41 | yes - called from `$E3CB` |
| `$E5FF-$E606` | `rearmCarrierTimer` | 8 | internal |
| `$E607-$E653` | `startNextTxChar` | 77 | internal (`$E604` fall-through, `$E673`) |
| `$E654-$E662` | `setBitPeriodFull` / `setBitPeriod` | 15 | internal |
| `$E663-$E684` | `nmiStartNextChar` | 34 | internal |
| `$E685-$E732` | `commNmiHandler` | 174 | internal (reached through `$FFFA/$FFFB`) |
| `$E73C-$E742` | `queueByteForTransmit` | 7 | yes - called from `$E7D2`, `$E81D`, `$E87C`, `$E92A` |

That is `$E534-$E732` plus `$E73C-$E742`, 518 bytes in all.  Six 6551 registers replace all of it,
so there will be a lot of padding.

Everything else in the module is untouched by the hardware change:

* the four ring buffers and their push/pop routines, `$E40F-$E533` (the two "UART" rings are just
  memory; only their producer and consumer change);
* the three indirect link-I/O vectors `$E3B6/$E3B9/$E3BC` and the table at `$E3BF`;
* the frame/ARQ layer `$E909-$EAB2` and its state block `$EAB7-$EB02`;
* the packet/chat layer `$E111-$E2FF`.

Three data bytes are the interface between the baud table and the UART: `$E056`, `$E057` and `$E058`
(section 4).  Their meaning is private to the module, so the SwiftLink build may redefine them.

The single most important software contract across the boundary is **`uartPendingCount` at `$E0A5`**:
the number of characters handed to the transmitter that have not physically left the machine.  Four
places above the UART read it and will misbehave if it lies:

* `$E76B` `serviceLinkTick` compares it with `frameInFlightFlag` `$E0A4` to decide that a queued
  packet has drained and a new one may be built;
* `$E82D` `continueByteSync` waits for it to reach 0 before sending the next `$00` sync byte;
* `$E860` `servicePacketTransmit` refuses to start anything new while it is 2 or more;
* `$E539` `flushUartTxRing` resets it from `txCharActive` `$E5BB`.

`queueByteForTransmit` `$E73C` increments it; the stock NMI decrements it at `$E6B0` when a character
finishes and zeroes it at `$E634` if the ring unexpectedly runs dry.  A 6551 build must keep the same
accounting, counting a byte as pending until TDRE says the transmit register has taken it.

`$E044` `txPaceCounter` is a transmitter throttle owned by the UART layer, but `beginByteSyncPhase`
reaches into it: `$E820-$E825` ORs bit 1 in so that at least two transmit slots separate the sync
bytes.  The replacement must tolerate that write (and may simply ignore the byte).


## 1. The suspend/resume handshake ($E039 request, $E03A acknowledge)

The fast loader (`$0804` and the drive code) transfers bytes with a two-bit handshake on CIA2 port A
timed against `$D012`.  It cannot survive an NMI, so before any disk access the game parks the
opponent module and waits for it to confirm.

### Game side

`suspendCommModule` `$0F5F`:

```
0F5F  pha                 ; A must survive
0F60  lda $E03B           ; isLinkActive - no link (or the trainer) means nothing to suspend
0F63  beq $0F6F
0F65  lda #$C0            ; the request code
0F67  sta $E039           ; nmiSuspendRequest
0F6A  lda $E03A           ; nmiSuspendAck ...
0F6D  bpl $0F6A           ; ... spin until bit 7 is SET
0F6F  pla
0F70  rts
```

`resumeCommModule` `$0F71` is the mirror image: it stores `$00` into `$E039` at `$0F78` and spins at
`$0F7B` until bit 7 of `$E03A` is **clear**.

Both are reached through `suspendCommForDiskAccess` `$10CB` and `resumeCommAfterDiskAccess` `$10D1`,
which also put "WORKING..." on the status line.  Callers: `$0B3D`, `$1030`, `$103E`, `$1044`,
`$1086`, `$10A8`, `$10DC` in the main program and `$7B7D`, `$7DF7`, `$7DFE`, `$7F57`, `$7F95`,
`$815E`, `$81A2`, `$81AF` in the map-generator overlay.  `waitForGameDiskInserted` `$10DC` suspends
and deliberately leaves the module suspended for its caller.

### Exact values

| Byte | Value | Meaning |
|---|---|---|
| `$E039` `nmiSuspendRequest` | `$00` | no request - run normally |
| | `$C0` | the game wants the module's interrupts off (only bit 7 is ever tested) |
| | `$80` | written by the module itself when it parks (see below) |
| `$E03A` `nmiSuspendAck` | `$00` | interrupts are running |
| | `$80` | interrupts are off; the disk may be touched |

Only bit 7 matters on both bytes.  `$E5DD` tests the request with `BMI`, and `$0F6D`/`$0F7E` test the
acknowledge with `BPL`/`BMI`.

### Module side, and where it runs

The handshake is served from `pollLinkStatus` `$E00C` -> `pollCarrierState` `$E3CB` ->
`serviceCarrierAndSuspendRequest` `$E5D6`, which the raster IRQ calls once per frame at `$112C`
(right after the `$E000` X=0 tick at `$1129`).  **The game's spin loops therefore depend on the
raster IRQ still running**; the module never answers from the store itself.  (The solo trainer
answers from its `$E000` X=0 entry instead, at `$E059-$E05C` of `trainerAiE000.s`, by copying `$E039`
straight into `$E03A`.  Either entry is acceptable - the raster IRQ calls both, in that order.)

The stock sequence at `$E5D6`:

```
E5D6  lda $E03A       ; acknowledge
E5D9  asl a           ; C = "already suspended"
E5DA  lda $E039       ; request
E5DD  bmi $E5C1       ; bit 7 set -> suspendUartIfRunning
E5DF  bcc $E5E4       ; no request and not suspended -> carry on to the carrier sample
E5E1  jsr $E586       ; no request but still suspended -> restartUart
E5E4  ...             ; carrier sampling (section 2)
```

`suspendUartIfRunning` `$E5C1` is a two-byte `BCS $E5D5` that returns at once when the suspend has
already been acknowledged, otherwise it falls into `stopCommNmi` `$E5C3`.

`stopCommNmi` does three things: writes `$FF` to `uartRestartRequest` `$E042` (which forces
`connectionPhase` `$E040` back to 0 on the next tick of the modem state machine), calls
`setCiaNmiMask` with `$7F` to disable every CIA2 interrupt source, and decrements `uartPendingCount`
`$E0A5` if a character was half way out of the transmitter, because that character will never finish.

`setCiaNmiMask` `$E593` is where the two handshake bytes are actually written:

```
E5A9  eor #$FF        ; $92/$83 -> $00, $7F -> $80
E5AB  and #$80
E5AD  sta $E039       ; nmiSuspendRequest
E5B0  sta $E03A       ; nmiSuspendAck
```

so an enable mask clears both bytes and the disable mask sets both to `$80`.  Note that the module
overwrites the game's `$C0` request with its own `$80`; that is deliberate and harmless, because on
the next frame `$E5DD` still sees bit 7 set and `$E5C1` short-circuits.

`restartUart` `$E586` is the resume path: it zeroes the six bit-level UART state bytes `$E5BB-$E5C0`,
writes 1 to `uartRestartRequest` `$E042` ("re-evaluate the connection but keep the phase"), primes
`carrierSampleTimer` `$E045` with a negative value, and falls into `setCiaNmiMask` with `$92`, which
clears both handshake bytes.  `restartUart` is also the cold-start path, called from `openCommLink`
at `$E2CF`.

### What the SwiftLink UART layer must do

**On suspend** (`$E039` bit 7 set and `$E03A` bit 7 clear):

1. Silence the ACIA completely.  The expansion-port NMI is non-maskable, so it is not enough to set
   `SEI`; the interrupt source itself must go.  Set command-register bit 1 (receiver IRQ disable) and
   leave the transmit control bits at "TX IRQ off".  Do **not** clear command bit 0 - that is DTR,
   and dropping it makes a Hayes modem hang up (section 3).
2. Read the status register once afterwards so any already-latched IRQ flag is cleared.
3. Decide what to do about the character that may be mid-transmission.  The stock code decrements
   `$E0A5` for it (`$E5CD-$E5D4`); the same reasoning applies, since after a disk load the peer will
   have to resynchronise anyway.
4. Set `uartRestartRequest` `$E042 = $FF` so the connection falls back to phase 0, exactly as
   `stopCommNmi` does.  The frame layer will then rebuild byte sync, which is the right answer
   because incoming bytes were dropped on the floor while the drive was busy.
5. Set `$E039 = $80` and `$E03A = $80`.

**On resume** (`$E039` bit 7 clear and `$E03A` bit 7 set):

1. Re-enable the receive interrupt (command bit 1 clear, bit 0 still set).
2. Throw away whatever the receiver may have latched during the load - read the data register once
   and clear the overrun/framing/parity bits by reading status.
3. Clear the module's own bit-level state, set `uartRestartRequest` `$E042 = $01`, and re-prime the
   quiet-line timer `carrierSampleTimer` `$E045` with a negative value, as `restartUart` does.
4. Set `$E039 = $00` and `$E03A = $00`.

**Do not touch CIA2 at all.**  The stock `configureUserPortLines` writes `CIA2_CRA = $51` (starts
timer A with the serial port in output mode), `CIA2_TA_LO/HI`, `CIA2_SDR`, `CIA2_DDRB = $26`,
`CIA2_PRB` and `CIA2_PRA` bit 2.  The fast loader owns CIA2 port A bits 4-7 and its own DDR; leaving
CIA2 alone removes a whole class of interference that the stock driver had to suspend around.  The
SwiftLink build still has to suspend, because the ACIA's NMI would wreck the loader's cycle timing
just as thoroughly.

**The NMI chain must be preserved.**  `installCommNmiVector` `$E57B` writes `$E685` into `$FFFA/$FFFB`
(the ROMs are banked out, so the vectors are RAM).  When the NMI was not the module's, the stock
handler restores the interrupt mask and jumps through `nmiChainVector` `$E031/$E032`, which the game
patches to `$1298` (a bare `RTI`) at `$0BF3/$0BFB`.  `$E031/$E032` are inside the frozen block, so
the SwiftLink handler must keep chaining through them - that is the path the RESTORE key takes.


## 2. Carrier detection

### Where the bit comes from in the stock driver

`serviceCarrierAndSuspendRequest` `$E5D6`, after the suspend handshake:

```
E5E4  lda $E03B        ; isLinkActive - if the link was never opened, do not sample at all
E5E7  beq $E662        ; (an RTS)
E5E9  lda $E04A        ; carrierOverrideFlags
E5EC  bmi $E604        ; bit 7 would publish A verbatim (no code in the image ever sets it)
E5EE  asl a            ; bit 6 -> bit 7
E5EF  bmi $E5F8        ; the C= + C override is on: report carrier without reading the line
E5F1  eor $DD01        ; CIA2_PRB, through $E04A as a polarity mask (normally $00)
E5F4  and #$10         ; PB4
E5F6  adc #$F0         ; PB4 high -> A=$00 C=1 ; PB4 low -> A=$F0 C=0
E5F8  sec
E5F9  ror a            ; -> $80 no carrier, $F8 carrier, $C0 override
E5FA  inc $E045        ; carrierSampleTimer
E5FD  bpl $E604        ; still positive: a character arrived recently, keep bit 7
E5FF  sta $E045        ; quiet line: park the (negative) sample here so the timer stays negative
E602  and #$7F         ; and strip the "data flowing" bit
E604  sta $E03D        ; linkStatusSample
```

**The user-port bit is `CIA2_PRB` bit 4 (PB4), user-port pin H, the standard C64 RS-232 DCD input,
and carrier means PB4 reads LOW.**  That inversion is the level converter's doing: on the user port
the RS-232 control lines arrive TTL-inverted, so an asserted (positive) DCD at the connector shows up
as a 0 at the CIA.  With no interface plugged in, PB4 floats/pulls high and the driver reports "no
carrier" - which is why the C= + C override exists.

`$E04A` `carrierOverrideFlags` doubles as a polarity mask because of the `EOR $DD01`: setting bit 4
there would invert the sense of the DCD test.  No code writes bit 4; only bit 6 is toggled, by the
C= + C hot key through `$E04B` `carrierOverrideToggleMask` = `$40`.

The three possible raw samples, before the quiet-line adjustment:

| Condition | `$E03D` |
|---|---|
| PB4 high (no carrier) | `$80` |
| PB4 low (carrier) | `$F8` |
| C= + C override active | `$C0` |

and with bit 7 stripped when the line has been quiet: `$00`, `$78`, `$40`.

### The "data is flowing" bit (bit 7)

`carrierSampleTimer` `$E045` is incremented once per frame here and zeroed by the NMI receiver at
`$E719` on every character that arrives with a good stop bit.  Starting from 0 it takes 128 frames
(about 2.1 s NTSC, 2.6 s PAL) to go negative, at which point `rearmCarrierTimer` `$E5FF` stores the
sample into it - a negative value - so it stays negative until the next good character resets it to
0.  Bit 7 of `$E03D` therefore means "a character has been received in the last ~2 seconds".

The SwiftLink build must reproduce this: zero `$E045` from the receive path each time a byte is taken
out of the ACIA's data register with no framing/parity error.

### Debouncing, and how it reaches `$E03C`

`pollCarrierState` `$E3CB` (the `$E00C` implementation):

```
E3CB  jsr $E5D6            ; suspend handshake + fresh sample
E3CE  lda $E03D            ; linkStatusSample
E3D1  cmp $E03C            ; linkStatus
E3D4  beq $E3E3            ; agrees - reset the debounce count
E3D6  inc $E043            ; carrierDebounceCount
E3D9  ldx $E043
E3DC  cpx #$F0             ; 240 consecutive disagreeing samples
E3DE  bcc $E3EA
E3E0  sta $E03C            ; accept the new value
E3E3  ldx #$00
E3E5  stx $E043
E3E8  beq $E3F2
E3EA  and #$80             ; meanwhile take only the "data flowing" bit ...
E3EC  ora $E03C            ; ... and merge it in (this can only SET bit 7, never clear it)
E3EF  sta $E03C
E3F2  rts
```

240 frames is about 4.0 s NTSC / 4.8 s PAL - deliberately slow, because a modem's DCD twitches during
negotiation.  It applies to the first acquisition too, so "WAITING FOR CONNECTION..." sits on screen
for at least four seconds after carrier appears.

Note the asymmetry at `$E3EA`: between accepted transitions the merge can only turn bit 7 on.  Bit 7
of `$E03C` therefore only ever falls when a whole new sample is accepted, i.e. after 240 frames.
`hangUpModemSetState` at `$1B4B` relies on exactly that (see below).

### The three bytes the rest of the game reads

| Byte | Written by | Read by |
|---|---|---|
| `$E03B` `isLinkActive` | `openCommLink` `$E2D2` (`INC` -> 1); cleared by `clearLinkVars` `$E2AE`; forced to 0 by the game at `$1B01` in a trainer game | `$0F60`, `$0F71`, `$1331`, `$1352`, `$1A40`, `$1A8C`, `$1B20`, `$1B38`, `$1B5F`, `$4E46`, `$795D`, and `$E13E` inside the module |
| `$E03C` `linkStatus` | `pollCarrierState` only | `$1B4B` (bit 7), `$1BB6` (bit 6), `$56B1` (bit 6), `$65BC` (bit 6); inside the module `$E2F8`, `$E622`, `$E787`, `$E7E3` |
| `$E03D` `linkStatusSample` | `serviceCarrierAndSuspendRequest` only | `$1BAB` (bit 6); inside the module `$E61F` |

`$E03B` is **not** carrier-derived.  It only says "`$E003` X=0 has been called and the UART has been
opened".  Do not make it depend on DCD.

Bit meanings, which must not change:

* `$E03C` bit 6 = carrier present (debounced).  `pollMenuSession` `$56B1` tears the whole session down
  and jumps to `disconnectFromOpponent` `$1C17` when it is clear; `waitForCarrier` `$1BB6` spins until
  it is set; the VOICE PAUSE handler `$65BC` uses it to decide whether to warn the opponent first.
* `$E03C` bit 7 = data has been flowing.  `hangUpModemSetState` `$1B4B` waits (up to `$26` ticks of
  `zp_7F`) for it to go clear after telling the player to pick up the handset.
* `$E03D` bit 6 = the *undebounced* carrier bit.  `waitForCarrier` `$1BAB` uses it to step a countdown
  that nothing ever tests, so only bit 6's value matters, not its timing.

### Reading DCD on the 6551 instead

Status register (`base+1`) bit 6 is the DCD line and **it is active low**, so:

```
        lda ACIA_STATUS         ; base+1
        and #$40                ; bit 6: DCD line
        ; Z=1 (bit clear) means carrier present
```

Two SwiftLink-specific facts, both from CMD's own SwiftLink-232 Application Notes v1.1
(<http://csbruce.com/cbm/ftp/reference/swiftlink.txt>), sections 3.2 and 4:

1. **DCD and DSR are swapped at the ACIA on the SwiftLink.**  CMD deliberately exchanged the two
   signals so the 6551's receiver (which the chip gates on its own /DCD pin) stays enabled at all
   times while the user still gets to see the modem's DCD.  The result is that **status bit 6 reflects
   the modem's DCD line and bit 5 reflects DSR**, which is the *opposite* of the plain 6551 data
   sheet and of the register summary in this project's task brief.  Use bit 6.
2. **An unwired DCD reads as carrier present.**  There are pull-up resistors on DCD, DSR and CTS, so
   "if you happen to use a cable that is missing the DCD line, the pull-up resistor will pull the line
   active, so that bit #6 in the status register would be cleared".  For a null-modem cable that
   carries only TxD, RxD and ground this is exactly the behaviour the game wants: permanent carrier,
   no need for the C= + C override at all.

Also worth knowing: a state change on DCD or DSR raises an ACIA interrupt in its own right, so the
NMI handler must be prepared for an NMI in which neither RDRF nor TDRE is set.  Reading the status
register clears the interrupt flag.

**Caution about dummy reads.**  On the 6502, `STA abs,Y` and `LDA abs,X` perform a read at the
un-carried address whenever the index crosses a page.  `loadBaudParameters` `$E353` uses
`sta $DF59,y` with Y = `$FD..$FF` to reach `$E056-$E058`; the un-carried read lands on `$DF56`.  If
the cartridge is strapped to `$DF00` and mirrors its four registers through the page, `$DF56` aliases
the command register (`$56 & 3 = 2`), which is harmless - but the same trick landing on `$DF55` would
alias the *status* register, and reading status clears the pending interrupt flag.  Avoid
absolute-indexed addressing whose un-carried address can fall inside the ACIA's page.


## 3. The modem state machine ($E756) and connection phases ($E040)

### Call path

Raster IRQ `$1129` -> `$E000` X=0 -> `commRequestDispatch` `$E111` -> `serviceCommTick` `$E12F`.
`serviceCommTick` takes the re-entrancy lock `serviceLock` `$E0A7` (which rests at 1), always calls
`runModemStateMachine` `$E756`, and only when `connectionPhase` `$E040` >= 3 **and** `$E03B` is
non-zero does it also run `receivePacketFsm` `$E14D` and `sendPacketFsm` `$E1DD`.

`runModemStateMachine` falls through into `sendNextModemCommandChar` `$E7CA` and from there into
`runLinkStateMachine` `$E7F7`, so one call walks the whole chain.

### The four phases

| `$E040` | Name | What runs | Border (see below) |
|---|---|---|---|
| 0 | idle / link down | `$E765` sees phase 0 with no restart request and returns immediately | black / yellow |
| 1 | modem command + terminal mode | `serviceModemInput` `$E799` and `sendNextModemCommandChar` `$E7CA` shuttle characters between the modem and the two host rings | light blue / blue |
| 2 | byte sync | `beginByteSyncPhase` `$E805` / `continueByteSync` `$E828` | light red / red |
| 3 | packet protocol | `runPacketPhase` `$E858`, plus the packet FSMs above | light green / green |

Phase 0 is entered by `stopCommNmi` writing `$FF` into `uartRestartRequest` `$E042`, which
`$E75D-$E762` consumes by storing 0 into `$E040`.  A request of `$01` (from `restartUart`) means
"re-evaluate but keep the phase".

### How phase 1 is entered and left

```
E77B  lda #$01
E77D  cmp $E040
E780  beq $E799        ; already in terminal mode
E782  ldx $E03F        ; modemReplyTimer
E785  bne $E791        ; a modem dialogue is under way -> enter/stay in terminal mode
E787  bit $E03C        ; debounced carrier byte
E78A  bvs $E7F7        ; V = bit 6 = carrier: skip the modem dialogue entirely
E78C  jsr $E0C3        ; popHostOutRing - no carrier: discard everything queued for the opponent
E78F  bcc $E78C
E791  jsr $E534        ; flushUartTxRing
E794  lda #$01
E796  sta $E040        ; phase 1
```

So terminal mode is entered when **either** an AT command is in flight (`$E03F` non-zero) **or** there
is no carrier.  `$E78A` is the important branch: with carrier present and no AT string pending, the
module jumps straight to `runLinkStateMachine` and never visits phase 1.

Leaving phase 1 goes through `modemReplyTimer` `$E03F`:

* `queueModemCommandString` `$E393` sets it to `$FF` (negative = "a command string is going out").
* `sendNextModemCommandChar` arms it with `$79` = 121 frames (~2.0 s NTSC) when it transmits the CR
  that terminates an AT command (`$E7D5-$E7DE`).
* `$E7E3-$E7E9`: while `$E03C` bit 6 is clear the timer is pinned at 1, so it fires on the first tick
  after carrier appears.
* When it reaches 0 the module fabricates a CR into the host input ring (`$E7F2/$E7F4`) so the chat
  line unblocks, and falls straight into `runLinkStateMachine`.

`runLinkStateMachine` `$E7F7` then dispatches: any non-zero `linkErrorCount` `$E047` restarts byte
sync whatever the phase; phase 2 continues the sync at `$E828`; phase 3 or above runs the packet
protocol; phases 0 and 1 fall through into a fresh `beginByteSyncPhase`.

### Where the Hayes strings live and how they go out

Three canned strings sit in page `$EB`, **stored back to front**, because
`queueModemCommandString` `$E393` copies them forwards into `hostOutRing+1` (`modemCommandChars`
`$E092`) and then sets the read index to the character count, and `popHostOutRing` walks that index
downwards.

| Address | Emitted as | Queued by |
|---|---|---|
| `$EBD6` `modemHangUpString` | delay `$A0`, `+`, `+`, `+`, delay `$A0`, CR, delay `$C0`, `A`, `T`, `H`, `0`, CR | `hangUpModem` `$E390`, via `hangUpStringPtrLo` `$EBFD` = `$D6` |
| `$EBE3` `modemAnswerInitString` | delay `$C0`, `ATQ0V1X1A`, CR | `openCommLink` `$E2E3` when `$E011` = 0 |
| `$EBF0` `modemDialInitString` | delay `$C0`, `ATQ0V1X1D`, CR | `openCommLink` `$E2E3` when `$E011` = 1 |

`modemInitStringPtrLoTable` `$EBFE` holds the two low bytes `$E3,$F0`; the high byte `$EB` is the
un-patched half of the self-modifying `LDA $EB00,x` at `$E3A1`.

A queued byte with bit 7 set is never transmitted: `$E7D0` parks it in `modemDelayCounter` `$EB01` as
a negative frame count, which `tickGuardDelay` `$E7C0` counts back up to zero.  That is how the Hayes
`+++` guard times are produced (`$A0` = 96 frames, `$C0` = 64 frames).

Two things worth noticing about the dial string: it is `ATD` with **no telephone number**, and the
game's prompts ("GET OPPONENT ON PHONE AND...", "PRESS A OR O AND SET MODEM.", "PRESS SPACE, WAIT,
HANGUP PHONE.") make it clear that the players are expected to establish the voice call by hand and
then hand the line to the modems.  Modem Wars never dials anybody.  So a direct-cable build loses
nothing by not dialling.

`$E048` `modemOptionFlags` (`$CC` on disk) gates all of this:

* bit 7 = "a Hayes modem is attached".  `queueModemCommandString` `$E393` tests it first and returns
  `A = $FF` without doing anything when it is clear - **no AT string is ever queued and `$E03F` is
  never set**.  `serviceModemInput` `$E79E` also discards everything received in phase 1 when it is
  clear.
* bit 6 = "watch the verbose result codes".  `checkConnectSpeed` `$E7A7` sniffs for a CR preceded by
  `'0'` (the last digit of `CONNECT 1200`; a plain `CONNECT` ends in `T` and is ignored) and switches
  to the second baud entry.

`$E048` is at `$E048`, one byte past the end of the frozen block `$E01D-$E047`, so the SwiftLink build
is free to change it.

### What a direct null-modem connection has to skip

Set `$E048` bit 7 clear (and bit 6 clear - there is no result code to sniff).  Then:

* `openCommLink` `$E2E1-$E2E3` still calls `queueModemCommandString`, but it returns immediately, so
  `$E03F` `modemReplyTimer` stays 0 and `hostOutCount` `$E02E` stays 0.
* Because `$E02E` stays 0, the chat editor at `$1357` opens straight away instead of waiting for an
  AT string to drain.
* On the first tick after `openCommLink`, `$E782` finds `$E03F` = 0 and `$E787` finds carrier, so
  `$E78A` branches to `runLinkStateMachine` and the module goes 0 -> 2 -> 3 without ever entering
  phase 1.  Nothing needs to be cut out of the state machine; it already has the path.
* `hangUpModem` `$E38D` still calls `dropDtrLine` `$E574` and then `queueModemCommandString`, which
  again does nothing.  On the ACIA the equivalent of `dropDtrLine` is clearing command bit 0, which
  also disables the receiver and all interrupts - that is the correct behaviour for "hang up", and
  `commLinkControlDispatch` `$E2A2-$E2A9` immediately follows it with `stopCommNmi`.  Note `$E2A5`
  spins on `modemReplyTimer` `$E03F` until `LSR` leaves zero, i.e. until it is 0 or 1; with no modem
  configured `$E03F` is already 0, so that loop exits at once.
* Carrier: with no DCD wire the SwiftLink's pull-up reports carrier permanently, so `$E03C` bit 6
  settles set after the 240-frame debounce and stays there.  The C= + C override is then redundant,
  but it costs nothing to leave it working for people whose cable does carry a real DCD.

The one thing a null-modem build genuinely must handle differently is **who starts talking first**.
The byte-sync handshake at `$E805` is symmetric (both ends send `$00` until they see a `$00`, then
answer `$FF` and wait for the peer's `$FF`, restarting after ten fruitless rounds), so answer and
originate are interchangeable at that level.  `$E011` `isOriginateMode` still matters, though: the
game asks the ANSWER/ORIGINATE question at `$0CBD` and stores the result at `$0CDE`, and the stock
module uses it to pick the AT string (`$E2DD`), to index `userPortIdleTable` `$E04F` (both entries are
`$26`, so it makes no difference) and to index `serialShiftPatternTable` `$E051` together with
`baudIndex`.  A SwiftLink build should keep reading `$E011` if it wants the two ends to disagree about
anything (for example, to pick different bit patterns), but nothing above the UART requires it.

### Border-colour indicator (useful while bringing the new UART up)

`readKeyAndHandleModemHotkeys` `$E2F0-$E30E` paints `VIC_BORDER` from `linkStatusBorderTable` `$E05F`
using `index = connectionPhase*2 + carrier`.  Each byte is `colour*2 + always-paint`:

| Index | Byte | Colour | Painted |
|---|---|---|---|
| 0 (phase 0, no carrier) | `$00` | black | only while C= is held |
| 1 (phase 0, carrier) | `$0E` | yellow | only while C= is held |
| 2 (phase 1, no carrier) | `$1D` | light blue | always |
| 3 (phase 1, carrier) | `$0D` | blue | always |
| 4 (phase 2, no carrier) | `$14` | light red | only while C= is held |
| 5 (phase 2, carrier) | `$04` | red | only while C= is held |
| 6 (phase 3, no carrier) | `$1A` | light green | only while C= is held |
| 7 (phase 3, carrier) | `$0A` | green | only while C= is held |

Hold the Commodore key and the border tells you which phase the link is in.  Note the whole hot-key
path (and therefore this indicator) is skipped while `inputLockoutTimer` `$0B7D` is non-zero, because
the raster IRQ only calls `pollKeyboardEvent` `$0E56` at `$11E7` when it is 0.


## 4. Baud selection

### The stock table and what reads it

`baudParameterTable` `$E059`, two 3-byte entries, indexed by `baudIndex` `$E055` (0 or 3):

```
E059  $50 $0D $01      ; entry 0: bit period $0D50 = 3408 cycles = 300.1 baud, pacing 1
E05C  $53 $03 $02      ; entry 1: bit period $0353 =  851 cycles = 1201.8 baud, pacing 2
```

(3408 and 851 cycles against the NTSC 1022727 Hz system clock.)

`loadBaudParameters` `$E353` copies three bytes from `baudParameterTable+X` into
`bitPeriodLo` `$E056`, `bitPeriodHi` `$E057` and `txPaceReload` `$E058`, using
`ldy #$FD` / `sta $DF59,y` so one register both counts and indexes (`$DF59 + $FD = $E056`).  It
returns `A = $FF`, which is what the hot-key path needs in order to swallow the key.

Three call sites, all inside the module:

| Caller | X | Why |
|---|---|---|
| `openCommLink` `$E2C9` | `baudIndex` `$E055` | cold start |
| C= + 3 / C= + 1 hot keys, falling through `$E350` | 0 / 3 | player choice |
| `switchTo1200Baud` `$E7B2` | 3 (loaded at `$E7B0`) | `CONNECT 1200` was seen on the line |

`$E056/$E057` are consumed by `setBitPeriod` `$E657` (which programs CIA2 timer A or timer B) and by
the half-bit start-bit delay at `$E6E2`; `$E058` reloads `txPaceCounter` `$E044` at `$E644`.  All
three are private to the UART layer, so the SwiftLink build may redefine them - for example as
{control-register byte, spare, spare}, or a wider table with more entries.

**The game never writes `$E055`, `$E056`, `$E057` or `$E058`, and never reads them.**  There is no
saved baud preference anywhere: `baudIndex` is reset to its disk value (`$00` = 300 baud) every time
the module is reloaded from track 34, and `clearLinkVars` does not touch it because it lies outside
`$E039-$E047`.  The only thing the game stores about the link setup is `$E011` `isOriginateMode`,
written at `$0CDE` from the A/O prompt.

`$E051` `serialShiftPatternTable` (`$27,$2F,$3F,$37`, indexed by `isOriginateMode EOR baudIndex`) and
`$E04F` `userPortIdleTable` are user-port artefacts with no SwiftLink equivalent; the shift-register
write at `$E559` goes to CIA2 SP2 (user-port pin 7), which is not part of the standard RS-232 wiring
and whose purpose is not established.  Both tables are outside the frozen region and can be reused.

### The Commodore-key hot keys already in use

`readKeyAndHandleModemHotkeys` `$E2EC` is jump-table entry `$E015` and is the game's **only** keyboard
read: `pollKeyboardEvent` starts at `$0E56` with a `JSR $E015`, and the raster IRQ calls it at `$11E7`
once a frame.
It scans through the hook at `$E012`, whose operand the game patches to `scanKeyboard` `$0DB7` at
`$0F4B/$0F50`.

Key codes are the game's own: from `keyMatrixCodeTable` `$0D67`, an ordinary key returns its ASCII
code with bit 7 set (`'A'` = `$C1`, `'3'` = `$B3`), the four function keys return `$00-$03`, control
keys return their ASCII control code with bit 7 set (RETURN = `$8D`), and `$FF` means no key.  X
returns `$80` when the Commodore key is held.

Gates before any hot key is considered:

* `$E310` `BPL` - codes below `$80` (the function keys) are handed straight to the game and can never
  be hot keys.
* `$E312-$E319` - a code equal to `lastHotkeyCode` `$E046` with the Commodore key still down is
  swallowed, which is the auto-repeat filter.
* `$E31F` - the Commodore key must be held (X = `$80`).

The complete list, in the order the code tests them:

| Code | Key | Address | Action |
|---|---|---|---|
| `$C8` | C= + H | `$E323` | `EOR` `dtrToggleMask` `$E04C` = `$24` into `CIA2_PRB`: toggle PB2 (DTR) and PB5 |
| `$C3` | C= + C | `$E332` | `EOR` `$E04B` = `$40` into `carrierOverrideFlags` `$E04A`: pretend carrier is present |
| `$B3` | C= + 3 | `$E342` | `baudIndex` `$E055` = 0, then `loadBaudParameters` with X=0: 300 baud |
| `$B1` | C= + 1 | `$E34A` | `baudIndex` `$E055` = 3, then `loadBaudParameters` with X=3: 1200 baud |
| `$8D` | C= + RETURN | `$E362` | `DEC skipModemInitString` `$E041` (0 -> `$FF`), `openCommLink` `$E2C1`, `modemReplyTimer` `$E03F` = `$8D`; returns the RETURN code to the game with X cleared, so this key is **not** swallowed |
| `$D0` | C= + P | `$E374` | `hangUpModem` `$E38D` (drop DTR, queue `+++`/`ATH0`); its tail returns `$FF` |
| `$C1` | C= + A | `$E37A` | `isOriginateMode` `$E011` = 0, then `configureUserPortLines` `$E540` |
| `$CF` | C= + O | `$E37E` | `isOriginateMode` `$E011` = 1, then `configureUserPortLines` `$E540` |

Every one of them except C= + RETURN returns `A = $FF` so the game never sees the keystroke.  So does
**every other** Commodore-key combination: the fall-through at `$E38A` returns `$FF` unconditionally.
Adding new hot keys therefore cannot break anything the game currently does with the keyboard - those
codes are already being eaten - as long as the eight codes above keep their meanings.

Free and sensible for new baud keys: C= + 2 (`$B2`), C= + 4 (`$B4`), C= + 9 (`$B9`), C= + 0 (`$B0`),
C= + 6 (`$B6`), C= + 8 (`$B8`).  Note that C= + 3 and C= + 1 are already spent on 300 and 1200, so a
"digit = speed" scheme has to work around them; mapping C= + 2 -> 2400, C= + 4 -> 4800, C= + 9 ->
9600, C= + 0 -> 19200 and C= + 8 -> 38400 collides with nothing.  Avoid `$FE` and `$FF` (the modifier
and no-key sentinels) and remember that `$B3`/`$B1` must keep working if the module is to stay usable
with a real 300/1200 modem.

### The SwiftLink baud table, and verification of the doubling claim

**Conclusion: the doubling claim is correct, and the specific values in the task brief are correct.**
Verified against two independent sources beyond the brief:

1. CMD, *SwiftLink-232 Application Notes v1.1*, section 3.4 and the control-register figure
   (<http://csbruce.com/cbm/ftp/reference/swiftlink.txt>).  "Note that our cartridge uses a
   double-speed crystal, so values given on the data sheet are doubled ... (the minimum speed is 100
   bps and the maximum speed is 38,400 bps)", followed by the full table below.
2. The cc65 SwiftLink driver `libsrc/c64/ser/c64-swlink.s`
   (<https://github.com/cc65/cc65/blob/master/libsrc/c64/ser/c64-swlink.s>), whose `BaudTable` maps
   300 -> `$05`, 600 -> `$06`, 1200 -> `$07`, 2400 -> `$08`, 3600 -> `$09`, 4800 -> `$0A`,
   7200 -> `$0B`, 9600 -> `$0C`, 19200 -> `$0E`, 38400 -> `$0F`, and marks 50/75/110/134.5/1800 as
   unavailable - exactly what a doubled table predicts (1800 is unreachable because the nominal 1800
   entry now yields 3600).

Control register (`base+3`) = `$10` (bit 4 = internal baud-rate generator, bits 6-5 = `00` = 8 data
bits, bit 7 = 0 = one stop bit) OR the rate bits:

| Bits 3-0 | Control byte | SwiftLink rate | Nominal 6551 rate |
|---|---|---|---|
| `$00` | `$10` | 16x external clock | 16x external clock |
| `$01` | `$11` | 100 | 50 |
| `$02` | `$12` | 150 | 75 |
| `$03` | `$13` | 219.84 | 109.92 |
| `$04` | `$14` | 269.16 | 134.58 |
| `$05` | `$15` | **300** | 150 |
| `$06` | `$16` | 600 | 300 |
| `$07` | `$17` | **1200** | 600 |
| `$08` | `$18` | **2400** | 1200 |
| `$09` | `$19` | 3600 | 1800 |
| `$0A` | `$1A` | **4800** | 2400 |
| `$0B` | `$1B` | 7200 | 3600 |
| `$0C` | `$1C` | **9600** | 4800 |
| `$0D` | `$1D` | 14400 | 7200 |
| `$0E` | `$1E` | **19200** | 9600 |
| `$0F` | `$1F` | **38400** | 19200 |

To stay wire compatible with the stock driver, the SwiftLink build must be able to produce 300
(`$15`) and 1200 (`$17`).  Those are the only two speeds the stock module can talk at, so a stock
machine and a SwiftLink machine can only meet there.

Bear in mind that the game's *throughput* ceiling is not the line speed.  The frame layer starts at
most one thing per raster IRQ (`$E860` refuses when `uartPendingCount` >= 2) and the packet layer
exchanges one packet per lock-step turn, so past a few thousand baud the win is latency and
retransmit cost, not bandwidth.


## 5. `$E030` - the build id

`commBuildId` `$E030` is one byte inside the frozen block `$E01D-$E047`.

| Module | Value | Source |
|---|---|---|
| `game/modemDriverE000` (track 18 s7 + track 34) | `$00` | `modemDriverE000.s` `$E030`, and byte `$030` of the rebuilt 4096-byte image |
| `game/trainerAiE000` (track 35) | `$FF` | `trainerAiE000.s` `$E030` |

Only bit 7 is ever tested.  Nothing in the module writes it; it is a constant baked into the sector
image, and it survives every `clearInlineVarBlock` because none of the cleared blocks covers `$E030`
(`clearPacketVars` stops at `$E02F`, `clearLinkVars` starts at `$E039`).

The five read sites in `mainProgram0800.s`:

| Address | Routine | What the game does |
|---|---|---|
| `$0AEA` | `startGameFromSetup` | `EOR isSoloTrainer` (`$0BA5`), `AND #$80`: if bit 7 of the wanted opponent and the resident module disagree, `$0AF1/$0AF4` load the other module off disk |
| `$0B2C` | `startGameFromSetup` | `LDA $E030` / `STA $0BA5`: the resident module's id is written **back over** the wanted flag, so `$0BA5` afterwards always describes what is actually in memory |
| `$1A9F` | `miscTabAction` (ABORT GAME) | negative: skip the `$8C`/reason-0 "I am leaving" handshake, because the trainer discards everything sent to it |
| `$1AFA` | `endGameToMainMenu` | negative: force `isLinkActive` `$E03B` to 0 and preselect main-menu item 1 (PRACTICE WITH SOLO TRAINER) instead of item 0 |
| `$1B3D` | `hangUpModemSetState` | negative: skip the "PICK UP PHONE THEN PRESS SPACE." prompt (message `$17`) and the carrier-quiet wait at `$1B4B`, and go straight to `$E003` X=3 |

**The SwiftLink module must keep `$E030 = $00`.**  It is the modem build; a `$FF` there would make the
game believe the solo trainer is resident, which would (a) make `$0AEA` reload track 34 over the top
of the SwiftLink module every time a modem game starts, (b) suppress the hang-up handshake and the
end-of-game link teardown, and (c) rewrite `$0BA5` to `$FF`, turning the game into a solo game.
`checkAbi.py` enforces this as part of the `$E01D-$E047` frozen region, but it is worth stating
explicitly because it is the one byte in that region that carries meaning rather than state.

Two related bytes in the same frozen block, for completeness:

* `$E02F` `peerCommBuildId` - the *opponent's* `$E030`, stored by `exchangePlayerNamesAndSettings`
  at `$EDAD` during the start-of-session handshake.  Both ends of a modem game therefore report `$00`
  to each other; a SwiftLink machine and a stock machine will exchange identical ids, which is what
  we want since the wire protocol is unchanged.
* `$E045-$E047` hold `$44 $54 $48` ("DTH") on disk - leftovers from the sector image, because this
  page comes from track 18 sector 7, outside the encrypted area.  They are inside the frozen region,
  so the SwiftLink image must reproduce those exact junk bytes even though `clearLinkVars` `$E034`
  zeroes them the moment the link is closed.


## 6. Checklist for the replacement UART layer

Contracts, in the order they will bite:

1. `$E030` stays `$00`; `$E01D-$E047` and `$E000-$E017` come out byte-identical, junk bytes included.
2. `$E039`/`$E03A` suspend handshake served once per frame from the `$E00C` path, with `$80`/`$00`
   bit-7 semantics; ACIA interrupts genuinely off between them; CIA2 never touched.
3. `$E031/$E032` still chained on a foreign NMI.
4. `$E03D` publishes `$80`/`$F8`-shaped samples (bit 6 = carrier, bit 7 = data flowing within ~128
   frames), driven from ACIA status bit 6 with **carrier = bit clear**; `$E045` zeroed from the
   receive path; the 240-frame debounce at `$E3CB` left exactly as it is.
5. `$E03B` set by `openCommLink`, not by carrier.
6. `$E0A5` `uartPendingCount` accurate at all times; `$E044` writable by `$E820`.
7. `queueByteForTransmit` `$E73C`, `flushUartTxRing` `$E534`, `configureUserPortLines` `$E540`,
   `dropDtrLine` `$E574`, `installCommNmiVector` `$E57B`, `restartUart` `$E586`, `stopCommNmi`
   `$E5C3` and `serviceCarrierAndSuspendRequest` `$E5D6` keep their addresses.
8. `$E048` bit 7 clear for a cable-only build (no AT strings, no result-code sniffing, phase 1 never
   entered); leave the option so a real modem can still be driven.
9. `loadBaudParameters` `$E353` keeps its three-byte stride and its `A = $FF` return, or all four of
   its call sites (`$E2C9`, `$E350` fall-through, `$E7B2`) change together.
10. New hot keys only in the free codes; `$C8 $C3 $B3 $B1 $8D $D0 $C1 $CF` keep their present
    meanings, and C= + RETURN keeps returning the key to the game rather than swallowing it.


## 7. Open questions

* **Which SwiftLink clones swap DCD and DSR?**  CMD's own cartridge does (section 2), and the
  Turbo232 is documented as SwiftLink compatible, but the modern reimplementations (GLINK232 and
  friends) advertise "modem control" as an option and do not all say which way round they wire it.
  A build that only ever sees a null-modem cable does not care, because both bits read active; a
  build that wants real DCD should probably offer a bit in `$E04A` to select which status bit to
  look at, since `$E04A` is already used as a polarity/override mask by `$E5F1`.
* **Base address.**  `$DE00` is the default, `$DF00` the strap option; CMD's own notes recommend that
  software cope with both (probe by writing the control register and reading it back).  A run-time
  probe costs a few bytes and removes a support headache, and there is plenty of room in the freed
  UART region.
* **Status-register bit 7 at high speed.**  CMD warns that bit 7 (interrupt occurred) is unreliable
  at 9600 bps and above, and their own sample NMI handler ignores it and tests RDRF/TDRE/DCD/DSR
  directly.  Worth following.
* **CTS.**  The 6551 stops transmitting on its own when CTS goes inactive, and clears TDRE while it
  does, with no way to see CTS from any register.  On a null-modem cable with RTS/CTS crossed, that
  gives a free flow-control mechanism during disk loads: raising RTS on the suspending machine (both
  transmit-control bits clear) throttles the peer's transmitter automatically.  Whether that is worth
  using, or whether it is better to let the ARQ layer clean up as it does today, is a design decision
  the driver work will have to make.