1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =============================== 3 ===============================
4 vCPU feature selection on arm64 4 vCPU feature selection on arm64
5 =============================== 5 ===============================
6 6
7 KVM/arm64 provides two mechanisms that allow u 7 KVM/arm64 provides two mechanisms that allow userspace to configure
8 the CPU features presented to the guest. 8 the CPU features presented to the guest.
9 9
10 KVM_ARM_VCPU_INIT 10 KVM_ARM_VCPU_INIT
11 ================= 11 =================
12 12
13 The ``KVM_ARM_VCPU_INIT`` ioctl accepts a bitm 13 The ``KVM_ARM_VCPU_INIT`` ioctl accepts a bitmap of feature flags
14 (``struct kvm_vcpu_init::features``). Features 14 (``struct kvm_vcpu_init::features``). Features enabled by this interface are
15 *opt-in* and may change/extend UAPI. See :ref: 15 *opt-in* and may change/extend UAPI. See :ref:`KVM_ARM_VCPU_INIT` for complete
16 documentation of the features controlled by th 16 documentation of the features controlled by the ioctl.
17 17
18 Otherwise, all CPU features supported by KVM a 18 Otherwise, all CPU features supported by KVM are described by the architected
19 ID registers. 19 ID registers.
20 20
21 The ID Registers 21 The ID Registers
22 ================ 22 ================
23 23
24 The Arm architecture specifies a range of *ID 24 The Arm architecture specifies a range of *ID Registers* that describe the set
25 of architectural features supported by the CPU 25 of architectural features supported by the CPU implementation. KVM initializes
26 the guest's ID registers to the maximum set of 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-scope 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. 28 values could be shared for all vCPUs in a VM.
29 29
30 KVM allows userspace to *opt-out* of certain C 30 KVM allows userspace to *opt-out* of certain CPU features described by the ID
31 registers by writing values to them via the `` 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 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. Us 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 ``KV 34 are mutable in the ID registers using the ``KVM_ARM_GET_REG_WRITABLE_MASKS``.
35 See the :ref:`ioctl documentation <KVM_ARM_GET 35 See the :ref:`ioctl documentation <KVM_ARM_GET_REG_WRITABLE_MASKS>` for more
36 details. 36 details.
37 37
38 Userspace is allowed to *limit* or *mask* CPU 38 Userspace is allowed to *limit* or *mask* CPU features according to the rules
39 outlined by the architecture in DDI0487J.a D19 39 outlined by the architecture in DDI0487J.a D19.1.3 'Principles of the ID
40 scheme for fields in ID register'. KVM does no 40 scheme for fields in ID register'. KVM does not allow ID register values that
41 exceed the capabilities of the system. 41 exceed the capabilities of the system.
42 42
43 .. warning:: 43 .. warning::
44 It is **strongly recommended** that userspa 44 It is **strongly recommended** that userspace modify the ID register values
45 before accessing the rest of the vCPU's CPU 45 before accessing the rest of the vCPU's CPU register state. KVM may use the
46 ID register values to control feature emula 46 ID register values to control feature emulation. Interleaving ID register
47 modification with other system register acc 47 modification with other system register accesses may lead to unpredictable
48 behavior. 48 behavior.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.