| 1 | Protected Virtualization on s390x |
| 2 | ================================= |
| 3 | |
| 4 | The memory and most of the registers of Protected Virtual Machines |
| 5 | (PVMs) are encrypted or inaccessible to the hypervisor, effectively |
| 6 | prohibiting VM introspection when the VM is running. At rest, PVMs are |
| 7 | encrypted and can only be decrypted by the firmware, represented by an |
| 8 | entity called Ultravisor, of specific IBM Z machines. |
| 9 | |
| 10 | |
| 11 | Prerequisites |
| 12 | ------------- |
| 13 | |
| 14 | To run PVMs, a machine with the Protected Virtualization feature, as |
| 15 | indicated by the Ultravisor Call facility (stfle bit 158), is |
| 16 | required. The Ultravisor needs to be initialized at boot by setting |
| 17 | ``prot_virt=1`` on the host's kernel command line. |
| 18 | |
| 19 | Running PVMs requires using the KVM hypervisor. |
| 20 | |
| 21 | If those requirements are met, the capability ``KVM_CAP_S390_PROTECTED`` |
| 22 | will indicate that KVM can support PVMs on that LPAR. |
| 23 | |
| 24 | |
| 25 | Running a Protected Virtual Machine |
| 26 | ----------------------------------- |
| 27 | |
| 28 | To run a PVM you will need to select a CPU model which includes the |
| 29 | ``Unpack facility`` (stfle bit 161 represented by the feature |
| 30 | ``unpack``/``S390_FEAT_UNPACK``), and add these options to the command line:: |
| 31 | |
| 32 | -object s390-pv-guest,id=pv0 \ |
| 33 | -machine confidential-guest-support=pv0 |
| 34 | |
| 35 | Adding these options will: |
| 36 | |
| 37 | * Ensure the ``unpack`` facility is available |
| 38 | * Enable the IOMMU by default for all I/O devices |
| 39 | * Initialize the PV mechanism |
| 40 | |
| 41 | Passthrough (vfio) devices are currently not supported. |
| 42 | |
| 43 | Host huge page backings are not supported. However guests can use huge |
| 44 | pages as indicated by its facilities. |
| 45 | |
| 46 | |
| 47 | Boot Process |
| 48 | ------------ |
| 49 | |
| 50 | A secure guest image can either be loaded from disk or supplied on the |
| 51 | QEMU command line. Booting from disk is done by the unmodified |
| 52 | s390-ccw BIOS. I.e., the bootmap is interpreted, multiple components |
| 53 | are read into memory and control is transferred to one of the |
| 54 | components (zipl stage3). Stage3 does some fixups and then transfers |
| 55 | control to some program residing in guest memory, which is normally |
| 56 | the OS kernel. The secure image has another component prepended |
| 57 | (stage3a) that uses the new diag308 subcodes 8 and 10 to trigger the |
| 58 | transition into secure mode. |
| 59 | |
| 60 | Booting from the image supplied on the QEMU command line requires that |
| 61 | the file passed via -kernel has the same memory layout as would result |
| 62 | from the disk boot. This memory layout includes the encrypted |
| 63 | components (kernel, initrd, cmdline), the stage3a loader and |
| 64 | metadata. In case this boot method is used, the command line |
| 65 | options -initrd and -cmdline are ineffective. The preparation of a PVM |
| 66 | image is done via the ``genprotimg`` tool from the s390-tools |
| 67 | collection. |