mirror of
https://github.com/hardkernel/linux.git
synced 2026-06-06 10:58:48 +09:00
FROMLIST: docs: gunyah: Introduce Gunyah Hypervisor
Gunyah is an open-source Type-1 hypervisor developed by Qualcomm. It does not depend on any lower-privileged OS/kernel code for its core functionality. This increases its security and can support a smaller trusted computing based when compared to Type-2 hypervisors. Add documentation describing the Gunyah hypervisor and the main components of the Gunyah hypervisor which are of interest to Linux virtualization development. Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Change-Id: I471b5ad02732f25e35efe033cd281025c84d0f09 Signed-off-by: Elliot Berman <quic_eberman@quicinc.com> Bug: 268234781 Link: https://lore.kernel.org/all/20230304010632.2127470-2-quic_eberman@quicinc.com/
This commit is contained in:
Elliot Berman
committed by
Aleksei Vetrov
Aleksei Vetrov
parent
f72d338c3d
commit
de3283f904
113
Documentation/virt/gunyah/index.rst
Normal file
113
Documentation/virt/gunyah/index.rst
Normal file
@@ -0,0 +1,113 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
=================
|
||||
Gunyah Hypervisor
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
message-queue
|
||||
|
||||
Gunyah is a Type-1 hypervisor which is independent of any OS kernel, and runs in
|
||||
a higher CPU privilege level. It does not depend on any lower-privileged operating system
|
||||
for its core functionality. This increases its security and can support a much smaller
|
||||
trusted computing base than a Type-2 hypervisor.
|
||||
|
||||
Gunyah is an open source hypervisor. The source repo is available at
|
||||
https://github.com/quic/gunyah-hypervisor.
|
||||
|
||||
Gunyah provides these following features.
|
||||
|
||||
- Scheduling:
|
||||
|
||||
A scheduler for virtual CPUs (vCPUs) on physical CPUs enables time-sharing
|
||||
of the CPUs. Gunyah supports two models of scheduling:
|
||||
|
||||
1. "Behind the back" scheduling in which Gunyah hypervisor schedules vCPUS on its own.
|
||||
2. "Proxy" scheduling in which a delegated VM can donate part of one of its vCPU slice
|
||||
to another VM's vCPU via a hypercall.
|
||||
|
||||
- Memory Management:
|
||||
|
||||
APIs handling memory, abstracted as objects, limiting direct use of physical
|
||||
addresses. Memory ownership and usage tracking of all memory under its control.
|
||||
Memory partitioning between VMs is a fundamental security feature.
|
||||
|
||||
- Interrupt Virtualization:
|
||||
|
||||
Uses CPU hardware interrupt virtualization capabilities. Interrupts are handled
|
||||
in the hypervisor and routed to the assigned VM.
|
||||
|
||||
- Inter-VM Communication:
|
||||
|
||||
There are several different mechanisms provided for communicating between VMs.
|
||||
|
||||
- Virtual platform:
|
||||
|
||||
Architectural devices such as interrupt controllers and CPU timers are directly provided
|
||||
by the hypervisor as well as core virtual platform devices and system APIs such as ARM PSCI.
|
||||
|
||||
- Device Virtualization:
|
||||
|
||||
Para-virtualization of devices is supported using inter-VM communication.
|
||||
|
||||
Architectures supported
|
||||
=======================
|
||||
AArch64 with a GIC
|
||||
|
||||
Resources and Capabilities
|
||||
==========================
|
||||
|
||||
Some services or resources provided by the Gunyah hypervisor are described to a virtual machine by
|
||||
capability IDs. For instance, inter-VM communication is performed with doorbells and message queues.
|
||||
Gunyah allows access to manipulate that doorbell via the capability ID. These resources are
|
||||
described in Linux as a struct gh_resource.
|
||||
|
||||
High level management of these resources is performed by the resource manager VM. RM informs a
|
||||
guest VM about resources it can access through either the device tree or via guest-initiated RPC.
|
||||
|
||||
For each virtual machine, Gunyah maintains a table of resources which can be accessed by that VM.
|
||||
An entry in this table is called a "capability" and VMs can only access resources via this
|
||||
capability table. Hence, virtual Gunyah resources are referenced by a "capability IDs" and not
|
||||
"resource IDs". If 2 VMs have access to the same resource, they might not be using the same
|
||||
capability ID to access that resource since the capability tables are independent per VM.
|
||||
|
||||
Resource Manager
|
||||
================
|
||||
|
||||
The resource manager (RM) is a privileged application VM supporting the Gunyah Hypervisor.
|
||||
It provides policy enforcement aspects of the virtualization system. The resource manager can
|
||||
be treated as an extension of the Hypervisor but is separated to its own partition to ensure
|
||||
that the hypervisor layer itself remains small and secure and to maintain a separation of policy
|
||||
and mechanism in the platform. RM runs at arm64 NS-EL1 similar to other virtual machines.
|
||||
|
||||
Communication with the resource manager from each guest VM happens with message-queue.rst. Details
|
||||
about the specific messages can be found in drivers/virt/gunyah/rsc_mgr.c
|
||||
|
||||
::
|
||||
|
||||
+-------+ +--------+ +--------+
|
||||
| RM | | VM_A | | VM_B |
|
||||
+-.-.-.-+ +---.----+ +---.----+
|
||||
| | | |
|
||||
+-.-.-----------.------------.----+
|
||||
| | \==========/ | |
|
||||
| \========================/ |
|
||||
| Gunyah |
|
||||
+---------------------------------+
|
||||
|
||||
The source for the resource manager is available at https://github.com/quic/gunyah-resource-manager.
|
||||
|
||||
The resource manager provides the following features:
|
||||
|
||||
- VM lifecycle management: allocating a VM, starting VMs, destruction of VMs
|
||||
- VM access control policy, including memory sharing and lending
|
||||
- Interrupt routing configuration
|
||||
- Forwarding of system-level events (e.g. VM shutdown) to owner VM
|
||||
|
||||
When booting a virtual machine which uses a devicetree such as Linux, resource manager overlays a
|
||||
/hypervisor node. This node can let Linux know it is running as a Gunyah guest VM,
|
||||
how to communicate with resource manager, and basic description and capabilities of
|
||||
this VM. See Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml for a description
|
||||
of this node.
|
||||
63
Documentation/virt/gunyah/message-queue.rst
Normal file
63
Documentation/virt/gunyah/message-queue.rst
Normal file
@@ -0,0 +1,63 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
Message Queues
|
||||
==============
|
||||
Message queue is a simple low-capacity IPC channel between two VMs. It is
|
||||
intended for sending small control and configuration messages. Each message
|
||||
queue is unidirectional, so a full-duplex IPC channel requires a pair of queues.
|
||||
|
||||
Messages can be up to 240 bytes in length. Longer messages require a further
|
||||
protocol on top of the message queue messages themselves. For instance, communication
|
||||
with the resource manager adds a header field for sending longer messages via multiple
|
||||
message fragments.
|
||||
|
||||
The diagram below shows how message queue works. A typical configuration involves
|
||||
2 message queues. Message queue 1 allows VM_A to send messages to VM_B. Message
|
||||
queue 2 allows VM_B to send messages to VM_A.
|
||||
|
||||
1. VM_A sends a message of up to 240 bytes in length. It raises a hypercall
|
||||
with the message to inform the hypervisor to add the message to
|
||||
message queue 1's queue. The hypervisor copies memory into the internal
|
||||
message queue representation; the memory doesn't need to be shared between
|
||||
VM_A and VM_B.
|
||||
|
||||
2. Gunyah raises the corresponding interrupt for VM_B (Rx vIRQ) when any of
|
||||
these happens:
|
||||
|
||||
a. gh_msgq_send() has PUSH flag. Queue is immediately flushed. This is the typical case.
|
||||
b. Explicility with gh_msgq_push command from VM_A.
|
||||
c. Message queue has reached a threshold depth.
|
||||
|
||||
3. VM_B calls gh_msgq_recv() and Gunyah copies message to requested buffer.
|
||||
|
||||
4. Gunyah buffers messages in the queue. If the queue became full when VM_A added a message,
|
||||
the return values for gh_msgq_send() include a flag that indicates the queue is full.
|
||||
Once VM_B receives the message and, thus, there is space in the queue, Gunyah
|
||||
will raise the Tx vIRQ on VM_A to indicate it can continue sending messages.
|
||||
|
||||
For VM_B to send a message to VM_A, the process is identical, except that hypercalls
|
||||
reference message queue 2's capability ID. Each message queue has its own independent
|
||||
vIRQ: two TX message queues will have two vIRQs (and two capability IDs).
|
||||
|
||||
::
|
||||
|
||||
+---------------+ +-----------------+ +---------------+
|
||||
| VM_A | |Gunyah hypervisor| | VM_B |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
| | Tx | | | |
|
||||
| |-------->| | Rx vIRQ | |
|
||||
|gh_msgq_send() | Tx vIRQ |Message queue 1 |-------->|gh_msgq_recv() |
|
||||
| |<------- | | | |
|
||||
| | | | | |
|
||||
| Message Queue | | | | Message Queue |
|
||||
| driver | | | | driver |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
| | | | Tx | |
|
||||
| | Rx vIRQ | |<--------| |
|
||||
|gh_msgq_recv() |<--------|Message queue 2 | Tx vIRQ |gh_msgq_send() |
|
||||
| | | |-------->| |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
+---------------+ +-----------------+ +---------------+
|
||||
@@ -15,6 +15,7 @@ Linux Virtualization Support
|
||||
acrn/index
|
||||
coco/sev-guest
|
||||
hyperv/index
|
||||
gunyah/index
|
||||
|
||||
.. only:: html and subproject
|
||||
|
||||
|
||||
Reference in New Issue
Block a user