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