From 08aa5a7012c5cc3e9990442b576386f0a8975672 Mon Sep 17 00:00:00 2001 From: Changyuan Lyu Date: Mon, 18 Nov 2024 17:49:00 -0800 Subject: [PATCH] docs: update README Signed-off-by: Changyuan Lyu --- README.md | 97 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 49 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 94ff027..b39f348 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ ![Crates.io Version](https://img.shields.io/crates/v/alioth) ![Crates.io License](https://img.shields.io/crates/l/alioth) -Alioth is an experimental [KVM](https://docs.kernel.org/virt/kvm/api.html)-based -type-2 hypervisor (virtual machine monitor) in Rust implemented from scratch. +Alioth /AL-lee-oth/ is an experimental +[KVM](https://docs.kernel.org/virt/kvm/api.html)-based type-2 hypervisor +(virtual machine monitor) in Rust implemented from scratch. > [!IMPORTANT] > @@ -14,68 +15,68 @@ type-2 hypervisor (virtual machine monitor) in Rust implemented from scratch. ## Quick start -- Install Alioth from source, +- Install Alioth from source, - ```sh - cargo install alioth-cli --git https://github.com/google/alioth.git - ``` + ```sh + cargo install alioth-cli --git https://github.com/google/alioth.git + ``` -- Make an initramfs with - [u-root](https://github.com/u-root/u-root?tab=readme-ov-file#examples). +- Make an initramfs with + [u-root](https://github.com/u-root/u-root?tab=readme-ov-file#examples). -- Boot a Linux kernel with 2 CPUs and 4 GiB memory, +- Boot a Linux kernel with 2 CPUs and 4 GiB memory, - ```sh - alioth -l info --log-to-file \ - run \ - --kernel /path/to/vmlinuz \ - --cmd-line "console=ttyS0" \ - --initramfs /path/to/initramfs \ - --mem-size 4G \ - --num-cpu 2 - ``` + ```sh + alioth -l info --log-to-file \ + run \ + --kernel /path/to/vmlinuz \ + --cmd-line "console=ttyS0" \ + --initramfs /path/to/initramfs \ + --memory size=4G \ + --num-cpu 2 + ``` ## Features -- Runs on `x86_64` and `aarch64`. -- Boots confidential VMs with AMD SEV, SEV-ES, or SEV-SNP, see - [coco.md](docs/coco.md) for details. -- VirtIO devices - - `net` backed by a tap device, - - `vsock` backed by host `/dev/vhost-vsock`, - - `blk` backed by a raw-formatted image, - - `entropy` backed by host `/dev/urandom`, - - `fs` backed by [virtiofsd](https://gitlab.com/virtio-fs/virtiofsd) with - experimental Direct Access (DAX), - - (WIP) `balloon` with free page reporting. -- PCI device passthrough based on - [VFIO/IOMMUFD](https://docs.kernel.org/driver-api/vfio.html#iommufd-and-vfio-iommu-type1). -- Other devices - - serial console: 16450 on `x86_64`, pl011 on `aarch64`, - - [fw_cfg](https://www.qemu.org/docs/master/specs/fw_cfg.html) (QEMU Firmware - Configuration Device), - - [pvpanic](https://www.qemu.org/docs/master/specs/pvpanic.html). +- Runs on `x86_64` and `aarch64`. +- Boots confidential VMs with AMD SEV, SEV-ES, or SEV-SNP, see + [coco.md](docs/coco.md) for details. +- VirtIO devices + - `net` backed by a tap device, + - `vsock` backed by host `/dev/vhost-vsock`, + - `blk` backed by a raw-formatted image, + - `entropy` backed by host `/dev/urandom`, + - `fs` backed by [virtiofsd](https://gitlab.com/virtio-fs/virtiofsd) with + experimental Direct Access (DAX), + - (WIP) `balloon` with free page reporting. +- PCI device passthrough based on + [VFIO/IOMMUFD](https://docs.kernel.org/driver-api/vfio.html#iommufd-and-vfio-iommu-type1). +- Other devices + - serial console: 16450 on `x86_64`, pl011 on `aarch64`, + - [fw_cfg](https://www.qemu.org/docs/master/specs/fw_cfg.html) (QEMU + Firmware Configuration Device), + - [pvpanic](https://www.qemu.org/docs/master/specs/pvpanic.html). ## TODOs -- [ ] explore a better solution to ACPI DSDT to replace the pre-compiled AML - bytes, -- [ ] increase test coverage, -- [ ] add missing documents, -- [ ] (long term) port Alioth to Apple's - [Hypervisor](https://developer.apple.com/documentation/hypervisor) - framework, -- [ ] performance, performance, and performance! +- [ ] explore a better solution to ACPI DSDT to replace the pre-compiled AML + bytes, +- [ ] increase test coverage, +- [ ] add missing documents, +- [ ](long term) port Alioth to Apple's + [Hypervisor](https://developer.apple.com/documentation/hypervisor) + framework, +- [ ] performance, performance, and performance! ## Acknowledgment The virtualization implementation in Alioth takes the following projects as references, -- [QEMU](https://gitlab.com/qemu-project/qemu.git) -- [crosvm](https://chromium.googlesource.com/crosvm/crosvm/) -- [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) -- [xhyve](https://github.com/machyve/xhyve) +- [QEMU](https://gitlab.com/qemu-project/qemu.git) +- [crosvm](https://chromium.googlesource.com/crosvm/crosvm/) +- [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) +- [xhyve](https://github.com/machyve/xhyve) The [error handling](docs/error-handling.md) practice is inspired by [GreptimeDB](https://github.com/GreptimeTeam/greptimedb)'s