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