About this project

Diosix strives to be a lightweight, reliable, and secure multi-core bare-metal hypervisor written in Zig for 64-bit RISC-V computers. It is aimed at systems small and large that have a need to run multiple hardware-isolated operating systems at the same time.

Below is a recording of a user logging into a RISC-V Linux guest OS running on Diosix.

This project is a work-in-progress. By using Zig, we aim to iterate and innovate quickly while maintaining a strict focus on safety, security, and robustness.

Diosix is designed to be self-contained and simple to install. It includes a privileged Linux-based Root Virtual Machine (Root VM) for managing the host hardware and orchestrating other guest workloads.

For a deeper dive into this type-1 hypervisor’s design, see the technical documentation.

Build Diosix

To build Diosix, you must have at least version 0.17.0 of the Zig toolchain and Git version 2.54 installed.

Follow these steps to build the hypervisor from source:

1. Clone the repository and enter the project directory:

   git clone --branch stable https://github.com/diodesign/diosix.git
   cd diosix
   

2. Start the build process using the wrapper script:

   ./scripts/build.sh
   

To ensure the compiled hypervisor binary embeds accurate versioning and diagnostic info, scripts/build.sh captures fresh host metadata, such as the current git revision and build date, on every execution. This prevents the Zig build system from reusing stale cached values, which can happen if zig build is run directly.

For a detailed explanation of the compilation process, declarative hardware configuration, and the dependency caching system, see the build system documentation.

Root VM image

The build process automatically downloads and cross-compiles BuildRoot if the Root VM image is missing or needs updating. Because Diosix builds everything from source for an absolute guarantee of provenance and security, this initial BuildRoot step can take significant time to compile the Linux kernel, a busybox userspace, and the cross-compiler toolchain. Subsequent builds rely on the cached output.

Supported hardware

Diosix runs on RVA20-compliant (RV64GC) systems, automatically adapting its isolation model based on whether the hypervisor (H) extension or physical memory protection (PMP) is available.

Target hardware systems

Diosix relies on a modular, declarative hardware configuration model. Available hardware ports are defined inside target configuration YAML files located in hypervisor/hw/ports/, such as qemu-virt.yaml.

The default target system is specified in hypervisor/hw/ports/default.yaml, which defaults to qemu-virt. To compile for a different target hardware system, specify the target name using the -Dsystem parameter. For example, to target a PMP-only Qemu-simulated system, use:

./scripts/build.sh -Dsystem=qemu-virt-pmp

You can view all dynamically discovered target hardware systems and other build options by running:

./scripts/build.sh -h

Output files

The hypervisor executable is generated at ./zig-out/bin/vmdiosix.

Run Diosix

Although the hypervisor compiles for physical hardware targets, the simplest way to run and test Diosix is inside an emulated environment using QEMU.

We recommend using at least version 10.1.5 of QEMU. Ensure the 64-bit RISC-V system emulator is installed on your host system.

To boot the hypervisor with four virtual CPU cores and 2GB of RAM using the emulated QEMU virt machine environment, run the following command:

./scripts/build.sh run

By default, the hypervisor sends its output to the serial port, which QEMU displays in the terminal. Exit and terminate the emulator by pressing Ctrl-a followed by x. To enter the debug console, press Ctrl-a followed by c.

Develop Diosix

We welcome contributions to the project and ask that you follow our established development standards to ensure high-quality code and documentation.

When writing new code, please be mindful of ownership and memory management; function callers are responsible for freeing any pointers returned by functions that require an allocator. Always use the provided allocator for cleanup to avoid leaks.

We require comprehensive unit tests for all new core logic to verify correctness. These tests run on the build host and must pass successfully before any Changes are accepted into the codebase.

To execute the test suite, run the following command:

./scripts/build.sh test

All contributions must strictly adhere to the Diosix style guide. This guide covers both our technical writing standards — such as defining abbreviations on first use and using sentence-case headings — and our idiomatic Zig coding conventions.

Finally, we use the Calendar Versioning (YY.MINOR) format for our releases, where even-numbered minor versions indicate stable releases and odd numbers represent development builds.

Branching model

The project maintains two primary branches to orchestrate development and releases:

• stable: The branch representing production-ready code. Releases are created directly from this branch, and it is also the source branch used to build the official project website, diosix.org.
• devel: The active staging branch for development and ongoing feature additions.

Development workflows should target the devel branch. Changes are only merged from devel into stable after completing rigorous testing, quality control, and validation.

Contact and community

If you have questions, wish to contribute, or need to report an issue, email hello@diosix.org. You can also submit pull requests or raise issues through this GitHub repository.

If you have discovered a security vulnerability, please follow the security reporting process to disclose the matter privately and responsibly.

All participants are expected to follow the project’s code of conduct.

Copyright and license

Copyright © 2024-2026 Diosix contributors. This project is distributed under the terms of the MIT License. See LICENSE for the full text and CONTRIBUTORS for the list of copyright holders.

The diosix.org illustration is a combination of artwork provided by Katerina Limpitsouni and RISC-V International.

All product names, logos, brands, trademarks, and registered trademarks are property of their respective owners. All company, product, and service names used by the Diosix project and its contributors are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.