1.. SPDX-License-Identifier: GPL-2.0 2 3======================= 4Virtual Machine Manager 5======================= 6 7The Gunyah Virtual Machine Manager is a Linux driver to support launching 8virtual machines using Gunyah. 9 10Configuration of a Gunyah virtual machine is done via a devicetree. When the VM 11is launched, memory is provided by the host VM which contains the devictree. 12Gunyah reads the devicetree to configure the memory map and create resources 13such as vCPUs for the VM. Memory can be shared with the VM with 14`GH_VM_SET_USER_MEM_REGION`_. Userspace can interact with the resources in Linux 15by adding "functions" to the VM. 16 17Gunyah Functions 18================ 19 20Components of a Gunyah VM's configuration that need kernel configuration are 21called "functions" and are built on top of a framework. Functions are identified 22by a string and have some argument(s) to configure them. They are typically 23created by the `GH_VM_ADD_FUNCTION`_ ioctl. 24 25Functions typically will always do at least one of these operations: 26 271. Create resource ticket(s). Resource tickets allow a function to register 28 itself as the client for a Gunyah resource (e.g. doorbell or vCPU) and 29 the function is given the pointer to the &struct gh_resource when the 30 VM is starting. 31 322. Register IO handler(s). IO handlers allow a function to handle stage-2 faults 33 from the virtual machine. 34 35Sample Userspace VMM 36==================== 37 38A sample userspace VMM is included in samples/gunyah/ along with a minimal 39devicetree that can be used to launch a VM. To build this sample, enable 40CONFIG_SAMPLE_GUNYAH. 41 42IOCTLs and userspace VMM flows 43============================== 44 45The kernel exposes a char device interface at /dev/gunyah. 46 47To create a VM, use the `GH_CREATE_VM`_ ioctl. A successful call will return a 48"Gunyah VM" file descriptor. 49 50/dev/gunyah API Descriptions 51---------------------------- 52 53GH_CREATE_VM 54~~~~~~~~~~~~ 55 56Creates a Gunyah VM. The argument is reserved for future use and must be 0. 57A successful call will return a Gunyah VM file descriptor. See 58`Gunyah VM API Descriptions`_ for list of IOCTLs that can be made on this file 59file descriptor. 60 61Gunyah VM API Descriptions 62-------------------------- 63 64GH_VM_SET_USER_MEM_REGION 65~~~~~~~~~~~~~~~~~~~~~~~~~ 66 67This ioctl allows the user to create or delete a memory parcel for a guest 68virtual machine. Each memory region is uniquely identified by a label; 69attempting to create two regions with the same label is not allowed. Labels are 70unique per virtual machine. 71 72While VMM is guest-agnostic and allows runtime addition of memory regions, 73Linux guest virtual machines do not support accepting memory regions at runtime. 74Thus, for Linux guests, memory regions should be provided before starting the VM 75and the VM must be configured via the devicetree to accept these at boot-up. 76 77The guest physical address is used by Linux kernel to check that the requested 78user regions do not overlap and to help find the corresponding memory region 79for calls like `GH_VM_SET_DTB_CONFIG`_. It must be page aligned. 80 81To add a memory region, call `GH_VM_SET_USER_MEM_REGION`_ with fields set as 82described above. 83 84.. kernel-doc:: include/uapi/linux/gunyah.h 85 :identifiers: gh_userspace_memory_region gh_mem_flags 86 87GH_VM_SET_DTB_CONFIG 88~~~~~~~~~~~~~~~~~~~~ 89 90This ioctl sets the location of the VM's devicetree blob and is used by Gunyah 91Resource Manager to allocate resources. The guest physical memory must be part 92of the primary memory parcel provided to the VM prior to GH_VM_START. 93 94.. kernel-doc:: include/uapi/linux/gunyah.h 95 :identifiers: gh_vm_dtb_config 96 97GH_VM_START 98~~~~~~~~~~~ 99 100This ioctl starts the VM. 101 102GH_VM_ADD_FUNCTION 103~~~~~~~~~~~~~~~~~~ 104 105This ioctl registers a Gunyah VM function with the VM manager. The VM function 106is described with a &struct gh_fn_desc.type and some arguments for that type. 107Typically, the function is added before the VM starts, but the function doesn't 108"operate" until the VM starts with `GH_VM_START`_. For example, vCPU ioctls will 109all return an error until the VM starts because the vCPUs don't exist until the 110VM is started. This allows the VMM to set up all the kernel functions needed for 111the VM *before* the VM starts. 112 113.. kernel-doc:: include/uapi/linux/gunyah.h 114 :identifiers: gh_fn_desc gh_fn_type 115 116The argument types are documented below: 117 118.. kernel-doc:: include/uapi/linux/gunyah.h 119 :identifiers: gh_fn_vcpu_arg gh_fn_irqfd_arg gh_irqfd_flags gh_fn_ioeventfd_arg gh_ioeventfd_flags 120 121Gunyah VCPU API Descriptions 122---------------------------- 123 124A vCPU file descriptor is created after calling `GH_VM_ADD_FUNCTION` with the type `GH_FN_VCPU`. 125 126GH_VCPU_RUN 127~~~~~~~~~~~ 128 129This ioctl is used to run a guest virtual cpu. While there are no 130explicit parameters, there is an implicit parameter block that can be 131obtained by mmap()ing the vcpu fd at offset 0, with the size given by 132`GH_VCPU_MMAP_SIZE`_. The parameter block is formatted as a 'struct 133gh_vcpu_run' (see below). 134 135GH_VCPU_MMAP_SIZE 136~~~~~~~~~~~~~~~~~ 137 138The `GH_VCPU_RUN`_ ioctl communicates with userspace via a shared 139memory region. This ioctl returns the size of that region. See the 140`GH_VCPU_RUN`_ documentation for details. 141 142.. kernel-doc:: include/uapi/linux/gunyah.h 143 :identifiers: gh_vcpu_exit gh_vcpu_run gh_vm_status gh_vm_exit_info 144