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

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