| Message ID | 20200304114231.23493-18-frankja@linux.ibm.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | s390x: Protected Virtualization support | expand |
On 04.03.20 12:42, Janosch Frank wrote: > Lets add some documentation for the Protected VM functionality. > > Signed-off-by: Janosch Frank <frankja@linux.ibm.com> > --- > docs/system/index.rst | 1 + > docs/system/protvirt.rst | 57 ++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 58 insertions(+) > create mode 100644 docs/system/protvirt.rst > > diff --git a/docs/system/index.rst b/docs/system/index.rst > index 1a4b2c82ac..d2dc63b973 100644 > --- a/docs/system/index.rst > +++ b/docs/system/index.rst > @@ -16,3 +16,4 @@ Contents: > > qemu-block-drivers > vfio-ap > + protvirt > diff --git a/docs/system/protvirt.rst b/docs/system/protvirt.rst > new file mode 100644 > index 0000000000..a1902cc47c > --- /dev/null > +++ b/docs/system/protvirt.rst > @@ -0,0 +1,57 @@ > +Protected Virtualization on s390x > +================================= > + > +The memory and most of the register contents of Protected Virtual s/register contents/registers/ > +Machines (PVMs) are inaccessible to the hypervisor, effectively s/inaccessible/encrypted or even inaccessible/ ? > +prohibiting VM introspection when the VM is running. At rest, PVMs are > +encrypted and can only be decrypted by the firmware of specific IBM Z > +machines. maybe "(a.k.a. the Ultravisor)" > + > + > +Prerequisites > +------------- > + > +To run PVMs, you need to have a machine with the Protected "a machine with the Protected Virtualization feature is required" > +Virtualization feature, which is indicated by the Ultravisor Call > +facility (stfle bit 158). This is a KVM only feature, therefore you ", therefore, " I don't understand the "KVM only" feature part. Just say that an updated KVM + right HW is required and how it is to be updated. > +need a KVM which is able to support PVMs and activate the Ultravisor "a KVM version" > +initialization by setting `prot_virt=1` on the kernel command line. > + > +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 move into protected mode, the s/move/transition/ ? > +`Unpack facility` (stfle bit 161) needs to be part of the cpu model of > +the VM. Maybe mention the CPU feature name here. > + > +All I/O devices need to use the IOMMU. > +Passthrough (vfio) devices are currently not supported. > + > +Host huge page backings are not supported. The guest however can use "However, the guest can ..." > +huge pages as indicated by its facilities. > + > + > +Boot Process > +------------ > + > +A secure guest image can be both booted from disk and using the QEMU "either be loaded from disk or supplied on the QEMU command line" ? > +command line. Booting from disk is done by the unmodified s390-ccw > +BIOS. I.e., the bootmap is interpreted and a number of components is "interpreted, multiple components are" > +read into memory and control is transferred to one of the components > +(zipl stage3), which does some fixups and then transfers control to > +some program residing in guest memory, which is normally the OS to many ", which". Better split that up for readability. > +kernel. The secure image has another component prepended (stage3a) > +which uses the new diag308 subcodes 8 and 10 to trigger the transition > +into secure mode. > + > +Booting from the command line requires that the file passed "from the image supplied on the QEMU command line" ? > +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 secure guest image is done by a s/of secure/of a PMV image/ > +program (name tbd) of the s390-tools package. > General: secure guest -> PMV
On 3/4/20 8:09 PM, David Hildenbrand wrote: > On 04.03.20 12:42, Janosch Frank wrote: >> Lets add some documentation for the Protected VM functionality. >> >> Signed-off-by: Janosch Frank <frankja@linux.ibm.com> >> --- >> docs/system/index.rst | 1 + >> docs/system/protvirt.rst | 57 ++++++++++++++++++++++++++++++++++++++++ >> 2 files changed, 58 insertions(+) >> create mode 100644 docs/system/protvirt.rst >> >> diff --git a/docs/system/index.rst b/docs/system/index.rst >> index 1a4b2c82ac..d2dc63b973 100644 >> --- a/docs/system/index.rst >> +++ b/docs/system/index.rst >> @@ -16,3 +16,4 @@ Contents: >> >> qemu-block-drivers >> vfio-ap >> + protvirt >> diff --git a/docs/system/protvirt.rst b/docs/system/protvirt.rst >> new file mode 100644 >> index 0000000000..a1902cc47c >> --- /dev/null >> +++ b/docs/system/protvirt.rst >> @@ -0,0 +1,57 @@ >> +Protected Virtualization on s390x >> +================================= >> + >> +The memory and most of the register contents of Protected Virtual > > s/register contents/registers/ Ack > >> +Machines (PVMs) are inaccessible to the hypervisor, effectively > > s/inaccessible/encrypted or even inaccessible/ ? > >> +prohibiting VM introspection when the VM is running. At rest, PVMs are >> +encrypted and can only be decrypted by the firmware of specific IBM Z >> +machines. > > maybe "(a.k.a. the Ultravisor)" 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, you need to have a machine with the Protected > > "a machine with the Protected Virtualization feature is required" Ack > >> +Virtualization feature, which is indicated by the Ultravisor Call >> +facility (stfle bit 158). This is a KVM only feature, therefore you > > ", therefore, " > > I don't understand the "KVM only" feature part. Just say that an updated > KVM + right HW is required and how it is to be updated. The KVM only part is mostly messaging that this can't be run under TCG > >> +need a KVM which is able to support PVMs and activate the Ultravisor > > "a KVM version" > >> +initialization by setting `prot_virt=1` on the kernel command line. To run PVMs a machine with the Protected Virtualization feature which is 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 kernel command line. >> + >> +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 move into protected mode, the > > s/move/transition/ ? Ack I also took most of the suggestions below with some forms of modification. > >> +`Unpack facility` (stfle bit 161) needs to be part of the cpu model of >> +the VM. > > Maybe mention the CPU feature name here. > >> + >> +All I/O devices need to use the IOMMU. >> +Passthrough (vfio) devices are currently not supported. >> + >> +Host huge page backings are not supported. The guest however can use > > "However, the guest can ..." > >> +huge pages as indicated by its facilities. >> + >> + >> +Boot Process >> +------------ >> + >> +A secure guest image can be both booted from disk and using the QEMU > > "either be loaded from disk or supplied on the QEMU command line" ? > >> +command line. Booting from disk is done by the unmodified s390-ccw >> +BIOS. I.e., the bootmap is interpreted and a number of components is > > "interpreted, multiple components are" > >> +read into memory and control is transferred to one of the components >> +(zipl stage3), which does some fixups and then transfers control to >> +some program residing in guest memory, which is normally the OS > > to many ", which". Better split that up for readability. > >> +kernel. The secure image has another component prepended (stage3a) >> +which uses the new diag308 subcodes 8 and 10 to trigger the transition >> +into secure mode. >> + >> +Booting from the command line requires that the file passed > > "from the image supplied on the QEMU command line" ? > >> +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 secure guest image is done by a > > s/of secure/of a PMV image/ > >> +program (name tbd) of the s390-tools package. >> > > > General: secure guest -> PMV >
diff --git a/docs/system/index.rst b/docs/system/index.rst index 1a4b2c82ac..d2dc63b973 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -16,3 +16,4 @@ Contents: qemu-block-drivers vfio-ap + protvirt diff --git a/docs/system/protvirt.rst b/docs/system/protvirt.rst new file mode 100644 index 0000000000..a1902cc47c --- /dev/null +++ b/docs/system/protvirt.rst @@ -0,0 +1,57 @@ +Protected Virtualization on s390x +================================= + +The memory and most of the register contents of Protected Virtual +Machines (PVMs) are 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 of specific IBM Z +machines. + + +Prerequisites +------------- + +To run PVMs, you need to have a machine with the Protected +Virtualization feature, which is indicated by the Ultravisor Call +facility (stfle bit 158). This is a KVM only feature, therefore you +need a KVM which is able to support PVMs and activate the Ultravisor +initialization by setting `prot_virt=1` on the kernel command line. + +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 move into protected mode, the +`Unpack facility` (stfle bit 161) 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. The guest however can use +huge pages as indicated by its facilities. + + +Boot Process +------------ + +A secure guest image can be both booted from disk and using the QEMU +command line. Booting from disk is done by the unmodified s390-ccw +BIOS. I.e., the bootmap is interpreted and a number of components is +read into memory and control is transferred to one of the components +(zipl stage3), which 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) +which uses the new diag308 subcodes 8 and 10 to trigger the transition +into secure mode. + +Booting from the 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 secure guest image is done by a +program (name tbd) of the s390-tools package.
Lets add some documentation for the Protected VM functionality. Signed-off-by: Janosch Frank <frankja@linux.ibm.com> --- docs/system/index.rst | 1 + docs/system/protvirt.rst | 57 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 docs/system/protvirt.rst