| Generic vm interface |
| ==================================== |
| |
| The virtual machine "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, |
| KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same |
| struct kvm_device_attr as other devices, but targets VM-wide settings |
| and controls. |
| |
| The groups and attributes per virtual machine, if any, are architecture |
| specific. |
| |
| 1. GROUP: KVM_S390_VM_MEM_CTRL |
| Architectures: s390 |
| |
| 1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA |
| Parameters: none |
| Returns: -EBUSY if a vcpu is already defined, otherwise 0 |
| |
| Enables Collaborative Memory Management Assist (CMMA) for the virtual machine. |
| |
| 1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA |
| Parameters: none |
| Returns: -EINVAL if CMMA was not enabled |
| 0 otherwise |
| |
| Clear the CMMA status for all guest pages, so any pages the guest marked |
| as unused are again used any may not be reclaimed by the host. |
| |
| 1.3. ATTRIBUTE KVM_S390_VM_MEM_LIMIT_SIZE |
| Parameters: in attr->addr the address for the new limit of guest memory |
| Returns: -EFAULT if the given address is not accessible |
| -EINVAL if the virtual machine is of type UCONTROL |
| -E2BIG if the given guest memory is to big for that machine |
| -EBUSY if a vcpu is already defined |
| -ENOMEM if not enough memory is available for a new shadow guest mapping |
| 0 otherwise |
| |
| Allows userspace to query the actual limit and set a new limit for |
| the maximum guest memory size. The limit will be rounded up to |
| 2048 MB, 4096 GB, 8192 TB respectively, as this limit is governed by |
| the number of page table levels. In the case that there is no limit we will set |
| the limit to KVM_S390_NO_MEM_LIMIT (U64_MAX). |
| |
| 2. GROUP: KVM_S390_VM_CPU_MODEL |
| Architectures: s390 |
| |
| 2.1. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE (r/o) |
| |
| Allows user space to retrieve machine and kvm specific cpu related information: |
| |
| struct kvm_s390_vm_cpu_machine { |
| __u64 cpuid; # CPUID of host |
| __u32 ibc; # IBC level range offered by host |
| __u8 pad[4]; |
| __u64 fac_mask[256]; # set of cpu facilities enabled by KVM |
| __u64 fac_list[256]; # set of cpu facilities offered by host |
| } |
| |
| Parameters: address of buffer to store the machine related cpu data |
| of type struct kvm_s390_vm_cpu_machine* |
| Returns: -EFAULT if the given address is not accessible from kernel space |
| -ENOMEM if not enough memory is available to process the ioctl |
| 0 in case of success |
| |
| 2.2. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR (r/w) |
| |
| Allows user space to retrieve or request to change cpu related information for a vcpu: |
| |
| struct kvm_s390_vm_cpu_processor { |
| __u64 cpuid; # CPUID currently (to be) used by this vcpu |
| __u16 ibc; # IBC level currently (to be) used by this vcpu |
| __u8 pad[6]; |
| __u64 fac_list[256]; # set of cpu facilities currently (to be) used |
| # by this vcpu |
| } |
| |
| KVM does not enforce or limit the cpu model data in any form. Take the information |
| retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration |
| setups. Instruction interceptions triggered by additionally set facility bits that |
| are not handled by KVM need to by imlemented in the VM driver code. |
| |
| Parameters: address of buffer to store/set the processor related cpu |
| data of type struct kvm_s390_vm_cpu_processor*. |
| Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case) |
| -EFAULT if the given address is not accessible from kernel space |
| -ENOMEM if not enough memory is available to process the ioctl |
| 0 in case of success |
| |
| 2.3. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_FEAT (r/o) |
| |
| Allows user space to retrieve available cpu features. A feature is available if |
| provided by the hardware and supported by kvm. In theory, cpu features could |
| even be completely emulated by kvm. |
| |
| struct kvm_s390_vm_cpu_feat { |
| __u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering |
| }; |
| |
| Parameters: address of a buffer to load the feature list from. |
| Returns: -EFAULT if the given address is not accessible from kernel space. |
| 0 in case of success. |
| |
| 2.4. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_FEAT (r/w) |
| |
| Allows user space to retrieve or change enabled cpu features for all VCPUs of a |
| VM. Features that are not available cannot be enabled. |
| |
| See 2.3. for a description of the parameter struct. |
| |
| Parameters: address of a buffer to store/load the feature list from. |
| Returns: -EFAULT if the given address is not accessible from kernel space. |
| -EINVAL if a cpu feature that is not available is to be enabled. |
| -EBUSY if at least one VCPU has already been defined. |
| 0 in case of success. |
| |
| 2.5. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_SUBFUNC (r/o) |
| |
| Allows user space to retrieve available cpu subfunctions without any filtering |
| done by a set IBC. These subfunctions are indicated to the guest VCPU via |
| query or "test bit" subfunctions and used e.g. by cpacf functions, plo and ptff. |
| |
| A subfunction block is only valid if KVM_S390_VM_CPU_MACHINE contains the |
| STFL(E) bit introducing the affected instruction. If the affected instruction |
| indicates subfunctions via a "query subfunction", the response block is |
| contained in the returned struct. If the affected instruction |
| indicates subfunctions via a "test bit" mechanism, the subfunction codes are |
| contained in the returned struct in MSB 0 bit numbering. |
| |
| struct kvm_s390_vm_cpu_subfunc { |
| u8 plo[32]; # always valid (ESA/390 feature) |
| u8 ptff[16]; # valid with TOD-clock steering |
| u8 kmac[16]; # valid with Message-Security-Assist |
| u8 kmc[16]; # valid with Message-Security-Assist |
| u8 km[16]; # valid with Message-Security-Assist |
| u8 kimd[16]; # valid with Message-Security-Assist |
| u8 klmd[16]; # valid with Message-Security-Assist |
| u8 pckmo[16]; # valid with Message-Security-Assist-Extension 3 |
| u8 kmctr[16]; # valid with Message-Security-Assist-Extension 4 |
| u8 kmf[16]; # valid with Message-Security-Assist-Extension 4 |
| u8 kmo[16]; # valid with Message-Security-Assist-Extension 4 |
| u8 pcc[16]; # valid with Message-Security-Assist-Extension 4 |
| u8 ppno[16]; # valid with Message-Security-Assist-Extension 5 |
| u8 kma[16]; # valid with Message-Security-Assist-Extension 8 |
| u8 kdsa[16]; # valid with Message-Security-Assist-Extension 9 |
| u8 reserved[1792]; # reserved for future instructions |
| }; |
| |
| Parameters: address of a buffer to load the subfunction blocks from. |
| Returns: -EFAULT if the given address is not accessible from kernel space. |
| 0 in case of success. |
| |
| 2.6. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_SUBFUNC (r/w) |
| |
| Allows user space to retrieve or change cpu subfunctions to be indicated for |
| all VCPUs of a VM. This attribute will only be available if kernel and |
| hardware support are in place. |
| |
| The kernel uses the configured subfunction blocks for indication to |
| the guest. A subfunction block will only be used if the associated STFL(E) bit |
| has not been disabled by user space (so the instruction to be queried is |
| actually available for the guest). |
| |
| As long as no data has been written, a read will fail. The IBC will be used |
| to determine available subfunctions in this case, this will guarantee backward |
| compatibility. |
| |
| See 2.5. for a description of the parameter struct. |
| |
| Parameters: address of a buffer to store/load the subfunction blocks from. |
| Returns: -EFAULT if the given address is not accessible from kernel space. |
| -EINVAL when reading, if there was no write yet. |
| -EBUSY if at least one VCPU has already been defined. |
| 0 in case of success. |
| |
| 3. GROUP: KVM_S390_VM_TOD |
| Architectures: s390 |
| |
| 3.1. ATTRIBUTE: KVM_S390_VM_TOD_HIGH |
| |
| Allows user space to set/get the TOD clock extension (u8) (superseded by |
| KVM_S390_VM_TOD_EXT). |
| |
| Parameters: address of a buffer in user space to store the data (u8) to |
| Returns: -EFAULT if the given address is not accessible from kernel space |
| -EINVAL if setting the TOD clock extension to != 0 is not supported |
| |
| 3.2. ATTRIBUTE: KVM_S390_VM_TOD_LOW |
| |
| Allows user space to set/get bits 0-63 of the TOD clock register as defined in |
| the POP (u64). |
| |
| Parameters: address of a buffer in user space to store the data (u64) to |
| Returns: -EFAULT if the given address is not accessible from kernel space |
| |
| 3.3. ATTRIBUTE: KVM_S390_VM_TOD_EXT |
| Allows user space to set/get bits 0-63 of the TOD clock register as defined in |
| the POP (u64). If the guest CPU model supports the TOD clock extension (u8), it |
| also allows user space to get/set it. If the guest CPU model does not support |
| it, it is stored as 0 and not allowed to be set to a value != 0. |
| |
| Parameters: address of a buffer in user space to store the data |
| (kvm_s390_vm_tod_clock) to |
| Returns: -EFAULT if the given address is not accessible from kernel space |
| -EINVAL if setting the TOD clock extension to != 0 is not supported |
| |
| 4. GROUP: KVM_S390_VM_CRYPTO |
| Architectures: s390 |
| |
| 4.1. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_AES_KW (w/o) |
| |
| Allows user space to enable aes key wrapping, including generating a new |
| wrapping key. |
| |
| Parameters: none |
| Returns: 0 |
| |
| 4.2. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_DEA_KW (w/o) |
| |
| Allows user space to enable dea key wrapping, including generating a new |
| wrapping key. |
| |
| Parameters: none |
| Returns: 0 |
| |
| 4.3. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_AES_KW (w/o) |
| |
| Allows user space to disable aes key wrapping, clearing the wrapping key. |
| |
| Parameters: none |
| Returns: 0 |
| |
| 4.4. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_DEA_KW (w/o) |
| |
| Allows user space to disable dea key wrapping, clearing the wrapping key. |
| |
| Parameters: none |
| Returns: 0 |
| |
| 5. GROUP: KVM_S390_VM_MIGRATION |
| Architectures: s390 |
| |
| 5.1. ATTRIBUTE: KVM_S390_VM_MIGRATION_STOP (w/o) |
| |
| Allows userspace to stop migration mode, needed for PGSTE migration. |
| Setting this attribute when migration mode is not active will have no |
| effects. |
| |
| Parameters: none |
| Returns: 0 |
| |
| 5.2. ATTRIBUTE: KVM_S390_VM_MIGRATION_START (w/o) |
| |
| Allows userspace to start migration mode, needed for PGSTE migration. |
| Setting this attribute when migration mode is already active will have |
| no effects. |
| |
| Parameters: none |
| Returns: -ENOMEM if there is not enough free memory to start migration mode |
| -EINVAL if the state of the VM is invalid (e.g. no memory defined) |
| 0 in case of success. |
| |
| 5.3. ATTRIBUTE: KVM_S390_VM_MIGRATION_STATUS (r/o) |
| |
| Allows userspace to query the status of migration mode. |
| |
| Parameters: address of a buffer in user space to store the data (u64) to; |
| the data itself is either 0 if migration mode is disabled or 1 |
| if it is enabled |
| Returns: -EFAULT if the given address is not accessible from kernel space |
| 0 in case of success. |
