> -----Original Message-----
> From: Eric Auger <[email protected]>
> Sent: 03 May 2026 08:34
> To: [email protected]; [email protected]; qemu-
> [email protected]; [email protected]; [email protected];
> [email protected]; [email protected];
> [email protected]; [email protected]; Shameer Kolothum Thodi
> <[email protected]>; [email protected]
> Cc: [email protected]; [email protected]; [email protected];
> [email protected]; [email protected]; [email protected];
> [email protected]
> Subject: [PATCH v4 17/17] arm/cpu-features: document ID reg properties
>
> External email: Use caution opening links or attachments
>
>
> From: Cornelia Huck <[email protected]>
>
> Add some documentation for how individual ID registers can be
> configured with the host cpu model.
>
> [CH: adapt to removal of the 'custom' model, added some more
> explanations about using the ID register props]
> Signed-off-by: Eric Auger <[email protected]>
> Signed-off-by: Cornelia Huck <[email protected]>
> ---
> docs/system/arm/cpu-features.rst | 104
> ++++++++++++++++++++++++++++---
> 1 file changed, 96 insertions(+), 8 deletions(-)
>
> diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-
> features.rst
> index 10b0eff27e..22f671b15d 100644
> --- a/docs/system/arm/cpu-features.rst
> +++ b/docs/system/arm/cpu-features.rst
> @@ -2,7 +2,10 @@ Arm CPU Features
> ================
>
> CPU features are optional features that a CPU of supporting type may
> -choose to implement or not. In QEMU, optional CPU features have
> +choose to implement or not. QEMU provides two different mechanisms
> +to configure those features:
> +
> +1. For most CPU models, optional CPU features may have
> corresponding boolean CPU proprieties that, when enabled, indicate
> that the feature is implemented, and, conversely, when disabled,
> indicate that it is not implemented. An example of an Arm CPU feature
> @@ -31,6 +34,16 @@ running guests in AArch32.
> CPU features that are inherently specific to KVM are
> prefixed with "kvm-" and are described in "KVM VCPU Features".
>
> +2. Additionally, the ``host`` CPU model on KVM allows to configure optional
> +CPU features via the corresponding ID registers. The host kernel allows
> +to write a subset of ID register fields. The host model exposes
> +properties for each writable ID register field. Those options are named
> +SYSREG_<IDREG>_<FIELD>. IDREG and FIELD names are those used in the
> +ARM ARM Reference Manual. They can also be found in the Linux
> +arch/arm64/tool/sysreg file which is used to automatically generate the
arch/arm64/tools/sysreg
Anyway, I think this needs update as the scripts now uses Registers.json
from AARCHMRS, right?
> +description for those registers and fields. This currently only has been
> +implemented for KVM.
> +
> CPU Feature Probing
> ===================
>
> @@ -126,13 +139,20 @@ A note about CPU models and KVM
>
> Named CPU models generally do not work with KVM. There are a few cases
> that do work, e.g. using the named CPU model ``cortex-a57`` with KVM on a
> -seattle host, but mostly if KVM is enabled the ``host`` CPU type must be
> -used. This means the guest is provided all the same CPU features as the
> -host CPU type has. And, for this reason, the ``host`` CPU type should
> -enable all CPU features that the host has by default. Indeed it's even
> -a bit strange to allow disabling CPU features that the host has when using
> -the ``host`` CPU type, but in the absence of CPU models it's the best we can
> -do if we want to launch guests without all the host's CPU features enabled.
> +seattle host, but mostly if KVM is enabled, the ``host`` CPU model must be
> +used.
> +
> +Using the ``host`` type means the guest is provided all the same CPU
> +features as the host CPU type has. And, for this reason, the ``host``
> +CPU type should enable all CPU features that the host has by default.
> +
> +In case some features need to be hidden to the guest, and the host kernel
s/hidden to the guest/hidden from the guest/
> +supports it, the ``host`` model can be instructed to disable individual
> +ID register values. This is especially useful for migration purposes.
> +However, this interface will not allow configuring an arbitrary set of
> +features; the ID registers must describe a subset of the host's features,
> +and all differences to the host's configuration must actually be supported
> +by the kernel to be deconfigured.
>
> Enabling KVM also affects the ``query-cpu-model-expansion`` QMP
> command. The
> affect is not only limited to specific features, as pointed out in example
> @@ -169,6 +189,13 @@ disabling many SVE vector lengths would be quite
> verbose, the ``sve<N>`` CPU
> properties have special semantics (see "SVE CPU Property Parsing
> Semantics").
>
> +Additionally, if supported by KVM on the host kernel, the ``host`` CPU model
> +may be configured via individual ID register field properties, for example::
> +
> + $ qemu-system-aarch64 -M virt -cpu
> host,SYSREG_ID_AA64ISAR0_EL1_DP=0x0
> +
> +This forces ID_AA64ISAR0_EL1 DP field to 0.
> +
> KVM VCPU Features
> =================
>
> @@ -495,3 +522,64 @@ Legal values for ``S`` are 30, 34, 36, and 39; the
> default is 30.
>
> As with ``x-rme``, the ``x-l0gptsz`` property may be renamed or
> removed in some future QEMU release.
> +
> +Configuring CPU features via ID register fields
> +===============================================
> +
> +Note that this is currently only supported under KVM, and with the
> +``host`` CPU model.
> +
> +Querying available ID register fields
> +-------------------------------------
> +
> +QEMU will create properties for all ID register fields that are
> +reported as being writable by the kernel, and that are known to the
> +QEMU instance. Therefore, the same QEMU binary may expose different
> +properties when run under a different kernel.
> +
> +To find out all available writable ID register fields, use the
> +``query-cpu-model-expansion`` QMP command::
> +
> + (QEMU) query-cpu-model-expansion type=full model={"name":"host"}
> + {"return": {
> + "model": {"name": "host", "props": {
> + "SYSREG_ID_AA64PFR0_EL1_EL3": 1,
> "SYSREG_ID_AA64ISAR2_EL1_CLRBHB": 0,
> + "SYSREG_CTR_EL0_L1Ip": 3, "SYSREG_CTR_EL0_DminLine": 4,
> + "SYSREG_ID_AA64MMFR0_EL1_BIGEND": 1,
> "SYSREG_ID_AA64MMFR1_EL1_ECBHB": 0,
> + "SYSREG_ID_AA64MMFR2_EL1_CnP": 1,
> "SYSREG_ID_DFR0_EL1_PerfMon": 4,
> + "SYSREG_ID_AA64PFR0_EL1_DIT": 0,
> "SYSREG_ID_AA64MMFR1_EL1_HAFDBS": 2,
> + "SYSREG_ID_AA64ISAR0_EL1_FHM": 0,
> "SYSREG_ID_AA64ISAR2_EL1_CSSC": 0,
> + "SYSREG_ID_AA64ISAR0_EL1_DP": 1, (...)
> + }}}}
> +
> +If a certain field in an ID register does not show up in this list, it
> +is not writable with the specific host kernel.
> +
> +A note on compatibility
> +-----------------------
> +
> +A common use case for providing a defined set of ID register values is
> +to be able to present a fixed set of features to a guest, often referred
> +to as "stable guest ABI". This may take the form of ironing out differences
> +between two similar CPUs with the intention of being able to migrate
> +between machines with those CPUs, or providing the same CPU across Linux
> +kernel updates on the host.
> +
> +Over the course of time, the Linux kernel is changing the set of ID register
> +fields that are writable by userspace. Newly introduced writable ID
> +registers should be initialized to 0 to ensure compatibility. However, ID
> +registers that have already been introduced that undergo a change as to
> +which fields are writable may introduce incompatibities that need to be
s/incompatibities/incompatibilities/
Thanks,
Shameer
> +addressed on a case-by-case basis for the systems that you wish to migrate
> +inbetween.
> +
> +A note on Arm CPU features (FEAT_xxx)
> +-------------------------------------
> +
> +Configuring CPUs is done on a feature level on other architectures, and this
> +would imply configuring FEAT_xxx values on Arm. However, differences
> between
> +CPUs may not map to FEAT_xxx, but to differences in other registers in the
> +ID register range; for example, differences in the cache architecture exposed
> +via ``CTR_EL0``. We therefore cannot rely on configuration via FEAT_xxx. A
> +feature-based interface more similar to other architectures may be
> implemented
> +on top of the ID register interface in the future.
> --
> 2.53.0
