[PATCH 0/3] rSTify ppc-spapr-uv-hcalls.txt.

[PATCH 0/3] rSTify ppc-spapr-uv-hcalls.txt.

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

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

-- 
2.34.1

[PATCH 1/3] rSTify ppc-spapr-uv-hcalls.txt.

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
---
 docs/specs/ppc-spapr-uv-hcalls.txt | 165 ++++++++++++++++-------------
 1 file changed, 89 insertions(+), 76 deletions(-)

diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.txt
index 389c2740d7..a00288deb3 100644
--- a/docs/specs/ppc-spapr-uv-hcalls.txt
+++ b/docs/specs/ppc-spapr-uv-hcalls.txt
@@ -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.
-- 
2.34.1

[PATCH 2/3] Rename ppc-spapr-uv-hcalls.txt to ppc-spapr-uv-hcalls.rst.

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
---
 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%)

diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.rst
similarity index 100%
rename from docs/specs/ppc-spapr-uv-hcalls.txt
rename to docs/specs/ppc-spapr-uv-hcalls.rst
-- 
2.34.1

[PATCH 3/3] Link new ppc-spapr-uv-hcalls.rst to pseries.rst.

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
---
 docs/system/ppc/pseries.rst | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst
index d0aade3a31..569237dc0c 100644
--- a/docs/system/ppc/pseries.rst
+++ b/docs/system/ppc/pseries.rst
@@ -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
 =====================================================
 
-- 
2.34.1

Re: [PATCH 1/3] rSTify ppc-spapr-uv-hcalls.txt.

[Daniel Henrique Barboza]

On 1/17/22 16:19, lagarcia@linux.ibm.com wrote:
> From: Leonardo Garcia <lagarcia@br.ibm.com>
> 
> Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
> ---

Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>

>   docs/specs/ppc-spapr-uv-hcalls.txt | 165 ++++++++++++++++-------------
>   1 file changed, 89 insertions(+), 76 deletions(-)
> 
> diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.txt
> index 389c2740d7..a00288deb3 100644
> --- a/docs/specs/ppc-spapr-uv-hcalls.txt
> +++ b/docs/specs/ppc-spapr-uv-hcalls.txt
> @@ -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.

[Daniel Henrique Barboza]

On 1/17/22 16:19, lagarcia@linux.ibm.com wrote:
> From: Leonardo Garcia <lagarcia@br.ibm.com>
> 
> Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
> ---

Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>

>   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%)
> 
> diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.rst
> similarity index 100%
> rename from docs/specs/ppc-spapr-uv-hcalls.txt
> rename to docs/specs/ppc-spapr-uv-hcalls.rst

Re: [PATCH 3/3] Link new ppc-spapr-uv-hcalls.rst to pseries.rst.

[Daniel Henrique Barboza]

On 1/17/22 16:19, lagarcia@linux.ibm.com wrote:
> From: Leonardo Garcia <lagarcia@br.ibm.com>
> 
> Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
> ---

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.


Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>



[1] https://lists.gnu.org/archive/html/qemu-devel/2022-01/msg02701.html

>   docs/system/ppc/pseries.rst | 6 +-----
>   1 file changed, 1 insertion(+), 5 deletions(-)
> 
> diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst
> index d0aade3a31..569237dc0c 100644
> --- a/docs/system/ppc/pseries.rst
> +++ b/docs/system/ppc/pseries.rst
> @@ -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.

[Cédric Le Goater]

On 1/17/22 21:53, Daniel Henrique Barboza wrote:
> 
> 
> On 1/17/22 16:19, lagarcia@linux.ibm.com wrote:
>> From: Leonardo Garcia <lagarcia@br.ibm.com>
>>
>> Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
>> ---
> 
> 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.

yes. That's fine. I have queued the first series already.

Thanks,

C.

Re: [PATCH 0/3] rSTify ppc-spapr-uv-hcalls.txt.

[Cédric Le Goater]

On 1/17/22 20:19, lagarcia@linux.ibm.com wrote:
> From: Leonardo Garcia <lagarcia@br.ibm.com>
> 
> 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
> 


Applied to ppc-7.0

Thanks,

C.