# x65/emu architecture

> Architecture diagram of the GitHub repository x65/emu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/x65/emu
- Repository: https://github.com/x65/emu

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-time Subsystem
    subgraph "Build-time Subsystem"
        direction TB
        CMake["CMake (CMakeLists.txt)"]:::orange
        Codegen["Code Generators"]:::orange
        Generated["Generated CPU Decode Code"]:::orange
    end

    CMake -->|configures & invokes| Codegen
    Codegen -->|produces| Generated

    %% Runtime Subsystem
    subgraph "Runtime Subsystem"
        direction TB

        subgraph "Emulation Engine" 
            direction TB
            X65["System Glue (src/systems/x65.c/.h)"]:::blue
            Chips["Chip Modules (tick(pin_mask))"]:::blue
            Memory["Memory & Bus Subsystem"]:::blue
        end

        subgraph "Core Services"
            direction TB
            Clock["Clock & Timing (src/common/clock.c/.h)"]:::gray
            Prof["Profiling & Logging (src/common/prof.c/.h & src/log.h)"]:::gray
            FS["File System Abstraction (src/common/fs.c/.h)"]:::gray
        end

        subgraph "UI Layer"
            direction TB
            NativeUI["Native UI (Sokol+ImGui)"]:::purple
            WebUI["Web UI (shell.html, webapi.c/.h)"]:::purple
        end

        subgraph "Audio/Video Backend"
            direction TB
            Video["Video Backend (shaders.glsl)"]:::green
            Audio["Audio Backend (Sokol stubs)"]:::green
        end

        subgraph "Test Harness" 
            direction TB
            Test["Unit/Regression Tests (src/tests)"]:::dashed
        end
    end

    %% Data Flows
    ROMs["Sample ROMs (roms/)"]:::default
    UserInput["User Input (keyboard/mouse)"]:::default

    ROMs -->|loads| FS
    FS -->|memory map| X65
    X65 -->|ticks chips| Chips
    X65 -->|logging events| Prof
    Prof -->|writes logs| Test

    UserInput -->|UI events| NativeUI
    UserInput -->|UI events| WebUI
    NativeUI -->|pin_mask inputs| X65
    WebUI -->|pin_mask inputs| X65

    X65 -->|framebuffer| Video
    X65 -->|audio_buffer| Audio

    %% Click Events
    click CMake "https://github.com/x65/emu/blob/main/CMakeLists.txt"
    click Codegen "https://github.com/x65/emu/blob/main/src/codegen/m6502_gen.py"
    click Codegen "https://github.com/x65/emu/blob/main/src/codegen/w65c816s_gen.py"
    click Codegen "https://github.com/x65/emu/blob/main/src/codegen/m6502_gen.sh"
    click Codegen "https://github.com/x65/emu/blob/main/src/codegen/w65c816s_gen.sh"
    click X65 "https://github.com/x65/emu/blob/main/src/systems/x65.c"
    click X65 "https://github.com/x65/emu/blob/main/src/systems/x65.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/cgia.c"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/cgia.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/pwm.c"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/pwm.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/ymf262.c"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/ymf262.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/ria816.c"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/ria816.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/tca6416a.c"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/tca6416a.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/m6526.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/w65c816s.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/beeper.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/chips_common.h"
    click Chips "https://github.com/x65/emu/blob/main/src/chips/clk.h"
    click Memory "https://github.com/x65/emu/blob/main/src/common/fs.c"
    click Memory "https://github.com/x65/emu/blob/main/src/common/fs.h"
    click Memory "https://github.com/x65/emu/blob/main/src/common/config.h"
    click Clock "https://github.com/x65/emu/blob/main/src/common/clock.c"
    click Clock "https://github.com/x65/emu/blob/main/src/common/clock.h"
    click Prof "https://github.com/x65/emu/blob/main/src/common/prof.c"
    click Prof "https://github.com/x65/emu/blob/main/src/common/prof.h"
    click Prof "https://github.com/x65/emu/blob/main/src/log.h"
    click FS "https://github.com/x65/emu/blob/main/src/common/fs.c"
    click FS "https://github.com/x65/emu/blob/main/src/common/fs.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/common/sokol.c"
    click NativeUI "https://github.com/x65/emu/blob/main/src/common/ui.cc"
    click NativeUI "https://github.com/x65/emu/blob/main/src/common/ui.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_console.cc"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_console.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_memedit.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_dbg.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_display.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_settings.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_snapshot.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_audio.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_chip.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_dasm.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_ria816.cc"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_ria816.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_tca6416a.cc"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_tca6416a.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_w65c816s.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_ymf262.cc"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_ymf262.h"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_x65.cc"
    click NativeUI "https://github.com/x65/emu/blob/main/src/ui/ui_x65.h"
    click WebUI "https://github.com/x65/emu/blob/main/src/common/webapi.c"
    click WebUI "https://github.com/x65/emu/blob/main/src/common/webapi.h"
    click WebUI "https://github.com/x65/emu/blob/main/src/common/shell.html"
    click WebUI "https://github.com/x65/emu/blob/main/src/shell.html"
    click Video "https://github.com/x65/emu/blob/main/src/common/shaders.glsl"
    click Test "https://github.com/x65/emu/blob/main/src/tests/CMakeLists.txt"
    click Test "https://github.com/x65/emu/blob/main/src/tests/cpuemu.c"
    click Test "https://github.com/x65/emu/blob/main/src/tests/cputest.cpp"
    click Test "https://github.com/x65/emu/blob/main/src/tests/AllSuiteA.bin"
    click Test "https://github.com/x65/emu/blob/main/src/tests/AllSuiteA.log"
    click Test "https://github.com/x65/emu/blob/main/src/tests/ehbasic.bin"
    click ROMs "https://github.com/x65/emu/tree/main/roms/"

    %% Styles
    classDef orange fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef blue fill:#87CEFA,stroke:#333,stroke-width:1px;
    classDef gray fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef purple fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef green fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef dashed stroke-dasharray: 5 5,fill:none,stroke:#333,stroke-width:1px;
    class ROMs,UserInput default
```
