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
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
--
2.25.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.
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. > >
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>
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 >
© 2016 - 2025 Red Hat, Inc.