Lib.rs

› Emulators
#emulation #risc-v #entry-point #qemu #artificial-intelligence #clippy #ai-agents #full-system #machina

app machina-emu

CLI entry point for the Machina RISC-V full-system emulator

Owned by zevorn.

3 releases

new 0.1.2 Apr 3, 2026
0.1.1 Apr 2, 2026
0.1.0 Apr 2, 2026

#10 in Emulators

MIT license

2MB
16K SLoC

Rust 14K SLoC // 0.1% comments Python 2K SLoC // 0.1% comments Shell 229 SLoC // 0.1% comments

Machina (/ˈmɑːkɪnə/)

English | 中文

A modular RISC-V full-system emulator written in Rust, featuring a JIT dynamic binary translation engine.

An AI-agent collaborative development case study — this project is primarily developed through collaboration between human developers and AI agents (Claude, Codex), serving as an educational example of AI-assisted systems programming.

Overview

Machina is a Rust reimplementation of core QEMU concepts — TCG (Tiny Code Generator), device models, and full-system emulation — designed to boot and run rCore-Tutorial chapters 1–8 on a RISC-V virtual machine.

What It Can Do

  • JIT binary translation: RISC-V → x86-64 with TB caching, chaining, and optimization
  • Full-system emulation: PLIC, ACLINT, UART, Sv39 MMU, SBI firmware
  • VirtIO block device: mmap'd raw disk images for file system chapters
  • Monitor console: QMP-compatible JSON protocol + HMP text commands
  • Difftest: Instruction-level comparison against QEMU via GDB RSP
  • 1039 tests, zero failures

rCore-Tutorial Support

Chapter Feature Status
ch1 Hello World ✅ Pass
ch2 Batch Processing ✅ Pass
ch3 Multitasking + Timer ✅ Pass
ch4 Sv39 Virtual Memory ✅ Pass
ch5 Process Management ✅ Pass (shell)
ch6 File System (VirtIO) ✅ Pass (shell)
ch7 IPC & Signals ✅ Pass (shell)
ch8 Concurrency ✅ Pass (shell)

Quick Start

Build

git clone https://github.com/gevico/machina.git
cd machina
cargo build --release

Run rCore-Tutorial

# Ch1-Ch5: bare-metal kernel (no disk needed)
./target/release/machina -nographic -bios none -kernel path/to/ch5.elf

# Ch6-Ch8: with VirtIO block device
./target/release/machina -nographic \
  -drive file=path/to/fs.img \
  -kernel path/to/ch6.elf

# With monitor console (QMP over TCP)
./target/release/machina -nographic \
  -monitor tcp:127.0.0.1:4444 \
  -bios none -kernel path/to/ch5.elf

# Instruction-level difftest against QEMU
./target/release/machina --difftest \
  -bios none -kernel path/to/ch1.elf

Keyboard Shortcuts (-nographic)

Key Action
Ctrl+A, X Exit emulator
Ctrl+A, C Toggle monitor console
Ctrl+A, H Show help

Workspace

Crate Description
machina CLI entry point
machina-core IR definitions, CPU trait, monitor state
machina-accel Optimizer, register allocator, x86-64 codegen, execution engine
machina-guest-riscv RISC-V frontend: RV64GC + privileged ISA (188 instructions), Sv39 MMU
machina-decode .decode file parser and Rust decoder generator
machina-system Full-system CPU bridge, CpuManager, WFI
machina-memory AddressSpace, memory regions, MMIO dispatch
machina-hw-core Device infrastructure: IRQ, chardev, FDT
machina-hw-intc PLIC, ACLINT (MTIMER + MSWI)
machina-hw-char UART 16550A
machina-hw-riscv Reference machine (riscv64-ref), boot, SBI
machina-hw-virtio VirtIO MMIO transport + block device
machina-monitor MMP (QMP-compatible) + HMP monitor console
machina-difftest GDB RSP client for differential testing
machina-tests 1039 tests

Contributing

Machina is an AI-agent collaborative development project. Contributions are welcome from both humans and AI agents.

How to Contribute

  1. Open an Issue first — describe the bug, feature, or improvement
  2. Fork the repository — create your own copy
  3. Create a branch — git checkout -b feature/your-feature
  4. Make changes — follow the coding style (80-column, cargo fmt, cargo clippy)
  5. Test — cargo test --workspace must pass
  6. Submit a Pull Request — reference the issue number

Coding Style

  • 80-column line width
  • cargo fmt for formatting
  • cargo clippy -- -D warnings for zero warnings
  • English comments, only at key logic points
  • Commit messages: module: subject format

AI Agent Workflow

This project uses Humanize for structured AI development:

  • RLCR Loop: Round → Loop → Codex Review — iterative development with automated code review
  • BitLesson: Persistent knowledge base capturing debugging insights across sessions
  • Plan-driven: Design specs → implementation plans → RLCR execution

References

Project Description Link
QEMU Reference implementation https://github.com/qemu/qemu
rCore-Tutorial-v3 Target OS tutorial https://github.com/rcore-os/rCore-Tutorial-v3
tg-rcore-tutorial Componentized tutorial series https://github.com/rcore-os
rust-vmm Rust virtualization components https://github.com/rust-vmm

License

MIT

Dependencies