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

[Cornelia Huck <cohuck@redhat.com>]

On Thu, 27 Feb 2020 03:47:17 -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 | 59 ++++++++++++++++++++++++++++++++++
>  1 file changed, 59 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 7505d7a6c0d8..bae90f3cd11d 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -4648,6 +4648,54 @@ 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 that will become inaccessible 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
> +
> +  Deregister the VM from the Ultravisor and reclaim the memory that
> +  had been donated to the Ultravisor, making it usable by the kernel
> +  again.  All registered VCPUs are converted back to non-protected
> +  ones.

Do you want to mention that memory might be lost on error? Or is that
too far in should-not-happen-land for callers to care about?

Anyway,
Reviewed-by: Cornelia Huck <cohuck@redhat.com>