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