Define docs structure for environments
Adds an extensible structure for documents related to secure processing
environments. The only class of environment currently represented is
Secure Partitions. This change adds a structure to support general
FF-A documents as well as op-tee and hafnium specific documents.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: Ic2fdd792580d711091435716e4b9c863df424149
diff --git a/docs/certification/psa.rst b/docs/certification/psa.rst
index d12f12c..c99e1c2 100644
--- a/docs/certification/psa.rst
+++ b/docs/certification/psa.rst
@@ -2,7 +2,7 @@
==============================
Trusted Services is the home of the |PSA| reference implementation. The PSA partitions are implemented based on the |FF-A|
-specification. For details on FF-A support in TS please see the :doc:`ff-a` page.
+specification.
For background information on |PSA| please visit the `PSA homepage`_. If you are looking for information on certified products
please visit `www.psacertified.org`_
diff --git a/docs/environments/index.rst b/docs/environments/index.rst
index 18948ea..adb9008 100644
--- a/docs/environments/index.rst
+++ b/docs/environments/index.rst
@@ -1,9 +1,15 @@
Environments
============
+Depending on Arm architecture and SoC capabilities, there may be different options for
+implementing hardware-backed isolation for protecting security sensitive workloads. The
+Trusted Services project decouples service related components from any particular
+environment, enabling services to be deployed in different environments. This section
+provides information about supported secure processing environments.
+
.. toctree::
:maxdepth: 1
- :caption: Contents:
+ :caption: Supported Environments:
secure-partitions/index
diff --git a/docs/certification/ff-a.rst b/docs/environments/secure-partitions/ff-a/index.rst
similarity index 68%
rename from docs/certification/ff-a.rst
rename to docs/environments/secure-partitions/ff-a/index.rst
index c6a8e39..5c7dc03 100644
--- a/docs/certification/ff-a.rst
+++ b/docs/environments/secure-partitions/ff-a/index.rst
@@ -11,10 +11,6 @@
--------------
-.. _`PSA homepage`: https://developer.arm.com/architectures/security-architectures/platform-security-architecture
-.. _`www.psacertified.org`: https://www.psacertified.org/certified-products/
-.. _`Hafnium project`: https://www.trustedfirmware.org/projects/hafnium/
-
-*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/secure-partitions/index.rst b/docs/environments/secure-partitions/index.rst
index 9ab70d1..d57b103 100644
--- a/docs/environments/secure-partitions/index.rst
+++ b/docs/environments/secure-partitions/index.rst
@@ -1,16 +1,40 @@
Secure Partitions
=================
+:term:`Secure Partitions<Secure Partition>` are defined by the :term:`FF-A` standard
+
+Secure partitions are isolated processing environments managed by a Secure Partition Manager (SPM).
+An SPM performs the role of hypervisor for the Arm Secure state and is responsible for managing
+SP initialization, memory management and messaging. The Arm Firmware Framework for A-Profile (FF-A)
+specification (`FF-A Specification`_) defines the set of firmware features that enable the use of
+secure partitions for protecting sensitive workloads.
+
+The Armv8.4 architecture introduces the virtualization extension in the Secure state. For silicon
+based on Armv8.4 (or above) that implement the Secure-EL2 extension, the `Hafnium Project`_
+provides a reference SPM implementation. For pre-Arm8.4 silicon, the `OP-TEE Project`_ provides
+an alternative reference SPM implementation.
+
+Within the Trusted Services, the environments realized by the two reference SPM implementations
+are named as follows:
+
+ * *hfsp* - for service deployment under Hafnium
+ * *opteesp* - for service deployment under OP-TEE
+
.. toctree::
:maxdepth: 1
:caption: Contents:
+ ff-a/index
+ spm/optee/index
+ spm/hafnium/index
libsp
- userspace-programs-on-fvp
- opteesp-deployment-guide
--------------
+.. _`FF-A Specification`: https://developer.arm.com/documentation/den0077/latest
+.. _`Hafnium Project`: https://www.trustedfirmware.org/projects/hafnium/
+.. _`OP-TEE Project`: https://www.trustedfirmware.org/projects/op-tee/
+
*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/secure-partitions/spm/hafnium/index.rst b/docs/environments/secure-partitions/spm/hafnium/index.rst
new file mode 100644
index 0000000..88cbbcc
--- /dev/null
+++ b/docs/environments/secure-partitions/spm/hafnium/index.rst
@@ -0,0 +1,12 @@
+S-EL1 Secure Partitions under Hafnium
+=====================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/secure-partitions/spm/optee/index.rst b/docs/environments/secure-partitions/spm/optee/index.rst
new file mode 100644
index 0000000..2149880
--- /dev/null
+++ b/docs/environments/secure-partitions/spm/optee/index.rst
@@ -0,0 +1,15 @@
+S-EL0 Secure Partitions under OP-TEE
+====================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ userspace-programs-on-fvp
+ opteesp-deployment-guide
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/secure-partitions/opteesp-deployment-guide.rst b/docs/environments/secure-partitions/spm/optee/opteesp-deployment-guide.rst
similarity index 100%
rename from docs/environments/secure-partitions/opteesp-deployment-guide.rst
rename to docs/environments/secure-partitions/spm/optee/opteesp-deployment-guide.rst
diff --git a/docs/environments/secure-partitions/userspace-programs-on-fvp.rst b/docs/environments/secure-partitions/spm/optee/userspace-programs-on-fvp.rst
similarity index 100%
rename from docs/environments/secure-partitions/userspace-programs-on-fvp.rst
rename to docs/environments/secure-partitions/spm/optee/userspace-programs-on-fvp.rst