| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
======================================= |
| 4 |
Internal ABI between the kernel and HYP |
| 5 |
======================================= |
| 6 |
|
| 7 |
This file documents the interaction between the Linux kernel and the |
| 8 |
hypervisor layer when running Linux as a hypervisor (for example |
| 9 |
KVM). It doesn't cover the interaction of the kernel with the |
| 10 |
hypervisor when running as a guest (under Xen, KVM or any other |
| 11 |
hypervisor), or any hypervisor-specific interaction when the kernel is |
| 12 |
used as a host. |
| 13 |
|
| 14 |
Note: KVM/arm has been removed from the kernel. The API described |
| 15 |
here is still valid though, as it allows the kernel to kexec when |
| 16 |
booted at HYP. It can also be used by a hypervisor other than KVM |
| 17 |
if necessary. |
| 18 |
|
| 19 |
On arm and arm64 (without VHE), the kernel doesn't run in hypervisor |
| 20 |
mode, but still needs to interact with it, allowing a built-in |
| 21 |
hypervisor to be either installed or torn down. |
| 22 |
|
| 23 |
In order to achieve this, the kernel must be booted at HYP (arm) or |
| 24 |
EL2 (arm64), allowing it to install a set of stubs before dropping to |
| 25 |
SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction, |
| 26 |
and only act on individual CPUs. |
| 27 |
|
| 28 |
Unless specified otherwise, any built-in hypervisor must implement |
| 29 |
these functions (see arch/arm{,64}/include/asm/virt.h): |
| 30 |
|
| 31 |
* :: |
| 32 |
|
| 33 |
r0/x0 = HVC_SET_VECTORS |
| 34 |
r1/x1 = vectors |
| 35 |
|
| 36 |
Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors' |
| 37 |
must be a physical address, and respect the alignment requirements |
| 38 |
of the architecture. Only implemented by the initial stubs, not by |
| 39 |
Linux hypervisors. |
| 40 |
|
| 41 |
* :: |
| 42 |
|
| 43 |
r0/x0 = HVC_RESET_VECTORS |
| 44 |
|
| 45 |
Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials |
| 46 |
stubs' exception vector value. This effectively disables an existing |
| 47 |
hypervisor. |
| 48 |
|
| 49 |
* :: |
| 50 |
|
| 51 |
r0/x0 = HVC_SOFT_RESTART |
| 52 |
r1/x1 = restart address |
| 53 |
x2 = x0's value when entering the next payload (arm64) |
| 54 |
x3 = x1's value when entering the next payload (arm64) |
| 55 |
x4 = x2's value when entering the next payload (arm64) |
| 56 |
|
| 57 |
Mask all exceptions, disable the MMU, clear I+D bits, move the arguments |
| 58 |
into place (arm64 only), and jump to the restart address while at HYP/EL2. |
| 59 |
This hypercall is not expected to return to its caller. |
| 60 |
|
| 61 |
* :: |
| 62 |
|
| 63 |
x0 = HVC_FINALISE_EL2 (arm64 only) |
| 64 |
|
| 65 |
Finish configuring EL2 depending on the command-line options, |
| 66 |
including an attempt to upgrade the kernel's exception level from |
| 67 |
EL1 to EL2 by enabling the VHE mode. This is conditioned by the CPU |
| 68 |
supporting VHE, the EL2 MMU being off, and VHE not being disabled by |
| 69 |
any other means (command line option, for example). |
| 70 |
|
| 71 |
Any other value of r0/x0 triggers a hypervisor-specific handling, |
| 72 |
which is not documented here. |
| 73 |
|
| 74 |
The return value of a stub hypercall is held by r0/x0, and is 0 on |
| 75 |
success, and HVC_STUB_ERR on error. A stub hypercall is allowed to |
| 76 |
clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and |
| 77 |
ip on arm). It is thus recommended to use a function call to perform |
| 78 |
the hypercall. |