1.. SPDX-License-Identifier: GPL-2.0 2 3================= 4Gunyah Hypervisor 5================= 6 7.. toctree:: 8 :maxdepth: 1 9 10 vm-manager 11 message-queue 12 13Gunyah is a Type-1 hypervisor which is independent of any OS kernel, and runs in 14a higher CPU privilege level. It does not depend on any lower-privileged operating system 15for its core functionality. This increases its security and can support a much smaller 16trusted computing base than a Type-2 hypervisor. 17 18Gunyah is an open source hypervisor. The source repo is available at 19https://github.com/quic/gunyah-hypervisor. 20 21Gunyah provides these following features. 22 23- Scheduling: 24 25 A scheduler for virtual CPUs (vCPUs) on physical CPUs enables time-sharing 26 of the CPUs. Gunyah supports two models of scheduling: 27 28 1. "Behind the back" scheduling in which Gunyah hypervisor schedules vCPUS on its own. 29 2. "Proxy" scheduling in which a delegated VM can donate part of one of its vCPU slice 30 to another VM's vCPU via a hypercall. 31 32- Memory Management: 33 34 APIs handling memory, abstracted as objects, limiting direct use of physical 35 addresses. Memory ownership and usage tracking of all memory under its control. 36 Memory partitioning between VMs is a fundamental security feature. 37 38- Interrupt Virtualization: 39 40 Uses CPU hardware interrupt virtualization capabilities. Interrupts are handled 41 in the hypervisor and routed to the assigned VM. 42 43- Inter-VM Communication: 44 45 There are several different mechanisms provided for communicating between VMs. 46 47- Virtual platform: 48 49 Architectural devices such as interrupt controllers and CPU timers are directly provided 50 by the hypervisor as well as core virtual platform devices and system APIs such as ARM PSCI. 51 52- Device Virtualization: 53 54 Para-virtualization of devices is supported using inter-VM communication. 55 56Architectures supported 57======================= 58AArch64 with a GIC 59 60Resources and Capabilities 61========================== 62 63Some services or resources provided by the Gunyah hypervisor are described to a virtual machine by 64capability IDs. For instance, inter-VM communication is performed with doorbells and message queues. 65Gunyah allows access to manipulate that doorbell via the capability ID. These resources are 66described in Linux as a struct gh_resource. 67 68High level management of these resources is performed by the resource manager VM. RM informs a 69guest VM about resources it can access through either the device tree or via guest-initiated RPC. 70 71For each virtual machine, Gunyah maintains a table of resources which can be accessed by that VM. 72An entry in this table is called a "capability" and VMs can only access resources via this 73capability table. Hence, virtual Gunyah resources are referenced by a "capability IDs" and not 74"resource IDs". If 2 VMs have access to the same resource, they might not be using the same 75capability ID to access that resource since the capability tables are independent per VM. 76 77Resource Manager 78================ 79 80The resource manager (RM) is a privileged application VM supporting the Gunyah Hypervisor. 81It provides policy enforcement aspects of the virtualization system. The resource manager can 82be treated as an extension of the Hypervisor but is separated to its own partition to ensure 83that the hypervisor layer itself remains small and secure and to maintain a separation of policy 84and mechanism in the platform. RM runs at arm64 NS-EL1 similar to other virtual machines. 85 86Communication with the resource manager from each guest VM happens with message-queue.rst. Details 87about the specific messages can be found in drivers/virt/gunyah/rsc_mgr.c 88 89:: 90 91 +-------+ +--------+ +--------+ 92 | RM | | VM_A | | VM_B | 93 +-.-.-.-+ +---.----+ +---.----+ 94 | | | | 95 +-.-.-----------.------------.----+ 96 | | \==========/ | | 97 | \========================/ | 98 | Gunyah | 99 +---------------------------------+ 100 101The source for the resource manager is available at https://github.com/quic/gunyah-resource-manager. 102 103The resource manager provides the following features: 104 105- VM lifecycle management: allocating a VM, starting VMs, destruction of VMs 106- VM access control policy, including memory sharing and lending 107- Interrupt routing configuration 108- Forwarding of system-level events (e.g. VM shutdown) to owner VM 109 110When booting a virtual machine which uses a devicetree such as Linux, resource manager overlays a 111/hypervisor node. This node can let Linux know it is running as a Gunyah guest VM, 112how to communicate with resource manager, and basic description and capabilities of 113this VM. See Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml for a description 114of this node. 115