ULTIMATEEXPERIMENTSCommodore 64 · Work in progress

Memory, paging, and coherence

Development note: see current status, build instructions and installation for present qualification. Historical measurements below apply to their stated slice, not every current build.

These are full-system budgets; current measured subsets are recorded in MEMORY_BUDGET (local development record, not distributed) and MEMORY_IMPLEMENTATION. The 512-byte coherent byte cache and bytewise coherent guest/REU range transfers are implemented and functionally tested; page size and future optimizations remain candidates. All ranges below are inclusive unless a length is explicitly given.

Guest address space

Guest physical range Behavior
00000–9FFFF 640 KiB conventional RAM, including writable IVT/BDA
A0000–B7FFF Uninstalled video/RAM for this CGA profile; deterministic reads, writes ignored/logged as specified
B8000–BBFFF 16 KiB CGA VRAM; text pages and graphics share backing
BC000–EFFFF Reserved/uninstalled space; add aliases or option-ROM data only when the profile requires it
F0000–FFFFF Synthetic BIOS ROM and tables; guest writes do not change ROM

Reserve a full 1 MiB REU backing arena for straightforward physical indexing, but enforce this bus map; do not accidentally make holes writable RAM. CPU-only conformance tests use a separate all-RAM bus mode because their vectors assume 1 MiB writable RAM.

Compute an effective offset with 16-bit arithmetic; then physical = ((segment << 4) + offset) & 0xFFFFF. Segment aliases must reach the same cache entry. Instruction IP, stack SP, and string SI/DI updates wrap as 16-bit registers. Do not conflate those rules with the second byte of every multi-byte memory transfer. Freeze word/far-pointer boundary behavior at offsets FFFF/FFFE from original-CPU vectors/reference code, including odd-address behavior, before enabling a shared read16 fast path. Test physical FFFFF→00000 separately. Avoid importing modern protected-mode segment-limit behavior.

C64 host map: 64 KiB fully accounted for

Host range Bytes Current allocation / remaining budget
0000–01FF 512 6510 port, allocated ZP, hardware stack
0200–07FF 1,536 KERNAL-compatible work areas, bootstrap, host input/buffers
0800–3FFF 14,336 CPU, hot memory routines, native BIOS/control code
4000–43FF 1,024 VIC bitmap color matrix / text screen
4400–47FF 1,024 Packed 4×8 CP437 font source
4800–4FFF 2,048 8×8 CP437 font source / aligned character generator
5000–5FFF 4,096 Resident DEVICECODE, current 4,074 bytes plus 22-byte tail
6000–7FFF 8,192 VIC bitmap reservation (8,000 displayed bytes)
8000–BFFF 16,384 Guest cache frames; includes RAM under BASIC
C000–C0FF 256 Coherent range staging buffer; linker-enforced reservation
C100–C8FF 2,048 Linked UCIBUFFER: command/data/status transport storage
C900–CFFF 1,792 Exclusive FILE/TEXT/INPUT/PIT/GFX/HD/DISK overlay window
D000–DFFF 4,096 I/O visible: VIC, SID, color RAM, CIA, REU/UCI
E000–EFFF 4,096 State, page map, descriptors, dirty maps, bounce buffers
F000–FDFF 3,584 Copied HD/scroll code: 2,144 bytes plus 1,440-byte zero tail
FE00–FFFF 512 Excluded vector/gateway reserve
Total 65,536 Executable windows total 23,808 bytes; C900 is shared, not seven simultaneous allocations

The VIC bank is 4000–7FFF: the matrix at 4000 and bitmap at 6000 are in the same 16 KiB bank. This must be asserted, not inferred from total free bytes. Font alignment and VIC character-ROM visibility must also be checked. Color RAM is at D800 and is already inside the I/O reservation, not another 1 KiB of ordinary RAM.

Host normal mapping exposes RAM under BASIC/KERNAL while leaving I/O visible. KERNAL calls use a resident gateway outside hidden memory; save/restore $00/$01, needed ZP, IRQ state, stack, return registers, and channel state. Guest frames under BASIC and metadata under KERNAL remain protected from accidental CPU access during that mapping. REU staging buffers stay in known visible RAM. Initially avoid DMA into I/O and avoid using RAM under I/O altogether. IRQ/NMI vectors and handlers must remain valid across all maps; test RESTORE/NMI and error exits.

