Skip to content

Latest commit

 

History

History
183 lines (127 loc) · 8.51 KB

README.md

File metadata and controls

183 lines (127 loc) · 8.51 KB
Raw

Unishyper

Unishyper: A Rust-based Unikernel Enhancing Reliability and Efficiency of Embedded Systems.

Unishyper is now open sourced at Gitee under Mulan PSL v2.

Related projects

Supported Boards and Platforms

MACHINE ARCH Description
qemu aarch64 QEMU/KVM (qemu-system-aarch64)
shyper aarch64 Shyper Type-1 Hypervisor
tx2 aarch64 NVIDIA TX2
qemu x86_64 QEMU/KVM (qemu-system-x86_64)
qemu riscv64 QEMU/KVM (qemu-system-riscv64)
k210 riscv64 Kendryte K210 on Maix Dock(M1/M1W)
raspi4 aarch64 Raspberry Pi 4 Model B (upcoming)

Features

  1. Singal address space, singal priveledge level.
  2. SMP support, multi-thread support.
  3. Network stack and file system support.
  4. Virtio drivers (virtio-net, virtio-blk).
  5. Terminal support.
  6. Unilib-fs support.
  7. Zone, thread grained memory isolation mechanism.
  8. Rust-std support, with modified rust-toolchain.
  9. Unwind based fault tolerance.
  10. Parts of axdriver ported from ArceOS is suppported (bus-mmio), feature 'axdriver' is required.

Architecture

Architecture

Unilib Interface

Unilib-workflow

A set of interfaces based on the idea of offload that spans unikernel and the running hypervisor platform. Based on Unilib, unikernels can conveniently use the rich general-purpose library interfaces provided by general purpose OSs running in other virtualized partitions, and choose to offload part of the protocol stack, further simplifying the unikernel structure.

Unilib-structure

The introduction of Unilib allows unikernel to choose to abandon the complex and huge device drivers and libraries code, which greatly simplifies the code size of Unikernel.

Zone-isolation based on MPK

Beyond memory management based on Rust, Unishyper’s Zone mechanism provides extra protection and safe risks that may escape Rust security insurance. Based on Zone, thread memory access permissions can be divided at a finer granularity.

On x86_64 architecture, Unishyper uses Memory Protection Keys (MPK) from Intel to achieve a Zone Demo.

Zone-based-on-MPK

Fault tolerance based on Unwind

Unishyper implements a fault tracing and tolerance mechanism based on Rust’s unwind, which includes backtracing error call chains, recording error logs, handling faults, releasing resources, and restart trying.

Fault-tolerance-based-on-unwind

Toolchains

  1. Nightly Rust (nightly-2022-09-14 tested)
  2. rust-src component (use make dependencies to install)
  3. QEMU emulator version 5.0.0
  4. mkfs from util-linux 2.31.1 (for making disk.img, see Makefile for details)
  5. cargo-binutils for using rust-objcopy and rust-objdump tools
  6. Rboot for bootloader on x86_64
  7. K210 kflash tool kflash.py for Maix Dock(M1/M1W) flashing.
  8. mkimage u-boot image tool

Applications

The examples directory contains example demos.

For build preparation:

cargo install cargo-binutils

# See .gitmodules for details
git submodule update --init --recursive

use this lines to build and emulate:

make ARCH=<arch> MACHINE=<platform> APP=<app_dir> APP_BIN=<app_bin> LOG=<log_level> run

# for examples/hello_world
ARCH=x86_64 APP=hello_world make run
# for examples/net_tcp_bench
ARCH=aarch64 APP=net_tcp_bench APP_BIN=server-bw NET=y make run

Terminal Support

The unishyper support command line interaction through a simple terminal implementation with "terminal" feature enabled. The simple terminal supports basic input and output, and some basic file operations, including ls, mkdir, cat, e.g.

You can input "help" in terminal for more information.

☻ SHELL➜ help
This is unishyper,
a research unikernel targeting a scalable and predictable runtime for embedded devices.
List of classes of commands:

cat [FILE]      -- Concatenate files and print on the standard output, "fs" feature is required.
free            -- Dump memory usage info.
kill [TID]      -- Kill target thread according to TID, you can use "ps" command to check running threads.
ls [DIR]        -- List information about the FILEs (the current directory by default), "fs" feature is required.
mkdir [DIR]     -- Create the DIRECTORY, if they do not already exist, "fs" feature is required.
ps              -- Report a snapshot of the current threads, you can use "run [TID]" to wake the ready ones.
run [TID]       -- Run target thread according to TID, you can use "ps" command to check available threads.
help            -- Print this message.

☻ SHELL➜

Network Support

To enable an ethernet device, we have to setup a tap device on the host system. For instance, the following command establish the tap device tap0 on Linux, or you can just run make tap_setup to set up tap device for network support.

sudo ip tuntap add tap0 mode tap
sudo ip addr add 10.0.0.1/24 broadcast 10.0.0.255 dev tap0
sudo ip link set dev tap0 up
sudo bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'

Add the feature net in the Cargo.toml. Unishyper use the network stack smoltcp to offer TCP/UDP communication.

By default, Unishyper's network interface uses 10.0.0.2 as IP address, 10.0.0.1 for the gateway and 255.255.255.0 as network mask.

Currently, Unishyper does only support network interfaces through virtio-net. To use it, you have to start Unishyper in Qemu with following parameters:

QEMU_NETWORK_OPTIONS := -netdev tap,id=tap0,ifname=tap0,script=no,downscript=no \
						-device virtio-net-device,mac=48:b0:2d:0e:6e:9e,netdev=tap0 \
						-global virtio-mmio.force-legacy=false

You may see Makefile for details.

FS Support

Currently Unishyper provides two types of file system, including Fatfs based on virtio and Unilib-fs based on Unilib API running on rust hypervisor.

Fatfs

To enable Fatfs, we need to enable the features fs and fat, and prefare a disk.img for it. The following command make a disk image from zero, or you can just run make disk to prepare a disk img.

dd if=/dev/zero of=disk.img bs=4096 count=92160 2>/dev/null
mkfs.fat -F 32 disk.img

Unishyper use the fatfs to offer fatfs support.

Currently, Unishyper does only support blk operation through virtio-blk. To use it, you have to start Unishyper in Qemu with following parameters:

QEMU_DISK_OPTIONS := -drive file=disk.img,if=none,format=raw,id=x0 \
					 -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 \
					 -global virtio-mmio.force-legacy=false

You may see Makefile for details.

Unilib-FS

Unishyper's Unilib-FS is based on the support of Rust-Shyper. Unishyper's fs operation request is passed to the MVM by a HVC request from Unishyper and a IPI request inside hypervisor. The MVM will perform the file operation on its user daemon process and send the result back to Unishyper.

Through the thought of unilib, Unishyper can get rid of the huge code size of file system and block device driver, replaced with just a few lines of HVC calls.