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/index.rst b/docs/deployments/index.rst
new file mode 100644
index 0000000..40a6949
--- /dev/null
+++ b/docs/deployments/index.rst
@@ -0,0 +1,31 @@
+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/deployments/libraries.rst b/docs/deployments/libraries.rst
new file mode 100644
index 0000000..2e60d86
--- /dev/null
+++ b/docs/deployments/libraries.rst
@@ -0,0 +1,51 @@
+Libraries
+=========
+Some deployments build common functionality into libraries that may be used by
+other deployments or external applications. The following library deployments
+are currently supported:
+
+libts
+-----
+Userspace applications that depend on trusted services may use *libts* for handling
+service discovery and RPC messaging. A major benefit to application developers is
+that *libts* entirely decouples client applications from details of where a service
+provider is deployed and how to communicate with it. All TS test executables and
+tools that interact with service providers use *libts*.
+
+To facilitate test and development within a native PC environment, the *libts*
+deployment for the *linux-pc* environment integrates a set of service providers
+into the library itself. From a client application's perspective, this looks
+exactly the same as when running on a target platform with service providers
+deployed in secure processing environments. For more information, see:
+:ref:`Service Locator`.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc* - service providers integrated into library
+ * | *arm-linux* - communicates with service providers in secure processing environment
+ * - Used by
+ - * Userspace applications
+
+libsp
+-----
+*libsp* provides a functional interface for using FF-A messaging and memory
+management facilities. *libsp* is used in SP deployments. For more information, see:
+:ref:`libsp`.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *opteesp*
+ * - Used by
+ - * Secure partitions
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
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
diff --git a/docs/deployments/test-executables.rst b/docs/deployments/test-executables.rst
new file mode 100644
index 0000000..db569f3
--- /dev/null
+++ b/docs/deployments/test-executables.rst
@@ -0,0 +1,113 @@
+Test Executables
+================
+The Trusted Services project maintains a number of deployments concerned with
+test. Although there may be some coverage overlap between different deployments,
+in general, the built test executables corresponding to different deployments
+serve different purposes. Most test executables may be run either on target
+hardware or a development PC as a native application. For more information, see:
+:ref:`Running Tests`.
+
+The following test deployments are currently supported:
+
+component-test
+--------------
+The component-test deployment combines a large set of tests and components into
+a monolithic image that may be run as a userspace application. The CppUtest test
+framework is used for running tests and capturing results. The component-test
+executable may be built and run very quickly to obtain a first pass check for
+build failures or regressions.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc*
+ * | *arm-linux*
+ * - Used for
+ - * | Build testing
+ * | Development support and debug
+ * | Regression testing
+
+ts-service-test
+---------------
+The ts-service-test deployment combines test suites that exercise service providers
+via their standard service interfaces where test cases perform the role of service client.
+Service discovery and RPC messaging is handled by the *libts* shared library. On real targets,
+the *libts* library uses a dynamic discovery mechanism to locate and communicate with real
+service deployments. For native PC builds, service providers are embedded into the *libts*
+library itself, allowing service level testing within a native PC environment.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc* - tests against service providers integrated into *libts*
+ * | *arm-linux* - tests against real service deployments
+ * - Used for
+ - * | End-to-end service testing
+ * | Security testing
+ * | Development support and debug
+ * | Regression testing
+
+uefi-test
+---------
+The uefi-test deployment includes service level tests for UEFI SMM services.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc* - tests against service providers integrated into *libts*
+ * | *arm-linux* - tests against real service deployments using MM_COMMUNICATE
+ * - Used for
+ - * | UEFI service level testing
+ * | Regression testing
+
+psa-api-test
+------------
+Used for PSA API conformance testing using test suites from: `PSA Arch Test project`_.
+Tests are integrated with service clients to enable end-to-end testing against deployed
+service providers. Separate executables are built for each API under test. As with
+ts-service-test and uefi-test, service discovery and messaging is handled by *libts*,
+allowing API tests to be run on real targets or within a native PC environment.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc* - tests against service providers integrated into *libts*
+ * | *arm-linux* - tests against real service deployments
+ * - Used for
+ - * | PSA API conformance testing
+ * | Regression testing
+
+ts-remote-test
+--------------
+The ts-remote-test deployment builds a userspace application that allows a remote
+test runner to be discovered and controlled. It implements a subset of the the
+CppUtest command line interface but instead of running tests directly, it
+communicates with the remote test runner to run tests and collect results. Can
+be used, for example, to control the running of tests included in the env-test
+deployment.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc* - tests against test runner service provider integrated into *libts*
+ * | *arm-linux* - tests against real test runner deployment e.g. env-test
+ * - Used for
+ - * | Running environment tests
+
+--------------
+
+.. _`PSA Arch Test project`: https://github.com/ARM-software/psa-arch-tests.git
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/deployments/tools-demo-apps.rst b/docs/deployments/tools-demo-apps.rst
new file mode 100644
index 0000000..f3c3adf
--- /dev/null
+++ b/docs/deployments/tools-demo-apps.rst
@@ -0,0 +1,41 @@
+Tools & Demo Applications
+=========================
+The following deployments are concerned with building tools and demo applications.
+
+platform-inspect
+----------------
+The *platform-inspect* tool may be run from a Linux terminal to inspect and
+report information about platform firmware. Functionality is currently limited
+to retrieving a firmware attestation report and printing its contents.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc*
+ * | *arm-linux*
+ * - Used for
+ - * | Obtaining information about platform firmware
+
+ts-demo
+-------
+*ts-demo* is a simple application that uses the Crypto service to perform some
+typical sign, verify and encrypt operations. It is intended to be used as an
+example of how trusted services can be used by userspace applications.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc*
+ * | *arm-linux*
+ * - Used for
+ - * | Provides an example for how to use trusted services
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause