-
Notifications
You must be signed in to change notification settings - Fork 56
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README: Update to reflect current functionality and usage
Signed-off-by: Rob Bradford <[email protected]>
- Loading branch information
Showing
1 changed file
with
30 additions
and
80 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,21 +1,25 @@ | ||
| # Simple KVM firmware | ||
| # Rust Hypervisor Firmware | ||
|
|
||
| **This project is an experiment and should not be used production workloads.** | ||
| This repository contains a simple firmware that is designed to be launched from | ||
| anything that supports loading ELF binaries and running them with the | ||
| PVH booting standard | ||
|
|
||
| This repository contains a simple KVM firmware that is designed to be launched | ||
| from anything that supports loading ELF binaries and running them with the | ||
| Linux kernel loading standard. | ||
|
|
||
| The ultimate goal is to be able to use this "firmware" to be able to load a | ||
| bootloader from within a disk image. | ||
| The purpose is to be able to use this firmware to be able to load a | ||
| bootloader from within a disk image without requiring the use of a complex | ||
| firmware such as TianoCore/edk2 and without requiring the VMM to reuse | ||
| functionality used for booting the Linux kernel. | ||
|
|
||
| Currently it will directly load a kernel from a disk image that follows the | ||
| [Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) | ||
|
|
||
| There is also minimal EFI compatibility support allowing the boot of some | ||
| images that use EFI (shim + GRUB2 as used by Ubuntu). | ||
|
|
||
| The firmware is primarily developed against [Cloud | ||
| Hypervisor](https://github.com/intel/cloud-hypervisor). | ||
| Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) but there is | ||
| also support for using QEMU's PVH loader. | ||
|
|
||
| This project was orginally developed using | ||
| This project was originally developed using | ||
| [Firecracker](https://github.com/firecracker-microvm) however as it does not | ||
| currently support resetting the virtio block device it is not possible to boot | ||
| all the way into the OS. | ||
|
|
@@ -32,7 +36,7 @@ target/target/release/hypervisor-fw | |
|
|
||
| ## Features | ||
|
|
||
| * virtio (MMIO & PCI) block support | ||
| * virtio (PCI) block support | ||
| * GPT parsing (to find EFI system partition) | ||
| * FAT12/16/32 directory traversal and file reading | ||
| * bzImage loader | ||
|
|
@@ -42,17 +46,16 @@ target/target/release/hypervisor-fw | |
|
|
||
| ## Running | ||
|
|
||
| Works with Cloud Hypervisor and Firecracker as a drop in replacement for the | ||
| Linux kernel. It does not work with crosvm as crosvm has a hardcoded kernel | ||
| function start address. | ||
| Works with Cloud Hypervisor and QEMU via their PVH loaders as an alternative to | ||
| the Linux kernel. | ||
|
|
||
| Cloud Hypervisor is currently the primary development target for the firmware | ||
| although support for other VMMs will be considered. | ||
| Cloud Hypervisor and QEMU are currently the primary development targets for the | ||
| firmware although support for other VMMs will be considered. | ||
|
|
||
| ### Cloud Hypervisor | ||
|
|
||
| As per [getting | ||
| started](https://github.com/intel/cloud-hypervisor/blob/master/README.md#2-getting-started) | ||
| started](https://github.com/cloud-hypervisor/cloud-hypervisor/blob/master/README.md#2-getting-started) | ||
|
|
||
| However instead of using the binary firmware for the parameter to `--kernel` | ||
| instead use the binary you build above. | ||
|
|
@@ -62,57 +65,29 @@ $ pushd $CLOUDH | |
| $ sudo setcap cap_net_admin+ep ./cloud-hypervisor/target/release/cloud-hypervisor | ||
| $ ./cloud-hypervisor/target/release/cloud-hypervisor \ | ||
| --kernel ./target/target/release/hypervisor-fw \ | ||
| --disk path=./clear-29160-kvm.img \ | ||
| --disk path=focal-server-cloudimg-amd64.raw \ | ||
| --cpus boot=4 \ | ||
| --memory size=512M \ | ||
| --net "tap=,mac=,ip=,mask=" \ | ||
| --rng | ||
| $ popd | ||
| ``` | ||
|
|
||
| ### Firecracker | ||
| ### QEMU | ||
|
|
||
| As per [quick | ||
| start](https://github.com/firecracker-microvm/firecracker/blob/master/docs/getting-started.md) | ||
| Use the QEMU `-kernel` parameter to specify the path to the firmware. | ||
|
|
||
| Replacing the kernel and rootfs to point at the firmware and the full disk | ||
| image instead. | ||
| e.g. | ||
|
|
||
| ``` | ||
| curl --unix-socket /tmp/firecracker.socket -i \ | ||
| -X PUT 'http://localhost/boot-source' \ | ||
| -H 'Accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "kernel_image_path": "target/target/release/hypervisor-fw", | ||
| "boot_args": "" | ||
| }' | ||
| curl --unix-socket /tmp/firecracker.socket -i \ | ||
| -X PUT 'http://localhost/drives/rootfs' \ | ||
| -H 'Accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "drive_id": "rootfs", | ||
| "path_on_host": "clear-28660-kvm.img", | ||
| "is_root_device": true, | ||
| "is_read_only": false | ||
| }' | ||
| curl --unix-socket /tmp/firecracker.socket -i \ | ||
| -X PUT 'http://localhost/actions' \ | ||
| -H 'Accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "action_type": "InstanceStart" | ||
| }' | ||
| $ qemu-system-x86_64 -machine q35,accel=kvm -cpu host,-vmx -m 1G\ | ||
| -kernel ./target/target/release/hypervisor-fw \ | ||
| -display none -nodefaults \ | ||
| -serial stdio \ | ||
| -drive id=os,file=focal-server-cloudimg-amd64.raw,if=none \ | ||
| -device virtio-blk-pci,drive=os,disable-legacy=on | ||
| ``` | ||
|
|
||
| **Currently Firecracker's virtio block device does not support resetting the | ||
| device and as such it is not possible for the booted Linux kernel to take over | ||
| the device from the firmware.** | ||
|
|
||
| ## Testing | ||
|
|
||
| "cargo test" needs disk images from make-test-disks.sh | ||
|
|
@@ -122,28 +97,3 @@ And clear-28660-kvm.img: | |
| https://download.clearlinux.org/releases/28660/clear/clear-28660-kvm.img.xz | ||
|
|
||
| sha1sum: 5fc086643dea4b20c59a795a262e0d2400fab15f | ||
|
|
||
| ## Security | ||
|
|
||
| **Reporting a Potential Security Vulnerability**: If you have discovered | ||
| potential security vulnerability in this project, please send an e-mail to | ||
| [email protected]. For issues related to Intel Products, please visit | ||
| https://security-center.intel.com. | ||
|
|
||
| It is important to include the following details: | ||
| - The projects and versions affected | ||
| - Detailed description of the vulnerability | ||
| - Information on known exploits | ||
|
|
||
| Vulnerability information is extremely sensitive. Please encrypt all security | ||
| vulnerability reports using our *PGP key* | ||
|
|
||
| A member of the Intel Product Security Team will review your e-mail and | ||
| contact you to to collaborate on resolving the issue. For more information on | ||
| how Intel works to resolve security issues, see: *Vulnerability Handling | ||
| Guidelines* | ||
|
|
||
| PGP Key: https://www.intel.com/content/www/us/en/security-center/pgp-public-key.html | ||
|
|
||
| Vulnerability Handling Guidelines: https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html | ||
|
|
||