fw-pseudo-registers.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=======================================
  4ARM firmware pseudo-registers interface
  5=======================================
  6
  7KVM handles the hypercall services as requested by the guests. New hypercall
  8services are regularly made available by the ARM specification or by KVM (as
  9vendor services) if they make sense from a virtualization point of view.
 10
 11This means that a guest booted on two different versions of KVM can observe
 12two different "firmware" revisions. This could cause issues if a given guest
 13is tied to a particular version of a hypercall service, or if a migration
 14causes a different version to be exposed out of the blue to an unsuspecting
 15guest.
 16
 17In order to remedy this situation, KVM exposes a set of "firmware
 18pseudo-registers" that can be manipulated using the GET/SET_ONE_REG
 19interface. These registers can be saved/restored by userspace, and set
 20to a convenient value as required.
 21
 22The 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
 78Bitmap Feature Firmware Registers
 79---------------------------------
 80
 81Contrary to the above registers, the following registers exposes the
 82hypercall services in the form of a feature-bitmap to the userspace. This
 83bitmap is translated to the services that are available to the guest.
 84There is a register defined per service call owner and can be accessed via
 85GET/SET_ONE_REG interface.
 86
 87By default, these registers are set with the upper limit of the features
 88that are supported. This way userspace can discover all the usable
 89hypercall services via GET_ONE_REG. The user-space can write-back the
 90desired bitmap back via SET_ONE_REG. The features for the registers that
 91are untouched, probably because userspace isn't aware of them, will be
 92exposed as is to the guest.
 93
 94Note that KVM will not allow the userspace to configure the registers
 95anymore once any of the vCPUs has run at least once. Instead, it will
 96return a -EBUSY.
 97
 98The 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[0-63].
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* KVM_REG_ARM_VENDOR_HYP_BMAP_2:
131    Controls the bitmap of the Vendor specific Hypervisor Service Calls[64-127].
132
133  The following bits are accepted:
134
135    Bit-0: KVM_REG_ARM_VENDOR_HYP_BIT_DISCOVER_IMPL_VER
136      This represents the ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_VER_FUNC_ID
137      function-id. This is reset to 0.
138
139    Bit-1: KVM_REG_ARM_VENDOR_HYP_BIT_DISCOVER_IMPL_CPUS
140      This represents the ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_CPUS_FUNC_ID
141      function-id. This is reset to 0.
142
143Errors:
144
145    =======  =============================================================
146    -ENOENT   Unknown register accessed.
147    -EBUSY    Attempt a 'write' to the register after the VM has started.
148    -EINVAL   Invalid bitmap written to the register.
149    =======  =============================================================
150
151.. [1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf