1.. SPDX-License-Identifier: GPL-2.0 2 3================= 4Gunyah Hypervisor 5================= 6 7.. toctree:: 8 :maxdepth: 1 9 10 message-queue 11 12Gunyah is a Type-1 hypervisor which is independent of any OS kernel, and runs in 13a more privileged CPU level (EL2 on Aarch64). It does not depend on a less 14privileged operating system for its core functionality. This increases its 15security and can support a much smaller trusted computing base than a Type-2 16hypervisor. 17 18Gunyah is an open source hypervisor. The source repository 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 which can coexist on 27 a running system: 28 29 1. Hypervisor vCPU scheduling in which Gunyah hypervisor schedules vCPUS on 30 its own. The default is a real-time priority with round-robin scheduler. 31 2. "Proxy" scheduling in which an owner-VM can donate the remainder of its 32 own vCPU's time slice to an owned-VM's vCPU via a hypercall. 33 34- Memory Management: 35 36 APIs handling memory, abstracted as objects, limiting direct use of physical 37 addresses. Memory ownership and usage tracking of all memory under its control. 38 Memory partitioning between VMs is a fundamental security feature. 39 40- Interrupt Virtualization: 41 42 Interrupt ownership is tracked and interrupt delivery is directly to the 43 assigned VM. Gunyah makes use of hardware interrupt virtualization where 44 possible. 45 46- Inter-VM Communication: 47 48 There are several different mechanisms provided for communicating between VMs. 49 50 1. Message queues 51 2. Doorbells 52 3. Virtio MMIO transport 53 4. Shared memory 54 55- Virtual platform: 56 57 Architectural devices such as interrupt controllers and CPU timers are 58 directly provided by the hypervisor as well as core virtual platform devices 59 and system APIs such as ARM PSCI. 60 61- Device Virtualization: 62 63 Para-virtualization of devices is supported using inter-VM communication and 64 virtio transport support. Select stage 2 faults by virtual machines that use 65 proxy-scheduled vCPUs can be handled directly by Linux to provide Type-2 66 hypervisor style on-demand paging and/or device emulation. 67 68Architectures supported 69======================= 70AArch64 with a GICv3 or GICv4.1 71 72Resources and Capabilities 73========================== 74 75Services/resources provided by the Gunyah hypervisor are accessible to a 76virtual machine through capabilities. A capability is an access control 77token granting the holder a set of permissions to operate on a specific 78hypervisor object (conceptually similar to a file-descriptor). 79For example, inter-VM communication using Gunyah doorbells and message queues 80is performed using hypercalls taking Capability ID arguments for the required 81IPC objects. These resources are described in Linux as a struct gunyah_resource. 82 83Unlike UNIX file descriptors, there is no path-based or similar lookup of 84an object to create a new Capability, meaning simpler security analysis. 85Creation of a new Capability requires the holding of a set of privileged 86Capabilities which are typically never given out by the Resource Manager (RM). 87 88Gunyah itself provides no APIs for Capability ID discovery. Enumeration of 89Capability IDs is provided by RM as a higher level service to VMs. 90 91Resource Manager 92================ 93 94The Gunyah Resource Manager (RM) is a privileged application VM supporting the 95Gunyah Hypervisor. It provides policy enforcement aspects of the virtualization 96system. The resource manager can be treated as an extension of the Hypervisor 97but is separated to its own partition to ensure that the hypervisor layer itself 98remains small and secure and to maintain a separation of policy and mechanism in 99the platform. The resource manager runs at arm64 NS-EL1, similar to other 100virtual machines. 101 102Communication with the resource manager from other virtual machines happens as 103described in message-queue.rst. Details about the specific messages can be found 104in drivers/virt/gunyah/rsc_mgr.c 105 106:: 107 108 +-------+ +--------+ +--------+ 109 | RM | | VM_A | | VM_B | 110 +-.-.-.-+ +---.----+ +---.----+ 111 | | | | 112 +-.-.-----------.------------.----+ 113 | | \==========/ | | 114 | \========================/ | 115 | Gunyah | 116 +---------------------------------+ 117 118The source for the resource manager is available at 119https://github.com/quic/gunyah-resource-manager. 120 121The resource manager provides the following features: 122 123- VM lifecycle management: allocating a VM, starting VMs, destruction of VMs 124- VM access control policy, including memory sharing and lending 125- Interrupt routing configuration 126- Forwarding of system-level events (e.g. VM shutdown) to owner VM 127- Resource (capability) discovery 128 129A VM requires boot configuration to establish communication with the resource 130manager. This is provided to VMs via a 'hypervisor' device tree node which is 131overlaid to the VMs DT by the RM. This node lets guests know they are running 132as a Gunyah guest VM, how to communicate with resource manager, and basic 133description and capabilities of this VM. See 134Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml for a 135description of this node. 136