Add sp environment documentation
Explain differences between opteesp and sp environments, along
documenting the build process of sp deployments.
Signed-off-by: Imre Kis <imre.kis@arm.com>
Change-Id: I036c30e730c355c134d3167f44723cd3a400bf77
diff --git a/docs/deployments/secure-partitions.rst b/docs/deployments/secure-partitions.rst
index 338363c..7727de9 100644
--- a/docs/deployments/secure-partitions.rst
+++ b/docs/deployments/secure-partitions.rst
@@ -23,6 +23,7 @@
* - Supported Environments
- * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * *sp* (SPMC agnostic S-EL0 SP format)
* - External Dependencies
- * | TRNG (platform specific)
* | Secure storage SP
@@ -42,6 +43,7 @@
* - Supported Environments
- * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * *sp* (SPMC agnostic S-EL0 SP format)
* - External Dependencies
- * | TPM Event Log (via SP boot parameter)
* | Crypto SP
@@ -62,6 +64,7 @@
* - Supported Environments
- * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * *sp* (SPMC agnostic S-EL0 SP format)
* - External Dependencies
- * Depends on configured storage backend
@@ -88,6 +91,7 @@
* - Supported Environments
- * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * *sp* (SPMC agnostic S-EL0 SP format)
* - External Dependencies
- * SE communication peripheral (platform specific)
@@ -104,6 +108,7 @@
* - Supported Environments
- * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * *sp* (SPMC agnostic S-EL0 SP format)
* - External Dependencies
- * | Secure storage service instance (e.g. hosted by protected-storage SP)
* | Crypto service instance (e.g. hosted crypto SP)
@@ -123,11 +128,12 @@
* - Supported Environments
- * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * *sp* (SPMC agnostic S-EL0 SP format)
* - External Dependencies
- * Any hardware accessed by test cases (platform specific)
--------------
-*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2022-2023, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/project-structure.rst b/docs/developer/project-structure.rst
index 3f0e717..0e34989 100644
--- a/docs/developer/project-structure.rst
+++ b/docs/developer/project-structure.rst
@@ -40,6 +40,7 @@
deployments
|-- protected-storage/opteesp
|-- crypto/opteesp
+ |-- crypto/sp
|-- ts-demo/arm-linux
|-- component-test/linux-pc
|-- libts/linux-pc
@@ -61,6 +62,9 @@
|-- common.cmake <-- Common cmake file
|-- service_init.c <-- Common initialization code
|-- opteesp
+ | |-- CMakeLists.txt <-- Includes ../common.cmake to inherit common definitions
+ | |-- opteesp_service_init.c
+ |-- sp
|-- CMakeLists.txt <-- Includes ../common.cmake to inherit common definitions
|-- opteesp_service_init.c
@@ -72,6 +76,7 @@
particular environment live under a sub-directory whose name describes the environment. For example:
- *opteesp* An S-EL0 secure partition hosted by OP-TEE
+ - *sp* SPMC agnostic S-EL0 secure partition
- *arm-linux* Linux user-space, cross compiled for Arm.
- *linux-pc* Native PC POSIX environment
@@ -87,6 +92,26 @@
A deployment will include an environment specific build file (see above) that defines the list of environment
specific components used for a deployment into a particular environment.
+opteesp
+"""""""
+
+The opteesp environment uses a very similar SP format to the OP-TEE Trusted Applications. It is an ELF file with an OP-TEE
+specific header structure at its beginning. The SP image is relocatable and it is handled by the ELF loader (ldelf) component
+of OP-TEE. Naturally this environment only works with OP-TEE in the role of the SPMC.
+
+sp
+""
+
+Deployments that use the sp environment can produce SPMC agnostic SP images. This environment generates SP images as flat
+binaries that can be loaded without an ELF loader. The initialization of the stack and the handling of relocation must be done
+in the startup code of the SP. Setting the memory access rights of different sections of the SP image can be either done
+thought load relative memory regions in the manifest or by using the ``FFA_MEM_PERM_SET`` interface of the FF-A v1.1
+specification in the boot phase of the SP.
+
+Trusted Services first builds ELF files for the sp environment deployments and then it generates the memory region nodes of the
+manifest based on the sections of the ELF file. The sections of the ELF is then copied into the flat binary image. The
+environment provides the startup file so all the necessary initialization steps are done before the ``sp_main`` call.
+
platforms
'''''''''
@@ -206,6 +231,6 @@
--------------
-*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2023, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/software-requirements.rst b/docs/developer/software-requirements.rst
index 1449724..cbdf81a 100644
--- a/docs/developer/software-requirements.rst
+++ b/docs/developer/software-requirements.rst
@@ -16,7 +16,7 @@
* Python3.6 and the modules listed in ``<project>/requirements.txt``.
* GCC supporting the deployment.
- * `opteesp` environment: a host to aarch64 cross-compiler is needed. Please use the compilers specified by the
+ * `opteesp` and `sp` environments: a host to aarch64 cross-compiler is needed. Please use the compilers specified by the
`OP-TEE documentation`_.
* `arm-linux` environment: a host to aarch64 linux cross-compiler is needed. Please use the version `9.2-2019.12` of the
"aarch64-none-linux-gnu" compiler available from `arm Developer`_.
@@ -34,6 +34,6 @@
.. _CMake download page: https://cmake.org/files/v3.18/
.. _`AEM FVP`: https://developer.arm.com/-/media/Files/downloads/ecosystem-models/FVP_Base_RevC-2xAEMvA_11.18_16_Linux64.tgz
-*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2023, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/services/secure-storage-service-description.rst b/docs/services/secure-storage-service-description.rst
index 03295bf..f786af5 100644
--- a/docs/services/secure-storage-service-description.rst
+++ b/docs/services/secure-storage-service-description.rst
@@ -150,7 +150,7 @@
''''''''''''''''''''''''''''''''''''''''''''''''
The Crypto service provider uses the Mbed Crypto portion of Mbed TLS to implement crypto
operations. Persistent keys are stored via the PSA Internal Trusted Storage C API.
-In the opteesp deployment of the Crypto service provider, a storage client backend is
+In the opteesp and sp deployments of the Crypto service provider, a storage client backend is
used that accesses a secure store provided by a separate secure partition. The following
deployment diagram illustrates the storage frontend/backend combination used:
@@ -167,6 +167,6 @@
--------------
-*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2022-2023, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/services/uefi-smm-services.rst b/docs/services/uefi-smm-services.rst
index 3795063..c21ea4c 100644
--- a/docs/services/uefi-smm-services.rst
+++ b/docs/services/uefi-smm-services.rst
@@ -33,7 +33,7 @@
* Can be used with any RPC layer - not tied to MM Communicate RPC.
* Volatile and non-volatile storage is accessed via instances of the common *storage_backend* interface.
-The *smm-gateway/opteesp* deployment integrates the *smm_variable* service provider with the following:
+The *smm-gateway/opteesp* and *smm-gateway/sp* deployments integrate the *smm_variable* service provider with the following:
* An MM Communicate based RPC endpoint.
* A *mock_store* instance for volatile variables.
@@ -238,6 +238,6 @@
--------------
-*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2021-2023, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause