| Message ID | 20230920183310.1163034-11-oliver.upton@linux.dev (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | KVM: arm64: Enable 'writable' ID registers | expand |
Hi Oliver, kernel test robot noticed the following build warnings: [auto build test WARNING on ce9ecca0238b140b88f43859b211c9fdfd8e5b70] url: https://github.com/intel-lab-lkp/linux/commits/Oliver-Upton/KVM-arm64-Allow-userspace-to-get-the-writable-masks-for-feature-ID-registers/20230921-023547 base: ce9ecca0238b140b88f43859b211c9fdfd8e5b70 patch link: https://lore.kernel.org/r/20230920183310.1163034-11-oliver.upton%40linux.dev patch subject: [PATCH v10 10/12] KVM: arm64: Document vCPU feature selection UAPIs reproduce: (https://download.01.org/0day-ci/archive/20230927/202309271037.rM4DMYYZ-lkp@intel.com/reproduce) If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags | Reported-by: kernel test robot <lkp@intel.com> | Closes: https://lore.kernel.org/oe-kbuild-all/202309271037.rM4DMYYZ-lkp@intel.com/ All warnings (new ones prefixed by >>): >> Documentation/virt/kvm/arm/vcpu-features.rst:13: WARNING: undefined label: kvm_arm_vcpu_init (if the link has no caption the label must precede a section header) >> Documentation/virt/kvm/arm/vcpu-features.rst:30: WARNING: undefined label: kvm_arm_get_reg_writable_masks (if the link has no caption the label must precede a section header) vim +13 Documentation/virt/kvm/arm/vcpu-features.rst 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 are VM-scoped in KVM, meaning that the values 28 are identical 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
On Wed, Sep 27, 2023 at 10:45:34AM +0800, kernel test robot wrote: > Hi Oliver, > > kernel test robot noticed the following build warnings: Looks like I failed to include the diff that adds the labels I'm referencing, which is addressed with the following: diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 8cd91bc550bc..6068b711cdb0 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -3370,6 +3370,8 @@ return indicates the attribute is implemented. It does not necessarily indicate that the attribute can be read or written in the device's current state. "addr" is ignored. +.. _KVM_ARM_VCPU_INIT: + 4.82 KVM_ARM_VCPU_INIT ---------------------- @@ -6070,6 +6072,8 @@ writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG interface. No error will be returned, but the resulting offset will not be applied. +.. _KVM_ARM_GET_REG_WRITABLE_MASKS: + 4.139 KVM_ARM_GET_REG_WRITABLE_MASKS -------------------------------------------
diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst index e84848432158..7f231c724e16 100644 --- a/Documentation/virt/kvm/arm/index.rst +++ b/Documentation/virt/kvm/arm/index.rst @@ -11,3 +11,4 @@ ARM hypercalls pvtime ptp_kvm + vcpu-features diff --git a/Documentation/virt/kvm/arm/vcpu-features.rst b/Documentation/virt/kvm/arm/vcpu-features.rst new file mode 100644 index 000000000000..2d2f89c5781f --- /dev/null +++ b/Documentation/virt/kvm/arm/vcpu-features.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +vCPU feature selection on arm64 +=============================== + +KVM/arm64 provides two mechanisms that allow userspace to configure +the CPU features presented to the guest. + +KVM_ARM_VCPU_INIT +================= + +The ``KVM_ARM_VCPU_INIT`` ioctl accepts a bitmap of feature flags +(``struct kvm_vcpu_init::features``). Features enabled by this interface are +*opt-in* and may change/extend UAPI. See :ref:`KVM_ARM_VCPU_INIT` for complete +documentation of the features controlled by the ioctl. + +Otherwise, all CPU features supported by KVM are described by the architected +ID registers. + +The ID Registers +================ + +The Arm architecture specifies a range of *ID Registers* that describe the set +of architectural features supported by the CPU implementation. KVM initializes +the guest's ID registers to the maximum set of CPU features supported by the +system. The ID register values are VM-scoped in KVM, meaning that the values +are identical for all vCPUs in a VM. + +KVM allows userspace to *opt-out* of certain CPU features described by the ID +registers by writing values to them via the ``KVM_SET_ONE_REG`` ioctl. The ID +registers are mutable until the VM has started, i.e. userspace has called +``KVM_RUN`` on at least one vCPU in the VM. Userspace can discover what fields +are mutable in the ID registers using the ``KVM_ARM_GET_REG_WRITABLE_MASKS``. +See the :ref:`ioctl documentation <KVM_ARM_GET_REG_WRITABLE_MASKS>` for more +details. + +Userspace is allowed to *limit* or *mask* CPU features according to the rules +outlined by the architecture in DDI0487J 'D19.1.3 Principles of the ID scheme +for fields in ID register'. KVM does not allow ID register values that exceed +the capabilities of the system. + +.. warning:: + It is **strongly recommended** that userspace modify the ID register values + before accessing the rest of the vCPU's CPU register state. KVM may use the + ID register values to control feature emulation. Interleaving ID register + modification with other system register accesses may lead to unpredictable + behavior.
KVM/arm64 has a couple schemes for handling vCPU feature selection now, which is a lot to put on userspace. Add some documentation about how these interact and provide some recommendations for how to use the writable ID register scheme. Signed-off-by: Oliver Upton <oliver.upton@linux.dev> --- Documentation/virt/kvm/arm/index.rst | 1 + Documentation/virt/kvm/arm/vcpu-features.rst | 48 ++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 Documentation/virt/kvm/arm/vcpu-features.rst