KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

hikami

★ 58 Open GitHub ↗

A lightweight Type-1 hypervisor for RISC-V H-extension, featuring RISC-V extension emulation. (on Milk-V Megrez)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hikami
[![Rust](https://github.com/Alignof/hikami/actions/workflows/rust.yml/badge.svg)](https://github.com/Alignof/hikami/actions/workflows/rust.yml)\
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](https://riscv.or.jp/wp-content/uploads/RV-Days_Tokyo_2024_Summer_paper_9.pdf)\
Paper in ComSys2024(ja): [link](https://ipsj.ixsq.nii.ac.jp/records/241051)

## Related projects
- [ozora](https://github.com/Alignof/ozora): Generator for hypervisor(hikami) module and decoder (raki). 
- [raki](https://github.com/Alignof/raki): RISC-V instruction decoder.
- [wild-screen-alloc](https://github.com/Alignof/wild-screen-alloc): Slab allocator for bare-metal Rust.

## Documents
```sh
$ 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:

```toml
# 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](https://github.com/Alignof/hikami_zbb)

and add `zbb=false` option to qemu args in `.cargo/config.toml`.
```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
```sh
$ 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
```sh
# 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
```sh
# 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](https://github.com/Alignof/vivado-risc-v/blob/master/README.md)

#### Boot
```sh
# 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](https://github.com/riscv/riscv-isa-manual/releases/download/20240411/unpriv-isa-asciidoc.pdf)
- [The RISC-V Instruction Set Manual: Volume II Version 20240411](https://github.com/riscv/riscv-isa-manual/releases/download/20240411/priv-isa-asciidoc.pdf)
- [Rvirt](https://github.com/mit-pdos/RVirt)
- [hypocaust-2](https://github.com/KuangjuX/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](https://www.ipa.go.jp/jinzai/mitou/it/2024/gaiyou-tn-3.html)

hikami

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README