Add documentation for launch security type s390-pv.

Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
---
 docs/formatdomain.rst              |  7 ++++
 docs/kbase/s390_protected_virt.rst | 55 +++++++++++++++++++++++++-----
 2 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index c6dede053f..a1b028c4ad 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -8078,6 +8078,13 @@ Note: DEA/TDEA is synonymous with DES/TDES.
 Launch Security
 ---------------
 
+Specifying ``<launchSecurity type='s390-pv'\>`` in a s390 domain prepares
+the guest to run in protected virtualization secure mode, also known as
+IBM Secure Execution. For more required host and guest preparation steps, see
+`Protected Virtualization on s390 <kbase/s390_protected_virt.html>`__
+:since:`Since 7.5.0`
+
+
 The contents of the ``<launchSecurity type='sev'>`` element is used to provide
 the guest owners input used for creating an encrypted VM using the AMD SEV
 feature (Secure Encrypted Virtualization). SEV is an extension to the AMD-V
diff --git a/docs/kbase/s390_protected_virt.rst b/docs/kbase/s390_protected_virt.rst
index 1718a556d4..66203568d9 100644
--- a/docs/kbase/s390_protected_virt.rst
+++ b/docs/kbase/s390_protected_virt.rst
@@ -127,10 +127,13 @@ Protected virtualization guests support I/O using virtio devices.
 As the virtio data structures of secure guests are not accessible
 by the host, it is necessary to use shared memory ('bounce buffers').
 
-To enable virtio devices to use shared buffers, it is necessary
-to configure them with platform_iommu enabled. This can done by adding
-``iommu='on'`` to the driver element of a virtio device definition in the
-guest's XML, e.g.
+Since libvirt 7.5.0 the
+`<launchSecurity> <https://libvirt.org/formatdomain.html#launchSecurity>`__
+element with type ``s390-pv`` should be used on protected virtualization guests.
+Without ``launchSecurity`` you must enable all virtio devices to use shared
+buffers by configuring them with platform_iommu enabled.
+This can done by adding ``iommu='on'`` to the driver element of a virtio
+device definition in the guest's XML, e.g.
 
 ::
 
@@ -140,8 +143,10 @@ guest's XML, e.g.
      <driver name='vhost' iommu='on'/>
    </interface>
 
-It is mandatory to define all virtio bus devices in this way to
-prevent the host from attempting to access protected memory.
+Unless you are using ``launchSecurity`` you must define all virtio bus
+devices in this way to prevent the host from attempting to access
+protected memory.
+
 Ballooning will not work and is fenced by QEMU. It should be
 disabled by specifying
 
@@ -158,8 +163,42 @@ allocated 2K entries. A commonly used value for swiotlb is 262144.
 Example guest definition
 ========================
 
-Minimal domain XML for a protected virtualization guest, essentially
-it's mostly about the ``iommu`` property
+Minimal domain XML for a protected virtualization guest with
+the ``launchSecurity`` element of type ``s390-pv``
+
+::
+
+   <domain type='kvm'>
+     <name>protected</name>
+     <memory unit='KiB'>2048000</memory>
+     <currentMemory unit='KiB'>2048000</currentMemory>
+     <vcpu>1</vcpu>
+     <os>
+       <type arch='s390x'>hvm</type>
+     </os>
+     <cpu mode='host-model'/>
+     <devices>
+       <disk type='file' device='disk'>
+         <driver name='qemu' type='qcow2' cache='none' io='native'>
+         <source file='/var/lib/libvirt/images/protected.qcow2'/>
+         <target dev='vda' bus='virtio'/>
+       </disk>
+       <interface type='network'>
+         <source network='default'/>
+         <model type='virtio'/>
+       </interface>
+       <console type='pty'/>
+       <memballoon model='none'/>
+     </devices>
+     <launchSecurity type='s390-pv'/>
+   </domain>
+
+
+Example guest definition without launchSecurity
+===============================================
+
+Minimal domain XML for a protected virtualization guest using the
+``iommu='on'`` setting for each virtio device.
 
 ::
 
-- 
2.30.2

On Tue, Jun 22, 2021 at 03:10:49PM +0200, Boris Fiuczynski wrote:
> Add documentation for launch security type s390-pv.
> 
> Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
> Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
> ---
>  docs/formatdomain.rst              |  7 ++++
>  docs/kbase/s390_protected_virt.rst | 55 +++++++++++++++++++++++++-----
>  2 files changed, 54 insertions(+), 8 deletions(-)
> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index c6dede053f..a1b028c4ad 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -8078,6 +8078,13 @@ Note: DEA/TDEA is synonymous with DES/TDES.
>  Launch Security
>  ---------------
>  
> +Specifying ``<launchSecurity type='s390-pv'\>`` in a s390 domain prepares
> +the guest to run in protected virtualization secure mode, also known as
> +IBM Secure Execution. For more required host and guest preparation steps, see
> +`Protected Virtualization on s390 <kbase/s390_protected_virt.html>`__
> +:since:`Since 7.5.0`
> +
> +
>  The contents of the ``<launchSecurity type='sev'>`` element is used to provide
>  the guest owners input used for creating an encrypted VM using the AMD SEV
>  feature (Secure Encrypted Virtualization). SEV is an extension to the AMD-V
> diff --git a/docs/kbase/s390_protected_virt.rst b/docs/kbase/s390_protected_virt.rst
> index 1718a556d4..66203568d9 100644
> --- a/docs/kbase/s390_protected_virt.rst
> +++ b/docs/kbase/s390_protected_virt.rst
> @@ -127,10 +127,13 @@ Protected virtualization guests support I/O using virtio devices.
>  As the virtio data structures of secure guests are not accessible
>  by the host, it is necessary to use shared memory ('bounce buffers').
>  
> -To enable virtio devices to use shared buffers, it is necessary
> -to configure them with platform_iommu enabled. This can done by adding
> -``iommu='on'`` to the driver element of a virtio device definition in the
> -guest's XML, e.g.
> +Since libvirt 7.5.0 the
> +`<launchSecurity> <https://libvirt.org/formatdomain.html#launchSecurity>`__
> +element with type ``s390-pv`` should be used on protected virtualization guests.
> +Without ``launchSecurity`` you must enable all virtio devices to use shared
> +buffers by configuring them with platform_iommu enabled.
> +This can done by adding ``iommu='on'`` to the driver element of a virtio
> +device definition in the guest's XML, e.g.
>  
>  ::
>  
> @@ -140,8 +143,10 @@ guest's XML, e.g.
>       <driver name='vhost' iommu='on'/>
>     </interface>
>  
> -It is mandatory to define all virtio bus devices in this way to
> -prevent the host from attempting to access protected memory.
> +Unless you are using ``launchSecurity`` you must define all virtio bus
> +devices in this way to prevent the host from attempting to access
> +protected memory.
> +
>  Ballooning will not work and is fenced by QEMU. It should be
>  disabled by specifying
>  
> @@ -158,8 +163,42 @@ allocated 2K entries. A commonly used value for swiotlb is 262144.
>  Example guest definition
>  ========================
>  
> -Minimal domain XML for a protected virtualization guest, essentially
> -it's mostly about the ``iommu`` property
> +Minimal domain XML for a protected virtualization guest with
> +the ``launchSecurity`` element of type ``s390-pv``
> +
> +::
> +
> +   <domain type='kvm'>
> +     <name>protected</name>
> +     <memory unit='KiB'>2048000</memory>
> +     <currentMemory unit='KiB'>2048000</currentMemory>
> +     <vcpu>1</vcpu>
> +     <os>
> +       <type arch='s390x'>hvm</type>
> +     </os>
> +     <cpu mode='host-model'/>
> +     <devices>
> +       <disk type='file' device='disk'>
> +         <driver name='qemu' type='qcow2' cache='none' io='native'>
> +         <source file='/var/lib/libvirt/images/protected.qcow2'/>
> +         <target dev='vda' bus='virtio'/>
> +       </disk>
> +       <interface type='network'>
> +         <source network='default'/>
> +         <model type='virtio'/>
> +       </interface>
> +       <console type='pty'/>
> +       <memballoon model='none'/>
> +     </devices>
> +     <launchSecurity type='s390-pv'/>
> +   </domain>
> +
> +
> +Example guest definition without launchSecurity
> +===============================================
> +
> +Minimal domain XML for a protected virtualization guest using the
> +``iommu='on'`` setting for each virtio device.

I don't know how s390-pv works but for example with AMD SEV it is
required to use `iommu='on'` otherwise the device is not visible inside
the VM so I would like to make sure there is no misunderstanding and
it is correct.

Pavel

>  ::
>  
> -- 
> 2.30.2
> 

...

> > +Example guest definition without launchSecurity
> > +===============================================
> > +
> > +Minimal domain XML for a protected virtualization guest using the
> > +``iommu='on'`` setting for each virtio device.
> 
> I don't know how s390-pv works but for example with AMD SEV it is
> required to use `iommu='on'` otherwise the device is not visible inside
> the VM so I would like to make sure there is no misunderstanding and
> it is correct.

Can you elaborate on how is the device not visible in the VM? IIRC 'iommu=on'
makes sure that the guest virtio driver is able to negotiate the
VIRTIO_F_IOMMU_PLATFORM feature which in connection with the correct IOMMU model
setting makes SEV work with virtio and IOMMU
(AFAIR OVMF has a dedicated SEV iommu driver).

Therefore, that flag should have nothing to do with device visibility, in fact
in x86_64's case it will be a PCI device, so you'll always be able to list
those.

Regards,
Erik

On 6/25/21 12:11 PM, Pavel Hrdina wrote:
>> @@ -158,8 +163,42 @@ allocated 2K entries. A commonly used value for swiotlb is 262144.
>>   Example guest definition
>>   ========================
>>   
>> -Minimal domain XML for a protected virtualization guest, essentially
>> -it's mostly about the ``iommu`` property
>> +Minimal domain XML for a protected virtualization guest with
>> +the ``launchSecurity`` element of type ``s390-pv``
>> +
>> +::
>> +
>> +   <domain type='kvm'>
>> +     <name>protected</name>
>> +     <memory unit='KiB'>2048000</memory>
>> +     <currentMemory unit='KiB'>2048000</currentMemory>
>> +     <vcpu>1</vcpu>
>> +     <os>
>> +       <type arch='s390x'>hvm</type>
>> +     </os>
>> +     <cpu mode='host-model'/>
>> +     <devices>
>> +       <disk type='file' device='disk'>
>> +         <driver name='qemu' type='qcow2' cache='none' io='native'>
>> +         <source file='/var/lib/libvirt/images/protected.qcow2'/>
>> +         <target dev='vda' bus='virtio'/>
>> +       </disk>
>> +       <interface type='network'>
>> +         <source network='default'/>
>> +         <model type='virtio'/>
>> +       </interface>
>> +       <console type='pty'/>
>> +       <memballoon model='none'/>
>> +     </devices>
>> +     <launchSecurity type='s390-pv'/>
>> +   </domain>
>> +
>> +
>> +Example guest definition without launchSecurity
>> +===============================================
>> +
>> +Minimal domain XML for a protected virtualization guest using the
>> +``iommu='on'`` setting for each virtio device.
> I don't know how s390-pv works but for example with AMD SEV it is
> required to use `iommu='on'` otherwise the device is not visible inside
> the VM so I would like to make sure there is no misunderstanding and
> it is correct.
> 
> Pavel
> 

Using IBM Secure Execution you have to use `iommu='on'` on each virtio 
device. If you do not do so the devices will be available in the guest 
but it is very likely that once some tries to use these devices the 
guest very likely is going to crash.
BUT when specifying launchSecurity with type 's390-pv' one does not have 
to use `iommu='on'` on each virtio device any longer!

I tried to cover that with this change in the docs:
+Since libvirt 7.5.0 the
+`<launchSecurity> <https://libvirt.org/formatdomain.html#launchSecurity>`__
+element with type ``s390-pv`` should be used on protected 
virtualization guests.
+Without ``launchSecurity`` you must enable all virtio devices to use shared
+buffers by configuring them with platform_iommu enabled.

-- 
Mit freundlichen Grüßen/Kind regards
    Boris Fiuczynski

IBM Deutschland Research & Development GmbH
Vorsitzender des Aufsichtsrats: Gregor Pillen
Geschäftsführung: Dirk Wittkopp
Sitz der Gesellschaft: Böblingen
Registergericht: Amtsgericht Stuttgart, HRB 243294