Docs: Enable RTD on tf-m-extras
Added files required for the tf-m-extras documentation to be displayed on Read the Docs.
Change-Id: I813589f566b58834dc75142b7a92349589d8da87
Signed-off-by: Elena Uziunaite <elena.uziunaite@arm.com>
diff --git a/docs/_static/css/tf_custom.css b/docs/_static/css/tf_custom.css
new file mode 100644
index 0000000..5085397
--- /dev/null
+++ b/docs/_static/css/tf_custom.css
@@ -0,0 +1,77 @@
+/*-----------------------------------------------------------------------------
+# Copyright (c) 2023, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#----------------------------------------------------------------------------*/
+
+/* Limit page width */
+@media only screen and (min-width: 780px) {
+ .wy-nav-content {
+ max-width: 1100px;
+ }
+}
+
+/* Flexbox Tile Grid Settings */
+.grid {
+ list-style-type: none !important;
+ display: -webkit-box;
+ display: -ms-flexbox;
+ display: flex;
+ -ms-flex-wrap: wrap;
+ flex-wrap: wrap;
+ -webkit-box-pack: center;
+ -ms-flex-pack: center;
+ justify-content: center;
+ margin: 1rem auto;
+ max-width: calc((250px + 2rem) * 4);
+}
+
+.grid-item {
+ list-style-type: none !important;
+ -webkit-box-flex: 0;
+ -ms-flex: 0 0 auto;
+ flex: 0 0 auto;
+ width: 200px;
+ text-align: center;
+ margin: 1rem;
+}
+
+.grid-item a {
+ display: block;
+ width: 190px;
+ height: 190px;
+ padding: 12px;
+ display: -webkit-box;
+ display: -ms-flexbox;
+ display: flex;
+ -webkit-box-orient: vertical;
+ -webkit-box-direction: normal;
+ -ms-flex-direction: column;
+ flex-direction: column;
+ -webkit-box-pack: center;
+ -ms-flex-pack: center;
+ justify-content: center;
+ -webkit-box-align: center;
+ -ms-flex-align: center;
+ align-items: center;
+ border: 1px solid #c6cbce;
+ background-color: #2980B9;
+ color: white;
+}
+
+.grid-item h2 {
+ font-size: 1rem;
+ margin-bottom: 0.5rem;
+}
+
+.grid-item img {
+ max-width: 75%;
+ margin-bottom: 0.5rem;
+}
+
+
+.grid-item a:hover {
+ background-color: #32cd32;
+ color: white;
+}
diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico
new file mode 100644
index 0000000..915353d
--- /dev/null
+++ b/docs/_static/images/favicon.ico
Binary files differ
diff --git a/docs/_static/images/tf_logo_white.png b/docs/_static/images/tf_logo_white.png
new file mode 100644
index 0000000..e7bff71
--- /dev/null
+++ b/docs/_static/images/tf_logo_white.png
Binary files differ
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..da80cd3
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+#-------------------------------------------------------------------------------
+# Copyright (c) 2019-2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+import os
+import sys
+import re
+from subprocess import check_output
+
+# -- Project information -----------------------------------------------------
+
+project = 'Trusted Firmware-M Extras'
+copyright = '2023, ARM CE-OSS'
+author = 'ARM CE-OSS'
+title = 'User Guide'
+
+# -- Extract current version -------------------------------------------------
+
+try:
+ vrex = re.compile(r'TF-M(?P<GIT_VERSION>v.+?)'
+ r'(-[0-9]+-g)?(?P<GIT_SHA>[a-f0-9]{7,})?$')
+
+ version = check_output("git describe --tags --always",
+ shell = True, encoding = 'UTF-8')
+
+ _v = vrex.match(version)
+ release = _v.group('GIT_VERSION')
+ if _v.group('GIT_SHA'):
+ version = release + "+" + _v.group('GIT_SHA')[:7]
+
+except:
+ version = release = 'Unknown'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+ 'sphinx.ext.imgmath',
+ 'm2r2', #Support markdown files. Needed for external code.
+ 'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
+ 'sphinxcontrib.plantuml', #Add support for PlantUML drawings
+ 'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
+ 'sphinx_tabs.tabs', #Enable tab extension in Sphinx
+]
+
+# Make auto section labels generated be prefixed with file name.
+autosectionlabel_prefix_document=True
+# Add auto section label for level 2 headers only.
+autosectionlabel_maxdepth=2
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
+ 'platform/cypress/psoc64/security/keys/readme.rst',
+ 'lib/ext/**']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+
+html_theme_options = {
+ 'collapse_navigation' : False,
+ 'prev_next_buttons_location' : None, # Hide Prev and Next buttons
+ 'display_version': True, # Show version under logo
+ 'sticky_navigation': True,
+ 'navigation_depth': 3,
+}
+
+# Remove the "View page source" link from the top of docs pages
+html_show_sourcelink = False
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to configuration directory. They are copied after the builtin static
+# files, so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Set the documentation logo relative to configuration directory
+html_logo = '_static/images/tf_logo_white.png'
+
+# Set the documentation favicon
+html_favicon = '_static/images/favicon.ico'
+
+#Disable adding conf.py copyright notice to HTML output
+html_show_copyright = False
+
+# Disable showing Sphinx footer message:
+# "Built with Sphinx using a theme provided by Read the Docs. "
+html_show_sphinx = False
+
+#Add custom css for HTML. Used to allow full page width rendering
+def setup(app):
+ app.add_css_file('css/tfm_custom.css')
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'TF-M doc'
+
+# Enable figures and tables auto numbering
+numfig = True
+numfig_secnum_depth = 0
+numfig_format = {
+ 'figure': 'Figure %s:',
+ 'table': 'Table %s:',
+ 'code-block': 'Listing %s:',
+ 'section': '%s'
+}
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+ # 'papersize': 'letterpaper',
+ # 'pointsize': '10pt',
+ # 'preamble': '',
+ # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'TF-M.tex', title,
+ author, 'manual'),
+]
+
+language = 'en'
diff --git a/docs/examples/corstone310_fvp_dma/clcd_example.rst b/docs/examples/corstone310_fvp_dma/clcd_example.rst
new file mode 100644
index 0000000..30b9bd5
--- /dev/null
+++ b/docs/examples/corstone310_fvp_dma/clcd_example.rst
@@ -0,0 +1,28 @@
+######################################
+Non-Secure DMA350 example for FreeRTOS
+######################################
+
+FreeRTOS example to demonstrate the DMA-350 privileged and unprivileged APIs.
+The privileged task demonstrates a way of using of command linking feature.
+The unprivileged task demonstrates the usage of the unprivileged DMA API through
+a simple 2D example.
+
+For detailed description of how privilege separation can be achieved with
+DMA-350, checkout :doc:`DMA-350 privilege separation </partitions/dma350_unpriv_partition/dma350_privilege_separation>`
+
+***********
+Build steps
+***********
+1. Run the following command in the tf-m directory:
+
+.. code-block::
+
+ $ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps3/corstone310/fvp -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DDEFAULT_NS_SCATTER=OFF -DPLATFORM_SVC_HANDLERS=ON -DNS_EVALUATION_APP_PATH=<tf-m-extras root>/examples/corstone310_fvp_dma/clcd_example
+
+2. Then:
+
+.. code-block::
+
+ $ cmake --build cmake_build -- install
+
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
diff --git a/docs/examples/corstone310_fvp_dma/triggering_example.rst b/docs/examples/corstone310_fvp_dma/triggering_example.rst
new file mode 100644
index 0000000..f887a10
--- /dev/null
+++ b/docs/examples/corstone310_fvp_dma/triggering_example.rst
@@ -0,0 +1,54 @@
+###################################
+DMA350 Triggering interface example
+###################################
+
+Example usage of triggering flow control with DMA350. The DMA350 is configured to control
+the data exchange with the UARTs. The CPU can enter into WFI() and the DMA will signal, when
+the transactions are done. The CPU only wakes up to proccess the received data, then goes back
+to sleep.
+
+***********
+Build steps
+***********
+1. Run the following command in the tf-m directory:
+
+.. code-block::
+
+ $ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps3/corstone310/fvp -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DNS_EVALUATION_APP_PATH=<tf-m-extras root>/examples/corstone310_fvp_dma/triggering_example
+
+2. Then:
+
+.. code-block::
+
+ $ cmake --build cmake_build -- install
+
+*********
+Run steps
+*********
+The example can run only with 11.22.35 or later versions of Corstone SSE-310 Arm Ecosystem FVP.
+The ``mps3_board.uart1_adapter_tx.ENABLE`` and ``mps3_board.uart0_adapter_rx.ENABLE`` parameters have to be set, to enable the triggering interface of the UARTs.
+The ``mps3_board.uart0.rx_overrun_mode=0`` parameter is needed. UART overrun can happen when the received data is not handled in time.
+The UART overrun interrupt is turned off to prevent lock-up, but there might be data loss when the user sends data during data processing or UART transmitting.
+
+1. Run the following command:
+
+.. code-block::
+
+ ./FVP_Corstone_SSE-310 -a cpu0*="bl2.axf" --data "tfm_s_ns_signed.bin"@0x38000000 -C mps3_board.uart1_adapter_tx.ENABLE=true -C mps3_board.uart0_adapter_rx.ENABLE=true -C mps3_board.uart0.rx_overrun_mode=0
+
+
+2. After the FVP starts the following message will be shown in the FVP telnetterminal0:
+
+.. code-block::
+
+ Starting DMA350 Triggering example
+
+
+ ---------------------------------------------------------
+ ---------------------------------------------------------
+ Configure DMA350 for TX on UART1, then CPU goes to sleep.
+ Type in 10 character to this terminal
+
+Select the FVP telnetterminal0 and type in 10 characters. The 10 characters are going to be echoed back in reverse order to the FVP telnetterminal1.
+
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
diff --git a/docs/examples/example_partition.rst b/docs/examples/example_partition.rst
new file mode 100644
index 0000000..ac3f4c3
--- /dev/null
+++ b/docs/examples/example_partition.rst
@@ -0,0 +1,150 @@
+######################
+TF-M Example Partition
+######################
+The TF-M example partition is a simple Secure Partition implementation provided
+to aid development of new Secure Partitions.
+
+It is an Application RoT, SFN model Secure Partition and implements an
+connection-based RoT Service.
+
+Please refer to `PSA Firmware Framework 1.0`_
+and `Firmware Framework for M 1.1 Extensions`_
+for details of the attributes of Secure Partitions.
+
+Please refer to `Adding Secure Partition`_
+for more details of adding a new Secure Partition to TF-M.
+
+**************
+File structure
+**************
+
+.. code-block:: bash
+
+ .
+ ├── CMakeLists.txt
+ ├── README.rst
+ ├── tfm_example_manifest_list.yaml
+ ├── tfm_example_partition_api.c
+ ├── tfm_example_partition_api.h
+ ├── tfm_example_partition.c
+ └── tfm_example_partition.yaml
+
+- ``CMakeLists.txt``
+
+ The CMake file for building this example Secure Partitions.
+ It is specific to the TF-M build system.
+
+- ``README.rst``
+
+ This document.
+
+- ``tfm_example_partition.yaml``
+
+ The manifest of this Secure Partition.
+
+- ``tfm_example_manifest_list.yaml``
+
+ The manifest list that describes the Secure Partition manifest of this Secure
+ Partition. See `TF-M Manifest List`_ for details of manifest lists.
+
+- ``tfm_example_partition.c``
+
+ The core implementation of this Secure Partition.
+
+- ``tfm_example_partition_api.c``
+
+ The APIs for accessing the RoT Services provided by this Secure Partition.
+
+- ``tfm_example_partition_api.h``
+
+ The header file that declares the RoT Services APIs.
+
+************
+How to Build
+************
+It is recommended to build this example Secure Partition via out-of-tree build.
+It can minimize the changes to TF-M source code for building and testing the
+example.
+
+To build, append the following extra build configurations to the CMake build
+commands.
+
+- ``-DTFM_PARTITION_EXAMPLE``
+
+ This is the configuration switch to enable or disable building this example.
+ Set to ``ON`` to enable or ``OFF`` to disable.
+
+- ``-DTFM_EXTRA_PARTITION_PATHS``
+
+ Set it to the absolute path of this directory.
+
+- ``-DTFM_EXTRA_MANIFEST_LIST_FILES``
+
+ Set it to the absolute path of the manifest list mentioned above -
+ ``tfm_example_manifest_list.yaml``.
+
+Refer to `Out-of-tree Secure Partition build`_ for more details.
+
+***********
+How to Test
+***********
+To test the RoT Services, you need to build the APIs and call the service APIs
+somewhere.
+
+If you want to add comprehensive tests using the TF-M test framework, please
+refer to `Adding TF-M Regression Test Suite`_.
+
+Testing in NSPE
+===============
+Any NSPE can be used to test the example RoT services.
+If you are using the tf-m-tests repo as NSPE, you can:
+
+- Add the ``tfm_example_partition_api.c`` to ``tfm_ns_api`` CMake library.
+- Add the current directory in the include directory of ``tfm_ns_api``.
+- Call the services APIs in the ``test_app`` function.
+
+Testing in SPE
+==============
+
+Testing in SPE is to test requesting the RoT Services in any Secure Partition.
+
+- Add the example services to the ``dependencies`` attribute in the target
+ Secure Partition's manifest.
+- Call the services APIs somewhere in the Secure Partition, for example, in the
+ entry function.
+
+Note that the API source file has already been added in the ``CMakeLists.txt``.
+There are no extra steps to build the APIs for testing in SPE.
+
+**********
+References
+**********
+
+| `PSA Firmware Framework 1.0`_
+| `Firmware Framework for M 1.1 Extensions`_
+| `Adding Secure Partition`_
+| `TF-M Manifest List`_
+| `Out-of-tree Secure Partition build`_
+| `Adding TF-M Regression Test Suite`_
+
+.. _PSA Firmware Framework 1.0:
+ https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4
+
+.. _Firmware Framework for M 1.1 Extensions:
+ https://documentation-service.arm.com/static/600067c09b9c2d1bb22cd1c5?token=
+
+.. _Adding Secure Partition:
+ https://trustedfirmware-m.readthedocs.io/en/latest/integration_guide/services/tfm_secure_partition_addition.html
+
+.. _TF-M Manifest List:
+ https://trustedfirmware-m.readthedocs.io/en/latest/integration_guide/services/tfm_manifest_tool_user_guide.html#manifest-list
+
+.. _Out-of-tree Secure Partition build:
+ https://trustedfirmware-m.readthedocs.io/en/latest/integration_guide/services/tfm_secure_partition_addition.html#out-of-tree-secure-partition-build
+
+.. _Adding TF-M Regression Test Suite:
+ https://git.trustedfirmware.org/TF-M/tf-m-tests.git/tree/docs/tfm_test_suites_addition.rst
+
+--------------
+
+*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
diff --git a/docs/examples/examples.rst b/docs/examples/examples.rst
new file mode 100644
index 0000000..2df2ee1
--- /dev/null
+++ b/docs/examples/examples.rst
@@ -0,0 +1,65 @@
+The list and simple introduction of the examples in this folder.
+
+###################
+corstone310_fvp_dma
+###################
+
+***********
+Description
+***********
+* DMA-350 Secure tests
+* Non-secure DMA-350 examples for the Corstone-310 FVP platform
+
+***********
+Maintainers
+***********
+- Bence Balogh `<bence.balogh@arm.com> <bence.balogh@arm.com>`_
+- Mark Horvath `<mark.horvath@arm.com> <mark.horvath@arm.com>`_
+
+#########################
+extra_test_suites_example
+#########################
+
+***********
+Description
+***********
+An example and template of out-of-tree build of extra regression test suites.
+
+***********
+Maintainers
+***********
+Jianliang Shen `<jianliang.shen@arm.com> <jianliang.shen@arm.com>`_
+
+#################
+example_partition
+#################
+
+***********
+Description
+***********
+A simple secure partition implementation.
+
+***********
+Maintainers
+***********
+Jianliang Shen `<jianliang.shen@arm.com> <jianliang.shen@arm.com>`_
+
+#########
+vad_an552
+#########
+
+***********
+Description
+***********
+Example application for the AN552 FPGA image, details can be found
+`here </examples/vad_an552/readme.rst>`.
+
+***********
+Maintainers
+***********
+- Gabor Toth `<gabor.toth@arm.com> <gabor.toth@arm.com>`_
+- Mark Horvath `<mark.horvath@arm.com> <mark.horvath@arm.com>`_
+
+---------------------------
+
+*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
new file mode 100644
index 0000000..7f447ef
--- /dev/null
+++ b/docs/examples/index.rst
@@ -0,0 +1,14 @@
+Examples
+========
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+ :hidden:
+
+ Non-Secure DMA350 Example for FreeRTOS <corstone310_fvp_dma/clcd_example>
+ DMA350 Triggering Interface Example <corstone310_fvp_dma/triggering_example>
+ TF-M Example Partition <example_partition>
+ Threat Models <vad_an552/index>
+
+.. include:: examples.rst
diff --git a/docs/examples/vad_an552/index.rst b/docs/examples/vad_an552/index.rst
new file mode 100644
index 0000000..67dce36
--- /dev/null
+++ b/docs/examples/vad_an552/index.rst
@@ -0,0 +1,12 @@
+Threat Models
+=============
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/examples/vad_an552/threat_model.rst b/docs/examples/vad_an552/threat_model.rst
new file mode 100644
index 0000000..50e1a18
--- /dev/null
+++ b/docs/examples/vad_an552/threat_model.rst
@@ -0,0 +1,343 @@
+################################################################
+Trusted Firmware-M Voice Activity Detection Example Threat Model
+################################################################
+
+************
+Introduction
+************
+
+This document extends the generic threat model of Trusted Firmware-M (TF-M).
+This threat model provides an analysis of Voice Activity Detection (VAD) Example
+in TF-M and identifies general threats and mitigation.
+
+Scope
+=====
+
+TF-M supports diverse models and topologies. It also implements multiple
+isolation levels. Each case may focus on different target of evaluation (TOE)
+and identify different assets and threats.
+TF-M implementation consists of several secure services, defined as
+Root of Trust (RoT) service. Those RoT services belong to diverse RoT
+(Application RoT or PSA RoT) and access different assets and hardware. Therefore
+each RoT service may require a dedicated threat model.
+
+This analysis only focuses on the assets and threats introduced by the VAD
+example. The TF-M implementation, topologies, or other RoT services are out of
+scope of this document.
+
+Methodology
+===========
+
+The threat modeling in this document follows the process listed below to
+build up the threat model.
+
+- Target of Evaluation (TOE)
+- Assets identification
+- Data Flow Diagram (DFD)
+- Threats prioritization
+- Threats identification
+
+TOE is the entity on which threat modeling is performed. The logic behind this
+process is to firstly investigate the TOE which could be a system, solution or
+use case. This first step helps to identify the assets to be protected in TOE.
+
+According to TOE and assets, Trust Boundaries can be determined. The Data Flow
+Diagram (DFD) across Trust Boundaries is then defined to help identify the
+threats.
+
+Those threats should be prioritized based on a specific group of principals and
+metrics. The principals and metrics should also be specified.
+
+********************
+Target of Evaluation
+********************
+
+A typical TF-M system diagram can be seen on `Generic Threat Model <Generic-Threat-Model_>`_.
+TF-M is running in the Secure Processing Environment (SPE) and NS software is
+running in Non-secure Processing Environment (NSPE).
+
+The TOE in this general model is the VAD Secure Partition and the interaction of
+peripherals, and NSPE. The VAD algorithm itself and its possible flaws are not
+in scope of this document, however the threats that such flaws can cause and its
+mitigations are in scope.
+
+********************
+Asset identification
+********************
+
+In this threat model, assets include the items listed below:
+
+- Software RoT data, e.g.
+
+ - Secure partition code and data
+ - NSPE data stored in SPE
+ - Data generated in SPE as requested by NSPE
+ - Data flowing from peripherals to SPE
+
+- Availability of entire RoT service
+- Result of a RoT service
+
+*****************
+Data Flow Diagram
+*****************
+
+The list and details of data flows are described in the `Generic Threat Model <Generic-Threat-Model_>`_.
+In addition to the data flows above, this use-case introduces a new data flow
+from a peripheral to the SPE. Although the peripheral resides within the SPE,
+the data from it is external so must be considered as data crossing a trust
+boundary. This Data flow will be labeled as DF7 from now on.
+
+.. note::
+
+ All the other data flows across the Trusted Boundary besides the valid ones
+ mentioned in the `Generic Threat Model <Generic-Threat-Model_>`_ and above
+ should be prohibited by default. Proper isolation must be configured to
+ prevent NSPE directly accessing SPE.
+
+ Although the data flows are covered in general in the TF-M Generic Threat
+ Model, for DF2-DF5, given the inner workings and flow of control in VAD
+ partition, additional threats are also considered. Threats identified in the
+ Generic Threat Model still applies.
+
+*********************
+Threat identification
+*********************
+
+Threat priority
+===============
+
+Threat priority is indicated by the score calculated via Common Vulnerability
+Scoring System (CVSS) Version 3.1 [CVSS]_. The higher the threat scores, the
+greater severity the threat is with and the higher the priority is.
+
+CVSS scores can be mapped to qualitative severity ratings defined in CVSS 3.1
+specification [CVSS_SPEC]_. This threat model follows the same mapping between
+CVSS scores and threat priority rating.
+
+This document focuses on *Base Score* which reflects the constant and general
+severity of a threat according to its intrinsic characteristics.
+
+The *Impacted Component* defined in [CVSS_SPEC]_ refers to the assets listed in
+`Asset identification`_.
+
+Threats and mitigation list
+===========================
+
+This section lists generic threats and corresponding mitigation, based on the
+the analysis of data flows in `Data Flow Diagram`_.
+
+Threats are identified following ``STRIDE`` model. Please refer to [STRIDE]_ for
+more details.
+
+The field ``CVSS Score`` reflects the threat priority defined in
+`Threat priority`_. The field ``CVSS Vector String`` contains the textual
+representation of the CVSS metric values used to score the threat. Refer to
+[CVSS_SPEC]_ for more details of CVSS vector string.
+
+.. note::
+
+ A generic threat may have different behaviors and therefore require different
+ mitigation, in diverse TF-M models and usage scenarios.
+
+ This threat model document focuses on threats specific to the VAD partition.
+ Similar threats might exist in the generic threat model with different
+ consequense or severity. For the details of generic threats in general usage
+ scenario, please refer to the `Generic Threat Model <Generic-Threat-Model_>`_ document.
+
+NSPE requests TF-M secure service
+---------------------------------
+
+This section identifies threats on ``DF2`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-VAD-REQUEST-SERVICE-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-VAD-REQUEST-SERVICE-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may extract result of a VAD |
+ | | service request by measuring time while the service was |
+ | | unavailable for further request. |
+ +---------------+------------------------------------------------------------+
+ | Justification | A malicious NS application may request VAD service to |
+ | | perform voice activity detection, while another legit NS |
+ | | app is doing so. By measuring how much time it takes for |
+ | | the service to became available, it can be extracted if |
+ | | there was voice activity or not. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclose |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | Not yet. Service could use non-blocking or callback based |
+ | | Implementation. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 2.9 (Low) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:U/C:L/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-VAD-REQUEST-SERVICE-D-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-VAD-REQUEST-SERVICE-D-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A Malicious NS applications may frequently call secure |
+ | | services to block secure service requests from other NS |
+ | | applications. |
+ +---------------+------------------------------------------------------------+
+ | Justification | TF-M runs on IoT devices with constrained resource. Even |
+ | | though multiple outstanding NS PSA Client calls can be |
+ | | supported in system, the number of NS PSA client calls |
+ | | served by TF-M simultaneously are still limited. |
+ | | |
+ | | Therefore, if a malicious NS application or multiple |
+ | | malicious NS applications continue calling TF-M secure |
+ | | services frequently, it may block other NS applications to |
+ | | request secure service from TF-M. |
+ | | |
+ | | For VAD service request, this can have more consequense as |
+ | | the current implementation is blocking Secure thread. |
+ +---------------+------------------------------------------------------------+
+ | Category | Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M is unable to manage behavior of NS applications. |
+ | | Assets are not disclosed and TF-M is neither directly |
+ | | impacted in this threat. |
+ | | |
+ | | Repeatedly exploiting this vulnerability could distrupt |
+ | | and decrease the availability of TF-M and other secure |
+ | | servicese, but not completely. Because of this, the |
+ | | availability vector of the threat is considered high. |
+ | | |
+ | | It relies on NS OS to enhance scheduling policy and |
+ | | prevent a single NS application to occupy entire CPU time. |
+ | | It is beyond the scope of this threat model. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 6.2 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+NS interrupts preempts SPE execution
+------------------------------------
+
+This section identifies threats on ``DF5`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-VAD-NS-INTERRUPT-T-D-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-VAD-NS-INTERRUPT-T-D-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker may trigger spurious NS interrupts frequently |
+ | | to block SPE execution. |
+ +---------------+------------------------------------------------------------+
+ | Justification | In single Armv8-M core scenario, an attacker may inject a |
+ | | malicious NS application or hijack a NS hardware to |
+ | | frequently trigger spurious NS interrupts to keep |
+ | | preempting SPE and block SPE to perform normal secure |
+ | | execution. |
+ | | |
+ | | Blocking VAD service long enough can cause loss of input |
+ | | data from peripherals to the service, possibly changing |
+ | | the return value of the service request. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering / Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | It is out of scope of TF-M. |
+ | | |
+ | | Assets protected by TF-M won't be leaked. TF-M won't be |
+ | | directly impacted. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 5.1 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:L/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+Data from peripherals to SPE
+------------------------------------
+
+This section identifies threats on ``DF7`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-VAD-PERIPH-DATA-TO-SPE-T-D-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-VAD-PERIPH-DATA-TO-SPE-T-D-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker may gain ability to artificially modify the |
+ | | data and may trigger untested data paths within the voice |
+ | | activity detection algorithm. |
+ +---------------+------------------------------------------------------------+
+ | Justification | TF-M is unable to prevent manipulation of external data, |
+ | | attacker might inject malicious data through the |
+ | | peripheral. The VAD algorithm is considered trusted, but |
+ | | given its complexity, might be subject to vulnaribilities |
+ | | within its data flow. |
+ | | |
+ | | By carefully crafted data, an attacker might be able to |
+ | | cause the failure of the VAD algorithm. It can also be |
+ | | used or gain in-depth knowledge of the algorithm, possibly |
+ | | making it prone to adversarial attacks. The attacker might |
+ | | also be able to read data accessible within the secure |
+ | | partition that the VAD algorithm is running in. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering / Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | It is out of scope of TF-M to mitigate vulnerabilities |
+ | | within the VAD algorithm, however TF-M is responsible for |
+ | | properly isolating the algorithm within the secure |
+ | | partition, so vulnerabilities must not propagate. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 6.8 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+***************
+Version control
+***************
+
+.. table:: Version control
+
+ +---------+--------------------------------------------------+---------------+
+ | Version | Description | TF-M version |
+ +=========+==================================================+===============+
+ | v1.0 | First version | TF-M v1.6.0 |
+ +---------+--------------------------------------------------+---------------+
+
+*********
+Reference
+*********
+
+.. [Security-Incident-Process] `Security Incident Process <https://developer.trustedfirmware.org/w/collaboration/security_center/reporting/>`_
+
+.. [Generic-Threat-Model] `Generic Threat Model <https://tf-m-user-guide.trustedfirmware.org/docs/security/threat_models/generic_threat_model.html>`_
+
+.. [FF-M] `Arm® Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4>`_
+
+.. [DUAL-CPU-BOOT] `Booting a dual core system <https://tf-m-user-guide.trustedfirmware.org/docs/technical_references/design_docs/dual-cpu/booting_a_dual_core_system.html>`_
+
+.. [CVSS] `Common Vulnerability Scoring System Version 3.1 Calculator <https://www.first.org/cvss/calculator/3.1>`_
+
+.. [CVSS_SPEC] `CVSS v3.1 Specification Document <https://www.first.org/cvss/v3-1/cvss-v31-specification_r1.pdf>`_
+
+.. [STRIDE] `The STRIDE Threat Model <https://docs.microsoft.com/en-us/previous-versions/commerce-server/ee823878(v=cs.20)?redirectedfrom=MSDN>`_
+
+.. [SECURE-BOOT] `Secure boot <https://tf-m-user-guide.trustedfirmware.org/docs/technical_references/design_docs/tfm_secure_boot.html>`_
+
+.. [ROLLBACK-PROTECT] `Rollback protection in TF-M secure boot <https://tf-m-user-guide.trustedfirmware.org/docs/technical_references/design_docs/secure_boot_rollback_protection.html>`_
+
+.. [STACK-SEAL] `Armv8-M processor Secure software Stack Sealing vulnerability <https://developer.arm.com/support/arm-security-updates/armv8-m-stack-sealing>`_
+
+.. [ADVISORY-TFMV-1] `Advisory TFMV-1 <https://tf-m-user-guide.trustedfirmware.org/docs/security/security_advisories/stack_seal_vulnerability.html>`_
+
+.. [ADVISORY-TFMV-2] `Advisory TFMV-2 <https://tf-m-user-guide.trustedfirmware.org/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.html>`_
+
+--------------------
+
+*Copyright (c) 2020-2022 Arm Limited. All Rights Reserved.*
diff --git a/docs/examples/vad_an552/vad_an552.rst b/docs/examples/vad_an552/vad_an552.rst
new file mode 100644
index 0000000..b1071bc
--- /dev/null
+++ b/docs/examples/vad_an552/vad_an552.rst
@@ -0,0 +1,275 @@
+#########################################
+Voice Activity Detection demo application
+#########################################
+
+A demo application for the AN552 FPGA showcasing:
+
+* secure partition using MVE to speed up algorithms
+* secure peripheral usage from secure partition with interrupt handling
+* AWS cloud connectivity with OTA on the non-secure side
+
+---------------
+Brief Operation
+---------------
+
+After boot-up the application first checks whether Over-the-Air update (OTA)
+was initiated from AWS cloud. If yes, the OTA process is executed, otherwise
+the voice activity detection algorithm is started on the secure side. While the
+algorithm is running the non-secure side keep polling it for results. After a
+minute the algorithm is stopped, and the operation restarted with the OTA check
+again.
+
+If the algorithm detects voice, a short audio sample (~100 ms) is recorded, and
+the highest energy frequency component is calculated. This frequency is written
+onto the serial line and it is sent to AWS cloud. Then the algorithm is
+restarted or the OTA check is started if the timeout is up.
+
+By default the solution requires ethernet connectivity, it will not start the
+main operation until the network is up. This can be overwritten if the
+``-DVAD_AN552_NO_CONNECTIVITY=ON`` cmake flag is defined. The effect is:
+
+* No need for Ethernet connection.
+* No need for IoT thing creation in AWS cloud and source update with
+ its credentials.
+* OTA check and AWS cloud communication is not executed.
+
+---------------
+HW requirements
+---------------
+
+* AN552 Version 2.0 FPGA image on MPS3 board.
+* Ethernet connection with access to the internet. (Not needed if
+ ``-DVAD_AN552_NO_CONNECTIVITY=ON`` is added for cmake.)
+* 2 or 3 pole microphone connected into the audio connector. In case of a
+ stereo microphone only the right channel is used.
+
+------------------
+Build instructions
+------------------
+
+*********************************************************
+AWS thing creation and source update with the credentials
+*********************************************************
+
+By default it is required to create an IoT thing in AWS to run the application,
+but this can be skipped if ``-DVAD_AN552_NO_CONNECTIVITY=ON`` is added for
+cmake.
+
+-----------------------------------
+Create an IoT thing for your device
+-----------------------------------
+
+#. Login to your account and browse to the `AWS IoT console <https://console.aws.amazon.com/iotv2/>`__.
+#. In the left navigation pane, choose ``All devices``, and then choose ``Things``.
+#. Click on ``Create things``.
+#. Choose ``Create single thing``.
+#. At the ``Specify thing properties`` page add the name of your thing at
+ ``Thing name``. You will need to add the name later to your C code. Click
+ ``Next``.
+#. At the ``Configure device certificate`` page choose ``Auto-generate a new
+ certificate``, and click ``Next``.
+#. The thing can be created by clicking on ``Create thing`` at the
+ ``Attach policies to certificate`` page. The policy will be created at the
+ next section.
+#. Download the key files and the certificate, and make a note of the name of
+ the certificate.
+#. Activate your certificate if it is not active by default.
+
+---------------
+Create a policy
+---------------
+
+For the sake of simplicity in this example a very permissive Policy is created,
+for production usage a more restrictive one is recommended.
+
+#. In the navigation pane of the AWS IoT console, choose ``Security``, and then
+ choose ``Policies``.
+#. At the ``Policies`` page, choose ``Create policy``.
+#. At the ``Create a policy`` page, enter a name for the policy.
+#. At the Policy document click on JSON, and paste the following snippet into the
+ Policy document textbox, then click on ``Create``. (``Region`` and
+ ``Account ID`` must be updated.)
+
+.. code-block:: JSON
+
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "iot:Connect",
+ "iot:Publish",
+ "iot:Subscribe",
+ "iot:Receive"
+ ],
+ "Resource": "arn:aws:iot:<Region>:<Account ID without dashes>:*"
+ }
+ ]
+ }
+
+---------------------------------------
+Attach the created policy to your thing
+---------------------------------------
+
+#. In the left navigation pane of the AWS IoT console, choose ``Secure``, and
+ then choose ``Certificates``. You should see the certificate that you have
+ created earlier.
+#. Click on the three dots next to the certificate and choose
+ ``Attach policy``.
+#. In the ``Attach policies to certificate(s)`` window choose the created
+ policy and click ``Attach``.
+
+------------------------------------
+Update source with thing credentials
+------------------------------------
+
+Edit `examples/vad_an552/ns_side/amazon-freertos/aws_clientcredential.h` file and
+set the value of the following macros:
+
+* `clientcredentialMQTT_BROKER_ENDPOINT`, set this to the endpoint name of your
+ amazon account. To find this go to the AWS IoT console page and in the left
+ navigation pane click on ``Settings``. The Endpoint can be found under
+ ``Device data endpoint``.
+
+* `clientcredentialIOT_THING_NAME`, set this to the name of the created thing.
+
+Recreate or update examples/vad_an552/ns_side/amazon-freertos/aws_clientcredential_keys.h`
+with the downloaded certificate and keys.
+
+Recreate with the html tool from Amazon-FreeRTOS:
+
+#. Clone `Amazon-FreeRTOS <https://github.com/aws/amazon-freertos>`__.
+#. Open ``Amazon-FreeRTOS/tools/certificate_configuration/CertificateConfigurator.html``
+ in your browser.
+#. Upload the downloaded certificate and the private key.
+#. Click on ``Generate and save aws_clientcredential_keys.h``
+#. Download the file and update `examples/vad_an552/ns_side/amazon-freertos/aws_clientcredential_keys.h`
+ with it.
+
+Alternatively, the file can be updated by hand by setting the values of the
+following macros:
+
+* ``keyCLIENT_CERTIFICATE_PEM``, content of ``<your-thing-certificate-unique-string>-certificate.pem.crt``.
+* ``keyCLIENT_PRIVATE_KEY_PEM``, content of ``<your-thing-certificate-unique-string>-private.pem.key``.
+* ``keyCLIENT_PUBLIC_KEY_PEM``, content of ``<your-thing-certificate-unique-string>-public.pem.key``.
+
+------------------
+Running TF-M build
+------------------
+
+For building TF-M's build system is used with the following mandatory CMAKE
+flags::
+
+ -DTFM_PLATFORM=arm/mps3/corstone300/an552
+ -DNS_EVALUATION_APP_PATH=<path-to-tf-m-extras-repo>/examples/vad_an552/ns_side
+ -DTFM_EXTRA_PARTITION_PATHS=<path-to-tf-m-extras-repo>/partitions/vad_an552_sp/
+ -DTFM_EXTRA_MANIFEST_LIST_FILES=<path-to-tf-m-extras-repo>/partitions/vad_an552_sp/extra_manifest_list.yaml
+ -DPROJECT_CONFIG_HEADER_FILE=<path-to-tf-m-extras-repo>/examples/vad_an552/ns_side/project_config.h
+ -DTFM_PARTITION_FIRMWARE_UPDATE=ON -DMCUBOOT_DATA_SHARING=ON
+ -DMCUBOOT_UPGRADE_STRATEGY=SWAP_USING_SCRATCH
+ -DMCUBOOT_IMAGE_NUMBER=1 -DMCUBOOT_SIGNATURE_KEY_LEN=2048
+ -DCONFIG_TFM_ENABLE_MVE=ON -DCONFIG_TFM_SPM_BACKEND=IPC
+ -DPLATFORM_HAS_FIRMWARE_UPDATE_SUPPORT=ON -DTFM_PARTITION_PLATFORM=ON
+ -DTFM_PARTITION_CRYPTO=ON -DTFM_PARTITION_INTERNAL_TRUSTED_STORAGE=ON
+ -DTFM_PARTITION_PROTECTED_STORAGE=ON -DMCUBOOT_CONFIRM_IMAGE=ON
+
+
+The application also can be run without MVE support, in that case the
+``-DCONFIG_TFM_ENABLE_MVE=ON`` flags should be omitted, and the
+``configENABLE_MVE`` can be set to ``0`` in the
+``ns_side/amazon-freertos/FreeRTOSConfig.h`` file.
+Our measurements showed that MVE speeds up the frequency calculation by 10
+times with release GCC build.
+
+You can check TF-M's build instructions
+`here <https://trustedfirmware-m.readthedocs.io/en/latest/building/tfm_build_instruction.html>`__.
+
+-----------------------
+Running the application
+-----------------------
+
+It is covered by the generic TF-M run instructions for AN552
+`here <https://trustedfirmware-m.readthedocs.io/en/latest/platform/arm/mps3/corstone300/README.html?highlight=an552#build-instructions-with-platform-name-arm-mps3-corstone300-an547>`__.
+
+---------------------------
+Testing the voice algorithm
+---------------------------
+
+Start up the board, wait until ``==== Start listening ====`` is written on the
+serial console and start talking, or make some noise. You can check that the
+``Voice detected with most energy at X Hz`` message is written onto the serial
+console, and the same message is sent to AWS cloud.
+
+For checking the AWS messages:
+
+#. In the left navigation pane of the AWS IoT console, choose ``Test``.
+#. Define ``<Name of your thing>/vad_an552`` as the topic filter.
+#. Click on ``Subscribe``.
+#. Once a message is sent to AWS cloud you should see it on this page.
+
+.. note::
+
+ For this test it is recommended to find a quiet environment, because any
+ noise can trigger the voice activity algorithm.
+
+For testing the frequency calculation pure sine signals should be used,
+the accuracy is about +/- 100 Hz.
+
+----------------------
+Testing Amazon AWS OTA
+----------------------
+
+To run an OTA update a new image must be created with higher version number.
+This can be easily done by rebuilding the solution with the following cmake
+flag: ``-DMCUBOOT_IMAGE_VERSION_S=2.1.0``. (The version itself can be anything, but
+must be higher than the version of the currently running image.) The
+``-DMCUBOOT_CONFIRM_IMAGE`` flag should be set to OFF in the new image build
+config, because the demo going to confirm the new image after downloading it.
+
+The image signature must be extracted from the final binary, can be done by
+openssl running the following commands in the build directory:
+
+#. ``openssl dgst -sha256 -binary -out update-digest.bin tfm_s_ns_signed.bin``
+#. ``openssl pkeyutl -sign -pkeyopt digest:sha256 -pkeyopt rsa_padding_mode:pss -pkeyopt rsa_mgf1_md:sha256 -inkey <path to tfm source>/bl2/ext/mcuboot/root-RSA-2048.pem -in update-digest.bin -out update-signature.bin``
+#. ``openssl base64 -A -in update-signature.bin -out update-signature.txt``
+
+Once the signature extracted into ``update-signature.txt`` file, the OTA job
+can be created:
+
+#. `Create an Amazon S3 bucket to store your update <https://docs.aws.amazon.com/freertos/latest/userguide/dg-ota-bucket.html>`__.
+#. `Create an OTA Update service role <https://docs.aws.amazon.com/freertos/latest/userguide/create-service-role.html>`__.
+#. `Create an OTA user policy <https://docs.aws.amazon.com/freertos/latest/userguide/create-ota-user-policy.html>`__.
+#. Go to AWS IoT web interface and choose ``Manage`` and then ``Jobs``.
+#. Click the create job button and select ``Create FreeRTOS OTA update job``.
+#. Give it a name and click next.
+#. Select the device to update (the Thing you created in earlier steps).
+#. Select ``MQTT`` transport only.
+#. Select ``Use my custom signed file``.
+#. Paste the signature string from the ``update-signature.txt`` file. Make sure
+ that it is pasted as it is without any whitespace characters.
+#. Select ``SHA-256`` and ``RSA`` algorithms.
+#. For ``Path name of code signing certificate on device`` put in ``0``
+ (the path is not used).
+#. Select upload new file and select the signed update binary
+ ``tfm_s_ns_signed.bin``.
+#. Select the S3 bucket you created to upload the binary to.
+#. For ``Path name of file on device`` put in ``combined image``.
+#. As the role, select the OTA role you created.
+#. Click next.
+#. Click next, your update job is ready and running. If your board is running
+ (or the next time it will be turned on) the update will be performed.
+
+After the update happened the system resets, and the image version is written
+onto the serial console. That way the update can be verified.
+
+.. note::
+
+ The OTA process only updates the image stored in RAM, so if the MPS3 board
+ is power cycled the system will boot up with the original image. The FPGA at
+ power-on loads the application image from the SD card to RAM, and the SD
+ card content is not changed during OTA.
+
+-------------
+
+*Copyright (c) 2021-2023, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..89e5a81
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,100 @@
+################################
+Trusted Firmware-M Extras
+################################
+
+.. raw:: html
+
+The Trusted Firmware-M (TF-M) Extras repository is the extension of the TF-M
+main repository to host the examples, demonstrations, third-party modules,
+third-party secure partitions, etc.
+
+*******
+License
+*******
+
+The default license of new source code in this repository is :doc:`BSD 3-clause <license>`.
+
+Some source files are contributed by the third-parties or derived from the
+external projects. A license file should be included in the root folder of these
+source files if it has a different license.
+
+****************
+Folder Structure
+****************
+
+- `examples`: This folder hosts the examples and demos for TF-M.
+- `partitions`: This folder hosts the supplementary or third-party secure
+ partitions for TF-M.
+
+*****************************
+Contribute to this repository
+*****************************
+
+Refer to `contributing process <https://trustedfirmware-m.readthedocs.io/en/latest/contributing/contributing_process.html>`_
+for the TF-M general contribution guideline.
+
+Please contact `TF-M development mailing list <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org>`_
+for any question.
+
+.. note::
+ If your contribution consists of pre-bulit binaries, please upload your
+ binary components to
+ `Trusted Firmware binary repository (tf-binaries) <https://git.trustedfirmware.org/tf-binaries.git/about/>`_.
+ This respository accepts source files only.
+
+Additional requirements
+=======================
+
+- It is expected and strongly recommended to integrate and test your
+ example/secure partition with TF-M latest release, to enable new features and
+ mitigate known security vulnerabilities.
+
+- List the example and secure partition in
+ :doc:`example readme <examples/examples_readme>` and
+ :doc:`secure partition readme <partitions/partitions_readme>` respectively.
+
+ - Each example/secure partition shall specify the following information
+
+ - A brief description
+ - Maintainers with their contact emails
+ - If the example/secure partition is not integrated or tested with the
+ latest TF-M release, specify the TF-M version/commit ID tested with.
+
+ - Each example/secure partition shall follow the structure below
+
+ .. code-block:: rst
+
+ Folder name
+ ===========
+
+ Description
+ -----------
+ Simple description
+
+ Maintainers
+ -----------
+ Maintainer list and emails
+
+ TF-M version
+ ------------
+ Optional. Specify the TF-M version/commit ID if it is not integrated or
+ test with latest TF-M release.
+
+.. toctree::
+ :caption: Overview
+ :maxdepth: 1
+ :hidden:
+
+ Partitions <partitions/index>
+ Examples <examples/index>
+
+.. toctree::
+ :caption: Links
+ :maxdepth: 1
+ :hidden:
+
+ Trusted Firmware-M <https://trustedfirmware-m.readthedocs.io/en/latest/>
+
+--------------
+
+*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/delegated_attestation/delegated_attest_flow.svg b/docs/partitions/delegated_attestation/delegated_attest_flow.svg
new file mode 100644
index 0000000..ef732a8
--- /dev/null
+++ b/docs/partitions/delegated_attestation/delegated_attest_flow.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="1479px" preserveAspectRatio="none" style="width:1042px;height:1479px;background:#FFFFFF;" version="1.1" viewBox="0 0 1042 1479" width="1042px" zoomAndPan="magnify"><defs/><g><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="93" x2="93" y1="36.2969" y2="1443.7344"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="238" x2="238" y1="36.2969" y2="1443.7344"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="430" x2="430" y1="36.2969" y2="1443.7344"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="534" x2="534" y1="36.2969" y2="1443.7344"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="635" x2="635" y1="36.2969" y2="1443.7344"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="801" x2="801" y1="36.2969" y2="1443.7344"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="928" x2="928" y1="36.2969" y2="1443.7344"/><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="89" x="49" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="75" x="56" y="24.9951">Application</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="89" x="49" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="75" x="56" y="1462.7295">Application</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="167" x="155" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="153" x="162" y="24.9951">Delegated_attestation</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="167" x="155" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="153" x="162" y="1462.7295">Delegated_attestation</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="129" x="366" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="115" x="373" y="24.9951">Initial_attestation</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="129" x="366" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="115" x="373" y="1462.7295">Initial_attestation</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="59" x="505" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="45" x="512" y="24.9951">Crypto</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="59" x="505" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="45" x="512" y="1462.7295">Crypto</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="122" x="574" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="108" x="581" y="24.9951">Measured_boot</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="122" x="574" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="108" x="581" y="1462.7295">Measured_boot</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="136" x="733" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="122" x="740" y="24.9951">Other_subsystem</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="136" x="733" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="122" x="740" y="1462.7295">Other_subsystem</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="98" x="879" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="84" x="886" y="24.9951">Bootloaders</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="98" x="879" y="1442.7344"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="84" x="886" y="1462.7295">Bootloaders</text><rect fill="#EEEEEE" height="3" style="stroke:#EEEEEE;stroke-width:1.0;" width="1035" x="0" y="66.8633"/><line style="stroke:#000000;stroke-width:1.0;" x1="0" x2="1035" y1="66.8633" y2="66.8633"/><line style="stroke:#000000;stroke-width:1.0;" x1="0" x2="1035" y1="69.8633" y2="69.8633"/><rect fill="#EEEEEE" height="23.1328" style="stroke:#000000;stroke-width:2.0;" width="143" x="446" y="56.2969"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="124" x="452" y="72.3638">TF-M Boot phase</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="201" x="827" y="94.4297"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="193" x="831" y="110.4966">Get the IAK from the platform.</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="138" x="831" y="125.6294">IAK might derive from</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="155" x="831" y="140.7622">seed or pre-provisioned.</text><polygon fill="#181818" points="545.5,169.9609,535.5,173.9609,545.5,177.9609,541.5,173.9609" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="539.5" x2="927" y1="173.9609" y2="173.9609"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="232" x="551.5" y="168.895">Pass Initial Attestation Key to Crypto</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="164" x="846" y="186.9609"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="99" x="850" y="203.0278">Get the seed of</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="156" x="850" y="218.1606">Platform Attestation Key</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="117" x="850" y="233.2935">from the platform.</text><polygon fill="#181818" points="545.5,262.4922,535.5,266.4922,545.5,270.4922,541.5,266.4922" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="539.5" x2="927" y1="266.4922" y2="266.4922"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="253" x="551.5" y="261.4263">Pass Platform Attestation Key to Crypto</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="204" x="826" y="279.4922"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="196" x="830" y="295.5591">Store firmware measurements</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="149" x="830" y="310.6919">and metadata to buffer</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="174" x="548" y="327.7578"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="127" x="552" y="343.8247">Read measurement</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="166" x="552" y="358.9575">and metadata from buffer</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="89" x="552" y="374.0903">at service init.</text><rect fill="#EEEEEE" height="3" style="stroke:#EEEEEE;stroke-width:1.0;" width="1035" x="0" y="406.7227"/><line style="stroke:#000000;stroke-width:1.0;" x1="0" x2="1035" y1="406.7227" y2="406.7227"/><line style="stroke:#000000;stroke-width:1.0;" x1="0" x2="1035" y1="409.7227" y2="409.7227"/><rect fill="#EEEEEE" height="23.1328" style="stroke:#000000;stroke-width:2.0;" width="120" x="457.5" y="396.1563"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="101" x="463.5" y="412.2231">TF-M Runtime</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="149" x="726" y="434.2891"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="141" x="730" y="450.356">Firmware is measured</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="50" x="730" y="465.4888">at boot.</text><polygon fill="#181818" points="646,494.6875,636,498.6875,646,502.6875,642,498.6875" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="640" x2="800" y1="498.6875" y2="498.6875"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="142" x="652" y="493.6216">extend_measurement</text><polygon fill="#181818" points="646,523.8203,636,527.8203,646,531.8203,642,527.8203" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="640" x2="800" y1="527.8203" y2="527.8203"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="142" x="652" y="522.7544">extend_measurement</text><polygon fill="#181818" points="226.5,552.9531,236.5,556.9531,226.5,560.9531,230.5,556.9531" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="93.5" x2="232.5" y1="556.9531" y2="556.9531"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="121" x="100.5" y="551.8872">get_delegated_key</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="193" x="142" y="569.9531"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="117" x="146" y="586.02">Preparation to key</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="185" x="146" y="601.1528">derivation. Query all platform</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="161" x="146" y="616.2856">firmware measurements.</text><polygon fill="#181818" points="623,645.4844,633,649.4844,623,653.4844,627,649.4844" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="238.5" x2="629" y1="649.4844" y2="649.4844"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="127" x="245.5" y="644.4185">read_measurement</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="187" x="145" y="662.4844"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="179" x="149" y="678.5513">Hashing the measurements</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="168" x="149" y="693.6841">and associated metadata.</text><polygon fill="#181818" points="522.5,722.8828,532.5,726.8828,522.5,730.8828,526.5,726.8828" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="238.5" x2="528.5" y1="726.8828" y2="726.8828"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="125" x="245.5" y="721.8169">psa_hash_compute</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="161" x="158" y="739.8828"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="135" x="162" y="755.9497">Derive delegated key</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="144" x="162" y="771.0825">from seed. Input is the</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="153" x="162" y="786.2153">hash of measurements.</text><polygon fill="#181818" points="522.5,815.4141,532.5,819.4141,522.5,823.4141,526.5,819.4141" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="238.5" x2="528.5" y1="819.4141" y2="819.4141"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="98" x="245.5" y="814.3481">psa_derive_key</text><polygon fill="#181818" points="104.5,844.5469,94.5,848.5469,104.5,852.5469,100.5,848.5469" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="98.5" x2="237.5" y1="848.5469" y2="848.5469"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="121" x="110.5" y="843.481">get_delegated_key</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="158" x="14" y="861.5469"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="147" x="18" y="877.6138">Private key is returned.</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="150" x="18" y="892.7466">Public part is computed</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="82" x="18" y="907.8794">by the caller.</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="124" x="31" y="924.9453"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="116" x="35" y="941.0122">Hash of public key</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="83" x="35" y="956.145">is computed.</text><polygon fill="#181818" points="226.5,985.3438,236.5,989.3438,226.5,993.3438,230.5,989.3438" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="93.5" x2="232.5" y1="989.3438" y2="989.3438"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="64" x="100.5" y="984.2778">get_token</text><rect fill="#FEFFDD" height="68" style="stroke:#181818;stroke-width:0.5;" width="186" x="145" y="1002.3438"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="116" x="149" y="1018.4106">Hash of public key</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="127" x="149" y="1033.5435">is received as input.</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="178" x="149" y="1048.6763">Compare against previously</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="77" x="149" y="1063.8091">derived key.</text><polygon fill="#181818" points="418.5,1093.0078,428.5,1097.0078,418.5,1101.0078,422.5,1097.0078" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="238.5" x2="424.5" y1="1097.0078" y2="1097.0078"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="168" x="245.5" y="1091.9419">get_initial_attestion_token</text><rect fill="#FEFFDD" height="53" style="stroke:#181818;stroke-width:0.5;" width="191" x="335" y="1110.0078"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="177" x="339" y="1126.0747">Produce the token including</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="183" x="339" y="1141.2075">the hash of public key as the</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="101" x="339" y="1156.3403">Challenge claim</text><polygon fill="#181818" points="623,1185.5391,633,1189.5391,623,1193.5391,627,1189.5391" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="430.5" x2="629" y1="1189.5391" y2="1189.5391"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="127" x="437.5" y="1184.4731">read_measurement</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="214" x="323" y="1202.5391"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="206" x="327" y="1218.606">Include firmware measurements</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="168" x="327" y="1233.7388">and associated metadata.</text><rect fill="#FEFFDD" height="23" style="stroke:#181818;stroke-width:0.5;" width="148" x="356" y="1250.8047"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="140" x="360" y="1266.8716">Sign the token by IAK.</text><polygon fill="#181818" points="249.5,1296.0703,239.5,1300.0703,249.5,1304.0703,245.5,1300.0703" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="243.5" x2="429.5" y1="1300.0703" y2="1300.0703"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="168" x="255.5" y="1295.0044">get_initial_attestion_token</text><polygon fill="#181818" points="104.5,1325.2031,94.5,1329.2031,104.5,1333.2031,100.5,1329.2031" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="98.5" x2="237.5" y1="1329.2031" y2="1329.2031"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="64" x="110.5" y="1324.1372">get_token</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="177" x="5" y="1342.2031"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="169" x="9" y="1358.27">Create and sign sub-token</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="113" x="9" y="1373.4028">by delegated key.</text><rect fill="#FEFFDD" height="38" style="stroke:#181818;stroke-width:0.5;" width="161" x="13" y="1390.4688"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="113" x="17" y="1406.5356">Create final token</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="153" x="17" y="1421.6685">including all sub-tokens.</text><!--MD5=[ae5a7bee97e920dfe78c75c7082bfd3c]
+@startuml
+
+participant Application
+participant Delegated_attestation
+participant Initial_attestation
+participant Crypto
+participant Measured_boot
+participant Other_subsystem
+participant Bootloaders
+
+== TF-M Boot phase ==
+Rnote over Bootloaders: Get the IAK from the platform.\n\ IAK might derive from\n\ seed or pre-provisioned.
+Bootloaders -> Crypto: Pass Initial Attestation Key to Crypto
+Rnote over Bootloaders: Get the seed of\n\ Platform Attestation Key\n\ from the platform.
+Bootloaders -> Crypto: Pass Platform Attestation Key to Crypto
+Rnote over Bootloaders: Store firmware measurements\n\ and metadata to buffer
+Rnote over Measured_boot: Read measurement\n\ and metadata from buffer\n\ at service init.
+
+== TF-M Runtime ==
+Rnote over Other_subsystem: Firmware is measured\n\ at boot.
+Other_subsystem -> Measured_boot: extend_measurement
+Other_subsystem -> Measured_boot: extend_measurement
+Application -> Delegated_attestation: get_delegated_key
+Rnote over Delegated_attestation: Preparation to key\n\ derivation. Query all platform\n\ firmware measurements.
+Delegated_attestation -> Measured_boot: read_measurement
+Rnote over Delegated_attestation: Hashing the measurements\n\ and associated metadata.
+Delegated_attestation -> Crypto: psa_hash_compute
+Rnote over Delegated_attestation: Derive delegated key\n\ from seed. Input is the\n\ hash of measurements.
+Delegated_attestation -> Crypto: psa_derive_key
+Delegated_attestation -> Application: get_delegated_key
+Rnote over Application: Private key is returned.\n\ Public part is computed\n\ by the caller.
+Rnote over Application: Hash of public key\n\ is computed.
+Application -> Delegated_attestation: get_token
+Rnote over Delegated_attestation: Hash of public key\n\ is received as input.\n\ Compare against previously\n\ derived key.
+Delegated_attestation-> Initial_attestation: get_initial_attestion_token
+Rnote over Initial_attestation: Produce the token including\n\ the hash of public key as the\n\ Challenge claim
+Initial_attestation -> Measured_boot: read_measurement
+Rnote over Initial_attestation: Include firmware measurements\n\ and associated metadata.
+Rnote over Initial_attestation: Sign the token by IAK.
+Initial_attestation -> Delegated_attestation: get_initial_attestion_token
+Delegated_attestation -> Application: get_token
+Rnote over Application: Create and sign sub-token\n\ by delegated key.
+Rnote over Application: Create final token\n\ including all sub-tokens.
+@enduml
+
+PlantUML version 1.2022.7(Mon Aug 22 19:01:30 CEST 2022)
+(GPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Default Encoding: UTF-8
+Language: hu
+Country: HU
+--></g></svg>
\ No newline at end of file
diff --git a/docs/partitions/delegated_attestation/delegated_attest_integration_guide.rst b/docs/partitions/delegated_attestation/delegated_attest_integration_guide.rst
new file mode 100644
index 0000000..4c08e19
--- /dev/null
+++ b/docs/partitions/delegated_attestation/delegated_attest_integration_guide.rst
@@ -0,0 +1,203 @@
+###############################################
+Delegated Attestation Service Integration Guide
+###############################################
+
+************
+Introduction
+************
+
+Delegated Attestation Service was mainly developed to support the attestation
+flow on the ``ARM Confidential Compute Architecture`` (ARM CCA) [1]_. However,
+it implements a generic model, which fits to other use cases as well. Delegated
+attestation is a model where the responsibility of creating the overall
+attestation token is split between different parties. The overall token is a
+composition of sub-tokens, where each sub-token is produced by an individual
+entity within the system. Each sub-token is signed with a different key, which
+is owned by the sub-token producer. The signing keys are derived in a chain.
+Each key is derived by the producer of the previous (in the chain) attestation
+token. The sub-tokens must be cryptographically bound to each other, to make the
+key chain back traceable to the initial attestation key (IAK), which is used
+to sign the initial attestation token. The cryptographic binding is achieved
+by including the hash of the public key in the challenge claim of the
+predecessor attestation token. The IAK or seed of it is provisioned at chip
+manufacturing time. The rest of the signing keys in the chain are derived at
+runtime. The main functionalities of the delegated attestation service are:
+
+- Provide an API to derive a delegated attestation key.
+- Provide an API to make the previous attestation token (e.g.: initial or
+ platform token) queryable.
+
+The entity at the end of the chain is responsible to compose the final
+attestation token. This can be achieved by nesting the tokens or adding a
+wrapper around the sub-tokens.
+
+Usage example:
+
+- Initial or platform attestation token is produced by the Initial
+ Attestation service. Signed by IAK.
+- Additional attestation token can be produced by any entity in the system.
+ An entity can request a signing key via the
+ ``tfm_delegated_attest_get_delegated_key`` call. The previous attestation
+ token can be queried via the ``tfm_delegated_attest_get_token`` call. The
+ input is the hash of the corresponding public key, which is included as
+ the challenge claim.
+
+.. code-block:: restructuredtext
+
+ Composed / final attestation token:
+ +----------------------------------------------------------------+
+ | |
+ | Delegated Attestation Platform Attestation |
+ | Token Token |
+ | +---------------+ +-------------------+ |
+ | | Challenge | +------>| Hash of delegated | |
+ | | ... | | B | public key as | W |
+ | | Delegated | | i | challenge | r |
+ | | public key | | n | ... | a |
+ | | ... | | d | ... | p |
+ | | Other claims | | i | Other claims | p |
+ | +---------------+ | n +-------------------+ e |
+ | | Signed with | | g | Signed with | r |
+ | | delegated |-----+ | IAK | |
+ | | private key | | | |
+ | +---------------+ +-------------------+ |
+ | |
+ +----------------------------------------------------------------+
+
+
+Dependencies
+============
+
+Delegated Attestation service has the following dependencies on other secure
+services within TF-M:
+
+- Crypto service: Crypto service has access to the pre-provisioned built-in
+ keys. It derives a signing key on request.
+- Initial Attestation service: Provides the initial attestation token.
+- Measured boot: Provides the firmware measurements and associated metadata.
+ They are used to compute the input for the key derivation.
+
+.. code-block:: restructuredtext
+
+ +-------------------+
+ | Initial |
+ +---------------+ | Attestation |
+ | | <--------------------| Service |
+ <------------| | get_token() | |
+ get_key() | | +-------------------+
+ | |
+ | Delegated | +-------------------+
+ | Attestation | <--------------------| Crypto |
+ | Service | key_derivation() | Service |
+ | | | |
+ | | +-------------------+
+ | |
+ <------------| | +-------------------+
+ get_token() | | <--------------------| Measured |
+ +---------------+ read_measurement() | Boot |
+ | Service |
+ | |
+ +-------------------+
+
+Delegated Attestation flow diagram
+==================================
+
+.. figure:: delegated_attest_flow.svg
+ :align: center
+
+
+Key derivation
+==============
+
+The system MUST have a pre-provisioned seed programmed at chip manufacturing
+time. Several keys could be derived from this seed. The key derivation happens
+in two phases:
+
+- Boot phase: Done by the bootloader, BL1_1 on RSS platform. The input is
+ the device lifecycle, hash of BL1_2 bootloader, etc.
+- Runtime phase: Delegated attestation and crypto services are responsible
+ for the derivation. Delegated attestation computes the inputs from
+ firmware measurements and crypto service does the actual derivation.
+
+Always the same key is derived until the firmware images (and thereby their
+measurement - hash value is constant) are not changed. If any firmware image
+gets updated or the device lifecycle has changed, then it will result in a
+different delegated signing key than the previous one.
+
+
+**************
+Code structure
+**************
+
+The TF-M Delegated Attestation Service source and header files are located in
+the current directory. The interfaces for the delegated attestation service are
+located in the ``interface/include``. The headers to be included by
+applications that want to use functions from the API is
+``tfm_delegated_attestation.h`` and ``tfm_delegated_attest_defs.h``.
+
+Service source files
+====================
+
+- ``delegated_attest.c`` : Implements core functionalities such as
+ implementation of APIs. Interacts with dependent services to derive
+ the signing key and get the initial attestation token.
+- ``tfm_delegated_attestation_api.c``: Implements the secure API layer to
+ allow other services in the secure domain to request functionalities
+ from the delegated attestation service using the PSA API interface.
+- ``delegated_attest_req_mngr.c``: Includes the initialization entry of
+ delegated attestation service and handles service requests in IPC model.
+
+Delegated Attestation Interfaces
+================================
+
+The TF-M Delegated Attestation service exposes the following interfaces:
+
+.. code-block:: c
+
+ psa_status_t
+ tfm_delegated_attest_get_delegated_key(psa_ecc_family_t ecc_curve,
+ uint32_t key_bits,
+ uint8_t *key_buf,
+ size_t key_buf_size,
+ size_t *key_size,
+ psa_algorithm_t hash_algo);
+ psa_status_t
+ tfm_delegated_attest_get_token(const uint8_t *dak_pub_hash,
+ size_t dak_pub_hash_size,
+ uint8_t *token_buf,
+ size_t token_buf_size,
+ size_t *token_size);
+
+
+Related compile time options for out of tree build
+==================================================
+- ``TFM_PARTITION_DELEGATED_ATTESTATION``: To include the delegated attestation
+ secure partition and its services, its value should be ON. By default, it is
+ switched OFF.
+
+- ``TFM_EXTRA_MANIFEST_LIST_FILES``: <tf-m-extras-repo>/partitions/
+ delegated_attestation/delegated_attestation_manifest_list.yaml
+
+- ``TFM_EXTRA_PARTITION_PATHS``: <tf-m-extras-repo>/partitions/
+ delegated_attestation
+
+- ``DELEG_ATTEST_DUMP_TOKEN_AND_KEY``: If turned ON then the derived delegated
+ attestation key and the delegated attestation token is printed to the console.
+
+************
+Verification
+************
+
+Regression test
+===============
+
+Regression test suite is implemented in ``test/delegated_attest_test.c``.
+
+References
+==========
+
+.. [1] https://developer.arm.com/documentation/DEN0096/A_a/?lang=en
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/dice_protection_environment.rst b/docs/partitions/dice_protection_environment.rst
new file mode 100644
index 0000000..12f4fe2
--- /dev/null
+++ b/docs/partitions/dice_protection_environment.rst
@@ -0,0 +1,146 @@
+###########################
+DICE Protection Environment
+###########################
+
+The DICE Protection Environment (DPE) service makes it possible to execute DICE
+commands within an isolated execution environment. It provides clients with an
+interface to send DICE commands, encoded as CBOR objects, that act on opaque
+context handles. The DPE service performs DICE derivations and certification on
+its internal contexts, without exposing the DICE secrets (private keys and CDIs)
+outside of the isolated execution environment.
+
+For a full description of DPE, see the
+`DPE Specification <https://trustedcomputinggroup.org/wp-content/uploads/TCG-DICE-Protection-Environment-Specification_14february2023-1.pdf>`_.
+
+DPE consists of both a runtime service and boot time integration. The DPE
+service is currently a work in progress.
+
+*********
+Boot time
+*********
+
+A platform integrating DPE must perform the following boot-time functions:
+
+- Derive a RoT CDI from the UDS (HUK) provisioned in OTP, lifecycle state and
+ measurement of the first firmware stage after ROM (BL1_2), and store it via a
+ platform-specific mechanism to be retrieved at runtime.
+
+- Store boot measurements and metadata for all images loaded by the bootloaders
+ in the TF-M shared boot data area.
+
+*******************
+Runtime DPE service
+*******************
+
+The runtime DPE service provides the following functionality.
+
+Initialization
+==============
+
+At initialization, DPE completes the following tasks:
+
+- Retrieves and processes offline measurements and metadata from the TF-M shared
+ boot data area.
+
+- Retrieves the RoT CDI generated at boot time by calling the
+ ``dpe_plat_get_rot_cdi()`` platform function.
+
+- Derives DICE contexts for the RoT layer and platform layer, using the values
+ processed from boot data and the RoT CDI.
+
+- Shares the initial context handle, corresponding to the newly-created child
+ context, with the first client (AP BL1), via a platform-specific mechanism.
+
+Context management
+==================
+
+The internal DICE contexts are referred to by clients of the DPE service using
+opaque context handles. Each DPE command generates a new context handle that is
+returned to the client to refer to the new internal state. Each context handle
+can only be used once, so clients must use the "retain context" parameter of the
+DPE commands if they wish to obtain a fresh handle to the same context.
+
+The context handles are 32-bit integers, where the lower 16-bits is the index of
+the context within the service and the upper 16-bits is a random nonce.
+
+The internal contexts are associated with the 32-bit ID of the owner of the
+context. The DPE service only permits the owner to access the context through
+its context handle. In the TF-M integration, the ID is bound to the PSA Client
+ID of the sender of the DPE message.
+
+Client APIs
+===========
+
+The DPE partition in TF-M wraps the DPE commands into PSA messages. The request
+manager abstracts PSA message handling, and the remainder of the service avoids
+coupling to TF-M partition specifics.
+
+The DPE commands themselves are CBOR-encoded objects that the DPE decode layer
+decodes into calls to one of the following supported DICE functions.
+
+DeriveChild
+-----------
+
+Adds a component context to the layer, consisting of:
+
+- Context handle
+- Parent context handle
+- Linked layer
+- Is leaf
+- Client ID
+- DICE input values
+
+ - Code hash
+ - Config value
+ - Authority hash
+ - Operating mode
+
+When a layer is finalized (create_certificate=true), it:
+
+- Computes the Attestation CDI and Sealing CDI.
+
+- Derives an attestation keypair from the Attestation CDI.
+
+- Creates the corresponding certificate and signs it with the previous layer's
+ attestation private key.
+
+- Stores the finalized certificate in DPE partition SRAM.
+
+Certificates are created in the CBOR Web Token (CWT) format, using the QCBOR
+and t_cose libraries. CWT is specified in
+`RFC 8392 <https://www.rfc-editor.org/rfc/rfc8392.html>`_,
+with customization from
+`Open DICE <https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/specification.md#CBOR-UDS-Certificates>`_.
+
+CertifyKey
+----------
+
+Generates a leaf certificate and returns the full certificate chain leading to
+it. If a public key is supplied, then it certifies the key.
+
+- Adds label (if supplied) to list of measurements.
+
+- Finalizes the layer (as for DeriveChild above).
+
+- Returns the certificate chain (collection of individual certificates) as a
+ CBOR array with format [+COSE_Sign1, COSE_Key]. The (pre-provisioned) root
+ attestation public key is the first element in the CBOR array.
+
+Seal
+----
+
+Encrypts and authenticates data using two keys derived from the Sealing CDI,
+identifiers of the software components in the chain and a supplied label.
+
+- Not currently implemented.
+
+Unseal
+------
+
+Inverse of Seal.
+
+- Not currently implemented.
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/dma350_unpriv_partition/DMA350_privilege_separation_flow.svg b/docs/partitions/dma350_unpriv_partition/DMA350_privilege_separation_flow.svg
new file mode 100644
index 0000000..b69f7f7
--- /dev/null
+++ b/docs/partitions/dma350_unpriv_partition/DMA350_privilege_separation_flow.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" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="741px" height="411px" viewBox="-0.5 -0.5 741 411" style="background-color: rgb(255, 255, 255);"><defs><linearGradient x1="100%" y1="0%" x2="0%" y2="0%" id="mx-gradient-ffc700-1-95d600-1-e-0"><stop offset="0%" style="stop-color: rgb(149, 214, 0); stop-opacity: 1;"/><stop offset="100%" style="stop-color: rgb(255, 199, 0); stop-opacity: 1;"/></linearGradient></defs><g><path d="M 0 23 L 0 0 L 740 0 L 740 23" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="all"/><path d="M 0 23 L 0 410 L 740 410 L 740 23" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="none"/><path d="M 0 23 L 740 23" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="369.5" y="16">Application</text></g><path d="M 220 63 L 220 40 L 420 40 L 420 63" fill="#ffc700" stroke="none" pointer-events="none"/><path d="M 220 63 L 220 160 L 420 160 L 420 63" fill="#e5eceb" stroke="none" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="319.5" y="56">Common unprivileged functions</text></g><rect x="240" y="105" width="160" height="35" fill="#ffc700" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 158px; height: 1px; padding-top: 123px; margin-left: 241px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">DMA350 Unprivileged API</div></div></div></foreignObject><text x="320" y="126" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">DMA350 Unprivileged API</text></switch></g><path d="M 500 263 L 500 240 L 720 240 L 720 263" fill="#333e48" stroke="none" pointer-events="none"/><path d="M 500 263 L 500 310 L 720 310 L 720 263" fill="#e5eceb" stroke="none" pointer-events="none"/><g fill="#FFFFFF" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="609.5" y="256">DMA350</text></g><rect x="520" y="280" width="80" height="20" fill="#95d600" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 290px; margin-left: 521px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Channel 1</div></div></div></foreignObject><text x="560" y="294" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Channel 1</text></switch></g><rect x="620" y="280" width="80" height="20" fill="#00c1de" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 290px; margin-left: 621px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Channel 2</div></div></div></foreignObject><text x="660" y="294" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Channel 2</text></switch></g><path d="M 170 55 L 205 55 L 205 113.8 L 233.63 113.76" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 238.88 113.75 L 231.89 117.26 L 233.63 113.76 L 231.88 110.26 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 90px; margin-left: 150px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; background-color: rgb(255, 255, 255); white-space: nowrap;">1. Request memcopy</div></div></div></foreignObject><text x="150" y="93" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">1. Request memcopy</text></switch></g><rect x="20" y="40" width="150" height="30" fill="#95d600" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 55px; margin-left: 21px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Unprivileged Task 1</div></div></div></foreignObject><text x="95" y="59" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Unprivileged Task 1</text></switch></g><path d="M 170 155 L 190 155 L 190 122.5 L 233.63 122.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 238.88 122.5 L 231.88 126 L 233.63 122.5 L 231.88 119 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="20" y="140" width="150" height="30" fill="#7d868c" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 155px; margin-left: 21px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;"><font color="#ffffff">Unprivileged Task 2</font></div></div></div></foreignObject><text x="95" y="159" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Unprivileged Task 2</text></switch></g><path d="M 170 195 L 205 195 L 205 131.3 L 233.63 131.26" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 238.88 131.25 L 231.89 134.76 L 233.63 131.26 L 231.88 127.76 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="20" y="180" width="150" height="30" fill="#7d868c" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 195px; margin-left: 21px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;"><font color="#ffffff">Unprivileged Task N</font></div></div></div></foreignObject><text x="95" y="199" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Unprivileged Task N</text></switch></g><path d="M 500 343 L 500 320 L 720 320 L 720 343" fill="#333e48" stroke="none" pointer-events="none"/><path d="M 500 343 L 500 390 L 720 390 L 720 343" fill="#e5eceb" stroke="none" pointer-events="none"/><g fill="#FFFFFF" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="609.5" y="336">MPU</text></g><rect x="520" y="355" width="80" height="20" fill="url(#mx-gradient-ffc700-1-95d600-1-e-0)" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 365px; margin-left: 521px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Unprivileged</div></div></div></foreignObject><text x="560" y="369" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Unprivileged</text></switch></g><rect x="620" y="355" width="80" height="20" fill="#00c1de" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 365px; margin-left: 621px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Privileged</div></div></div></foreignObject><text x="660" y="369" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Privileged</text></switch></g><path d="M 500 63 L 500 40 L 720 40 L 720 63" fill="#00c1de" stroke="none" pointer-events="none"/><path d="M 500 63 L 500 200 L 720 200 L 720 63" fill="#e5eceb" stroke="none" pointer-events="none"/><g fill="#000000" font-family="Helvetica" font-weight="bold" pointer-events="none" text-anchor="middle" font-size="12px"><text x="609.5" y="56">Privileged functions</text></g><path d="M 564.08 111.98 L 570 112 L 570 143.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 570 148.88 L 566.5 141.88 L 570 143.63 L 573.5 141.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 130px; margin-left: 640px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; background-color: rgb(255, 255, 255); white-space: nowrap;">3. Call to specific handler</div></div></div></foreignObject><text x="640" y="133" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">3. Call to specific handler</text></switch></g><rect x="530" y="78" width="160" height="35" fill="#00c1de" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 158px; height: 1px; padding-top: 96px; margin-left: 531px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">SVC Handler</div></div></div></foreignObject><text x="610" y="99" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">SVC Handler</text></switch></g><rect x="530" y="150" width="160" height="35" fill="#00c1de" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 158px; height: 1px; padding-top: 168px; margin-left: 531px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Privileged (checker) Task</div></div></div></foreignObject><text x="610" y="171" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Privileged (checker) Task</text></switch></g><path d="M 400 122.5 L 460 122.5 L 460 95.5 L 523.63 95.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 528.88 95.5 L 521.88 99 L 523.63 95.5 L 521.88 92 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 81px; margin-left: 470px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; background-color: rgb(255, 255, 255); white-space: nowrap;">2. SVC call</div></div></div></foreignObject><text x="470" y="84" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">2. SVC call</text></switch></g><path d="M 530 167.5 L 480 167.5 L 480 337.5 L 493.63 337.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 498.88 337.5 L 491.88 341 L 493.63 337.5 L 491.88 334 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 241px; margin-left: 440px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; background-color: rgb(255, 255, 255); white-space: nowrap;">4. Query MPU</div></div></div></foreignObject><text x="440" y="244" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">4. Query MPU</text></switch></g><path d="M 570 185 L 570 232.5 L 560 232.5 L 560 273.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 560 278.88 L 556.5 271.88 L 560 273.63 L 563.5 271.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><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: 220px; margin-left: 630px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; background-color: rgb(255, 255, 255); white-space: nowrap;">5. Configure channel</div></div></div></foreignObject><text x="630" y="223" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">5. Configure channel</text></switch></g></g></svg>
\ No newline at end of file
diff --git a/docs/partitions/dma350_unpriv_partition/dma350_privillege_separation.rst b/docs/partitions/dma350_unpriv_partition/dma350_privillege_separation.rst
new file mode 100644
index 0000000..688bb54
--- /dev/null
+++ b/docs/partitions/dma350_unpriv_partition/dma350_privillege_separation.rst
@@ -0,0 +1,112 @@
+############################
+DMA-350 privilege separation
+############################
+
+The DMA-350 component consists of multiple channels, that can work
+independently. These channels can be limited in both privilege and security.
+When Non-secure access is granted to a DMA channel, the device automatically
+limits the generated transfers to Non-secure. The same happens, when
+unprivileged access is granted to a channel: the transfers will be limited to
+unprivileged. However, there is a risk in the latter: If a system does not
+utilize a system MPU to filter DMA accesses to the memory system, unprivileged
+DMA channels can access to privileged data, and this results in security issues.
+
+For such systems, if unprivileged tasks need access to the DMA, Arm recommends
+the following, both for Secure and Non-secure applications:
+
+#. Set all DMA channels to privileged in the DMA controller
+#. Grant read-write accesses in MPU for the DMA channel register blocks for the
+ unprivileged task
+#. Create a privileged (checker) task, that can be called from an unprivileged
+ task (eg. via SVC call):
+
+ a. Use this privileged task to provide a limited API towards the
+ unprivileged task
+ b. The privileged task can check the parameters and the addresses that
+ would be accessed by the DMA operation. Based on the result, it can
+ setup the DMA channel with the requested parameters or deny it
+ completely
+
+.. note::
+
+ * It is assumed that the Operation System provides a method to define MPU
+ configurations as a per task basis, and always updates the MPU
+ configuration for the current running unprivileged task. When the
+ privileged (checker) task is called, the current MPU configuration -
+ which is of the (unprivileged) caller task - should remain intact. This
+ way, when the privileged (checker) task queries the MPU for unprivileged
+ access with an address, the result will be from the perspective of the
+ (unprivileged) caller task.
+ * The API provided by the privileged task should be limited, as checking
+ complex configuration would require simulating the inner workings of the
+ DMA itself.
+ * In case dynamic assignment of the channels is required, special care must
+ be taken when reconfiguring the privilege or security of a channel. To
+ prevent information leakage and privilege escalation, reconfiguration of
+ a channel can only happen on an idle channel, and it also results in
+ resetting the registers of that channel.
+
+The following diagram shows an example call flow from Unprivileged Task 1 to
+configuring the DMA channel:
+
+.. figure:: DMA350_privilege_separation_flow.svg
+ :alt: DMA-350 privilege separation flow diagram
+
+#. Unprivileged Task 1 calls the DMA-350 unprivileged API
+#. DMA-350 unprivileged API function makes an SVC call with an arbitrary, but
+ unique SVC number (this must be different from SVC services that the RTOS
+ already offered.)
+#. SVC Handler forwards the call to the DMA-350 specific handler
+#. Privileged (checker) task extracts the parameters from the caller stack and
+ query the MPU:
+
+ a. Requested channel register for read access
+ b. Requested source address range for read access
+ c. Requested destination address range for read-write access
+
+#. If all query pass, configure the requested channel. If not, return an error
+ status and this error information propagate back to the unprivileged task 1.
+
+Some example functionality the unprivileged API can provide:
+
+* Memory copy, memory move, endian swap copy
+* Triggers for application specific configurations: The DMA is configured by
+ privileged tasks; API only to start/stop/query the given channel
+
+The following list demonstrates how are unprivileged accesses are checked and
+blocked.
+
+#. Direct from an unprivileged task: Denied by the built-in check of the DMA.
+ It will result in either security violation or RAZ/WI (read as zero, write
+ ignored), depending on DMA configuration
+#. Access through the API, request for a channel that is not dedicated to the
+ Blocked by the privileged (checker) task. When the request is made, the task
+ queries the MPU, whether there is unprivileged read access for the channel
+ registers, using the TTT instructions
+#. Access through the API, with requested read/write addresses in privileged
+ region: Blocked by the privileged (checker) task. When the request is made,
+ the task can queries the address range (that would be affected by the
+ operation) in the MPU for unprivileged access, using the TTT instructions
+ or the cmse_check_address_range intrinsic
+#. Access through the API, with requested read/write addresses in unprivileged
+ channel register block region: Blocked by the target DMA channel. The checker
+ layer will allow the transaction, as in the MPU, the target address is set to
+ unprivileged. The transaction will be generated as an unprivileged transfer,
+ but as the target DMA channel is set to privileged in the DMA controller, it
+ will block the access. It will result in either security violation or RAZ/WI,
+ depending on DMA configuration
+
+Software developers must also consider:
+
+* How to inform the unprivileged task that a DMA operation is completed - The
+ DMA interrupt handle could utilize RTOS event communication to send an event
+ to the unprivileged task to indicate that the DMA operation is completed.
+* How errors are handled - If a DMA operation results in an error, potentially
+ the error handler (execute in privileged state) can inform the unprivileged
+ task via RTOS message/event queue.
+
+To support these communications, the unprivileged APIs and the SVC services for
+setting up DMA-350 might require RTOS specific parameters to define the OS
+events / message queue to use.
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/dma350_unpriv_partition/dma350_unpriv_partition.rst b/docs/partitions/dma350_unpriv_partition/dma350_unpriv_partition.rst
new file mode 100644
index 0000000..84c2f9d
--- /dev/null
+++ b/docs/partitions/dma350_unpriv_partition/dma350_unpriv_partition.rst
@@ -0,0 +1,32 @@
+######
+Readme
+######
+
+TF-M application root of trust partition example for the unprivileged DMA-350
+library. It is expected to be used in Isolation Level 2, as the unprivileged API
+checks the access rights based on the MPU configuration.
+The example demonstrates the proper, non-blocking usage of the library, as well
+as some negative tests for invalid channel access, not allocated channel
+access, and accesses for privileged memory.
+For detailed description of how privilege separation can be achieved with
+DMA-350, checkout :doc:`DMA-350 privilege separation <dma350_privilege_separation.rst>`
+The partition requires a DMA350 peripheral in the platform with Channel 0 configured as
+secure, like for example mps3/corstone310/fvp.
+
+**********************************************
+Build steps for mps3/corstone310/fvp platform
+**********************************************
+1. Run the following command in the tf-m directory:
+
+.. code-block:: bash
+
+ $ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps3/corstone310/fvp -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DTFM_ISOLATION_LEVEL=2 -DPLATFORM_SVC_HANDLERS=ON -DTFM_EXTRA_PARTITION_PATHS=<tf-m-extras root>/partitions/dma350_unpriv_partition -DTFM_PARTITION_LOG_LEVEL=TFM_PARTITION_LOG_LEVEL_INFO -DTFM_EXTRA_MANIFEST_LIST_FILES=<tf-m-extras root>/partitions/dma350_unpriv_partition/extra_manifest_list.yaml
+
+2. Then:
+
+.. code-block:: bash
+
+ $ cmake --build cmake_build -- install
+
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/external_trusted_secure_storage/ETSS_partition_application_note.pdf b/docs/partitions/external_trusted_secure_storage/ETSS_partition_application_note.pdf
new file mode 100644
index 0000000..ce23a85
--- /dev/null
+++ b/docs/partitions/external_trusted_secure_storage/ETSS_partition_application_note.pdf
Binary files differ
diff --git a/docs/partitions/external_trusted_secure_storage/External_Trusted_Secure_Storage_Proposal.pdf b/docs/partitions/external_trusted_secure_storage/External_Trusted_Secure_Storage_Proposal.pdf
new file mode 100644
index 0000000..e507930
--- /dev/null
+++ b/docs/partitions/external_trusted_secure_storage/External_Trusted_Secure_Storage_Proposal.pdf
Binary files differ
diff --git a/docs/partitions/external_trusted_secure_storage/external_trusted_secure_storage.rst b/docs/partitions/external_trusted_secure_storage/external_trusted_secure_storage.rst
new file mode 100644
index 0000000..716604d
--- /dev/null
+++ b/docs/partitions/external_trusted_secure_storage/external_trusted_secure_storage.rst
@@ -0,0 +1,287 @@
+###############################
+External Trusted Secure Storage
+###############################
+
+********
+Abstract
+********
+
+This document mainly introduces the motivation of adding External Trusted Secure
+Storage(ETSS) partition and the corresponding design proposal.
+
+************
+Introduction
+************
+
+A secure storage solution is very important when storage is external to MCU.
+Macronix and other Flash memory suppliers have developed several security memory
+products, and three major products are RPMC, Authentication Flash, and a more
+full featured secure Flash like Macronix ArmorFlash.
+
+RPMC is a memory device which provides non-volatile monotonic counters for
+replay protection.
+
+Authentication Flash mainly provides authentication mechanism to enhance the
+security of data transmition.
+
+Compared to previous two security Flash, the full featured secure Flash performs
+authentication, encryption along with a full range of additional security
+features. This secure Flash generally equips with hardware crypto engine with
+advanced cryptography algorithms, physically unclonable function(PUF),
+non-volatile monotonic counters, TRNG, key storage and management module, etc.
+Secure Flash always provides protection against hardware attacks such as
+probing, side-attack and fault injection.
+
+In addition, the communication channel between host MCU/SoC and secure Flash is
+protected by encryption, authentication, data scrambling, and frame sequencing
+with monotonic counters, as shown in :ref:`secure communication channel between
+host and secure Flash`.Besides, the independent secure sections configured with
+specific security policy satisfies multi-tenant isolation.
+
+Hence the secure Flash provides dependable defense against unauthorised access,
+man-in-the-middle, replay, sniffing and other security threats.
+
+.. _secure communication channel between host and secure Flash:
+
+.. figure:: media/secure_communication_channel.png
+ :align: center
+
+ Secure communication channel between host and secure Flash
+
+More information about secure Flash can be extracted from Macronix ArmorFlash
+product introduction [1]_ and the ArmorFlash Whitepaper [2]_ for understanding
+the secure memory architectures in emerging electronic systems.
+
+
+**************
+Design concept
+**************
+
+Overview
+========
+An ETSS partition is developed as a PSA RoT secure partition to provide external
+trusted secure storage services based on above external security memory products
+features. These three major security memory products are collectively referred
+to as secure Flash in the following.
+The ETSS partition includes several software components, which are listed below:
+
+ +-------------------------+------------------------------------------------+
+ | **Component name** | **Description** |
+ +=========================+================================================+
+ | service API | The service interface of ETSS partition to the |
+ | | NSPE/SPE |
+ +-------------------------+------------------------------------------------+
+ | Service module | This module handles the service calls from |
+ | | NSPE/SPE |
+ +-------------------------+------------------------------------------------+
+ | Secure Flash framework | This module is the generic framework of secure |
+ | module | Flash driver. |
+ +-------------------------+------------------------------------------------+
+
+The interaction between these different components is illustrated in the
+following block diagram:
+
+.. figure:: media/block_diagram_of_etss_components.png
+ :align: center
+
+ Block diagram of the different components of ETSS partition.
+
+The more detailed architecture of ETSS service with secure Flash framework is
+shown below.
+
+.. figure:: media/etss_with_secure_flash_framework.png
+ :align: center
+
+ Layered architecture of ETSS service with secure Flash framework
+
+ETSS services can be accessed by other services running in SPE, or by
+applications running in the NSPE.
+
+ETSS services are split into two independent parts: provisioning and deployment.
+A secure Flash provisioning process should be performed before deployment to set
+up binding keys and grant access rights. The ``etss_secure_flash_provisioning``
+service is provided to perform secure Flash provisioning in the manufacture
+process. The specific provisioning implementation may vary with security memory
+vendors and platforms.
+
+After provisioning, ETSS is ready for providing deployment services with
+external secure Flash.
+The available services vary with security memory products.
+There are three types of services:
+
+- Secure storage
+- Replay protection monotonic counter manipulation
+- Extra services based on extended security features(such as PUF, true random
+ number generator, etc.)
+
+The actually available services are based on the security features of backend
+secure Flash.
+
+Taking following scenarios for example:
+
+- The external security memory product is just an RPMC, only monotonic counters
+ manipulation services are available.
+- The external security memory product is a full featured secure Flash, it
+ supports security read, security program, has a certain number of monotonic
+ counters and other extra security functions. Then the holistic ETSS services
+ may be available.
+
+In the current implementation, ETSS partition just copies the concise filesystem
+implemented in TF-M ITS partition.
+As this filesystem doesn't involve access rights management, to support
+secure Flash multi-zone isolation, it needs to declare separate filesystem
+contexts for each secure Flash isolated partition.
+The detailed layout of each isolated partition is set up by the specific
+secureflash_layout.h of each secure Flash.
+For each specific security memory products, the secureflash_layout.h should be
+configured according to the application scenario.
+
+If user needs to support two and more security memory products simultaneously
+in ETSS partition, then corresponding secure Flash instances and filesystem
+contexts should be declared.
+
+The secure Flash framework module aims to generalize the application interface
+of secure Flash driver, and cover different vendors' security memory products.
+It can be intergated with different software platforms and OSes, and consists of
+four parts: secure Flash API layer, secure Flash common layer, vendor specific
+layer and crypto service interface.
+
+- Secure Flash API layer: This layer mainly manages application's access
+permission based on application identification and pre-provisioned information.
+The implementation of this layer varies accross software platforms and OSes.
+Here integrated with TF-M, this layer manages access permissions based on client
+id, and derives parameters passed to secure Flash common layer.
+
+- Secure Flash common layer: This layer abstracts secure Flash operations, and
+calls binding vendor specific operations.
+
+- Vendor specific layer: The specific implementation of different secure Flash
+vendors and JEDEC recommended implementation, it depends on upper layer's choice
+to bind with JEDEC recommended implementation or vendor specific implementation.
+This layer calls tf-m crypto services via crypto service interface to perform
+cryptographic operations, then assemble packets sent to external secure Flash
+and parse packets received from external secure Flash.
+
+If vendors tend to contribute projects with hiding some critical source codes,
+then these critical parts can be released as library files. These library files
+may be maintained in another git repository because of different license,
+vendors should explain how to access these library files in relevant documents.
+
+
+Code structure
+==============
+
+The code structure of this partition is as follows:
+
+tf-m-extras repo:
+
+``partitions/external_trusted_secure_storage/etss_partition/``
+
+- ``etss.yaml`` - ETSS partition manifest file
+- ``etss_secure_api.c`` - ETSS API implementation for SPE
+- ``etss_req_mngr.c`` - Uniform IPC request handlers
+- ``external_trusted_secure_storage.h`` - ETSS API with client_id parameter
+- ``external_trusted_secure_storage.c`` - ETSS implementation, using secureflash_fs as back-end
+- ``secureflash_fs/`` - Secure Flash filesystem
+- ``external_secure_flash/`` - Secure Flash filesystem operations
+- ``secureflash/`` - Backend secure Flash framework for ETSS service
+ - ``secureflash.c`` - Secure Flash API layer interfaces implementation
+ - ``secureflash.h`` - Secure Flash API layer interfaces
+ - ``secureflash_common/`` - Secure Flash common layer of secure Flash framework
+ - ``crypto_interface/`` - Crypto service interface of secure Flash framework
+ - ``JEDEC_recommend_impl/`` - Reserved JEDEC recommend uniform implementation
+ - ``macronix/`` - Macronix specific implementation
+ - ``secureflash_vendor2/`` - Reserved vendor2 specific implementation
+ - ``secureflash_vendor3/`` - Reserved vendor3 specific implementation
+- ``template/`` - Templates of underlying hardware platform specific implementation of ETSS service
+
+``interface/``
+
+- ``include/etss/etss_api.h`` - ETSS API
+- ``include/etss/etss_defs.h`` - ETSS definitions
+- ``src/etss/etss_ipc_api.c`` - ETSS API implementation for NSPE
+
+``suites/etss``
+
+- ``non_secure/etss_ns_interface_testsuite.c`` - ETSS non-secure client interface test suite
+- ``secure/etss_s_interface_testsuite.c`` - ETSS secure client interface test suite
+- ``secure/etss_s_reliability_testsuite.c`` - ETSS secure interface reliability test suite
+
+tf-binaries repo:
+
+``macronix/commonBinaryMX75/``
+
+- ``mx75_armor_lib.a`` - The binary library of Macronix mx75 series ArmorFlash
+
+.. note::
+
+The ``suites/etss/`` provides ETSS service test suites, this folder can be
+integrated with ``tf-m-tests/test/suites`` for testing.
+
+
+***********************
+Configuration and Build
+***********************
+
+Currently, only GNUARM is supported to build as an out-of-tree Secure Partition.
+
+To test etss service, put ``external_trusted_secure_storage/interface/include/etss``
+under ``trusted-firmware-m/interface/include``, put ``external_trusted_secure_storage/interface/src/etss``
+under ``trusted-firmware-m/interface/src``.
+Add corresponding command within ``trusted-firmware-m/interface/CMakeLists.txt``.
+Besides, to integrate ETSS testsuites sample with ``tf-m-tests``, put the
+``suites/etss`` folder under ``tf-m-test/test/suites``, add following command to
+``tf-m-test/test/suites/CMakeLists.txt``.
+
+.. code-block:: cmake
+
+ add_subdirectory(suites/etss)
+
+ and add the following command to ``tf-m-test/app/CMakeLists.txt``
+
+.. code-block:: cmake
+
+ $<$<BOOL:${TFM_PARTITION_EXTERNAL_TRUSTED_SECURE_STORAGE}>:${INTERFACE_SRC_DIR}/etss/etss_ipc_api.c>
+
+build with the following commands.
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_build -DTFM_PLATFORM=stm/stm32l562e_dk \
+ -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON \
+ -DTFM_EXTRA_MANIFEST_LIST_FILES=<tf-m-extras-abs-path>/partitions/external_trusted_secure_storage/etss_manifest_list.yaml \
+ -DTFM_EXTRA_PARTITION_PATHS=<tf-m-extras-abs-path>/partitions/external_trusted_secure_storage/etss_partition \
+ -DTFM_PARTITION_EXTERNAL_TRUSTED_SECURE_STORAGE=ON -DTFM_ISOLATION_LEVEL=2
+ cmake --build cmake_build -- install
+
+.. note:: <tf-m-extras-abs-path>:The absolute path of tf-m-extras folder.
+ The corresponding trusted-firmware-m version is v1.4.0.
+ At the moment, ETSS partition has been tested with STM32L562E_DK
+ development board. As this development board hasn't carried any
+ secure Flash. An external secure Flash is connected to MCU by fly
+ lines.
+
+**************
+Future changes
+**************
+
+Currently, the implementation of secure Flash provisioning service is primitive,
+and only suitable for developer mode. In the future, a proper secure
+Flash provisioning implementation will be provided.
+
+Besises, the following works are underway:
+ - Optimize secure Flash sessions management.
+ - Add access rights management features to secure Flash filesystem.
+
+References
+==========
+
+.. [1] `ArmorFlash product instruction <https://www.mxic.com.tw/en-us/products/Pages/ArmorFlash.aspx>`_
+
+.. [2] `ArmorFlash Whitepaper <https://www.macronix.com/en-us/products/Documents/Secure%20Memory%20Architectures%20in%20Emerging%20Electronic%20Systems.pdf>`_
+
+-----------
+
+*Copyright (c) 2021-2022, Macronix International Co. LTD. All rights reserved.*
+*SPDX-License-Identifier: BSD-3-Clause*
diff --git a/docs/partitions/external_trusted_secure_storage/media/block_diagram_of_etss_components.png b/docs/partitions/external_trusted_secure_storage/media/block_diagram_of_etss_components.png
new file mode 100644
index 0000000..d115567
--- /dev/null
+++ b/docs/partitions/external_trusted_secure_storage/media/block_diagram_of_etss_components.png
Binary files differ
diff --git a/docs/partitions/external_trusted_secure_storage/media/etss_with_secure_flash_framework.png b/docs/partitions/external_trusted_secure_storage/media/etss_with_secure_flash_framework.png
new file mode 100644
index 0000000..ed6253e
--- /dev/null
+++ b/docs/partitions/external_trusted_secure_storage/media/etss_with_secure_flash_framework.png
Binary files differ
diff --git a/docs/partitions/external_trusted_secure_storage/media/secure_communication_channel.png b/docs/partitions/external_trusted_secure_storage/media/secure_communication_channel.png
new file mode 100644
index 0000000..ed034ed
--- /dev/null
+++ b/docs/partitions/external_trusted_secure_storage/media/secure_communication_channel.png
Binary files differ
diff --git a/docs/partitions/index.rst b/docs/partitions/index.rst
new file mode 100644
index 0000000..048cbb2
--- /dev/null
+++ b/docs/partitions/index.rst
@@ -0,0 +1,16 @@
+Partitions
+==========
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+ :hidden:
+
+ Delegated Attestation Service Integration Guide <delegated_attestation/delegated_attest_integration_guide>
+ DICE Protection Environmnet <dice_protection_environment>
+ DMA-350 Privilege Separation <dma350_unpriv_partition/dma350_privilege_separation>
+ Corstone310 Build Steps <dma350_unpriv_partition/dma350_unpriv_partition>
+ External Trusted Secure Storage <external_trusted_secure_storage/external_trusted_secure_storage>
+ Measured Boot Service Integration Guide <measured_boot_integration_guide>
+
+.. include:: partitions.rst
diff --git a/docs/partitions/measured_boot_integration_guide.rst b/docs/partitions/measured_boot_integration_guide.rst
new file mode 100644
index 0000000..5478e23
--- /dev/null
+++ b/docs/partitions/measured_boot_integration_guide.rst
@@ -0,0 +1,132 @@
+#######################################
+Measured Boot Service Integration Guide
+#######################################
+
+Introduction
+************
+Measured Boot partition provides services to extend and read
+measurements (hash values and metadata) during various stages of a power cycle.
+These measurements can be extended and read by any application/service
+(secure or non-secure).
+
+************
+Measurements
+************
+The initial attestation token (required by attestation service) is formed of
+various claims. Each software component claim comprises of the following
+measurements which are extended and read by Measured Boot services.
+
+ - **Measurement type**: It represents the role of the
+ software component. Value is encoded as a short(!) text string.
+
+ - **Measurement value**: It represents a hash of the invariant software
+ component in memory at start-up time. The value must be a cryptographic
+ hash of 256 bits or stronger. Value is encoded as a byte string.
+
+ - **Version**: It represents the issued software version. Value is encoded
+ as a text string.
+
+ - **Signer ID**: It represents the hash of a signing authority public key.
+ Value is encoded as a byte string.
+
+ - **Measurement description**: It represents the way in which the
+ measurement value of the software component is computed. Value is
+ encoded as text string containing an abbreviated description (name) of
+ the measurement method.
+
+**************
+Code structure
+**************
+
+The TF-M Measured Boot Service source and header files are located in current
+directory. The interfaces for the measured boot service are located in the
+``interface/include``. The headers to be included by applications that want
+to use functions from the API is ``measured_boot_api.h`` and
+``measured_boot_defs.h``.
+
+Service source files
+====================
+
+- Measured Boot Service:
+ - ``measured_boot.c`` : Implements core functionalities such as
+ implementation of APIs, extension and reading of measurements.
+ - ``measured_boot_api.c``: Implements the secure API layer to
+ allow other services in the secure domain to request functionalities
+ from the measured boot service using the PSA API interface.
+ - ``measured_boot_req_mngr.c``: Includes the initialization entry of
+ measured boot service and handles service requests in IPC model.
+
+Measured Boot Interfaces
+========================
+
+The TF-M Measured Boot service exposes the following interfaces:
+
+.. code-block:: c
+
+ psa_status_t tfm_measured_boot_read_measurement(
+ uint8_t index,
+ uint8_t *signer_id,
+ size_t signer_id_size,
+ size_t *signer_id_len,
+ uint8_t *version,
+ size_t version_size,
+ size_t *version_len,
+ uint32_t *measurement_algo,
+ uint8_t *sw_type,
+ size_t sw_type_size,
+ size_t *sw_type_len,
+ uint8_t *measurement_value,
+ size_t measurement_value_size,
+ size_t *measurement_value_len,
+ bool *is_locked);
+ psa_status_t tfm_measured_boot_extend_measurement(
+ uint8_t index,
+ const uint8_t *signer_id,
+ size_t signer_id_size,
+ const uint8_t *version,
+ size_t version_size,
+ uint32_t measurement_algo,
+ const uint8_t *sw_type,
+ size_t sw_type_size,
+ const uint8_t *measurement_value,
+ size_t measurement_value_size,
+ bool lock_measurement);
+
+When reading measurement, the caller must allocate large enough
+buffers to accommodate data for all the output measurement parameters.
+The definitions ``SIGNER_ID_MAX_SIZE``, ``VERSION_MAX_SIZE``,
+``SW_TYPE_MAX_SIZE``, and ``MEASUREMENT_VALUE_MAX_SIZE`` can be used to
+determine the required size of the buffers.
+
+System integrators might need to port these interfaces to a custom secure
+partition manager implementation (SPM). Implementations in TF-M project can be
+found in tf-m-extras repository.
+
+- ``partitions/measured_boot/interface/src/measured_boot_api.c``:
+ non-secure as well as secure interface implementation
+
+Related compile time options for out of tree build
+--------------------------------------------------
+- ``TFM_PARTITION_MEASURED_BOOT``: To include measured boot secure partition
+ and its services, its value should be ON. By default, it is switched OFF.
+
+- ``MEASURED_BOOT_HASH_ALG``: This option selects the hash algorithm used
+ for extension of measurement hashes. Its default value is PSA_ALG_SHA_256.
+
+- ``TFM_EXTRA_MANIFEST_LIST_FILES``: <tf-m-extras-repo>/partitions/
+ measured_boot/measured_boot_manifest_list.yaml
+
+- ``TFM_EXTRA_PARTITION_PATHS``: <tf-m-extras-repo>/partitions/measured_boot
+
+************
+Verification
+************
+
+Regression test
+===============
+
+To be implemented.
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/partitions.rst b/docs/partitions/partitions.rst
new file mode 100644
index 0000000..1bd240d
--- /dev/null
+++ b/docs/partitions/partitions.rst
@@ -0,0 +1,92 @@
+The list and simple introduction of 3rd-party Secure Partitions in this folder.
+
+######################
+dma350_upriv_partition
+######################
+
+***********
+Description
+***********
+DMA-350 Example unprivileged partition
+
+***********
+Maintainers
+***********
+- Bence Balogh `<bence.balogh@arm.com> <bence.balogh@arm.com>`_
+- Mark Horvath `<mark.horvath@arm.com> <mark.horvath@arm.com>`_
+
+#############
+measured_boot
+#############
+
+***********
+Description
+***********
+Measured boot partition for extending and retrieving software component
+measurements for RSS platform.
+
+***********
+Maintainers
+***********
+- Maulik Patel `<Maulik.Patel@arm.com>`_
+- David Vincze `<David.Vincze@arm.com>`_
+
+###############################
+external_trusted_secure_storage
+###############################
+
+***********
+Description
+***********
+ETSS partition for providing external trusted secure storage services
+to protect assets stored in external secure Flash from a variety of
+security attacks.
+
+***********
+Maintainers
+***********
+- Poppy Wu `<poppywu@mxic.com.cn>`_
+
+************
+TF-M version
+************
+TF-M V1.4.0
+
+#####################
+delegated_attestation
+#####################
+
+***********
+Description
+***********
+The aim of the partition is to support platforms/systems using a delegated
+attestation model by providing services for delegated key generation and
+platform attestation token creation.
+
+***********
+Maintainers
+***********
+- David Vincze `<David.Vincze@arm.com>`_
+
+############
+vad_an552_sp
+############
+
+***********
+Description
+***********
+Secure partition for the AN552 FPGA image. It implements voice activity
+detection on the microphone input of the MPS3 board, and if voice detected
+(which can be any noise) a short sample (~100 ms) is recorded. Then it can be
+calculated that which frequency component has the highest energy in the
+recorded sample.
+
+***********
+Maintainers
+***********
+- Gabor Toth `<gabor.toth@arm.com> <gabor.toth@arm.com>`_
+- Mark Horvath `<mark.horvath@arm.com> <mark.horvath@arm.com>`_
+
+---------------------------
+
+*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..4678dc5
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,10 @@
+graphviz
+Jinja2>=3.0.2
+latex
+Sphinx==4.2.0
+m2r2
+sphinx-rtd-theme>=1.0.0
+sphinxcontrib-plantuml==0.22
+sphinxcontrib-svg2pdfconverter==1.1.1
+sphinx-tabs==3.2.0
+docutils==0.16
