diff options
| -rw-r--r-- | docs/system/s390x/protvirt.rst | 60 | ||||
| -rw-r--r-- | docs/system/target-s390x.rst | 5 |
2 files changed, 65 insertions, 0 deletions
diff --git a/docs/system/s390x/protvirt.rst b/docs/system/s390x/protvirt.rst new file mode 100644 index 0000000..712974a --- /dev/null +++ b/docs/system/s390x/protvirt.rst @@ -0,0 +1,60 @@ +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 +collection. diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst index 4c8b7cd..7d76ae9 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 |