C64-dev/newLang/planning/claims/E01-S02.md

---

story: E01-S02 owner: e01_mmu_probe status: done started: 2026-11-07 depends-on: [E01-S01]

E01-S02 Claim

Intended change

Create an isolated C128 MMU probe that proves distinct RAM banks, verified common memory, safe return across a bank switch, explicit IRQ handling, and observed page-zero/page-one behavior.

File area

• src/platform/mmu-probe.s
• cfg/mmu-probe-c128.cfg
• scripts/build-mmu-probe.ps1
• scripts/run-mmu-probe.ps1
• scripts/verify-mmu-probe.ps1
• monitor/mmu-probe-*.txt
• docs/mmu-probe.md
• planning/claims/E01-S02.md
• generated files under build/

Acceptance evidence

• Both 64K banks hold and return distinct test patterns ($4000 = $11 in bank 0, $22 in bank 1).
• The chosen common region remains visible from both bank selections (8K bottom+top common; marker round-trip passes).
• Common code safely switches bank and returns with IRQ handling explicit (JSR/RTS under bank 1 with SP unchanged; PHP/SEI ... PLP).
• Page-zero/page-one relocation and common-priority behavior are recorded in docs/mmu-probe.md.
• VICE monitor evidence shows only intended MMU writes (42 stores in the entry..done window, all from probe code, only $FF00 and $D506-$D50A).

Coordination notes

E01-S01 files are read-only inputs. KERNAL mapping wrappers belong to E01-S03 and are not implemented here. Added one paragraph to docs/architecture.md §4.2 pointing to the evidence, as E01-S04 did for display/clock.

Work log

• Consulted the Commodore 128 Programmer's Reference Guide MMU sections.
• First verified run: result $DF; only the page-zero common-priority bit failed. The probe had assumed bottom common would cancel a P0 pointer aimed at bank 1.
• Added observation bytes. VICE x128 3.10 shows the translation applies but the bank bit is forced to 0: P0 write landed at bank0:$21F1; P1 PHA landed at bank0:$2100+SP. Rewrote both checks to assert that model.
• Fixed a probe side effect: the P1 test left $5A at bank0:$21F6 (BASIC area). That byte is now saved and restored.
• Fixed the verifier: byte checks parse monitor dump rows instead of only matching row-start addresses; removed an extra r command that stopped q from exiting x128; replaced a text grep of register names with a real store trace on $FF00 and $D500-$D50B, armed only during the probe window because the KERNAL $02A5/$02AB helper floods $FF00 stores during boot.

Completion

• Tests run: scripts/verify-mmu-probe.ps1 (twice); scripts/run-mmu-probe.ps1; scripts/verify-minimal.ps1; scripts/verify-display-clock.ps1; tests/grammar/validate.ps1.
• Results: result $FF, completion $A5, banks $11/$22, pages $77/$33, common-priority bank0 $66/$5A, 42 audited MMU stores; screenshot shows NOVA128 MMU PROBE OK then READY.; minimal, display/clock, and grammar regressions pass.
• Files changed: src/platform/mmu-probe.s, scripts/verify-mmu-probe.ps1, monitor/mmu-probe-trace.txt, docs/mmu-probe.md (new), docs/architecture.md §4.2, this claim.
• Remaining risks: VICE-only evidence (physical check is E08-S06). An IRQ taken with bank 1 selected is untested; mmu.s must keep IRQs masked across non-default mappings unless E01-S03/E01-S05 proves a common-RAM IRQ path. The probe's addresses are not the final compiler map (E01-S05).