Loading Documentation/virt/kvm/api.rst +166 −5 Original line number Diff line number Diff line Loading @@ -960,6 +960,14 @@ memory. __u8 pad2[30]; }; If the KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag is returned from the KVM_CAP_XEN_HVM check, it may be set in the flags field of this ioctl. This requests KVM to generate the contents of the hypercall page automatically; hypercalls will be intercepted and passed to userspace through KVM_EXIT_XEN. In this case, all of the blob size and address fields must be zero. No other flags are currently valid in the struct kvm_xen_hvm_config. 4.29 KVM_GET_CLOCK ------------------ Loading Loading @@ -4831,6 +4839,101 @@ into user space. If a vCPU is in running state while this ioctl is invoked, the vCPU may experience inconsistent filtering behavior on MSR accesses. 4.127 KVM_XEN_HVM_SET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vm ioctl :Parameters: struct kvm_xen_hvm_attr :Returns: 0 on success, < 0 on error :: struct kvm_xen_hvm_attr { __u16 type; __u16 pad[3]; union { __u8 long_mode; __u8 vector; struct { __u64 gfn; } shared_info; __u64 pad[4]; } u; }; type values: KVM_XEN_ATTR_TYPE_LONG_MODE Sets the ABI mode of the VM to 32-bit or 64-bit (long mode). This determines the layout of the shared info pages exposed to the VM. KVM_XEN_ATTR_TYPE_SHARED_INFO Sets the guest physical frame number at which the Xen "shared info" page resides. Note that although Xen places vcpu_info for the first 32 vCPUs in the shared_info page, KVM does not automatically do so and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO be used explicitly even when the vcpu_info for a given vCPU resides at the "default" location in the shared_info page. This is because KVM is not aware of the Xen CPU id which is used as the index into the vcpu_info[] array, so cannot know the correct default location. KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Sets the exception vector used to deliver Xen event channel upcalls. 4.128 KVM_XEN_HVM_GET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vm ioctl :Parameters: struct kvm_xen_hvm_attr :Returns: 0 on success, < 0 on error Allows Xen VM attributes to be read. For the structure and types, see KVM_XEN_HVM_SET_ATTR above. 4.129 KVM_XEN_VCPU_SET_ATTR --------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vcpu ioctl :Parameters: struct kvm_xen_vcpu_attr :Returns: 0 on success, < 0 on error :: struct kvm_xen_vcpu_attr { __u16 type; __u16 pad[3]; union { __u64 gpa; __u64 pad[4]; } u; }; type values: KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO Sets the guest physical address of the vcpu_info for a given vCPU. KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO Sets the guest physical address of an additional pvclock structure for a given vCPU. This is typically used for guest vsyscall support. 4.130 KVM_XEN_VCPU_GET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vcpu ioctl :Parameters: struct kvm_xen_vcpu_attr :Returns: 0 on success, < 0 on error Allows Xen vCPU attributes to be read. For the structure and types, see KVM_XEN_VCPU_SET_ATTR above. 5. The kvm_run structure ======================== Loading Loading @@ -4998,13 +5101,18 @@ to the byte array. .. note:: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, KVM_EXIT_XEN, KVM_EXIT_EPR, KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding operations are complete (and guest state is consistent) only after userspace has re-entered the kernel with KVM_RUN. The kernel side will first finish incomplete operations and then check for pending signals. Userspace can re-enter the guest with an unmasked signal pending to complete pending operations. incomplete operations and then check for pending signals. The pending state of the operation is not preserved in state which is visible to userspace, thus userspace should ensure that the operation is completed before performing a live migration. Userspace can re-enter the guest with an unmasked signal pending or with the immediate_exit field set to complete pending operations without allowing any further instructions to be executed. :: Loading Loading @@ -5329,6 +5437,34 @@ wants to write. Once finished processing the event, user space must continue vCPU execution. If the MSR write was unsuccessful, user space also sets the "error" field to "1". :: struct kvm_xen_exit { #define KVM_EXIT_XEN_HCALL 1 __u32 type; union { struct { __u32 longmode; __u32 cpl; __u64 input; __u64 result; __u64 params[6]; } hcall; } u; }; /* KVM_EXIT_XEN */ struct kvm_hyperv_exit xen; Indicates that the VCPU exits into userspace to process some tasks related to Xen emulation. Valid values for 'type' are: - KVM_EXIT_XEN_HCALL -- synchronously notify user-space about Xen hypercall. Userspace is expected to place the hypercall result into the appropriate field before invoking KVM_RUN again. :: /* Fix the size of the union. */ Loading Loading @@ -6454,7 +6590,6 @@ guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf (0x40000001). Otherwise, a guest may use the paravirtual features regardless of what has actually been exposed through the CPUID leaf. 8.29 KVM_CAP_DIRTY_LOG_RING --------------------------- Loading Loading @@ -6541,3 +6676,29 @@ KVM_GET_DIRTY_LOG and KVM_CLEAR_DIRTY_LOG. After enabling KVM_CAP_DIRTY_LOG_RING with an acceptable dirty ring size, the virtual machine will switch to ring-buffer dirty page tracking and further KVM_GET_DIRTY_LOG or KVM_CLEAR_DIRTY_LOG ioctls will fail. 8.30 KVM_CAP_XEN_HVM -------------------- :Architectures: x86 This capability indicates the features that Xen supports for hosting Xen PVHVM guests. Valid flags are:: #define KVM_XEN_HVM_CONFIG_HYPERCALL_MSR (1 << 0) #define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1) #define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2) The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG ioctl is available, for the guest to set its hypercall page. If KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL is also set, the same flag may also be provided in the flags to KVM_XEN_HVM_CONFIG, without providing hypercall page contents, to request that KVM generate hypercall page content automatically and also enable interception of guest hypercalls with KVM_EXIT_XEN. The KVM_XEN_HVM_CONFIG_SHARED_INFO flag indicates the availability of the KVM_XEN_HVM_SET_ATTR, KVM_XEN_HVM_GET_ATTR, KVM_XEN_VCPU_SET_ATTR and KVM_XEN_VCPU_GET_ATTR ioctls, as well as the delivery of exception vectors for event channel upcalls when the evtchn_upcall_pending field of a vcpu's vcpu_info is set. Loading
Documentation/virt/kvm/api.rst +166 −5 Original line number Diff line number Diff line Loading @@ -960,6 +960,14 @@ memory. __u8 pad2[30]; }; If the KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag is returned from the KVM_CAP_XEN_HVM check, it may be set in the flags field of this ioctl. This requests KVM to generate the contents of the hypercall page automatically; hypercalls will be intercepted and passed to userspace through KVM_EXIT_XEN. In this case, all of the blob size and address fields must be zero. No other flags are currently valid in the struct kvm_xen_hvm_config. 4.29 KVM_GET_CLOCK ------------------ Loading Loading @@ -4831,6 +4839,101 @@ into user space. If a vCPU is in running state while this ioctl is invoked, the vCPU may experience inconsistent filtering behavior on MSR accesses. 4.127 KVM_XEN_HVM_SET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vm ioctl :Parameters: struct kvm_xen_hvm_attr :Returns: 0 on success, < 0 on error :: struct kvm_xen_hvm_attr { __u16 type; __u16 pad[3]; union { __u8 long_mode; __u8 vector; struct { __u64 gfn; } shared_info; __u64 pad[4]; } u; }; type values: KVM_XEN_ATTR_TYPE_LONG_MODE Sets the ABI mode of the VM to 32-bit or 64-bit (long mode). This determines the layout of the shared info pages exposed to the VM. KVM_XEN_ATTR_TYPE_SHARED_INFO Sets the guest physical frame number at which the Xen "shared info" page resides. Note that although Xen places vcpu_info for the first 32 vCPUs in the shared_info page, KVM does not automatically do so and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO be used explicitly even when the vcpu_info for a given vCPU resides at the "default" location in the shared_info page. This is because KVM is not aware of the Xen CPU id which is used as the index into the vcpu_info[] array, so cannot know the correct default location. KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Sets the exception vector used to deliver Xen event channel upcalls. 4.128 KVM_XEN_HVM_GET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vm ioctl :Parameters: struct kvm_xen_hvm_attr :Returns: 0 on success, < 0 on error Allows Xen VM attributes to be read. For the structure and types, see KVM_XEN_HVM_SET_ATTR above. 4.129 KVM_XEN_VCPU_SET_ATTR --------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vcpu ioctl :Parameters: struct kvm_xen_vcpu_attr :Returns: 0 on success, < 0 on error :: struct kvm_xen_vcpu_attr { __u16 type; __u16 pad[3]; union { __u64 gpa; __u64 pad[4]; } u; }; type values: KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO Sets the guest physical address of the vcpu_info for a given vCPU. KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO Sets the guest physical address of an additional pvclock structure for a given vCPU. This is typically used for guest vsyscall support. 4.130 KVM_XEN_VCPU_GET_ATTR -------------------------- :Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO :Architectures: x86 :Type: vcpu ioctl :Parameters: struct kvm_xen_vcpu_attr :Returns: 0 on success, < 0 on error Allows Xen vCPU attributes to be read. For the structure and types, see KVM_XEN_VCPU_SET_ATTR above. 5. The kvm_run structure ======================== Loading Loading @@ -4998,13 +5101,18 @@ to the byte array. .. note:: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, KVM_EXIT_XEN, KVM_EXIT_EPR, KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding operations are complete (and guest state is consistent) only after userspace has re-entered the kernel with KVM_RUN. The kernel side will first finish incomplete operations and then check for pending signals. Userspace can re-enter the guest with an unmasked signal pending to complete pending operations. incomplete operations and then check for pending signals. The pending state of the operation is not preserved in state which is visible to userspace, thus userspace should ensure that the operation is completed before performing a live migration. Userspace can re-enter the guest with an unmasked signal pending or with the immediate_exit field set to complete pending operations without allowing any further instructions to be executed. :: Loading Loading @@ -5329,6 +5437,34 @@ wants to write. Once finished processing the event, user space must continue vCPU execution. If the MSR write was unsuccessful, user space also sets the "error" field to "1". :: struct kvm_xen_exit { #define KVM_EXIT_XEN_HCALL 1 __u32 type; union { struct { __u32 longmode; __u32 cpl; __u64 input; __u64 result; __u64 params[6]; } hcall; } u; }; /* KVM_EXIT_XEN */ struct kvm_hyperv_exit xen; Indicates that the VCPU exits into userspace to process some tasks related to Xen emulation. Valid values for 'type' are: - KVM_EXIT_XEN_HCALL -- synchronously notify user-space about Xen hypercall. Userspace is expected to place the hypercall result into the appropriate field before invoking KVM_RUN again. :: /* Fix the size of the union. */ Loading Loading @@ -6454,7 +6590,6 @@ guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf (0x40000001). Otherwise, a guest may use the paravirtual features regardless of what has actually been exposed through the CPUID leaf. 8.29 KVM_CAP_DIRTY_LOG_RING --------------------------- Loading Loading @@ -6541,3 +6676,29 @@ KVM_GET_DIRTY_LOG and KVM_CLEAR_DIRTY_LOG. After enabling KVM_CAP_DIRTY_LOG_RING with an acceptable dirty ring size, the virtual machine will switch to ring-buffer dirty page tracking and further KVM_GET_DIRTY_LOG or KVM_CLEAR_DIRTY_LOG ioctls will fail. 8.30 KVM_CAP_XEN_HVM -------------------- :Architectures: x86 This capability indicates the features that Xen supports for hosting Xen PVHVM guests. Valid flags are:: #define KVM_XEN_HVM_CONFIG_HYPERCALL_MSR (1 << 0) #define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1) #define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2) The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG ioctl is available, for the guest to set its hypercall page. If KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL is also set, the same flag may also be provided in the flags to KVM_XEN_HVM_CONFIG, without providing hypercall page contents, to request that KVM generate hypercall page content automatically and also enable interception of guest hypercalls with KVM_EXIT_XEN. The KVM_XEN_HVM_CONFIG_SHARED_INFO flag indicates the availability of the KVM_XEN_HVM_SET_ATTR, KVM_XEN_HVM_GET_ATTR, KVM_XEN_VCPU_SET_ATTR and KVM_XEN_VCPU_GET_ATTR ioctls, as well as the delivery of exception vectors for event channel upcalls when the evtchn_upcall_pending field of a vcpu's vcpu_info is set.
David Woodhouse <dwmw@amazon.co.uk>David Woodhouse <dwmw@amazon.co.uk>