aboutsummaryrefslogtreecommitdiff
path: root/docs/environments/deployment-guides/opteesp-deployment-guide.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/environments/deployment-guides/opteesp-deployment-guide.rst')
-rw-r--r--docs/environments/deployment-guides/opteesp-deployment-guide.rst97
1 files changed, 97 insertions, 0 deletions
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 000000000..e71140fa8
--- /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