Adding a bit of documentation and links about the TDShim and how to run
it with Cloud Hypervisor.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
In order to allow for human readable output for the VM configuration, we
pull it out of the snapshot, which becomes effectively the list of
states from the VM. The configuration is stored through a dedicated file
in JSON format (not including any binary output).
Having the ability to read and modify the VM configuration manually
between the snapshot and restore phases makes debugging easier, as well
as empowers users for extending the use cases relying on the
snapshot/restore feature.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Remove the bits about this feature being experimental, as well as
limitations around virtio-mem and vhost-user devices.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Since we moved to the CloudHvX64 target from EDK2, we can't use the same
OVMF firmware for both Cloud Hypervisor and QEMU. The documentation
needed some updates.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The Linux Foundation have recommended the use of the this license for
documentation so this change included the license in the documentation
directory.
The file "networking.md" was remove as the copyright holder did not give
their consent.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
Update documentation and CI to rely on the new CLOUDHV.fd firmware built
from the newly introduced target CloudHvX64.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Currently cloud-hypervisor supports hotplug of CPUs, passthrough devices, virtio devices and memory resizing,
but in hotplug.md it still mentiones: "Currently Cloud Hypervisor only supports hot plugging of CPU devices."
We need to remove the incorrect information from hotplug.md to reflect the true situation.
Fixes: #3504
Signed-off-by: Liang Zhou <zhoul110@chinatelecom.cn>
There is a corner case of using the Cloud Hypervisor on AArch64:
If the VM is started on a device where RAM is limited, and if the user
allocates nearly as much memory for the guest as is still free on the
host, we need to enable the swap memory.
This commit documented this corner case with explanation.
Also, this commit corrects the hardware requirement of the GIC interrupt
controller for running the Cloud Hypervisor on AArch64, accroding to
[1].
Fixes: https://github.com/cloud-hypervisor/cloud-hypervisor/issues/3419
Signed-off-by: Henry Wang <Henry.Wang@arm.com>
[1] https://www.kernel.org/doc/html/latest/virt/kvm/devices/arm-vgic-its.html
Bumping the OVMF binary version along with UEFI documentation to
reflect the latest set of patches on top of tianocore/edk2 'master'
branch, which can be found on the Cloud Hypervisor fork on 'ch' branch.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Current `Getting Started` section only contains steps for the x86_64
platform, as we have a documentation doing the same thing for AArch64,
we can point users to the correct documentation.
Also, this commit modifies the `docs/arm64.md` to fit the documentation
style within the project.
Signed-off-by: Henry Wang <Henry.Wang@arm.com>
Creating some brief documentation for TDX, summarizing the links on
where to find more information about TDX, as well as how to run Cloud
Hypervisor on it.
Fixes#3318
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Fixing a few inconsistencies and extending the document to tackle
multiple devices use case, as well as having multiple devices under the
same IOMMU group.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The proper way to refer to the project is "Cloud Hypervisor" without the
hyphen in the middle. On the other hand, if one refers to the binary
name, it is "cloud-hypervisor".
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This new document describes the available options for the parameter
`--cpus`, how to use them and what is their usage.
Fixes#3317
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The purpose is to add more info while running
spdk vhost tgt. For example, adding more info
(total_size, block_size) to describe the meaning
on creating malloc bdev inside spdk vhost tgt.
Signed-off-by: Ziye Yang <ziye.yang@intel.com>
The elements of a list should be using commas as the correct delimiter
now that it is supported. Deprecate use of colons as delimiter.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Update introduction of option `prefault`.
In addition, this commit also did the following:
- Rearrange options, synchronize order with `config.rs`.
- Break long lines in `hugepages`.
- Update old example of `hugepages` in memory zone.
Signed-off-by: Li Yu <liyu.yukiteru@bytedance.com>
Added a section in "Usage" chapter of "iommu.md" to introduce the
special behavior when virtio-iommu is working with FDT on AArch64.
Signed-off-by: Michael Zhao <michael.zhao@arm.com>
To enable live-migration for vhost-user devices, we now always shutdown
the source VM when the migration is completed. This patch reflects this
change in the documentation.
Signed-off-by: Bo Chen <chen.bo@intel.com>
Change the block size to the standard 512 byte sector size to that
disk images can be used (since their partition tables will be specified
in terms of 512 byte sectors.)
Also remove the hugepages=on option from the command line as it is not
necessary.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
It is forbidden that the same memory zone belongs to more than one
NUMA node. This commit adds related validation to the `--numa`
parameter to prevent the user from specifying such configuration.
Signed-off-by: Henry Wang <Henry.Wang@arm.com>
Replacing QCOW mentions with other viable options. There is still
docs/custom-image.md which talks about creating QCOW, however it
might be more convenient to be touched when the actual changes
are indeed there.
Related to #1985.
Signed-off-by: Anatol Belski <anbelski@linux.microsoft.com>
Add missing option of hugepage_size in argument of memory,
and add some details about lacking huge pages.
Signed-off-by: Yu Li <liyu.yukiteru@bytedance.com>
The edk2 upstream has already suppoorted AArch64 Cloud Hypervisor,
and hence we can use upstream edk2 in CI and doc.
Signed-off-by: Henry Wang <Henry.Wang@arm.com>
This new option allows the user to define a list of SGX EPC sections
attached to a specific NUMA node.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
In order to uniquely identify each SGX EPC section, we introduce a
mandatory option `id` to the `--sgx-epc` parameter.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Simplified the build instruction on arm64.
And the binary built with default option can be used for both UEFI and
direct-kernel test.
Signed-off-by: Michael Zhao <michael.zhao@arm.com>
Make sure the unique PCI bus is tied to the default NUMA node 0, and
update the documentation to let the users know about this special case.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Some new integration tests will require the "stress" binary to be
present in the guest in order to run correctly.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Updated the obsoleted instructions and scripts, based on Open vSwitch
v2.13.1, DPDK stable v19.11.3, and Cloud Hypervisor v15.0 (on Ubuntu
20.04.1).
Signed-off-by: Bo Chen <chen.bo@intel.com>
The latest kvm-sgx code has renamed sgx_virt_epc device node
to sgx_vepc. Update cloud-hypervisor code and documentation to
follow this.
Signed-off-by: Mikko Ylinen <mikko.ylinen@intel.com>
With recent kernels, it is now expected to use "bind" control from the
sysfs in order to bind a specific device to the vfio-pci driver.
The use of "new_id" is still required but it is only needed once per
device type. Let's say you want to bind two virtio-net devices, you will
need to add the device_id:vendor_id pair through "new_id", while you
will be required to use "bind" for each device.
Fixes#2545
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The MCRS method returns a 64-bit memory range descriptor. The
calculation is supposed to be done as follows:
max = min + len - 1
However, every operand is represented not as a QWORD but as combination
of two DWORDs for high and low part. Till now, the calculation was done
this way, please see also inline comments:
max.lo = min.lo + len.lo //this may overflow, need to carry over to high
max.hi = min.hi + len.hi
max.hi = max.hi - 1 // subtraction needs to happen on the low part
This calculation has been corrected the following way:
max.lo = min.lo + len.lo
max.hi = min.hi + len.hi + (max.lo < min.lo) // check for overflow
max.lo = max.lo - 1 // subtract from low part
The relevant part from the generated ASL for the MCRS method:
```
Method (MCRS, 1, Serialized)
{
Acquire (MLCK, 0xFFFF)
\_SB.MHPC.MSEL = Arg0
Name (MR64, ResourceTemplate ()
{
QWordMemory (ResourceProducer, PosDecode, MinFixed, MaxFixed, Cacheable, ReadWrite,
0x0000000000000000, // Granularity
0x0000000000000000, // Range Minimum
0xFFFFFFFFFFFFFFFE, // Range Maximum
0x0000000000000000, // Translation Offset
0xFFFFFFFFFFFFFFFF, // Length
,, _Y00, AddressRangeMemory, TypeStatic)
})
CreateQWordField (MR64, \_SB.MHPC.MCRS._Y00._MIN, MINL) // _MIN: Minimum Base Address
CreateDWordField (MR64, 0x12, MINH)
CreateQWordField (MR64, \_SB.MHPC.MCRS._Y00._MAX, MAXL) // _MAX: Maximum Base Address
CreateDWordField (MR64, 0x1A, MAXH)
CreateQWordField (MR64, \_SB.MHPC.MCRS._Y00._LEN, LENL) // _LEN: Length
CreateDWordField (MR64, 0x2A, LENH)
MINL = \_SB.MHPC.MHBL
MINH = \_SB.MHPC.MHBH
LENL = \_SB.MHPC.MHLL
LENH = \_SB.MHPC.MHLH
MAXL = (MINL + LENL) /* \_SB_.MHPC.MCRS.LENL */
MAXH = (MINH + LENH) /* \_SB_.MHPC.MCRS.LENH */
If ((MAXL < MINL))
{
MAXH += One /* \_SB_.MHPC.MCRS.MAXH */
}
MAXL -= One
Release (MLCK)
Return (MR64) /* \_SB_.MHPC.MCRS.MR64 */
}
```
Fixes#1800.
Signed-off-by: Anatol Belski <anbelski@linux.microsoft.com>
Both changes aim to document the absence of the CPU hot-remove
functionality on Windows.
Closes#2457.
Signed-off-by: Anatol Belski <anbelski@linux.microsoft.com>
The hotplug documentation was missing the explanation on how to use
memory hotplug with virtio-mem.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Document that seccomp is on and how to disable it along with a pointer
on how to identify missing syscalls during development.
Fixes#993
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Since INTx is now supported for VFIO PCI devices, there is no more
limitations regarding VFIO, which means the documentation must be
updated accordingly.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Including a warning that the user is respsonsible for ensuring that they
have sufficient pages of the specified size.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
Because of the behavior of the NVIDIA proprietary driver, we can't
expect NVIDIA cards with only MSI support to be functioning correctly
after they've been passed through with Cloud-Hypervisor.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Based on the LKML feedback, the devices under /dev/sgx/* are
not justified. SGX RFC v40 moves the SGX device nodes to /dev/sgx_*
and this is reflected in kvm-sgx (next branch) too.
Update cloud-hypervisor code and documentation to follow this.
Signed-off-by: Mikko Ylinen <mikko.ylinen@intel.com>
Now that we can support supplying an fd to the TAP device we can support
the MACVTAP and MACVLAN use cases.
Fixes: #872
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
The standalone `--balloon` parameter being fully functional at this
point, we can get rid of the balloon options from the --memory
parameter.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This changeset extends the documentation with the UEFI and Windows
related info. The focus is on providing consumer with a minimum
necessary and proper piece of the information to enter the features
quickly. While UEFI is a cross platform topic, it is a required
prerequisite for the Windows usage.
Signed-off-by: Anatol Belski <anbelski@linux.microsoft.com>
Misspellings were identified by https://github.com/marketplace/actions/check-spelling
* Initial corrections suggested by Google Sheets
* Additional corrections by Google Chrome auto-suggest
* Some manual corrections
Signed-off-by: Josh Soref <jsoref@users.noreply.github.com>
Add the new option 'hotplugged_size' to both --memory-zone and --memory
parameters so that we can let the user specify a certain amount of
memory being plugged at boot.
This is also part of making sure we can store the virtio-mem size over a
reboot of the VM.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Implement a new VM action called 'resize-zone' allowing the user to
resize one specific memory zone at a time. This relies on all the
preliminary work from the previous commits to resize each virtio-mem
device independently from each others.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
In anticipation for resizing support of an individual memory zone,
this commit introduces a new option 'hotplug_size' to '--memory-zone'
parameter. This defines the amount of memory that can be added through
each specific memory zone.
Because memory zone resize is tied to virtio-mem, make sure the user
selects 'virtio-mem' hotplug method, otherwise return an error.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The goal of this commit is to rename the existing NUMA option 'id' with
'guest_numa_id'. This is done without any modification to the way this
option behaves.
The reason for the rename is caused by the observation that all other
parameters with an option called 'id' expect a string to be provided.
Because in this particular case we expect a u32 representing a proximity
domain from the ACPI specification, it's better to name it with a more
explicit name.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Based on the recent changes regarding how to describe NUMA nodes to the
guest, the documentation related to memory zones and NUMA has been
updated accordingly.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Writing some new documentation to help users understand how the guest
memory can be described through Cloud-Hypervisor parameters.
Fixes#1659
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Use of backing file is deprecated hence use the `hugepages` field.
Also use the `boot` field for specifying number of cpus
Signed-off-by: Amey Narkhede <ameynarkhede02@gmail.com>
Use updated --memory option parameters. The field `size` needs
M/G suffix. Without the suffix cloud-hypervisor panics at
src/main.rs:353
Also the use of backing file is deprecated so use `shared` field
Signed-off-by: Amey Narkhede <ameynarkhede02@gmail.com>
Add some documentation regarding the snapshot/restore feature which was
introduced earlier, explaining how the feature works and how to use it
properly.
Fixes#1490
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Add the basic infrastructure for fuzzing along with a qcow fuzzer ported
from crosvm and adapted to our code.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
With recent changes (#1030#1084), the '/vm.remove-device' API is no
longer restricted to remove VFIO PCI devices. It now supports (almost)
all hotpluggable devices, e.g. disk/net/pmem/fs/vsock.
Signed-off-by: Bo Chen <chen.bo@intel.com>
Now that our CI has transitioned from ClearLinux to Ubuntu images
exclusively, let's update the documentation to refer to Ubuntu images
instead of ClearLinux's ones.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Now that the project relies on Ubuntu images, the documentation related
to the creation of a custom image has been updated. It's important to
note this procedure could be applied to any other distribution, given
that the package manager's commands would be slightly different.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Update the API documentation to reflect that the hotplug APIs return
data about the device as well as the newly added /vm.counters API.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
Currently, not every feature of the cloud-hypervisor is enabled
on AArch64, which means that on AArch64 machines, the
`run_unit_tests.sh` needs to be tailored and some unit test cases
should be run on x86_64 only.
Also this commit fixes the typo and unifies `Arm64` and `AArch64`
in the AArch64 document.
Signed-off-by: Henry Wang <Henry.Wang@arm.com>
The support of AArch64 is in very early stage. The steps in building and
runing on X86 and AArch64 can not align well yet. Adding AArch64 content
to README.md would produce much divergence.
Adding a guide in docs/ folder could be a better way to start now.
Signed-off-by: Michael Zhao <michael.zhao@arm.com>
The action of "vm.delete" should not report errors on non-booted
VMs. This patch also revised the "docs/api.md" to reflect the right
'Prerequisites' of different API actions, e.g. on "vm.delete" and
"vm.boot".
Fixes: #1110
Signed-off-by: Bo Chen <chen.bo@intel.com>
This config option provided very little value and instead we now enable
this feature (which then lets the guest control the cache mode)
unconditionally.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
This doc describe how to use vhost-user-blk in Cloud Hypervisor
with SPDK. With this doc, we can setup simple test environment on
Ubuntu release.
Signed-off-by: Yang Zhong <yang.zhong@intel.com>
Currently unimplemented. Once implemented, this API will allow for
creating virtio-fs devices in the VM after it has booted.
Signed-off-by: Dean Sheather <dean@coder.com>
Add a document to illustrate how to test vhost-user-net function with
OpenVSwitch + DPDK as backend.
Signed-off-by: Cathy Zhang <cathy.zhang@intel.com>
The option desired_ram is in byte, make larger the amount of memory to
add.
Signed-off-by: Jose Carlos Venegas Munoz <jose.carlos.venegas.munoz@intel.com>
This commit introduces the new command "remove-device" that will let a
user hot-unplug a VFIO PCI device from an already running VM.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
A new ClearLinux image has been uploaded to the Azure storage account.
It is based off of the ClearLinux cloudguest image 31310 version, with
three extra bundles added to it.
First bundle is curl, which adds the curl binary to the image, second
bundle is iperf, adding the iperf binary to the image, and third bundle
is sysadmin-basic to include utility like netcat.
The image is 2G in size.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Just updating the documentation regarding the pre-creation of a tap
interface supporting multiqueue, by adding what the cloud-hypervisor
--net parameter should look like.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
With the latest version of virtiofsd, some changes have been made
to the socket path parameter. This needs to be updated in the cloud
hypervisor codebase, so that our CI keeps running correctly.
Fixes#611
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The cache= option from the virtiofsd backend is meant to be used
depending on how the user wants to use the guest page cache. For most
use cases, we want to bypass the guest page cache to reduce the guest
memory footprint, which is why "cache=none" should be the default.
"cache=always" is the other option when the user wants to do something
specific by using the guest page cache, but should not be the default
anymore.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
With latest kernel, virtio-fs mount command has been simplified, and
this needs to be applied everywhere in our tests and documentation.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The documentation was out of date since the URL to download virtiofsd
binary was not valid anymore. Instead, the updated documentation now
describe how to build virtiofsd from source.
Fixes#491
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Update all references to the new repository locations. Many of these will
redirect however the one used for the hypervisor-fw binary does not so
this is required to allow the builds to pass.
Signed-off-by: Rob Bradford <robert.bradford@intel.com>
This commit introduces a dedicated document describing the device model
supported by cloud-hypervisor VMM.
It needs to be updated anytime a new device will be added in the future.
Fixes#437
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
The cloud-hypervisor supports the DAX shared region for better virtio-fs
performances, but it was not updated in the documentation. This commit
takes care of this and also update the mount command since it changed
with virtio-fs v0.3.
Fixes#433
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Based on recent update of the cloudguest image used by Cloud Hypervisor,
we identified some missing or incorrect details in the instructions.
This patch is here to fix those.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This patch extends the existing virtual IOMMU documentation, explaining
how the use of huge pages can drastically improve the VM boot time.
Particularly, how in case of nested VFIO, the impact is significant and
the rationales behind it.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Having the virtual IOMMU created with --iommu is one thing, but we also
need a way to decide if a VFIO device should be attached to the virtual
IOMMU or not. That's why we introduce an extra option "iommu" with the
value "on" or "off". By default, the device is not attached, which means
"iommu=off".
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This patch introduces a specific documentation for the virtual IOMMU
device. This is important to understand what the use cases are for this
new device and how to properly use it with virtio devices.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
Having the virtual IOMMU created with --iommu is one thing, but we also
need a way to decide if a virtio-blk device should be attached to this
virtual IOMMU or not. That's why we introduce an extra option "iommu"
with the value "on" or "off". By default, the device is not attached,
which means "iommu=off".
One side effect of this new option is that we had to introduce a new
option for the disk path, simply called "path=".
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This is a quick guide on how to create a custom Clear Linux image based
on the official tooling provided by Clear Linux. If for any reason, the
image we are using is missing some interesting bundles that are packaged
by Clear Linux, this documentation will be the guide on how to proceed.
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
