About this project

Diosix is a type-1 bare-metal hypervisor written in the Zig programming language for 64-bit RISC-V systems. It allows systems large and small to run multiple hardware-isolated operating systems at the same time.

This project is an ongoing work-in-progress. By using Zig, we aim to innovate and iterate quickly while maintaining a strict focus on safety, security, and robustness. We target RISC-V for its open, modular, and extensible nature.

Quickstart

The simplest way to run and test Diosix is inside an emulated environment using the QEMU emulator. The following instructions assume you are using a Linux host system and are comfortable using a command-line terminal.

Before you begin, ensure you have the following software installed on your host:

QEMU version 10.1.5 or later.
Git version 2.54 or later.
Zig version 0.17.0 or later.

To build, compile, and run the complete system:

Clone the repository and enter the project directory:

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

Compile the hypervisor and boot the system inside QEMU:
```
./scripts/build.sh run
```
The build process automatically downloads and compiles a trusted Linux guest Virtual Machine (VM) called the Root VM, which assists the hypervisor in managing the host hardware and running other guests. Once compilation completes, QEMU boots the hypervisor, which then automatically starts and runs this Root VM.

The hypervisor outputs debug and diagnostic information directly to your terminal. You can also interact with the running Root VM via the terminal.
To log into the Root VM, use the username root with no password.

If the Root VM is powered off, the hypervisor will automatically restart it.

To control the emulator process from your terminal:

Exit the emulator by pressing Ctrl-a followed by x to terminate the emulation.
Enter the QEMU monitor shell by pressing Ctrl-a followed by c. Press Ctrl-a and c again to return to the hypervisor console.

The following is a recording of a user building and running Diosix, and then logging into and interacting with the Root VM running on the hypervisor.

More information

For more information about Diosix, see the following documentation:

Diosix architecture: Learn about the hypervisor’s hierarchical forking model, privileged Root VM design, security boundary rules, and memory address space terminology.
Build Diosix: Learn about the build system, build commands, and incremental build caching.
Run Diosix: Learn how to run the hypervisor, use target emulators, customize boot parameters, and load the software onto physical hardware targets.
Develop for Diosix: View the project’s programming guidelines, memory ownership rules, unit testing commands, Git branching workflows, and CalVer release versioning.

For more information about the technology used by the hypervisor, see the following external documentation:

Copyright and license

The diosix.org website 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 are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.