External/cloud-hypervisor
1
0
Fork 0
mirror of https://github.com/cloud-hypervisor/cloud-hypervisor.git synced 2024-07-04 17:02:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

README: Fix formatting by keeping each line 80 characters long

Browse Source 
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This commit is contained in:
Sebastien Boeuf 2022-02-01 10:24:12 +01:00
parent bea100707f
commit 424efe6c69
1 changed files with 94 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
README.md
View File

@ -27,12 +27,19 @@
# 1. What is Cloud Hypervisor? # 1. What is Cloud Hypervisor?
Cloud Hypervisor is an open source Virtual Machine Monitor (VMM) that runs on top of [KVM](https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt) and the MSHV hypervisors . Cloud Hypervisor is an open source Virtual Machine Monitor (VMM) that runs on
top of [KVM](https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt)
hypervisor and Microsoft Hypervisor (MSHV).
The project focuses on exclusively running modern, cloud workloads, on top of a limited set of hardware architectures and platforms. The project focuses on exclusively running modern, cloud workloads, on top of
Cloud workloads refers to those that are usually run by customers inside a cloud provider. For our purposes this means modern operating systems with most I/O handled by paravirtualised devices (i.e. virtio), no requirement for legacy devices, and 64-bit CPUs. a limited set of hardware architectures and platforms. Cloud workloads refers
to those that are usually run by customers inside a cloud provider. For our
purposes this means modern operating systems with most I/O handled by
paravirtualised devices (i.e. virtio), no requirement for legacy devices, and
64-bit CPUs.
Cloud Hypervisor is implemented in [Rust](https://www.rust-lang.org/) and is based on the [rust-vmm](https://github.com/rust-vmm) crates. Cloud Hypervisor is implemented in [Rust](https://www.rust-lang.org/) and is
based on the [rust-vmm](https://github.com/rust-vmm) crates.
## Objectives ## Objectives
@ -51,7 +58,9 @@ Cloud Hypervisor is implemented in [Rust](https://www.rust-lang.org/) and is bas
### Architectures ### Architectures
Cloud Hypervisor supports the `x86-64` and `AArch64` architectures. There are some small differences in functionality between the two architectures (see [#1125](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/1125)). Cloud Hypervisor supports the `x86-64` and `AArch64` architectures. There are
some small differences in functionality between the two architectures
(see [#1125](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/1125)).
### Guest OS ### Guest OS
@ -74,9 +83,9 @@ $ mkdir $CLOUDH
## Install prerequisites ## Install prerequisites
You need to install some prerequisite packages in order to build and test Cloud Hypervisor. You need to install some prerequisite packages in order to build and test Cloud
Here, all the steps are based on Ubuntu, for other Linux distributions please replace the Hypervisor. Here, all the steps are based on Ubuntu, for other Linux
package manager and package name. distributions please replace the package manager and package name.
```shell ```shell
# Install git # Install git
@ -107,7 +116,8 @@ $ cargo build --release --target=x86_64-unknown-linux-musl --all
$ popd $ popd
``` ```
This will build a `cloud-hypervisor` binary under `$CLOUDH/cloud-hypervisor/target/release/cloud-hypervisor`. This will build a `cloud-hypervisor` binary under
`$CLOUDH/cloud-hypervisor/target/release/cloud-hypervisor`.
### Containerized builds and tests ### Containerized builds and tests
@ -139,18 +149,20 @@ development script commands and their related options.
## Run ## Run
You can run a guest VM by either using an existing cloud image or booting into your own kernel and disk image. You can run a guest VM by either using an existing cloud image or booting into
your own kernel and disk image.
### Cloud image ### Cloud image
Cloud Hypervisor supports booting disk images containing all needed Cloud Hypervisor supports booting disk images containing all needed
components to run cloud workloads, a.k.a. cloud images. To do that we rely on components to run cloud workloads, a.k.a. cloud images. To do that we rely on
the [Rust Hypervisor the [Rust Hypervisor
Firmware](https://github.com/cloud-hypervisor/rust-hypervisor-firmware) project to provide Firmware](https://github.com/cloud-hypervisor/rust-hypervisor-firmware) project
an ELF to provide an ELF formatted KVM firmware for `cloud-hypervisor` to directly
formatted KVM firmware for `cloud-hypervisor` to directly boot into. boot into.
We need to get the latest `rust-hypervisor-firmware` release and also a working cloud image. Here we will use a Ubuntu image: We need to get the latest `rust-hypervisor-firmware` release and also a working
cloud image. Here we will use a Ubuntu image:
```shell ```shell
$ pushd $CLOUDH $ pushd $CLOUDH
@ -178,7 +190,10 @@ Multiple arguments can be given to the `--disk` parameter.
#### Building your kernel #### Building your kernel
Cloud Hypervisor also supports direct kernel boot into a `vmlinux` ELF kernel. In order to support virtio-iommu we have our own development branch. You are of course able to use your own kernel but these instructions will continue with the version that we develop and test against. Cloud Hypervisor also supports direct kernel boot into a `vmlinux` ELF kernel.
In order to support virtio-iommu we have our own development branch. You are
of course able to use your own kernel but these instructions will continue with
the version that we develop and test against.
To build the kernel: To build the kernel:
@ -195,11 +210,13 @@ $ KCFLAGS="-Wa,-mx86-used-note=no" make bzImage -j `nproc`
$ popd $ popd
``` ```
The `vmlinux` kernel image will then be located at `linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin`. The `vmlinux` kernel image will then be located at
`linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin`.
#### Disk image #### Disk image
For the disk image, we will use a Ubuntu cloud image that contains a root partition: For the disk image, we will use a Ubuntu cloud image that contains a root
partition:
```shell ```shell
$ pushd $CLOUDH $ pushd $CLOUDH
@ -210,8 +227,8 @@ $ popd
#### Booting the guest VM #### Booting the guest VM
Now we can directly boot into our custom kernel and make it use the Ubuntu root partition. Now we can directly boot into our custom kernel and make it use the Ubuntu root
If we want to have 4 vCPUs and 1024 MBytes of memory: partition. If we want to have 4 vCPUs and 1024 MBytes of memory:
```shell ```shell
$ pushd $CLOUDH $ pushd $CLOUDH
@ -246,7 +263,8 @@ $ ./cloud-hypervisor/target/release/cloud-hypervisor \
# 3. Status # 3. Status
Cloud Hypervisor is under active development. The following stability guarantees are currently made: Cloud Hypervisor is under active development. The following stability guarantees
are currently made:
* The API (including command line options) will not be removed or changed in a * The API (including command line options) will not be removed or changed in a
breaking way without a minimum of 2 releases notice. Where possible warnings breaking way without a minimum of 2 releases notice. Where possible warnings
@ -270,70 +288,87 @@ As of 2021-04-29, the following cloud images are supported:
- [Ubuntu Groovy](https://cloud-images.ubuntu.com/groovy/current/) (cloudimg) - [Ubuntu Groovy](https://cloud-images.ubuntu.com/groovy/current/) (cloudimg)
- [Ubuntu Hirsute](https://cloud-images.ubuntu.com/hirsute/current/) (cloudimg) - [Ubuntu Hirsute](https://cloud-images.ubuntu.com/hirsute/current/) (cloudimg)
Direct kernel boot to userspace should work with a rootfs from most distributions. Direct kernel boot to userspace should work with a rootfs from most
distributions.
## Hot Plug ## Hot Plug
Cloud Hypervisor supports hotplug of CPUs, passthrough devices (VFIO), `virtio-{net,block,pmem,fs,vsock}` and memory resizing. This [document](docs/hotplug.md) details how to add devices to Cloud Hypervisor supports hotplug of CPUs, passthrough devices (VFIO),
a running VM. `virtio-{net,block,pmem,fs,vsock}` and memory resizing. This
[document](docs/hotplug.md) details how to add devices to a running VM.
## Device Model ## Device Model
Details of the device model can be found in this [documentation](docs/device_model.md). Details of the device model can be found in this
[documentation](docs/device_model.md).
## TODO ## TODO
We are not tracking the Cloud Hypervisor TODO list from a specific git tracked file but through We are not tracking the Cloud Hypervisor TODO list from a specific git tracked
[github issues](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/new) instead. file but through
[github issues](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/new)
instead.
# 4. `rust-vmm` project dependency # 4. `rust-vmm` project dependency
In order to satisfy the design goal of having a high-performance, security-focused hypervisor the decision In order to satisfy the design goal of having a high-performance,
was made to use the [Rust](https://www.rust-lang.org/) programming language. security-focused hypervisor the decision was made to use the
The language's strong focus on memory and thread safety makes it an ideal candidate for implementing VMMs. [Rust](https://www.rust-lang.org/) programming language. The language's strong
focus on memory and thread safety makes it an ideal candidate for implementing
VMMs.
Instead of implementing the VMM components from scratch, Cloud Hypervisor is importing the [rust-vmm](https://github.com/rust-vmm) Instead of implementing the VMM components from scratch, Cloud Hypervisor is
crates, and sharing code and architecture together with other VMMs like e.g. Amazon's [Firecracker](https://firecracker-microvm.github.io/) importing the [rust-vmm](https://github.com/rust-vmm) crates, and sharing code
and Google's [crosvm](https://chromium.googlesource.com/chromiumos/platform/crosvm/). and architecture together with other VMMs like e.g. Amazon's
[Firecracker](https://firecracker-microvm.github.io/) and Google's
[crosvm](https://chromium.googlesource.com/chromiumos/platform/crosvm/).
Cloud Hypervisor embraces the rust-vmm project goals, which is to be able to share and re-use Cloud Hypervisor embraces the rust-vmm project goals, which is to be able to
as many virtualization crates as possible. As such, the Cloud Hypervisor relationship with the rust-vmm share and re-use as many virtualization crates as possible. As such, the Cloud
project is twofold: Hypervisor relationship with the rust-vmm project is twofold:
1. It will use as much of the rust-vmm code as possible. Any new rust-vmm crate that's relevant to the project 1. It will use as much of the rust-vmm code as possible. Any new rust-vmm crate
goals will be integrated as soon as possible. that's relevant to the project goals will be integrated as soon as possible.
2. As it is likely that the rust-vmm project will lack some of the features that Cloud Hypervisor needs (e.g. ACPI, 2. As it is likely that the rust-vmm project will lack some of the features that
VFIO, vhost-user, etc), we will be using the Cloud Hypervisor VMM to implement and test them, and contribute them Cloud Hypervisor needs (e.g. ACPI, VFIO, vhost-user, etc), we will be using
back to the rust-vmm project. the Cloud Hypervisor VMM to implement and test them, and contribute them back
to the rust-vmm project.
## Firecracker and crosvm ## Firecracker and crosvm
A large part of the Cloud Hypervisor code is based on either the Firecracker or the crosvm projects implementations. A large part of the Cloud Hypervisor code is based on either the Firecracker or
Both of these are VMMs written in Rust with a focus on safety and security, like Cloud Hypervisor. the crosvm projects implementations. Both of these are VMMs written in Rust with
a focus on safety and security, like Cloud Hypervisor.
However we want to emphasize that the Cloud Hypervisor project is neither a fork nor a reimplementation of any of those However we want to emphasize that the Cloud Hypervisor project is neither a fork
projects. The goals and use cases we're trying to meet are different. nor a reimplementation of any of those projects. The goals and use cases we're
We're aiming at supporting cloud workloads, i.e. those modern, full Linux distribution images currently being run by trying to meet are different. We're aiming at supporting cloud workloads, i.e.
Cloud Service Provider (CSP) tenants. those modern, full Linux distribution images currently being run by Cloud
Service Provider (CSP) tenants.
Our primary target is not to support client or serverless use cases, and as such our code base already diverges Our primary target is not to support client or serverless use cases, and as such
from the crosvm and Firecracker ones. As we add more features to support our use cases, we believe that the divergence our code base already diverges from the crosvm and Firecracker ones. As we add
will increase while at the same time sharing as much of the fundamental virtualization code through the rust-vmm project more features to support our use cases, we believe that the divergence will
crates as possible. increase while at the same time sharing as much of the fundamental
virtualization code through the rust-vmm project crates as possible.
# 5. Community # 5. Community
The Cloud Hypervisor project follows the governance, and community guidelines described in The Cloud Hypervisor project follows the governance, and community guidelines
the [Community](https://github.com/cloud-hypervisor/community) repository. described in the [Community](https://github.com/cloud-hypervisor/community)
repository.
## Contribute ## Contribute
We are working on building a global, diverse and collaborative community around the Cloud Hypervisor project. We are working on building a global, diverse and collaborative community around
Anyone who is interested in [contributing](CONTRIBUTING.md) to the project is welcome to participate. the Cloud Hypervisor project. Anyone who is interested in
[contributing](CONTRIBUTING.md) to the project is welcome to participate.
We believe that contributing to a open source project like Cloud Hypervisor covers a lot more than just sending We believe that contributing to a open source project like Cloud Hypervisor
code. Testing, documentation, pull request reviews, bug reports, feature requests, project improvement suggestions, covers a lot more than just sending code. Testing, documentation, pull request
etc, are all equal and welcome means of contribution. See the [CONTRIBUTING](CONTRIBUTING.md) document for more details. reviews, bug reports, feature requests, project improvement suggestions, etc,
are all equal and welcome means of contribution. See the
[CONTRIBUTING](CONTRIBUTING.md) document for more details.
## Join us ## Join us
@ -342,4 +377,5 @@ and [join us on Slack](https://cloud-hypervisor.slack.com/).
## Security issues ## Security issues
Please use the GitHub security advisories feature for reporting issues: https://github.com/cloud-hypervisor/cloud-hypervisor/security/advisories/new Please use the GitHub security advisories feature for reporting issues:
https://github.com/cloud-hypervisor/cloud-hypervisor/security/advisories/new