# peberlein/bulwip architecture

> Architecture diagram of the GitHub repository peberlein/bulwip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peberlein/bulwip
- Repository: https://github.com/peberlein/bulwip

## Overview

Main Components to Include:

##### Core Emulation Layer
- CPU Emulator (represented by cpu.c/cpu.h)
- GPU Emulator (gpu.c)
- Sound Chip Emulator (part of the system emulation)
- Memory Management System

##### Input/Output Layer
- SDL2 Interface (sdl.c)
- User Interface (ui.c)
- Input Handler (keyboard mappings)

##### Storage Components
- ROM/GROM Loader
- Cartridge Management System
- SAMS Banking (1MB)

##### Debug Infrastructure
- Debugger Interface
- Breakpoint Management
- Memory Viewers
- Listing Parser

##### Use a Layered Architecture Approach
- Blue: Core Emulation Components
- Green: I/O Systems
- Yellow: Storage Systems
- Red: Debug Infrastructure

##### Specific Implementation Details
- CLZ-based opcode decoding system
- Memory access function pointer system (per 256 bytes)
- 16-bit word memory architecture
- NTSC-CRT subsystem (from the NTSC-CRT directory)

- Component name
- Key responsibilities
- Interface points
- Important optimizations (like instruction loop design)

##### External Dependencies
- SDL2 library
- ROM/GROM file requirements
- Cartridge file formats

**[User Interface Layer]**
- ↑↓
**[Input/Output Layer]**
- ↑↓
**[Core Emulation Layer]**
- ↑↓
**[Storage Layer]**

Special Considerations:

##### Performance Optimizations
- How the instruction loop is contained in a single function
- Register usage optimization
- Memory access optimization strategy

##### Debug Integration
- How the debugger interfaces with all layers
- Breakpoint system integration
- Memory viewing pathways

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef core fill:#dae8fc,stroke:#6c8ebf
    classDef io fill:#d5e8d4,stroke:#82b366
    classDef storage fill:#fff2cc,stroke:#d6b656
    classDef debug fill:#f8cecc,stroke:#b85450
    classDef external fill:#e1d5e7,stroke:#9673a6

    %% User Interface Layer
    subgraph UI
        UserInterface["User Interface"]
        InputHandler["Input Handler"]
        DebugUI["Debug Interface"]
    end

    %% I/O Layer
    subgraph IO
        SDL["SDL2 Interface"]
        NTSC["NTSC-CRT System"]
    end

    %% Core Emulation Layer
    subgraph Core
        CPU["CPU Emulator"]
        GPU["GPU Emulator"]
        SoundChip["Sound Chip (9919)"]
        MemoryMgmt["Memory Management"]
    end

    %% Storage Layer
    subgraph Storage
        ROMLoader["ROM/GROM Loader"]
        CartridgeMgmt["Cartridge Management"]
        SAMSBanking["SAMS Banking (1MB)"]
    end

    %% Debug Infrastructure
    subgraph Debug
        Debugger["Debugger"]
        Breakpoints["Breakpoint Manager"]
        MemoryViewer["Memory Viewer"]
        ListingParser["Listing Parser"]
    end

    %% Relationships
    UserInterface --> SDL
    InputHandler --> SDL
    SDL --> NTSC
    NTSC --> GPU
    GPU --> CPU
    CPU --> MemoryMgmt
    MemoryMgmt --> SAMSBanking
    MemoryMgmt --> ROMLoader
    MemoryMgmt --> CartridgeMgmt
    CPU --> SoundChip
    Debugger --> CPU
    Debugger --> MemoryMgmt
    DebugUI --> Debugger
    Breakpoints --> CPU
    MemoryViewer --> MemoryMgmt
    ListingParser --> Debugger

    %% Component Classes
    class CPU,GPU,SoundChip,MemoryMgmt core
    class SDL,NTSC,InputHandler io
    class ROMLoader,CartridgeMgmt,SAMSBanking storage
    class Debugger,Breakpoints,MemoryViewer,ListingParser debug
    class UserInterface,DebugUI io

    %% Click Events
    click CPU "https://github.com/peberlein/bulwip/blob/main/cpu.c"
    click GPU "https://github.com/peberlein/bulwip/blob/main/gpu.c"
    click SDL "https://github.com/peberlein/bulwip/blob/main/sdl.c"
    click UserInterface "https://github.com/peberlein/bulwip/blob/main/ui.c"
    click NTSC "https://github.com/peberlein/bulwip/blob/main/NTSC-CRT/crt.c"

    %% Legend
    subgraph Legend
        CoreL["Core Emulation"]:::core
        IOL["I/O Systems"]:::io
        StorageL["Storage Systems"]:::storage
        DebugL["Debug Infrastructure"]:::debug
    end
```
