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.
  35
  36 CPU Feature Probing
  37 ===================
  38
  39 Determining which CPU features are available and functional for a given
  40 CPU type is possible with the `query-cpu-model-expansion` QMP command.
  41 Below are some examples where `scripts/qmp/qmp-shell` (see the top comment
  42 block in the script for usage) is used to issue the QMP commands.
  43
  44 (1) Determine which CPU features are available for the `max` CPU type
  45     (Note, we started QEMU with qemu-system-aarch64, so `max` is
  46      implementing the ARMv8-A reference manual in this case)::
  47
  48       (QEMU) query-cpu-model-expansion type=full model={"name":"max"}
  49       { "return": {
  50         "model": { "name": "max", "props": {
  51         "sve1664": true, "pmu": true, "sve1792": true, "sve1920": true,
  52         "sve128": true, "aarch64": true, "sve1024": true, "sve": true,
  53         "sve640": true, "sve768": true, "sve1408": true, "sve256": true,
  54         "sve1152": true, "sve512": true, "sve384": true, "sve1536": true,
  55         "sve896": true, "sve1280": true, "sve2048": true
  56       }}}}
  57
  58 We see that the `max` CPU type has the `pmu`, `aarch64`, `sve`, and many
  59 `sve<N>` CPU features.  We also see that all the CPU features are
  60 enabled, as they are all `true`.  (The `sve<N>` CPU features are all
  61 optional SVE vector lengths (see "SVE CPU Properties").  While with TCG
  62 all SVE vector lengths can be supported, when KVM is in use it's more
  63 likely that only a few lengths will be supported, if SVE is supported at
  64 all.)
  65
  66 (2) Let's try to disable the PMU::
  67
  68       (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"pmu":false}}
  69       { "return": {
  70         "model": { "name": "max", "props": {
  71         "sve1664": true, "pmu": false, "sve1792": true, "sve1920": true,
  72         "sve128": true, "aarch64": true, "sve1024": true, "sve": true,
  73         "sve640": true, "sve768": true, "sve1408": true, "sve256": true,
  74         "sve1152": true, "sve512": true, "sve384": true, "sve1536": true,
  75         "sve896": true, "sve1280": true, "sve2048": true
  76       }}}}
  77
  78 We see it worked, as `pmu` is now `false`.
  79
  80 (3) Let's try to disable `aarch64`, which enables the AArch32 CPU feature::
  81
  82       (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"aarch64":false}}
  83       {"error": {
  84        "class": "GenericError", "desc":
  85        "'aarch64' feature cannot be disabled unless KVM is enabled and 32-bit EL1 is supported"
  86       }}
  87
  88 It looks like this feature is limited to a configuration we do not
  89 currently have.
  90
  91 (4) Let's disable `sve` and see what happens to all the optional SVE
  92     vector lengths::
  93
  94       (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"sve":false}}
  95       { "return": {
  96         "model": { "name": "max", "props": {
  97         "sve1664": false, "pmu": true, "sve1792": false, "sve1920": false,
  98         "sve128": false, "aarch64": true, "sve1024": false, "sve": false,
  99         "sve640": false, "sve768": false, "sve1408": false, "sve256": false,
 100         "sve1152": false, "sve512": false, "sve384": false, "sve1536": false,
 101         "sve896": false, "sve1280": false, "sve2048": false
 102       }}}}
 103
 104 As expected they are now all `false`.
 105
 106 (5) Let's try probing CPU features for the Cortex-A15 CPU type::
 107
 108       (QEMU) query-cpu-model-expansion type=full model={"name":"cortex-a15"}
 109       {"return": {"model": {"name": "cortex-a15", "props": {"pmu": true}}}}
 110
 111 Only the `pmu` CPU feature is available.
 112
 113 A note about CPU feature dependencies
 114 -------------------------------------
 115
 116 It's possible for features to have dependencies on other features. I.e.
 117 it may be possible to change one feature at a time without error, but
 118 when attempting to change all features at once an error could occur
 119 depending on the order they are processed.  It's also possible changing
 120 all at once doesn't generate an error, because a feature's dependencies
 121 are satisfied with other features, but the same feature cannot be changed
 122 independently without error.  For these reasons callers should always
 123 attempt to make their desired changes all at once in order to ensure the
 124 collection is valid.
 125
 126 A note about CPU models and KVM
 127 -------------------------------
 128
 129 Named CPU models generally do not work with KVM.  There are a few cases
 130 that do work, e.g. using the named CPU model `cortex-a57` with KVM on a
 131 seattle host, but mostly if KVM is enabled the `host` CPU type must be
 132 used.  This means the guest is provided all the same CPU features as the
 133 host CPU type has.  And, for this reason, the `host` CPU type should
 134 enable all CPU features that the host has by default.  Indeed it's even
 135 a bit strange to allow disabling CPU features that the host has when using
 136 the `host` CPU type, but in the absence of CPU models it's the best we can
 137 do if we want to launch guests without all the host's CPU features enabled.
 138
 139 Enabling KVM also affects the `query-cpu-model-expansion` QMP command.  The
 140 affect is not only limited to specific features, as pointed out in example
 141 (3) of "CPU Feature Probing", but also to which CPU types may be expanded.
 142 When KVM is enabled, only the `max`, `host`, and current CPU type may be
 143 expanded.  This restriction is necessary as it's not possible to know all
 144 CPU types that may work with KVM, but it does impose a small risk of users
 145 experiencing unexpected errors.  For example on a seattle, as mentioned
 146 above, the `cortex-a57` CPU type is also valid when KVM is enabled.
 147 Therefore a user could use the `host` CPU type for the current type, but
 148 then attempt to query `cortex-a57`, however that query will fail with our
 149 restrictions.  This shouldn't be an issue though as management layers and
 150 users have been preferring the `host` CPU type for use with KVM for quite
 151 some time.  Additionally, if the KVM-enabled QEMU instance running on a
 152 seattle host is using the `cortex-a57` CPU type, then querying `cortex-a57`
 153 will work.
 154
 155 Using CPU Features
 156 ==================
 157
 158 After determining which CPU features are available and supported for a
 159 given CPU type, then they may be selectively enabled or disabled on the
 160 QEMU command line with that CPU type::
 161
 162   $ qemu-system-aarch64 -M virt -cpu max,pmu=off,sve=on,sve128=on,sve256=on
 163
 164 The example above disables the PMU and enables the first two SVE vector
 165 lengths for the `max` CPU type.  Note, the `sve=on` isn't actually
 166 necessary, because, as we observed above with our probe of the `max` CPU
 167 type, `sve` is already on by default.  Also, based on our probe of
 168 defaults, it would seem we need to disable many SVE vector lengths, rather
 169 than only enabling the two we want.  This isn't the case, because, as
 170 disabling many SVE vector lengths would be quite verbose, the `sve<N>` CPU
 171 properties have special semantics (see "SVE CPU Property Parsing
 172 Semantics").
 173
 174 SVE CPU Properties
 175 ==================
 176
 177 There are two types of SVE CPU properties: `sve` and `sve<N>`.  The first
 178 is used to enable or disable the entire SVE feature, just as the `pmu`
 179 CPU property completely enables or disables the PMU.  The second type
 180 is used to enable or disable specific vector lengths, where `N` is the
 181 number of bits of the length.  The `sve<N>` CPU properties have special
 182 dependencies and constraints, see "SVE CPU Property Dependencies and
 183 Constraints" below.  Additionally, as we want all supported vector lengths
 184 to be enabled by default, then, in order to avoid overly verbose command
 185 lines (command lines full of `sve<N>=off`, for all `N` not wanted), we
 186 provide the parsing semantics listed in "SVE CPU Property Parsing
 187 Semantics".
 188
 189 SVE CPU Property Dependencies and Constraints
 190 ---------------------------------------------
 191
 192   1) At least one vector length must be enabled when `sve` is enabled.
 193
 194   2) If a vector length `N` is enabled, then all power-of-two vector
 195      lengths smaller than `N` must also be enabled.  E.g. if `sve512`
 196      is enabled, then the 128-bit and 256-bit vector lengths must also
 197      be enabled.
 198
 199 SVE CPU Property Parsing Semantics
 200 ----------------------------------
 201
 202   1) If SVE is disabled (`sve=off`), then which SVE vector lengths
 203      are enabled or disabled is irrelevant to the guest, as the entire
 204      SVE feature is disabled and that disables all vector lengths for
 205      the guest.  However QEMU will still track any `sve<N>` CPU
 206      properties provided by the user.  If later an `sve=on` is provided,
 207      then the guest will get only the enabled lengths.  If no `sve=on`
 208      is provided and there are explicitly enabled vector lengths, then
 209      an error is generated.
 210
 211   2) If SVE is enabled (`sve=on`), but no `sve<N>` CPU properties are
 212      provided, then all supported vector lengths are enabled, including
 213      the non-power-of-two lengths.
 214
 215   3) If SVE is enabled, then an error is generated when attempting to
 216      disable the last enabled vector length (see constraint (1) of "SVE
 217      CPU Property Dependencies and Constraints").
 218
 219   4) If one or more vector lengths have been explicitly enabled and at
 220      at least one of the dependency lengths of the maximum enabled length
 221      has been explicitly disabled, then an error is generated (see
 222      constraint (2) of "SVE CPU Property Dependencies and Constraints").
 223
 224   5) If one or more `sve<N>` CPU properties are set `off`, but no `sve<N>`,
 225      CPU properties are set `on`, then the specified vector lengths are
 226      disabled but the default for any unspecified lengths remains enabled.
 227      Disabling a power-of-two vector length also disables all vector
 228      lengths larger than the power-of-two length (see constraint (2) of
 229      "SVE CPU Property Dependencies and Constraints").
 230
 231   6) If one or more `sve<N>` CPU properties are set to `on`, then they
 232      are enabled and all unspecified lengths default to disabled, except
 233      for the required lengths per constraint (2) of "SVE CPU Property
 234      Dependencies and Constraints", which will even be auto-enabled if
 235      they were not explicitly enabled.
 236
 237   7) If SVE was disabled (`sve=off`), allowing all vector lengths to be
 238      explicitly disabled (i.e. avoiding the error specified in (3) of
 239      "SVE CPU Property Parsing Semantics"), then if later an `sve=on` is
 240      provided an error will be generated.  To avoid this error, one must
 241      enable at least one vector length prior to enabling SVE.
 242
 243 SVE CPU Property Examples
 244 -------------------------
 245
 246   1) Disable SVE::
 247
 248      $ qemu-system-aarch64 -M virt -cpu max,sve=off
 249
 250   2) Implicitly enable all vector lengths for the `max` CPU type::
 251
 252      $ qemu-system-aarch64 -M virt -cpu max
 253
 254   3) Only enable the 128-bit vector length::
 255
 256      $ qemu-system-aarch64 -M virt -cpu max,sve128=on
 257
 258   4) Disable the 512-bit vector length and all larger vector lengths,
 259      since 512 is a power-of-two.  This results in all the smaller,
 260      uninitialized lengths (128, 256, and 384) defaulting to enabled::
 261
 262      $ qemu-system-aarch64 -M virt -cpu max,sve512=off
 263
 264   5) Enable the 128-bit, 256-bit, and 512-bit vector lengths::
 265
 266      $ qemu-system-aarch64 -M virt -cpu max,sve128=on,sve256=on,sve512=on
 267
 268   6) The same as (5), but since the 128-bit and 256-bit vector
 269      lengths are required for the 512-bit vector length to be enabled,
 270      then allow them to be auto-enabled::
 271
 272      $ qemu-system-aarch64 -M virt -cpu max,sve512=on
 273
 274   7) Do the same as (6), but by first disabling SVE and then re-enabling it::
 275
 276      $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve512=on,sve=on
 277
 278   8) Force errors regarding the last vector length::
 279
 280      $ qemu-system-aarch64 -M virt -cpu max,sve128=off
 281      $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve128=off,sve=on
 282
 283 SVE CPU Property Recommendations
 284 --------------------------------
 285
 286 The examples in "SVE CPU Property Examples" exhibit many ways to select
 287 vector lengths which developers may find useful in order to avoid overly
 288 verbose command lines.  However, the recommended way to select vector
 289 lengths is to explicitly enable each desired length.  Therefore only
 290 example's (1), (3), and (5) exhibit recommended uses of the properties.
 291