docs/system/s390x/protvirt.rst

   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.