memory: fit Ramsey-controlled motherboard fast RAM on the A3000/A4000

[LinuxJedi]

Summary

The Ramsey register file has been modelled since the big-box profiles landed, but the RAM it fronts was missing. This adds the motherboard fast RAM bank: 32-bit local memory off the chip bus that ends at $08000000 and grows downward (a full 16 MiB reaches $07000000), on both the A3000 and A4000. It is not autoconfig -- Kickstart sizes it with its own probe, reading Ramsey's control register for the DRAM geometry and pattern-testing the banks, with Fat Gary timing out the unfitted space -- so the decode, the register seeding, and the timeout all have to line up for the guest to see it.

• Memory gains the mb_ram bank; a new PlainMemRegion::MbRam decodes it in the CPU read/write/peek/debug-write paths at uncontended external speed, cacheable by both CPU caches like expansion RAM. peek_word_any and writable_ram_regions reach it for the debugger, GDB stub, and control protocol.
• [memory] motherboard / --motherboard size the bank; the A3000/A4000 profiles fit their stock 4M by default (motherboard = "0" removes it). Validation requires a Ramsey and a 32-bit CPU, and the size must fill whole Ramsey banks: 1M-4M in 1M steps, or 8M/12M/16M.
• Ramsey's control register is seeded from the fitted total (RamseyRevision::bank_bytes_for) instead of the hardcoded stock geometry, so Kickstart's probe and the diagnostic tools read a description matching the RAM that answers. This retires the TODO(codewiz) in emulator.rs.
• The launcher Memory tab gains a Motherboard RAM row (greyed "needs A3000/A4000" elsewhere); MachineDescriptor carries the size for the savestate shape guard, and STATE_VERSION moves to 35.
• Docs: configuration.md (including removing the stale "Motherboard fast RAM is not emulated" note), ui.md, copperline.example.toml, --help.

Note the behavior change: existing A3000/A4000 configs now boot with 4M of fast RAM fitted, matching the stock machines.

Verification

Booted the real Kickstart 3.1 A4000 ROM headless and walked exec's memory list over the control protocol:

• A4000, default 4M: "expansion memory": $07C00020-$08000000, attrs $0505 (PUBLIC|FAST|LOCAL|KICK), ExecBase relocated into the bank.
• A4000, --motherboard 16M: $07000020-$08000000, 16320 KB free.
• A3000 profile (Ramsey-04, 68030): same result from its 1 MiB-bank geometry.

tests/mb_ram.rs pins this as an asset-gated #[ignore] integration test (boots the KS 3.1 A4000 ROM, walks the MemList, ~1.6s in release; skips cleanly without the ROM). New unit tests cover the bank geometry helper, the base/reset math, config defaults and constraints, the debugger helpers, and a CPU-level test showing a 68030 store lands in the bank while a 68000's 24-bit bus wraps past it.

cargo test (1706 unit tests + suites), cargo clippy, and cargo fmt --check are all clean.

[Copilot]

Pull request overview

Adds emulation support for Ramsey-controlled “motherboard fast RAM” on big-box Amigas (A3000/A4000), including configuration/CLI/UI wiring, address decoding/cacheability, debugger visibility, and save-state shape updates.

Changes:

• Introduce a new Memory::mb_ram bank (top-down, ending at $0800_0000) and decode it across CPU + debugger access paths.
• Add config/CLI/UI support for sizing motherboard RAM (defaults to 4 MiB on A3000/A4000) plus validation and Ramsey control-register seeding based on fitted geometry.
• Update save-state descriptor/versioning and add unit/integration tests covering decode, geometry selection, and debugger helpers.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/mb_ram.rs	New asset-gated integration test that boots KS 3.1 and verifies Exec sizes the motherboard RAM bank.
src/zorro_device.rs	Update test Memory literals to include the new mb_ram field.
src/z3660.rs	Update multiple test Memory literals to include mb_ram.
src/wasmboard.rs	Update test Memory literal to include mb_ram.
src/video/window/tests.rs	Update test Memory literal to include mb_ram.
src/video/launcher.rs	Add “Motherboard RAM” row/presets and persist it into generated config overrides.
src/savestate.rs	Bump STATE_VERSION and extend MachineDescriptor tests/data to include mb_ram_bytes.
src/ramsey.rs	Add bank_bytes_for(total) helper and tests to seed Ramsey control geometry from fitted motherboard RAM.
src/memory.rs	Add mb_ram, fit_mb_ram, mb_ram_base, and reset handling + unit test.
src/main.rs	Add --motherboard SIZE CLI override and help text.
src/gdbstub.rs	Update test Memory literal to include mb_ram.
src/filesys.rs	Update test Memory literal to include mb_ram.
src/emulator.rs	Fit mb_ram during machine build and seed Ramsey geometry from fitted size.
src/cpu.rs	Add motherboard RAM to plain-memory decode, debugger writes, cacheability, and add a CPU-level decode test.
src/control.rs	Update test Memory literal to include mb_ram.
src/config.rs	Add [memory] motherboard + overrides, validation, profile defaults (A3000/A4000), and description string updates.
src/cdtv.rs	Update test Memory literal to include mb_ram.
src/bus/tests.rs	Add test ensuring debugger helpers (peek_word_any, writable_ram_regions) reach motherboard RAM.
src/bus.rs	Extend writable_ram_regions and peek_word_any to include motherboard RAM.
src/a4091.rs	Update test Memory literal to include mb_ram.
src/a2091.rs	Update test Memory literal to include mb_ram.
src/a2065.rs	Update test Memory literal to include mb_ram.
docs/guide/ui.md	Document launcher Memory tab now includes motherboard RAM.
docs/guide/configuration.md	Document [memory] motherboard/--motherboard and remove stale “not emulated” note.
copperline.example.toml	Add commented example/docs for motherboard RAM setting.

Comments suppressed due to low confidence (1)

src/savestate.rs:581

• In round_trips_the_machine_descriptor, the test constructs a MachineDescriptor with mb_ram_bytes set but uses a 24-bit M68EC020 CPU and MachineModel::A1200, which is an impossible combination for motherboard RAM per the new semantics. This makes the test harder to read/maintain and could become misleading if descriptor semantics tighten later. Use an A3000/A4000 + 32-bit CPU pairing in the test data.

        let descriptor = MachineDescriptor {
            cpu: CpuModel::M68EC020,
            chip_ram_bytes: 2 * 1024 * 1024,
            fast_ram_bytes: 8 * 1024 * 1024,
            slow_ram_bytes: 0,
            mb_ram_bytes: 4 * 1024 * 1024,
            chipset: crate::config::Chipset::Aga,
            video_standard: crate::chipset::agnus::VideoStandard::Ntsc,
            machine: Some(crate::config::MachineModel::A1200),
            rom: crate::config::RomId::of(b"a fake kickstart image"),

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.