Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Docs: KVM: Add doc for the bitmap firmware registers
Add the documentation for the bitmap firmware registers in
hypercalls.rst and api.rst. This includes the details for
KVM_REG_ARM_STD_BMAP, KVM_REG_ARM_STD_HYP_BMAP, and
KVM_REG_ARM_VENDOR_HYP_BMAP registers.
Since the document is growing to carry other hypercall related
information, make necessary adjustments to present the document
in a generic sense, rather than being PSCI focused.
Signed-off-by: Raghavendra Rao Ananta <rananta@google.com>
Reviewed-by: Gavin Shan <gshan@redhat.com>
[maz: small scale reformat, move things about, random typo fixes]
Signed-off-by: Marc Zyngier <maz@kernel.org>
Link: https://lore.kernel.org/r/20220502233853.1233742-7-rananta@google.com
authored by
Raghavendra Rao Ananta
and committed by
Marc Zyngier
fa246c68
f1ced23a
+96
-17
+18
Documentation/virt/kvm/api.rst
+18
Documentation/virt/kvm/api.rst
···
2601
2601
After the vcpu's SVE configuration is finalized, further attempts to
2602
2602
write this register will fail with EPERM.
2603
2603
2604
+
arm64 bitmap feature firmware pseudo-registers have the following bit pattern::
2605
+
2606
+
0x6030 0000 0016 <regno:16>
2607
+
2608
+
The bitmap feature firmware registers exposes the hypercall services that
2609
+
are available for userspace to configure. The set bits corresponds to the
2610
+
services that are available for the guests to access. By default, KVM
2611
+
sets all the supported bits during VM initialization. The userspace can
2612
+
discover the available services via KVM_GET_ONE_REG, and write back the
2613
+
bitmap corresponding to the features that it wishes guests to see via
2614
+
KVM_SET_ONE_REG.
2615
+
2616
+
Note: These registers are immutable once any of the vCPUs of the VM has
2617
+
run at least once. A KVM_SET_ONE_REG in such a scenario will return
2618
+
a -EBUSY to userspace.
2619
+
2620
+
(See Documentation/virt/kvm/arm/hypercalls.rst for more details.)
2621
+
2604
2622
2605
2623
MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
2606
2624
the register group type:
+78
-17
Documentation/virt/kvm/arm/hypercalls.rst
+78
-17
Documentation/virt/kvm/arm/hypercalls.rst
···
1
1
.. SPDX-License-Identifier: GPL-2.0
2
2
3
-
=========================================
4
-
Power State Coordination Interface (PSCI)
5
-
=========================================
3
+
=======================
4
+
ARM Hypercall Interface
5
+
=======================
6
6
7
-
KVM implements the PSCI (Power State Coordination Interface)
8
-
specification in order to provide services such as CPU on/off, reset
9
-
and power-off to the guest.
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
10
11
-
The PSCI specification is regularly updated to provide new features,
12
-
and KVM implements these updates if they make sense from a virtualization
13
-
point of view.
14
-
15
-
This means that a guest booted on two different versions of KVM can
16
-
observe two different "firmware" revisions. This could cause issues if
17
-
a given guest is tied to a particular PSCI revision (unlikely), or if
18
-
a migration causes a different PSCI version to be exposed out of the
19
-
blue to an unsuspecting guest.
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.
20
16
21
17
In order to remedy this situation, KVM exposes a set of "firmware
22
18
pseudo-registers" that can be manipulated using the GET/SET_ONE_REG
23
19
interface. These registers can be saved/restored by userspace, and set
24
-
to a convenient value if required.
20
+
to a convenient value as required.
25
21
26
-
The following register is defined:
22
+
The following registers are defined:
27
23
28
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
29
30
30
- Only valid if the vcpu has the KVM_ARM_VCPU_PSCI_0_2 feature set
31
31
(and thus has already been initialized)
···
73
73
this vCPU.
74
74
KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED:
75
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
+
======= =============================================================
76
137
77
138
.. [1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf