aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJulian Hall <julian.hall@arm.com>2020-11-25 03:07:21 +0100
committerGyörgy Szing <gyorgy.szing@arm.com>2021-01-28 00:06:35 +0000
commite76ade88c741bd1c052624082a869a60eebd420f (patch)
tree9547270318c9ae5539b40d8d9003e946d278e152
parent3924b1b22e28014e0905ce80cd4c4dae10a6bca5 (diff)
downloadtrusted-services-e76ade88c741bd1c052624082a869a60eebd420f.tar.gz
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
-rw-r--r--docs/conf.py5
-rw-r--r--docs/developer/arch-overview.rst79
-rw-r--r--docs/developer/b-test.rst6
-rw-r--r--docs/developer/build-instructions.rst140
-rw-r--r--docs/developer/deployments.rst49
-rw-r--r--docs/developer/docs-build.rst77
-rw-r--r--docs/developer/image/ServiceAccessProto.svg3
-rw-r--r--docs/developer/image/TSportabilityModel.svg3
-rw-r--r--docs/developer/image/TrustedServicesLayers.svg3
-rw-r--r--docs/developer/index.rst26
-rw-r--r--docs/developer/portability-model.rst211
-rw-r--r--docs/developer/project-structure.rst209
-rw-r--r--docs/developer/running-tests.rst48
-rw-r--r--docs/developer/service-access-protocols.rst202
-rw-r--r--docs/developer/service-descriptions/crypto-service-description.rst85
-rw-r--r--docs/developer/service-descriptions/index.rst14
-rw-r--r--docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml49
-rw-r--r--docs/developer/service-locator.rst169
-rw-r--r--docs/developer/software-requirements.rst38
-rw-r--r--docs/developer/uml/BuildFlow.puml55
-rw-r--r--docs/developer/uml/RpcSessionClassDiagram.puml20
-rw-r--r--docs/developer/uml/SecureServicesLayers.puml46
-rw-r--r--docs/developer/uml/ServiceDeployment.puml84
-rw-r--r--docs/developer/uml/ServiceLocationStrategyClassDiagram.puml24
-rw-r--r--docs/developer/uml/ServiceLocatorClassDiagram.puml37
-rw-r--r--docs/developer/writing-documentation.rst53
-rw-r--r--docs/environments/deployment-guides/fvp-deployment-guide.rst86
-rw-r--r--docs/environments/deployment-guides/opteesp-deployment-guide.rst97
-rw-r--r--docs/environments/ffa/libsp.rst132
-rw-r--r--docs/environments/index.rst16
-rw-r--r--docs/global_substitutions.txt6
-rw-r--r--docs/index.rst57
-rw-r--r--docs/overview/goals.rst43
-rw-r--r--docs/overview/index.rst15
-rw-r--r--docs/overview/introduction.rst69
-rw-r--r--docs/project/change-log.rst30
-rw-r--r--docs/project/coding-guidelines.rst73
-rw-r--r--docs/project/contributing.rst88
-rw-r--r--docs/project/glossary.rst35
-rw-r--r--docs/project/index.rst21
-rw-r--r--docs/project/license.rst4
-rw-r--r--docs/project/maintainers.rst6
-rw-r--r--docs/project/todo.rst22
-rw-r--r--docs/project/versioning_policy.rst47
-rw-r--r--docs/security/index.rst19
-rw-r--r--docs/standards/index.rst14
-rw-r--r--docs/standards/psa_certification.rst191
-rw-r--r--docs/uml/colors.puml30
-rw-r--r--docs/uml/libsp_functions.puml118
-rw-r--r--docs/uml/style-component.puml28
-rw-r--r--tools/b-test/Readme.rst6
51 files changed, 2973 insertions, 15 deletions
diff --git a/docs/conf.py b/docs/conf.py
index f9ccb6fca..e35a28ed1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
# -- Metadata about this file ------------------------------------------------
-__copyright__ = "Copyright (c) 2020 Arm Limited"
+__copyright__ = "Copyright (c) 2020-2021 Arm Limited and Contributors."
__license__ = "SPDX-License-Identifier: BSD-3-Clause"
# Configuration file for the Sphinx documentation builder.
@@ -102,8 +102,7 @@ autosectionlabel_maxdepth = 1
# -- Options for plantuml ----------------------------------------------------
plantuml_output_format = 'svg_img'
-
# -- Options for todo extension ----------------------------------------------
# Display todos
-todo_include_todos = True
+todo_include_todos = False
diff --git a/docs/developer/arch-overview.rst b/docs/developer/arch-overview.rst
new file mode 100644
index 000000000..d2f8c4d17
--- /dev/null
+++ b/docs/developer/arch-overview.rst
@@ -0,0 +1,79 @@
+Architecture Overview
+=====================
+
+The Trusted Services project provides a framework for developing applications that can be built and deployed in
+different secure processing environments and on different hardware platforms. The structure and conventions adopted
+are designed to maximize opportunities for component reuse. The project adopts a portability model based on the
+*ports and adapters* architectural pattern, which promotes loose coupling between an application
+and its environment. The model allows applications to be deployed in a diverse range of environments from full
+featured trusted OSs, such as OP-TEE, to bare metal secure partitions.
+
+For a more in-depth description of how the ports and adapters pattern is applied, see:
+:ref:`Portability Model`
+
+Service Model
+-------------
+
+Trusted services conform to a client/server model where service specific operations are invoked using an RPC mechanism.
+The realization of the RPC layer and any underlying messaging layer may vary between deployments but the service layer
+should be identical for every deployment of a particular service. The following diagram illustrates the common layered
+model and where standardization on layer interfaces and protocols will be aimed for.
+
+.. image:: image/TrustedServicesLayers.svg
+
+The layered service model is reflected in the project source tree where software components are organized by layer and role.
+Because components that perform the same role are inter-changeable, there is much flexibility to meet the needs of
+different deployments. For example:
+
+ - An instance of the secure storage service could be accessed by different types of client, each presenting
+ different upper edge APIs to suite the needs of different applications. Some different secure storage clients
+ could be:
+
+ - A filesystem driver that presents a filesystem mount for user-space access to stored objects.
+ - A client that presents the PSA Protected Storage API.
+
+ - Different types of secure storage provider are possible, each accessed using a common protocol. Some different
+ secure storage providers could be:
+
+ - A secure storage provider that uses an external RPMB serial flash device for storage.
+ - A secure storage provider that encrypts objects before passing them to a normal world agent to access
+ file-backed storage.
+
+ - Different RPC layers may be used to access services deployed in different secure processing environments.
+
+Service Deployments
+-------------------
+
+The ability to deploy trusted services over a range of secure processing environments allows a consistent view of
+services to be presented to clients, independent of the back-end implementation. For a particular service deployment, a
+concrete set of build-time and run-time dependencies and configurations must be defined. Representing each deployment
+in the project structure allows multiple deployments to be supported, each reusing a subset of shared components.
+The following diagram illustrates the dependencies and configurations that must be defined for a fully specified
+deployment.
+
+.. uml:: uml/ServiceDeployment.puml
+
+Currently supported deployments are listed here:
+:ref:`Deployments`
+
+Service Access Protocols
+------------------------
+
+As mentioned in the section on layering, trusted services are accessed by clients via an RPC layer. Independent of the
+mechanics of the RPC layer, a service access protocol is defined by:
+
+ - A supported set of operations, each qualified by an opcode.
+ - A set of request and response message parameter definitions, one for each operation.
+
+The main documentation page for service access protocols is here: :ref:`Service Access Protocols`.
+
+The trusted service framework can accommodate the use of arbitrary serializations for message parameters. So far,
+message protocols using Google Protocol Buffers and packed C structures have been defined.
+
+.. image:: image/ServiceAccessProto.svg
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/b-test.rst b/docs/developer/b-test.rst
new file mode 100644
index 000000000..4ef53c012
--- /dev/null
+++ b/docs/developer/b-test.rst
@@ -0,0 +1,6 @@
+.. include:: ../../tools/b-test/Readme.rst
+
+..
+ *Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+ SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/build-instructions.rst b/docs/developer/build-instructions.rst
new file mode 100644
index 000000000..5fe6c634a
--- /dev/null
+++ b/docs/developer/build-instructions.rst
@@ -0,0 +1,140 @@
+Build Instructions
+==================
+All trusted service builds use CMake to create native build files for building and installing service binaries
+and other build products. Details about the tools needed for building are specified here:
+:ref:`Software Requirements`.
+
+All top-level build files are located beneath the 'deployments' parent directory under a sub-directory
+for each deployment. For more information about the project directory structure, see:
+:ref:`Project Structure`.
+
+Build Flow
+----------
+All deployment builds follow a common flow that results in the creation of executable binaries or libraries
+and the installation of files into an output directory. Deploying the contents of the output directory into
+the target environment is handled in an environment specific way and is not part of the common build
+flow. The build flow conforms to the conventional CMake process where building takes place in to following
+two stages:
+
+ 1. Native build files, such as makefiles, are generated from CMake configuration files.
+ 2. Native build tools, such as make, are used to build and install items, ready for deployment.
+
+The following activity diagram illustrates the common deployment build flow. The green activity states
+lie outside of the common build flow. Environment specific instructions are provided for deploying into
+different environments:
+
+.. uml:: uml/BuildFlow.puml
+
+Building and Installing
+-----------------------
+When building from a clean environment where no generated build files exist, it is necessary to run
+the CMake command, specifying the source directory, the build directory and optionally, the install
+directory where build output is installed.
+
+To illustrate the steps involved, we will build the 'component-test' executable to run in the
+'linux-pc' environment. The built executable is a standalone program that uses the CppUTest
+framework to run a set of component level tests on components from within the project. For this
+example, it is assumed that we are building under Linux and 'make' is used as the native build tool.
+
+The described steps may be used for any of the deployments under the top-level *deployments* directory.
+
+Starting from the project root directory, change directory to the relevant deployment directory::
+
+ cd deployments/component-test/linux-pc
+
+Build file generation is performed using the CMake command. If no CMAKE_INSTALL_PREFIX path is
+specified, build output will be installed in the default location (*build/install*). To generate
+build files that install to the default location, use::
+
+ cmake -S . -B build
+
+To generate build files that install to an alternative location, use::
+
+ cmake -S . -B build -DCMAKE_INSTALL_PREFIX=<install_dir>
+
+Having successfully generated build files, the native build tool may be run to build and install
+files using::
+
+ cd build
+ make install
+
+In the above example, all build output is written to a sub-directory called 'build'. You
+are free to choose any location for build output.
+
+Dependencies on external components and in-tree built objects, such as libraries,
+are handled automatically by the build system during the *generating* phase. External components
+are fetched from the relevant source repository and built as part of the build context for the
+deployment binary being built. This allows deployment specific configuration and compiler options
+to be applied to the external component without impacting other builds. Dependencies on in-tree
+built libraries are handled in a similar manner.
+
+For information on running tests, see:
+:ref:`Running Tests`.
+
+For more information on deployments, see:
+:ref:`Deployments`.
+
+Installed build output files
+----------------------------
+On successfully completing the *building* phase of the build flow, a set of build output files are
+installed to the directory specified by CMAKE_INSTALL_PREFIX. The set of installed files will
+depend on the type of build and the environment in which the files will be deployed. The following
+table summarizes what files are installed for different typed of build during the *installing* phase
+of the build flow:
+
+.. list-table:: Example build output files
+ :header-rows: 1
+
+ * - Deployment type
+ - Environment
+ - Files installed
+ * - Binary executable
+ - linux-pc, arm-linux
+ - | *bin/* - program binary
+ * - Shared library
+ - linux-pc, arm-linux
+ - | *include/* - public header files
+ | *lib/* - shared library
+ | *lib/cmake/* - cmake target import file
+ * - SP image
+ - opteesp
+ - | *bin/* - stripped elf file for SP
+ | *lib/make* - OP-TEE helper makefile
+ * - SP collection
+ - opteesp
+ - | *bin/* - set of stripped elf files
+ | *lib/make/* - set of OP-TEE helper makefiles
+
+
+Deploying installed files
+-------------------------
+Having built and installed build output files to a known directory, further steps may be needed to
+deploy the files into the target processing environment. The nature of these steps will be different
+for different environments.
+
+To avoid overly complicating the common Trusted Services build system, details of how installed files
+are deployed into the target execution environment are handled separately and may rely on environment
+specific tools.
+
+Some example deployment methods are:
+
+ * A filesystem share exists between a build machine and the target machine. Files installed into the shared directory are
+ directly accessible by the target.
+ * Installed files are incorporated into a third-party build process e.g. OP-TEE.
+
+The following guides provide instructions on deploying to different environments:
+
+* :ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE`
+* :ref:`Deploying Programs on FVP`
+
+Batch Building
+--------------
+To support batching building of a set of deployments, a tool called b-test is included. For
+more information, see
+:doc:`b-test page <./b-test>`
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/deployments.rst b/docs/developer/deployments.rst
new file mode 100644
index 000000000..74fdeb3d1
--- /dev/null
+++ b/docs/developer/deployments.rst
@@ -0,0 +1,49 @@
+Deployments
+===========
+In the context of the Trusted Services project, a deployment represents a unit of functionality
+that is built for a specific environment. You can find out more about deployments here
+:ref:`Project Structure`.
+
+The following table lists currently supported deployments:
+
+.. list-table:: Supported deployments
+ :header-rows: 1
+
+ * - Deployment Name
+ - Environments
+ - Provides
+ - Used for
+ * - component-test
+ - linux-pc, arm-linux
+ - Standalone tests for components and integrations
+ - Test driven development and regression testing
+ * - ts-service-test
+ - linux-pc, arm-linux
+ - Service API level tests
+ - Tests services from perspective of client application
+ * - ts-demo
+ - linux-pc, arm-linux
+ - Demonstration client application
+ - Example user-space client application
+ * - libts
+ - linux-pc, arm-linux
+ - Provides standard client interface for locating services and establishing RPC sessions
+ - Client application development
+ * - crypto
+ - opteesp
+ - Crypto trusted service
+ - Production deployments
+ * - secure-storage
+ - opteesp
+ - Secure storage trusted service
+ - Production deployments
+ * - libsp
+ - opteesp
+ - FF-A interface library
+ - FF-A library used in secure partition environments
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/docs-build.rst b/docs/developer/docs-build.rst
new file mode 100644
index 000000000..3ae422434
--- /dev/null
+++ b/docs/developer/docs-build.rst
@@ -0,0 +1,77 @@
+Building Documentation
+======================
+
+To create a rendered copy of this documentation locally you can use the
+`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
+pages.
+
+If you are building the documentation for the first time then you will need to
+check that you have the required software packages, as described in the
+*Prerequisites* section that follows.
+
+Prerequisites
+-------------
+
+For building a local copy of the |TS| documentation you will need, at minimum:
+
+- GNUMake
+- Python 3 (3.5 or later)
+- PlantUML (1.2017.15 or later)
+
+You must also install the Python modules that are specified in the
+``requirements.txt`` file in the root of the ``docs`` directory. These modules
+can be installed using ``pip3`` (the Python Package Installer). Passing this
+requirements file as an argument to ``pip3`` automatically installs the specific
+module versions required.
+
+Example environment
+-------------------
+
+An example set of installation commands for Linux with the following assumptions:
+ #. OS and version: Ubuntu 18.04 LTS
+ #. `virtualenv` is used to separate the python dependencies
+ #. pip is used for python dependency management
+ #. `bash` is used as the shell.
+
+.. code:: shell
+
+ sudo apt install make python3 python3-pip virtualenv python3-virtualenv plantuml
+ virtualenv -p python3 ~/sphinx-venv
+ . ~/sphinx-venv/bin/activate
+ pip3 install -r requirements.txt
+ deactivate
+
+.. note::
+ More advanced usage instructions for *pip* are beyond the scope of this
+ document but you can refer to the `pip homepage`_ for detailed guides.
+
+.. note::
+ For more information on Virtualenv please refer to the `Virtualenv documentation`_
+
+Building rendered documentation
+-------------------------------
+
+From the ``docs`` directory of the project, run the following commands.
+
+.. code:: shell
+
+ . ~/sphinx-venv/bin/activate
+ make clean
+ make SPHINXOPTS=-W html
+ deactivate
+
+Output from the build process will be placed in:
+
+::
+
+ <tf-a CMF root>/docs/_build/html/
+
+--------------
+
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _pip homepage: https://pip.pypa.io/en/stable/
+.. _`Virtualenv documentation`: https://virtualenv.pypa.io/en/latest/
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/image/ServiceAccessProto.svg b/docs/developer/image/ServiceAccessProto.svg
new file mode 100644
index 000000000..aa7f9117a
--- /dev/null
+++ b/docs/developer/image/ServiceAccessProto.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="681px" height="331px" viewBox="-0.5 -0.5 681 331" content="&lt;mxfile host=&quot;confluence.arm.com&quot; modified=&quot;2020-10-05T19:50:28.353Z&quot; agent=&quot;Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0&quot; etag=&quot;Bzz9yr5hRQzs9jvCqYym&quot; version=&quot;12.7.1.1&quot; type=&quot;atlas&quot;&gt;&lt;mxAtlasLibraries/&gt;&lt;diagram id=&quot;Yb5y5pyupjcRv4pKJqIq&quot; name=&quot;Page-1&quot;&gt;7VjZbuM2FP0aA+1DDEqyJPsxXibTogOkcNt0ngpaupLYUKRA0Vu/vqRE7coKZ9wCozyEPNzPPZe81xNnlZ7uBM6SLzwEOrFReJo464ltWzN7rv5p5FwiC98AsSCh6dQAW/IPGBAZdE9CyDsdJedUkqwLBpwxCGQHw0LwY7dbxGl31QzHZkXUANsAUxh0eyChTEp07rZ6fwYSJ9XKFjItKa46GyBPcMiPLcjZTJyV4FyWpfS0AqrJq3gpx316orXemAAmXzPgTPh8c/f7WsLjr7cPm+TIf97d2OUsB0z35sD3gksecJqbXctzRYU6QKaLmkMQE2cZcSa3pt1S9TzDAWHxbzzTAFKIxLuKtZmp12xZsxK45zmRhDMFUYhUyzKRKTVTUrwD2uoRqMMWax9ASKLM9Euvw45LyVPVAVMSj464NQ1Sb3MZEUpXnHJRnNGJXP2nzyIFf4RWi1d85tQtvPwUPrSHMZFeGE4tyNjnDngKUpxVF9PqGKkYX7mxfAMcG+nVekraspsbEBu5x/XcjSJUwYjiDQJxBgLJQRxIAH8RzWuEA5hmWjIT26PaeDuhSrEu/VBIabePtPtDRFhpI+WEhMKPA3kJvmch6L1opRwTImGrBKVbj+pu6eriAmR7bo9sNCTbckfI9j6K69mA623JtQJXlOijXpu0Gxt1NTrK2phEP4w19xnWlAIPRF9W1+bN8f5rtHkD2gYkAQtv9ROqajwD1iVFcSHOfxoCi8pXXZm6VXV9ajeuz1XtRGQxbGq7pvq11dSM0pV6EAs/EX2+ohbiPCls96xxcr4XAbzsbhKLGOTLVyCEVaTwhKlbphy7NipMAMWSHLrxxZh5zQr3nGjHbzxw3pOS1ZNIeXAzrB0QDGbqvTd9rZXMDCZSmsDnVrdMd8if2XH9jFVXrd+JVFShnLIRc83q+/XtX0rf1nv17V9Z3+7/U989sVjOO+VtuW5vIvdD5D1zr6Du+cvqbmm5Tj066kKviZJTEoZ6xmUV/aenWGd60zK5sqd/79PsJ2b8aFmkeZYWfpECOnO9hm77DFiv6S2mRbCsIkNsIvYFGgnDEXYQHgvDl2sfITQMw6Piu8xjbc/saS849P0K6USHNdp2BBvV8MVf7cXA7q0g+wvkuU5nbbRhAQ9VKnYtUcgjf8DnjijQ1KtV4Q4tHgTgFvYbWNzxnIUTXih87b+dI2HYbPYtw7Dq8W5Z9A4YCCyhOGzwqKbds7KAlFU1THQWtRoYV5HQS5+7ZDLOoMe8gSqLmwT8SXuPBcrdUPrNCXs99yUc17d0VNm2sDMSZ6MRA/dfmcsZeJhBf7+qy6s6oiT746Uw5w3OXSdQ1a09HzH+t7+zrWFe/0oXZ2UgpUCT/SOKWbwv7vjvvv/81T7m+GMJ9jscX1Wbn23LiK758dvZ/As=&lt;/diagram&gt;&lt;/mxfile&gt;"><defs/><g><path d="M 230 0 L 270 0 L 270 14 L 450 14 L 450 180 L 230 180 L 230 14 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="10" pointer-events="all"/><path d="M 230 14 L 270 14" fill="none" stroke="#666666" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 197px; margin-left: 340px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; font-weight: bold; white-space: nowrap; ">Protocols</div></div></div></foreignObject><text x="340" y="209" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle" font-weight="bold">Protocols</text></switch></g><rect x="265" y="70" width="150" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 148px; height: 1px; padding-top: 100px; margin-left: 266px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">service_interface.proto<br />(Protobuf definition file)</div></div></div></foreignObject><text x="340" y="104" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">service_interface.proto...</text></switch></g><rect x="0" y="270" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 300px; margin-left: 1px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Service Client</div></div></div></foreignObject><text x="60" y="304" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Service Client</text></switch></g><rect x="560" y="270" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 300px; margin-left: 561px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Service Provider</div></div></div></foreignObject><text x="620" y="304" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Service Provider</text></switch></g><path d="M 30 270 L 30 110 Q 30 100 40 100 L 262.76 100" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><path d="M 256.88 103.5 L 263.88 100 L 256.88 96.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 650 270 L 650 110 Q 650 100 640 100 L 417.24 100" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><path d="M 423.12 96.5 L 416.12 100 L 423.12 103.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 562 92.5 L 600 127.16 L 562 161.83 L 562 142.16 C 496 142.17 442.5 212.83 442.5 300 C 442.5 196.26 496 112.17 562 112.16 Z" fill="#f0a30a" stroke="#bd7000" stroke-miterlimit="10" transform="rotate(90,521.25,196.25)" pointer-events="all"/><path d="M 155 288 L 525 288 L 525 270 L 560 300 L 525 330 L 525 312 L 155 312 L 155 330 L 120 300 L 155 270 Z" fill="#cce5ff" stroke="#36393d" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 300px; margin-left: 340px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: nowrap; ">Protobuf Message Encoding</div></div></div></foreignObject><text x="340" y="304" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Protobuf Message Encoding</text></switch></g><rect x="471.25" y="200" width="100" height="30" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 98px; height: 1px; padding-top: 215px; margin-left: 473px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Generate pack/unpack code in C</div></div></div></foreignObject><text x="473" y="219" fill="#000000" font-family="Helvetica" font-size="12px">Generate pack/un...</text></switch></g><path d="M 199.5 90 L 237.5 124.66 L 199.5 159.33 L 199.5 139.66 C 133.5 139.67 80 210.33 80 297.5 C 80 193.76 133.5 109.67 199.5 109.66 Z" fill="#f0a30a" stroke="#bd7000" stroke-miterlimit="10" transform="translate(0,193.75)scale(1,-1)translate(0,-193.75)rotate(-90,158.75,193.75)" pointer-events="all"/><rect x="120" y="200" width="120" height="30" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 118px; height: 1px; padding-top: 215px; margin-left: 122px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Generate pack/unpack code in native client language</div></div></div></foreignObject><text x="122" y="219" fill="#000000" font-family="Helvetica" font-size="12px">Generate pack/unpack...</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg> \ No newline at end of file
diff --git a/docs/developer/image/TSportabilityModel.svg b/docs/developer/image/TSportabilityModel.svg
new file mode 100644
index 000000000..e0635c552
--- /dev/null
+++ b/docs/developer/image/TSportabilityModel.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="471px" height="371px" viewBox="-0.5 -0.5 471 371" content="&lt;mxfile host=&quot;confluence.arm.com&quot; modified=&quot;2021-01-21T15:49:55.792Z&quot; agent=&quot;Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0&quot; etag=&quot;T4OmEHaxOAbJXEuewn-x&quot; version=&quot;12.7.1.1&quot; type=&quot;atlas&quot;&gt;&lt;mxAtlasLibraries/&gt;&lt;diagram id=&quot;Fh55IqWZiI4TxFe46PeK&quot; name=&quot;Page-1&quot;&gt;7Zpbc5s4FIB/jWe2D+4YZMf2Y25tZrbddSftNN2XjAwyaAuICvlCf/1KRsIg4ZikxgRv8xLpoAv6zjnSOTI9cB1u3lMY+x+Ji4KePXA3PXDTs21rZA35PyFJpQRYk0ziUexK2U5wj38iKRxI6RK7KCk1ZIQEDMdloUOiCDmsJIOUknW52YIE5Vlj6MkZBzvBvQMDZDT7il3mZ9LJqND6DmHPVzNbA/kkhKqxFCQ+dMm6IAK3PXBNCWFZKdxco0DQU1yyfu/2PM1fjKKI1elAfvzzJ/2azsm3VTL8Mr999B/Tvp2NsoLBUi74M10mDLlceI/oCjuIl2aUrLgaaM++CPhcV3NR8kTpDxjHAXYgwyR6I9fJUgWPLzkWRR9toEci3j5GFIeI8aFy6UyJOJGrtY8Zuo+hI7qtuU1xmc/CgNcsXnQx5UrGYqibhCwF4SuTg0SzQpShTUEkubxHhM9HU95EPgVSRdJIh7K63incmkiZX1B2bqRQGpmXj7zTAy9IVTxDLSNDLe2wXeAguCYBEUNGJELHwd0flnn3wcgADuwK4GDcFPALA/httMKURKFYps6er5OV4SWMku9IQ1VBDwbYE4AdPqxQ1JWgxv0nuJQPQuy6YppKbVGyjFwk1jE4jiby3Upqwh6bpj+ssvym9DA29ABdGAtUug7KLA7YdjN2nGNINZoFeqNT0pt0ml7FtntSetNO05u0TE+dhd3A1wevzHUtq9P42vZdywxku4SvdecFBr5ZANmC0NDgdzbBj32hhaF2y8GPSpafCvv5MDz13ceoecu1NNOdmqF7leWCxpjVSJVQ5F6KqwBhegFMEuyUUaENZg+F8jdhY29HsnazkSa3raSqEvG3fyhWCr1EdddtW1P99uqAp1zUQTWsg0HqIVbjJEauutrYo9MDOlMyivhWgFflC5EqRcoZZgSLnGmvyQwHmjFkS5fdijcY+kiT8kBgpA2UoTEG2hpWvu5fsDUzSzze6dKzwWL7d6TNTY9vTD+tyrAbu9GwzNykM+yGbbMzM5POsJu0zE5N1g12rw2emZR0B17bXqtYdRJe28eFbSYkBrwDuGASZz8ILfBGIG6SH88/NYBVV9qnjIvtOrnEWcTFylQOx8VyxN9x8ZHjYrtODvaSvPXYu5wGPN++DjhpYwm/XSOhaNRJrVM56bSmjypTOjsfHWo+ahjVHh/luodpoVksGiT73xhY2kE0HTz5Xnp77SsCXsje4Lgbhvkzn2H31CfhfJm0umH0tVPdrgiLTnuq18gE1YcBThrgyN3esx4gOM+i0A/zXACd7942Nv17yfgoqHnUQEM9td/WC0FVoHV01qBG/H4eEdS47uY8PdPNue0ACtTIds7DrS3Qvl//bzKjSU2/Vub3269f7tfj9Mt0Pftr/u8D++xfkk8f7+5oxdeVL7a0wTMs7eUWowKzV2sJ+oVTbUvQf3GfNhN+6xZnfJR7oL0Wrj83/ObV3QfFWfPdd9ng9j8=&lt;/diagram&gt;&lt;/mxfile&gt;"><defs/><g><path d="M 197.5 90 L 302.5 90 L 355 180 L 302.5 270 L 197.5 270 L 145 180 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" transform="rotate(90,250,180)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 178px; height: 1px; padding-top: 180px; margin-left: 161px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Provider<br />(application)</div></div></div></foreignObject><text x="250" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Provider...</text></switch></g><path d="M 157.5 25 L 342.5 25 L 435 185 L 342.5 345 L 157.5 345 L 65 185 Z" fill="none" stroke="#000000" stroke-miterlimit="10" transform="rotate(90,250,185)" pointer-events="all"/><rect x="230" y="305" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 315px; margin-left: 231px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Environment</div></div></div></foreignObject><text x="250" y="319" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Enviro...</text></switch></g><rect x="350" y="135" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="149" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="175" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="189" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="215" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="229" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="135" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="149" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="175" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="189" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="215" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="229" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="390" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Platform</div></div></div></foreignObject><text x="410" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Platfo...</text></switch></g><ellipse cx="25" cy="145" rx="25" ry="15" fill="transparent" stroke="#000000" pointer-events="all"/><path d="M 50 145 L 93.63 145" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 145 L 91.88 148.5 L 93.63 145 L 91.88 141.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="150" y="140" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="150" y="180" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="150" y="220" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="220" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="180" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="140" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="10" y="170" width="30" height="30" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 40 185 L 93.63 185" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 185 L 91.88 188.5 L 93.63 185 L 91.88 181.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><ellipse cx="375" cy="255" rx="15" ry="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 400 225 L 430 225 Q 440 225 440 235 L 440 245 Q 440 255 430 255 L 396.37 255" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 391.12 255 L 398.12 251.5 L 396.37 255 L 398.12 258.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 125 240 L 140 255 L 125 270 L 110 255 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 125.17 470 125.17 470 134.5 L 470 155.5 C 470 164.83 450 164.83 450 155.5 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 141.5 470 141.5 470 134.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 145 L 443.63 145" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 145 L 441.88 148.5 L 443.63 145 L 441.88 141.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 165.17 470 165.17 470 174.5 L 470 195.5 C 470 204.83 450 204.83 450 195.5 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 181.5 470 181.5 470 174.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 185 L 443.63 185" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 185 L 441.88 188.5 L 443.63 185 L 441.88 181.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 110 255 L 60 255 Q 50 255 50 245 L 50 235 Q 50 225 60 225 L 93.63 225" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 225 L 91.88 228.5 L 93.63 225 L 91.88 221.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg> \ No newline at end of file
diff --git a/docs/developer/image/TrustedServicesLayers.svg b/docs/developer/image/TrustedServicesLayers.svg
new file mode 100644
index 000000000..b57a65c69
--- /dev/null
+++ b/docs/developer/image/TrustedServicesLayers.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="1083px" height="379px" viewBox="-0.5 -0.5 1083 379" content="&lt;mxfile host=&quot;confluence.arm.com&quot; modified=&quot;2020-10-12T14:32:15.581Z&quot; agent=&quot;Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:81.0) Gecko/20100101 Firefox/81.0&quot; etag=&quot;NMyOFHADfPI-JQlNiOb1&quot; version=&quot;12.7.1.1&quot; type=&quot;atlas&quot;&gt;&lt;mxAtlasLibraries/&gt;&lt;diagram id=&quot;wNY_4wXUTk2zhrBGsPOK&quot; name=&quot;Page-1&quot;&gt;5Vpbd6I6FP41rnXOg7O4COpj8dJ22q5jaz22fYsQMTOBsELEy6+fBAMiYHV1vM2IDyU7N/J9e3/shFb0lje/pSCYPBEH4oqmOPOK3q5omto0Nf5HWBbSoqnmyuJS5Ejb2tBHSyiNirROkQPDjYaMEMxQsGm0ie9Dm23YAKVkttlsTPDmrAFw5YzK2tC3AYaFZkPksMnK2jAyre8gcifJzKoiazyQNJaGcAIcMsuY9E5Fb1FC2OrOm7cgFugluKz6dbfUpg9Goc/26UDu3/S+A+e2oVYHdwNj/r+nV+UoEcBTueAWRmJATelRYsMwRL7LCx0/QpT4XlwVr4YtEogomfoOFLOoFd2aTRCD/QDYonbGvYLbJszDsnqMMG4RTGjcV++Y4sftIaPkJ8zU1HStbdR5DQYjiHskRAwRn9fZ/Bkgb2RFkDLEmXrMNWBEzAkwckub38iKEWGMeOKRiM8yEyvxlT5SwrrOLUXIE/z42HCeMUkKbiHxIKML3kTWVrWG9AcZEdXUY2Zr/9ITp5lkfEs3pRFIn3bT0de08xvJfLkXzG4Gr8Fy5D18OB9jv3sTfuisWit4QR/aUwo/9QLln36v8++JvMHSJCl/lzeozT2cwVSP5QzLD/f5MUJGU3/oBt7351bTj0ok4ZVOQ8Yp1ZQ+pBGyhV8kMrGVfWU3+wcJJ3MTQa2IXxpxWfyOBp9WgO+l1xKAAYy5510cYI1zA6YXAHviggPcleQ8gsUloqbWTghb+8mcvfhDN2zMfgzf3eipsezsGaZcviOeQJ0fwTSh2x6nRv2U+G2L047vBARdgLTlETtloJYi9icEah6088dpvYBaASToOzdiqyLyEwx4smXH+QagrGjOwMVRoos3CW1ceBeFb0ZSbM+zle1FUpoj9paMwe8zvXhp3UkUkj5bqQnJlNpw9/uQr8aFbHc8QifZj20hOisYJTwmNgoxYCja3MWVkStn6K1ifi34eb2q5xxktfBeKhXdbSOp+QxFy420gqYwUuxt6cK/7oCNggOKVIRb7v2I2CBOk/MeyaONbTrbzgTaQ44julsUhmgJRvFQwnViNY2XalgVo53k8Bawf7qxPGSy7XF8lfrbp8GV14f0PEA+RyW75S59wSvftFr9IK6THHCsU/rNEch4HMKjMN28cqlRL0pCcvv8WpOv+0sKkpei4khHVpBk/o3zgSTD/C8I/1j5SALmouSjcQL5KD0FKu4orks+9EuWD9U8mH6UDHU4ASn1rOJeK7NzuHzt+DRark472MtoOgiUZzS1qoHx0MWtea3sOwLxPJFZ8jSTszYWe77f2hzmjorHhviVHRWb8VU8yV1dBzoPUnPhWS9uM9WyM/x87v+VbWYpAcUj/OsiQNXPzYBxXQxozQuLAPO68T9/ABRPuhICTCxe6SPK71xx16OEEZvg4s6BT4OCEO7mwgHhJP3KePyPghnmfeLDw1Bo5Bjck8D0o+HvMHhnWjXz4X5Ib9/d0atyOwlai5K3uEiVeNJfSb8pFCk79RGvsce5eNmXBPUQjm8N6s1h1LYYdX3w4N936GMZbH+18hiny314cf0PMqtcdf1/RnrnFw==&lt;/diagram&gt;&lt;/mxfile&gt;"><defs/><g><rect x="1" y="17" width="320" height="360" rx="48" ry="48" fill="#e6e6e6" stroke="#432d57" stroke-width="3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 318px; height: 1px; padding-top: 14px; margin-left: 2px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Client Processing Environment</div></div></div></foreignObject><text x="161" y="14" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Client Processing Environment</text></switch></g><rect x="471" y="17" width="610" height="360" rx="54" ry="54" fill="#e6e6e6" stroke="#b20000" stroke-width="3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 608px; height: 1px; padding-top: 14px; margin-left: 472px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Secure Processing Environment (SPE)</div></div></div></foreignObject><text x="776" y="14" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Secure Processing Environment (SPE)</text></switch></g><rect x="21" y="137" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 167px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Client</div></div></div></foreignObject><text x="161" y="171" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Client</text></switch></g><rect x="21" y="197" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 227px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">RPC Caller</div></div></div></foreignObject><text x="161" y="231" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">RPC Caller</text></switch></g><rect x="21" y="257" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 287px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Messaging Layer</div></div></div></foreignObject><text x="161" y="291" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Messaging Layer</text></switch></g><rect x="491" y="137" width="570" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 568px; height: 1px; padding-top: 167px; margin-left: 492px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Provider</div></div></div></foreignObject><text x="776" y="171" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Provider</text></switch></g><rect x="491" y="197" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 227px; margin-left: 492px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">RPC Endpoint</div></div></div></foreignObject><text x="631" y="231" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">RPC Endpoint</text></switch></g><rect x="491" y="257" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 287px; margin-left: 492px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Messaging Layer</div></div></div></foreignObject><text x="631" y="291" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Messaging Layer</text></switch></g><path d="M 307.37 227 L 484.63 227" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 302.12 227 L 309.12 223.5 L 307.37 227 L 309.12 230.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 489.88 227 L 482.88 230.5 L 484.63 227 L 482.88 223.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 218px; margin-left: 390px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Call Invocation</div></div></div></foreignObject><text x="390" y="221" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Call Invocation</text></switch></g><path d="M 307.37 166.98 L 484.63 166.52" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 302.12 167 L 309.11 163.48 L 307.37 166.98 L 309.13 170.48 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 489.88 166.5 L 482.89 170.02 L 484.63 166.52 L 482.87 163.02 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 157px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Service Ops</div></div></div></foreignObject><text x="391" y="161" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Service Ops</text></switch></g><path d="M 307.37 286.98 L 484.63 286.52" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 302.12 287 L 309.11 283.48 L 307.37 286.98 L 309.13 290.48 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 489.88 286.5 L 482.89 290.02 L 484.63 286.52 L 482.87 283.02 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 277px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Messaging</div></div></div></foreignObject><text x="391" y="281" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Messaging</text></switch></g><rect x="101" y="187" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 197px; margin-left: 102px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="161" y="201" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><rect x="101" y="247" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 257px; margin-left: 102px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="161" y="261" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><rect x="571" y="187" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 197px; margin-left: 572px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="631" y="201" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><rect x="571" y="247" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 257px; margin-left: 572px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="631" y="261" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><ellipse cx="391" cy="222" rx="60" ry="95" fill="transparent" stroke="#000000" stroke-dasharray="3 3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 124px; margin-left: 332px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common<br />Protocols</div></div></div></foreignObject><text x="391" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Common...</text></switch></g><rect x="791" y="197" width="270" height="120" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 268px; height: 1px; padding-top: 257px; margin-left: 792px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Backend Services</div></div></div></foreignObject><text x="926" y="261" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Backend Services</text></switch></g><rect x="861" y="187" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 197px; margin-left: 862px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="921" y="201" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg> \ No newline at end of file
diff --git a/docs/developer/index.rst b/docs/developer/index.rst
new file mode 100644
index 000000000..33a03cc00
--- /dev/null
+++ b/docs/developer/index.rst
@@ -0,0 +1,26 @@
+Developer Docs
+==============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ arch-overview
+ project-structure
+ portability-model
+ service-access-protocols
+ service-locator
+ deployments
+ service-descriptions/index
+ software-requirements
+ build-instructions
+ running-tests
+ docs-build
+ writing-documentation
+ b-test
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/portability-model.rst b/docs/developer/portability-model.rst
new file mode 100644
index 000000000..8305cb237
--- /dev/null
+++ b/docs/developer/portability-model.rst
@@ -0,0 +1,211 @@
+Portability Model
+=================
+
+Within the Trusted Services project, an environment represents the execution environment for an application such
+as a trusted service provider. Some example environments are:
+
+ - *opteesp* - Secure partition managed by OP-TEE.
+ - *opteeta* - TA running under OP-TEE with access to the Global Platform internal API.
+ - *hfsp* - Secure partition managed by Hafnium.
+
+An underlying TEE or SPM that manages a secure processing environment will have its own model for porting to different hardware.
+For example, OP-TEE has its own driver model that allows for alternative hardware drivers. In some cases, a secure processing
+environment will not provide native support for all hardware that an application depends on. To address this, the TS
+portability model allows:
+
+ - Application interfaces to be adapted to services natively provided by a secure processing environment if they are available.
+ - Adapting to platform provided drivers when no native environment support is available.
+
+Ports and Adapters Architecture
+-------------------------------
+
+An application is decoupled from any particular environment via a set of interfaces that reflect the needs of the application.
+This model conforms to the *ports and adapters* architectural pattern that aims to avoid tight coupling between application
+components and any particular environment. This pattern, also known as the *hexagonal architecture*, is often illustrated as
+a hexagonal cell with the application on the inside and the platform on the outside.
+
+The following diagram illustrates how ports and adapters is applied in the trusted services project to provide a model for
+application portability.
+
+.. image:: image/TSportabilityModel.svg
+
+The portability model has the following characteristics:
+
+ - The application is decoupled from the environment by a set of virtual interfaces (ports) that reflect the needs of the
+ application.
+ - Those interfaces are realized by a set of adapters that either use native environment services or platform provided
+ services.
+ - For a given environment, the set of adapters that realize interfaces used by an application will always be the same,
+ independent of the platform.
+ - A platform presents interfaces that conform to conventional driver and middleware abstractions such as block drivers and
+ filesystems.
+ - The set of platform interfaces that an application depends on is defined by the set of adapters used for a deployment of an
+ application in a particular environment. This can form the basis for a platform configuration.
+
+The need to use platform provided components will depend on the native features provided by an environment. For example, the
+*opteeta* environment represents the TA environment provided by OP-TEE. In its role as a trusted OS, OP-TEE provides access to
+an implementation of the Global Platform Internal Core API that provides services such as secure storage. Usage of any back-end
+hardware is handled by OP-TEE and its own OS components so no additional provision is needed. Bare metal environments such as
+secure partitions offer few native facilities so it may be necessary to map application interfaces to platform provided drivers.
+Mapping application interfaces to platform drivers is a way of extending the native services provided by an environment.
+
+The portability model allows for an arbitrary partitioning of hardware-backed services between native environment services and
+platform drivers.
+
+Portability Model Example
+-------------------------
+
+To illustrate usage of the portability model, consider deployments of the following two trusted services:
+
+ - fTPM based on the Microsoft TPM2.0 reference implementation.
+ - trustedfirmware.org Crypto service based on the Mbed TLS library.
+
+The Microsoft TPM2.0 reference and Mbed TLS both define their own platform interfaces to allow for platform specific
+implementations of features such as roll-back protected storage and entropy. Although some interfaces are similar between the
+two implementations, they are not the same. These interfaces are classed as ports within the ports and adapters architecture.
+To simplify the example, just the entropy platform dependency is considered. Both fTPM and Crypto service providers need access
+to a cryptographic grade RNG to support key generation. How the RNG is realized will depend on:
+
+ - What facilities the environment natively provides.
+ - What other trusted services are available on the device.
+ - Whether the environment allows for platform specific access to hardware.
+ - Availability of a spare hardware TRNG instance.
+
+Adapters will be responsible for adapting both fTPM and Crypto views of an entropy source to a suitable realization.
+Some example adapters:
+
+fTPM adapters that realize MS entropy interface (port)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
+ - *Adapts to crypto service* - Uses crypto service generate_random operation
+ - *Adapts to TEE API* - Uses native TEE OS
+ - *Adapts to TRNG* - Uses platform TRNG hardware
+
+Crypto adapters that realize Mbed TLS entropy source interface (port)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+ - *Adapts to fTPM* - Uses TPM2 getrandom command
+ - *TEE API* - Uses native TEE OS
+ - *TRNG* - Uses platform TRNG hardware
+
+The above examples reveal that for a given environment, a port may be realized by more than one type of adapter. For example, an
+fTPM deployed within a secure partition could source entropy from either TRNG hardware or from the Crypto service. This
+ambiguity may be resolved by various strategies such as:
+
+ 1. Allow a service profile to be applied at build time that defines a core set of mandatory trusted services. A build-time
+ selection of alternative adapters is made, based on available core services.
+ 2. A built image for a trusted service deployment to a particular environment includes the superset of adapters that could be
+ used. A runtime configuration is applied, that specifies which adapters to use.
+
+Providing Platform Firmware
+---------------------------
+
+A goal of the TS project is to reduce barriers to deploying trusted services on different hardware platforms. To this end,
+build-time and run-time coupling between TS project and platform components should be minimized. Platform providers should be
+free to make any of the following choices:
+
+ - Reuse existing drivers and driver frameworks (e.g. from tf-a, an RTOS, CMSIS).
+ - Provide platform components as part of a BSP.
+ - Maintain platform components in separate repos.
+ - Operate independent test, bug reporting and release processes for platform components.
+ - Control the logical organization and naming of different platforms within the TS project.
+ - Maintain whatever platform configuration files that are needed within the provider's sub-tree within the TS project.
+
+The platform top-level directory within the TS project provides a structure that allows platform specific components to be
+contributed by different providers. Different providers are represented beneath the platform/providers directory. The virtual
+platform interfaces used by some adapters are defined under platform/interface. The directory structure beneath a platform
+provider's parent is organized to reflect the provider's own naming scheme for different hardware. Supported platforms are each
+represented by a leaf sub-directory within the provider's subtree.
+
+For Arm provided platforms, the structure will look something like this::
+
+ platform
+ |-- interface
+ |-- providers
+ |--arm
+ |-- corstone700
+ |-- fvp
+ |-- fvp_base_aemva
+ |-- fvp_base_revc-2xaemv8a
+ |-- platform.cmake
+
+Under each platform leaf directory is a file called *platform.cmake*. This file implements the common configuration and build
+interface that will be used during the deployment build process. How this interface is realized is entirely down to the
+platform provider. An implementation will do things like setting configuration variables for SoC, board and driver selection.
+Any additional files needed to support platform configuration and build may be included within the platform provider's sub-tree.
+
+For product developers who want to define and maintain their own private platforms, it should be possible to override the
+default platform/providers directory path to allow an alternative sub-tree to be used. A product developer is free to organize
+a private sub-tree in any way that suites their needs.
+
+Although the TS project structure doesn't mandate it, platform specific firmware is likely to live outside of the TS project.
+The ability to reuse existing drivers and driver frameworks is important for promoting adoption across hardware from different
+vendors. Board and silicon vendors may reuse existing CI and project infrastructure for platform components that they maintain.
+
+Some special platforms are provided by the TS project itself. These are represented beneath the *ts* provider.
+Current TS platforms are:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10, 90
+
+ * - TS Platform
+ - Purpose
+ * - ts/vanilla
+ - | A platform that never provides any drivers. The ts/vanilla platform should be used when an environment provides its own
+ | device framework and no additional drivers need to be provided by the platform. An attempt to build a deployment with
+ | platform dependencies on the vanilla platform will result in a build-time error. The vanilla platform is selected by
+ | default at build-time if no explicit platform has been specified.
+ * - ts/mock
+ - | A platform that provides a complete set of drivers that may be selected when building any deployment. The platform uses
+ | mock drivers that don't offer functionality suitable for production builds. The mock platform is useful for CI build
+ | testing of deployments with platform dependencies. You should always expect a deployment with platform dependencies to
+ | build when TS_PLATFORM=ts/mock.
+
+Determining a Platform Configuration for a Deployment
+-----------------------------------------------------
+
+The TS project supports building and installing an application image into different environments that could be hosted on
+different hardware platforms. A platform is characterized by SoC and board-level hardware and possibly by OS type components
+such as device drivers and middleware. To deploy an application that depends on platform drivers, you need to tie-down:
+
+ - *Application name* - such as the name of the service e.g. crypto, secure-storage, attestation, tpm.
+ - *Environment* - the environment in which the application will run e.g. bare metal secure partition, Global Platform TEE,
+ Trusty TEE, microcontroller RTOS.
+ - *Platform* - the hardware platform that hosts the environment.
+
+The following example illustrates how these parameters are specified via the deployment build command line::
+
+ cd trusted-services/deployments/crypto/opteesp
+ cmake -S . -B build -DTS_PLATFORM=arm/fvp/fvp_base_revc-2xaemv8a
+
+The combination of <application name> + <environment> allows a set of build-time platform dependencies to be generated, based on
+the set of adapter components used for the deployment. This information is passed via the platform build interface to the
+platform.cmake file for the specified platform via a CMake target property called TS_PLATFORM_DRIVER_DEPENDENCIES. The
+translation of the platform dependency information to a suitable build configuration is handled by the platform.cmake file for
+the selected platform. This separation gives a platform provider the freedom to use their own configuration conventions when
+reusing existing drivers.
+
+To allow for out-of-tree platform definitions, the root path for platform definitions may be modified by providing an
+alternative value for TS_PLATFORM_ROOT. Both TS_PLATFORM and TS_PLATFORM_ROOT may be set via the CMake command line or using
+environment variables.
+
+Adapters
+--------
+
+As described above, the role of an adapter conforms to the Ports and Adapters pattern. With reference to the hexagonal cell
+representation, an adapter implements an application defined inside interface and adapts it to either an environment interface
+or an outside platform interface. Within the TS project, adapters are treated like any other software component and may be
+reused whenever appropriate. However, because an adapter implements an application defined interface, adapter implementations
+will tend to be tied to a particular application or component. The complexity of adapter implementations can vary a lot and
+will depend on how closely an inside interface matches either an outside interface or an environment interface.
+
+The collection of adapters used for a deployment is defined by the environment specific build file for a deployment. Deployment
+of the same service into a different environment may result in a different set of adapters being used. As each adapter is
+treated as a separate component, a separate component.cmake file exists for each adapter. When an adapter depends on one or
+more platform interfaces, the dependency must be declared in the adapter's component.cmake file. This information forms the
+basis for the platform build configuration.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/project-structure.rst b/docs/developer/project-structure.rst
new file mode 100644
index 000000000..b070510d8
--- /dev/null
+++ b/docs/developer/project-structure.rst
@@ -0,0 +1,209 @@
+Project Structure
+=================
+
+This page describes the directory and repository structure for the trusted services project.
+
+Top-Level Project Organization
+------------------------------
+The project is organized under the following top-level directories::
+
+ project
+ |-- docs
+ |-- deployments
+ |-- environments
+ |-- platforms
+ |-- components
+ |-- external
+ |-- protocols
+ |-- tools
+
+Top-level directories are used to organize project files as follows:
+
+docs
+''''
+
+The home for project documentation source.
+
+deployments
+'''''''''''
+
+A deployment represents the build instance of a service (or in fact any unit of functionality) for a particular
+environment. For each deployment, there is a single deployable output, usually a binary executable. The
+deployment is concerned with configuring and building a particular set of components to run in a particular
+environment. For each supported deployment, there is a leaf sub-directory that lives under a parent. The
+parent directory identifies what's being deployed while the leaf sub-directory identifies where it is being
+deployed. The following example illustrates how the 'what' and 'where' are combined to form fully defined
+deployments::
+
+ deployment-name = <descriptive-name>/<environment>
+
+ deployments
+ |-- secure-storage/opteesp
+ |-- crypto/opteesp
+ |-- ts-demo/arm-linux
+ |-- component-test/posix-x86
+ |-- ts-lib/posix-x86
+
+The trusted services project uses CMake to configure and generate build files. A CMakeLists.txt file exists
+for each deployment to define the set of components, any deployment specific configuration and anything
+environment specific. Each deployment leaf directory also holds a source file that defines the main entry
+point to allow a particular set of components to be initialized before entering the application that implements
+the core functionality of software being deployed.
+
+The directory structure for deployments supports inheritance from the deployment parent to promote reuse of
+common definitions and initialization code. For example, deployments of the secure-storage service for
+different environments are likely to have similarities in terms of the set of components used and in subsystem
+initialization code. To avoid duplication between deployments, common cmake and source files may be located
+under the deployment parent. This is illustrated in the following::
+
+ deployments
+ |-- secure-storage
+ |-- common.cmake <-- Common cmake file
+ |-- service_init.c <-- Common initialization code
+ |-- opteesp
+ |-- CMakeLists.txt <-- Includes ../common.cmake to inherit common definitions
+ |-- opteesp_service_init.c
+
+environments
+''''''''''''
+
+An environment represents the execution context in which a built image runs. There are different environments
+represented in the project structure, one for each supported isolated execution context. Files related to a
+particular environment live under a sub-directory whose name describes the environment. For example:
+
+ - opteesp An S-EL0 secure partition hosted by OP-TEE
+ - arm-linux Linux user-space, cross compiled for Arm.
+ - linux-pc Native PC POSIX environment
+
+Files related to an environment will tend to live outside of the project tree and will need to be imported
+in some way. How this is handled will depend on the environment. An environment will generally provide the
+following:
+
+ - Environment specific libraries that have been externally built.
+ - Public header files for libraries.
+ - An install method that takes a deployment image and installs it in the environment.
+ - Compiler configuration
+
+A deployment will include an environment specific build file (see above) that defines the list of environment
+specific components used for a deployment into a particular environment.
+
+platforms
+'''''''''
+
+For some deployments, an environment may not provide access to all hardware backed services needed by an
+application. Files under the platforms directory are concerned with configuring and building platform specific
+code that extends the capabilities of an environment. Details of how this works are described in the:
+:ref:`Portability Model`
+
+components
+''''''''''
+
+Source code lives under the components directory, organized as reusable groups of source files. A component
+is the unit of reuse for code that may be combined with other components to realize the functionality needed
+for a deployment. Creating a new deployment should be just a case of selecting the right set of components
+to provide the required functionality for the target environment. Some components may depend on other
+components and others may only make sense in a particular environment.
+
+The components sub-tree has an organization that reflects the layered model where service components are
+kept separate from RPC components and so on. There is also a separation between client components and service
+provider components. The following illustrates this::
+
+ components
+ |-- service
+ | |-- common
+ | | |-- test
+ | |-- secure-storage
+ | | |-- client
+ | | |-- provider
+ | | |-- test
+ | |-- crypto
+ | | |-- client
+ | | |- component.cmake
+ | | |-- provider
+ |-- rpc
+ | |-- common
+ | |-- ffarpc
+ | | |-- caller
+ | | |-- endpoint
+
+Each leaf directory under the components parent includes a cmake file called component.cmake. This is used to
+define all files that make up the component and any special defines that are needed to build it. A deployment
+CMakeLists.txt just needs to reference the required set of components. No details of the component internals
+are reflected in the deployment CMakeLists.txt file.
+
+Test components
+'''''''''''''''
+
+Test code is treated in exactly the same as any other source code and is organized into components to achieve
+the same reuse goals. To create a deployment intended for testing, you select an appropriate set of components
+where some happen to be test components. By convention, test components live in sub-directories called test.
+Test directories are located at the point in the components sub-tree that reflects the scope of tests. In the
+above example, two test sub-directories are illustrated. The locations of the test component directories imply
+the following about the scope of the tests::
+
+ components
+ |-- service
+ | |-- common
+ | | |-- test <-- Tests for the common service component
+ | |-- secure-storage
+ | | |-- client
+ | | |-- provider
+ | | |-- test <-- Service level tests for the secure-storage service
+
+If it is necessary to componentize tests further, sub-directories under the test directory may be used, say
+for different classes of test. e.g::
+
+ components
+ |-- service
+ |-- common
+ |-- test
+ |-- unit
+ |-- fuzz
+
+external
+''''''''
+
+Code that originates from other open source projects that needs to be built as part of trusted service
+deployments is represented by directories beneath the external top-level directory. External components
+are generally fetched from the source repo during the CMake build process. During the build for a particular
+deployment, a deployment specific configuration may be applied to an external component. A CMake file under
+each external component directory is responsible for fetching and building the external component::
+
+ external
+ |-- CppUTest
+ | |-- CppUTest.cmake
+ | |-- cpputest-cmake-fix.patch
+ |-- mbed-crypto
+ |-- nanopb
+
+protocols
+'''''''''
+
+The protocols directory holds protocol definition files to allow clients to use trusted services. Ideally,
+the service access protocol should be formally defined using an interface description language (IDL) that
+provides a programming language neutral definition of the service interface. The protocols directory
+structure accommodates protocol definitions using different definition methods. Where a service access
+protocol has been defined using an IDL with language compilation support, code may be generated from the
+interface description to allow RPC request and response parameters to be serialized and deserialized in a
+compatible way between service clients and providers. The protocols sub-tree is organized as follows::
+
+ protocols
+ |-- service
+ | |-- common
+ | |-- crypto
+ | | |-- packed-c <-- C structure based definitions
+ | | |-- protobuf <-- Protocol Buffers definitions
+ | |-- secure-storage
+ | |-- packed-c
+
+tools
+'''''
+
+The project directory structure includes a tools directory for holding general purpose tools components
+to support activities such as build and test.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/running-tests.rst b/docs/developer/running-tests.rst
new file mode 100644
index 000000000..be0e82ab9
--- /dev/null
+++ b/docs/developer/running-tests.rst
@@ -0,0 +1,48 @@
+Running Tests
+=============
+
+
+
+Running component tests
+-----------------------
+On successfully completing the steps above, a binary executable called 'component-test'
+will have been created. Because this deployment targets the linux-pc environment, the
+executable may be run as a native application. The application uses the stock CppUtest
+command line test runner.
+
+To run component tests, use::
+
+ ./component-test -v
+
+ Typical verbose output:
+ TEST(PackedCprotocolChecks, checkTsStatusCodes) - 0 ms
+ TEST(InternalTrustedStorageTests, storeNewItem) - 0 ms
+ TEST(E2EcryptoOpTests, generateRandomNumbers) - 2 ms
+ TEST(E2EcryptoOpTests, asymEncryptDecrypt) - 4 ms
+ TEST(E2EcryptoOpTests, signAndVerifyHash) - 40 ms
+ TEST(E2EcryptoOpTests, exportAndImportKeyPair) - 18 ms
+ TEST(E2EcryptoOpTests, exportPublicKey) - 7 ms
+ TEST(E2EcryptoOpTests, generatePersistentKeys) - 39 ms
+ TEST(E2EcryptoOpTests, generateVolatileKeys) - 20 ms
+ TEST(CryptoFaultTests, randomNumbersWithBrokenStorage) - 0 ms
+ TEST(CryptoFaultTests, persistentKeysWithBrokenStorage) - 9 ms
+ TEST(CryptoFaultTests, volatileKeyWithBrokenStorage) - 8 ms
+ TEST(PocCryptoOpTests, checkOpSequence) - 13 ms
+ TEST(CryptoMsgTests, SignHashOutMsgTest) - 0 ms
+ TEST(CryptoMsgTests, SignHashInMsgTest) - 0 ms
+ TEST(CryptoMsgTests, ExportPublicKeyOutMsgTest) - 1 ms
+ TEST(CryptoMsgTests, ExportPublicKeyInMsgTest) - 0 ms
+ TEST(CryptoMsgTests, GenerateKeyInMsgTest) - 0 ms
+ TEST(ServiceFrameworkTests, serviceWithOps) - 0 ms
+ TEST(ServiceFrameworkTests, serviceWithNoOps) - 0 ms
+ TEST(TsDemoTests, runTsDemo) - 71 ms
+
+ OK (21 tests, 21 ran, 159 checks, 0 ignored, 0 filtered out, 233 ms)
+
+
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-access-protocols.rst b/docs/developer/service-access-protocols.rst
new file mode 100644
index 000000000..4161f0d15
--- /dev/null
+++ b/docs/developer/service-access-protocols.rst
@@ -0,0 +1,202 @@
+Service Access Protocols
+========================
+
+A trusted service is accessed by calling service-specific methods via an RPC mechanism. The set of callable methods forms the
+public interface exposed by a service. This section is concerned with interface conventions and protocols used for serializing
+method parameters and return values. It is anticipated that there will be a need to support different parameter serialization
+schemes to suite different needs. The project accommodates this with the following:
+
+ - The Protocols directory structure allows for different protocol definitions for the same service.
+ - Message serialization code is decoupled from service provider code using an abstract 'serializer' interface. Alternative
+ concrete serializers may provide implementations of the interface.
+
+RPC Session
+-----------
+
+Before a client can call trusted service methods, an RPC session must be established where an association is made between an RPC
+Caller and a call endpoint that corresponds to the required service provider instance. To establish the session, the client
+must provide:
+
+ - An identifier for the service provider instance.
+ - Any client credentials that allow RPC layer access control to be applied if needed.
+
+.. uml:: uml/RpcSessionClassDiagram.puml
+
+Once the RPC session is established, the client may call service methods via an abstract RPC Caller interface that takes the
+following parameters:
+
+ - The opcode that identifies the method to call.
+ - A buffer for the serialized method parameters.
+ - A buffer for the serialized return values.
+
+A deployment independent interface for locating services and establishing RPC sessions is described here: :ref:`Service Locator`
+
+Status Codes
+------------
+
+On returning from a request to invoke a service method, two status codes are returned as follows:
+
+ - *RPC status* - A generic status code that corresponds to the RPC call transaction. RPC status codes are standardized across
+ all services.
+ - *Operation status* - a service specific status code.
+
+Separation of status codes by layer allows service specific status codes to be accommodated while keeping RPC status codes
+common.
+
+A client should only check the returned operation status if the returned RPC status value is RPC_CALL_ACCEPTED. All other RPC
+status values indicate that an error occurred in delivering the RPC request. An RPC status of RPC_CALL_ACCEPTED does not
+indicate that the service operation was successful. It merely indicates that the request was delivered, a suitable handler was
+identified and the request parameters were understood.
+
+Service Access Protocol Definition Conventions
+----------------------------------------------
+
+A service access protocol defines the following:
+
+ - Opcodes used for identifying service methods.
+ - Request parameters for each method.
+ - Response parameters for method return values.
+ - Operation status code.
+
+Details of how public interface definition files for trusted services are organized, see: :ref:`Project Structure`
+
+It is possible that for certain deployments, it will be necessary to customize which parameter encoding scheme is used. Many
+schemes are possible such as Protocol Buffers, CBOR, JSON, TLV, TPM commands or packed C structures. To make scheme
+customization straight forward, serilize/deserialize operations should be encapsulated behind a common interface to decouple
+service provider code from any particular serialization scheme. A section below describes a pattern for achieving this.
+
+Service Namespace
+'''''''''''''''''
+
+Definitions that form a service access protocol should live within a namespace that is unique for the particular service. Using
+a namespace for service definitions avoids possible clashes between similarly named definitions that belong to different
+services. How the namespace is implemented depends on how the access protocol is defined. For example, the Protocol Buffers
+definitions for the crypto service all live within the ts_crypto package. The recommended convention for forming a trusted
+service namespace is as follows::
+
+ ts_<service_name>
+
+ e.g.
+ ts_crypto
+ ts_secure_storage
+
+Language Independent Protocol Definitions
+'''''''''''''''''''''''''''''''''''''''''
+
+By defining service access protocols using an interface description language (IDL) with good support for different programming
+languages, it should be straight forward to access trusted services from clients written in a range of languages. On Arm
+Cortex-A deployments, it is common for user applications to be implemented using a range of languages such as Go, Python or
+Java. Rather than relying on a binding to a C client library, native client code may be generated from the formal protocol
+definition files. Initial protocol definitions use Google Protocol Buffers as the IDL. The project structure allows for use of
+alternative definition schemes and serializations.
+
+Opcode Definition
+`````````````````
+
+Opcodes are integer values that identify methods implemented by a service endpoint. Opcodes only need to be unique within the
+scope of a particular service. The mapping of opcode to method is an important part of a service interface definition and
+should be readily available to clients written in a variety of programming languages. For a Protocol Buffers based definition,
+opcodes are defined in a file called::
+
+ opcodes.proto
+
+For example, for the Crypto trusted service, the Protocol Buffers opcode definitions are in::
+
+ protocols/service/crypto/protobuf/opcodes.proto
+
+Alternative definitions for light-weight C clients using the packed-c scheme are in::
+
+ protocols/service/crypto/packed-c/opcodes.h
+
+Parameter Definition
+````````````````````
+
+The convention used for serializing method parameters and return values may be specific to a particular service. The definition
+file will include message definitions for both request and response parameters. Common objects that are used for multiple
+methods should be defined in separate files. When using Protobufs, the following naming convention for method parameter files
+should be used::
+
+ <method_name>.proto
+
+For example, the Crypto export_public_key method is defined in a file called::
+
+ protocols/service/crypto/protobuf/export_public_key.proto
+
+RPC Status Codes
+````````````````
+
+Generic RPC status code definitions using different definition schemes are defined here::
+
+ protocols/rpc/common/protobuf/status.proto
+ protocols/rpc/common/packed-c/status.h
+
+Service Status Codes
+````````````````````
+
+Service specific status code definitions using different definition schemes are defined here (using crypto service as an
+example)::
+
+ protocols/service/crypto/protobuf/status.proto
+ protocols/service/crypto/packed-c/status.h
+
+Status code definitions may also be shared between services. For example, services that conform to PSA API conventions will use
+standardized PSA status codes, defined here::
+
+ protocols/service/psa/protobuf/status.proto
+ protocols/service/psa/packed-c/status.h
+
+Use of Protocol Buffers
+-----------------------
+
+When Protocol Buffers is used for protocol definition and parameter serialization, the following conventions have been adopted.
+
+.proto File Style Guide
+'''''''''''''''''''''''
+
+The style of the .proto files should follow Google's Protocol Buffers Style Guide.
+
+Protocol Buffer Library for Trusted Services
+''''''''''''''''''''''''''''''''''''''''''''
+
+Protocol Buffers standardizes how service interfaces are defined and the on-wire encoding for messages. Because of this, service
+clients and service providers are free to use any conformant implementation. However for trusted services that may be deployed
+across a range of environments, some of which may be resource constrained, a lightweight library should be used for C/C++ code
+that implement or use trusted services. For this purpose, Nanobp (https://github.com/nanopb/nanopb) should be used.
+
+Serialization Protocol Flexibility
+----------------------------------
+
+Many different serialization protocols exist for encoding and decoding message parameters. Hard-wiring a particular protocol
+into a trusted service provider implementation isn't desirable for the following reasons:
+
+ - Depending on the complexity of serialization operations, mixing serialization logic with protocol-independent code makes
+ trusted service provider code bigger and more difficult to maintain.
+ - Different protocols may be needed for different deployments. It should be possible to make a build-time or even a
+ run-time selection of which protocol to use.
+ - The number of supported serializations protocols is likely to grow. Adding a new protocol shouldn't require you to make
+ extensive code changes and definitely shouldn't break support for existing protocols.
+
+These problems can be avoided by implementing protocol specific operations behind a common interface. Serialize/deserialize
+operations will have the following pattern::
+
+ int serialize_for_method(msg_buffer *buf, in args...);
+ int deserialize_for_method(const msg_buffer *buf, out args...);
+
+To extend a service provider to support a new serialization encoding, the following steps are required:
+
+ 1. Define a new encoding identifier string if a suitable one doesn't exist. Currently used identifiers are protobuf and
+ packed-c. The identifier will be used as a directory name so it needs to be filename-friendly. Some likely candidate
+ identifiers could be cbor and json.
+ 2. Add a new RPC encoding ID to *protocols/rpc/common/packed-c/encoding.h*. This is used by a caller to identify the encoding
+ used for RPC parameters. This is analogous to the content-type header parameter used in HTTP.
+ 3. Under the protocols parent directory, add a new access protocol definition for the service that needs extending. This will
+ be a representation of existing service access protocols but using a definition notation compatible with the new encoding.
+ 4. Add a new serializer implementation under the service provider's serializer directory e.g. for the crypto service -
+ *components/service/crypto/provider/serializer*.
+ 5. Add registration of the new serializer to any deployment initialization code where the new encoding is needed.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-descriptions/crypto-service-description.rst b/docs/developer/service-descriptions/crypto-service-description.rst
new file mode 100644
index 000000000..717c73b55
--- /dev/null
+++ b/docs/developer/service-descriptions/crypto-service-description.rst
@@ -0,0 +1,85 @@
+Crypto Service Description
+==========================
+Service Overview
+----------------
+The Crypto service provides a rich set of cryptographic operations with the backing
+of a private key store. Clients identify keys using opaque key handles, enabling
+cryptographic operations to be performed without exposing key values beyond the
+boundary of the service's secure processing environment. This pattern underpins
+the security guarantees offered by the Crypto service.
+
+The set of supported operations is aligned to the PSA Crypto API. C API functions
+are invoked by clients using the Crypto service access protocol. All types and values
+defined by the PSA Crypto C API are projected by the Crypto access protocol. The
+one-to-one mapping between the C API and Crypto access protocol allows developers
+to use PSA Crypto documentation and examples to understand details of the protocol.
+
+Supported operations fall into the following categories:
+
+ * Key lifetime management
+ * Message signing and signature verification
+ * Asymmetric encryption/decryption
+ * Random number generation
+
+Service Provider Implementation
+-------------------------------
+The default crypto service provider uses the Mbed Crypto library to implement backend
+operations. The following diagram illustrates the component dependencies in the crypto
+service provider implementation (note that there are many more handlers than
+illustrated):
+
+.. uml:: uml/CryptoProviderClassDiagram.puml
+
+The packages illustrated reflect the partitioning of the code into separate directories.
+Functionality is partitioned as follows:
+
+Crypto Provider
+'''''''''''''''
+Implements the set of handlers that map incoming RPC call requests to PSA Crypto API
+function calls. A separate handler function exists for each operation supported by the
+service.
+
+Crypto Serializer
+'''''''''''''''''
+Incoming call request parameters are de-serialized and response parameters serialized
+by a serializer. The trusted services framework allows for the use of alternative
+serializers to support different parameter encoding schemes.
+
+Mbed Crypto
+'''''''''''
+All cryptographic operations are handled by an instance of the Mbed Crypto library.
+The library is built with a specific configuration that creates dependencies on the
+following:
+
+ * PSA ITS API for persistent key storage
+ * External entropy source
+
+Secure Storage
+''''''''''''''
+Persistent storage of keys is handled by an instance of the Secure Storage service.
+The service is accessed via a client that presents the PSA ITS API at its upper edge.
+This is needed for compatibility with Mbed Crypto. As long as it meets security
+requirements, any Secure Storage service provider may be used. An RPC session between
+the Crypto and Secure Storage service providers is established during initialization
+and is maintained for the lifetime of the Crypto service provider.
+
+Entropy Source
+''''''''''''''
+Certain cryptographic operations, such as key generation, require use of a
+cryptographically secure random number generator. To allow a hardware TRNG to be used,
+the Mbed Crypto library is configured to use an externally provided entropy source.
+Any deployment of the service provider must include an implementation of the following
+function::
+
+ int mbedtls_hardware_poll(void *data, unsigned char *output, size_t len, size_t *olen)
+
+For production deployments, an implementation of this function should be provided that
+obtains the requested bytes of entropy from a suitable source. To allow the Crypto
+service to be used where no hardware backed implementation is available, a software
+only implementation is provided.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-descriptions/index.rst b/docs/developer/service-descriptions/index.rst
new file mode 100644
index 000000000..6f710a4d2
--- /dev/null
+++ b/docs/developer/service-descriptions/index.rst
@@ -0,0 +1,14 @@
+Service Descriptions
+====================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ crypto-service-description
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml b/docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml
new file mode 100644
index 000000000..65c6d83d1
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml
@@ -0,0 +1,49 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+allow_mixing
+left to right direction
+
+
+package CryptoProvider
+{
+ class handler
+ class generate_key_handler
+ class import_key_handler
+ class sign_hash_handler
+ generate_key_handler --|> handler
+ import_key_handler --|> handler
+ sign_hash_handler --|> handler
+}
+package CryptoSerializer
+{
+ class crypto_serializer
+ class protobuf_crypto_serializer
+ class packed_c_crypto_serializer
+ protobuf_crypto_serializer --|> crypto_serializer
+ packed_c_crypto_serializer --|> crypto_serializer
+}
+package MbedCrypto
+{
+ class libmbedcrypto
+}
+package SecureStorage
+{
+ class its_client
+}
+package EntropySource
+{
+ class hw_entropy_source
+}
+
+CryptoProvider ..> CryptoSerializer
+CryptoProvider ..> MbedCrypto
+MbedCrypto ..> SecureStorage
+MbedCrypto ..> EntropySource
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/service-locator.rst b/docs/developer/service-locator.rst
new file mode 100644
index 000000000..80649139d
--- /dev/null
+++ b/docs/developer/service-locator.rst
@@ -0,0 +1,169 @@
+Service Locator
+===============
+
+The service locator model provides clients of trusted services with a common interface for locating service instances and
+establishing RPC sessions with service endpoints. By using the service locator, application code is decoupled from the details
+of where services are deployed. Use of the service locator is entirely optional for client applications. Different deployments
+of *libts* provide implementations of the service locator API that are suitable for different environments. The trusted
+services project uses *libts* to decouple test code from the services under test. This enables tests to be reused for testing
+on different platforms with different distributions of services. The same flexibility may be exploited when writing
+applications that use trusted services.
+
+Service Locator Model
+---------------------
+
+The following class diagram illustrates the service locator model:
+
+.. uml:: uml/ServiceLocatorClassDiagram.puml
+
+The model takes inspiration from microservices architectures where there is a similar need to decouple clients from service
+location. In the model, classes have the following roles:
+
+Class service_locator
+'''''''''''''''''''''
+
+The service_locator is responsible for locating service provider instances and returning a service_context object to allow a
+client to establish RPC sessions with the located service endpoint. A service instance is requested by a client using a service
+name. The service name uniquely identifies a service instance, independent of where the service provider is located. The
+service_locator is a singleton and forms the common interface for locating trusted services.
+
+Class service_context
+'''''''''''''''''''''
+
+A service_context object represents a located service and enables a service client to establish RPC sessions with the service.
+A concrete service_context will provide open and close methods that manage RPC session setup and teardown.
+
+Class rpc_caller
+''''''''''''''''
+
+An rpc_caller provides methods for making remote calls associated with a service endpoint. An rpc_caller object represents an
+instance of an RPC session.
+
+Locating Service Instances
+--------------------------
+
+The location of service instances is likely to vary between deployments. Many factors influence where a service instance is
+deployed and the method needed to locate it. e.g.:
+
+ - The type of processing environment in which a service instance is deployed. e.g. service could be deployed in a secure
+ partition, as a TA or in a secure enclave.
+ - Whether a service instance is co-located with other services instances in the same processing environment or whether a
+ separate environment instance is used per service instance.
+ - For Linux user-space clients, the kernel driver model used for messaging influences how a service is located and the type
+ of messaging interface used for RPC requests.
+
+Because of the wide variability in service deployment options, the Trusted Services framework supports the following:
+
+ - *Location independent service names* - a naming convention for identifying service instances, wherever they are located.
+ By using a location independent service name, a client is decoupled from the actual location of a service instance
+ (similar to a DNS names). A concrete service locator is responsible for resolving the location independent service name.
+ - *Service location strategies* - to accommodate the likely variability, an extensible framework for alternative service
+ location strategies is provided.
+
+Service Names
+'''''''''''''
+
+Location Independent Service Names
+``````````````````````````````````
+
+Because of the potential variability in where service instances are deployed, a naming convention that allows a service instance
+to be identified, independent of its location, is useful. By using a location independent service name, coupling between a
+client application and any particular service deployment can be avoided. Use of the Service Locator API and location
+independent service names allows client applications to be portable across different platforms.
+
+The service instance naming convention uses a URN type string to uniquely identify a particular instance of a class of service.
+To provide extensibility, a naming authority is included in the name. This allows anyone with a domain name to define their own
+unique service names. Core service names are defined under the *trustedfirmware.org* authority. The general structure of a
+service name is as follows::
+
+ urn:sn:<authority>:<service>.<version>:<instance>
+
+ The 'urn' prefix should be dropped when service names are used in context.
+ The version field is optional.
+
+The naming convention includes a version number, separated from the <service> field by a '.' character. Beyond the '.', any
+version numbering scheme may be used. This will potentially be useful for delegating version compatibility decisions to a
+service locator. It is preferable for a client to specify a service name that includes a version number as this will
+potentially allow a service locator to:
+
+ - Locate a compatible service instance. For example, a service provider may expose multiple RPC call endpoints to handle
+ different protocol versions. A service locator may resolve the name to the compatible RPC endpoint, based on the version
+ string requested by the client.
+ - Fail gracefully if no compatible version is found.
+
+Some example service names::
+
+ sn:trustedfirmware.org:crypto.1.0.4:0
+ sn:trustedfirmware.org:secure-storage.1.3.11:1
+ sn:trustedfirmware.org:tpm.2.0:0
+
+Location Specific Service Names
+```````````````````````````````
+
+To enable a client to be able to specify location specific service names, it should also be possible to use names that express a
+location specific identifier such as a partition UUID. While use of location specific services names creates a coupling between
+the client and details of the service deployment, their use may be important in the following cases:
+
+ - Where there is no well-known mapping between a location independent service name and a location specific identifier.
+ - Where the client needs to be specific e.g. for tests that target a specific service deployment.
+
+Location specific service names use the same structure as location independent services names but with a technology specific
+authority field. The following is an example of a service name that identifies a service instance that is deployed in a secure
+partition::
+
+ sn:ffa:d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0:0
+
+ The instance field qualified a particular SP instance from the discovered set.
+
+Service Location Strategies
+'''''''''''''''''''''''''''
+
+The method used by the service locator to resolve a service name to a service instance will depend on the environment in which a
+client is running and where service instances are located. Services will need to be located by any client of a trusted service.
+There are typically two classes of trusted service client:
+
+ - A user-space application.
+ - Another trusted service, running in a secure processing environment.
+
+Different methods for locating service instances in different environments are illustrated in the following examples:
+
+Locating a Service from Linux User-space
+````````````````````````````````````````
+
+Depending on the kernel driver model used, the example methods for locating service instances from Linux user-space are:
+
+ 1. Service instances are represented by device nodes e.g. /dev/tpm0. The service locator will simply map the <service>
+ portion of the services name to the base device name and the <instance> to the device node instance.
+ 2. A service instance is hosted by a TEE as a TA. The TEE will provide a discovery mechanism that will allow a TA type and
+ instance to be identified. The service locator will need to map the service name to the TEE specific naming scheme.
+ 3. A special device that provides messaging provides a method for discovery. e.g. an FF-A driver supports partition
+ discovery.
+ 4. A device is used for remote messaging to a separate microcontroller. There is a well-known protocol for endpoint
+ discovery using the messaging layer.
+
+Locating a Service from another Trusted Service
+```````````````````````````````````````````````
+
+Where a trusted service uses another trusted service, it is likely that both service instances will be running in the same
+security domain e.g. both running in secure partitions within the secure world. Where a single service instance is deployed per
+secure partition, the client service will use the following strategy to locate the service provider:
+
+ 1. The service name is mapped to the well known UUID for the class of SP that hosts the service provider.
+ 2. FF-A partition discovery is used to find all SPs that match the requested UUID.
+ 3. The service instance portion of the service name is used to match the partition ID when selecting the target SP from the
+ list of discovered SPs.
+
+Extending the Service Locator Model
+```````````````````````````````````
+
+To accommodate the need to support alternative location strategies, the Service Locator model can be extended to use a set of
+concrete strategy objects to implement different methods of locating a service instance. The set of strategies used will be
+different for different client environments. The following class diagram illustrates how the model can be extended.
+
+.. uml:: uml/ServiceLocationStrategyClassDiagram.puml
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/software-requirements.rst b/docs/developer/software-requirements.rst
new file mode 100644
index 000000000..ec6c2e406
--- /dev/null
+++ b/docs/developer/software-requirements.rst
@@ -0,0 +1,38 @@
+Software Requirements
+=====================
+
+As of today the only available normal-world interface for Trusted Services is available trough linux. Building and end-to-end
+firmware stack requires compiling the Linux Kernel and linux user space applications. This restricts the possible host
+environments to Linux distributions.
+While some TS components can be built under Windows this scenario is not mandated by this documentation.
+
+The preferred host environment is Ubuntu 18.04.
+
+The following tools are required:
+
+ * CMake, version 3.18.4. (See the `CMake download page`_.)
+ * GNU Make v4.1 or higher.
+ * Git v2.17 or newer.
+ * Python3.6 and the modules listed in ``<project>/requirements.txt``.
+ * GCC supporting the deployment.
+
+ * `opteesp` environment: a host to aarch64 cross-compiler is needed. Please use the compilers specified by the
+ `OP-TEE documentation`_.
+ * `arm-linux` environment: a host to aarch64 linux cross-compiler is needed. Please use the version `9.2-2019.12` of the
+ "aarch64-none-linux-gnu" compiler available from `arm Developer`_.
+ (Note: the compiler part of the OP-TEE build environment works too.)
+ * For `linux-pc` environment use the native version of GCC available in your Linux distribution.
+
+To build the documentation, please refer to :ref:`Building Documentation`.
+
+.. todo:: Add info on commit validation dependencies (checkpatch, uncrustify, etc...)
+
+--------------
+
+.. _OP-TEE documentation: https://optee.readthedocs.io/en/latest/building/gits/build.html#step-4-get-the-toolchains
+.. _arm Developer: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads
+.. _CMake download page: https://cmake.org/files/v3.18/
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/uml/BuildFlow.puml b/docs/developer/uml/BuildFlow.puml
new file mode 100644
index 000000000..0dc146862
--- /dev/null
+++ b/docs/developer/uml/BuildFlow.puml
@@ -0,0 +1,55 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+(*) --> [cmake command] "Generating"
+note right
+ Generate native build files from deployment
+ configuration files. External components are
+ fetched and built. Child deployments are
+ generated, built and installed.
+end note
+
+If "success"
+ --> [false]"Generation Errors" #Red
+else
+ --> [true]"Generated"
+Endif
+
+--> [make install command] "Building"
+note right
+ Compile and link to create build output.
+end note
+
+If "success"
+ --> [false]"Build Errors" #Red
+else
+ --> [true]"Built"
+Endif
+
+--> "Installing"
+note right
+ Copy build output files to installation
+ directory specified by CMAKE_INSTALL_PREFIX.
+end note
+
+If "success"
+ --> [false]"Install Errors" #Red
+else
+ --> [true]"Installed"
+Endif
+
+--> "Deploying" #Green
+note right
+ Perform environment specific
+ deployment steps.
+end note
+
+--> "Deployed" #Green
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/uml/RpcSessionClassDiagram.puml b/docs/developer/uml/RpcSessionClassDiagram.puml
new file mode 100644
index 000000000..d2645605b
--- /dev/null
+++ b/docs/developer/uml/RpcSessionClassDiagram.puml
@@ -0,0 +1,20 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+class rpc_caller {
+ {abstract}int call(opcode, param_buf, result_buf)
+}
+
+rpc_caller -> call_ep
+note right on link
+Association with call_ep is made when
+RPC session is established.
+end note
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/uml/SecureServicesLayers.puml b/docs/developer/uml/SecureServicesLayers.puml
new file mode 100644
index 000000000..114b2fbd5
--- /dev/null
+++ b/docs/developer/uml/SecureServicesLayers.puml
@@ -0,0 +1,46 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+!include ../../uml/style-component.puml
+
+package "Client Processing Environment" COLOR_GREY1 {
+ NS_COMPONENT trusted_service_client as "Trusted Service client"
+ NS_IFC ns_rpc as "RPC"
+ NS_COMPONENT rpc_caller as "RPC Caller"
+ NS_IFC ns_messaging as "messaging"
+ NS_COMPONENT ns_messaging_layer as "Messaging Layer"
+}
+trusted_service_client --down-> ns_rpc
+ns_rpc-down->rpc_caller
+rpc_caller-down->ns_messaging
+ns_messaging-down->ns_messaging_layer
+
+package "Secure Processing Environment" COLOR_BLUE2 {
+ S_COMPONENT trusted_service_provider as "Trusted Service Provider"
+ S_COMPONENT rpc_endpoint as "RPC endpoint"
+ S_COMPONENT s_messaging_layer as "Messaging Layer"
+ S_COMPONENT backend_service as "Backend Service"
+ S_IFC s_rpc as "RPC"
+ S_IFC s_messaging as "messaging"
+ S_IFC s_backend as "backend interface"
+}
+
+trusted_service_provider --down-> s_rpc
+s_rpc-down->rpc_endpoint
+rpc_endpoint-down->s_messaging
+s_messaging-down->s_messaging_layer
+
+trusted_service_provider-down->s_backend
+s_backend-down->backend_service
+
+trusted_service_client<.>trusted_service_provider
+rpc_caller<.>rpc_endpoint
+ns_messaging_layer<.>s_messaging_layer
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/uml/ServiceDeployment.puml b/docs/developer/uml/ServiceDeployment.puml
new file mode 100644
index 000000000..8c6f9548a
--- /dev/null
+++ b/docs/developer/uml/ServiceDeployment.puml
@@ -0,0 +1,84 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+!include ../../uml/style-component.puml
+
+skinparam component {
+ BackgroundColor COLOR_BLUE2
+}
+
+skinparam package {
+ BackgroundColor COLOR_BLUE1
+}
+
+package "tools" {
+ component sw_qa as "Software QA Tools"
+ component compiler_toolchain as "Compiler Toolchain"
+}
+
+package "protocols" {
+ component proto_protobuf as "Protobuf interface definition"
+ component proto_packed_c as "Packed-C interface definition"
+}
+
+package "platform" {
+ component plat_interfaces as "Common driver interfaces"
+ component plat_providers as "Platform providers"
+}
+
+package "deployments" {
+ component deploy_deploy as "Deployment"
+ component depoy_build_cfg as "Deployment specific build configuration"
+ component deploy_init as "Deployment specific service initialization"
+}
+
+package "components" {
+ component comp_src as "Source files"
+ component comp_test_cases as "Test cases"
+ component comp_adapters as "Adapters"
+}
+
+package "external" {
+ component ext_all as "External components/libraries"
+}
+
+package "environments" {
+ component env_build_cfg as "Environment build configuration"
+ component env_libs as "Environment libraries"
+ component env_hdrs as "Environment header files"
+ component env_inst as "installation"
+ env_build_cfg-[hidden]->env_libs
+ env_build_cfg-[hidden]->env_hdrs
+}
+
+deploy_deploy ...> depoy_build_cfg
+deploy_deploy .up.> deploy_init
+
+deploy_deploy ..left..> proto_protobuf
+deploy_deploy ..left..> proto_packed_c
+
+deploy_deploy ..right..> env_build_cfg
+deploy_deploy ..right..> env_libs
+deploy_deploy ..right..> env_hdrs
+deploy_deploy ..right..> env_inst
+
+deploy_deploy ..up..> sw_qa
+deploy_deploy ..up..> compiler_toolchain
+
+deploy_deploy ..> ext_all
+
+deploy_deploy ..down..> comp_src
+deploy_deploy ..down..> comp_test_cases
+deploy_deploy ..down..> comp_adapters
+
+deploy_init -[hidden]up-> proto_protobuf
+
+comp_adapters ...> plat_interfaces
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/uml/ServiceLocationStrategyClassDiagram.puml b/docs/developer/uml/ServiceLocationStrategyClassDiagram.puml
new file mode 100644
index 000000000..4ef2c52fd
--- /dev/null
+++ b/docs/developer/uml/ServiceLocationStrategyClassDiagram.puml
@@ -0,0 +1,24 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+class service_location_strategy
+{
+ {abstract} service_context query(service_name)
+}
+
+class service_locator <<singleton>>
+{
+ void init()
+ void register_strategy(strategy)
+ service_context query(service_name)
+}
+
+service_locator --> "0..*" service_location_strategy
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/uml/ServiceLocatorClassDiagram.puml b/docs/developer/uml/ServiceLocatorClassDiagram.puml
new file mode 100644
index 000000000..0519f41c3
--- /dev/null
+++ b/docs/developer/uml/ServiceLocatorClassDiagram.puml
@@ -0,0 +1,37 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+class service_client
+
+class rpc_caller
+{
+ rpc_call_handle call_begin()
+ int call_invoke()
+ void call_end()
+}
+
+abstract class service_context
+{
+ {abstract} rpc_caller open()
+ {abstract} void close(rpc_caller)
+}
+
+class service_locator <<singleton>>
+{
+ service_context query(service_name)
+ void relinquish(service_context)
+}
+
+service_locator ..> "finds" service_context
+service_context ..> "opens session" rpc_caller
+service_client ..> "queries" service_locator
+service_client --> service_context
+service_client --> rpc_caller
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/writing-documentation.rst b/docs/developer/writing-documentation.rst
new file mode 100644
index 000000000..850d9cd83
--- /dev/null
+++ b/docs/developer/writing-documentation.rst
@@ -0,0 +1,53 @@
+Writing documentation
+=====================
+
+|TS| is documented using `Sphinx`_, which in turn uses Docutils and `Restructured Text`_ (|REST| hereafter).
+
+The source files for the documents are in the *docs* directory of the |TS_REPO|.
+
+The preferred output format is *HTML*, and other formats may or may not work.
+
+
+Section Headings
+----------------
+
+In order to avoid problems if documents include each other, it is important to follow a consistent section heading
+style. Please use at most five heading levels. Please use the following style::
+
+ First-Level Title
+ =================
+
+ Second-Level Title
+ ------------------
+
+ Third-Level Title
+ '''''''''''''''''
+
+ Forth-level Title
+ """""""""""""""""
+
+ Fifth-level Title
+ ~~~~~~~~~~~~~~~~~
+
+
+Inline documentation
+--------------------
+
+To get all information integrated into a single document the project uses Sphinx extensions to allow capturing inline
+documentation into this manual.
+
+
+CMake
+'''''
+
+.. todo:: Add content about how to document cmake scripts.
+
+
+--------------
+
+.. _`Restructured Text`: https://docutils.sourceforge.io/rst.html
+.. _`Sphinx`: https://www.sphinx-doc.org
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
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 000000000..eeb90780f
--- /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 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
diff --git a/docs/environments/ffa/libsp.rst b/docs/environments/ffa/libsp.rst
new file mode 100644
index 000000000..ff1b55210
--- /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 000000000..a2448270a
--- /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
diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt
index 925a078d6..bc1625eff 100644
--- a/docs/global_substitutions.txt
+++ b/docs/global_substitutions.txt
@@ -8,13 +8,15 @@
.. |LCS| replace:: :term:`LCS`
.. |ACLE| replace:: :term:`ACLE`
.. |REST| replace:: reST
+.. |SEMVER| replace:: `Semantic Versioning`_
.. _`TS Mailing List`: https://lists.trustedfirmware.org/mailman/listinfo/trusted-services
-.. _`TS repository`: https://review.trustedfirmware.org/TS/trusted-services.git
+.. _`TS repository`: https://review.trustedfirmware.org/admin/repos/TS/trusted-services
+.. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html
..
--------------
- *Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+ *Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/index.rst b/docs/index.rst
index 9a643c45c..cb44e2c3c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,16 +4,67 @@ The Trusted Services project provides a framework for developing and deploying d
root-of-trust services across a range of secure processing environments such as those
provided by OP-TEE and Hafnium.
+.. raw:: html
+
+ <ul class="grid">
+ <li class="grid-item">
+ <a href="overview/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>About trusted services</h2>
+ </a>
+ <p></p>
+ </li>
+ <li class="grid-item">
+ <a href="project/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>About the project</h2>
+ </a>
+ <p></p>
+ </li>
+ <li class="grid-item">
+ <a href="developer/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Developer Docs</h2>
+ </a>
+ <p></p>
+ </li>
+ <li class="grid-item">
+ <a href="environments/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Processing Environments</h2>
+ </a>
+ <p></p>
+ </li>
+ <li class="grid-item">
+ <a href="security/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Security Model</h2>
+ </a>
+ <p></p>
+ </li>
+ <li class="grid-item">
+ <a href="standards/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Standards Compliance</h2>
+ </a>
+ <p></p>
+ </li>
+ </ul>
+
.. toctree::
:maxdepth: 1
:caption: Contents:
:hidden:
- project/license
- project/maintainers
+ overview/index
+ project/index
+ developer/index
+ environments/index
+ security/index
+ standards/index
--------------
-*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/overview/goals.rst b/docs/overview/goals.rst
new file mode 100644
index 000000000..0e6312278
--- /dev/null
+++ b/docs/overview/goals.rst
@@ -0,0 +1,43 @@
+Project Goals
+=============
+
+The trusted services project aims to make it easy to write new trusted services that can be deployed in different secure
+processing environments without having to rewrite lots of code. The aim is to make component reuse as painless as possible by
+keeping software components free of unnecessary dependencies on anything environment or platform specific.
+
+The project structure has been designed to help meet the following goals:
+
+ - **Support multiple deployments** - allow for different deployments where common service code can be built to run in
+ different environments.
+ - **Support multiple processing environments** - allow support for new processing environments to be easily added.
+ - **Support multiple hardware platforms** - provide a portability model for different hardware.
+ - **Avoid the need for duplicated code** - by encouraging code sharing, code duplication can be minimized.
+ - **Avoid cross-talk between builds** - allow images for different deployments to be built independently without any nasty
+ cross dependencies.
+ - **Support and promote automated testing** - writing and running test cases that operate on individual components,
+ component assemblies or complete service deployments should be easy and accessible.
+ - **Support component sharing with deployment specific configuration** - where necessary, a deployment specific build
+ configuration may need to be applied to a shared component.
+ - **Control which versions of external components are used** - where external components such as libraries are used, it
+ should be possible to peg to a specific version.
+
+Enhancing Security through Reuse and Testing
+--------------------------------------------
+
+Reuse of common framework and service components across multiple deployments will help to shake out bugs that may present
+security vulnerabilities. Repeated reuse of a piece of software in different contexts and by different people can help harden
+the code through progressive improvements and bug fixes. Reuse of a common framework also creates opportunities for standard
+solutions to security problems such as service discovery, client identification, authentication and access control.
+
+The confidence to reuse components needs to be underpinned by testing. A project structure that makes it easy to add tests, run
+tests and live with an increasing suite of test cases is fundamentally important in meeting security goals. Although trusted
+service code will be deployed in execution environments where test and debug can be somewhat awkward, a large amount of the code
+can be tested effectively in a native PC environment. Where code can be tested on a PC, it should be. It should be easy for
+anyone to build and run tests to give confidence that a component passes all tests before changes are made and that code changes
+haven't broken anything.
+
+----------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/overview/index.rst b/docs/overview/index.rst
new file mode 100644
index 000000000..4706034ea
--- /dev/null
+++ b/docs/overview/index.rst
@@ -0,0 +1,15 @@
+About trusted services
+======================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ introduction
+ goals
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/overview/introduction.rst b/docs/overview/introduction.rst
new file mode 100644
index 000000000..674e0b50d
--- /dev/null
+++ b/docs/overview/introduction.rst
@@ -0,0 +1,69 @@
+What are trusted services?
+==========================
+
+The term 'trusted service' is used as a general name for a class of application that runs in an isolated
+processing environment. Other applications rely on trusted services to perform security related operations in
+a way that avoids exposing secret data beyond the isolation boundary of the environment. The word 'trusted'
+does not imply anything inherently trustworthy about a service application but rather that other applications
+put trust in the service. Meeting those trust obligations relies on a range of hardware and firmware
+implemented security measures.
+
+The Arm architecture, in combination with standard firmware, provides a range of isolated processing environments
+that offer hardware-backed protection against various classes of attack. Because of their strong security
+properties, these environments are suitable for running applications that have access to valuable assets
+such as keys or sensitive user data. The goal of the Trusted Services project is to provide a framework in
+which security related services may be developed, tested and easily deployed to run in any of the supported
+environments. A core set of trusted services are implemented to provide basic device security functions such
+as cryptography and secure storage.
+
+Example isolated processing environments are:
+
+ - **Secure partitions** - secure world VMs managed by a secure partition manager
+ - **Trusted applications** - application environments managed by a TEE
+ - **Integrated microcontroller** - a secondary MCU used as a secure enclave
+
+Typical problems solved by trusted services
+-------------------------------------------
+
+The following are examples of how trusted services can solve common device security problems.
+
+
+Protecting IoT device identity
+''''''''''''''''''''''''''''''
+
+During the provisioning process, an IoT device is assigned a secure identity that consists of a public/private
+key pair and a CA signed certificate that includes the public key. The device is also provisioned with the
+public key corresponding to the cloud service that it will operate with. The provisioned material is used
+whenever a device connects to the cloud during the authentication process. To prevent the possibility
+of device cloning or unauthorized transfer to a different cloud service, all provisioned material must be
+held in secure storage and access to the private key must be prevented. To achieve this, the certificate
+verification and nonce signing performed during the TLS handshake is performed by the Crypto trusted service
+that performs the operations without exposing the private key.
+
+
+Protecting Software Updates
+'''''''''''''''''''''''''''
+
+To ensure that software updates applied to a device originate from a legitimate source, update packages are
+signed. A signed package will include a signature block that includes a hash of the package contents within
+the signed data. During the update process, a device will verify the signature using a provisioned public key
+that corresponds to the signing key used by the update originator. By holding the public key in secure storage
+and performing the signature verification using the Crypto service, unauthorized modification of the update
+source is prevented.
+
+
+Secure Logging
+''''''''''''''
+
+A managed IoT device will often be configured by an installation engineer who has physical access to the
+device. To allow a cloud operator to audit configuration changes, it is necessary to keep a log of
+configuration steps performed by the installation engineer. To avoid the possibility of fraudulent
+modification of the audit log, a device signs log data using a device unique key-pair. The public key
+corresponding to the signing private key may be retrieved by the cloud operator to allow the log to
+be verified. To protect the signing key, the Crypto service is used for signing log records.
+
+--------------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/change-log.rst b/docs/project/change-log.rst
new file mode 100644
index 000000000..fbabfa42a
--- /dev/null
+++ b/docs/project/change-log.rst
@@ -0,0 +1,30 @@
+Change Log & Release Notes
+==========================
+
+This document contains a summary of the new features, changes, fixes and known
+issues in each release of Trusted Services.
+
+Version 0.1.0
+-------------
+
+New Features
+^^^^^^^^^^^^
+First release.
+
+Changes
+^^^^^^^
+None.
+
+Resolved Issues
+^^^^^^^^^^^^^^^
+None.
+
+Deprecations
+^^^^^^^^^^^^
+None.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/coding-guidelines.rst b/docs/project/coding-guidelines.rst
new file mode 100644
index 000000000..3090aa489
--- /dev/null
+++ b/docs/project/coding-guidelines.rst
@@ -0,0 +1,73 @@
+Coding Style & Guidelines
+=========================
+
+The following sections contain |TS| coding guidelines. They are continually evolving and should not be considered "set
+in stone". Feel free to question them and provide feedback.
+
+The |TS| project uses multiple "domains" (textual content types, like programming languages) and each defines its own
+rules.
+
+To help configuring text editors the project comes with "`EditorConfig`_" file(s). (:download:`../../.editorconfig`).
+
+Shared rules
+------------
+
+The following rules are common for all domains, except where noted otherwise:
+
+#. Files shall be **UTF-8** encoded.
+#. Use **Unix** style line endings (``LF`` character)
+#. The primary language of the project is English. All comments and documentation must be in this language.
+#. Trailing whitespace is not welcome, please trim these.
+
+C Domain
+--------
+
+C source code rules are base on the *Linux Coding Style* (See: |LCS|). The following deviations apply:
+
+5. |TS| follows *ISO/IEC 9899:1999* standard with |ACLE| version *Q3 2020* extensions.
+#. Line length shall not exceed 100 characters.
+#. Use `snake_case`_ for function, variable and file names.
+#. Each file shall be "self contained" and include header files with external dependencies. No file shall depend on
+ headers included by other files.
+#. Include ordering: please include project specific headers first and then system includes. Please order the files
+ alphabetically in the above two groups.
+#. All variables must be initialized.
+
+Boring stuff is not for smart people and the project uses the `Uncrustify`_ code beautifier to easy formatting the
+source. (See :download:`../../.uncrustify.cfg`)
+
+CMake domain
+------------
+
+11. CMake file names use `CamelCase`_ style.
+#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size.
+#. Use LF as line end in CMake files.
+#. Remove trailing whitespace.
+#. Maximum line length is 128 characters.
+#. When complicated functionality is needed prefer CMake scripting over other languages.
+#. Prefix local variables with `_`.
+#. Use functions to prevent global name-space pollution.
+#. Use `snake_case`_ for function and variable names.
+#. Use the ``include_guard()`` CMake function when creating new modules, to prevent multiple inclusion.
+#. Use self contained modules, i.e. include direct dependencies of the module.
+#. Use the Sphinx CMake domain for in-line documentation of CMake scripts. For details please refer to the
+ `CMake Documentation`_.
+
+.. todo:: Explain CMake return values and parent scope concept in more detail.
+
+Restructured Text Domain
+------------------------
+
+Please refer to :doc:`/developer/writing-documentation`.
+
+--------------
+
+.. _`CamelCase`: https://hu.wikipedia.org/wiki/CamelCase
+.. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
+.. _`CMake Documentation`: https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst
+.. _`EditorConfig`: https://editorconfig.org/
+.. _`Uncrustify`: https://github.com/uncrustify/uncrustify
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/contributing.rst b/docs/project/contributing.rst
new file mode 100644
index 000000000..d9760d9f1
--- /dev/null
+++ b/docs/project/contributing.rst
@@ -0,0 +1,88 @@
+Contributing
+============
+
+
+Getting Started
+---------------
+
+- Make sure you have a GitHub account and you are logged on `developer.trustedfirmware.org`_.
+- Send an email to the |TS_MAIL_LIST| about your work. This gives everyone
+ visibility of whether others are working on something similar.
+- Clone the |TS_REPO| on your own machine.
+- Create a local topic branch based on ``main`` branch of the |TS_REPO|.
+
+Making Changes
+--------------
+
+- Make commits of logical units. See these general `Git guidelines`_ for contributing to a project.
+- Follow the :ref:`Coding Style & Guidelines`.
+- Keep the commits on topic. If you need to fix another bug or make another enhancement, please create a separate
+ change.
+- Avoid long commit series. If you do have a long series, consider whether some
+ commits should be squashed together or addressed in a separate topic.
+- Make sure your commit messages are in the proper format. Please keel the 50/72 rule (for details see `Tim Popes blog entry`_.)
+- Where appropriate, please update the documentation.
+
+ - Consider whether the this document or other in-source documentation
+ needs updating.
+ - Ensure that each changed file has the correct copyright and license information. Files that entirely consist of
+ contributions to this project should have a copyright notice and BSD-3-Clause SPDX license identifier of the form
+ as shown in :ref:`license`. Files that contain changes to imported Third Party IP files should retain their
+ original copyright and license notices. For significant contributions you may add your own copyright notice in
+ following format::
+
+ Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
+
+ where XXXX is the year of first contribution (if different to YYYY) and YYYY is the year of most recent
+ contribution. *<OWNER>* is your name or your company name.
+ - If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform
+ port), then also update the :ref:`maintainers` file.
+ - For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit
+ of the series. Otherwise, include the documentation changes within the single commit.
+
+- Please test your changes.
+
+Submitting Changes
+------------------
+
+- Ensure that each commit in the series has at least one ``Signed-off-by:`` line, using your real name and email
+ address. The names in the ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes to the
+ commit, they must also add their own ``Signed-off-by:`` line. By adding this line the contributor certifies the
+ contribution is made under the terms of the :download:`Developer Certificate of Origin <../../dco.txt>`.
+
+ More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
+
+- Ensure that each commit also has a unique ``Change-Id:`` line. If you have cloned the repository with the "`Clone with
+ commit-msg hook`" clone method, this should already be the case.
+
+ More details may be found in the `Gerrit Change-Ids documentation`_.
+
+- Submit your changes for review at https://review.trustedfirmware.org targeting the ``integration`` branch.
+
+ - The changes will then undergo further review and testing by the :ref:`maintainers`. Any review comments will be made
+ directly on your patch. This may require you to do some rework.
+
+ Refer to the `Gerrit Uploading Changes documentation`_ for more details.
+
+- When the changes are accepted, the :ref:`maintainers` will integrate them.
+
+ - Typically, the :ref:`maintainers` will merge the changes into the ``integration`` branch.
+ - If the changes are not based on a sufficiently-recent commit, or if they cannot be automatically rebased, then the
+ :ref:`maintainers` may rebase it on the ``main`` branch or ask you to do so.
+ - After final integration testing, the changes will make their way into the ``main`` branch. If a problem is found
+ during integration, the merge commit will be removed from the ``integration`` branch and the :ref:`maintainers` will
+ ask you to create a new patch set to resolve the problem.
+
+--------------
+
+.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
+.. _Git guidelines: http://git-scm.com/book/ch5-2.html
+.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
+.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
+.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
+.. _`Tim Popes blog entry`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/glossary.rst b/docs/project/glossary.rst
new file mode 100644
index 000000000..da907b436
--- /dev/null
+++ b/docs/project/glossary.rst
@@ -0,0 +1,35 @@
+Glossary
+========
+
+This glossary provides definitions for terms and abbreviations used in the Trusted Services documentation.
+
+You can find additional definitions in the `Arm Glossary`_.
+
+.. glossary::
+ :sorted:
+
+ TF-A
+ Trusted Firmware-A
+
+ TS
+ Trusted Services
+
+ C identifier like string
+ A name which uses only alphanumeric characters and underscores and the first character is not a digit.
+
+ LCS
+ `Linux Coding Style`_
+
+ ACLE
+ `Arm C language extensions`_
+
+
+--------------
+
+.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
+.. _`Linux Coding Style`: https://www.kernel.org/doc/html/v4.10/process/coding-style.html
+.. _`Arm C language extensions`: https://developer.arm.com/documentation/101028/0012/?lang=en
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/index.rst b/docs/project/index.rst
new file mode 100644
index 000000000..21f1d0f57
--- /dev/null
+++ b/docs/project/index.rst
@@ -0,0 +1,21 @@
+About the project
+=================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ change-log
+ coding-guidelines
+ contributing
+ glossary
+ license
+ maintainers
+ versioning_policy
+ todo
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/license.rst b/docs/project/license.rst
index 472bc6a12..fb63be6a8 100644
--- a/docs/project/license.rst
+++ b/docs/project/license.rst
@@ -1,7 +1,7 @@
License
=======
-Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
@@ -11,7 +11,7 @@ are permitted provided that the following conditions are met:
- Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
-- Neither the name of ARM nor the names of its contributors may be used to
+- Neither the name of Arm nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior
written permission.
diff --git a/docs/project/maintainers.rst b/docs/project/maintainers.rst
index 61d13c586..992d92695 100644
--- a/docs/project/maintainers.rst
+++ b/docs/project/maintainers.rst
@@ -1,9 +1,9 @@
Maintainers
===========
-|TS| is a Trusted Firmware maintained project. All contributions are ultimately
+|TS| is a trustedfirmware.org maintained project. All contributions are ultimately
merged by the maintainers listed below. Technical ownership of some parts of the
-codebase is delegated to the code owners listed below. An acknowledgement from
+code-base is delegated to the code owners listed below. An acknowledgment from
these code maintainers may be required before the maintainers merge a
contribution.
@@ -45,6 +45,6 @@ Code owners
.. _`Linux Maintainers file`: https://github.com/torvalds/linux/blob/master/MAINTAINERS#L80
.. _Project Maintenance Process: https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/
-*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/todo.rst b/docs/project/todo.rst
new file mode 100644
index 000000000..1739eabcd
--- /dev/null
+++ b/docs/project/todo.rst
@@ -0,0 +1,22 @@
+TODO list
+=========
+
+This file collects information on planned future changes and issues to be
+addressed. For managing the TODO list below, the `Sphinx TODO extension`_ is
+used.
+
+.. todo:: Find a solution to make the rendering of TODO entries less intrusive
+ at their original location.
+
+List of TODO entries in the project
+-----------------------------------
+
+.. todolist::
+
+--------------
+
+.. _`Sphinx TODO extension`: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause \ No newline at end of file
diff --git a/docs/project/versioning_policy.rst b/docs/project/versioning_policy.rst
new file mode 100644
index 000000000..d57057fbe
--- /dev/null
+++ b/docs/project/versioning_policy.rst
@@ -0,0 +1,47 @@
+Versioning policy
+==================
+
+This document captures information about the version identifier used by the
+project. It tells the meaning of each part, where the version information is
+captured and how it is managed.
+
+Summary
+-------
+
+The version identifier identifies the feature set supported by a specific
+release, and captures compatibility information to other releases.
+
+This project uses "Semantic Versioning", for details please refer to |SEMVER|.
+
+In general the version number is constructed from three numbers. The `MAJOR`
+number is changed when incompatible API changes are introduced, the `MINOR`
+version when you functionality is added in a backward compatible manner, and
+the `PATCH` version when backwards compatible bug fixes are added.
+
+Each release will get a unique release id assigned. When a release is made, the
+version number will get incremented in accordance with the compatibility rules
+mentioned above.
+
+This project is only using the core version and will not use pre-release or
+build specific metadata extension.
+
+Storage and format
+------------------
+
+The version number of each release will be stored at two locations:
+ #. In a tag of the version control system in the form of "vX.Y.Z" where X Y
+ and Z are the major, minor and patch version numbers.
+ #. In a file called version.txt. This file uses ASCII encoding and will
+ contain the version number as "X.Y.Z" where X Y and Z are the major,
+ minor and patch version numbers.
+
+.. note:: The version id is independent from version identifiers of the
+ versioning system used to store the |TS| (i.e. git).
+
+--------------
+
+.. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/security/index.rst b/docs/security/index.rst
new file mode 100644
index 000000000..ac271be6f
--- /dev/null
+++ b/docs/security/index.rst
@@ -0,0 +1,19 @@
+Security Model
+==============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ self
+
+TODO:
+SDL
+Threat Modell
+etc..
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/standards/index.rst b/docs/standards/index.rst
new file mode 100644
index 000000000..486cac031
--- /dev/null
+++ b/docs/standards/index.rst
@@ -0,0 +1,14 @@
+Standards Compliance
+====================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ psa_certification
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/standards/psa_certification.rst b/docs/standards/psa_certification.rst
new file mode 100644
index 000000000..e9a888c91
--- /dev/null
+++ b/docs/standards/psa_certification.rst
@@ -0,0 +1,191 @@
+PSA Certification Requirements
+==============================
+
+Trusted services contribute to meeting PSA security requirements. In the context of PSA certification, the scope and required
+capabilities of supported trusted services are guided by:
+
+ - The security primitives needed by system software for PSA level 1 checklist compliance.
+ - Test coverage of the certification test suite used for PSA Functional API certification.
+
+To determine what security primitives are needed, the 'system software' PSA scope has been used as a reference. The current PSA
+level 1 questionnaire is highly Cortex-M specific so some interpretation is needed to map requirements to Cortex-A based designs
+that use a rich-OS such as Linux. The following assessment is based on the assumption that the PSA system software scope
+encompasses an entire Linux distribution. The reference system software for the assessment will include:
+
+ - TF-A.
+ - Secure partition manager (OP-TEE with FF-A extensions performs this role).
+ - Set of trusted services, deployed in S-EL0 secure partitions that are built-in to the OP-TEE image to allow early loading.
+ - Normal-world boot loader. EDK2 with Grub used as reference.
+ - Linux kernel.
+ - Root filesystem that includes generic services, libraries and program binaries.
+
+Product developers will extend the base distribution to add application specific components.
+
+PSA System Software Questionnaire Analysis
+------------------------------------------
+
+The following table lists PSA level 1 assessment questions with an attempt to identify the back-end security primitives that are
+needed to meet the requirement. The table is based on PSA Certified Level 1 Questionnaire Version 2.1.
+
+.. list-table:: PSA Questionnaire Analysis
+ :widths: 13 40 15 15 28
+ :header-rows: 1
+
+ * - Requirement
+ - Summary
+ - Depends on
+ - TS used
+ - Comment
+ * - R1.1
+ - | System software and application software update
+ | verification using immutable root-of-trust.
+ - Verify signed hash
+ - Crypto
+ - Depends on secure for persistent key storage.
+ * - R1.2
+ - | System software and application software update
+ | anti-rollback protection.
+ - Increment only NV counter
+ - | Secure Storage (for protecting normal
+ | world components)
+ - | TF-A uses OTP fuses for early boot stages. This requirement is much more difficult to meet
+ | on Cortex-A compared to M as
+ | there are potentially many separately updatable components.
+ * - R2.1
+ - Protected device ID
+ - Sign hash
+ - Crypto
+ - Depends on secure storage for persistent key storage.
+ * - R2.2
+ - Secure storage
+ - Replay protected persistent storage, tied to device
+ - Secure storage
+ - | A filesystem mount that provided file storage with the required security properties would be
+ | the conventional interface for user-space processes.
+ * - R2.3
+ - Crypto best practices
+ - TRNG for random number and key generation
+ - Crypto
+ - Crypto service will need an entropy source.
+ * - R3.1
+ - Remote server authentication
+ - Verify signed hash
+ - Crypto
+ - Depends on secure storage for persistent key storage.
+ * - R3.2
+ - Communication encryption
+ - Kernel encryption support
+ - None
+ - Not a use-case for trusted services.
+ * - R3.3
+ - TLS authentication support
+ - Sign & verify hash
+ - Crypto
+ - TLS library such as Mbed TLS needs to use Crypto service.
+ * - R4.1
+ - Provide attestation token for device life-cycle state
+ - Secure life-cycle state variable, Sign message.
+ - Attestation, Secure lifecycle, Crypto
+ -
+ * - R4.2
+ - Unused functionality disabled
+ - Secure life-cycle state variable
+ - Secure Lifecycle
+ - | Although the PSA questionnaire doesn't state this, in practice, the minimal capabilities
+ | required will depend on the device lifecycle state. This will extend to all parts of the
+ | system software, including trusted service capabilities.
+ * - R4.3
+ - Secure logging
+ - Sign hash for non-repudiable log.
+ - Crypto
+ - | PSA questionnaire isn't specific about non-repudiation but for security auditing purposes,
+ | this may be a requirement. For example, for industrial IoT applications where conformance
+ | to IEC 62443 is important, verifiable log data that can be reliably traced, back to the
+ | originating device is understood to be required.
+ * - R4.4
+ - Restricted log file access
+ - File access control
+ - None
+ - File access using standard Linux DAC or MAC if used.
+ * - R4.5
+ - Data on external interfaces checked defensively
+ - Good coding practices in application components
+ -
+ - | The same could be applied for messages crossing any security boundary e.g. trusted service
+ | interfaces. PSA only mentions external interfaces and critical APIs but for Cortex-A, this
+ | likely to be insufficient.
+ * - R4.6
+ - Principle of least privileges
+ - Use of Linux isolation, access control and other containment methods.
+ -
+ - | No direct dependency on trusted services but access to TS held assets must be controlled
+ | according to principle of least privileges.
+ * - R5.1
+ - Passwords not resettable
+ - Enforcing password policy
+ -
+ -
+ * - R5.2
+ - Password best practices
+ - Enforcing password policy
+ -
+ -
+ * - R5.3
+ - User authentication using critical security parameters
+ - Depends on auth method
+ - Crypto (possibly)
+ - | Requirement is not specific enough to determine if there is a trusted service dependency.
+ | Dependency may be indirect, say to authenticate an Oauth2 server.
+ * - R6.1
+ - Externally applied configuration signed
+ - Verify signed hash
+ - Crypto
+ - Similar to firmware update verification requirement.
+ * - R7.1
+ - Persistent storage of user data must support destructive erase
+ - Destructive erase secure Storage (possibly)
+ - Secure storage
+ - | File based storage with a filesystem mount with the required security properties would be the
+ | conventional way to provide persistent storage to user-space processes.
+
+Observations
+------------
+
+- All dependencies on the PSA Crypto service involve persistent keys. Volatile key support is not needed for compliance.
+- Applying R4.2 to system software doesn't really make sense. The system software features that are needed are largely
+ determined by the application software that implements the device functionality. For a supplier of the base system software,
+ a super-set of required functionality is likely to be the right offering but with the facility to allow features to be
+ configured by device developers. The ability to apply a configuration that limits functionality would be a more useful goal.
+- Although the PSA certification document doesn't mention this, available device capabilities need to be a function of device
+ life-cycle state. For example, some features used during manufacture should not be available when a device is delivered to
+ end users.
+- It's hard to see anyone using the PSA Protected Storage API directly. However, enabling a filesystem mount with equivalent
+ security properties would be beneficial. For example, a protected storage filesystem driver that uses the Protected Storage
+ service as its back-end would be a good fit. The PSA Protected Storage API would never be used directly by user-space
+ applications.
+- Logging with the guarantee of non-repudiation is really required to support audit use-cases. Without that guarantee, it's
+ just logging.
+
+PSA Functional API Tests
+------------------------
+
+Functional API tests suites are currently available for:
+
+ - PSA Crypto
+ - PSA Attestation
+ - PSA Storage
+
+Running and passing API tests is not a requirement for PSA level 1 certification. However, incorporating the API tests into the
+trusted service test process is obviously beneficial as a way of demonstrating a defined set of functionality.
+
+Functional API tests focus on valid behavior testing and are quite thorough in exercising all required functionality that can be
+observed at each API. To pass all tests, the service implementation needs to be complete, at least from a functional
+perspective.
+
+Test code depends on an implementation of the PSA C APIs for each service under test.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/uml/colors.puml b/docs/uml/colors.puml
new file mode 100644
index 000000000..7b1238c52
--- /dev/null
+++ b/docs/uml/colors.puml
@@ -0,0 +1,30 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+' Colors shared between various graphs
+
+!define COLOR_ARM_BLUE #0091BD
+!define COLOR_LT_BLUE b3edff
+
+' The higher the number at the end of the name the darker the color is.
+!define COLOR_BLUE1 #DCEEF3
+!define COLOR_BLUE2 #B9DDE7
+!define COLOR_BLUE3 #96CDDB
+!define COLOR_GREEN1 #EBF1E0
+!define COLOR_GREEN2 #DEF2B8
+!define COLOR_GREY1 #D9D9D9
+!define COLOR_GREY2 #F2F2F2
+!define COLOR_RED1 #FF9C9C
+!define COLOR_RED2 #FFD6D6
+
+!define COLOR_PSA_NW COLOR_GREY1
+!define COLOR_PSA_S_APP_ROT COLOR_GREEN1
+!define COLOR_PSA_S_PSA_ROT COLOR_BLUE2
+!define COLOR_PSA_S_ROT_PERIPHERAL COLOR_BLUE1
+!define COLOR_PSA_NS_PE COLOR_NW
+!define COLOR_PSA_FW_API COLOR_RED2
+!define COLOR_PSA_ROT_SERVICE_API COLOR_RED1
diff --git a/docs/uml/libsp_functions.puml b/docs/uml/libsp_functions.puml
new file mode 100644
index 000000000..b46cc01ec
--- /dev/null
+++ b/docs/uml/libsp_functions.puml
@@ -0,0 +1,118 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+class ffa_internal_api {
+ .. SVC call ..
+ + ffa_svc()
+}
+
+package "FF-A layer" {
+ class ffa_api {
+ .. Setup and discovery interfaces ..
+ + ffa_version()
+ + ffa_features()
+ + ffa_rx_release()
+ + ffa_rxtx_map()
+ + ffa_rxtx_unmap()
+ + ffa_partition_info_get()
+ + ffa_id_get()
+
+ .. CPU cycle management interfaces ..
+ + ffa_msg_wait()
+
+ .. Messaging interfaces ..
+ + ffa_msg_send_direct_req()
+ + ffa_msg_send_direct_resp()
+
+ .. Memory management interfaces ..
+ + ffa_mem_donate()
+ + ffa_mem_donate_rxtx()
+ + ffa_mem_lend()
+ + ffa_mem_lend_rxtx()
+ + ffa_mem_share()
+ + ffa_mem_share_rxtx()
+ + ffa_mem_retrieve_req()
+ + ffa_mem_retrieve_req_rxtx()
+ + ffa_mem_relinquish()
+ + ffa_mem_reclaim()
+
+ .. Interrupt handler definition ..
+ + ffa_interrupt_handler()
+ }
+
+ class ffa_memory_descriptors {
+ .. Transaction buffer handling ..
+ + ffa_init_mem_transaction_buffer()
+
+ .. Transaction descriptor ..
+ + ffa_init_mem_transaction_desc()
+ + ffa_get_mem_transaction_desc()
+
+ .. Memory access descriptor ..
+ + ffa_reserve_mem_access_desc()
+ + ffa_add_mem_access_desc()
+ + ffa_get_mem_access_desc_count()
+ + ffa_get_mem_access_desc()
+
+ .. Memory region ..
+ + ffa_add_memory_region()
+ + ffa_get_memory_region()
+ }
+}
+
+package "SP layer" {
+ class sp_rxtx {
+ .. RXTX buffer handling ..
+ + sp_rxtx_buffer_map()
+ + sp_rxtx_buffer_unmap()
+ + sp_rxtx_buffer_alignment_boundary_get()
+ + sp_rxtx_buffer_rx_get()
+ + sp_rxtx_buffer_tx_get()
+ }
+
+ class sp_memory_management {
+ .. Donate ..
+ + sp_memory_donate()
+ + sp_memory_donate_dynamic()
+ + sp_memory_donate_dynamic_is_supported()
+
+ .. Lend ..
+ + sp_memory_lend()
+ + sp_memory_lend_dynamic()
+ + sp_memory_lend_dynamic_is_supported()
+
+ .. Share ..
+ + sp_memory_share()
+ + sp_memory_share_dynamic()
+ + sp_memory_share_dynamic_is_supported()
+
+ .. Retrieve ..
+ + sp_memory_retrieve()
+ + sp_memory_retrieve_dynamic()
+ + sp_memory_retrieve_dynamic_is_supported()
+
+ .. Relinquish ..
+ + sp_memory_relinquish()
+
+ .. Reclaim ..
+ + sp_memory_reclaim()
+ }
+}
+
+
+ffa_api -left-> ffa_internal_api
+
+ffa_api -[hidden]-> ffa_memory_descriptors
+
+sp_rxtx -left-> ffa_api
+sp_memory_management --> ffa_api
+sp_memory_management -left-> ffa_memory_descriptors
+sp_memory_management -up-> sp_rxtx
+
+@enduml
diff --git a/docs/uml/style-component.puml b/docs/uml/style-component.puml
new file mode 100644
index 000000000..9400e93b6
--- /dev/null
+++ b/docs/uml/style-component.puml
@@ -0,0 +1,28 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+!include colors.puml
+
+'Comonent diagram definitions
+!define NS_COMPONENT component COLOR_GREY2
+!define NS_IFC interface COLOR_GREY2
+!define S_COMPONENT component COLOR_BLUE1
+!define S_IFC interface COLOR_BLUE1
+
+skinparam component {
+ ArrowColor black
+ BorderColor black
+}
+
+skinparam interface {
+ BorderColor black
+}
+
+skinparam BackgroundColor COLOR_ARM_BLUE
+
+@enduml
diff --git a/tools/b-test/Readme.rst b/tools/b-test/Readme.rst
index 4100e9188..a4ec2c40e 100644
--- a/tools/b-test/Readme.rst
+++ b/tools/b-test/Readme.rst
@@ -96,8 +96,6 @@ Execute ``run.sh help`` to get further details.
--------------
-*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
-
.. |yasha| replace:: `yasha`_
.. |jinja2| replace:: `Jinja2`_
.. |yaml| replace:: `yaml`_
@@ -105,3 +103,7 @@ Execute ``run.sh help`` to get further details.
.. _Jinja2: https://palletsprojects.com/p/jinja
.. _yasha: https://github.com/kblomqvist/yasha
.. _yaml: https://yaml.org
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause \ No newline at end of file