Overview
VirtMCU is The Matrix for Microcontrollers—a globally deterministic, lockstep simulation framework built on QEMU 11.0.0. It allows you to boot thousands of microcontrollers, wire them via virtual buses, and synchronize them with 3D physics engines like MuJoCo or NVIDIA Omniverse.
Unlike traditional emulators that suffer from wall-clock scheduling jitter, VirtMCU guarantees zero-jitter execution and bit-for-bit reproducibility across all nodes using the Zenoh federation bus. You run the exact same firmware binaries you deploy to real hardware.
Installation
1. Clone and Submodules
git clone https://github.com/RefractSystems/virtmcu.git
cd virtmcu
git submodule update --init --recursive
2. Setup Environment
The setup script applies the arm-generic-fdt patches and builds QEMU as a module-aware emulator.
make setup
make venv
source .venv/bin/activate
Architecture
VirtMCU is engineered for absolute determinism, enabling you to escape the simulation trap and eradicate ghost bugs.
Zero-Jitter Execution Engine
The core TCG loop runs decoupled from wall-clock time. Host OS preemption and thread pausing have zero impact on the simulated progression of time.
SystemC TLM-2.0 Integration
Bring your Verilated hardware and FPGA IP directly into the simulation mesh over a high-throughput, low-latency UDP data plane.
Rust-Native Extensibility
Write peripheral models in memory-safe Rust. Dynamic plugins load instantly via FFI boundaries without recompiling the QEMU core.
Cyber-Physical Boundaries
Translate virtual MMIO register writes directly into simulated physical torque, force, and acceleration within physics engines.
Usage
Launch a simulation using a Renode .repl file as the platform description:
./scripts/run.sh --repl platform.repl --kernel firmware.elf
To run in lockstep with a Zenoh time master (e.g., FirmwareStudio):
./scripts/run.sh --dtb board.dtb --kernel firmware.elf \
-device zenoh-clock,node=0,router=tcp/localhost:7447
Synchronization
VirtMCU supports three distinct clock modes to balance performance and precision:
- Standalone: Free-running TCG at maximum host speed. Used for development and CI.
- Slaved-Suspend: Cooperative halting at TB boundaries. ~95% throughput. Recommended for most FirmwareStudio workloads.
- Slaved-Icount: Exact nanosecond virtual time. Required for firmware measuring sub-quantum intervals (PWM, µs DMA).
The Masterclass Curriculum
The VirtMCU documentation is structured as a comprehensive Masterclass to take you from firmware basics to advanced distributed systems.
Part I: Fundamentals
Deep dive into SoC Anatomy, MMIO, QEMU Architecture, the Object Model (QOM), and Parallel Discrete Event Simulation (PDES).
Part IV: Practical Mastery
Interactive lessons on Dynamic Machines, Rust Migration, and parsing .repl to Device Trees (DTB).
Part V: Distributed Systems
Master the Zenoh Clock, Co-Simulation, SystemC CAN bus integration, and Interactive UART across nodes.
Part VIII: War Stories
Real-world debugging postmortems, including the FlexRay SIGSEGV, CI ASan Failures, and QEMU Plugin Visibility.
FAQ
How should I approach learning the system?
Follow the Masterclass Curriculum in order. Start with Part I to build fundamental intuition before writing code in Part IV.
Why no Python in the simulation loop?
Python's GIL and garbage collector introduce milliseconds of latency. We write native Rust plugins or C (.so) files that achieve near-native performance for MMIO.
Why Zenoh instead of standard UDP sockets?
Standard sockets ruin determinism because the host OS network stack introduces random latency. Zenoh provides virtual-timestamped delivery across nodes, guaranteeing exact causal ordering.