Expand deployments document structure
To cope with the growing number of deployments, the documentation
structure for deployments has been expanded to include sub-pages
for the different types of deployment. This commit includes
fuller descriptions of SP deployments.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: Id383cdb67f9e1e3a515e81673cc84077f77b5562
diff --git a/docs/developer/deployments.rst b/docs/developer/deployments.rst
deleted file mode 100644
index 74fdeb3..0000000
--- a/docs/developer/deployments.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-Deployments
-===========
-In the context of the Trusted Services project, a deployment represents a unit of functionality
-that is built for a specific environment. You can find out more about deployments here
-:ref:`Project Structure`.
-
-The following table lists currently supported deployments:
-
-.. list-table:: Supported deployments
- :header-rows: 1
-
- * - Deployment Name
- - Environments
- - Provides
- - Used for
- * - component-test
- - linux-pc, arm-linux
- - Standalone tests for components and integrations
- - Test driven development and regression testing
- * - ts-service-test
- - linux-pc, arm-linux
- - Service API level tests
- - Tests services from perspective of client application
- * - ts-demo
- - linux-pc, arm-linux
- - Demonstration client application
- - Example user-space client application
- * - libts
- - linux-pc, arm-linux
- - Provides standard client interface for locating services and establishing RPC sessions
- - Client application development
- * - crypto
- - opteesp
- - Crypto trusted service
- - Production deployments
- * - secure-storage
- - opteesp
- - Secure storage trusted service
- - Production deployments
- * - libsp
- - opteesp
- - FF-A interface library
- - FF-A library used in secure partition environments
-
---------------
-
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
-
-SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments/demo-apps.rst b/docs/developer/deployments/demo-apps.rst
new file mode 100644
index 0000000..abde218
--- /dev/null
+++ b/docs/developer/deployments/demo-apps.rst
@@ -0,0 +1,10 @@
+Demo Applications
+=================
+To do
+
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments/index.rst b/docs/developer/deployments/index.rst
new file mode 100644
index 0000000..a9b2048
--- /dev/null
+++ b/docs/developer/deployments/index.rst
@@ -0,0 +1,32 @@
+Deployments
+===========
+In the context of the Trusted Services project, a deployment represents a build of an
+assembly of components that is intended to run within a specific environment. Some
+deployments may be built for different platforms using platform specific components
+if needed. The concept of a deployment is general purpose and can be applied to building
+a wide range of targets such as secure partition images, user-space tools, shared libraries
+and test executables.
+
+Supported deployments are described on the following pages:
+
+.. toctree::
+ :maxdepth: 1
+
+ secure-partitions
+ test-executables
+ libraries
+ tools
+ demo-apps
+
+Related deployments:
+
+ - :ref:`Project Structure`
+ - :ref:`Portability Model`
+ - :ref:`Build Instructions`
+ - :ref:`Running Tests`
+
+--------------
+
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments/libraries.rst b/docs/developer/deployments/libraries.rst
new file mode 100644
index 0000000..cf80eab
--- /dev/null
+++ b/docs/developer/deployments/libraries.rst
@@ -0,0 +1,10 @@
+Libraries
+=========
+To do
+
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments/secure-partitions.rst b/docs/developer/deployments/secure-partitions.rst
new file mode 100644
index 0000000..8e6ba24
--- /dev/null
+++ b/docs/developer/deployments/secure-partitions.rst
@@ -0,0 +1,133 @@
+Secure Partitions
+=================
+Secure partition (SP) deployments are concerned with building SP images that can
+be loaded and run under a secure partition manager such as Hafnium or OP-TEE.
+SP images will usually include service provider components that expose a
+service interface that may be reached using FF-A messages. A set of SP images
+will be loaded and verified by device firmware to provide the required services.
+
+The following SP deployments are currently supported:
+
+crypto
+------
+An instance of the crypto service provider is built into an SP image to
+perform cryptographic operations on behalf of clients running in different
+partitions. Backend crypto operations are implemented by the crypto library
+component of MbedTLS. This deployment provides the cryptographic facilities
+needed for PSA certification. For more information, see:
+:ref:`Crypto Service Description`.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * - External Dependencies
+ - * | TRNG (platform specific)
+ * | Secure storage SP
+
+attestation
+-----------
+An instance of the attestation service provider is built into an SP image
+to support remote attestation use-cases. The service provider obtains a
+trusted view of the boot state of device firmware from the TPM event log
+collected by the boot loader. This deployment provides the initial attestation
+facility needed for PSA certification. For more information, see:
+:ref:`Attestation Service Description`.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * - External Dependencies
+ - * | TPM Event Log (via SP boot parameter)
+ * | Crypto SP
+
+internal-trusted-storage & protected-storage
+--------------------------------------------
+Two secure storage SP deployments are provided to allow different classes
+of storage to coexist on a device. Both deployments build an instance of
+the secure storage service provider with a storage backend. To allow
+different security trade-offs to be made and to support different hardware,
+a system integrator may configure which storage backend to use. Secure storage
+is a requirement for PSA certification. For more information, see:
+:ref:`Secure Storage Service Description`.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * - External Dependencies
+ - * Depends on configured storage backend
+
+se-proxy
+--------
+The se-proxy SP provides access to services hosted by a secure enclave (hence
+'se'). A secure enclave consists of a separate MCU, connected to the host via
+a secure communications channel. To protect access to the communication channel,
+the se-proxy SP is assigned exclusive access to the communication peripheral via
+device or memory regions defined in the SP manifest. The deployment integrates
+multiple service providers into the SP image. After performing access control,
+service requests are forwarded to the secure enclave.
+
+The se-proxy deployment includes proxies for the following services:
+
+ - Crypto
+ - Attestation
+ - Internal Trusted Storage
+ - Protected Storage
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * - External Dependencies
+ - * SE communication peripheral (platform specific)
+
+smm-gateway
+-----------
+An instance of the smm-variable service provider is built into the smm-gateway SP
+image to provide secure world backing for UEFI SMM services. The smm-gateway SP
+provides a lightweight alternative to StMM. For more information, see:
+:ref:`UEFI SMM Services`.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * - External Dependencies
+ - * | Secure storage service instance (e.g. hosted by protected-storage SP)
+ * | Crypto service instance (e.g. hosted crypto SP)
+
+env-test
+--------
+An instance of the test runner service provider is built into an SP image to
+allow test cases to be run from within the SP isolated environment. The SP
+image also includes environment and platform specific test cases to allow
+access to FF-A services and platform hardware to be tested. The test runner
+service provider is intended to be used in conjunction with a client that
+coordinates which tests to run and collects test results.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * *opteesp* (runs as an S-EL0 SP under OP-TEE)
+ * - External Dependencies
+ - * Any hardware accessed by test cases (platform specific)
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments/test-executables.rst b/docs/developer/deployments/test-executables.rst
new file mode 100644
index 0000000..78345ef
--- /dev/null
+++ b/docs/developer/deployments/test-executables.rst
@@ -0,0 +1,10 @@
+Test Executables
+================
+To do
+
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments/tools.rst b/docs/developer/deployments/tools.rst
new file mode 100644
index 0000000..88fdd28
--- /dev/null
+++ b/docs/developer/deployments/tools.rst
@@ -0,0 +1,10 @@
+Tools
+=====
+To do
+
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/index.rst b/docs/developer/index.rst
index 33a03cc..5fe886f 100644
--- a/docs/developer/index.rst
+++ b/docs/developer/index.rst
@@ -10,7 +10,7 @@
portability-model
service-access-protocols
service-locator
- deployments
+ deployments/index
service-descriptions/index
software-requirements
build-instructions
@@ -21,6 +21,6 @@
--------------
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/standards/psa.rst b/docs/standards/psa.rst
index 1dbed39..eb22b3e 100644
--- a/docs/standards/psa.rst
+++ b/docs/standards/psa.rst
@@ -8,7 +8,7 @@
please visit `www.psacertified.org`_
For a list of PSA specific components refer to deployments targeting the ``opteesp`` environment on the
-:doc:`/developer/deployments` page.
+:doc:`/developer/deployments/index` page.
--------------
@@ -16,6 +16,6 @@
.. _`www.psacertified.org`: https://www.psacertified.org/certified-products/
.. _`Hafnium project`: https://www.trustedfirmware.org/projects/hafnium/
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause