[PATCH v3 6/6] docs: add s390-pv documentation

[Pavel Hrdina]

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 at linux.ibm.com>
> Reviewed-by: Daniel Henrique Barboza <danielhb413 at 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
> 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20210625/da4b1a78/attachment-0001.sig>