The seven current managed overlay variants have resident wrappers, exclusive ownership and explicit load/release failure paths. Resident CPU/pager and guest interrupt routing remain callable; FILE/HD cannot nest leases. Startup sources and copied code must be committed before the cache reuses31 populated startup frames across the32-frame cache span (frame23 is the explicit zero gap). Record separate CODE/RODATA/BSS boundaries; do not execute embedded constants or overwrite persistent state with an overlay. See HD and copied-code contract.

REU arena: 4 MiB minimum profile

REU range Capacity Use
000000–0FFFFF 1 MiB Guest physical backing arena
100000–17FFFF 512 KiB Full360KiB rotating floppy arena0; descriptor chooses A/B/spare ownership
180000–1FFFFF 512 KiB Full360KiB rotating floppy arena1
200000–2FFFFF 1 MiB Hard-disk extent cache, independent of guest RAM cache
300000–33FFFF 256 KiB Cold assembly payloads / fonts / immutable assets
340000–37FFFF 256 KiB Eight physical immutable slots340000–343FFF (seven managed variants plus special SAVER); authoritative sector350000; handoff352000; remaining transfer reserve
380000–3D9FFF 360 KiB Full rotating floppy arena2, initially free incoming-media staging; replaces optional trace scratch
3DA000–3DFFFF 24 KiB Unallocated gap
3E0000–3EFFFF 64 KiB Reserved installer main-PRG staging bank
3F0000–3FEFFF 60 KiB Unallocated reserve
3FF000–3FFFFF 4 KiB Reserved versioned installer/handoff anchor

User clarification 2026-10-14: assume 4 MiB or larger, including room for overlays. This supersedes the initial 16 MiB minimum proposal. The supplied360KiB disks fit all three arenas. User direction2026-10-16 favors more REU for speed; do not reduce buffering to conserve capacity when it slows execution. Above4MiB allocations must remain explicit and bounded. Larger REUs can expand the HD cache and floppy slots through a capacity-aware allocator; 720 KiB and larger floppy support requires that expanded profile, never truncation. No runtime feature may require memory above the 4 MiB baseline. REU is volatile: arena allocation is not persistence. A 20 MiB hard disk remains file-backed.

Expanded REC DMA counters may wrap within 512 KiB without carrying into the upper bank latch. The implemented low-level routine accepts only a nonzero, single-64-KiB-bank chunk and rejects crossing ranges; implemented range operations split and explicitly reload the bank. This is conservative for differing firmware and keeps page transfers safe. See implemented REU contract and coherent range contract.

Guest page cache

Start with 512-byte pages, 32 frames in 16 KiB, solely as a benchmark candidate. Sweep 256/512/1024/2048 bytes with the same total cache budget. Use physical-page tags and a direct page→frame table where practical: 1 MiB/512 = 2,048 byte entries, with FF meaning absent. A 256-byte global table needs 4,096 entries before descriptors; either use a sparse/two-level table or charge the extra storage against cache/working RAM. Do not compare page sizes while ignoring metadata cost.

Per-frame state: physical tag, valid/dirty, pin/reference count, replacement reference bit, generation. A simple clock replacement policy is the baseline; measure alternatives. CS fetch, current stack, and recent data may receive preference, but do not permanently pin whole segments. Eviction must always be possible. Acquire two-frame word operands in a deterministic order or use a safe scratch copy so a small cache cannot deadlock or invalidate the first byte's pointer.

Fast fetch stores a host pointer, physical tag, valid span, and generation. The span ends at page, instruction-IP, and address-space boundaries. Segment changes, taken control transfers, eviction, and overlapping writes invalidate relevant cached pointers. Avoid a 32-entry linear tag scan for every byte. Measure full translation cost as well as warm register-only dispatch.

Coherence invariants

  1. A physical guest page has at most one authoritative dirty host frame. REU is current only when no newer dirty frame exists.
  2. Every writer, including BIOS disk reads, native text helpers, debugger injection, REP fast paths, and memory initialization, uses the memory API or a range-acquire/commit API with equivalent semantics.
  3. Before a disk write reads a guest range, include its dirty resident bytes. Before a disk read replaces guest bytes, preserve untouched dirty bytes and merge/update or invalidate the destination frames. Flushing after overwriting REU can restore stale data and is forbidden.
  4. Renderers see dirty host VRAM frames, not stale REU copies. All VRAM changes mark display regions; palette/start-address/mode changes can invalidate the entire visible image without changing VRAM.
  5. Any guest write to executable bytes invalidates decoded/fetch state for all segment aliases. A predecode cache added later keys by physical bytes/generations, not just CS:IP.
  6. REU-to-REU copies use a host bounce buffer. Ordinary REU registers do not provide a direct REU-to-REU copy command.
  7. REP acceleration preserves the actual forward/backward sequence. Overlapping MOVS is not automatically memmove: forward overlap can deliberately replicate bytes. Split at segment/index/page/physical-wrap boundaries and event checkpoints; preserve CX/SI/DI/flags at interruption.
  8. Reads/writes crossing RAM/ROM/video boundaries dispatch each affected byte/part under the bus contract. An optimization may not bypass ROM protection or dirty-video notification.

