rSTify ppc-spapr-uv-hcalls.txt.
cover rSTify ppc-spapr-uv-hcalls.txt.
From: Leonardo Garcia <[email protected]>
Leonardo Garcia (3):
rSTify ppc-spapr-uv-hcalls.txt.
Rename ppc-spapr-uv-hcalls.txt to ppc-spapr-uv-hcalls.rst. Link new ppc-spapr-uv-hcalls.rst to pseries.rst.
docs/specs/ppc-spapr-uv-hcalls.rst | 89 ++++++++++++++++++++++++++++++ docs/specs/ppc-spapr-uv-hcalls.txt | 76 ------------------------- docs/system/ppc/pseries.rst | 6 +- 3 files changed, 90 insertions(+), 81 deletions(-) create mode 100644 docs/specs/ppc-spapr-uv-hcalls.rst delete mode 100644 docs/specs/ppc-spapr-uv-hcalls.txt
Signature · 1 line
2.34.1
PATCH 1/3 rSTify ppc-spapr-uv-hcalls.txt.
From: Leonardo Garcia <[email protected]>
--- docs/specs/ppc-spapr-uv-hcalls.txt | 165 ++++++++++++++++------------- 1 file changed, 89 insertions(+), 76 deletions(-)
docs/specs/ppc-spapr-uv-hcalls.txt +89 -76
@@ -1,76 +1,89 @@ -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. +=================================== +Hypervisor calls and the Ultravisor +=================================== + +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 access to. pSeries guests on such systems can communicate with +the ultravisor (via ultracalls) to switch to a secure virtual machine (SVM) mode +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 Linux on +Power Architecture Reference document ([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 IBM internally maintained Power Architecture Platform +Reference (PAPR+) documentation 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 of the 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``) +--------------------------- + +SVM file systems 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. + +Arguments: + + ``r3``: ``H_TPM_COMM`` (``0xef10``) + + ``r4``: ``TPM`` operation, one of: + + ``TPM_COMM_OP_EXECUTE`` (``0x1``): send a request to a TPM and receive a + response, opening a new TPM session if one has not already been opened. + + ``TPM_COMM_OP_CLOSE_SESSION`` (``0x2``): close the existing TPM session, if + any. + + ``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 + 4 KB. + + ``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 4 KB, 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``: one of the following values: + + ``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.
Signature · 1 line
2.34.1
PATCH 2/3 Rename ppc-spapr-uv-hcalls.txt to ppc-spapr-uv-hcalls.rst.
In reply to [email protected]From: Leonardo Garcia <[email protected]>
---
docs/specs/{ppc-spapr-uv-hcalls.txt => ppc-spapr-uv-hcalls.rst} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename docs/specs/{ppc-spapr-uv-hcalls.txt => ppc-spapr-uv-hcalls.rst} (100%)docs/specs/ppc-spapr-uv-hcalls.rst renamed from docs/specs/ppc-spapr-uv-hcalls.txt +0 -0
Signature · 1 line
2.34.1
PATCH 3/3 Link new ppc-spapr-uv-hcalls.rst to pseries.rst.
In reply to [email protected]From: Leonardo Garcia <[email protected]>
--- docs/system/ppc/pseries.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-)
docs/system/ppc/pseries.rst +1 -5
@@ -113,13 +113,9 @@ can also be found in QEMU documentation: ../../specs/ppc-spapr-hotplug.rst ../../specs/ppc-spapr-hcalls.rst ../../specs/ppc-spapr-numa.rst + ../../specs/ppc-spapr-uv-hcalls.rst ../../specs/ppc-spapr-xive.rst -Other documentation available in QEMU docs directory: - -* Hypervisor calls needed by the Ultravisor - (``/docs/specs/ppc-spapr-uv-hcalls.txt``). - Switching between the KVM-PR and KVM-HV kernel module =====================================================
Signature · 1 line
2.34.1
Quoted 4 lines · On 1/17/22 16:19, [email protected] wrote:
From: Leonardo Garcia <[email protected]>
Signed-off-by Leonardo Garcia <[email protected]>---
Quoted 173 lines
docs/specs/ppc-spapr-uv-hcalls.txt | 165 ++++++++++++++++------------- 1 file changed, 89 insertions(+), 76 deletions(-)docs/specs/ppc-spapr-uv-hcalls.txt +89
-76@@ -1,76 +1,89 @@ -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. +=================================== +Hypervisor calls and the Ultravisor +=================================== + +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 access to. pSeries guests on such systems can communicate with +the ultravisor (via ultracalls) to switch to a secure virtual machine (SVM) mode +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 Linux on +Power Architecture Reference document ([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 IBM internally maintained Power Architecture Platform +Reference (PAPR+) documentation 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 of the 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``) +--------------------------- + +SVM file systems 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. + +Arguments: + + ``r3``: ``H_TPM_COMM`` (``0xef10``) + + ``r4``: ``TPM`` operation, one of: + + ``TPM_COMM_OP_EXECUTE`` (``0x1``): send a request to a TPM and receive a + response, opening a new TPM session if one has not already been opened. + + ``TPM_COMM_OP_CLOSE_SESSION`` (``0x2``): close the existing TPM session, if + any. + + ``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 + 4 KB. + + ``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 4 KB, 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``: one of the following values: + + ``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.
Re: [PATCH 2/3] Rename ppc-spapr-uv-hcalls.txt to ppc-spapr-uv-hcalls.rst.
In reply to [email protected]Quoted 4 lines · On 1/17/22 16:19, [email protected] wrote:
From: Leonardo Garcia <[email protected]>
Signed-off-by Leonardo Garcia <[email protected]>---
Quoted 8 lines
docs/specs/{ppc-spapr-uv-hcalls.txt => ppc-spapr-uv-hcalls.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-)rename
docs/specs/{ppc-spapr-uv-hcalls.txt=>ppc-spapr-uv-hcalls.rst} (100%)docs/specs/ppc-spapr-uv-hcalls.rst renamed from docs/specs/ppc-spapr-uv-hcalls.txt +0
-0
Re: [PATCH 3/3] Link new ppc-spapr-uv-hcalls.rst to pseries.rst.
In reply to [email protected]Quoted 4 lines · On 1/17/22 16:19, [email protected] wrote:
From: Leonardo Garcia <[email protected]>
Signed-off-by Leonardo Garcia <[email protected]>---
It is worth noticing that this patch applies cleanly only if the
"[PATCH 0/3] rSTify ppc-spapr-hotplug.txt" [1]
series is applied first. The reason is that docs/system/ppc/pseries.rst being changed here already has the ppc-spapr-hotplug.rst link.
[1] https://lists.gnu.org/archive/html/qemu-devel/2022-01/msg02701.html
Quoted 22 lines
docs/system/ppc/pseries.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-)docs/system/ppc/pseries.rst +1
-5@@ -113,13 +113,9 @@ can also be found in QEMU documentation: ../../specs/ppc-spapr-hotplug.rst ../../specs/ppc-spapr-hcalls.rst ../../specs/ppc-spapr-numa.rst + ../../specs/ppc-spapr-uv-hcalls.rst ../../specs/ppc-spapr-xive.rst -Other documentation available in QEMU docs directory: - -* Hypervisor calls needed by the Ultravisor - (``/docs/specs/ppc-spapr-uv-hcalls.txt``). - Switching between the KVM-PR and KVM-HV kernel module =====================================================
Re: [PATCH 3/3] Link new ppc-spapr-uv-hcalls.rst to pseries.rst.
Quoted 8 lines · Daniel Henrique Barboza
Quoted 4 lines · On 1/17/22 16:19, [email protected] wrote:
From: Leonardo Garcia <[email protected]>
Signed-off-by Leonardo Garcia <[email protected]>---
Quoted 6 lines
It is worth noticing that this patch applies cleanly only if the
"[PATCH 0/3] rSTify ppc-spapr-hotplug.txt" [1]
series is applied first. The reason is that
docs/system/ppc/pseries.rstbeing changed here already has theppc-spapr-hotplug.rstlink.
yes. That's fine. I have queued the first series already.
Thanks,
C.
Cédric Le Goater
AppliedQuoted 7 lines · On 1/17/22 20:19, [email protected] wrote:
From: Leonardo Garcia <[email protected]>
Leonardo Garcia (3):
rSTify ppc-spapr-uv-hcalls.txt.
Rename ppc-spapr-uv-hcalls.txt toppc-spapr-uv-hcalls.rst. Link newppc-spapr-uv-hcalls.rsttopseries.rst.
Quoted 7 lines
docs/specs/ppc-spapr-uv-hcalls.rst | 89 ++++++++++++++++++++++++++++++ docs/specs/ppc-spapr-uv-hcalls.txt | 76 ------------------------- docs/system/ppc/pseries.rst | 6 +- 3 files changed, 90 insertions(+), 81 deletions(-)create mode 100644
docs/specs/ppc-spapr-uv-hcalls.rstdelete mode 100644docs/specs/ppc-spapr-uv-hcalls.txt
Applied to ppc-7.0
Thanks,
C.