# lekkit/rvvm architecture

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

- Interactive diagram: https://gitdiagram.com/lekkit/rvvm
- Repository: https://github.com/lekkit/rvvm

## Overview

##### Main Components

a. Core Emulation Layer:
- CPU Emulation (src/cpu/)
- RISC-V Interpreter (32/64-bit)
- JIT Compilation System (src/rvjit/)
- MMU Implementation
- CSR Handling

b. Device Emulation Layer:
- Storage Devices
- NVMe Controller
- ATA Controller
- Network Devices
- RTL8169
- OpenCores Ethernet
- Input/Output Devices
- Framebuffer
- HID Devices (Keyboard/Mouse)
- UART/Serial
- GPIO
- System Devices
- PLIC (Platform-Level Interrupt Controller)
- CLINT (Core Local Interruptor)
- PCI Bus Controller

c. Platform Abstraction:
- Multiple GUI Backend Support
- SDL
- X11
- Win32
- Haiku
- Network Stack
- TAP Interfaces
- Port Forwarding
- Host System Integration
- VFIO Support
- Isolation Layer

d. External Interfaces:
- JNI Bindings
- LibRetro Bindings
- Library API (librvvm)

##### Relationship Flows to Illustrate

a. Guest-Host Interaction:
**Host OS → Isolation Layer → RVVM Core → Guest System**

b. Device Emulation Flow:
**Guest Access → MMU → Device Controllers → Host Drivers**

c. CPU Execution Pipeline:
**Instruction Fetch → Decoder → JIT/Interpreter → Execution**

##### Implementation Details

- Thread management for SMP
- Memory mapping and management
- Device interrupt routing
- JIT backend selection paths

**┌─ External API Layer ─────────────────────┐**
- (JNI, LibRetro, Public API)             │
- Platform Abstraction Layer ─────────────┤
- (GUI, Network, Host Integration)         │
- Device Emulation Layer ─────────────────┤
- (Storage, Network, I/O, System Devices)  │
- Core Emulation Layer ──────────────────┤
- (CPU, MMU, JIT, Interrupts)             │
- ┘

- Core components (Red)
- Device emulation (Blue)
- Host interfaces (Green)
- External APIs (Yellow)

- Component types
- Connection types
- Security boundaries
- Performance-critical paths
- Configuration options

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef core fill:#ffcccc,stroke:#ff0000
    classDef device fill:#cce5ff,stroke:#0066cc
    classDef platform fill:#ccffcc,stroke:#009900
    classDef external fill:#ffffcc,stroke:#cccc00
    classDef security stroke:#000000,stroke-dasharray: 5 5

    %% Core Emulation Layer
    subgraph CoreLayer["Core Emulation Layer"]
        CPU["CPU Emulation"]
        JIT["JIT Compilation"]
        MMU["MMU Implementation"]
        CSR["CSR Handling"]
    end

    %% Device Emulation Layer
    subgraph DeviceLayer["Device Emulation Layer"]
        subgraph Storage["Storage Devices"]
            NVME["NVMe Controller"]
            ATA["ATA Controller"]
        end
        
        subgraph Network["Network Devices"]
            RTL["RTL8169"]
            ETH["OpenCores Ethernet"]
        end
        
        subgraph IO["I/O Devices"]
            FB["Framebuffer"]
            UART["UART/Serial"]
        end
        
        subgraph System["System Devices"]
            PLIC["PLIC Controller"]
            CLINT["CLINT"]
        end
    end

    %% Platform Abstraction Layer
    subgraph PlatformLayer["Platform Abstraction Layer"]
        subgraph GUI["GUI Backend"]
            SDL["SDL"]
            X11["X11"]
            WIN["Win32"]
            HAIKU["Haiku"]
        end
        
        subgraph NetStack["Network Stack"]
            TAP["TAP Interface"]
            VFIO["VFIO Support"]
        end
        
        ISO["Isolation Layer"]
    end

    %% External API Layer
    subgraph APILayer["External API Layer"]
        JNI["JNI Bindings"]
        RETRO["LibRetro Bindings"]
        API["Library API"]
    end

    %% Relationships
    CPU --> MMU
    MMU --> CSR
    CPU --> JIT
    MMU --> Storage
    MMU --> Network
    MMU --> IO
    MMU --> System
    ISO --> CoreLayer
    GUI --> FB
    NetStack --> Network
    CoreLayer --> DeviceLayer
    DeviceLayer --> PlatformLayer
    PlatformLayer --> APILayer

    %% Click events
    click CPU "https://github.com/LekKit/RVVM/tree/staging/src/cpu/"
    click JIT "https://github.com/LekKit/RVVM/tree/staging/src/rvjit/"
    click MMU "https://github.com/LekKit/RVVM/blob/staging/src/riscv_mmu.h"
    click CSR "https://github.com/LekKit/RVVM/blob/staging/src/riscv_csr.h"
    click NVME "https://github.com/LekKit/RVVM/blob/staging/src/devices/nvme.h"
    click ATA "https://github.com/LekKit/RVVM/blob/staging/src/devices/ata.h"
    click RTL "https://github.com/LekKit/RVVM/blob/staging/src/devices/rtl8169.h"
    click ETH "https://github.com/LekKit/RVVM/blob/staging/src/devices/eth-oc.h"
    click FB "https://github.com/LekKit/RVVM/blob/staging/src/devices/framebuffer.h"
    click UART "https://github.com/LekKit/RVVM/blob/staging/src/devices/ns16550a.h"
    click PLIC "https://github.com/LekKit/RVVM/blob/staging/src/devices/plic.h"
    click CLINT "https://github.com/LekKit/RVVM/blob/staging/src/devices/clint.h"
    click SDL "https://github.com/LekKit/RVVM/blob/staging/src/devices/sdl_window.c"
    click X11 "https://github.com/LekKit/RVVM/blob/staging/src/devices/x11window_xlib.c"
    click WIN "https://github.com/LekKit/RVVM/blob/staging/src/devices/win32window.c"
    click HAIKU "https://github.com/LekKit/RVVM/blob/staging/src/devices/haiku_window.cpp"
    click TAP "https://github.com/LekKit/RVVM/blob/staging/src/devices/tap_linux.c"
    click JNI "https://github.com/LekKit/RVVM/tree/staging/src/bindings/jni/"
    click RETRO "https://github.com/LekKit/RVVM/tree/staging/src/bindings/libretro/"
    click API "https://github.com/LekKit/RVVM/blob/staging/src/rvvmlib.h"
    click VFIO "https://github.com/LekKit/RVVM/blob/staging/src/devices/pci-vfio.h"
    click ISO "https://github.com/LekKit/RVVM/blob/staging/src/rvvm_isolation.h"

    %% Style applications
    class CPU,JIT,MMU,CSR core
    class NVME,ATA,RTL,ETH,FB,UART,PLIC,CLINT device
    class SDL,X11,WIN,HAIKU,TAP,VFIO,ISO platform
    class JNI,RETRO,API external
```
