diff mbox series

[v10,15/16] docs: system: Add protvirt docs

Message ID 20200318143047.2335-16-frankja@linux.ibm.com (mailing list archive)
State New, archived
Headers show
Series s390x: Protected Virtualization support | expand

Commit Message

Janosch Frank March 18, 2020, 2:30 p.m. UTC
Let's add some documentation for the Protected VM functionality.

Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
Acked-by: David Hildenbrand <david@redhat.com>
Reviewed-by: Claudio Imbrenda <imbrenda@linux.ibm.com>
---
 docs/system/s390x/protvirt.rst | 59 ++++++++++++++++++++++++++++++++++
 docs/system/target-s390x.rst   |  5 +++
 2 files changed, 64 insertions(+)
 create mode 100644 docs/system/s390x/protvirt.rst

Comments

Cornelia Huck March 18, 2020, 2:53 p.m. UTC | #1
On Wed, 18 Mar 2020 10:30:46 -0400
Janosch Frank <frankja@linux.ibm.com> wrote:

> Let's add some documentation for the Protected VM functionality.
> 
> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
> Acked-by: David Hildenbrand <david@redhat.com>
> Reviewed-by: Claudio Imbrenda <imbrenda@linux.ibm.com>
> ---
>  docs/system/s390x/protvirt.rst | 59 ++++++++++++++++++++++++++++++++++
>  docs/system/target-s390x.rst   |  5 +++
>  2 files changed, 64 insertions(+)
>  create mode 100644 docs/system/s390x/protvirt.rst

(...)

> +Booting from the image supplied on the QEMU command line requires that
> +the file passed via -kernel has the same memory layout as would result
> +from the disk boot. This memory layout includes the encrypted
> +components (kernel, initrd, cmdline), the stage3a loader and
> +metadata. In case this boot method is used, the command line
> +options -initrd and -cmdline are ineffective. The preparation of a PVM
> +image is done via the `genprotimg` tool from the s390-tools package.

I still think 'package' is not a good name (yes, I realize that
s390-tools' README uses that term as well :) I'd prefer 'collection' or
something like that, so it doesn't get confused with distro packages,
which may use a different name. But no strong opinion.

> diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
> index 4c8b7cdd66154d26..8d97158dc804af1c 100644
> --- a/docs/system/target-s390x.rst
> +++ b/docs/system/target-s390x.rst
> @@ -24,3 +24,8 @@ or vfio-ap is also available.
>  .. toctree::
>     s390x/vfio-ap
>  
> +Architectural features
> +~~~~~~~~

Architecture features
=====================

?

> +
> +.. toctree::
> +   s390x/protvirt

Otherwise, looks good to me.
Christian Borntraeger March 18, 2020, 4:50 p.m. UTC | #2
On 18.03.20 15:30, Janosch Frank wrote:
> Let's add some documentation for the Protected VM functionality.
> 
> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
> Acked-by: David Hildenbrand <david@redhat.com>
> Reviewed-by: Claudio Imbrenda <imbrenda@linux.ibm.com>

Acked-by: Christian Borntraeger <borntraeger@de.ibm.com>

> ---
>  docs/system/s390x/protvirt.rst | 59 ++++++++++++++++++++++++++++++++++
>  docs/system/target-s390x.rst   |  5 +++
>  2 files changed, 64 insertions(+)
>  create mode 100644 docs/system/s390x/protvirt.rst
> 
> diff --git a/docs/system/s390x/protvirt.rst b/docs/system/s390x/protvirt.rst
> new file mode 100644
> index 0000000000000000..71172511632f7bcb
> --- /dev/null
> +++ b/docs/system/s390x/protvirt.rst
> @@ -0,0 +1,59 @@
> +Protected Virtualization on s390x
> +=================================
> +
> +The memory and most of the registers of Protected Virtual Machines
> +(PVMs) are encrypted or inaccessible to the hypervisor, effectively
> +prohibiting VM introspection when the VM is running. At rest, PVMs are
> +encrypted and can only be decrypted by the firmware, represented by an
> +entity called Ultravisor, of specific IBM Z machines.
> +
> +
> +Prerequisites
> +-------------
> +
> +To run PVMs, a machine with the Protected Virtualization feature, as
> +indicated by the Ultravisor Call facility (stfle bit 158), is
> +required. The Ultravisor needs to be initialized at boot by setting
> +`prot_virt=1` on the host's kernel command line.
> +
> +Running PVMs requires using the KVM hypervisor.
> +
> +If those requirements are met, the capability `KVM_CAP_S390_PROTECTED`
> +will indicate that KVM can support PVMs on that LPAR.
> +
> +
> +QEMU Settings
> +-------------
> +
> +To indicate to the VM that it can transition into protected mode, the
> +`Unpack facility` (stfle bit 161 represented by the feature
> +`unpack`/`S390_FEAT_UNPACK`) needs to be part of the cpu model of
> +the VM.
> +
> +All I/O devices need to use the IOMMU.
> +Passthrough (vfio) devices are currently not supported.
> +
> +Host huge page backings are not supported. However guests can use huge
> +pages as indicated by its facilities.
> +
> +
> +Boot Process
> +------------
> +
> +A secure guest image can either be loaded from disk or supplied on the
> +QEMU command line. Booting from disk is done by the unmodified
> +s390-ccw BIOS. I.e., the bootmap is interpreted, multiple components
> +are read into memory and control is transferred to one of the
> +components (zipl stage3). Stage3 does some fixups and then transfers
> +control to some program residing in guest memory, which is normally
> +the OS kernel. The secure image has another component prepended
> +(stage3a) that uses the new diag308 subcodes 8 and 10 to trigger the
> +transition into secure mode.
> +
> +Booting from the image supplied on the QEMU command line requires that
> +the file passed via -kernel has the same memory layout as would result
> +from the disk boot. This memory layout includes the encrypted
> +components (kernel, initrd, cmdline), the stage3a loader and
> +metadata. In case this boot method is used, the command line
> +options -initrd and -cmdline are ineffective. The preparation of a PVM
> +image is done via the `genprotimg` tool from the s390-tools package.
> diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
> index 4c8b7cdd66154d26..8d97158dc804af1c 100644
> --- a/docs/system/target-s390x.rst
> +++ b/docs/system/target-s390x.rst
> @@ -24,3 +24,8 @@ or vfio-ap is also available.
>  .. toctree::
>     s390x/vfio-ap
>  
> +Architectural features
> +~~~~~~~~
> +
> +.. toctree::
> +   s390x/protvirt
>
Janosch Frank March 19, 2020, 9:04 a.m. UTC | #3
On 3/18/20 3:53 PM, Cornelia Huck wrote:
> On Wed, 18 Mar 2020 10:30:46 -0400
> Janosch Frank <frankja@linux.ibm.com> wrote:
> 
>> Let's add some documentation for the Protected VM functionality.
>>
>> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
>> Acked-by: David Hildenbrand <david@redhat.com>
>> Reviewed-by: Claudio Imbrenda <imbrenda@linux.ibm.com>
>> ---
>>  docs/system/s390x/protvirt.rst | 59 ++++++++++++++++++++++++++++++++++
>>  docs/system/target-s390x.rst   |  5 +++
>>  2 files changed, 64 insertions(+)
>>  create mode 100644 docs/system/s390x/protvirt.rst
> 
> (...)
> 
>> +Booting from the image supplied on the QEMU command line requires that
>> +the file passed via -kernel has the same memory layout as would result
>> +from the disk boot. This memory layout includes the encrypted
>> +components (kernel, initrd, cmdline), the stage3a loader and
>> +metadata. In case this boot method is used, the command line
>> +options -initrd and -cmdline are ineffective. The preparation of a PVM
>> +image is done via the `genprotimg` tool from the s390-tools package.
> 
> I still think 'package' is not a good name (yes, I realize that
> s390-tools' README uses that term as well :) I'd prefer 'collection' or
> something like that, so it doesn't get confused with distro packages,
> which may use a different name. But no strong opinion.

collection it is

> 
>> diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
>> index 4c8b7cdd66154d26..8d97158dc804af1c 100644
>> --- a/docs/system/target-s390x.rst
>> +++ b/docs/system/target-s390x.rst
>> @@ -24,3 +24,8 @@ or vfio-ap is also available.
>>  .. toctree::
>>     s390x/vfio-ap
>>  
>> +Architectural features
>> +~~~~~~~~
> 
> Architecture features
> =====================
> 
> ?

Ack

> 
>> +
>> +.. toctree::
>> +   s390x/protvirt
> 
> Otherwise, looks good to me.
> 
>
Cornelia Huck March 19, 2020, 9:59 a.m. UTC | #4
On Thu, 19 Mar 2020 10:04:38 +0100
Janosch Frank <frankja@linux.ibm.com> wrote:

> On 3/18/20 3:53 PM, Cornelia Huck wrote:
> > On Wed, 18 Mar 2020 10:30:46 -0400
> > Janosch Frank <frankja@linux.ibm.com> wrote:
> >   
> >> Let's add some documentation for the Protected VM functionality.
> >>
> >> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
> >> Acked-by: David Hildenbrand <david@redhat.com>
> >> Reviewed-by: Claudio Imbrenda <imbrenda@linux.ibm.com>
> >> ---
> >>  docs/system/s390x/protvirt.rst | 59 ++++++++++++++++++++++++++++++++++
> >>  docs/system/target-s390x.rst   |  5 +++
> >>  2 files changed, 64 insertions(+)
> >>  create mode 100644 docs/system/s390x/protvirt.rst  
> > 
> > (...)
> >   
> >> +Booting from the image supplied on the QEMU command line requires that
> >> +the file passed via -kernel has the same memory layout as would result
> >> +from the disk boot. This memory layout includes the encrypted
> >> +components (kernel, initrd, cmdline), the stage3a loader and
> >> +metadata. In case this boot method is used, the command line
> >> +options -initrd and -cmdline are ineffective. The preparation of a PVM
> >> +image is done via the `genprotimg` tool from the s390-tools package.  
> > 
> > I still think 'package' is not a good name (yes, I realize that
> > s390-tools' README uses that term as well :) I'd prefer 'collection' or
> > something like that, so it doesn't get confused with distro packages,
> > which may use a different name. But no strong opinion.  
> 
> collection it is
> 
> >   
> >> diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
> >> index 4c8b7cdd66154d26..8d97158dc804af1c 100644
> >> --- a/docs/system/target-s390x.rst
> >> +++ b/docs/system/target-s390x.rst
> >> @@ -24,3 +24,8 @@ or vfio-ap is also available.
> >>  .. toctree::
> >>     s390x/vfio-ap
> >>  
> >> +Architectural features
> >> +~~~~~~~~  
> > 
> > Architecture features
> > =====================
> > 
> > ?  
> 
> Ack
> 
> >   
> >> +
> >> +.. toctree::
> >> +   s390x/protvirt  
> > 
> > Otherwise, looks good to me.
> > 
> >   
> 
> 

With those changes,
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
diff mbox series

Patch

diff --git a/docs/system/s390x/protvirt.rst b/docs/system/s390x/protvirt.rst
new file mode 100644
index 0000000000000000..71172511632f7bcb
--- /dev/null
+++ b/docs/system/s390x/protvirt.rst
@@ -0,0 +1,59 @@ 
+Protected Virtualization on s390x
+=================================
+
+The memory and most of the registers of Protected Virtual Machines
+(PVMs) are encrypted or inaccessible to the hypervisor, effectively
+prohibiting VM introspection when the VM is running. At rest, PVMs are
+encrypted and can only be decrypted by the firmware, represented by an
+entity called Ultravisor, of specific IBM Z machines.
+
+
+Prerequisites
+-------------
+
+To run PVMs, a machine with the Protected Virtualization feature, as
+indicated by the Ultravisor Call facility (stfle bit 158), is
+required. The Ultravisor needs to be initialized at boot by setting
+`prot_virt=1` on the host's kernel command line.
+
+Running PVMs requires using the KVM hypervisor.
+
+If those requirements are met, the capability `KVM_CAP_S390_PROTECTED`
+will indicate that KVM can support PVMs on that LPAR.
+
+
+QEMU Settings
+-------------
+
+To indicate to the VM that it can transition into protected mode, the
+`Unpack facility` (stfle bit 161 represented by the feature
+`unpack`/`S390_FEAT_UNPACK`) needs to be part of the cpu model of
+the VM.
+
+All I/O devices need to use the IOMMU.
+Passthrough (vfio) devices are currently not supported.
+
+Host huge page backings are not supported. However guests can use huge
+pages as indicated by its facilities.
+
+
+Boot Process
+------------
+
+A secure guest image can either be loaded from disk or supplied on the
+QEMU command line. Booting from disk is done by the unmodified
+s390-ccw BIOS. I.e., the bootmap is interpreted, multiple components
+are read into memory and control is transferred to one of the
+components (zipl stage3). Stage3 does some fixups and then transfers
+control to some program residing in guest memory, which is normally
+the OS kernel. The secure image has another component prepended
+(stage3a) that uses the new diag308 subcodes 8 and 10 to trigger the
+transition into secure mode.
+
+Booting from the image supplied on the QEMU command line requires that
+the file passed via -kernel has the same memory layout as would result
+from the disk boot. This memory layout includes the encrypted
+components (kernel, initrd, cmdline), the stage3a loader and
+metadata. In case this boot method is used, the command line
+options -initrd and -cmdline are ineffective. The preparation of a PVM
+image is done via the `genprotimg` tool from the s390-tools package.
diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
index 4c8b7cdd66154d26..8d97158dc804af1c 100644
--- a/docs/system/target-s390x.rst
+++ b/docs/system/target-s390x.rst
@@ -24,3 +24,8 @@  or vfio-ap is also available.
 .. toctree::
    s390x/vfio-ap
 
+Architectural features
+~~~~~~~~
+
+.. toctree::
+   s390x/protvirt