MAINTAINERS: Make section QOM cover hw/core/*bus.c as well
[qemu/armbru.git] / docs / specs / ppc-spapr-uv-hcalls.txt
blob389c2740d764175ab0c50749c9ae1f198f61e328
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.
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.
17 == hypercalls needed by the ultravisor ==
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.
25 - H_TPM_COMM (0xef10)
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.
31   For TPM_COMM_OP_CLOSE_SESSION operation:
32     Close the existing TPM session, if any.
34   Arguments:
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.
51   Return values:
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.
64   Use-case/notes:
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.
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.