modemwars/swiftlink/hotkeyReport.md

The Commodore-key hot keys, exercised in VICE

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.

testReport.md left one hole in the driver's hot-key layer:

The C= + C carrier override could not be exercised. forceCarrier() sent ctrl+c four times to each machine and carrierOverrideFlags ($E04A) read back 0 every time, so I cannot say that hot key works.

That is closed here. Everything below was observed on 2026-08-21 with VICE 3.7.1 (x64sc, NTSC), one machine, ../Modem_Wars_SwiftLink.d64, driven by swiftlink/testHotkeys.py. Nothing is inferred from the source unless it says so. The full session log is swiftlink/testLogs/hotkeyRun.txt.

Summary of what is now verified: the Commodore key under VICE's default C64 keymap is Tab; C= + C toggles carrierOverrideFlags $E04A bit 6 on and off; with the override on the carrier sampler reports carrier without ever reading DCD, and it does so even when the DCD input says "no carrier", where with the override off the same input produces "no carrier"; and C= + 2 followed by C= + 3 reprogram the ACIA control register $DE03 to $18 (2400 baud) and back to $15 (300).

---

1. How you press the Commodore key under VICE - determined by experiment

The game does not use the KERNAL. scanKeyboard $0DB7 reads the CIA1 matrix itself, once per raster IRQ, and it reports the Commodore key only when matrix row 7, column 5 is pulled low. So the whole question is which X keysym VICE's active keymap puts at 7/5, and the only way to be sure is to press candidates and watch a byte the module writes.

testHotkeys.py holds each candidate together with C and reads two bytes while the keys are still down: carrierOverrideFlags $E04A, which only the C= + C hot key touches, and lastHotkeyCode $E046, which the module writes on every new key code it sees. Every key is pressed with xdotool keydown, held for 900 ms - about 54 of the game's once-a-frame scans at true C64 speed - and then released, because a tap is not reliably visible to a once-a-frame scanner.

host key held with C	$E04A before -> after	$E046 while held	verdict
Control_L	$00 -> $00	$FF	nothing reaches the module at all
Tab	$00 -> $40	$C3	C= + C fired: this is the Commodore key
Super_L	$40 -> $40	$C3	the letter arrives as a plain key; no hot key

(Super_L starts from $40 because the Tab row above had just turned the override on; what matters in its row is that the value does not change.)

That is reproducible: the same three lines came out of three separate boots.

Why the earlier ctrl+c attempt could never have worked, and it is not just the tap:

• The monitor reports KeymapIndex=0 with KeymapSymFile="gtk3_sym.vkm" - index 0 is the symbolic map, so gtk3_sym.vkm is the live one.
• In that file, Tab 7 5 8200 (8192 = "key is (left) cbm on emulated machine") and Control_L 7 2 16392 (16384 = "key is (left) ctrl"). Left Control is the C64 CTRL key, not the Commodore key. Only the positional map gtk3_pos.vkm puts C= on Control_L (Control_L 7 5 8200), and it puts CTRL on Tab.
• Row 7 column 2 - CTRL - is $FF in the game's own keyMatrixCodeTable $0D67, and scanKeyboard answers $FF = "no key at all" the moment it finds that cell ($0E37 bne L_0E3E). So holding left Control does not merely fail to be C=, it blinds the whole scan. That is exactly what the $E046 = $FF column above shows.

The Super_L row is the control case worth having: Super_L appears in neither gtk3_sym.vkm nor gtk3_pos.vkm, so VICE ignores it, the C arrives on its own, lastHotkeyCode becomes $C3 - and $E04A does not change, because $E31F cpx #$80 fails. "The key got in" and "the hot key fired" are therefore two different observations, and the sweep separates them.

Two further keys were tried in an earlier boot and are recorded for the next person:

• Alt_L - $E046 stayed $FF, and worse, every key sent after it was swallowed: holding Alt opens the GTK menu bar, which takes a keyboard grab. The rest of that run was junk. Do not put Alt in a candidate sweep; testHotkeys.py no longer does.
• Control_R - no effect, $E046 = $FF, but this was measured after Alt_L had already wedged that run, so it proves nothing.

That boot's log is testLogs/hotkeyKeymapSweep.txt; its Control_L, Tab and Super_L rows match the table above exactly.

2. C= + C toggles the override on, and off again

