jcs.org / qemu
qemu with hax to log dma reads & writes jcs.org/2018/11/12/vfio
fork atom

docs: system: Add protvirt docs

Let's add some documentation for the Protected VM functionality.

Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
Reviewed-by: Claudio Imbrenda <imbrenda@linux.ibm.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Acked-by: David Hildenbrand <david@redhat.com>
Acked-by: Christian Borntraeger <borntraeger@de.ibm.com>
Message-Id: <20200319131921.2367-16-frankja@linux.ibm.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>

authored by

Janosch Frank and committed by
Cornelia Huck 42fc5eae f2a2d9a2

+65
+60
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 + QEMU Settings 26 + ------------- 27 + 28 + To indicate to the VM that it can transition into protected mode, the 29 + `Unpack facility` (stfle bit 161 represented by the feature 30 + `unpack`/`S390_FEAT_UNPACK`) needs to be part of the cpu model of 31 + the VM. 32 + 33 + All I/O devices need to use the IOMMU. 34 + Passthrough (vfio) devices are currently not supported. 35 + 36 + Host huge page backings are not supported. However guests can use huge 37 + pages as indicated by its facilities. 38 + 39 + 40 + Boot Process 41 + ------------ 42 + 43 + A secure guest image can either be loaded from disk or supplied on the 44 + QEMU command line. Booting from disk is done by the unmodified 45 + s390-ccw BIOS. I.e., the bootmap is interpreted, multiple components 46 + are read into memory and control is transferred to one of the 47 + components (zipl stage3). Stage3 does some fixups and then transfers 48 + control to some program residing in guest memory, which is normally 49 + the OS kernel. The secure image has another component prepended 50 + (stage3a) that uses the new diag308 subcodes 8 and 10 to trigger the 51 + transition into secure mode. 52 + 53 + Booting from the image supplied on the QEMU command line requires that 54 + the file passed via -kernel has the same memory layout as would result 55 + from the disk boot. This memory layout includes the encrypted 56 + components (kernel, initrd, cmdline), the stage3a loader and 57 + metadata. In case this boot method is used, the command line 58 + options -initrd and -cmdline are ineffective. The preparation of a PVM 59 + image is done via the `genprotimg` tool from the s390-tools 60 + collection.
+5
docs/system/target-s390x.rst
··· 24 24 .. toctree:: 25 25 s390x/vfio-ap 26 26 27 + Architectural features 28 + ====================== 29 + 30 + .. toctree:: 31 + s390x/protvirt