C64-dev/newLang/docs/platform-display-clock.md

C128 Display and Clock Probe

Story: E01-S04
Status: observed in VICE x128 3.10; not a final compiler memory map

Primary Platform Facts

The Commodore 128 Programmer's Reference Guide documents:

• $00D7 (MODE) bit 7: $00 selects the active 40-column editor and $80 selects the active 80-column editor.
• $FF5F (SWAPPER): switches the C128 editor's 40/80-column local state.
• $D030 bit 0: set selects 2 MHz and disables VIC video; clear selects 1 MHz and permits VIC video.
• $D030 bit 1 is a chip-test facility and must remain clear.
• I/O accesses in 2 MHz mode are stretched to remain synchronized with 1 MHz I/O devices.

Sources:

• Commodore 128 Programmer's Reference Guide, SWAPPER, page 449.
• Same guide, 8564 VIC “2 MHz Operation” and “System Clock Control,” pages 589–590: https://www.pagetable.com/docs/Commodore%20128%20Programmer%27s%20Reference%20Guide.pdf
• Installed VICE 3.10 manual, C128 options -40col and -80col.

Probe Policy

src/platform/display-clock.s follows the policy approved by D112:

1. Respect the editor/display already selected by the user.
2. Send all text through KERNAL CHROUT ($FFD2).
3. Force the conservative 1 MHz baseline before inspecting the display.
4. In 40-column mode, stay at 1 MHz so VIC output remains visible.
5. In 80-column mode, set $D030 bit 0, perform KERNAL output at 2 MHz, and then restore 1 MHz before returning to BASIC.
6. If display mode or fast-mode activation is uncertain, use 1 MHz. This is the deterministic fallback for the compiler.

The probe does not call SWAPPER because the compiler must not override the user's selected display. SWAPPER remains the documented mechanism if a future, separately approved feature explicitly changes displays.

Observed Results

The verification script boots x128 independently with -40col and -80col.

Mode	MODE captured	Result	Fast observed	Final $D030 bit 0	Trace
40-column	$00	$44	$00	$00	$1C2E then $1C8C; never $1C49
80-column	$80	$85	$01	$00	$1C3D, $1C49, then $1C8C

VICE reads $FC from $D030 after fallback because unconnected upper bits read high; the meaningful speed bit 0 and test bit 1 are both clear. The probe's final_clock field stores the masked speed bit and is $00 in both modes.

Result bit meanings are probe-local: bit 7 is the 80-column path, bit 6 is the 40-column path, bit 2 proves ordinary semantic RAM markers survived, and bit 0 proves the 2 MHz control bit read back set.

The 40-column screenshot contains:

NOVA128 40 COL KERNAL OK
1MHZ FALLBACK OK

The 80-column screenshot contains:

NOVA128 80 COL KERNAL OK
2MHZ KERNAL IO OK
RESTORED 1MHZ

VDC RAM Boundary

The probe never reads or writes VDC address/data registers $D600/$D601. Machine-readable state lives in normal CPU RAM at $1D0F–$1D14; the build script rejects executable source references to $D600/$D601. In 80-column mode, only the C128 KERNAL/editor owns display transfer to VDC-local RAM.

This establishes the architectural rule: VDC RAM is display-only and never a home for compiler symbols, semantic tables, stacks, or intermediate data.

Reproduction

From newLang/:

./scripts/build-display-clock.ps1
./scripts/verify-display-clock.ps1

Generated screenshots, remote-monitor trace transcripts, PRG, map, and labels remain under ignored build/.