Document the ioctls and usage of Gunyah VM Manager driver. Signed-off-by: Elliot Berman <quic_eberman@xxxxxxxxxxx> --- Documentation/virt/gunyah/index.rst | 1 + Documentation/virt/gunyah/vm-manager.rst | 82 ++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 Documentation/virt/gunyah/vm-manager.rst diff --git a/Documentation/virt/gunyah/index.rst b/Documentation/virt/gunyah/index.rst index 74aa345e0a14..7058249825b1 100644 --- a/Documentation/virt/gunyah/index.rst +++ b/Documentation/virt/gunyah/index.rst @@ -7,6 +7,7 @@ Gunyah Hypervisor .. toctree:: :maxdepth: 1 + vm-manager message-queue Gunyah is a Type-1 hypervisor which is independent of any OS kernel, and runs in diff --git a/Documentation/virt/gunyah/vm-manager.rst b/Documentation/virt/gunyah/vm-manager.rst new file mode 100644 index 000000000000..50d8ae7fabcd --- /dev/null +++ b/Documentation/virt/gunyah/vm-manager.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Virtual Machine Manager +======================= + +The Gunyah Virtual Machine Manager is a Linux driver to support launching +virtual machines using Gunyah. It presently supports launching non-proxy +scheduled Linux-like virtual machines. + +Except for some basic information about the location of initial binaries, +most of the configuration about a Gunyah virtual machine is described in the +VM's devicetree. The devicetree is generated by userspace. Interacting with the +virtual machine is still done via the kernel and VM configuration requires some +of the corresponding functionality to be set up in the kernel. For instance, +sharing userspace memory with a VM is done via the `GH_VM_SET_USER_MEM_REGION`_ +ioctl. The VM itself is configured to use the memory region via the +devicetree. + +Sample Userspace VMM +==================== + +A sample userspace VMM is included in samples/gunyah/ along with a minimal +devicetree that can be used to launch a VM. To build this sample, enable +CONFIG_SAMPLE_GUNYAH. + +IOCTLs and userspace VMM flows +============================== + +The kernel exposes a char device interface at /dev/gunyah. + +To create a VM, use the `GH_CREATE_VM`_ ioctl. A successful call will return a +"Gunyah VM" file descriptor. + +/dev/gunyah API Descriptions +---------------------------- + +GH_CREATE_VM +~~~~~~~~~~~~ + +Creates a Gunyah VM. The argument is reserved for future use and must be 0. + +Gunyah VM API Descriptions +-------------------------- + +GH_VM_SET_USER_MEM_REGION +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This ioctl allows the user to create or delete a memory parcel for a guest +virtual machine. Each memory region is uniquely identified by a label; +attempting to create two regions with the same label is not allowed. Labels are +unique per virtual machine. + +While VMM is guest-agnostic and allows runtime addition of memory regions, +Linux guest virtual machines do not support accepting memory regions at runtime. +Thus, memory regions should be provided before starting the VM and the VM must +be configured to accept these at boot-up. + +The guest physical address is used by Linux kernel to check that the requested +user regions do not overlap and to help find the corresponding memory region +for calls like `GH_VM_SET_DTB_CONFIG`_. It must be page aligned. + +To add a memory region, call `GH_VM_SET_USER_MEM_REGION`_ with fields set as +described above. + +.. kernel-doc:: include/uapi/linux/gunyah.h + :identifiers: gh_userspace_memory_region gh_mem_flags + +GH_VM_SET_DTB_CONFIG +~~~~~~~~~~~~~~~~~~~~ + +This ioctl sets the location of the VM's devicetree blob and is used by Gunyah +Resource Manager to allocate resources. The guest physical memory should be part +of the primary memory parcel provided to the VM prior to GH_VM_START. + +.. kernel-doc:: include/uapi/linux/gunyah.h + :identifiers: gh_vm_dtb_config + +GH_VM_START +~~~~~~~~~~~ + +This ioctl starts the VM. -- 2.40.0