docs/arm-cpu-features.rst

   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
  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".
  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
  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)::
  49
  50       (QEMU) query-cpu-model-expansion type=full model={"name":"max"}
  51       { "return": {
  52         "model": { "name": "max", "props": {
  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
  58       }}}}
  59
  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.)
  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": {
  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
  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
  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::
 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
 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
 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
 188                            adjustment is enabled (vtime is not *not*
 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
 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
 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.
 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
 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.
 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
 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>`,
 279      CPU properties are set `on`, then the specified vector lengths are
 280      disabled but the default for any unspecified lengths remains enabled.
 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").
 286
 287   8) If one or more `sve<N>` CPU properties are set to `on`, then they
 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
 293   9) If SVE was disabled (`sve=off`), allowing all vector lengths to be
 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
 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::
 316
 317      $ qemu-system-aarch64 -M virt -cpu max,sve128=on
 318
 319   5) Disable the 512-bit vector length and all larger vector lengths,
 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
 325   6) Enable the 128-bit, 256-bit, and 512-bit vector lengths::
 326
 327      $ qemu-system-aarch64 -M virt -cpu max,sve128=on,sve256=on,sve512=on
 328
 329   7) The same as (6), but since the 128-bit and 256-bit vector
 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
 335   8) Do the same as (7), but by first disabling SVE and then re-enabling it::
 336
 337      $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve512=on,sve=on
 338
 339   9) Force errors regarding the last vector length::
 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 --------------------------------
 346
 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
 351 example's (1), (4), and (6) exhibit recommended uses of the properties.
 352