minirvEMU

A lightweight RISC-V (RV32E) instruction set emulator written in Rust. This project provides a complete reference implementation for the minimal RISC-V ISA subset, featuring full instruction execution, memory simulation, and comprehensive logging capabilities.

About miniRV ISA

The miniRV ISA is a minimal subset of RISC-V designed for educational purposes and lightweight implementations:

• Registers: 16 general-purpose registers (GPR[0-15]) - same as RV32E standard
• Memory: 16MB of simulated memory with bounds checking
• Initial State: Program counter (PC) starts at 0x0
• Instruction Set (8 total):
  • Arithmetic: add, addi (addition with immediate)
  • Memory: lw, lbu (load word/byte unsigned)
  • Store: sw, sb (store word/byte)
  • Control: jalr (jump and link register)
  • Load Upper: lui (load upper immediate)
• ISA Compliance: Follows RV32I specification for other details

Features

• Full minirv-CPU Emulation: Complete RV32E subset instruction set (minirv ISA) implementation
• Memory Management:
  • 16MB simulated memory with proper bounds checking
  • Little-endian byte order support
  • Early detection of out-of-bounds access
• Instruction Processing:
  • Efficient instruction decoding and execution
  • Proper handling of sign extension and bit manipulation via optimized macros
  • Support for all 8 core miniRV instructions
• Comprehensive Logging:
  • inst.log: Full instruction trace with execution details
  • pc.log: Program counter progression
  • gpr.log: Register state snapshots after each instruction
• Robust Error Handling:
  • Memory access violations detection
  • Unsupported instruction detection
  • Clear error messages for debugging

Project Structure

.
├── src/
│   ├── main.rs          # Entry point and I/O handling
│   ├── cpu.rs           # CPU emulation core
│   └── macros.rs        # Optimized bit manipulation utilities
├── Cargo.toml           # Rust manifest
├── LICENSE              # License information
└── README.md            # This file

Building

Prerequisites

• Rust 1.70 or later
• Cargo

Debug Build

cargo build

Output: target/debug/emu

Release Build (Optimized)

cargo build --release

Output: target/release/emu

Usage

Basic Execution

./target/release/emu <path_to_binary_image>

Example

./target/release/emu program.bin

Output Files

After execution, the following log files are generated in the current directory:

• inst.log: Instruction execution trace showing:
  • Instruction address (PC)
  • Raw instruction bytes
  • Decoded instruction details
  • Register and memory changes
• pc.log: Program counter values logged at each step
• gpr.log: General-purpose register states after instruction execution
  • Shows all 16 register values (GPR[0-15])
  • GPR[0] (x0) is always kept at 0 per RISC-V spec

Implementation Details

Macro-Based Optimization

The emulator uses efficient macros for bit manipulation:

• bit_mask!: Extract arbitrary bit ranges from instructions
• sign_extend!: Perform arithmetic sign extension for immediates

These macros are defined in src/macros.rs and imported via #[macro_use].

License

MIT License - See LICENSE file for details