Refactor top-level document structure
In preparation for extending documentation on PSA certified and
secure processing environments, the top-level structure has been
cleaned-up and simplified. PNGs from tf-m for docs home have
been reused for consistency.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: Id2b7d9b46dd90f419d00c417a06003e32862ead0
diff --git a/docs/deployments/secure-partitions.rst b/docs/deployments/secure-partitions.rst
new file mode 100644
index 0000000..338363c
--- /dev/null
+++ b/docs/deployments/secure-partitions.rst
@@ -0,0 +1,133 @@
+Secure Partition Images
+=======================
+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 deployments that create SP images 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`.
+
+.. 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`.
+
+.. 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`.
+
+.. 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