Getting Started
Prerequisites
- One of the supported evaluation boards: STM32G071RBT6 (Cortex-M0+), STM32F429ZIT6 (Cortex-M4), STM32H743ZIT6 (Cortex-M7) or CH32V307VCT6 (RV32IMAC).
- A supported toolchain: Keil uVision 5 (armcc), IAR EWARM, or GCC/Clang-LLVM. Other toolchains are neither recommended nor supported at this point.
- The RME Concord microkernel (M7M1) — RVM builds on it.
Repository layout
The project generator (rvgen) locates the repositories by relative path, so keep them as siblings under one root:
<root>/
├─ M7M02_Ammonite/ the RVM hypervisor side (Monitor, Platform, Guest/)
├─ M7M01_Eukaron/ the RME microkernel RVM builds on
├─ M5P01_Prokaron/ the RMP RTOS (ships its own RVM platform layers)
├─ FreeRTOS_V900/ guest OS trees — the port sources live here
├─ uCOSII_V293/
├─ uCOSIII_V308/
├─ RTThread_V411/
├─ DjyOS_V110/
├─ KLite_V521/
├─ RTEMS_V701/ RTEMS 7.0-rc1 BSP/spec/sample overlay
└─ Zephyr_V370/ Zephyr 3.7.0 LTS west-workspace overlayVendor BSP packages live in the M0P0_Library repository.
Generate a project
All guests are driven by the RVM project generator rvgen from the Project/ directory of M7M02_Ammonite. The .rvp project file selects the chip, platform and guest type:
<Guest_Type> | Guest |
|---|---|
RMP | RMP |
FRT | FreeRTOS |
UO2 | uC/OS-II |
UO3 | uC/OS-III |
RTT | RT-Thread |
RTE | RTEMS 7.0-rc1 (ARMv7-M + GCC) |
ZPR | Zephyr 3.7.0 LTS (ARMv7-M + GCC) |
DJY | DjyOS (commemorative) |
KLT | KLite (commemorative) |
RTEMS and Zephyr need their official build environments first (arm-rtems7-gcc and an RTEMS tree; west, CMake/Ninja and a Zephyr 3.7.0 LTS west workspace). Apply the RTEMS_V701 / Zephyr_V370 overlay only after the native build is green; see GUEST.md.
Two entry scripts exist:
benchmark.sh— generates the standard benchmark image (the one behind the benchmark tables).generate.sh— runs the same generator without the benchmark option; the guest boots the plain application in<guest>_main.c, which is copied into the workspace asmain.c(with the idle-parking hook). Both scripts must be given the same source roots.
The generator emits the build system (GCC Makefile / Keil / IAR project) with the correct include order, copying all needed port files into the generated workspace.
Windows users
Copy the binary-to-C converter (bincopy.exe) next to your compiler — for Keil uVision 5:
Keil\ARM\ARMCC\bin\bincopy.exeFor Eclipse-GCC, copy it into the GCC installation folder.
Build and run
- Open the generated project with your toolchain (or run
makefor the GCC Makefile flavor) and build it. - Flash the image to the board. The examples use only the serial port, which is already configured for you.
- Start step-by-step debugging, or let it run and watch the serial console — the benchmark prints its results there (e.g.
PASS: 0 faults, 9 items).
Integrating a guest manually
The Guest/ library contains only the added files — it never overwrites official kernel sources, so a plain overlay is safe:
- Copy the guest's directory (e.g.
FreeRTOS_V900/) over the root of your official tree of the same version (merge directories). - The RVM port directories land beside the official ones, exactly like additional official ports (e.g.
portable/GCC/ARM_A7M_RVM/). - Configure the port switches if the guest has any (see Guest Support).
Never edit the mirror
M7M02_Ammonite/Guest/ is a mirror produced by update-maintainer-only.sh. Edit the source trees (e.g. RTThread_V411/), then re-run the script from the Guest/ directory.
Hypercalls
RVM employs paravirtualization to minimize time and memory overhead. It provides hypercalls for the sensitive privileged operations a guest needs: console output, virtual interrupt control, vector mapping, event channels, sleep and watchdog management.
| Hypercall | Number | Description |
|---|---|---|
| RVM_HYP_SPURIOUS | 0 | Spurious hypercall, ignored (the timer interrupt arrived before the request) |
| RVM_HYP_PUTCHAR | 1 | Print one character to the console |
| RVM_HYP_REBOOT | 2 | Reboot the current virtual machine |
| RVM_HYP_INT_ENA | 3 | Enable virtual machine interrupts |
| RVM_HYP_INT_DIS | 4 | Disable virtual machine interrupts |
| RVM_HYP_VCT_PHYS | 5 | Map a virtual vector of the virtual machine to a physical vector |
| RVM_HYP_VCT_EVT | 6 | Map a virtual vector of the virtual machine to an event channel |
| RVM_HYP_VCT_DEL | 7 | Delete a virtual vector mapping |
| RVM_HYP_VCT_LCK | 8 | Lockdown the virtual vector mappings of the virtual machine |
| RVM_HYP_VCT_WAIT | 9 | Sleep the virtual machine until a vector comes in |
| RVM_HYP_EVT_ADD | 10 | Add the send capability of an event source to the virtual machine |
| RVM_HYP_EVT_DEL | 11 | Delete the send capability of an event source from the virtual machine |
| RVM_HYP_EVT_SND | 12 | Send an event to an event channel |
| RVM_HYP_WDG_CLR | 13 | Start and feed the watchdog |
Notes
- Virtual vs. physical masking.
CPSID/BASEPRIonly mask physical interrupts and have no effect on virtual delivery. Guests must useRVM_HYP_INT_ENA/RVM_HYP_INT_DIS(or their C wrappersRVM_Virt_Int_Unmask()/RVM_Virt_Int_Mask()) to control virtual interrupt delivery. - Idle parking. The user manual (§4.4.3) requires a guest's idle thread to call
RVM_HYP_VCT_WAIT(hypercall 9) repeatedly: it suspends the user thread and removes it from the run queue until the next virtual interrupt, stopping an idle guest from spinning the core. The hook is transparent — it resumes at the call site, changes no kernel state, and never blocks in the RTOS sense. Each guest wires it through its own official idle hook (vApplicationIdleHook,OS_AppIdleTaskHookPtr,rt_thread_idle_sethook,djy_set_idle_hook,klt_set_idle_hook). - Event channels. Hypercalls 5/6/10/11/12 build the inter-VM communication mechanism: virtual vectors map to event channels, and send capabilities are granted per virtual machine — see the user manual for the communication design.
Going further
- The full user manual covers every configuration option in depth. For production deployments, prefer the default configuration files — the kernel has too many details to configure safely by hand.
- The hypercall section below lists all privileged operations a guest can request.
- Port contracts and implementation strategies per guest: GUEST.md.