Taken at the "GET OPPONENT ON PHONE AND PRESS A OR O" prompt, where the module is resident ($E012 reads JMP $0DB7, the game's scanKeyboard) and the raster IRQ is already calling $E015 every frame:

when	$E04A
before	$00
after one C= + C	$40
after a second C= + C	$00

$40 is carrierOverrideToggleMask $E04B, i.e. bit 6, and the second press clears it again, which is what $E339 eor carrierOverrideFlags is supposed to do. The auto-repeat filter at $E312 does not get in the way as long as the key is released between presses: with nothing held, scanKeyboard returns $FF, and lastHotkeyCode $E046 is reloaded with $FF, so the next $C3 is a fresh code.

Note that the hot key works before the link is open (isLinkActive $E03B = $00 in all three rows above). The override flag is set; it simply has nothing to act on yet, because the carrier sampler returns early at $E5E7 while the link is down.

3. What the override does to the link state the game reads

The link was then opened for real - A at the answer/originate prompt, then space - and came up on the first attempt: aciaCommandShadow $E5BE = $05, $E03B isLinkActive = $01, control register $DE03 = $15 (8N1, internal clock, 300 baud), connectionPhase $E040 = $02. The far end of the serial line is a TCP sink that accepts the connection and never answers, so the link stays in byte sync; 10697 bytes came out of the emulated 6551 during the run, beginning 0d 41 54 51 30 56 31 58 31 41 0d = CR ATQ0V1X1A CR, the answer-mode Hayes string, followed by the $00 stream of beginByteSyncPhase.

Two things about the game screen while all of this was going on, so the pictures are not misleading: with a peer that never answers, the game puts up "PHONE TROUBLE." (shots/hotkeys03linkOpen.png) and later "PICK UP PHONE THEN PRESS SPACE." (shots/hotkeys05borderHeld.png), while the module itself stays in connectionPhase $02 with isLinkActive = $01 throughout. The hot keys keep working in both of those states - inputLockoutTimer $0B7D read $00 at every measurement, so the raster IRQ was polling the keyboard through $E015 the whole time.

With that running, C= + C on and off again:

state	$E03B isLinkActive	$E03C linkStatus	$E03D linkStatusSample	$E5BC aciaStatusSave
override off	$01	$78	$78	$90
override on (read immediately)	$01	$40	$40	$90
override on, six seconds later	$01	$40	$40	$90
override off again	$01	$78	$78	$90
override off, six seconds later	$01	$78	$78	$90

Those two values are the driver's own fingerprints, from $E5F8-$E602:

• $78 = a real carrier sample. #$F0 -> SEC -> ROR = $F8, minus bit 7 because the line has been quiet (no character has arrived recently, so rearmCarrierTimer $E5FF strips it).
• $40 = an override sample. The override branch enters the same SEC / ROR with $80, so it produces $C0, minus the same bit 7 = $40.

So the override is not merely "carrier present" - it is visibly a different route to it, and the round trip back to $78 shows the second keypress really cleared the flag. $E03B is not carrier-derived and stays $01 throughout, exactly as spec_link.md says.

4. The case a null-modem cable with no DCD wire depends on

VICE cannot produce "no carrier" on its own. On a SwiftLink the modem's DCD arrives on 6551 status bit 6 (CMD swapped DCD and DSR at the chip), and that is the bit the carrier sampler serviceCarrierAndSuspendRequest $E5D6 tests with BIT aciaStatusSave. Every status byte VICE's emulated 6551 produced in this project - $30 with the device closed, $10, $50, $88, $90, $98 while it is open - has bit 6 clear. VICE drives bit 5, the 6551's own DCD bit, and that only tracks whether the rs232 device is open. So in VICE the driver always sees carrier, and the override can never be the difference between a link and no link by itself.

It can be made the difference where the driver actually reads DCD: aciaStatusSave $E5BC, the shadow the NMI keeps and the only DCD the carrier sampler ever sees. The test breaks at $E5E9 - the LDA carrierOverrideFlags one instruction before the DCD test - pokes $E5BC to $40 (bit 6 set = DCD deasserted = no carrier), and single steps the sampler. Both passes below used exactly that same forced input, and $E5BC was read back as $40 after each one, so nothing refreshed it in between.

Override on ($E04A = $40) - the DCD test is never executed:

.C:e5e9  AD 4A E0  LDA $E04A   A:01
.C:e5ec  0A        ASL A       A:40      <- carrierOverrideFlags = $40 ...
.C:e5ed  30 09     BMI $E5F8   A:80      <- ... so bit 6 is now bit 7: branch taken,
.C:e5f8  38        SEC         A:80         $E5F1 BIT aciaStatusSave is skipped entirely
.C:e5f9  6A        ROR A       A:80
.C:e5fa  EE 45 E0  INC $E045   A:C0      <- sample = $C0: carrier, by override
.C:e5fd  10 05     BPL $E604   A:C0      <- quiet line, so bit 7 comes off
.C:e5ff  8D 45 E0  STA $E045   A:C0
.C:e602  29 7F     AND #$7F    A:C0
.C:e604  8D 3D E0  STA $E03D   A:40      <- published: bit 6 set = carrier present
.C:e607  AD BB E5  LDA $E5BB   A:40      <- on into startNextTxChar, and back out
.C:e60a  D0 56     BNE $E662   A:01
.C:e662  60        RTS         A:01
.C:e3ce  AD 3D E0  LDA $E03D   A:01
.C:e3d1  CD 3C E0  CMP $E03C   A:40
.C:e3d4  F0 0D     BEQ $E3E3   A:40      <- agrees with linkStatus, debounce reset

readback: $E03D = $40, $E03C = $40, $E5BC = $40.

Override off ($E04A = $00), same forced $E5BC = $40:

.C:e5ec  0A        ASL A       A:00
.C:e5ed  30 09     BMI $E5F8   A:00      <- not taken
.C:e5ef  A9 F0     LDA #$F0    A:00
.C:e5f1  2C BC E5  BIT $E5BC   A:F0      <- V := bit 6 of $40 = 1
.C:e5f4  50 02     BVC $E5F8   A:F0      <- not taken: DCD says no carrier
.C:e5f6  A9 00     LDA #$00    A:F0
.C:e5f8  38        SEC         A:00
.C:e5f9  6A        ROR A       A:00
.C:e5fa  EE 45 E0  INC $E045   A:80      <- sample = $80: no carrier
.C:e5fd  10 05     BPL $E604   A:80
.C:e5ff  8D 45 E0  STA $E045   A:80
.C:e602  29 7F     AND #$7F    A:80
.C:e604  8D 3D E0  STA $E03D   A:00      <- published: bit 6 clear = no carrier

readback: $E03D = $00, $E03C = $78 (unchanged - pollCarrierState needs 240 disagreeing frames before it accepts a new value), $E5BC = $40.

That is the whole point of the hot key, in two traces. Identical DCD input; with the override off the driver publishes "no carrier" and the game would tear the session down four seconds later (pollMenuSession $56B1 watches $E03C bit 6); with the override on it publishes "carrier" and never looks at the line at all. A three-wire null-modem cable, where DCD is not wired and the cartridge's pull-up already reads as carrier, does not need this - but a cable that does carry a real DCD from a peer that is not asserting it now demonstrably does.

5. A baud hot key really reprograms the ACIA

Same session, link up, at true C64 speed:

after	$E055 baudIndex	$E056 liveControlByte	$DE03 ACIA control
(before)	$00	$15	$15
C= + 2	$06	$18	$18
C= + 3	$00	$15	$15

$18 is entry 6 of baudEntryTable $E6FD - 2400 baud on a SwiftLink's doubled clock - and it is a value no earlier test in this project had ever written; testReport.md recorded only $1E (the probe pattern) and $15. C= + 3 puts it back to 300. Both the index and the register move together, so the backwards walk of baudEntryTable at $E344 and loadBaudParameters $E353 are both doing what section 3 of the README claims.

6. The border indicator, which is the C= key's other job

readKeyAndHandleModemHotkeys also paints VIC_BORDER from linkStatusBorderTable $E05F while the Commodore key is held, indexed by connectionPhase*2 + carrier. With the link up in connectionPhase $02 and linkStatus $78 (carrier) the index is 5, whose table byte is $04 = red, with the low bit clear so it is painted only while C= is held.

A checkpoint on the module's own STA VIC_BORDER at $E30C, armed first and Tab pressed afterwards:

#1 (Stop on  exec e30c)
.C:e30c  8D 20 D0    STA $D020      - A:02 X:80 Y:00 SP:de N.-.....

A = $02 is red - $04 from the table, halved by the LSR at $E305 - and X = $80 is scanKeyboard's "the Commodore key is held" flag, which is what took the BMI at $E308. So the paint really happens; the code that does it runs from the raster IRQ, so it repeats every frame for as long as the key is down.

Reading $D020 is not how to see it: it was $FC, the game's own border colour, both at that breakpoint (where the store had not executed yet) and again after the key was released, so the game rewrites the border later in the same frame and a monitor peek at an arbitrary moment nearly always catches the game's value. What the effect looks like on screen with the key held was not captured - the screenshot in shots/ was taken after the key came up.

7. Three things about the rig that the next person needs

1. VICE 3.7.1 has no WarpMode resource but its monitor does have a warp command. testReport.md only tried resourceset "WarpMode"/"Warp"/"WarpModeEnabled", all rejected, and concluded every run stays in warp. warp on, warp off and warp (query, answers "Warp mode is on./off.") all work. It matters more than it sounds, because -warp on the command line does not survive the autostart: the first run of this test, launched exactly like every run in testReport.md, sat for over eleven minutes at "loading under warp" and never reached the menu, while the same script with an explicit warp on issued before the $0800 breakpoint reached the options menu in about 50 seconds, twice in a row. VICE's own log says AUTOSTART: aborting. a second or two in - this disk's fast loader leaves the KERNAL routines VICE is watching - and -autostart-warp turning warp off at that point is the obvious explanation, though that part is inference, not measurement. That is very probably the "90 seconds to over five and a half minutes" variation testReport.md recorded. testHotkeys.py now warps the loader explicitly and issues warp off afterwards, so every key in this report was pressed against a machine running at true C64 speed. (Between the two traces in section 4 the emulated cycle counter advanced 73.8 M cycles = 72 s of NTSC C64 time, over a stretch of wall clock of the same order - not the hundreds of seconds warp would have produced.)
2. Do not stop the emulator while a key is held. A key pressed with xdotool keydown and then left down across a monitor stop does not survive the stop. This was the difference between two otherwise identical runs: with Tab pressed first and the $E30C checkpoint armed during the resulting monitor stop, the checkpoint never fired; with the checkpoint armed first and Tab pressed after the machine was running again, it fired immediately (section 6). Anything that needs a key to be down while the CPU runs must arm its breakpoints first and press afterwards. Reads taken during a stop are still fine - they show what the held key already did.
3. Alt_L wedges the run. Holding Alt opens the GTK menu bar and takes a keyboard grab; every xdotool key after that goes to the menu and the emulator sees nothing. testHotkeys.py verifies key delivery before and after the sweep ([keys] plain C: lastHotkeyCode = $C3) so this failure mode announces itself instead of silently producing zeros.

8. What this does not say

• Still nothing on real hardware. This is VICE 3.7.1 with -acia1mode 1 -acia1base 0xDE00 -acia1irq 1.
• The "no carrier" DCD was injected, not emulated. VICE never raises 6551 status bit 6, so the value was written into aciaStatusSave $E5BC at a breakpoint. That is the exact byte the carrier sampler reads and the exact bit the source documents, but a real SwiftLink with a real peer dropping DCD has not been observed.
• Only one machine. The peer was a TCP sink that never answers, so the link stayed in connectionPhase $02; the override was not tested with two machines actually playing.
• Only C= + C, C= + 2, C= + 3 and C= on its own were pressed. C= + H (DTR), C= + P (hang up), C= + A / C= + O, C= + RETURN and the other four baud keys are still untested.
• The disk-load suspend handshake, W65C51N boards and the $DF00 fallback remain untested, as testReport.md already said.

Files

file	what it is
testHotkeys.py	the test: keymap sweep, override toggle, border checkpoint, forced-DCD traces, baud hot keys
testLogs/hotkeyRun.txt	the session this report cites, monitor traffic included
testLogs/hotkeyKeymapSweep.txt	the earlier boot whose sweep also tried Alt_L and Control_R
shots/hotkeys01menu.png	the title screen, five seconds after the loader finished
shots/hotkeys02modemPrompt.png	"GET OPPONENT ON PHONE AND..." - where the keymap sweep was done
shots/hotkeys03linkOpen.png	after A and space, with the link open and the module in phase 2: the game says "PHONE TROUBLE."
shots/hotkeys04overrideOn.png	the same screen with the carrier override on
shots/hotkeys05borderHeld.png	the screen the border checkpoint was taken on (the key is already released, so the border is the game's own colour)