Documentation/virt/kvm/arm/vcpu-features.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============================
   4 vCPU feature selection on arm64
   5 ===============================
   6
   7 KVM/arm64 provides two mechanisms that allow userspace to configure
   8 the CPU features presented to the guest.
   9
  10 KVM_ARM_VCPU_INIT
  11 =================
  12
  13 The ``KVM_ARM_VCPU_INIT`` ioctl accepts a bitmap of feature flags
  14 (``struct kvm_vcpu_init::features``). Features enabled by this interface are
  15 *opt-in* and may change/extend UAPI. See :ref:`KVM_ARM_VCPU_INIT` for complete
  16 documentation of the features controlled by the ioctl.
  17
  18 Otherwise, all CPU features supported by KVM are described by the architected
  19 ID registers.
  20
  21 The ID Registers
  22 ================
  23
  24 The Arm architecture specifies a range of *ID Registers* that describe the set
  25 of architectural features supported by the CPU implementation. KVM initializes
  26 the guest's ID registers to the maximum set of CPU features supported by the
  27 system. The ID register values may be VM-scoped in KVM, meaning that the
  28 values could be shared for all vCPUs in a VM.
  29
  30 KVM allows userspace to *opt-out* of certain CPU features described by the ID
  31 registers by writing values to them via the ``KVM_SET_ONE_REG`` ioctl. The ID
  32 registers are mutable until the VM has started, i.e. userspace has called
  33 ``KVM_RUN`` on at least one vCPU in the VM. Userspace can discover what fields
  34 are mutable in the ID registers using the ``KVM_ARM_GET_REG_WRITABLE_MASKS``.
  35 See the :ref:`ioctl documentation <KVM_ARM_GET_REG_WRITABLE_MASKS>` for more
  36 details.
  37
  38 Userspace is allowed to *limit* or *mask* CPU features according to the rules
  39 outlined by the architecture in DDI0487J.a D19.1.3 'Principles of the ID
  40 scheme for fields in ID register'. KVM does not allow ID register values that
  41 exceed the capabilities of the system.
  42
  43 .. warning::
  44    It is **strongly recommended** that userspace modify the ID register values
  45    before accessing the rest of the vCPU's CPU register state. KVM may use the
  46    ID register values to control feature emulation. Interleaving ID register
  47    modification with other system register accesses may lead to unpredictable
  48    behavior.