Re: [PATCH v4 36/36] KVM: s390: protvirt: Add KVM api documentation

[Cornelia Huck <cohuck@redhat.com>]

On Mon, 24 Feb 2020 06:41:07 -0500
Christian Borntraeger <borntraeger@de.ibm.com> wrote:

> From: Janosch Frank <frankja@linux.ibm.com>
> 
> Add documentation for KVM_CAP_S390_PROTECTED capability and the
> KVM_S390_PV_COMMAND ioctl.
> 
> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
> [borntraeger@de.ibm.com: patch merging, splitting, fixing]
> Signed-off-by: Christian Borntraeger <borntraeger@de.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 55 ++++++++++++++++++++++++++++++++++
>  1 file changed, 55 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 7505d7a6c0d8..20abb8b2594e 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -4648,6 +4648,51 @@ the clear cpu reset definition in the POP. However, the cpu is not put
>  into ESA mode. This reset is a superset of the initial reset.
>  
>  
> +4.125 KVM_S390_PV_COMMAND
> +-------------------------
> +
> +:Capability: KVM_CAP_S390_PROTECTED
> +:Architectures: s390
> +:Type: vm ioctl
> +:Parameters: struct kvm_pv_cmd
> +:Returns: 0 on success, < 0 on error
> +
> +::
> +
> +  struct kvm_pv_cmd {
> +	__u32 cmd;	/* Command to be executed */
> +	__u16 rc;	/* Ultravisor return code */
> +	__u16 rrc;	/* Ultravisor return reason code */
> +	__u64 data;	/* Data or address */
> +	__u32 flags;    /* flags for future extensions. Must be 0 for now */
> +	__u32 reserved[3];
> +  };
> +
> +cmd values:
> +
> +KVM_PV_ENABLE
> +  Allocate memory and register the VM with the Ultravisor, thereby
> +  donating memory to the Ultravisor making it inaccessible to KVM.
> +  Also converts all existing CPUs to protected ones. Future hotplug
> +  CPUs will become protected during creation.

"Allocate memory and register the VM with the Ultravisor, thereby
donating memory to the Ultravisor that will become inaccsessible to
KVM. All existing CPUs are converted to protected ones. After this
command has succeeded, any CPU added via hotplug will become protected
during its creation as well."

> +
> +KVM_PV_DISABLE
> +  Deregisters the VM from the Ultravisor and frees memory that was
> +  donated, so the kernel can use it again. All registered VCPUs are
> +  converted back to non-protected ones.

"Deregister the VM from the Ultravisor and reclaim the memory that had
been donated to the Ultravisor, making it usable by the kernel again.
..."

> +
> +KVM_PV_VM_SET_SEC_PARMS
> +  Pass the image header from VM memory to the Ultravisor in
> +  preparation of image unpacking and verification.
> +
> +KVM_PV_VM_UNPACK
> +  Unpack (protect and decrypt) a page of the encrypted boot image.
> +
> +KVM_PV_VM_VERIFY
> +  Verify the integrity of the unpacked image. Only if this succeeds,
> +  KVM is allowed to start protected VCPUs.
> +
> +
>  5. The kvm_run structure
>  ========================
>  
> @@ -6026,3 +6071,13 @@ Architectures: s390
>  
>  This capability indicates that the KVM_S390_NORMAL_RESET and
>  KVM_S390_CLEAR_RESET ioctls are available.
> +
> +8.23 KVM_CAP_S390_PROTECTED
> +
> +Architecture: s390
> +
> +This capability indicates that KVM can start protected VMs and the
> +Ultravisor has therefore been initialized.

"This capability indicates that the Ultravisor has been initialized and
KVM can therefore start protected VMs."

> +This will provide the new KVM_S390_PV_COMMAND ioctl and it will allow
> +KVM_MP_STATE_LOAD as new MP_STATE. KVM_SET_MP_STATE can now fail for
> +protected guests when the state change is invalid.

"This capability governs the KVM_S390_PV_COMMAND ioctl and the
KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
guests when the state change is invalid."