DOC: update documentation.
Add documentation covering:
- developer information about architecture
- project structure and building
- project overview and service descriptions
- the portability model for supporting hardware
Signed-off-by: Julian Hall <julian.hall@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@gmail.com>
Change-Id: I8bf9c01a66350719d82a7ca2bc1c78a8ab17978d
diff --git a/docs/environments/deployment-guides/fvp-deployment-guide.rst b/docs/environments/deployment-guides/fvp-deployment-guide.rst
new file mode 100644
index 0000000..eeb9078
--- /dev/null
+++ b/docs/environments/deployment-guides/fvp-deployment-guide.rst
@@ -0,0 +1,86 @@
+Deploying 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`
+
+Shared directory
+----------------
+The OP-TEE image built for the FVP virtual platform supports directory sharing between the running
+OS and the host computer. 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 in *fvp.mk*, the shared
+directory is set-up automatically.
+
+On the host, the shared directory is located here::
+
+ optee/shared
+
+On the simulated device, running under FVP, a mount is created here::
+
+ /mnt
+
+Deploying service level tests
+-----------------------------
+As an example of how to load and run programs, the *ts-service-test* binary executable is used.
+The build file for the *arm-linux* deployment of *ts-service-test* lives under::
+
+ trusted-services/deployments/ts-service-test/arm-linux
+
+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.
+
+The build file for the *arm-linux* deployment of *libts* lives under::
+
+ trusted-services/deployments/libts/arm-linux
+
+Trusted service build instructions are here:
+:ref:`Build Instructions`
+
+Having built *ts-service-test* and *libts* for the *arm-linux* environment, the steps
+are required.
+
+Copy files to share directory
+'''''''''''''''''''''''''''''
+Assuming that the *OP-TEE* and *trusted-services* projects are located under a common
+parent directory, the following files need to be copied from the host using::
+
+ cp trusted-services/deployments/libts/arm-linux/build/install/lib/libts.so optee/shared/.
+ cp trusted-services/deployments/ts-service-test/arm-linux/build/install/bin/ts-service-test optee/shared/.
+
+Installing libts.so
+'''''''''''''''''''
+Having copied *libts.so* to the shared directory, it needs to be copied to one of the standard
+lib directories so that it is located when a dependent program is started. From the terminal
+command prompt for the booted FVP, use::
+
+ cd /mnt
+ cp libts.so /usr/lib/.
+
+Running the program executable
+''''''''''''''''''''''''''''''
+The *ts-service-test* program may be run directly from the */mnt* directory using::
+
+ ./ts-service-test -v
+
+If all is well, you should see something like::
+
+ TEST(E2EcryptoOpTests, generateRandomNumbers) - 3 ms
+ TEST(E2EcryptoOpTests, asymEncryptDecrypt) - 8 ms
+ TEST(E2EcryptoOpTests, signAndVerifyHash) - 29 ms
+ TEST(E2EcryptoOpTests, exportAndImportKeyPair) - 17 ms
+ TEST(E2EcryptoOpTests, exportPublicKey) - 10 ms
+ TEST(E2EcryptoOpTests, generatePersistentKeys) - 34 ms
+ TEST(E2EcryptoOpTests, generateVolatileKeys) - 16 ms
+
+ OK (7 tests, 7 ran, 56 checks, 0 ignored, 0 filtered out, 117 ms)
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/deployment-guides/opteesp-deployment-guide.rst b/docs/environments/deployment-guides/opteesp-deployment-guide.rst
new file mode 100644
index 0000000..e71140f
--- /dev/null
+++ b/docs/environments/deployment-guides/opteesp-deployment-guide.rst
@@ -0,0 +1,97 @@
+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. Secure partitions are loaded and run by OP-TEE using the early-TA
+feature where a set of TAs or SPs are loaded during OP-TEE initialization. This feature relies on
+SP images being incorporated into the *OP-TEE OS* image at build time. It is therefore necessary to
+have access to the OP-TEE build environment and tools in order to deploy SP images.
+
+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>`_
+
+Incorporating 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 EARLY_TA_PATHS make variable. The EARLY_TA_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>/bin
+
+The following example illustrates a setting of the EARLY_TA_PATHS variable to deploy the Secure Storage
+SP and Crypto SP::
+
+ EARLY_TA_PATHS="ts-install-dir/bin/dc1eef48-b17a-4ccf-ac8b-dfcff7711b14.stripped.elf \
+ ts-install-dir/bin/d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0.stripped.elf"
+
+To help with integration with the OP-TEE build system, the installation step for a deployment to the
+*opteesp* environment includes the generation of a simple makefile that extends the EARLY_TA_PATHS
+variable for the particular deployment. For example, the generated makefile for the crypto SP
+contains::
+
+ OPTEE_OS_COMMON_EXTRA_FLAGS+=EARLY_TA_PATHS+=${TS_INSTALL_PREFIX}/bin/d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0.stripped.elf
+
+The generated makefile is installed to::
+
+ <CMAKE_INSTALL_PREFIX>/lib/make
+
+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_ffa.mk*
+is included in the OP-TEE build repository that builds OP-TEE OS with a set of SP images that provide PSA
+RoT services. SP images are built using the standard trusted services build flow and are automatically
+injected into the *optee_os* build using the early TA feature described above.
+
+A bootable Linux image is created that is intended to run on the Arm FVP virtual platform. The built image
+includes user space programs that may be used to test and demonstrate the deployed trusted services.
+
+Setting up the OP-TEE build environment
+'''''''''''''''''''''''''''''''''''''''
+To help setup the OP-TEE build environment, a manifest file called *psa-sp-fvp.xml* is included in OP-TEE
+manifests repository. This may be used with the *repo* tool to manage the set of git repositories. Note
+that this manifest relies on SSH access to *github.com* so ensure that you have installed a suitable public
+key into your *github* account.
+
+Having created a new directory for the OP-TEE build environment, the required set of git repositories can
+be cloned and fetched using::
+
+ repo init -u https://git.trustedfirmware.org/OP-TEE/manifest.git -b psa-development -m psa-sp-fvp.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 your OP-TEE root directory)::
+
+ cd build
+ make -f fvp_ffa.mk all
+
+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::
+
+ ../Foundation_Platformpkg/models/Linux64_GCC-6.4/
+
+To boot the built image on FVP without building, use::
+
+ make run-only FVP_PATH=../Foundation_Platformpkg/models/Linux64_GCC-6.4/
+
+For information on running user space programs on FVP, see:
+
+:ref:`Deploying Programs on FVP`
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause