# nicolasiragne/gbmu architecture

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

- Interactive diagram: https://gitdiagram.com/nicolasiragne/gbmu
- Repository: https://github.com/nicolasiragne/gbmu

## Overview

##### Project type and purpose
- This is “GBmu,” a GameBoy emulator project. It ships two parallel implementations:
- A native C/C++ core + CLI/SDL‐based UI, built via CMake.
- A Rust “workspace” wrapping the same core via FFI (crates/bindings) plus two Rust executables (CLI and TUI debugger), built via Cargo.
- Its purpose is to emulate GameBoy hardware (CPU, PPU, GPU, timer, MMU, MBC) and expose a debugger/UI on top.

##### File structure
- Top‐level:
- srcs/ + includes/ + libyacc/ + CMakeLists.txt → C/C++ emulator core, debugger grammar, CLI debugger, SDL frontend (gbclodo).
- crates/ → Rust workspace:
– crates/bindings → build.rs uses cc crate to compile C core, providing safe FFI bindings.
– crates/shared → common Rust utilities.
– crates/gbmu → Rust CLI emulator, uses bindings + shared.
– crates/ui → Rust TUI debugger, uses bindings + shared.
- rom/, saves/, savestates/ → input ROMs & state persistence.
- scripts/ + docker/ + etc. → ancillary tooling.
- Build scripts:
- CMake and Makefile orchestrate the native build;
- Cargo.toml (workspace) orchestrates the Rust build.

##### README for additional insights
- Confirms CMake build for C/C++ binary (./gbmu <rom_file>), optional libyacc debugger vs. fallback_debugger.
- Mentions dependencies: GNU readline, SDL (implied by renderer_opengl), libyacc.

##### Main components & interactions
- Core Emulator Module (C code):
- CPU (includes registers, instruction decode, opcodes/)
- MMU (memory.c, io_map.c, MBC handlers)
- PPU/GPU (ppu.c, gpu.c, palette.c)
- Timer (timer.c), input (input_functions.c / joypad), sound (in DMG_SOUND.sav, not fully implemented),
- Savestate / Save‐game (savestate.c, save_game.c)
- Debugger Module (C++ and fallback):
- libyacc‐powered parser (libyacc_wrapper) + SymbolNonTerminal*/SymbolTerminal*
- Fallback (fallback_debugger.c, fallback_debugger.h)
- UI / Frontends:
- Native C CLI (“gbmu” binary)
- Native SDL/OpenGL GUI (“gbclodo” under srcs/gbclodo)
- Rust CLI (crates/gbmu)
- Rust TUI Debugger (crates/ui)
- FFI Layer:
- crates/bindings compiles and exposes the C core via Rust FFI (build.rs, bindings.rs)
- crates/shared shares error types & utilities in Rust
- External Dependencies:
- libreadline, SDL2/OpenGL, libyacc

##### Architectural patterns & design principles
- Layering / separation of concerns:
- Low‐level core (hardware emulation) completely independent of UI
- Debugger hooks wired into core via well‐defined C APIs
- Rust wrapper crate cleanly isolates FFI details (separation Rust/C)
- Build‐time abstraction:
- Two build systems side by side (CMake vs. Cargo)
- Conditional inclusion of libyacc vs. fallback using CMake variable WITH_LIBYACC
- Plugin/extension points:

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External storage and libs
    ROM["ROM Files"]:::ext
    StateStore["Savestate Storage"]:::ext
    ExtLibs["External Libs"]:::ext

    %% CMake Build Layer
    subgraph "CMake Build"
        subgraph "C Core"
            CPU["CPU"]:::core
            MMU["MMU & I/O"]:::core
            PPU["PPU/GPU"]:::core
            Timer["Timer"]:::core
            Savestate["Savestate/Save-game"]:::core
            subgraph "Debugger"
                Libyacc["libyacc Parser"]:::debugger
                Fallback["Fallback Debugger"]:::debugger
            end
        end
        NativeCLI["Native CLI (gbmu)"]:::native
        NativeGUI["Native GUI (gbclodo)"]:::native
    end

    %% Cargo Workspace Layer
    subgraph "Cargo Workspace"
        FFI["Rust FFI Layer (bindings)"]:::rust
        Shared["Rust Shared Lib"]:::rust
        RustCLI["Rust CLI Emulator"]:::rust
        RustTUI["Rust TUI Debugger"]:::rust
    end

    %% Data Flows
    ROM -->|"load ROM"| CPU
    CPU -->|"memory access"| MMU
    CPU -->|"render calls"| PPU
    CPU -->|"tick"| Timer
    CPU -->|"save/load state"| Savestate
    Savestate -->|"I/O"| StateStore

    CPU <-->|"debug hooks"| Libyacc
    CPU <-->|"debug hooks"| Fallback

    CPU -->|"executes"| NativeCLI
    CPU -->|"executes"| NativeGUI

    NativeCLI -.->|"readline"| ExtLibs
    NativeGUI -.->|"SDL2/OpenGL"| ExtLibs
    Libyacc -.->|"libyacc"| ExtLibs

    CPU -->|"FFI boundary"| FFI
    FFI -->|"rust types"| Shared
    Shared -->|"uses"| RustCLI
    Shared -->|"uses"| RustTUI

    %% Click Events
    click CPU "https://github.com/nicolasiragne/gbmu/blob/master/srcs/init_cpu.c"
    click MMU "https://github.com/nicolasiragne/gbmu/blob/master/srcs/io_map.c"
    click PPU "https://github.com/nicolasiragne/gbmu/blob/master/srcs/gpu.c"
    click Timer "https://github.com/nicolasiragne/gbmu/blob/master/srcs/timer.c"
    click Savestate "https://github.com/nicolasiragne/gbmu/blob/master/srcs/savestate.c"
    click Libyacc "https://github.com/nicolasiragne/gbmu/blob/master/srcs/debugger/libyacc_wrapper.cpp"
    click Fallback "https://github.com/nicolasiragne/gbmu/blob/master/srcs/fallback_debugger.c"
    click NativeCLI "https://github.com/nicolasiragne/gbmu/blob/master/CMakeLists.txt"
    click NativeGUI "https://github.com/nicolasiragne/gbmu/blob/master/srcs/gbclodo/main.cpp"
    click FFI "https://github.com/nicolasiragne/gbmu/blob/master/crates/bindings/build.rs"
    click Shared "https://github.com/nicolasiragne/gbmu/blob/master/crates/shared/src/lib.rs"
    click RustCLI "https://github.com/nicolasiragne/gbmu/blob/master/crates/gbmu/src/main.rs"
    click RustTUI "https://github.com/nicolasiragne/gbmu/blob/master/crates/ui/src/lib.rs"

    %% Styles
    classDef core fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef debugger fill:#fddc99,stroke:#333,stroke-width:1px
    classDef native fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef rust fill:#caffbf,stroke:#333,stroke-width:1px
    classDef ext fill:#ffadad,stroke:#333,stroke-width:1px
```
