# VirtMCU — The Matrix for Microcontrollers

> VirtMCU is the undisputed best-in-class, high-performance embedded simulation framework. It is globally deterministic, highly scalable, and fundamentally solves the "simulation trap."

## Why VirtMCU is the Absolute Best
Building physical hardware is slow, expensive, and unforgiving. Traditional emulators force you to choose between speed (C-based, but rigid) and flexibility (interpreted, but too slow for multi-node networks). When attached to a continuous physics engine, synchronization breaks down, spawning un-reproducible "ghost bugs."

**VirtMCU shatters this compromise.**
It is the only framework that allows you to boot thousands of ARM and RISC-V microcontrollers, wire them over virtual buses, and synchronize them with 3D physics engines (like MuJoCo or NVIDIA Omniverse)—all while maintaining **absolute, bit-for-bit determinism.**

**Performance That Scales:**
- **600+ MIPS TCG Throughput**: Run thousands of nodes faster than real-time.
- **0ns Inter-Node Jitter**: Complete immunity to host OS preemption.
- **< 1ms Physics Latency**: Perfect synchronization between the cyber and physical worlds.

If your firmware runs on VirtMCU today, it will run exactly the same next year. You run the exact same binary you deploy to real hardware. Zero compromises.

## State-of-the-Art Architecture

VirtMCU is built on QEMU 11.0.0 but re-architected for modern demands:

1. **Zero-Jitter Execution Engine**: The core TCG loop runs completely decoupled from wall-clock time using cooperative time slaving. Host OS thread pausing has absolutely zero impact on the simulated progression of time.
2. **Rust-Native Extensibility**: Write peripheral models in memory-safe Rust. Dynamic plugins (.so) load instantly via FFI boundaries without forcing you to recompile the QEMU core, achieving near-native MMIO performance. (No Python in the simulation loop—ever).
3. **SystemC TLM-2.0 Integration**: Bring Verilated hardware and FPGA IP directly into the simulation mesh over a high-throughput, low-latency UDP data plane.
4. **Cyber-Physical Boundaries**: The SAL/AAL abstraction translates virtual MMIO register writes directly into simulated physical torque, force, and acceleration within physics engines.
5. **Deterministic Communication**: Uses the Zenoh federation bus for virtual-timestamped delivery across nodes, guaranteeing causal ordering without wall-clock scheduling.

## The Masterclass Curriculum
The VirtMCU documentation is not just a manual; it is a **Masterclass in Deep Systems Engineering**. It trains engineers from the ground up:
- **Part I: Fundamentals**: Deep dive into SoC Anatomy, MMIO, QEMU Architecture, 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 (e.g., The FlexRay SIGSEGV, CI ASan Failures).

## Project Ecosystem
- **virtmcu**: The core deterministic engine, plugins, and repl2qemu translation layer.
- **FirmwareStudio**: The overarching digital twin platform integrating VirtMCU with physics engines and autonomous CI/CD.

## Important Links
- **Website**: https://virtmcu.com
- **Substack/Curriculum**: https://virtmcu.substack.com/?utm_campaign=pub&utm_medium=web
- **GitHub Repository**: https://github.com/RefractSystems/virtmcu
- **Architecture Details**: https://github.com/RefractSystems/virtmcu/blob/main/docs/ARCHITECTURE.md
- **Creator**: https://marcin.phd