Orange Pi5 kernel

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