docs/specs/ppc-spapr-uv-hcalls.rst

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