zdebel

zdebel / MEMORY_MAP.md

Last active 1 day ago

Like 0

revised this gist 1 day ago · 6d6989a

1 file changed, 82 insertions

MEMORY_MAP.md (file created)
@@ -0,0 +1,82 @@
1 + # P65: memory map and I/O registers
2 +
3 + The 65C02 sees 64 KB. All of it lives in one array in the Pico (`cpu_memory[]`);
4 + there is no address decoder in hardware, so the map below is decided purely by
5 + the firmware (core 1 bus loop, `src/65c02.c`, `include/mapper.h`).
6 + Names come from `include/mapper.h`, `emulator/memmap.py` and the equates at the
7 + top of `asm_examples/testrom1.a65` - keep the three in sync.
8 +
9 + ## 1. Map
10 +
11 + | Address | What |
12 + |----------------|------|
13 + | `$0000-$7FFF` | RAM, 32 KB (zero page, stack, BASIC, programs) |
14 + | `$8000-$80FF` | I/O page (registers below; unused offsets read the stored byte, writes ignored) |
15 + | `$8100-$FFFF` | ROM image (BASIC, 32512 B), writes ignored - **or RAM when ROMCTL bit 0 = 1** (section 3) |
16 +
17 + ## 2. Registers (offset from `$8000`)
18 +
19 + | Addr | Name | Access | Meaning |
20 + |---------|---------|--------|---------|
21 + | `$8000` | LEDS | W: bits 0-2 = LED0..2 (1 = on); R: `$F8` or leds | the three LEDs |
22 + | `$8001` | KEY | R: bit 7 = key waiting, bits 0-6 = ASCII; W: any value acknowledges | keyboard (8-char queue in the Pico) |
23 + | `$8002` | VDATA | R/W | TMS9918 data port, VRAM address auto-increments |
24 + | `$8003` | VCTRL | W: address / register; R: status | TMS9918 control / status. Status read clears flags and releases /IRQ; bit 7 = 60 Hz frame flag. See `VSYNC.md` |
25 + | `$8004` | ROMCTL | W: bit 0; R: bit 0, bit 7 | ROM on/off, see section 3 |
26 + | `$8010-$802F` | STORAGE | mailbox | flash file system, see `STORAGE.md` |
27 + | other | | | unused |
28 +
29 + ## 3. ROMCTL (`$8004`): switching the ROM off
30 +
31 + Gives the program 32 KB more RAM at `$8100-$FFFF`.
32 +
33 + | Bit | Write | Read |
34 + |-----|-------|------|
35 + | 0 | `1` = ROM off (area above the I/O page is RAM), `0` = ROM on (image restored) | current state (1 = ROM off) |
36 + | 7 | - | **busy**: the ROM image is being copied back, do not run ROM code yet |
37 +
38 + * Switching off changes nothing in memory: the ROM image stays at `$8100-$FFFF`
39 + until the program overwrites it, so ROM routines can still be called as long as
40 + their bytes are intact.
41 + * Switching on makes core 0 copy the 32 KB image back (about 0.3 ms, estimate,
42 + not measured). Poll bit 7 until it is clear.
43 + * `$8000-$80FF` stays I/O in both modes, so RAM is split: `$0000-$7FFF` and
44 + `$8100-$FFFF`.
45 + * With the ROM off, `$FFFA-$FFFF` (NMI / RESET / IRQ vectors) are RAM too:
46 + **the program must write its own vectors**, and an IRQ before that jumps
47 + into garbage. Keep interrupts disabled (`SEI`) across the switch.
48 + * Storage `LOAD` / `BLOAD` / `BRUN` may write above `$8100` while the ROM is off
49 + (otherwise such a load is refused with "address"). A file must not cross the
50 + I/O page.
51 + * Not restored by: Ctrl+= and the CPU reset done by `main.c` (only at power up).
52 + If a program with the ROM off hangs, power-cycle the Pico.
53 +
54 + Exit to BASIC from a program that switched the ROM off:
55 +
56 + ```asm
57 + sei
58 + stz $8004 ; ROM on
59 + wait: lda $8004
60 + bmi wait ; bit 7 = still copying
61 + jmp ($FFFC) ; cold start; or jump to the BASIC warm start
62 + ```
63 +
64 + Switching off:
65 +
66 + ```asm
67 + sei
68 + lda #1
69 + sta $8004 ; ROM off
70 + ; ... write your vectors at $FFFA-$FFFF, IRQ handler, etc. ...
71 + cli ; only if your IRQ vector is set up
72 + ```
73 +
74 + Status: emulator tested (`tests/test_romctl.py`); firmware builds, **not tested on
75 + the board** at the time of writing.
76 +
77 + ## 4. Where this is implemented
78 +
79 + * Firmware: `include/mapper.h` (map, `rom_ram`), `src/mapper.c` (`romctl_write`,
80 + `mapper_rom_poll`), `src/65c02.c` (write path), `src/video.c` (calls the poll).
81 + * Emulator: `emulator/memmap.py`, `emulator/machine.py` (`_romctl_write`,
82 + `_update_rom`), `emulator/cpu65c02.py`.