Skip to content

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 overlay

Vendor 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
RMPRMP
FRTFreeRTOS
UO2uC/OS-II
UO3uC/OS-III
RTTRT-Thread
RTERTEMS 7.0-rc1 (ARMv7-M + GCC)
ZPRZephyr 3.7.0 LTS (ARMv7-M + GCC)
DJYDjyOS (commemorative)
KLTKLite (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 as main.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.exe

For Eclipse-GCC, copy it into the GCC installation folder.

Build and run ​

  1. Open the generated project with your toolchain (or run make for the GCC Makefile flavor) and build it.
  2. Flash the image to the board. The examples use only the serial port, which is already configured for you.
  3. 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:

  1. Copy the guest's directory (e.g. FreeRTOS_V900/) over the root of your official tree of the same version (merge directories).
  2. The RVM port directories land beside the official ones, exactly like additional official ports (e.g. portable/GCC/ARM_A7M_RVM/).
  3. 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.

HypercallNumberDescription
RVM_HYP_SPURIOUS0Spurious hypercall, ignored (the timer interrupt arrived before the request)
RVM_HYP_PUTCHAR1Print one character to the console
RVM_HYP_REBOOT2Reboot the current virtual machine
RVM_HYP_INT_ENA3Enable virtual machine interrupts
RVM_HYP_INT_DIS4Disable virtual machine interrupts
RVM_HYP_VCT_PHYS5Map a virtual vector of the virtual machine to a physical vector
RVM_HYP_VCT_EVT6Map a virtual vector of the virtual machine to an event channel
RVM_HYP_VCT_DEL7Delete a virtual vector mapping
RVM_HYP_VCT_LCK8Lockdown the virtual vector mappings of the virtual machine
RVM_HYP_VCT_WAIT9Sleep the virtual machine until a vector comes in
RVM_HYP_EVT_ADD10Add the send capability of an event source to the virtual machine
RVM_HYP_EVT_DEL11Delete the send capability of an event source from the virtual machine
RVM_HYP_EVT_SND12Send an event to an event channel
RVM_HYP_WDG_CLR13Start and feed the watchdog

Notes ​

  • Virtual vs. physical masking. CPSID/BASEPRI only mask physical interrupts and have no effect on virtual delivery. Guests must use RVM_HYP_INT_ENA/RVM_HYP_INT_DIS (or their C wrappers RVM_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.

An official work of EDI, released into the public domain.

GitHub·Discord·QQ 群 1038895132·rtospro.com