Tests include alias writes, eviction during instruction fetch, dirty code replacement, BIOS DMA into partial cached pages, dirty video reads, zero-length bulk operations, 64 KiB count encoding, pin exhaustion, forced minimum-frame tests, and fault injection before/after each ownership transition.

Current BIOS and storage ownership

The BIOS initializer owns guest IVT/BDA 00000–004FF and ROM F0000–FFFFF. It uses the coherent bus under a temporary all-RAM initialization mode and restores the prior mode; normal guest writes cannot change ROM. Conventional RAM outside IVT/BDA and configured media remain caller-owned. INT 11h/12h ordinary ROM code reads mutable BDA through the CPU bus, including dirty resident bytes.

Legacy cold floppy A begins at REU100000 and remains explicitly unloaded until its import completes. Native paused mount/swap uses PREPARE/COMMIT and rotates three complete360KiB arenas100000/180000/380000, so later A/B bases come from their independent descriptors. The incoming loader can write only the returned free arena and must provide whole-file/CRC/known-close proof before publication. Dirty, readonly, mount/content/clean generation pairs and binding cookies are per drive; CLEAN acknowledges an independently verified complete save and cannot clear newer dirty data. Cold initialization resets this session state. Disk reads/writes use range copying, so partial cached-page neighbors and dirty export bytes retain their authority. C000–C0FF is a separate 256-byte host bounce buffer, unavailable to resident code. It is not embedded in the PRG. The linked UCI transport buffer occupies C100–C8FF, leaving C900–CFFF (1,792 bytes) for additional resident code; the full inclusive host map above still totals 65,536. These 2,048 bytes are measured reservations, not reclaimable code space while the transport is linked.

A range is linear physical guest memory with 20-bit wrap, unlike CPU segmented word helpers that wrap a 16-bit offset. The disk BIOS checks the translated physical 64 KiB DMA boundary independently from ES:BX wrapping. REU ranges must be outside guest backing and within the minimum 4 MiB arena; range length zero means no bytes, whereas the low-level DMA primitive rejects zero.

Resident device code and contiguous PRG layout

The runtime/unit linker configuration cfg/dos64-runtime.cfg places hot CODE/RODATA in MAIN at 0801–3FFF and DEVICECODE at 5000–5FFF. Logical video occupies 1,696 DEVICECODE bytes, 5000–569F. Other code may not spill into the 4000–4FFF screen/font reservation, the 6000–7FFF bitmap, cache frames or staging. Device scratch uses DEVICESTATE at EA00–EEFF; CACHEMETA is separately bounded to E900–E9FF, and EF00–EFFF stays reserved for future gateways/vectors. Code placement and static ownership are asserted independently from PRG length.

The PRG is contiguous because the loader writes sequential addresses. MAIN is zero-padded through 3FFF; 4000–4FFF contains explicit startup zero initialization for screen/font RAM, then DEVICECODE begins at 5000. Padding and startup zeros are file bytes, not linked CODE/RODATA or free-standing executable allocations. Loading the program initializes this display reservation but supplies no font or renderer. Runtime and unit PRGs can therefore have the same file length while their linked CODE/test payload differs. Standalone hardware probes/helpers retain cfg/dos64.cfg and their prior byte identity.

The historical video/adjust map is retained in slice evidence (local development record, not distributed), while the ledger (local development record, not distributed) records later linked modules. At that checkpoint runtime linked usage was 16,758 bytes; its 20,129-byte PRG additionally contains 2,072 MAIN padding bytes and 4,096 display startup zeros. Its unit linked usage was 17,746 with 1,096 MAIN padding bytes and the same 4,096 startup zeros, producing the same 20,129-byte PRG. UCIBUFFER at C100–C8FF is now linked and measured. It adds 2,048 writable bytes independently from the PRG file and its padding. Current clock/keyboard/UCI/native-clock maps supersede the historical video/adjust totals in the ledger.