DOC: update documentation.
Add documentation covering:
- developer information about architecture
- project structure and building
- project overview and service descriptions
- the portability model for supporting hardware
Signed-off-by: Julian Hall <julian.hall@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@gmail.com>
Change-Id: I8bf9c01a66350719d82a7ca2bc1c78a8ab17978d
diff --git a/docs/developer/arch-overview.rst b/docs/developer/arch-overview.rst
new file mode 100644
index 0000000..d2f8c4d
--- /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 0000000..4ef53c0
--- /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 0000000..5fe6c63
--- /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 0000000..74fdeb3
--- /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 0000000..3ae4224
--- /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 0000000..aa7f911
--- /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="<mxfile host="confluence.arm.com" modified="2020-10-05T19:50:28.353Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0" etag="Bzz9yr5hRQzs9jvCqYym" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="Yb5y5pyupjcRv4pKJqIq" name="Page-1">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=</diagram></mxfile>"><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 0000000..e0635c5
--- /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="<mxfile host="confluence.arm.com" modified="2021-01-21T15:49:55.792Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0" etag="T4OmEHaxOAbJXEuewn-x" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="Fh55IqWZiI4TxFe46PeK" name="Page-1">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=</diagram></mxfile>"><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 0000000..b57a65c
--- /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="<mxfile host="confluence.arm.com" modified="2020-10-12T14:32:15.581Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:81.0) Gecko/20100101 Firefox/81.0" etag="NMyOFHADfPI-JQlNiOb1" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="wNY_4wXUTk2zhrBGsPOK" name="Page-1">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==</diagram></mxfile>"><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 0000000..33a03cc
--- /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 0000000..8305cb2
--- /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 0000000..b070510
--- /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 0000000..be0e82a
--- /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 0000000..4161f0d
--- /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 0000000..717c73b
--- /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 0000000..6f710a4
--- /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 0000000..65c6d83
--- /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 0000000..8064913
--- /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 0000000..ec6c2e4
--- /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 0000000..0dc1468
--- /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 0000000..d264560
--- /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 0000000..114b2fb
--- /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 0000000..8c6f954
--- /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 0000000..4ef2c52
--- /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 0000000..0519f41
--- /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 0000000..850d9cd
--- /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
