On 5/7/26 9:44 PM, Shameer Kolothum Thodi wrote: > >> -----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? that's correct. > >> +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/ yup > >> +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/ noted. Thanks Eric > > 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
