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