hikami

A lightweight Type-1 hypervisor for RISC-V H-extension, featuring RISC-V extension emulation.

This project aims not only to realize a lightweight hypervisor that can be used on RISC-V H extensions, but also to easily reproduce and manage the "extension" on the hypervisor.\ Poster in RISC-V Days Tokyo 2024 Summer: PDF
Paper in ComSys2024(ja): link

Related projects

• ozora: Generator for hypervisor(hikami) module and decoder (raki).
• raki: RISC-V instruction decoder.
• wild-screen-alloc: Slab allocator for bare-metal Rust.

Documents

$ cargo doc --open

Extension Management

hikami utilizes a procedural macro crate called extension_manager to dynamically incorporate RISC-V extension emulations. This allows for adding or removing extension supports without modifying the core hypervisor code.

To enable an extension, simply add the extension crate name to the enable_extension feature list in the root Cargo.toml file. For example, to enable the Zbb extension, you would add hikami_zbb as follows:

# hikami/Cargo.toml
[dependencies]
hikami_zbb = { git = "https://github.com/Alignof/hikami_zbb", optional = true }
[features]
enable_extension = [ "hikami_zbb" ]

See also: https://github.com/Alignof/hikami_zbb

and add zbb=false option to qemu args in .cargo/config.toml.

[target.riscv64imac-unknown-none-elf]
runner = """
qemu-system-riscv64
-cpu rv64,smstateen=true,zbb=false
-machine virt
-bios default
-nographic
-m 2G
-drive file=rootfs.ext2,format=raw,id=hd0,if=none
-device ich9-ahci,id=ahci -device ide-hd,drive=hd0,bus=ahci.0 
-kernel
"""

During the build process, extension_manager automatically detects these crates and expands the necessary code to initialize the extension and dispatch instruction handling. This approach simplifies the management of multiple extensions and enhances the modularity of the hypervisor.

Getting Started

Setup

$ git clone https://github.com/buildroot/buildroot.git
$ cd buildroot/
$ make qemu_riscv64_virt_defconfig
$ make -j$(nproc)
$ ln -s output/images/rootfs.ext2 path/to/hikami/rootfs.ext2
$ ln -s output/build/linux-x.x.x/vmlinux path/to/hikami/guest_image/vmlinux
# optional
$ ln -s path/to/initrd path/to/hikami/guest_image/initrd

# copy host dts and edit to change user memory config
# QEMU's dtb can be obtained by adding the option `-machine dumpdtb=qemu.dtb`.
$ vim guest_image/guest.dts

Run on QEMU

# The actual command to be executed is written in .cargo/config.toml.
$ cargo r

Run on FPGA

The target FPGAs are as the following. (boards supported by vivado-riscv repository)

- AMD VC707 
- AMD KC705 
- Digilent Genesys 2 
- Digilent Nexys Video 
- Digilent Nexys A7 100T 
- Digilent Arty A7 100T

Building the FPGA environment

# set environment
$ git clone https://github.com/Alignof/vivado-risc-v -b feature/hikami
$ cd vivado-risc-v
$ make update-submodules

# Build FPGA bitstream
# Connect a micro-B cable to `PROG`
$ source /opt/Xilinx/Vivado/2024.2/settings64.sh
$ make CONFIG=rocket64b1 BOARD=nexys-video bitstream

# Prepare the SD card
$ ./mk-sd-card

# Program the FPGA flash memory
$ Xilinx/Vivado/2023.2/bin/hw_server
$ env HW_SERVER_URL=tcp:localhost:3121 xsdb -quiet board/jtag-freq.tcl
$ make CONFIG=rocket64b2 BOARD=nexys-video flash

See also for an environment information: https://github.com/Alignof/vivado-risc-v/blob/master/README.md

Boot

# Connect a micro-B cable to `UART`
$ sudo picocom -b 115200 /dev/ttyUSB2 # <- select the corresponding serial port 

# login: debian
# password: debian

Run on Milk-V Megrez

Coming soon...

References

• The RISC-V Instruction Set Manual: Volume I Version 20240411
• The RISC-V Instruction Set Manual: Volume II Version 20240411
• Rvirt
• hypocaust-2

Acknowledgement

Exploratory IT Human Resources Project (MITOU Program) of Information-technology Promotion Agency, Japan (IPA) in the fiscal year 2024.
https://www.ipa.go.jp/jinzai/mitou/it/2024/gaiyou-tn-3.html