mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-05-31 11:25:30 +00:00
71 lines
3.0 KiB
ReStructuredText
71 lines
3.0 KiB
ReStructuredText
.. _hv-hypercall:
|
|
|
|
Hypercall / HSM Upcall
|
|
######################
|
|
|
|
The hypercall/upcall is used to request services between the guest VM and the
|
|
hypervisor. The hypercall is from the guest VM to the hypervisor, and the upcall
|
|
is from the hypervisor to the guest VM. The hypervisor supports
|
|
hypercall APIs for VM management, I/O request distribution, interrupt injection,
|
|
PCI assignment, guest memory mapping, power management, and secure world switch.
|
|
|
|
The application binary interface (ABI) of ACRN hypercalls is defined as follows.
|
|
|
|
- A guest VM executes the ``vmcall`` instruction to trigger a hypercall.
|
|
|
|
- Input parameters of a hypercall include:
|
|
|
|
- A hypercall ID in register ``R8``, which specifies the kind of service
|
|
requested by the guest VM.
|
|
|
|
- The first parameter in register ``RDI`` and the second in register
|
|
``RSI``. The semantics of those two parameters vary among different kinds of
|
|
hypercalls and are defined in the :ref:`hv-hypercall-ref`. For hypercalls
|
|
requesting operations on a specific VM, the first parameter is typically the
|
|
ID of that VM.
|
|
|
|
- The register ``RAX`` contains the return value of the hypercall after a guest
|
|
VM executes the ``vmcall`` instruction, unless the ``vmcall`` instruction
|
|
triggers an exception. Other general-purpose registers are not modified by a
|
|
hypercall.
|
|
|
|
- If a hypercall parameter is defined as a pointer to a data structure,
|
|
fields in that structure can be either input, output, or inout.
|
|
|
|
There are some restrictions for hypercalls and upcalls:
|
|
|
|
#. Only specific VMs (the Service VM and the VM with Trusty enabled)
|
|
can invoke hypercalls. A VM that cannot invoke hypercalls gets ``#UD``
|
|
(invalid opcode exception).
|
|
#. Only ring 0 hypercalls from the guest VM are handled by the hypervisor;
|
|
otherwise, the hypervisor injects ``#GP(0)`` (generation protection
|
|
exception with error code ``0``) to the guest VM.
|
|
#. Each VM is permitted to invoke a certain subset of hypercalls. A VM
|
|
with Trusty enabled is allowed to invoke Trusty hypercalls, and the Service
|
|
VM is allowed to invoke the other hypercalls. A VM that invokes an
|
|
unpermitted hypercall gets the return value ``-EINVAL``.
|
|
See :ref:`secure-hypervisor-interface` for a detailed description.
|
|
#. The hypervisor needs to protect the critical resources such as global VM and
|
|
vCPU structures for VM and vCPU management hypercalls.
|
|
#. Upcall is only used for the Service VM.
|
|
|
|
|
|
The hypervisor and Service VM both use the same vector (0xF3), which is reserved
|
|
as the x86 platform IPI vector for hypervisor notification to the Service VM.
|
|
This upcall is necessary whenever there is a device emulation requirement to the
|
|
Service VM. The upcall vector (0xF3) is injected to Service VM vCPU0. The
|
|
Service VM registers the IRQ handler for vector (0xF3) and notifies the I/O
|
|
emulation module in the Service VM once the IRQ is triggered. View the detailed
|
|
upcall process at :ref:`ipi-management`.
|
|
|
|
.. _hv-hypercall-ref:
|
|
|
|
Hypercall APIs Reference
|
|
************************
|
|
|
|
:ref:`hypercall_apis` for the Service VM
|
|
|
|
:ref:`trusty-hypercalls` for Trusty
|
|
|
|
|