0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================
0004 Generic vm interface
0005 ====================
0006
0007 The virtual machine "device" also accepts the ioctls KVM_SET_DEVICE_ATTR,
0008 KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same
0009 struct kvm_device_attr as other devices, but targets VM-wide settings
0010 and controls.
0011
0012 The groups and attributes per virtual machine, if any, are architecture
0013 specific.
0014
0015 1. GROUP: KVM_S390_VM_MEM_CTRL
0016 ==============================
0017
0018 :Architectures: s390
0019
0020 1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA
0021 -------------------------------------------
0022
0023 :Parameters: none
0024 :Returns: -EBUSY if a vcpu is already defined, otherwise 0
0025
0026 Enables Collaborative Memory Management Assist (CMMA) for the virtual machine.
0027
0028 1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA
0029 ----------------------------------------
0030
0031 :Parameters: none
0032 :Returns: -EINVAL if CMMA was not enabled;
0033 0 otherwise
0034
0035 Clear the CMMA status for all guest pages, so any pages the guest marked
0036 as unused are again used any may not be reclaimed by the host.
0037
0038 1.3. ATTRIBUTE KVM_S390_VM_MEM_LIMIT_SIZE
0039 -----------------------------------------
0040
0041 :Parameters: in attr->addr the address for the new limit of guest memory
0042 :Returns: -EFAULT if the given address is not accessible;
0043 -EINVAL if the virtual machine is of type UCONTROL;
0044 -E2BIG if the given guest memory is to big for that machine;
0045 -EBUSY if a vcpu is already defined;
0046 -ENOMEM if not enough memory is available for a new shadow guest mapping;
0047 0 otherwise.
0048
0049 Allows userspace to query the actual limit and set a new limit for
0050 the maximum guest memory size. The limit will be rounded up to
0051 2048 MB, 4096 GB, 8192 TB respectively, as this limit is governed by
0052 the number of page table levels. In the case that there is no limit we will set
0053 the limit to KVM_S390_NO_MEM_LIMIT (U64_MAX).
0054
0055 2. GROUP: KVM_S390_VM_CPU_MODEL
0056 ===============================
0057
0058 :Architectures: s390
0059
0060 2.1. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE (r/o)
0061 ---------------------------------------------
0062
0063 Allows user space to retrieve machine and kvm specific cpu related information::
0064
0065 struct kvm_s390_vm_cpu_machine {
0066 __u64 cpuid; # CPUID of host
0067 __u32 ibc; # IBC level range offered by host
0068 __u8 pad[4];
0069 __u64 fac_mask[256]; # set of cpu facilities enabled by KVM
0070 __u64 fac_list[256]; # set of cpu facilities offered by host
0071 }
0072
0073 :Parameters: address of buffer to store the machine related cpu data
0074 of type struct kvm_s390_vm_cpu_machine*
0075 :Returns: -EFAULT if the given address is not accessible from kernel space;
0076 -ENOMEM if not enough memory is available to process the ioctl;
0077 0 in case of success.
0078
0079 2.2. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR (r/w)
0080 ===============================================
0081
0082 Allows user space to retrieve or request to change cpu related information for a vcpu::
0083
0084 struct kvm_s390_vm_cpu_processor {
0085 __u64 cpuid; # CPUID currently (to be) used by this vcpu
0086 __u16 ibc; # IBC level currently (to be) used by this vcpu
0087 __u8 pad[6];
0088 __u64 fac_list[256]; # set of cpu facilities currently (to be) used
0089 # by this vcpu
0090 }
0091
0092 KVM does not enforce or limit the cpu model data in any form. Take the information
0093 retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration
0094 setups. Instruction interceptions triggered by additionally set facility bits that
0095 are not handled by KVM need to by imlemented in the VM driver code.
0096
0097 :Parameters: address of buffer to store/set the processor related cpu
0098 data of type struct kvm_s390_vm_cpu_processor*.
0099 :Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case);
0100 -EFAULT if the given address is not accessible from kernel space;
0101 -ENOMEM if not enough memory is available to process the ioctl;
0102 0 in case of success.
0103
0104 .. _KVM_S390_VM_CPU_MACHINE_FEAT:
0105
0106 2.3. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_FEAT (r/o)
0107 --------------------------------------------------
0108
0109 Allows user space to retrieve available cpu features. A feature is available if
0110 provided by the hardware and supported by kvm. In theory, cpu features could
0111 even be completely emulated by kvm.
0112
0113 ::
0114
0115 struct kvm_s390_vm_cpu_feat {
0116 __u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering
0117 };
0118
0119 :Parameters: address of a buffer to load the feature list from.
0120 :Returns: -EFAULT if the given address is not accessible from kernel space;
0121 0 in case of success.
0122
0123 2.4. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_FEAT (r/w)
0124 ----------------------------------------------------
0125
0126 Allows user space to retrieve or change enabled cpu features for all VCPUs of a
0127 VM. Features that are not available cannot be enabled.
0128
0129 See :ref:`KVM_S390_VM_CPU_MACHINE_FEAT` for
0130 a description of the parameter struct.
0131
0132 :Parameters: address of a buffer to store/load the feature list from.
0133 :Returns: -EFAULT if the given address is not accessible from kernel space;
0134 -EINVAL if a cpu feature that is not available is to be enabled;
0135 -EBUSY if at least one VCPU has already been defined;
0136 0 in case of success.
0137
0138 .. _KVM_S390_VM_CPU_MACHINE_SUBFUNC:
0139
0140 2.5. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_SUBFUNC (r/o)
0141 -----------------------------------------------------
0142
0143 Allows user space to retrieve available cpu subfunctions without any filtering
0144 done by a set IBC. These subfunctions are indicated to the guest VCPU via
0145 query or "test bit" subfunctions and used e.g. by cpacf functions, plo and ptff.
0146
0147 A subfunction block is only valid if KVM_S390_VM_CPU_MACHINE contains the
0148 STFL(E) bit introducing the affected instruction. If the affected instruction
0149 indicates subfunctions via a "query subfunction", the response block is
0150 contained in the returned struct. If the affected instruction
0151 indicates subfunctions via a "test bit" mechanism, the subfunction codes are
0152 contained in the returned struct in MSB 0 bit numbering.
0153
0154 ::
0155
0156 struct kvm_s390_vm_cpu_subfunc {
0157 u8 plo[32]; # always valid (ESA/390 feature)
0158 u8 ptff[16]; # valid with TOD-clock steering
0159 u8 kmac[16]; # valid with Message-Security-Assist
0160 u8 kmc[16]; # valid with Message-Security-Assist
0161 u8 km[16]; # valid with Message-Security-Assist
0162 u8 kimd[16]; # valid with Message-Security-Assist
0163 u8 klmd[16]; # valid with Message-Security-Assist
0164 u8 pckmo[16]; # valid with Message-Security-Assist-Extension 3
0165 u8 kmctr[16]; # valid with Message-Security-Assist-Extension 4
0166 u8 kmf[16]; # valid with Message-Security-Assist-Extension 4
0167 u8 kmo[16]; # valid with Message-Security-Assist-Extension 4
0168 u8 pcc[16]; # valid with Message-Security-Assist-Extension 4
0169 u8 ppno[16]; # valid with Message-Security-Assist-Extension 5
0170 u8 kma[16]; # valid with Message-Security-Assist-Extension 8
0171 u8 kdsa[16]; # valid with Message-Security-Assist-Extension 9
0172 u8 reserved[1792]; # reserved for future instructions
0173 };
0174
0175 :Parameters: address of a buffer to load the subfunction blocks from.
0176 :Returns: -EFAULT if the given address is not accessible from kernel space;
0177 0 in case of success.
0178
0179 2.6. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_SUBFUNC (r/w)
0180 -------------------------------------------------------
0181
0182 Allows user space to retrieve or change cpu subfunctions to be indicated for
0183 all VCPUs of a VM. This attribute will only be available if kernel and
0184 hardware support are in place.
0185
0186 The kernel uses the configured subfunction blocks for indication to
0187 the guest. A subfunction block will only be used if the associated STFL(E) bit
0188 has not been disabled by user space (so the instruction to be queried is
0189 actually available for the guest).
0190
0191 As long as no data has been written, a read will fail. The IBC will be used
0192 to determine available subfunctions in this case, this will guarantee backward
0193 compatibility.
0194
0195 See :ref:`KVM_S390_VM_CPU_MACHINE_SUBFUNC` for a
0196 description of the parameter struct.
0197
0198 :Parameters: address of a buffer to store/load the subfunction blocks from.
0199 :Returns: -EFAULT if the given address is not accessible from kernel space;
0200 -EINVAL when reading, if there was no write yet;
0201 -EBUSY if at least one VCPU has already been defined;
0202 0 in case of success.
0203
0204 3. GROUP: KVM_S390_VM_TOD
0205 =========================
0206
0207 :Architectures: s390
0208
0209 3.1. ATTRIBUTE: KVM_S390_VM_TOD_HIGH
0210 ------------------------------------
0211
0212 Allows user space to set/get the TOD clock extension (u8) (superseded by
0213 KVM_S390_VM_TOD_EXT).
0214
0215 :Parameters: address of a buffer in user space to store the data (u8) to
0216 :Returns: -EFAULT if the given address is not accessible from kernel space;
0217 -EINVAL if setting the TOD clock extension to != 0 is not supported
0218
0219 3.2. ATTRIBUTE: KVM_S390_VM_TOD_LOW
0220 -----------------------------------
0221
0222 Allows user space to set/get bits 0-63 of the TOD clock register as defined in
0223 the POP (u64).
0224
0225 :Parameters: address of a buffer in user space to store the data (u64) to
0226 :Returns: -EFAULT if the given address is not accessible from kernel space
0227
0228 3.3. ATTRIBUTE: KVM_S390_VM_TOD_EXT
0229 -----------------------------------
0230
0231 Allows user space to set/get bits 0-63 of the TOD clock register as defined in
0232 the POP (u64). If the guest CPU model supports the TOD clock extension (u8), it
0233 also allows user space to get/set it. If the guest CPU model does not support
0234 it, it is stored as 0 and not allowed to be set to a value != 0.
0235
0236 :Parameters: address of a buffer in user space to store the data
0237 (kvm_s390_vm_tod_clock) to
0238 :Returns: -EFAULT if the given address is not accessible from kernel space;
0239 -EINVAL if setting the TOD clock extension to != 0 is not supported
0240
0241 4. GROUP: KVM_S390_VM_CRYPTO
0242 ============================
0243
0244 :Architectures: s390
0245
0246 4.1. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_AES_KW (w/o)
0247 ------------------------------------------------------
0248
0249 Allows user space to enable aes key wrapping, including generating a new
0250 wrapping key.
0251
0252 :Parameters: none
0253 :Returns: 0
0254
0255 4.2. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_DEA_KW (w/o)
0256 ------------------------------------------------------
0257
0258 Allows user space to enable dea key wrapping, including generating a new
0259 wrapping key.
0260
0261 :Parameters: none
0262 :Returns: 0
0263
0264 4.3. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_AES_KW (w/o)
0265 -------------------------------------------------------
0266
0267 Allows user space to disable aes key wrapping, clearing the wrapping key.
0268
0269 :Parameters: none
0270 :Returns: 0
0271
0272 4.4. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_DEA_KW (w/o)
0273 -------------------------------------------------------
0274
0275 Allows user space to disable dea key wrapping, clearing the wrapping key.
0276
0277 :Parameters: none
0278 :Returns: 0
0279
0280 5. GROUP: KVM_S390_VM_MIGRATION
0281 ===============================
0282
0283 :Architectures: s390
0284
0285 5.1. ATTRIBUTE: KVM_S390_VM_MIGRATION_STOP (w/o)
0286 ------------------------------------------------
0287
0288 Allows userspace to stop migration mode, needed for PGSTE migration.
0289 Setting this attribute when migration mode is not active will have no
0290 effects.
0291
0292 :Parameters: none
0293 :Returns: 0
0294
0295 5.2. ATTRIBUTE: KVM_S390_VM_MIGRATION_START (w/o)
0296 -------------------------------------------------
0297
0298 Allows userspace to start migration mode, needed for PGSTE migration.
0299 Setting this attribute when migration mode is already active will have
0300 no effects.
0301
0302 :Parameters: none
0303 :Returns: -ENOMEM if there is not enough free memory to start migration mode;
0304 -EINVAL if the state of the VM is invalid (e.g. no memory defined);
0305 0 in case of success.
0306
0307 5.3. ATTRIBUTE: KVM_S390_VM_MIGRATION_STATUS (r/o)
0308 --------------------------------------------------
0309
0310 Allows userspace to query the status of migration mode.
0311
0312 :Parameters: address of a buffer in user space to store the data (u64) to;
0313 the data itself is either 0 if migration mode is disabled or 1
0314 if it is enabled
0315 :Returns: -EFAULT if the given address is not accessible from kernel space;
0316 0 in case of success.
