Documentation/virt/kvm/arm/hypercalls.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======================
   4 ARM Hypercall Interface
   5 =======================
   6
   7 KVM handles the hypercall services as requested by the guests. New hypercall
   8 services are regularly made available by the ARM specification or by KVM (as
   9 vendor services) if they make sense from a virtualization point of view.
  10
  11 This means that a guest booted on two different versions of KVM can observe
  12 two different "firmware" revisions. This could cause issues if a given guest
  13 is tied to a particular version of a hypercall service, or if a migration
  14 causes a different version to be exposed out of the blue to an unsuspecting
  15 guest.
  16
  17 In order to remedy this situation, KVM exposes a set of "firmware
  18 pseudo-registers" that can be manipulated using the GET/SET_ONE_REG
  19 interface. These registers can be saved/restored by userspace, and set
  20 to a convenient value as required.
  21
  22 The following registers are defined:
  23
  24 * KVM_REG_ARM_PSCI_VERSION:
  25
  26   KVM implements the PSCI (Power State Coordination Interface)
  27   specification in order to provide services such as CPU on/off, reset
  28   and power-off to the guest.
  29
  30   - Only valid if the vcpu has the KVM_ARM_VCPU_PSCI_0_2 feature set
  31     (and thus has already been initialized)
  32   - Returns the current PSCI version on GET_ONE_REG (defaulting to the
  33     highest PSCI version implemented by KVM and compatible with v0.2)
  34   - Allows any PSCI version implemented by KVM and compatible with
  35     v0.2 to be set with SET_ONE_REG
  36   - Affects the whole VM (even if the register view is per-vcpu)
  37
  38 * KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1:
  39     Holds the state of the firmware support to mitigate CVE-2017-5715, as
  40     offered by KVM to the guest via a HVC call. The workaround is described
  41     under SMCCC_ARCH_WORKAROUND_1 in [1].
  42
  43   Accepted values are:
  44
  45     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_AVAIL:
  46       KVM does not offer
  47       firmware support for the workaround. The mitigation status for the
  48       guest is unknown.
  49     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_AVAIL:
  50       The workaround HVC call is
  51       available to the guest and required for the mitigation.
  52     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_REQUIRED:
  53       The workaround HVC call
  54       is available to the guest, but it is not needed on this VCPU.
  55
  56 * KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2:
  57     Holds the state of the firmware support to mitigate CVE-2018-3639, as
  58     offered by KVM to the guest via a HVC call. The workaround is described
  59     under SMCCC_ARCH_WORKAROUND_2 in [1]_.
  60
  61   Accepted values are:
  62
  63     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_AVAIL:
  64       A workaround is not
  65       available. KVM does not offer firmware support for the workaround.
  66     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_UNKNOWN:
  67       The workaround state is
  68       unknown. KVM does not offer firmware support for the workaround.
  69     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_AVAIL:
  70       The workaround is available,
  71       and can be disabled by a vCPU. If
  72       KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_ENABLED is set, it is active for
  73       this vCPU.
  74     KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED:
  75       The workaround is always active on this vCPU or it is not needed.
  76
  77
  78 Bitmap Feature Firmware Registers
  79 ---------------------------------
  80
  81 Contrary to the above registers, the following registers exposes the
  82 hypercall services in the form of a feature-bitmap to the userspace. This
  83 bitmap is translated to the services that are available to the guest.
  84 There is a register defined per service call owner and can be accessed via
  85 GET/SET_ONE_REG interface.
  86
  87 By default, these registers are set with the upper limit of the features
  88 that are supported. This way userspace can discover all the usable
  89 hypercall services via GET_ONE_REG. The user-space can write-back the
  90 desired bitmap back via SET_ONE_REG. The features for the registers that
  91 are untouched, probably because userspace isn't aware of them, will be
  92 exposed as is to the guest.
  93
  94 Note that KVM will not allow the userspace to configure the registers
  95 anymore once any of the vCPUs has run at least once. Instead, it will
  96 return a -EBUSY.
  97
  98 The pseudo-firmware bitmap register are as follows:
  99
 100 * KVM_REG_ARM_STD_BMAP:
 101     Controls the bitmap of the ARM Standard Secure Service Calls.
 102
 103   The following bits are accepted:
 104
 105     Bit-0: KVM_REG_ARM_STD_BIT_TRNG_V1_0:
 106       The bit represents the services offered under v1.0 of ARM True Random
 107       Number Generator (TRNG) specification, ARM DEN0098.
 108
 109 * KVM_REG_ARM_STD_HYP_BMAP:
 110     Controls the bitmap of the ARM Standard Hypervisor Service Calls.
 111
 112   The following bits are accepted:
 113
 114     Bit-0: KVM_REG_ARM_STD_HYP_BIT_PV_TIME:
 115       The bit represents the Paravirtualized Time service as represented by
 116       ARM DEN0057A.
 117
 118 * KVM_REG_ARM_VENDOR_HYP_BMAP:
 119     Controls the bitmap of the Vendor specific Hypervisor Service Calls.
 120
 121   The following bits are accepted:
 122
 123     Bit-0: KVM_REG_ARM_VENDOR_HYP_BIT_FUNC_FEAT
 124       The bit represents the ARM_SMCCC_VENDOR_HYP_KVM_FEATURES_FUNC_ID
 125       and ARM_SMCCC_VENDOR_HYP_CALL_UID_FUNC_ID function-ids.
 126
 127     Bit-1: KVM_REG_ARM_VENDOR_HYP_BIT_PTP:
 128       The bit represents the Precision Time Protocol KVM service.
 129
 130 Errors:
 131
 132     =======  =============================================================
 133     -ENOENT   Unknown register accessed.
 134     -EBUSY    Attempt a 'write' to the register after the VM has started.
 135     -EINVAL   Invalid bitmap written to the register.
 136     =======  =============================================================
 137
 138 .. [1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf