On Wed, 11 Mar 2020 09:21:50 -0400 Janosch Frank <fran...@linux.ibm.com> wrote:
> Lets add some documentation for the Protected VM functionality. > > Signed-off-by: Janosch Frank <fran...@linux.ibm.com> > --- > docs/system/index.rst | 1 + > docs/system/protvirt.rst | 56 > ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 > insertions(+) create mode 100644 docs/system/protvirt.rst > > diff --git a/docs/system/index.rst b/docs/system/index.rst > index 6e5f20fa1333ce23..74afbd7cc3fc0296 100644 > --- a/docs/system/index.rst > +++ b/docs/system/index.rst > @@ -34,3 +34,4 @@ Contents: > deprecated > build-platforms > license > + protvirt > diff --git a/docs/system/protvirt.rst b/docs/system/protvirt.rst > new file mode 100644 > index 0000000000000000..6c8cf0f7910eae86 > --- /dev/null > +++ b/docs/system/protvirt.rst > @@ -0,0 +1,56 @@ > +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 > +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. I'd add "of the host" just to make it extra clear > + > +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 > +`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). Stag3 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 via 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 by genprotimg of the s390-tools package. Reviewed-by: Claudio Imbrenda <imbre...@linux.ibm.com>
