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/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.*