Refuse --ram above what the configured CPU can address (issue #98)

[sidick]

Fixes #98.

--ram 32M on the default --cpu 68000 gave you a program that died several library calls later with continuation stub trapped at 0x000000c4 with no pending continuation -- a message about volamos's internals that points at nothing the user did.

Cause

The 24-bit address bus. The guest stack sits at the top of the address space, so --ram 64M puts A7 near 0x0400_0000, which a 68000/68010 cannot express. The address wraps, the JSR into a library pushes its return address into low memory, and the RTS pops whatever happened to be there. The wrapping is faithful to the hardware; placing the stack where the CPU cannot reach it is not.

Reproduces on main with the repo's own fixtures at --ram 17M -- one byte over 16 MiB is enough:

$ volamos --ram 17M fixtures/exectest
volamos: fixtures/exectest: continuation stub trapped at 0x000000c4 with no pending
continuation (guest jumped to the trampoline stub directly, or ContinuationStack
bookkeeping is out of sync)

fixtures/memtest too. fixtures/hello does not, because it makes no call that has to return through a continuation -- which is why a smoke test never caught this.

Fix

run checks before it even reads the program, and fails naming both flags -- the same treatment an oversized --stack already got:

$ volamos --ram 17M fixtures/exectest
volamos: --ram 17825792 is more address space than a 68000 can reach: that CPU has a
24-bit address bus, so it can only address 16777216 bytes, and the guest stack at the
top of a larger space would be at an address it cannot express -- ask for a 32-bit
address bus with --cpu 68020 (or any later model), or lower the size to 16777216 or
less (--ram on the command line, RAM= in a config file)

$ volamos --ram 64M --cpu 68020 fixtures/exectest
exec ok

Only a raised --ram was ever affected -- the default is exactly 16 MiB, which a test now pins against the CPU's own limit so the two constants cannot drift apart.

backend::addressable_bytes asks the m68k crate for the limit rather than hardcoding a model table. The crate owns CpuCore::address_mask and sets it per model, so the one authority on which models wrap is the emulator that does the wrapping. That also settles the 68EC020, which has a 24-bit external bus on real silicon that the crate does not currently model: volamos follows the crate rather than rejecting a configuration that demonstrably works today. Verified empirically across all 11 models -- only 68000 and 68010 wrap.

The check covers the config-file path too, since it sits in run after the merge (RAM=32M in a .volamos is refused the same way, and the message names RAM= as well as --ram).

Also here

• Two doc examples that this turns into errors: volamos --ram 64M --stack 1M fixtures/hello in CLI-Reference.md and volamos --stack 1M --ram 64M fixtures/hello in Examples.md. Both fixed, and every command in the changed doc sections was run to confirm it does what the page says.
• The missing 0.7 changelog entry for --sanitize: recycled heap block keeps its freed-block poison, so a fresh AllocVec reports use-after-free and runs ~75x slower #95/sanitize: clear recycled-block poison in the heap, not per handler #97, which merged without one.

Tests

Four new: the default---ram-equals-68000's-limit invariant, rejection on both 24-bit models, acceptance at u32::MAX on all nine 32-bit ones, and a cpu_model_name <-> parse_cpu_type round trip so an error message can only ever show a spelling the user could have typed.

cargo test --release: 1014 passed, 0 failed. clippy -D warnings and fmt --check clean.

🤖 Generated with Claude Code