C64-dev/newLang/docs/memory-map.md

Nova128 Compiler Memory Map

Story: E01-S05
Status: frozen for the compiler (D117); verified in VICE x128 3.10
Authoritative source: cfg/compiler.cfg. This document explains it.

The generated-program memory map is not frozen here. It belongs to E04-S01 and E04-S02, which must reuse the test mailbox below.

Mappings

State	CR	RCR (low bits)	P0	P1	IRQs
System	as BASIC left it ($00)	as BASIC left it	$0000	$0001	caller's
Compiler bank 0	$0E	%0110 8K bottom common	bank 0 page $1A	$0001	masked
Compiler bank 1	$4E	%0110 8K bottom common	bank 0 page $1A	$0001	masked

RCR bits 6–7 (VIC bank) are always carried over from the system value. src/compiler/mmu.s is the only module that writes MMU registers.

Bank 0

Range	Size	Name	Contents
$0000-$12FF		system	BASIC 7, KERNAL, editor, screen. Off limits except NMINV ($0318), which the compiler saves and restores
$1300-$18FF	1536	COMMON	Copied from the PRG by mmu_init: MMU switches, KERNAL wrapper, NMI guard, and any code that runs while bank 1 is mapped
$1900-$19FF	256	DISKBUF	Disk transfer buffer, visible from both banks
$1A00-$1AFF	256	private ZP	Physical page behind logical zero page in compiler states. Not a linker area: nothing else may live here
$1B00-$1BEF	240	SCRATCH	Shared state needed from both banks
$1BF0-$1BFF	16	MAILBOX	Fixed test mailbox (below)
$1C01-$1C0C	12	header	BASIC 7 stub 10 SYS 7181
$1C0D-$B7FF	39923	MAIN	STARTUP (always first, entry at $1C0D), CODE, RODATA, DATA, COMMON load image, BSS
$B800-$BFFF	2048	SWSTACK	Compiler software stack
$C000-$FFFF		system ROM	KERNAL/editor in both compiler states

$1300-$1BFF is the C128's free application area: after boot x128 shows only the power-on fill pattern there. All of $0000-$1FFF is bottom common RAM, so COMMON, DISKBUF, private ZP, SCRATCH, and MAILBOX are visible from bank 1.

Bank 1

Range	Size	Name	Contents
$0000-$1FFF		hidden	Covered by bottom common RAM in compiler states
$2000-$BFFF	40960	BANK1 / TABLES	Names, symbols, class/interface/type records, pass workspaces
$C000-$FFFF		unmapped	System ROM is visible here instead; BASIC string space at the top of bank 1 is untouched

Bank-1 data is reached only through mmu.s helpers (mmu_peek1/mmu_poke1 with the zero-page pointer mmu_ptr, and later block-copy routines), or by code in COMMON. MAIN code never runs while bank 1 is mapped, because MAIN above $1FFF is not visible then.

BASIC 7 keeps variables in bank 1 from $0400. The compiler is started with RUN, which clears variables, so overwriting $2000-$BFFF loses no BASIC state.

Zero Page

In compiler states P0 points at bank 0 page $1A, so the compiler owns the whole logical zero page $02-$FF (linker area ZP, 254 bytes). $00/$01 are the 8502 port and are never allocated. Modules allocate zero page only through the ZEROPAGE segment. Current users: mmu_ptr (2 bytes).

System zero page stays intact. KERNAL calls switch P0 back to $0000 for the call. While P0 is relocated, the system zero page is still readable at $1A00-$1AFF (the MMU swaps the two pages), e.g. ST at $1A90.

Interrupts

• IRQ: masked in both compiler states. The ROM IRQ path ($FF17) jumps via $0314 into BASIC's handler, which uses system zero page and would corrupt the private page. kcall enables IRQs only for the duration of a KERNAL call, in system state.
• NMI: cannot be masked. The ROM entry $FF05 uses no zero page: it pushes A/X/Y/CR, sets CR=0, and jumps via $0318. mmu_init points $0318 at mmu_nmi_guard (in COMMON), which reads the CIA #2 ICR, counts the event, and exits through $FF33 (pull CR/Y/X/A, RTI). RESTORE is therefore ignored while the compiler runs. mmu_shutdown restores $0318.

Test Mailbox

Defined in src/common/mailbox.inc. Used by platform tests, the compiler, and generated programs, and read by the harness after the program returns.

Address	Field	Meaning
$1BF0	magic 0	$4E (N) once initialized
$1BF1	magic 1	$38 (8)
$1BF2	producer	$01 platform test, $02 compiler, $03 generated program
$1BF3	status	$01 running, $A5 pass, $FA fail
$1BF4-$1BF5	code	Little-endian diagnostic, fault, or failed-check code; 0 on pass
$1BF6-$1BF7	address	Little-endian fault or completion address
$1BF8-$1BFF	data	Eight producer-defined bytes

Protocol:

1. The producer clears all 16 bytes, writes the magic and producer, then sets status $01 before doing any work.
2. It writes code, address, and data, then writes the final status last.
3. The harness polls until the magic matches and status is $A5 or $FA. A status still $01 at the timeout means the producer hung or crashed. A missing magic means it never started.

Evidence

scripts/verify-map-skeleton.ps1 links src/compiler/mmu.s with tests/platform/map-skeleton.s using cfg/compiler.cfg, then:

1. Builds five variants that overflow ZP, COMMON, MAIN, SWSTACK, and TABLES by one region's worth. ld65 rejects each in the expected memory area.
2. Checks fixed placements: STARTUP and skel_entry at $1C0D, MAILBOX at $1BF0, COMMON within $1300-$18FF, TABLES within $2000-$BFFF.
3. Runs the skeleton in x128 and reads the mailbox: 4E 38 01 A5 00 00 … 01 4E 1A C5. All six checks pass:

Check	What it proves
ZP	A store to logical ZP lands at $1Axx; system ZP is unchanged
KCALL	CHROUT via kcall_inline from both states; private ZP and CR/P0 intact afterwards
BANK1	First and last TABLES bytes hold bank-1 values; bank 0 at the same addresses unchanged
COMMON	DISKBUF/SCRATCH written in bank 0 read back in bank 1; mailbox written from bank 1
NMI	A CIA #2 timer NMI taken in the bank-1 state returns with CR $4E, P0 $1A, sentinel $C5, and the same SP
RESTORE	After mmu_shutdown: CR/RCR/P0/P1/$0318 and SP equal their entry values

Negative control: forcing P0L to $00 in mmu_bank0/1 makes the skeleton report FAIL with code $000F (ZP, KCALL, BANK1, NMI).