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         "pmu": true, "aarch64": true
  52       }}}}
  53
  54 We see that the `max` CPU type has the `pmu` and `aarch64` CPU features.
  55 We also see that the CPU features are enabled, as they are all `true`.
  56
  57 (2) Let's try to disable the PMU::
  58
  59       (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"pmu":false}}
  60       { "return": {
  61         "model": { "name": "max", "props": {
  62         "pmu": false, "aarch64": true
  63       }}}}
  64
  65 We see it worked, as `pmu` is now `false`.
  66
  67 (3) Let's try to disable `aarch64`, which enables the AArch32 CPU feature::
  68
  69       (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"aarch64":false}}
  70       {"error": {
  71        "class": "GenericError", "desc":
  72        "'aarch64' feature cannot be disabled unless KVM is enabled and 32-bit EL1 is supported"
  73       }}
  74
  75 It looks like this feature is limited to a configuration we do not
  76 currently have.
  77
  78 (4) Let's try probing CPU features for the Cortex-A15 CPU type::
  79
  80       (QEMU) query-cpu-model-expansion type=full model={"name":"cortex-a15"}
  81       {"return": {"model": {"name": "cortex-a15", "props": {"pmu": true}}}}
  82
  83 Only the `pmu` CPU feature is available.
  84
  85 A note about CPU feature dependencies
  86 -------------------------------------
  87
  88 It's possible for features to have dependencies on other features. I.e.
  89 it may be possible to change one feature at a time without error, but
  90 when attempting to change all features at once an error could occur
  91 depending on the order they are processed.  It's also possible changing
  92 all at once doesn't generate an error, because a feature's dependencies
  93 are satisfied with other features, but the same feature cannot be changed
  94 independently without error.  For these reasons callers should always
  95 attempt to make their desired changes all at once in order to ensure the
  96 collection is valid.
  97
  98 A note about CPU models and KVM
  99 -------------------------------
 100
 101 Named CPU models generally do not work with KVM.  There are a few cases
 102 that do work, e.g. using the named CPU model `cortex-a57` with KVM on a
 103 seattle host, but mostly if KVM is enabled the `host` CPU type must be
 104 used.  This means the guest is provided all the same CPU features as the
 105 host CPU type has.  And, for this reason, the `host` CPU type should
 106 enable all CPU features that the host has by default.  Indeed it's even
 107 a bit strange to allow disabling CPU features that the host has when using
 108 the `host` CPU type, but in the absence of CPU models it's the best we can
 109 do if we want to launch guests without all the host's CPU features enabled.
 110
 111 Enabling KVM also affects the `query-cpu-model-expansion` QMP command.  The
 112 affect is not only limited to specific features, as pointed out in example
 113 (3) of "CPU Feature Probing", but also to which CPU types may be expanded.
 114 When KVM is enabled, only the `max`, `host`, and current CPU type may be
 115 expanded.  This restriction is necessary as it's not possible to know all
 116 CPU types that may work with KVM, but it does impose a small risk of users
 117 experiencing unexpected errors.  For example on a seattle, as mentioned
 118 above, the `cortex-a57` CPU type is also valid when KVM is enabled.
 119 Therefore a user could use the `host` CPU type for the current type, but
 120 then attempt to query `cortex-a57`, however that query will fail with our
 121 restrictions.  This shouldn't be an issue though as management layers and
 122 users have been preferring the `host` CPU type for use with KVM for quite
 123 some time.  Additionally, if the KVM-enabled QEMU instance running on a
 124 seattle host is using the `cortex-a57` CPU type, then querying `cortex-a57`
 125 will work.
 126
 127 Using CPU Features
 128 ==================
 129
 130 After determining which CPU features are available and supported for a
 131 given CPU type, then they may be selectively enabled or disabled on the
 132 QEMU command line with that CPU type::
 133
 134   $ qemu-system-aarch64 -M virt -cpu max,pmu=off
 135
 136 The example above disables the PMU for the `max` CPU type.
 137