Document KVM_MIGRATE_CMD. To support live migration of confidential computing guests, the hardware may need to pass migration command related data between the source and destination. For confidential computing, the migration command related data is not accessible to KVM. Signed-off-by: Tony Lindgren --- Documentation/virt/kvm/api.rst | 47 ++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 6ae24c5ca559..31db949d3e44 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6504,6 +6504,53 @@ the capability to be present. `flags` must currently be zero. +4.144 KVM_MIGRATE_CMD +--------------------- + +:Capability: KVM_CAP_MIGRATION +:Architectures: arm64, x86 +:Type: vm ioctl +:Parameters: struct kvm_migrate_cmd (in/out) +:Returns: 0 on success, < 0 on error + +Allows userspace to send migration commands to the hardware. + +For confidential computing, the migration commands may use encrypted data +that needs to be passed between the source and destination hardware. The +hardware may also require specific coordination steps during migration that +must be triggered at precise points in the migration process. + +The parameter related data structures are:: + + #define KVM_MIGRATE_PREPARE 0 + #define KVM_MIGRATE_SETUP 1 + #define KVM_MIGRATE_TOKEN 2 + #define KVM_MIGRATE_SOURCE_BLACKOUT 3 + #define KVM_MIGRATE_ABORT 4 + #define KVM_MIGRATE_FINISH 5 + + struct kvm_transfer_buffer { + __u64 address; + __u32 size; + __u32 reserved; + }; + + @address - Userspace buffer address + @size - Size of the userspace buffer + @reserved - Reserved for future use + + struct kvm_migrate_cmd { + __u16 command; + __u16 flags; + __u32 reserved; + struct kvm_transfer_buffer buf; + }; + + @command - One of the defined KVM_MIGRATE commands + @flags - Hardware specific flags + @reserved - Reserved for future use + @buf - Userspace buffer for hardware specific data + .. _kvm_run: 5. The kvm_run structure -- 2.43.0 Document KVM_IMPORT_MEMORY and KVM_EXPORT_MEMORY. To support live migration of confidential computing guests, the hardware needs to export the encrypted pages on the source and to import the encrypted pages on the destination. Signed-off-by: Tony Lindgren --- Documentation/virt/kvm/api.rst | 89 +++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 31db949d3e44..dec73fd2c5bf 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6503,7 +6503,6 @@ the capability to be present. `flags` must currently be zero. - 4.144 KVM_MIGRATE_CMD --------------------- @@ -6551,6 +6550,94 @@ The parameter related data structures are:: @reserved - Reserved for future use @buf - Userspace buffer for hardware specific data +.. _KVM_IMPORT_MEMORY: + +4.145 KVM_IMPORT_MEMORY +----------------------- + +:Capability: KVM_CAP_MIGRATION +:Architectures: arm64, x86 +:Type: vm ioctl +:Parameters: struct kvm_memory_transfer (in/out) +:Returns: 0 on success, < 0 on error + +Allows userspace to request the hardware to import an array of memory pages from +a userspace buffer. + +The memory may not be directly accessible to KVM because of encryption. For +confidential computing, the guest memory is encrypted and only accessible to the +guest. + +The parameter related data structures are:: + + struct kvm_transfer_buffer { + __u64 address; + __u32 size; + __u32 reserved; + }; + + @address - Userspace buffer address + @size - Size of the userspace buffer + @reserved - Reserved for future use + + struct kvm_memory_transfer { + __u64 gfns; + __u32 nr_gfns; + __u16 id; + __u16 flags; + __u64 reserved; + struct kvm_transfer_buffer buf; + }; + + @gfns - Userspace array of GFNs to import + @nr_gfns - Number of GFNs + @id - Optional hardware specific transfer ID + @flags - Hardware specific flags + @reserved - Reserved for future use + @buf - Userspace buffer to import memory from + +The hardware specific ID is used at least for TDX for the migration thread +index. + +4.146 KVM_EXPORT_MEMORY +----------------------- + +:Capability: KVM_CAP_MIGRATION +:Architectures: arm64, x86 +:Type: vm ioctl +:Parameters: struct kvm_memory_transfer (in/out) +:Returns: 0 on success, < 0 on error + +Allows userspace to request the hardware to export an array of memory pages +to a userspace buffer. + +The memory may not be directly accessible to KVM because of encryption. For +confidential computing, the guest memory is encrypted and only accessible to the +guest. + +The parameters are:: + + struct kvm_memory_transfer { + __u64 gfns; + __u32 nr_gfns; + __u16 id; + __u16 flags; + __u64 reserved; + struct kvm_transfer_buffer buf; + }; + + @gfns - Userspace array of GFNs to export + @nr_gfns - Number of GFNs + @id - Optional hardware specific transfer ID + @flags - Hardware specific flags + @reserved - Reserved for future use + @buf - Userspace buffer to export memory to + +The hardware specific ID is used at least for TDX for the migration thread +index. + +See also :ref:`KVM_IMPORT_MEMORY `. + .. _kvm_run: 5. The kvm_run structure -- 2.43.0 Document KVM_IMPORT_VCPU and KVM_EXPORT_VCPU. To support live migration of confidential computing guests, the hardware needs to export the encrypted VCPU state on the source and to import the encrypted VCPU state on the destination. Signed-off-by: Tony Lindgren --- Documentation/virt/kvm/api.rst | 69 ++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index dec73fd2c5bf..d9499e3b461a 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6638,6 +6638,75 @@ index. See also :ref:`KVM_IMPORT_MEMORY `. +.. _KVM_IMPORT_VCPU: + +4.147 KVM_IMPORT_VCPU +--------------------- + +:Capability: KVM_CAP_MIGRATION +:Architectures: arm64, x86 +:Type: vcpu ioctl +:Parameters: struct kvm_vcpu_transfer (in/out) +:Returns: 0 on success, < 0 on error + +Allows userspace to request the hardware to import a VCPU state from a userspace +buffer. + +The VCPU state may not be directly accessible to KVM because of encryption. For +confidential computing, the VCPU state is encrypted and only accessible to the +guest. + +The parameter related data structures are:: + + struct kvm_transfer_buffer { + __u64 address; + __u32 size; + __u32 reserved; + }; + + @address - Userspace buffer address + @size - Size of the userspace buffer + @reserved - Reserved for future use + + struct kvm_vcpu_transfer { + __u32 flags; + __u32 reserved; + struct kvm_transfer_buffer buf; + }; + + @flags - Hardware specific flags + @reserved - Reserved for future use + @buf - Userspace buffer to import VCPU state from + +4.148 KVM_EXPORT_VCPU +--------------------- +:Capability: KVM_CAP_MIGRATION +:Architectures: arm64, x86 +:Type: vcpu ioctl +:Parameters: struct kvm_vcpu_transfer (in/out) +:Returns: 0 on success, < 0 on error + +Allows userspace to request the hardware to export a VCPU state to a userspace +buffer. + +The VCPU state may not be directly accessible to KVM because of encryption. For +confidential computing, the VCPU state is encrypted and only accessible to the +guest. + +The parameters are:: + + struct kvm_vcpu_transfer { + __u32 flags; + __u32 reserved; + struct kvm_transfer_buffer buf; + }; + + @flags - Hardware specific flags + @reserved - Reserved for future use + @buf - Userspace buffer to export VCPU state to + +See also :ref:`KVM_IMPORT_VCPU `. + .. _kvm_run: 5. The kvm_run structure -- 2.43.0