mirrors/alioth
1
0
Fork 0
mirror of https://github.com/google/alioth.git synced 2024-11-24 04:09:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: update README

Browse source 
Signed-off-by: Changyuan Lyu <changyuanl@google.com>
This commit is contained in:
Changyuan Lyu 2024-11-18 17:49:00 -08:00 committed by Lencerf
parent e493a7cf1c
commit 08aa5a7012
1 changed files with 49 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
README.md
View file

@ -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