# cnlohr/mini-rv32ima architecture

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

- Interactive diagram: https://gitdiagram.com/cnlohr/mini-rv32ima
- Repository: https://github.com/cnlohr/mini-rv32ima

## Overview

##### Project Type and Purpose
- Project type: A lightweight, embeddable RISC‑V rv32ima emulator library plus a demo CLI, integration with Buildroot Linux, bare‑metal examples, and experiments (e.g., running Doom, profiling).
- Core purpose: Provide a single‐file C emulator (`mini‑rv32ima.h`) and a demo wrapper (`mini‑rv32ima.c`) to run Linux userspace or flat binaries on an RV32 “no‑MMU” platform.

##### File Structure
Top‑level components:
- `mini‑rv32ima/`
- `mini‑rv32ima.h` – emulator core (fetch/decode/execute, CLINT, MMIO stubs)
- `mini‑rv32ima.c` – CLI loader, UART, DTB & kernel‐image loader
- `Makefile` (root) – orchestrates targets: `testdlimage`, `testbare`, `testdoom`, `everything`
- `baremetal/` – minimal flat‑binary demo (no image loader)
- `cachetest/` – microbenchmark of memory/cache handling via emulator macros
- `configs/` – Buildroot, BusyBox, custom kernel, Device‑Tree overlays
- `experiments/` – examples that plug into the emulator (e.g., Emdoom, profiling structure)
- `packages/` – auxiliary code: CoreMark, JS FizzBuzz, OpenSBI platform stubs
- `windows/` – PowerShell scripts for Windows setup and doom demo

##### README Insights
- Emulator design: single-header, no libc dependency, supports rv32ima+Zicsr, partial su, stubs for CLINT and fences.
- Demo: CLI wrapper loads a Linux image (via Buildroot), simulates console I/O.
- Build process:
– Linux: `make testdlimage` (downloads ~1 MB image & runs)
– Bare‑metal: `make testbare`
– Doom demo: `make testdoom` or Windows scripts.

##### Main Components and Their Interactions
a. Emulator Core (mini‑rv32ima.h)
- Instruction fetch → decode → execute
- Memory model: RAM array + MMIO handlers (CSRs, CLINT, UART)
b. Demo Wrapper (mini‑rv32ima.c)
- CLI & argument parsing
- Loads DTB + kernel ELF (via flat‑binary loader)
- Hooks `MINIRV32_HANDLE_MEM_*` macros to simulate consoles, control registers
c. Build System
- Root `Makefile` invokes cross‑compilation (TCC or GCC), Buildroot configuration, image creation, and emulator run scripts
- `configs/` supply defconfigs for Buildroot, BusyBox, kernel, and DT overlays
d. Experiments & Benchmarks
- `experiments/emdoom` – links Doom binary into emulator image, demonstrates graphics output via simulated video console
- `cachetest/` – measures emulator memory/cache performance
e. Bare‑Metal Flat Binary
- `baremetal/` folder demonstrates running a simple C/assembly program without Linux or DT

##### Architectural Patterns and Design Principles
- Single‑file library (STB‑style embed) + extensible macro hooks → pluggable MMIO/CSR.
- Clear separation of concerns:
– **Core library** for instruction emulation
– **Wrapper** for environment setup & I/O
– **Configs** for OS image builds
– **Experiments** for feature demos
- Makefile as orchestrator, supports multiple targets (Linux, bare‑metal, experiments).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Emulator Internals"
    CoreLib["Emulator Core (mini‑rv32ima.h)"]:::emulatorInternals
    DemoWrapper["Demo CLI Loader (mini‑rv32ima.c)"]:::emulatorInternals
  end

  subgraph "Build & Config"
    RootMakefile["Root Makefile"]:::build
    CoreMakefile["Core Library Makefile"]:::build
    BuildConfigs["Buildroot & OS Configs"]:::build
  end

  subgraph "Demos & Experiments"
    CacheTest["Cachetest Benchmark"]:::demo
    DoomExp["Doom Experiment (Emdoom)"]:::demo
    ProfilingExp["Profiling Experiment"]:::demo
    HelloLinux["Hello Linux Example"]:::demo
  end

  subgraph "Packages"
    CoreMarkPkg["CoreMark Package"]:::demo
    FizzBuzzPkg["JavaScript FizzBuzz"]:::demo
    OpenSBIPkg["OpenSBI Platform Stubs"]:::demo
  end

  subgraph "Platform Scripts & Bare-Metal"
    BareMetal["Bare‑Metal Demo"]:::platform
    WindowsScripts["Windows Scripts"]:::platform
  end

  DemoWrapper -->|"calls fetch/decode/execute"| CoreLib
  DemoWrapper -->|"loads kernel ELF from"| BuildConfigs
  BareMetal -->|"bypasses loader to"| CoreLib

  RootMakefile -->|"builds core library"| CoreMakefile
  RootMakefile -->|"orchestrates build & run CLI"| DemoWrapper
  RootMakefile -->|"triggers bare-metal demo"| BareMetal
  RootMakefile -->|"runs cache benchmark"| CacheTest
  RootMakefile -->|"runs Doom experiment"| DoomExp
  RootMakefile -->|"runs profiling experiment"| ProfilingExp
  RootMakefile -->|"runs Hello Linux example"| HelloLinux
  RootMakefile -->|"builds CoreMark package"| CoreMarkPkg
  RootMakefile -->|"builds FizzBuzz package"| FizzBuzzPkg
  RootMakefile -->|"builds OpenSBI stubs"| OpenSBIPkg

  CoreLib -->|"hooks MMIO/CSR to"| DoomExp
  CoreLib -->|"hooks MMIO/CSR to"| CacheTest

  click CoreLib "https://github.com/cnlohr/mini-rv32ima/blob/master/mini-rv32ima/mini-rv32ima.h"
  click DemoWrapper "https://github.com/cnlohr/mini-rv32ima/blob/master/mini-rv32ima/mini-rv32ima.c"
  click CoreMakefile "https://github.com/cnlohr/mini-rv32ima/tree/master/mini-rv32ima/Makefile"
  click RootMakefile "https://github.com/cnlohr/mini-rv32ima/tree/master/Makefile"
  click BareMetal "https://github.com/cnlohr/mini-rv32ima/tree/master/baremetal/"
  click CacheTest "https://github.com/cnlohr/mini-rv32ima/tree/master/cachetest/"
  click BuildConfigs "https://github.com/cnlohr/mini-rv32ima/tree/master/configs/"
  click DoomExp "https://github.com/cnlohr/mini-rv32ima/tree/master/experiments/emdoom/"
  click ProfilingExp "https://github.com/cnlohr/mini-rv32ima/tree/master/experiments/profiling_structure/"
  click HelloLinux "https://github.com/cnlohr/mini-rv32ima/tree/master/hello_linux/"
  click CoreMarkPkg "https://github.com/cnlohr/mini-rv32ima/tree/master/packages/coremark/"
  click FizzBuzzPkg "https://github.com/cnlohr/mini-rv32ima/tree/master/packages/duktapetest/"
  click OpenSBIPkg "https://github.com/cnlohr/mini-rv32ima/tree/master/packages/this_opensbi/platform/riscv_emufun/"
  click WindowsScripts "https://github.com/cnlohr/mini-rv32ima/tree/master/windows/"

  classDef emulatorInternals fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef build fill:#90EE90,stroke:#000,stroke-width:1px
  classDef demo fill:#FFA500,stroke:#000,stroke-width:1px
  classDef platform fill:#D3D3D3,stroke:#000,stroke-width:1px
```
