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