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/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/spm/optee/opteesp-deployment-guide.rst b/docs/environments/secure-partitions/spm/optee/opteesp-deployment-guide.rst
new file mode 100644
index 0000000..233a189
--- /dev/null
+++ b/docs/environments/secure-partitions/spm/optee/opteesp-deployment-guide.rst
@@ -0,0 +1,91 @@
+Deploying trusted services in S-EL0 Secure Partitions under OP-TEE
+==================================================================
+
+Trusted services built for the *opteesp* environment may be deployed to run within S-EL0 secure
+partitions, managed by OP-TEE. The current implementation of the OP-TEE SPMC supports booting SPs
+embedded into the OP-TEE OS binary (similar to early-TAs) or from the FIP.
+
+Tool prerequisites and general build instruction for OP-TEE are described here:
+`<https://optee.readthedocs.io/en/latest/building/gits/build.html>`_
+
+Download page for Arm Fixed Virtual Platforms (FVP):
+`<https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms>`_
+
+
+Embedding SP images into the *OP-TEE OS* image
+----------------------------------------------
+
+The set of SP images to include in the built *OP-TEE OS* image are specified to the *OP-TEE OS*
+build by the ``SP_PATHS`` make variable. The ``SP_PATHS`` variable should be assigned a string
+containing a space separated list of file paths for each SP image file to include. SP images
+that need to be deployed from the Trusted Services project will be located in the install directory,
+specified when the SP images where built i.e.::
+
+ <CMAKE_INSTALL_PREFIX>/opteesp/bin
+
+The following example illustrates a setting of the ``SP_PATHS`` variable to deploy the Secure Storage
+SP and Crypto SP::
+
+ SP_PATHS="ts-install-dir/opteesp/bin/dc1eef48-b17a-4ccf-ac8b-dfcff7711b14.stripped.elf \
+ ts-install-dir/opteesp/bin/d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0.stripped.elf"
+
+
+Reference OP-TEE build with PSA RoT Services
+--------------------------------------------
+
+To provide an example integration of OP-TEE with a set of trusted services, a makefile called
+*fvp-ps-sp.mk* is included in the OP-TEE build repository that builds OP-TEE OS with a set of SP
+images. SP images are built using the standard trusted services build flow and are automatically
+injected into the *optee_os* build using the TA feature described above.
+
+A bootable Linux image is created that is intended to run on the Arm AEM FVP virtual platform. The
+built image includes user space programs that may be used to test and demonstrate the deployed
+trusted services.
+
+
+Getting build dependencies
+''''''''''''''''''''''''''
+
+To help setup the workspace, a manifest file called *fvp-ts.xml* is included in OP-TEE manifests
+repository. This may be used with the *repo* tool to manage the set of git repositories.
+
+Having created a new directory for the workspace, the required set of git repositories can be cloned
+and fetched using::
+
+ repo init -u https://github.com/OP-TEE/manifest.git -b master -m fvp-ts.xml
+ repo sync
+
+
+Building the reference OP-TEE image
+'''''''''''''''''''''''''''''''''''
+
+To build the bootable image that includes OP-TEE and the set of secure partition images that hold the
+PSA RoT services, use the following (from the root directory of the workspace)::
+
+ make -C build
+
+This will take many tens of minutes to complete.
+
+
+Running the reference OP-TEE image on FVP
+'''''''''''''''''''''''''''''''''''''''''
+
+The fvp makefile includes a *run* and *run-only* target which can be used to start the FVP model and
+boot the built image. The example assumes that the FVP model has been installed in the following
+directory relative to the OP-TEE build directory::
+
+ ../Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3
+
+To boot the built image on FVP without building, use::
+
+ FVP_PATH=../Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3 make run-only
+
+For information on running user space programs on FVP, see:
+
+:ref:`Running User-space Programs on FVP`
+
+--------------
+
+*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/optee/userspace-programs-on-fvp.rst b/docs/environments/secure-partitions/spm/optee/userspace-programs-on-fvp.rst
new file mode 100644
index 0000000..e364839
--- /dev/null
+++ b/docs/environments/secure-partitions/spm/optee/userspace-programs-on-fvp.rst
@@ -0,0 +1,150 @@
+Running user-space programs on FVP
+==================================
+
+This page explains how to load and run user space programs on a Linux image running in FVP simulation.
+The loaded programs may use any trusted services that are available as part of the image firmware.
+
+To prepare and run an image that includes trusted services running in S-EL0 secure partitions under
+OP-TEE see: :ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE`
+
+The example assumes that the FVP model has been installed in the following
+directory relative to the OP-TEE build directory::
+
+ ../Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3
+
+
+Shared directory
+----------------
+
+The AEM FVP supports directory sharing between the target and the host OS. This provides a
+convenient way to transfer files between the host and the device simulation. When the FVP is run
+using the *run-only* target from the *op-tee/build* repository, the shared directory is set-up
+automatically. The whole "workspace" is shared to the FVP and mounted under ``/mnt/host``.
+
+
+Running service level tests
+---------------------------
+
+Most test and demo applications are integrated into the OP-TEE build flow, and can be build using
+the makefiles in the ``op-tee/build`` repository.
+
+To build all such binaries build the ``ffa-test-all`` target. For available targets please refer to
+fvp-psa-sp.mk_. As an example to build the ``ts-service-test`` application execute the following
+commands from the root of the workspace::
+
+ make -C build ffa-ts-service-test
+
+The executable includes service level test cases that exercise trusted services via their
+standard interfaces. Test cases use *libts* for locating services and establishing RPC
+sessions. *ts-service-test* provides a useful reference for understanding how *libts* may
+be used for accessing trusted services.
+
+Build output will be copied to ``out/ts-install``.
+
+To build the applications without using the ``op-tee/build`` files refer to the instructions here:
+:ref:`Build Instructions`
+
+Run *ts-service-test*
+'''''''''''''''''''''
+
+To start the FVP, from the root directory of the workspace, enter::
+
+ FVP_PATH=../Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3 make -C build run-only
+
+Once it boots to the login prompt, log in as root and from the FVP terminal, enter::
+
+ # Enter the mount target for the shared directory
+ cd /mnt/host
+
+ # Install the shared library and executables
+ cp -vat /usr out/ts-install/arm-linux/lib out/ts-install/arm-linux/bin
+
+ # Load the kernel modules
+ out/linux-arm-ffa-tee/load_module.sh
+ out/linux-arm-ffa-user/load_module.sh
+
+ # Run the test application
+ ts-service-test -v
+
+Use the same flow for other user-space programs. Check the output of the ``cp`` command executed to see
+executables copied under ``/usr/bin``.
+
+If all is well, you should see something like::
+
+ TEST(PsServiceTests, createAndSetExtended) - 0 ms
+ TEST(PsServiceTests, createAndSet) - 0 ms
+ TEST(PsServiceTests, storeNewItem) - 0 ms
+ TEST(ItsServiceTests, storeNewItem) - 0 ms
+ TEST(AttestationProvisioningTests, provisionedIak) - 1 ms
+ TEST(AttestationProvisioningTests, selfGeneratedIak) - 1 ms
+ TEST(AttestationServiceTests, repeatedOperation) - 75 ms
+ TEST(AttestationServiceTests, invalidChallengeLen) - 0 ms
+ TEST(AttestationServiceTests, checkTokenSize) - 2 ms
+ TEST(CryptoKeyDerivationServicePackedcTests, deriveAbort) - 0 ms
+ TEST(CryptoKeyDerivationServicePackedcTests, hkdfDeriveBytes) - 0 ms
+ TEST(CryptoKeyDerivationServicePackedcTests, hkdfDeriveKey) - 0 ms
+ TEST(CryptoMacServicePackedcTests, macAbort) - 0 ms
+ TEST(CryptoMacServicePackedcTests, signAndVerify) - 1 ms
+ TEST(CryptoCipherServicePackedcTests, cipherAbort) - 0 ms
+ TEST(CryptoCipherServicePackedcTests, encryptDecryptRoundtrip) - 0 ms
+ TEST(CryptoHashServicePackedcTests, hashAbort) - 0 ms
+ TEST(CryptoHashServicePackedcTests, hashAndVerify) - 0 ms
+ TEST(CryptoHashServicePackedcTests, calculateHash) - 0 ms
+ TEST(CryptoServicePackedcTests, generateRandomNumbers) - 0 ms
+ TEST(CryptoServicePackedcTests, asymEncryptDecryptWithSalt) - 14 ms
+ TEST(CryptoServicePackedcTests, asymEncryptDecrypt) - 1 ms
+ TEST(CryptoServicePackedcTests, signAndVerifyEat) - 4 ms
+ TEST(CryptoServicePackedcTests, signAndVerifyMessage) - 4 ms
+ TEST(CryptoServicePackedcTests, signAndVerifyHash) - 4 ms
+ TEST(CryptoServicePackedcTests, exportAndImportKeyPair) - 1 ms
+ TEST(CryptoServicePackedcTests, exportPublicKey) - 1 ms
+ TEST(CryptoServicePackedcTests, purgeKey) - 0 ms
+ TEST(CryptoServicePackedcTests, copyKey) - 1 ms
+ TEST(CryptoServicePackedcTests, generatePersistentKeys) - 1 ms
+ TEST(CryptoServicePackedcTests, generateVolatileKeys) - 0 ms
+ TEST(CryptoServiceProtobufTests, generateRandomNumbers) - 1 ms
+ TEST(CryptoServiceProtobufTests, asymEncryptDecryptWithSalt) - 15 ms
+ TEST(CryptoServiceProtobufTests, asymEncryptDecrypt) - 1 ms
+ TEST(CryptoServiceProtobufTests, signAndVerifyMessage) - 4 ms
+ TEST(CryptoServiceProtobufTests, signAndVerifyHash) - 4 ms
+ TEST(CryptoServiceProtobufTests, exportAndImportKeyPair) - 1 ms
+ TEST(CryptoServiceProtobufTests, exportPublicKey) - 0 ms
+ TEST(CryptoServiceProtobufTests, generatePersistentKeys) - 1 ms
+ TEST(CryptoServiceProtobufTests, generateVolatileKeys) - 1 ms
+ TEST(CryptoServiceLimitTests, volatileRsaKeyPairLimit) - 99 ms
+ TEST(CryptoServiceLimitTests, volatileEccKeyPairLimit) - 22 ms
+ TEST(DiscoveryServiceTests, checkServiceInfo) - 0 ms
+ TEST(SmmVariableAttackTests, getCheckPropertyWithMaxSizeName) - 0 ms
+ TEST(SmmVariableAttackTests, getCheckPropertyWithOversizeName) - 0 ms
+ TEST(SmmVariableAttackTests, setCheckPropertyWithMaxSizeName) - 0 ms
+ TEST(SmmVariableAttackTests, setCheckPropertyWithOversizeName) - 0 ms
+ TEST(SmmVariableAttackTests, enumerateWithSizeMaxNameSize) - 0 ms
+ TEST(SmmVariableAttackTests, enumerateWithOversizeName) - 0 ms
+ TEST(SmmVariableAttackTests, setAndGetWithSizeMaxNameSize) - 0 ms
+ TEST(SmmVariableAttackTests, setAndGetWithOversizeName) - 0 ms
+ TEST(SmmVariableAttackTests, setWithSizeMaxNameSize) - 0 ms
+ TEST(SmmVariableAttackTests, setWithOversizeName) - 0 ms
+ TEST(SmmVariableAttackTests, setWithSizeMaxDataSize) - 0 ms
+ TEST(SmmVariableAttackTests, setWithOversizeData) - 0 ms
+ TEST(SmmVariableServiceTests, checkMaxVariablePayload) - 0 ms
+ TEST(SmmVariableServiceTests, setSizeConstraint) - 0 ms
+ TEST(SmmVariableServiceTests, enumerateStoreContents) - 0 ms
+ TEST(SmmVariableServiceTests, getVarSizeNv) - 0 ms
+ TEST(SmmVariableServiceTests, getVarSize) - 0 ms
+ TEST(SmmVariableServiceTests, setAndGetNv) - 1 ms
+ TEST(SmmVariableServiceTests, setAndGet) - 0 ms
+ TEST(TestRunnerServiceTests, runSpecificTest) - 0 ms
+ TEST(TestRunnerServiceTests, runConfigTests) - 0 ms
+ TEST(TestRunnerServiceTests, listPlatformTests) - 0 ms
+ TEST(TestRunnerServiceTests, runAllTests) - 0 ms
+ TEST(TestRunnerServiceTests, listAllTests) - 0 ms
+
+ OK (67 tests, 67 ran, 977 checks, 0 ignored, 0 filtered out, 261 ms)
+
+--------------
+
+.. _fvp-psa-sp.mk :https://github.com/OP-TEE/build/blob/master/fvp-psa-sp.mk
+
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause