# lwagner94/riscv-emulator architecture

> Architecture diagram of the GitHub repository lwagner94/riscv-emulator, 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/lwagner94/riscv-emulator
- Repository: https://github.com/lwagner94/riscv-emulator

## Overview

##### Main Components

A. Core Emulator Components:
- CPU Core (src/cpu.rs)
- Memory Management Unit (src/memory/)
- Instruction Decoder (src/instruction.rs)
- Program Loader (src/loader.rs)
- GDB Server Interface (src/gdbserver.rs)

B. Memory-Mapped I/O Devices:
- Video Framebuffer (src/memory/video.rs)
- Debug Output Interface (src/memory/debug.rs)
- RAM Controller (src/memory/ram.rs)

C. External Interfaces:
- ELF Binary Loading System
- GDB Remote Debugging Protocol
- Program Output Devices

**[External Programs/Debug Tools] ←→ [GDB Server Interface]**
- ↓
**[Program Loader (ELF)] → [CPU Core] ←→ [Memory Management Unit]**
- ↓
- [Memory-Mapped I/O Devices]
- Framebuffer
- Debug Output
- RAM

##### Detailed Component Specifications

A. CPU Core:
- Instruction fetch/decode/execute cycle
- Register file and ALU
- Connection to memory management unit

B. Memory Management:
- Address space management (src/memory/addressspace.rs)
- Memory mapping scheme
- Different memory regions (RAM, I/O)

C. Debug Interface:
- GDB protocol handling
- Breakpoint management
- Debugging control flow

##### Implementation Details to Highlight

- The address space implementation and memory mapping scheme
- The instruction execution pipeline
- The relationship between the CPU and memory-mapped devices
- The GDB server interface and debugging capabilities
- The ELF loader's interaction with the system

**[ELF Binary] → [Loader] → [Memory Layout] → [CPU Execution] → [I/O Operations]**

- Maintain focus on the emulator's core components while showing how they interact
- Memory-mapped I/O system as it's a key feature
- Clear separation between the emulator core and debugging facilities
- Version information and supported RISC-V extensions (riscv32im)

- Hierarchical component layout
- Component grouping
- Export to high-resolution formats

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style definitions
    classDef core fill:#b3d1ff,stroke:#4d88ff
    classDef io fill:#90EE90,stroke:#228B22
    classDef external fill:#FFB366,stroke:#FF8000
    classDef memory fill:#E6E6FA,stroke:#8A2BE2
    classDef debug fill:#FFB6C1,stroke:#FF69B4

    %% External Tools
    ExtTools["External Debug Tools"]:::external
    GDB["GDB Server Interface"]:::debug
    click GDB "https://github.com/lwagner94/riscv-emulator/blob/master/src/gdbserver.rs"

    %% Core Components
    CPU["CPU Core"]:::core
    click CPU "https://github.com/lwagner94/riscv-emulator/blob/master/src/cpu.rs"
    InstDec["Instruction Decoder"]:::core
    click InstDec "https://github.com/lwagner94/riscv-emulator/blob/master/src/instruction.rs"
    Loader["Program Loader"]:::core
    click Loader "https://github.com/lwagner94/riscv-emulator/blob/master/src/loader.rs"

    %% Memory Management
    subgraph MemorySystem
        MMU["Memory Management Unit"]:::memory
        click MMU "https://github.com/lwagner94/riscv-emulator/blob/master/src/memory/mod.rs"
        AddressSpace["Address Space Manager"]:::memory
        click AddressSpace "https://github.com/lwagner94/riscv-emulator/blob/master/src/memory/addressspace.rs"
    end

    %% Memory-Mapped I/O
    subgraph IODevices
        Video["Video Framebuffer"]:::io
        click Video "https://github.com/lwagner94/riscv-emulator/blob/master/src/memory/video.rs"
        Debug["Debug Output"]:::io
        click Debug "https://github.com/lwagner94/riscv-emulator/blob/master/src/memory/debug.rs"
        RAM["RAM Controller"]:::io
        click RAM "https://github.com/lwagner94/riscv-emulator/blob/master/src/memory/ram.rs"
    end

    %% Main Entry and Error Handling
    Main["Main Entry Point"]:::core
    click Main "https://github.com/lwagner94/riscv-emulator/blob/master/src/main.rs"
    Error["Error Handler"]:::core
    click Error "https://github.com/lwagner94/riscv-emulator/blob/master/src/error.rs"

    %% Testing Components
    TestFW["Test Framework"]:::external
    click TestFW "https://github.com/lwagner94/riscv-emulator/blob/master/tests/common.rs"
    ProgTests["Program Tests"]:::external
    click ProgTests "https://github.com/lwagner94/riscv-emulator/blob/master/tests/program_tests.rs"

    %% Relationships
    ExtTools <--> GDB
    GDB --> CPU
    Loader --> CPU
    CPU <--> InstDec
    CPU <--> MMU
    MMU <--> AddressSpace
    AddressSpace --> IODevices
    Main --> CPU
    Main --> GDB
    Error -.-> CPU
    Error -.-> MMU
    TestFW --> ProgTests
    ProgTests --> Main

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["I/O Devices"]:::io
        L3["External Interfaces"]:::external
        L4["Memory Management"]:::memory
        L5["Debug Components"]:::debug
    end
```
