| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
======================================= |
| 4 |
ARM firmware pseudo-registers 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[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 |
|
| 143 |
Errors: |
| 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 |