0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======================================
0004 Internal ABI between the kernel and HYP
0005 =======================================
0006
0007 This file documents the interaction between the Linux kernel and the
0008 hypervisor layer when running Linux as a hypervisor (for example
0009 KVM). It doesn't cover the interaction of the kernel with the
0010 hypervisor when running as a guest (under Xen, KVM or any other
0011 hypervisor), or any hypervisor-specific interaction when the kernel is
0012 used as a host.
0013
0014 Note: KVM/arm has been removed from the kernel. The API described
0015 here is still valid though, as it allows the kernel to kexec when
0016 booted at HYP. It can also be used by a hypervisor other than KVM
0017 if necessary.
0018
0019 On arm and arm64 (without VHE), the kernel doesn't run in hypervisor
0020 mode, but still needs to interact with it, allowing a built-in
0021 hypervisor to be either installed or torn down.
0022
0023 In order to achieve this, the kernel must be booted at HYP (arm) or
0024 EL2 (arm64), allowing it to install a set of stubs before dropping to
0025 SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction,
0026 and only act on individual CPUs.
0027
0028 Unless specified otherwise, any built-in hypervisor must implement
0029 these functions (see arch/arm{,64}/include/asm/virt.h):
0030
0031 * ::
0032
0033 r0/x0 = HVC_SET_VECTORS
0034 r1/x1 = vectors
0035
0036 Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors'
0037 must be a physical address, and respect the alignment requirements
0038 of the architecture. Only implemented by the initial stubs, not by
0039 Linux hypervisors.
0040
0041 * ::
0042
0043 r0/x0 = HVC_RESET_VECTORS
0044
0045 Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials
0046 stubs' exception vector value. This effectively disables an existing
0047 hypervisor.
0048
0049 * ::
0050
0051 r0/x0 = HVC_SOFT_RESTART
0052 r1/x1 = restart address
0053 x2 = x0's value when entering the next payload (arm64)
0054 x3 = x1's value when entering the next payload (arm64)
0055 x4 = x2's value when entering the next payload (arm64)
0056
0057 Mask all exceptions, disable the MMU, clear I+D bits, move the arguments
0058 into place (arm64 only), and jump to the restart address while at HYP/EL2.
0059 This hypercall is not expected to return to its caller.
0060
0061 * ::
0062
0063 x0 = HVC_FINALISE_EL2 (arm64 only)
0064
0065 Finish configuring EL2 depending on the command-line options,
0066 including an attempt to upgrade the kernel's exception level from
0067 EL1 to EL2 by enabling the VHE mode. This is conditioned by the CPU
0068 supporting VHE, the EL2 MMU being off, and VHE not being disabled by
0069 any other means (command line option, for example).
0070
0071 Any other value of r0/x0 triggers a hypervisor-specific handling,
0072 which is not documented here.
0073
0074 The return value of a stub hypercall is held by r0/x0, and is 0 on
0075 success, and HVC_STUB_ERR on error. A stub hypercall is allowed to
0076 clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and
0077 ip on arm). It is thus recommended to use a function call to perform
0078 the hypercall.
