On PPC64 systems supporting Protected Execution Facility (PEF), system
memory can be placed in a secured region where only an "ultravisor"
running in firmware can provide to access it. pseries guests on such
systems can communicate with the ultravisor (via ultracalls) to switch to a
secure VM mode (SVM) where the guest's memory is relocated to this secured
region, making its memory inaccessible to normal processes/guests running on
the host.

The various ultracalls/hypercalls relating to SVM mode are currently
only documented internally, but are planned for direct inclusion into the
public OpenPOWER version of the PAPR specification (LoPAPR/LoPAR). An internal
ACR has been filed to reserve a hypercall number range specific to this
use-case to avoid any future conflicts with the internally-maintained PAPR
specification. This document summarizes some of these details as they relate
to QEMU.

== hypercalls needed by the ultravisor ==

Switching to SVM mode involves a number of hcalls issued by the ultravisor
to the hypervisor to orchestrate the movement of guest memory to secure
memory and various other aspects SVM mode. Numbers are assigned for these
hcalls within the reserved range 0xEF00-0xEF80. The below documents the
hcalls relevant to QEMU.

- H_TPM_COMM (0xef10)

  For TPM_COMM_OP_EXECUTE operation:
    Send a request to a TPM and receive a response, opening a new TPM session
    if one has not already been opened.

  For TPM_COMM_OP_CLOSE_SESSION operation:
    Close the existing TPM session, if any.

  Arguments:

    r3 : H_TPM_COMM (0xef10)
    r4 : TPM operation, one of:
         TPM_COMM_OP_EXECUTE (0x1)
         TPM_COMM_OP_CLOSE_SESSION (0x2)
    r5 : in_buffer, guest physical address of buffer containing the request
         - Caller may use the same address for both request and response
    r6 : in_size, size of the in buffer
         - Must be less than or equal to 4KB
    r7 : out_buffer, guest physical address of buffer to store the response
         - Caller may use the same address for both request and response
    r8 : out_size, size of the out buffer
         - Must be at least 4KB, as this is the maximum request/response size
           supported by most TPM implementations, including the TPM Resource
           Manager in the linux kernel.

  Return values:

    r3 : H_Success    request processed successfully
         H_PARAMETER  invalid TPM operation
         H_P2         in_buffer is invalid
         H_P3         in_size is invalid
         H_P4         out_buffer is invalid
         H_P5         out_size is invalid
         H_RESOURCE   problem communicating with TPM
         H_FUNCTION   TPM access is not currently allowed/configured
    r4 : For TPM_COMM_OP_EXECUTE, the size of the response will be stored here
         upon success.

  Use-case/notes:

    SVM filesystems are encrypted using a symmetric key. This key is then
    wrapped/encrypted using the public key of a trusted system which has the
    private key stored in the system's TPM. An Ultravisor will use this
    hcall to unwrap/unseal the symmetric key using the system's TPM device
    or a TPM Resource Manager associated with the device.

    The Ultravisor sets up a separate session key with the TPM in advance
    during host system boot. All sensitive in and out values will be
    encrypted using the session key. Though the hypervisor will see the 'in'
    and 'out' buffers in raw form, any sensitive contents will generally be
    encrypted using this session key.