Feature: System Emulation Framework (C64, generic modes)

[barryw]

Summary

Transform sim6502 from a processor emulator to a system emulation framework. Instead of processor(6502|6510|65c02), users will declare system(c64) or system(generic_6502) to get accurate memory maps, ROM overlays, and banking behavior.

This addresses #5 where C64 code writing to $A000-$DFFF (under BASIC/KERNAL ROM) corrupts code because the simulator uses flat 64KB RAM instead of the C64's layered memory architecture.

Motivation

Real 6502-based systems have complex memory architectures:

• C64: RAM "underneath" ROM, banking controlled by $01 processor port
• Apple II: Soft switches for bank selection
• Commander X16: VERA, banked RAM/ROM

The current flat 64KB model can't accurately test code that relies on these behaviors.

Proposed Design

1. New DSL Syntax

; New system declaration (processor auto-determined)
system(c64)              ; 6510 + C64 memory map + banking
system(generic_6502)     ; Plain 6502, flat 64KB (current behavior)
system(generic_6510)     ; 6510 with $00/$01 I/O, flat memory
system(generic_65c02)    ; 65C02, flat 64KB

; ROM loading (new)
rom("kernal", "kernal.901227-03.bin")
rom("basic", "basic.901226-01.bin")

; Program loading (existing, unchanged)
load("my-program.prg")

2. Backward Compatibility

processor() syntax continues to work but emits deprecation warning:

processor(6502)  →  Warning: processor() is deprecated, use system(generic_6502)

3. Memory Architecture

public interface IMemoryMap
{
    byte Read(int address);
    void Write(int address, byte value);
    void LoadRom(string name, byte[] data);
    void RegisterIOHandler(int startAddr, int endAddr, IIOHandler handler);
}

public interface IIOHandler
{
    byte Read(int address);
    void Write(int address, byte value);
}

Each system implements IMemoryMap:

• GenericMemoryMap - flat 64KB (current behavior)
• C64MemoryMap - RAM + ROM layers + $01 banking

4. C64 Memory Banking (Initial)

Banking controlled by $01 processor port bits 0-2:

$01 Value	LORAM	HIRAM	CHAREN	Result
$37	1	1	1	BASIC + KERNAL + I/O (default)
$36	0	1	1	KERNAL + I/O
$35	1	0	1	All RAM visible
$34	0	0	0	All RAM, no I/O
...				(8 combinations)

EXROM/GAME cartridge lines deferred to future release.

5. I/O Handling

I/O region ($D000-$DFFF) uses callback hooks:

• Default stubs return sensible values
• VIC-II: return last written or defaults
• SID: writes ignored (no audio emulation)
• CIA: basic stubs, can be extended later

6. ROM Configuration

Layered lookup (highest priority first):

1. DSL override: rom("kernal", "custom.bin")
2. Config file: ~/.sim6502/systems.json
3. Environment: SIM6502_ROM_PATH=/roms
4. Default paths: ./roms/{system}/ or ~/.sim6502/roms/{system}/

Users must supply their own legally-owned ROM images.

7. Initial System Support

System	Processor	Memory Model
c64	6510	Full C64 banking
generic_6502	6502	Flat 64KB
generic_6510	6510	Flat 64KB + $00/$01
generic_65c02	65C02	Flat 64KB

Future: C128, VIC-20, Apple II, Commander X16, NES

Implementation Tasks

1. Define IMemoryMap and IIOHandler interfaces
2. Create GenericMemoryMap (extract current behavior)
3. Create C64MemoryMap with banking logic
4. Add system() grammar rule and visitor
5. Add rom() grammar rule and visitor
6. Deprecate processor() with warning
7. Implement ROM configuration loading
8. Create C64-specific tests
9. Update documentation

Related Issues

• Fixes Unsupported opcode 5A (PHY) error during InitZobristTables execution #5 (C64 code writing under ROM corrupts memory)

Questions for Reviewers

@barryw - Please review this spec

• Does this cover your chess engine's needs?
• Any C64 banking edge cases I missed?
• Priority of future systems (X16, Apple II, etc.)?

---

🤖 Generated with Claude Code

[barryw]

This is exactly what's needed! A few thoughts:

DSL Syntax 👍

The system(c64) declaration is clean and intuitive. Having it at the suite level makes sense - you typically test an entire program against one target system.

Banking Model

The 8 configurations from $01 bits 0-2 are spot-on. For reference, the most commonly used configurations in real C64 code:

$01 Value	Config	Common Use Case
$37	Default (BASIC+KERNAL+I/O)	Normal BASIC programs
$36	KERNAL+I/O, no BASIC	Games using $A000-$BFFF for data
$35	I/O only, no ROMs	Demos, max RAM with I/O access
$34	All RAM, no I/O	Burst computation (my TT case!)

The "Under-ROM RAM" Behavior

The key detail: when ROM is banked in, writes still go to underlying RAM - they're just not readable until ROM is banked out. This is what makes the C64's memory architecture so flexible.

ROM banked IN:  READ = ROM,  WRITE = RAM (underneath)
ROM banked OUT: READ = RAM,  WRITE = RAM

Test Case from Issue #5

Once implemented, my failing test would work by simply adding:

suite("Transposition Table") {
  system(c64)  // Enable C64 memory model
  symbols("/code/main.sym")
  load("/code/main.prg", strip_header = true)
  // ... tests that use $A000-$BFFF banking now work!
}

Optional Nice-to-Have

If you wanted to go further (not required for my use case):

• peek_ram(addr) / peek_rom(addr) functions to inspect specific layers
• Warning when writing to I/O range ($D000-$DFFF) in config $34 (all RAM) - common bug in real C64 code

Really excited to see this! Happy to help test when you have a branch ready. 🎮

[barryw]

Implementation Complete! 🎉

The system emulation framework has been fully implemented. Here's what was delivered:

New DSL Syntax

System Declaration (replaces processor()):

system(c64)           # Full C64 with memory banking
system(generic_6502)  # Flat 64KB RAM
system(generic_6510)  # Flat 64KB + $00/$01 I/O port
system(generic_65c02) # Flat 64KB for 65C02

ROM Loading:

rom("kernal", "path/to/kernal.rom")
rom("basic", "path/to/basic.rom")

C64 Memory Banking

The critical C64 behavior is now implemented:

• Writes ALWAYS go to RAM, even when ROM is banked in
• Banking controlled via $01 port (LORAM, HIRAM, CHAREN bits)
• Full support for all C64 banking modes ($34, $35, $36, $37)

This enables "under-ROM" RAM techniques essential for chess engines and other C64 programs.

Backward Compatibility

processor() still works with a deprecation warning:

WARN: processor() is deprecated - use system(generic_6510) instead

Files Added

• sim6502/Systems/IMemoryMap.cs - Memory abstraction interface
• sim6502/Systems/IIOHandler.cs - I/O handler interface
• sim6502/Systems/SystemType.cs - System type enum
• sim6502/Systems/GenericMemoryMap.cs - Flat 64KB RAM
• sim6502/Systems/Generic6510MemoryMap.cs - 6510 with I/O port
• sim6502/Systems/C64MemoryMap.cs - Full C64 banking
• sim6502/Systems/MemoryMapFactory.cs - Factory for memory maps

Test Coverage

• 1195 tests passing (including 40+ new system emulation tests)
• C64 banking tests verify write-under-ROM behavior
• Backward compatibility tests for processor()

Example Usage

suites {
  suite("C64 Chess Engine Test") {
    system(c64)
    rom("kernal", "kernal.rom")
    rom("basic", "basic.rom")
    
    test("write-under-rom", "Write to RAM under BASIC ROM") {
      $A000 = $42          ; Goes to RAM underneath
      $01 = $35            ; Bank out ROMs
      assert(peekbyte($A000) == $42, "RAM visible after banking")
    }
  }
}

This implementation directly addresses Issue #5's requirements for proper C64 memory banking behavior.

Closes #6