How cnlohr/mini-rv32ima works
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).