1*dedc5d79SLeonardo Garcia=================================== 2*dedc5d79SLeonardo GarciaHypervisor calls and the Ultravisor 3*dedc5d79SLeonardo Garcia=================================== 4*dedc5d79SLeonardo Garcia 5*dedc5d79SLeonardo GarciaOn PPC64 systems supporting Protected Execution Facility (PEF), system memory 6*dedc5d79SLeonardo Garciacan be placed in a secured region where only an ultravisor running in firmware 7*dedc5d79SLeonardo Garciacan provide access to. pSeries guests on such systems can communicate with 8*dedc5d79SLeonardo Garciathe ultravisor (via ultracalls) to switch to a secure virtual machine (SVM) mode 9*dedc5d79SLeonardo Garciawhere the guest's memory is relocated to this secured region, making its memory 10*dedc5d79SLeonardo Garciainaccessible to normal processes/guests running on the host. 11*dedc5d79SLeonardo Garcia 12*dedc5d79SLeonardo GarciaThe various ultracalls/hypercalls relating to SVM mode are currently only 13*dedc5d79SLeonardo Garciadocumented internally, but are planned for direct inclusion into the Linux on 14*dedc5d79SLeonardo GarciaPower Architecture Reference document ([LoPAR]_). An internal ACR has been filed 15*dedc5d79SLeonardo Garciato reserve a hypercall number range specific to this use case to avoid any 16*dedc5d79SLeonardo Garciafuture conflicts with the IBM internally maintained Power Architecture Platform 17*dedc5d79SLeonardo GarciaReference (PAPR+) documentation specification. This document summarizes some of 18*dedc5d79SLeonardo Garciathese details as they relate to QEMU. 19*dedc5d79SLeonardo Garcia 20*dedc5d79SLeonardo GarciaHypercalls needed by the ultravisor 21*dedc5d79SLeonardo Garcia=================================== 22*dedc5d79SLeonardo Garcia 23*dedc5d79SLeonardo GarciaSwitching to SVM mode involves a number of hcalls issued by the ultravisor to 24*dedc5d79SLeonardo Garciathe hypervisor to orchestrate the movement of guest memory to secure memory and 25*dedc5d79SLeonardo Garciavarious other aspects of the SVM mode. Numbers are assigned for these hcalls 26*dedc5d79SLeonardo Garciawithin the reserved range ``0xEF00-0xEF80``. The below documents the hcalls 27*dedc5d79SLeonardo Garciarelevant to QEMU. 28*dedc5d79SLeonardo Garcia 29*dedc5d79SLeonardo Garcia``H_TPM_COMM`` (``0xef10``) 30*dedc5d79SLeonardo Garcia--------------------------- 31*dedc5d79SLeonardo Garcia 32*dedc5d79SLeonardo GarciaSVM file systems are encrypted using a symmetric key. This key is then 33*dedc5d79SLeonardo Garciawrapped/encrypted using the public key of a trusted system which has the private 34*dedc5d79SLeonardo Garciakey stored in the system's TPM. An Ultravisor will use this hcall to 35*dedc5d79SLeonardo Garciaunwrap/unseal the symmetric key using the system's TPM device or a TPM Resource 36*dedc5d79SLeonardo GarciaManager associated with the device. 37*dedc5d79SLeonardo Garcia 38*dedc5d79SLeonardo GarciaThe Ultravisor sets up a separate session key with the TPM in advance during 39*dedc5d79SLeonardo Garciahost system boot. All sensitive in and out values will be encrypted using the 40*dedc5d79SLeonardo Garciasession key. Though the hypervisor will see the in and out buffers in raw form, 41*dedc5d79SLeonardo Garciaany sensitive contents will generally be encrypted using this session key. 42*dedc5d79SLeonardo Garcia 43*dedc5d79SLeonardo GarciaArguments: 44*dedc5d79SLeonardo Garcia 45*dedc5d79SLeonardo Garcia ``r3``: ``H_TPM_COMM`` (``0xef10``) 46*dedc5d79SLeonardo Garcia 47*dedc5d79SLeonardo Garcia ``r4``: ``TPM`` operation, one of: 48*dedc5d79SLeonardo Garcia 49*dedc5d79SLeonardo Garcia ``TPM_COMM_OP_EXECUTE`` (``0x1``): send a request to a TPM and receive a 50*dedc5d79SLeonardo Garcia response, opening a new TPM session if one has not already been opened. 51*dedc5d79SLeonardo Garcia 52*dedc5d79SLeonardo Garcia ``TPM_COMM_OP_CLOSE_SESSION`` (``0x2``): close the existing TPM session, if 53*dedc5d79SLeonardo Garcia any. 54*dedc5d79SLeonardo Garcia 55*dedc5d79SLeonardo Garcia ``r5``: ``in_buffer``, guest physical address of buffer containing the 56*dedc5d79SLeonardo Garcia request. Caller may use the same address for both request and response. 57*dedc5d79SLeonardo Garcia 58*dedc5d79SLeonardo Garcia ``r6``: ``in_size``, size of the in buffer. Must be less than or equal to 59*dedc5d79SLeonardo Garcia 4 KB. 60*dedc5d79SLeonardo Garcia 61*dedc5d79SLeonardo Garcia ``r7``: ``out_buffer``, guest physical address of buffer to store the 62*dedc5d79SLeonardo Garcia response. Caller may use the same address for both request and response. 63*dedc5d79SLeonardo Garcia 64*dedc5d79SLeonardo Garcia ``r8``: ``out_size``, size of the out buffer. Must be at least 4 KB, as this 65*dedc5d79SLeonardo Garcia is the maximum request/response size supported by most TPM implementations, 66*dedc5d79SLeonardo Garcia including the TPM Resource Manager in the linux kernel. 67*dedc5d79SLeonardo Garcia 68*dedc5d79SLeonardo GarciaReturn values: 69*dedc5d79SLeonardo Garcia 70*dedc5d79SLeonardo Garcia ``r3``: one of the following values: 71*dedc5d79SLeonardo Garcia 72*dedc5d79SLeonardo Garcia ``H_Success``: request processed successfully. 73*dedc5d79SLeonardo Garcia 74*dedc5d79SLeonardo Garcia ``H_PARAMETER``: invalid TPM operation. 75*dedc5d79SLeonardo Garcia 76*dedc5d79SLeonardo Garcia ``H_P2``: ``in_buffer`` is invalid. 77*dedc5d79SLeonardo Garcia 78*dedc5d79SLeonardo Garcia ``H_P3``: ``in_size`` is invalid. 79*dedc5d79SLeonardo Garcia 80*dedc5d79SLeonardo Garcia ``H_P4``: ``out_buffer`` is invalid. 81*dedc5d79SLeonardo Garcia 82*dedc5d79SLeonardo Garcia ``H_P5``: ``out_size`` is invalid. 83*dedc5d79SLeonardo Garcia 84*dedc5d79SLeonardo Garcia ``H_RESOURCE``: problem communicating with TPM. 85*dedc5d79SLeonardo Garcia 86*dedc5d79SLeonardo Garcia ``H_FUNCTION``: TPM access is not currently allowed/configured. 87*dedc5d79SLeonardo Garcia 88*dedc5d79SLeonardo Garcia ``r4``: For ``TPM_COMM_OP_EXECUTE``, the size of the response will be stored 89*dedc5d79SLeonardo Garcia here upon success. 90