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

Christian Borntraeger
2020-02-25T19:30:42Z

On 25.02.20 16:50, Cornelia Huck wrote:
> 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."

ok

>> +
>> +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.
> ..."

ok

>
>> +
>> +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."

ok.
>
>> +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."

ok