Documentation/virt/kvm/arm/hyp-abi.rst

   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.