]>
Commit | Line | Data |
---|---|---|
e19afd56 AJ |
1 | ================ |
2 | ARM CPU Features | |
3 | ================ | |
4 | ||
5 | Examples of probing and using ARM CPU features | |
6 | ||
7 | Introduction | |
8 | ============ | |
9 | ||
10 | CPU features are optional features that a CPU of supporting type may | |
11 | choose to implement or not. In QEMU, optional CPU features have | |
12 | corresponding boolean CPU proprieties that, when enabled, indicate | |
13 | that the feature is implemented, and, conversely, when disabled, | |
14 | indicate that it is not implemented. An example of an ARM CPU feature | |
15 | is the Performance Monitoring Unit (PMU). CPU types such as the | |
16 | Cortex-A15 and the Cortex-A57, which respectively implement ARM | |
17 | architecture reference manuals ARMv7-A and ARMv8-A, may both optionally | |
18 | implement PMUs. For example, if a user wants to use a Cortex-A15 without | |
19 | a PMU, then the `-cpu` parameter should contain `pmu=off` on the QEMU | |
20 | command line, i.e. `-cpu cortex-a15,pmu=off`. | |
21 | ||
22 | As not all CPU types support all optional CPU features, then whether or | |
23 | not a CPU property exists depends on the CPU type. For example, CPUs | |
24 | that implement the ARMv8-A architecture reference manual may optionally | |
25 | support the AArch32 CPU feature, which may be enabled by disabling the | |
26 | `aarch64` CPU property. A CPU type such as the Cortex-A15, which does | |
27 | not implement ARMv8-A, will not have the `aarch64` CPU property. | |
28 | ||
29 | QEMU's support may be limited for some CPU features, only partially | |
30 | supporting the feature or only supporting the feature under certain | |
31 | configurations. For example, the `aarch64` CPU feature, which, when | |
32 | disabled, enables the optional AArch32 CPU feature, is only supported | |
33 | when using the KVM accelerator and when running on a host CPU type that | |
dea101a1 AJ |
34 | supports the feature. While `aarch64` currently only works with KVM, |
35 | it could work with TCG. CPU features that are specific to KVM are | |
36 | prefixed with "kvm-" and are described in "KVM VCPU Features". | |
e19afd56 AJ |
37 | |
38 | CPU Feature Probing | |
39 | =================== | |
40 | ||
41 | Determining which CPU features are available and functional for a given | |
42 | CPU type is possible with the `query-cpu-model-expansion` QMP command. | |
43 | Below are some examples where `scripts/qmp/qmp-shell` (see the top comment | |
44 | block in the script for usage) is used to issue the QMP commands. | |
45 | ||
f21673c3 SH |
46 | 1. Determine which CPU features are available for the `max` CPU type |
47 | (Note, we started QEMU with qemu-system-aarch64, so `max` is | |
48 | implementing the ARMv8-A reference manual in this case):: | |
e19afd56 AJ |
49 | |
50 | (QEMU) query-cpu-model-expansion type=full model={"name":"max"} | |
51 | { "return": { | |
52 | "model": { "name": "max", "props": { | |
0df9142d AJ |
53 | "sve1664": true, "pmu": true, "sve1792": true, "sve1920": true, |
54 | "sve128": true, "aarch64": true, "sve1024": true, "sve": true, | |
55 | "sve640": true, "sve768": true, "sve1408": true, "sve256": true, | |
56 | "sve1152": true, "sve512": true, "sve384": true, "sve1536": true, | |
57 | "sve896": true, "sve1280": true, "sve2048": true | |
e19afd56 AJ |
58 | }}}} |
59 | ||
0df9142d AJ |
60 | We see that the `max` CPU type has the `pmu`, `aarch64`, `sve`, and many |
61 | `sve<N>` CPU features. We also see that all the CPU features are | |
62 | enabled, as they are all `true`. (The `sve<N>` CPU features are all | |
63 | optional SVE vector lengths (see "SVE CPU Properties"). While with TCG | |
64 | all SVE vector lengths can be supported, when KVM is in use it's more | |
65 | likely that only a few lengths will be supported, if SVE is supported at | |
66 | all.) | |
e19afd56 AJ |
67 | |
68 | (2) Let's try to disable the PMU:: | |
69 | ||
70 | (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"pmu":false}} | |
71 | { "return": { | |
72 | "model": { "name": "max", "props": { | |
0df9142d AJ |
73 | "sve1664": true, "pmu": false, "sve1792": true, "sve1920": true, |
74 | "sve128": true, "aarch64": true, "sve1024": true, "sve": true, | |
75 | "sve640": true, "sve768": true, "sve1408": true, "sve256": true, | |
76 | "sve1152": true, "sve512": true, "sve384": true, "sve1536": true, | |
77 | "sve896": true, "sve1280": true, "sve2048": true | |
e19afd56 AJ |
78 | }}}} |
79 | ||
80 | We see it worked, as `pmu` is now `false`. | |
81 | ||
82 | (3) Let's try to disable `aarch64`, which enables the AArch32 CPU feature:: | |
83 | ||
84 | (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"aarch64":false}} | |
85 | {"error": { | |
86 | "class": "GenericError", "desc": | |
87 | "'aarch64' feature cannot be disabled unless KVM is enabled and 32-bit EL1 is supported" | |
88 | }} | |
89 | ||
90 | It looks like this feature is limited to a configuration we do not | |
91 | currently have. | |
92 | ||
0df9142d AJ |
93 | (4) Let's disable `sve` and see what happens to all the optional SVE |
94 | vector lengths:: | |
95 | ||
96 | (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"sve":false}} | |
97 | { "return": { | |
98 | "model": { "name": "max", "props": { | |
99 | "sve1664": false, "pmu": true, "sve1792": false, "sve1920": false, | |
100 | "sve128": false, "aarch64": true, "sve1024": false, "sve": false, | |
101 | "sve640": false, "sve768": false, "sve1408": false, "sve256": false, | |
102 | "sve1152": false, "sve512": false, "sve384": false, "sve1536": false, | |
103 | "sve896": false, "sve1280": false, "sve2048": false | |
104 | }}}} | |
105 | ||
106 | As expected they are now all `false`. | |
107 | ||
108 | (5) Let's try probing CPU features for the Cortex-A15 CPU type:: | |
e19afd56 AJ |
109 | |
110 | (QEMU) query-cpu-model-expansion type=full model={"name":"cortex-a15"} | |
111 | {"return": {"model": {"name": "cortex-a15", "props": {"pmu": true}}}} | |
112 | ||
113 | Only the `pmu` CPU feature is available. | |
114 | ||
115 | A note about CPU feature dependencies | |
116 | ------------------------------------- | |
117 | ||
118 | It's possible for features to have dependencies on other features. I.e. | |
119 | it may be possible to change one feature at a time without error, but | |
120 | when attempting to change all features at once an error could occur | |
121 | depending on the order they are processed. It's also possible changing | |
122 | all at once doesn't generate an error, because a feature's dependencies | |
123 | are satisfied with other features, but the same feature cannot be changed | |
124 | independently without error. For these reasons callers should always | |
125 | attempt to make their desired changes all at once in order to ensure the | |
126 | collection is valid. | |
127 | ||
128 | A note about CPU models and KVM | |
129 | ------------------------------- | |
130 | ||
131 | Named CPU models generally do not work with KVM. There are a few cases | |
132 | that do work, e.g. using the named CPU model `cortex-a57` with KVM on a | |
133 | seattle host, but mostly if KVM is enabled the `host` CPU type must be | |
134 | used. This means the guest is provided all the same CPU features as the | |
135 | host CPU type has. And, for this reason, the `host` CPU type should | |
136 | enable all CPU features that the host has by default. Indeed it's even | |
137 | a bit strange to allow disabling CPU features that the host has when using | |
138 | the `host` CPU type, but in the absence of CPU models it's the best we can | |
139 | do if we want to launch guests without all the host's CPU features enabled. | |
140 | ||
141 | Enabling KVM also affects the `query-cpu-model-expansion` QMP command. The | |
142 | affect is not only limited to specific features, as pointed out in example | |
143 | (3) of "CPU Feature Probing", but also to which CPU types may be expanded. | |
144 | When KVM is enabled, only the `max`, `host`, and current CPU type may be | |
145 | expanded. This restriction is necessary as it's not possible to know all | |
146 | CPU types that may work with KVM, but it does impose a small risk of users | |
147 | experiencing unexpected errors. For example on a seattle, as mentioned | |
148 | above, the `cortex-a57` CPU type is also valid when KVM is enabled. | |
149 | Therefore a user could use the `host` CPU type for the current type, but | |
150 | then attempt to query `cortex-a57`, however that query will fail with our | |
151 | restrictions. This shouldn't be an issue though as management layers and | |
152 | users have been preferring the `host` CPU type for use with KVM for quite | |
153 | some time. Additionally, if the KVM-enabled QEMU instance running on a | |
154 | seattle host is using the `cortex-a57` CPU type, then querying `cortex-a57` | |
155 | will work. | |
156 | ||
157 | Using CPU Features | |
158 | ================== | |
159 | ||
160 | After determining which CPU features are available and supported for a | |
161 | given CPU type, then they may be selectively enabled or disabled on the | |
162 | QEMU command line with that CPU type:: | |
163 | ||
0df9142d AJ |
164 | $ qemu-system-aarch64 -M virt -cpu max,pmu=off,sve=on,sve128=on,sve256=on |
165 | ||
166 | The example above disables the PMU and enables the first two SVE vector | |
167 | lengths for the `max` CPU type. Note, the `sve=on` isn't actually | |
168 | necessary, because, as we observed above with our probe of the `max` CPU | |
169 | type, `sve` is already on by default. Also, based on our probe of | |
170 | defaults, it would seem we need to disable many SVE vector lengths, rather | |
171 | than only enabling the two we want. This isn't the case, because, as | |
172 | disabling many SVE vector lengths would be quite verbose, the `sve<N>` CPU | |
173 | properties have special semantics (see "SVE CPU Property Parsing | |
174 | Semantics"). | |
175 | ||
dea101a1 AJ |
176 | KVM VCPU Features |
177 | ================= | |
178 | ||
179 | KVM VCPU features are CPU features that are specific to KVM, such as | |
180 | paravirt features or features that enable CPU virtualization extensions. | |
181 | The features' CPU properties are only available when KVM is enabled and | |
182 | are named with the prefix "kvm-". KVM VCPU features may be probed, | |
183 | enabled, and disabled in the same way as other CPU features. Below is | |
184 | the list of KVM VCPU features and their descriptions. | |
185 | ||
186 | kvm-no-adjvtime By default kvm-no-adjvtime is disabled. This | |
187 | means that by default the virtual time | |
fa3236a9 | 188 | adjustment is enabled (vtime is not *not* |
dea101a1 AJ |
189 | adjusted). |
190 | ||
191 | When virtual time adjustment is enabled each | |
192 | time the VM transitions back to running state | |
193 | the VCPU's virtual counter is updated to ensure | |
194 | stopped time is not counted. This avoids time | |
195 | jumps surprising guest OSes and applications, | |
196 | as long as they use the virtual counter for | |
197 | timekeeping. However it has the side effect of | |
198 | the virtual and physical counters diverging. | |
199 | All timekeeping based on the virtual counter | |
200 | will appear to lag behind any timekeeping that | |
201 | does not subtract VM stopped time. The guest | |
202 | may resynchronize its virtual counter with | |
203 | other time sources as needed. | |
204 | ||
205 | Enable kvm-no-adjvtime to disable virtual time | |
206 | adjustment, also restoring the legacy (pre-5.0) | |
207 | behavior. | |
208 | ||
0df9142d AJ |
209 | SVE CPU Properties |
210 | ================== | |
211 | ||
212 | There are two types of SVE CPU properties: `sve` and `sve<N>`. The first | |
213 | is used to enable or disable the entire SVE feature, just as the `pmu` | |
214 | CPU property completely enables or disables the PMU. The second type | |
215 | is used to enable or disable specific vector lengths, where `N` is the | |
216 | number of bits of the length. The `sve<N>` CPU properties have special | |
217 | dependencies and constraints, see "SVE CPU Property Dependencies and | |
218 | Constraints" below. Additionally, as we want all supported vector lengths | |
219 | to be enabled by default, then, in order to avoid overly verbose command | |
220 | lines (command lines full of `sve<N>=off`, for all `N` not wanted), we | |
221 | provide the parsing semantics listed in "SVE CPU Property Parsing | |
222 | Semantics". | |
223 | ||
224 | SVE CPU Property Dependencies and Constraints | |
225 | --------------------------------------------- | |
226 | ||
227 | 1) At least one vector length must be enabled when `sve` is enabled. | |
228 | ||
6fa8a379 AJ |
229 | 2) If a vector length `N` is enabled, then, when KVM is enabled, all |
230 | smaller, host supported vector lengths must also be enabled. If | |
231 | KVM is not enabled, then only all the smaller, power-of-two vector | |
232 | lengths must be enabled. E.g. with KVM if the host supports all | |
233 | vector lengths up to 512-bits (128, 256, 384, 512), then if `sve512` | |
234 | is enabled, the 128-bit vector length, 256-bit vector length, and | |
235 | 384-bit vector length must also be enabled. Without KVM, the 384-bit | |
236 | vector length would not be required. | |
237 | ||
238 | 3) If KVM is enabled then only vector lengths that the host CPU type | |
239 | support may be enabled. If SVE is not supported by the host, then | |
240 | no `sve*` properties may be enabled. | |
0df9142d AJ |
241 | |
242 | SVE CPU Property Parsing Semantics | |
243 | ---------------------------------- | |
244 | ||
245 | 1) If SVE is disabled (`sve=off`), then which SVE vector lengths | |
246 | are enabled or disabled is irrelevant to the guest, as the entire | |
247 | SVE feature is disabled and that disables all vector lengths for | |
248 | the guest. However QEMU will still track any `sve<N>` CPU | |
249 | properties provided by the user. If later an `sve=on` is provided, | |
250 | then the guest will get only the enabled lengths. If no `sve=on` | |
251 | is provided and there are explicitly enabled vector lengths, then | |
252 | an error is generated. | |
253 | ||
254 | 2) If SVE is enabled (`sve=on`), but no `sve<N>` CPU properties are | |
6fa8a379 AJ |
255 | provided, then all supported vector lengths are enabled, which when |
256 | KVM is not in use means including the non-power-of-two lengths, and, | |
257 | when KVM is in use, it means all vector lengths supported by the host | |
258 | processor. | |
0df9142d AJ |
259 | |
260 | 3) If SVE is enabled, then an error is generated when attempting to | |
261 | disable the last enabled vector length (see constraint (1) of "SVE | |
262 | CPU Property Dependencies and Constraints"). | |
263 | ||
264 | 4) If one or more vector lengths have been explicitly enabled and at | |
265 | at least one of the dependency lengths of the maximum enabled length | |
266 | has been explicitly disabled, then an error is generated (see | |
267 | constraint (2) of "SVE CPU Property Dependencies and Constraints"). | |
268 | ||
6fa8a379 AJ |
269 | 5) When KVM is enabled, if the host does not support SVE, then an error |
270 | is generated when attempting to enable any `sve*` properties (see | |
271 | constraint (3) of "SVE CPU Property Dependencies and Constraints"). | |
272 | ||
273 | 6) When KVM is enabled, if the host does support SVE, then an error is | |
274 | generated when attempting to enable any vector lengths not supported | |
275 | by the host (see constraint (3) of "SVE CPU Property Dependencies and | |
276 | Constraints"). | |
277 | ||
278 | 7) If one or more `sve<N>` CPU properties are set `off`, but no `sve<N>`, | |
0df9142d AJ |
279 | CPU properties are set `on`, then the specified vector lengths are |
280 | disabled but the default for any unspecified lengths remains enabled. | |
6fa8a379 AJ |
281 | When KVM is not enabled, disabling a power-of-two vector length also |
282 | disables all vector lengths larger than the power-of-two length. | |
283 | When KVM is enabled, then disabling any supported vector length also | |
284 | disables all larger vector lengths (see constraint (2) of "SVE CPU | |
285 | Property Dependencies and Constraints"). | |
0df9142d | 286 | |
6fa8a379 | 287 | 8) If one or more `sve<N>` CPU properties are set to `on`, then they |
0df9142d AJ |
288 | are enabled and all unspecified lengths default to disabled, except |
289 | for the required lengths per constraint (2) of "SVE CPU Property | |
290 | Dependencies and Constraints", which will even be auto-enabled if | |
291 | they were not explicitly enabled. | |
292 | ||
6fa8a379 | 293 | 9) If SVE was disabled (`sve=off`), allowing all vector lengths to be |
0df9142d AJ |
294 | explicitly disabled (i.e. avoiding the error specified in (3) of |
295 | "SVE CPU Property Parsing Semantics"), then if later an `sve=on` is | |
296 | provided an error will be generated. To avoid this error, one must | |
297 | enable at least one vector length prior to enabling SVE. | |
298 | ||
299 | SVE CPU Property Examples | |
300 | ------------------------- | |
301 | ||
302 | 1) Disable SVE:: | |
303 | ||
304 | $ qemu-system-aarch64 -M virt -cpu max,sve=off | |
305 | ||
306 | 2) Implicitly enable all vector lengths for the `max` CPU type:: | |
307 | ||
308 | $ qemu-system-aarch64 -M virt -cpu max | |
309 | ||
87014c6b AJ |
310 | 3) When KVM is enabled, implicitly enable all host CPU supported vector |
311 | lengths with the `host` CPU type:: | |
312 | ||
313 | $ qemu-system-aarch64 -M virt,accel=kvm -cpu host | |
314 | ||
315 | 4) Only enable the 128-bit vector length:: | |
0df9142d AJ |
316 | |
317 | $ qemu-system-aarch64 -M virt -cpu max,sve128=on | |
318 | ||
87014c6b | 319 | 5) Disable the 512-bit vector length and all larger vector lengths, |
0df9142d AJ |
320 | since 512 is a power-of-two. This results in all the smaller, |
321 | uninitialized lengths (128, 256, and 384) defaulting to enabled:: | |
322 | ||
323 | $ qemu-system-aarch64 -M virt -cpu max,sve512=off | |
324 | ||
87014c6b | 325 | 6) Enable the 128-bit, 256-bit, and 512-bit vector lengths:: |
0df9142d AJ |
326 | |
327 | $ qemu-system-aarch64 -M virt -cpu max,sve128=on,sve256=on,sve512=on | |
328 | ||
87014c6b | 329 | 7) The same as (6), but since the 128-bit and 256-bit vector |
0df9142d AJ |
330 | lengths are required for the 512-bit vector length to be enabled, |
331 | then allow them to be auto-enabled:: | |
332 | ||
333 | $ qemu-system-aarch64 -M virt -cpu max,sve512=on | |
334 | ||
87014c6b | 335 | 8) Do the same as (7), but by first disabling SVE and then re-enabling it:: |
0df9142d AJ |
336 | |
337 | $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve512=on,sve=on | |
338 | ||
87014c6b | 339 | 9) Force errors regarding the last vector length:: |
0df9142d AJ |
340 | |
341 | $ qemu-system-aarch64 -M virt -cpu max,sve128=off | |
342 | $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve128=off,sve=on | |
343 | ||
344 | SVE CPU Property Recommendations | |
345 | -------------------------------- | |
e19afd56 | 346 | |
0df9142d AJ |
347 | The examples in "SVE CPU Property Examples" exhibit many ways to select |
348 | vector lengths which developers may find useful in order to avoid overly | |
349 | verbose command lines. However, the recommended way to select vector | |
350 | lengths is to explicitly enable each desired length. Therefore only | |
87014c6b | 351 | example's (1), (4), and (6) exhibit recommended uses of the properties. |
e19afd56 | 352 |