How x65/emu works
Project type and purpose
• Project type: A native (and WebAssembly) emulation application written in C/C++ that simulates the “X65 Computer” by wiring chip‐level emulators together.
• Purpose: Load an XEX ROM, step through an emulated hardware “tick” loop, render video & audio, handle I/O, and optionally run in a browser via Emscripten.
File structure
Top‐level directories and purposes:
• src/ — Main emulator engine, chip definitions, system wiring, UI code
• src/chips/ — Individual chip tick implementations (CIA, PWM, YMF262, etc.)
• src/systems/ — System‐level glue (x65.c) that connects chips into a breadboard
• src/common/ — Cross‐platform helpers (clock, gfx, file system, web API, profiling, Sokol wrappers)
• src/ui/ — ImGui/Sokol/UI front‐end components (console, debugger, memory editor, settings, snapshots)
• src/codegen/ — Python/shell scripts that generate C code for 6502 and W65C816s instruction sets at build time
• roms/ — Sample XEX ROMs and data used to drive the emulator
• tests/ — Unit/regression tests, CPU‐emu test vectors
• CMakeLists.txt — Build orchestrator, configures native and WASM targets
Extract architecture hints from README
• Emulation core is “just wiring chip emulators” via a 64-bit pin mask interface.
• Supports native (Linux/Windows) with X11/ALSA, and WebAssembly (Emscripten + web API).
Main components
1. CMake – orchestrates configuration, compiles ext libs, invokes codegen scripts.
2. Code generators (m6502_gen.py, w65c816s_gen.py) → produce CPU decode tables and helper C code.
B. Runtime subsystem
• System glue (src/systems/x65.c) wires chip modules together
• Chip modules (src/chips/*.c & .h) implement tick(pin_mask) for each device
• Memory & Bus – common/fs.c, common/config.h handle ROM loading & memory map
• Clock & Timing (common/clock.c)
• Profiling & Logging (common/prof.c, src/log.h)
• File system abstraction (common/fs.c)
• Native UI: Sokol + ImGui wrappers (common/sokol.c, src/common/ui.cc, src/ui/*)
• Web UI: shell.html + webapi.c (for WASM)
• Components: console, memory editor, debugger, chip panels, audio settings
• Video: shaders.glsl → GPU via Mesa/EGL or WebGL
• Audio: ALSA (native) or Web Audio API (WASM)
• doctest & custom tests under src/tests
• CPU‐emu reference logs & binaries
Relationships & data flow
• At build‐time: CMake → codegen → compiled runtime modules → final emu/emu.wasm binary
• At runtime:
ROM file → Memory subsystem
↓
Emulation Engine ticks clock → each chip.tick(pin_mask)
↓
Video frames → shaders → Display
↑
User input (keyboard/mouse) → UI layer → translates to pin_mask inputs
↓
Audio samples → Audio backend
←
Profiles & logs ← Engine events
• For WASM: UI Layer uses webapi.c to interface with browser canvas and audio.
Architectural patterns & design principles
• Modular chip emulation: each chip isolated behind a uniform tick(pin_mask) API.
• Clear separation of concerns:
– Build‐time codegen vs runtime logic
– Core emulation vs UI vs platform abstraction
• Dependency injection via config.h and CMake targets for native vs WASM.