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 14Note: KVM/arm has been removed from the kernel. The API described 15here is still valid though, as it allows the kernel to kexec when 16booted at HYP. It can also be used by a hypervisor other than KVM 17if necessary. 18 19On arm and arm64 (without VHE), the kernel doesn't run in hypervisor 20mode, but still needs to interact with it, allowing a built-in 21hypervisor to be either installed or torn down. 22 23In order to achieve this, the kernel must be booted at HYP (arm) or 24EL2 (arm64), allowing it to install a set of stubs before dropping to 25SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction, 26and only act on individual CPUs. 27 28Unless specified otherwise, any built-in hypervisor must implement 29these 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 71Any other value of r0/x0 triggers a hypervisor-specific handling, 72which is not documented here. 73 74The return value of a stub hypercall is held by r0/x0, and is 0 on 75success, and HVC_STUB_ERR on error. A stub hypercall is allowed to 76clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and 77ip on arm). It is thus recommended to use a function call to perform 78the hypercall. 79