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
diff --git a/docs/environments/ffa/libsp.rst b/docs/environments/ffa/libsp.rst
new file mode 100644
index 0000000..ff1b552
--- /dev/null
+++ b/docs/environments/ffa/libsp.rst
@@ -0,0 +1,132 @@
+libsp
+=====
+
+libsp is intended to be used from S-EL0 secure partitions. It contains all
+the necessary features for communicating with other components using the FF-A
+interfaces.
+
+The implementation is split into multiple layers for easy maintainability and
+usage. The structure and the short description of the components of the library
+is described below.
+
+For detailed information about the FF-A interfaces please check the
+`FF-A specification <https://developer.arm.com/documentation/den0077/a/>`_
+
+The API reference documentation is included in the code.
+
+The components of the following diagram are illustrated as classes but as the
+library is written in C they are not real classes. Their purpose is to describe
+the interfaces and dependencies of the library's components.
+
+.. uml:: /uml/libsp_functions.puml
+
+SP layer
+--------
+
+The SP layer provides convenient high level interface for accessing FF-A
+features. The layer has multiple components around the groups of the FF-A
+interfaces.
+
+SP RXTX
+'''''''
+
+The FF-A calls may utilize a pair or buffers called RXTX buffers for passing
+data to the SPM that won't fit into registers. These buffers should be set up
+during the initialization phase of the SP, then the FF-A calls can use these in
+discovery or memory management calls.
+
+The SP RXTX component provides a high level interface for registering these
+buffers. It also enables other components of the SP layer to use these buffers
+during FF-A calls without the need of manually passing the buffers to the
+functions.
+
+SP memory management
+''''''''''''''''''''
+
+The FF-A memory management interfaces involve multiple steps for setting up a
+memory transaction. This component gives a set of functions to the user for
+doing these transactions in a simple way. The supported memory transactions
+follows below:
+
+* Donate
+
+* Lend
+
+* Share
+
+* Retrieve
+
+* Relinquish
+
+* Reclaim
+
+FF-A layer
+----------
+
+The FF-A layer provides functions and types for accessing FF-A features through
+a C API. This low level API gives full control of the FF-A call parameters.
+
+FF-A API
+''''''''
+
+The FF-A API provides wrappers for the FF-A interfaces. These interfaces are
+fitted into the following groups:
+
+* Setup and discovery interfaces
+
+* CPU cycle management interfaces
+
+* Messaging interfaces
+
+* Memory management interfaces
+
+The functions of this unit give raw control of all the parameters of the FF-A
+calls beside providing basic validity checks for the parameters.
+
+Couple FF-A interfaces have the ability to receive a response which indicates
+an interrupt that is meant to be handled by the SP. All these functions call a
+common interrupt handler function which is defined in the FF-A API component.
+This interrupt handler function should be implemented by the upper layers (in
+fact it is implemented by the SP layer or libsp).
+
+FF-A memory descriptors
+'''''''''''''''''''''''
+
+The FF-A defines memory descriptors to provide information to the SPM about the
+referenced memory areas. These are used by memory transactions like sharing,
+lending, etc. This information covers various details like instruction and data
+access rights, the endpoints of the transaction, address and size of the area,
+and so on. Building and parsing memory transaction structures can be quite
+complex and this is what this component addresses.
+
+First of all it provides a type for describing buffers where the transaction
+descriptors should be built. Using this type provides safety against buffer
+overflows during the transaction build and parse processes.
+
+The transaction data consists of three main sections.
+
+1. A transaction descriptor should be added where the memory region attributes
+ are described.
+
+2. Multiple memory access descriptors should be added which specify access for
+ each receiver of the memory area.
+
+3. Addresses and sizes of the memory regions can be added.
+
+At this point the transaction data should be ready to passed to the SPM by
+invoking the suitable FF-A call.
+
+
+FF-A internal API
+-----------------
+
+The lowest layer implemented in libsp is responsible for wrapping FF-A layer
+calls into the SVC conduit. Practically this means an escalation of the
+exception level and invoking the SVC handler of the SPM with the suitable
+parameters passed in registers.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/index.rst b/docs/environments/index.rst
new file mode 100644
index 0000000..a244827
--- /dev/null
+++ b/docs/environments/index.rst
@@ -0,0 +1,16 @@
+Processing Environments
+=======================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ ffa/libsp
+ deployment-guides/fvp-deployment-guide.rst
+ deployment-guides/opteesp-deployment-guide.rst
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause