Doc: convert markdown files to rst
The official documentation format for TF-M is becoming Restructured
Text. This change converts the existing .md files to the new format.
Due to support for documentation of external code (/lib) md support is
kept.
Change-Id: I3c1aef5d22442e0c7c362a40a8d344a266dc0940
Signed-off-by: Gyorgy Szing <Gyorgy.Szing@arm.com>
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
new file mode 100644
index 0000000..d975dc0
--- /dev/null
+++ b/docs/_static/css/custom.css
@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2019, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+.wy-nav-content {
+ max-width: 85% !important;
+}
diff --git a/docs/coding_guide.md b/docs/coding_guide.md
deleted file mode 100644
index 2c4f6f6..0000000
--- a/docs/coding_guide.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Yet another coding standard :)
-
-`Every rule has an exception so if you disagree or dislike then reach out!`
-
-The coding style of TF-M project is based on
-[Linux coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html)
-but there are updates for domain specific conventions as listed below.
-
-TF-M also reuses code from other SW projects, e.g.`CMSIS_5`, which
-means some areas of code may have different styles. We use common sense approach
-and new code may inherit coding style from external projects but it needs to
-remain within clear scope.
-
-The guidance below is provided as a help. It isn't meant to be a definitive list.
-
-As implied in the [contributing guide](../contributing.md), maintainers have
-the right to decide on what's acceptable in case of any divergence.
-
-`Text files do not fall within these rules as they may require different formatting.`
-
-## Consistent style
-
-The code needs to be consistent with itself, so if existing code in the file
-violates listed coding style rules then it is better to follow existing style
-in the file and not break consistency by following the rules listed here.
-
-You may need to add a comment in the commit description to clarify this.
-
-## List of rules
-* Use 4 spaces indentation. No tabs.
-* Use `lower_case_with_underscore` for filenames, variable and function names.
-* Use standard types e.g. `uint32_t`, `uint16_t`, `uint8_t`, `int32_t` etc.
-* Use `uintptr_t` type when representing addresses as numbers.
-* Use static for all private functions and variables.
-* Use void argument if your function doesn't contain any argument.
-* Use C90 `/* */` for comments rather than C99 `//`
-* No trailing spaces in code.
-* Max 80 characters length. Text files are exception as stated above.
-* Open curly brace ' { ' at the same if/else/while/for/switch statement line.
-* Use curly braces ' { } ' for one line statement bodies also.
-* Put open curly brace in the line below the function header.
-* Order function parameters so that input params are before output params.
-* Declare local variables at the beginning of the function.
-* Define macros in all caps i.e. `CAPITAL_WITH_UNDERSCORE`.
-* Use typedefs ONLY for function prototype declarations.
-* Type definitions in `lower_case_with_underscore` ended by `_t`.
-* Do not use typedef for other constructs as it obfuscates code.
-* Do not use bitfields.
-* Use static for all global variables to reduce the variable scope.
-* Use enumeration for error codes to keep the code readable.
-* Use descriptive variable and functions names.
-* Put the correct license header at the beginning of the file.
-* Keep the files (.h/.c) self-contained, i.e. put include dependencies in the file.
-* Put appropriate header define guard in .h files: `__HEADER_NAME__`.
- Any divergence from this rules should be clearly documented.
-* In a .c file, #include it's own header file first.
-* Document all the public functions in the header file only.
-* Document all the private functions in the source file only.
-* Add "extern C " definition for C++ support in the header files.
-* In the switch statement, aligned cases with the switch keyword.
-* For enums, use upper case letters with digits and underscore only.
-* Do not code while eating.
-
---------------
-
-*Copyright (c) 2018, Arm Limited. All rights reserved.*
diff --git a/docs/coding_guide.rst b/docs/coding_guide.rst
new file mode 100644
index 0000000..166442a
--- /dev/null
+++ b/docs/coding_guide.rst
@@ -0,0 +1,78 @@
+##############################
+Yet another coding standard :)
+##############################
+
+.. Warning::
+
+ Every rule has an exception so if you disagree or dislike then reach out!
+
+The coding style of TF-M project is based on
+`Linux coding style <https://www.kernel.org/doc/html/v4.10/process/coding-style.html>`__
+but there are updates for domain specific conventions as listed below.
+
+TF-M also reuses code from other SW projects, e.g. ``CMSIS_5``, which
+means some areas of code may have different styles. We use common sense approach
+and new code may inherit coding style from external projects but it needs to
+remain within clear scope.
+
+The guidance below is provided as a help. It isn't meant to be a definitive
+list.
+
+As implied in the :doc:`contributing guide </contributing>` maintainers
+have the right to decide on what's acceptable in case of any divergence.
+
+.. Warning::
+
+ Text files do not fall within these rules as they may require different formatting.``
+
+****************
+Consistent style
+****************
+The code needs to be consistent with itself, so if existing code in the file
+violates listed coding style rules then it is better to follow existing style
+in the file and not break consistency by following the rules listed here.
+
+You may need to add a comment in the commit description to clarify this.
+
+List of rules
+=============
+
+- Use 4 spaces indentation. No tabs.
+- Use ``lower_case_with_underscore`` for filenames, variable and function names.
+- Use standard types e.g. ``uint32_t``, ``uint16_t``, ``uint8_t``, ``int32_t``
+ etc.
+- Use ``uintptr_t`` type when representing addresses as numbers.
+- Use static for all private functions and variables.
+- Use void argument if your function doesn't contain any argument.
+- Use C90 ``/* */`` for comments rather than C99 ``//``
+- No trailing spaces in code.
+- Max 80 characters length. Text files are exception as stated above.
+- Open curly brace ``{`` at the same if/else/while/for/switch statement line.
+- Use curly braces ``{ }`` for one line statement bodies also.
+- Put open curly brace in the line below the function header.
+- Order function parameters so that input params are before output params.
+- Declare local variables at the beginning of the function.
+- Define macros in all caps i.e. ``CAPITAL_WITH_UNDERSCORE``.
+- Use typedefs **ONLY** for function prototype declarations.
+- Type definitions in ``lower_case_with_underscore`` ended by ``_t``.
+- Do not use typedef for other constructs as it obfuscates code.
+- Do not use bitfields.
+- Use static for all global variables to reduce the variable scope.
+- Use enumeration for error codes to keep the code readable.
+- Use descriptive variable and functions names.
+- Put the correct license header at the beginning of the file.
+- Keep the files (.h/.c) self-contained, i.e. put include dependencies in the
+ file.
+- Put appropriate header define guard in .h files: ``__HEADER_NAME__``.
+ Any divergence from this rules should be clearly documented.
+- In a .c file, #include it's own header file first.
+- Document all the public functions in the header file only.
+- Document all the private functions in the source file only.
+- Add "extern C " definition for C++ support in the header files.
+- In the switch statement, aligned cases with the switch keyword.
+- For enums, use upper case letters with digits and underscore only.
+- Do not code while eating.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/conf.py.in b/docs/conf.py.in
index 1caebb2..b32bbdb 100644
--- a/docs/conf.py.in
+++ b/docs/conf.py.in
@@ -40,16 +40,26 @@
# If your documentation needs a minimal Sphinx version, state it here.
#
-# needs_sphinx = '1.0'
+# needs_sphinx = '1.4'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.imgmath',
- 'm2r',
+ 'm2r', #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
]
+#Location of PlantUML
+plantuml = '@Java_JAVA_EXECUTABLE@ -jar @PLANTUML_JAR_PATH@'
+
+#Make auso section labals generated be prefixed with file name.
+autosectionlabel_prefix_document=True
+#Add auso section label for level 1 headers only.
+autosectionlabel_maxdepth=1
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -89,11 +99,11 @@
# documentation.
#
# html_theme_options = {}
-
+#
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this 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']
+html_static_path = ['@TFM_ROOT_DIR@/docs/_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
@@ -108,6 +118,10 @@
#Disable adding conf.py copyright notice to HTML output
html_show_copyright = False
+#Add custom css for HTML. Used to allow full page width rendering
+def setup(app):
+ app.add_stylesheet('css/custom.css')
+
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
diff --git a/docs/dco.rst b/docs/dco.rst
new file mode 100644
index 0000000..7a5a4c3
--- /dev/null
+++ b/docs/dco.rst
@@ -0,0 +1,12 @@
+
+###############################
+Developer Certificate of Origin
+###############################
+
+.. include:: /dco.txt
+ :literal:
+
+
+-----------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst b/docs/index.rst
index f88134a..f9c1282 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,69 +13,70 @@
:maxdepth: 2
:glob:
:hidden:
-
- contributing.md
- glossary.md
- maintainers.md
- docs/user_guides/tfm_sw_requirement.md
- docs/user_guides/tfm_build_instruction.md
- docs/coding_guide.md
- docs/user_guides/tfm_user_guide.md
- docs/user_guides/os_migration_guide_armv8m.md
- docs/user_guides/tfm_integration_guide.md
- docs/user_guides/tfm_ns_client_identification.md
- docs/user_guides/tfm_secure_boot.md
-
+
+ contributing
+ docs/dco
+ glossary
+ maintainers
+ docs/user_guides/tfm_sw_requirement
+ docs/user_guides/tfm_build_instruction
+ docs/coding_guide
+ docs/user_guides/tfm_user_guide
+ docs/user_guides/os_migration_guide_armv8m
+ docs/user_guides/tfm_integration_guide
+ docs/user_guides/tfm_ns_client_identification
+ docs/user_guides/tfm_secure_boot
+
.. toctree::
:maxdepth: 2
:caption: Secure services
:glob:
:hidden:
-
+
docs/user_guides/services/*
-
+
.. toctree::
:maxdepth: 2
:caption: Components
:glob:
:hidden:
-
+
lib/**
-
+
.. toctree::
:maxdepth: 2
:caption: Target platforms
:glob:
:hidden:
-
+
platform/**
-
+
.. toctree::
:caption: Design documents
:maxdepth: 2
:glob:
:hidden:
-
+
docs/design_documents/*
-
+
.. toctree::
:caption: Draft design documents
:maxdepth: 2
:glob:
:hidden:
-
+
docs/design_documents/drafts/*
-
+
.. toctree::
:caption: Rejected design documents
:maxdepth: 2
:glob:
:hidden:
-
+
docs/design_documents/rejected/*
-.. mdinclude:: readme.md
+.. include:: readme.rst
-----------
-:Copyright: Copyright (c) 2019, Arm Limited. All rights reserved.
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/os_migration_guide_armv8m.md b/docs/user_guides/os_migration_guide_armv8m.md
deleted file mode 100644
index 9a14094..0000000
--- a/docs/user_guides/os_migration_guide_armv8m.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Generic OS migration from Armv7-M to Armv8-M architecture
-
-The purpose of this document is to list a set of requirements needed for
-migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
-
-## List of requirements
-
-* If the same OS codebase is used for both Secure and Non Secure builds, it is
-suggested to put specific code targeted to the Non Secure build under a compile
-time switch, e.g. `#if (DOMAIN_NS == 1U)`. The OS build system in this case
-needs to be amended accordingly to support this new switch.
-* If the OS implements stack limit checking, the `PSPLIM` register needs to be
-initialized and properly handled during thread context switch operations.
-* If the OS manipulates directly the Link Register, the default Link Register
-value used in Handler mode transitions needs to be differentiated between Secure
-and Non Secure builds, i.e. `0xFD` and `0xBC`, respectively.
-* If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
-as described
-[here](https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html)
-, and would like to use the non-secure client identification feature of TF-M,
-then it also have to use the `enum tfm_status_e tfm_register_client_id (int32_t
-ns_client_id)` API function provided by TF-M, as described in
-[NS client identification documentation](tfm_ns_client_identification.md).
-* if the OS doesn't support the API mentioned above, it should set
-`TFM_NS_CLIENT_IDENTIFICATION` to `OFF` in the cmake system.
-* **_Note: This is NOT REQUIRED when the Non Secure OS build is meant to be
-integrated with TF-M running in Secure world._** If generic function calls into
-Secure world have to be supported in Non Secure builds, integrate an API for
-secure stack memory management (e.g. the TrustZone API for secure stack memory
-management described in `tz_context.h`).
-
---------------
-
-*Copyright (c) 2018, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/os_migration_guide_armv8m.rst b/docs/user_guides/os_migration_guide_armv8m.rst
new file mode 100644
index 0000000..752c332
--- /dev/null
+++ b/docs/user_guides/os_migration_guide_armv8m.rst
@@ -0,0 +1,42 @@
+#########################################################
+Generic OS migration from Armv7-M to Armv8-M architecture
+#########################################################
+The purpose of this document is to list a set of requirements needed for
+migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
+
+********************
+List of requirements
+********************
+- If the same OS codebase is used for both Secure and Non Secure builds, it is
+ suggested to put specific code targeted to the Non Secure build under a
+ compile time switch, e.g. ``#if (DOMAIN_NS == 1U)``. The OS build system in
+ this case needs to be amended accordingly to support this new switch.
+- If the OS implements stack limit checking, the ``PSPLIM`` register
+ needs to be initialized and properly handled during thread context switch
+ operations.
+- If the OS manipulates directly the Link Register, the default Link Register
+ value used in Handler mode transitions needs to be differentiated between
+ Secure and Non Secure builds, i.e. ``0xFD`` and ``0xBC``, respectively.
+- If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
+ as described
+ `here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
+ , and would like to use the non-secure client identification feature of TF-M,
+ then it also have to use the
+ ``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)``
+ API function provided by TF-M, as described in
+ :doc:`NS client identification documentation <tfm_ns_client_identification>`.
+- if the OS doesn't support the API mentioned above, it should set
+ ``TFM_NS_CLIENT_IDENTIFICATION`` to ``OFF`` in the cmake system.
+- .. Note::
+
+ This is NOT REQUIRED when the Non Secure OS build is meant
+ to be integrated with TF-M running in Secure world.
+
+ If generic function calls into Secure world have to be supported in Non Secure
+ builds, integrate an API for secure stack memory management (e.g. the
+ TrustZone API for secure stack memory management described in
+ ``tz_context.h``).
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_attestation_integration_guide.md b/docs/user_guides/services/tfm_attestation_integration_guide.md
deleted file mode 100644
index d6085f4..0000000
--- a/docs/user_guides/services/tfm_attestation_integration_guide.md
+++ /dev/null
@@ -1,396 +0,0 @@
-# TF-M Initial Attestation Service Integration Guide
-
-## Introduction
-TF-M Initial Attestation Service allows the application to prove the device
-identity during an authentication process to a verification entity. The initial
-attestation service can create a token on request, which contains a fix set of
-device specific data. Device must contain an attestation key pair, which is
-unique per device. The token is signed with the private part of attestation key
-pair. The public part of the key pair is known by the verification entity. The
-public key is used to verify the token authenticity. The data items in the token
-used to verify the device integrity and assess its trustworthiness. Attestation
-key provisioning is out of scope for the attestation service and is expected to
-take part during manufacturing of the device.
-
-## Current service limitations
-- **Signing of token** - In the current implementation the token is not properly
-signed. Signature is generated according to the
-[COSE](https://datatracker.ietf.org/doc/rfc8152/) format. But its actual value
-is not a correct ECDSA P256 signature, due to the lack of support of the ECDSA
-algorithm in the current implementation of the TF-M Crypto service. A fake
-signature is created, which is the concatenation of the token's hash value
-twice.
-
-## Claims in the initial attestation token
-The initial attestation token is formed of claims. A claim is a data item,
-which is represented in a key - value structure. The following fixed set of
-claims are included in the token:
-- **Challenge**: Input object from caller. Can be a single nonce from server or
-hash of nonce and attested data. It is intended to provide freshness to reports
-and the caller has responsibility to arrange this. Allowed length: 32, 48,
-64 bytes. The claim is modeled to be eventually represented by the EAT standard
-claim nonce. Until such a time as that standard exists, the claim will be
-represented by a custom claim. Value is encoded as byte string.
-
-- **Instance ID**: It represents the unique identifier of the instance. In the
-PSA definition it is a hash of the public attestation key of the instance. The
-claim is modeled to be eventually represented by the EAT standard claim UEID of
-type GUID. Until such a time as that standard exists, the claim will be
-represented by a custom claim Value is encoded as byte string.
-
-- **Verification service indicator**: Optional, recommended claim. It is used by
-a Relying Party to locate a validation service for the token. The value is a
-text string that can be used to locate the service or a URL specifying the
-address of the service. The claim is modeled to be eventually represented by
-the EAT standard claim origination. Until such a time as that standard exists,
-the claim will be represented by a custom claim. Value is encoded as text
-string.
-
-- **Profile definition**: Optional, recommended claim. It contains the name of a
-document that describes the 'profile' of the token, being a full description of
-the claims, their usage, verification and token signing. The document name may
-include versioning. Custom claim with a value encoded as text string.
-
-- **Implementation ID**: It represents the original implementation signer of the
-attestation key and identifies the contract between the report and verification.
-A verification service will use this claim to locate the details of the
-verification process. Custom claim with a value encoded as byte string.
-
-- **Security lifecycle**: It represents the current lifecycle state of the
-instance. Custom claim with a value encoded as an integer.
-
-- **Client ID**: The partition ID of that secure partition or non-secure thread
-who called the initial attestation API. Custom claim with a value encoded as a
-`signed` integer. Negative number represents non-secure caller, positive numbers
-represents secure callers, zero is invalid.
-
-- **HW version**: Optional claim. Globally unique number in EAN-13 format
-identifying the GDSII that went to fabrication, HW and ROM. It can be used to
-reference the security level of the PSA-ROT via a certification website. Custom
-claim with a value is encoded as text string.
-
-- **Boot seed**: It represents a random value created at system boot time that
-will allow differentiation of reports from different system sessions. The size
-is 32 bytes. Custom claim with a value is encoded as byte string.
-
-- **Software components**: Optional, recommended claim. It represents the
-software state of the system. The value of the claim is an array of CBOR map
-entries, with one entry per software component within the device. Each map
-contains multiple claims that describe evidence about the details of the
-software component.
-
- - **Measurement type**: Optional claim. It represents the role of the software
- component. Value is encoded as 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 byte string.
-
- - **Security epoch**: Optional claim. It represents the security control point
- of the software component. Value is encoded as unsigned integer.
-
- - **Version**: Optional claim. It represents the issued software version. Value
- is encoded as text string.
-
- - **Signer ID**: It represents the hash of a signing authority public key.
- Value is encoded as byte string.
-
- - **Measurement description**: Optional claim. 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.
-
-- **No software measurements**: In the event that the implementation does not
-contain any software measurements then the software components claim above can
-be omitted but instead it is mandatory to include this claim to indicate this is
-a deliberate state. Custom claim a value is encoded as an unsigned integer set
-to 1.
-
-## Initial attestation token (IAT) data encoding
-The initial attestation token is planned to be aligned with future version of
-[Entity Attestation Token](https://tools.ietf.org/html/draft-mandyam-eat-01)
-format. The token is encoded according to the
-[CBOR](https://tools.ietf.org/html/rfc7049) format and signed according to
-[COSE](https://tools.ietf.org/html/rfc8152) standard.
-
-## Code structure
-The PSA interface for the Initial Attestation Service is located in
-`interface/include`.
-The only header to be included by applications that want to use functions from
-the PSA API is `psa_initial_attestation.h`.
-The TF-M Initial Attestation Service source files are located in
-`secure_fw/services/initial_attestation`.
-The CBOR library is located in `lib/ext/qcbor` folder.
-
-### Service source files
-- CBOR library:
- - `lib/ext/qcbor`: This library is used to create a proper CBOR token. It can
- be used on 32-bit and 64-bit machines. It was designed to suite constrained
- devices with low memory usage and without dynamic memory allocation. It is a
- fork of this external
- [QCBOR library](https://github.com/laurencelundblade/QCBOR).
- - `lib/ext/qcbor/inc/qcbor.h`: Public API documentation of CBOR library.
-- COSE library:
- - `lib/t_cose`: This library is used to sign a CBOR token and create the COSE
- header and signature around the initial attestation token. Only a subset of the
- [COSE](https://tools.ietf.org/html/rfc8152) standard is implemented. Only the
- cose_sign1 signature schema is supported.
- - `lib/t_cose/src/t_cose_crypto.h`: Expose an API to bind `t_cose` library with
- available crypto library in the device.
- - `lib/t_cose/src/t_cose_psa_crypto.c`: Implements the exposed API and ports
- `t_cose` to psa_crypto library.
-- Initial Attestation Service:
- - `attestation_core.c` : Implements core functionalities such as implementation
- of APIs, retrieval of claims and token creation.
- - `attest_token.c`: Implements the token creation function such as start and
- finish token creation and adding claims to the token.
- - `attestation_crypto_stub.c`: Temporary file, it implements the missing
- psa_crypto APIs.
- - `attestation_key.c`: Get the attestation key from platform layer and register
- it to psa_crypto service for further usage.
- - `tfm_attestation.c`: Implements the SPM abstraction layer, and bind the
- attestation service to the SPM implementation in TF-M project.
- - `tfm_attestation_secure_api.c`: Implements the secure API layer to allow
- other services in the secure domain to request functionalities from the
- attestation service using the PSA API interface.
-
-### Service interface definitions
-- **Boot loader interface**: The attestation service might include data in the
-token about the distinct software components in the device. This data is
-provided by the boot loader and must be encoded in the TLV format, definition
-is described below in the boot loader interface paragraph. Possible claims in
-the boot status are describe above in the software components paragraph.
-- **Hardware abstraction layer**:
- - Headers are located in `platform/include` folder.
- - `tfm_attest_hal.h`: Expose an API to get the following claims: security
- lifecycle, verification service indicator, profile definition.
- - `tfm_plat_boot_seed.h`: Expose an API to get the boot seed claim.
- - `tfm_plat_device_id.h`: Expose an API to get the following claims:
- implementation ID, hardware version, instance ID.
-- **SPM interface**:
- - `attestation.h`: Expose an API to bind attestation service to an SPM
- implementation.
-- **PSA interface**:
- - `psa_initial_attestation.h`: Public API definition of initial attestation
- service.
-- **Crypto interface**:
- - `t_cose_crypto.h`: Expose an API to bind the `t_cose` implementation to any
- cryptographic library.
- - `tfm_plat_crypto_keys.h`: Expose an API to get the attestation key from
- platform layer.
-
-### PSA interface
-The TF-M Initial Attestation Service exposes the following PSA interface:
- ``` c
- enum psa_attest_err_t
- psa_initial_attest_get_token(const uint8_t *challenge_obj,
- uint32_t challenge_size,
- uint8_t *token,
- uint32_t *token_size);
-
-enum psa_attest_err_t
-psa_initial_attest_get_token_size(uint32_t challenge_size,
- uint32_t *token_size);
-```
-The caller must allocate a large enough buffer, where the token is going to be
-created by Initial Attestation Service. The size of the created token is highly
-dependent on the number of software components in the system and the provided
-attributes of these.
-The `psa_initial_attest_get_token_size()` function can be called to get the
-exact size of the created token.
-
-System integrators might need to port these interfaces to a custom secure
-partition manager implementation (SPM). Implementation in TF-M project can be
-found here:
-- `interface/src/tfm_initial_attestation_api.c`: non-secure interface
-implementation
-- `secure_fw/services/initial_attestation/tfm_attestation_secure_api.c`: secure
-interface implementation
-
-### Secure Partition Manager (SPM) interface
-The Initial Attestation Service defines the following interface towards the
-secure partition manager (SPM). System integrators **must** port this
-interface according to their SPM implementation.
-```c
-enum psa_attest_err_t
-attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
-
-enum psa_attest_err_t
-attest_get_caller_client_id(int32_t *caller_id);
-
-enum psa_attest_err_t
-attest_check_memory_access(void *addr,
- uint32_t size,
- enum attest_memory_access access);
-```
-- `attest_get_boot_data()`: Service can retrieve the relevant data from shared
-memory area between boot loader and runtime software. It might be the case that
-only SPM has direct access to the shared memory area, therefore this function
-can be used to copy the service related data from shared memory to a local
-memory buffer. In TF-M implementation this function must be called during
-service initialization phase, because the shared memory region is deliberately
-overlapping with secure main stack to spare some memory and reuse this area
-during execution. If boot loader is not available in the system to provide
-attributes of software components then this function must be implemented in a
-way that just initialize service's memory buffer to:
- ```c
- struct shared_data_tlv_header *tlv_header =
- (struct shared_data_tlv_header *)ptr;
- tlv_header->tlv_magic = 2016;
- tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
- ```
-
-- `attest_get_caller_client_id()`: Retrieves the ID of the caller thread.
-- `attest_check_memory_access()`: Validates the availability and access rights
-of memory regions received as input data: challenge object, token buffer, etc.
-- `tfm_client.h`: Service relies on the following external definitions, which
-must be present or included in this header file:
-
- ```c
- typedef struct psa_invec {
- const void *base;
- size_t len;
- } psa_invec;
-
- typedef struct psa_outvec {
- void *base;
- size_t len;
- } psa_outvec;
- ```
-
-### Hardware abstraction layer:
-The following API definitions are intended to retrieve the platform specific
-claims. System integrators **must** implement these interface according to their
-SoC and software design. Detailed definition of the claims are above in the
-claims in the initial attestation token paragraph.
-- `tfm_attest_hal_get_security_lifecycle()`: Get the security lifecycle of the
-device.
-- `tfm_attest_hal_get_verification_service()`: Get the verification service
-indicator for initial attestation.
-- `tfm_attest_hal_get_profile_definition()`: Get the name of the profile
-definition document for initial attestation.
-- `tfm_plat_get_boot_seed()`: Get the boot seed, which is a constant random
-number during a boot cycle.
-- `tfm_plat_get_instance_id()`: Get the UEID of the device.
-- `tfm_plat_get_implementation_id`: Get the implementation ID of the device.
-- `tfm_plat_get_hw_version`: Get the hardware version of the device.
-
-### Boot loader interface
-It is **recommended** to have a secure boot loader in the boot chain, which is
-capable of measuring the runtime firmware components (calculates the hash value
-of firmware images) and provide other attributes of these (version, type, etc).
-
-The shared data between boot loader and runtime software is TLV encoded. The
-definition of TLV structure is described in `bl2/include/tfm_boot_status.h`.
-The shared data is stored in a well known location in secure internal memory
-and this is a contract between boot loader and runtime SW.
-
-The structure of shared data must be the following:
- - At the beginning there must be a header: `struct shared_data_tlv_header`
- This contains a magic number and a size field which covers the entire
- size of the shared data area including this header.
- ```c
- struct shared_data_tlv_header {
- uint16_t tlv_magic;
- uint16_t tlv_tot_len;
- };
- ```
- - After the header there come the entries which are composed from an entry
- header structure: `struct shared_data_tlv_entry` and the data. In the entry
- header is a type field `tlv_type` which identify the consumer of the entry
- in the runtime software and specify the subtype of that data item. There is
- a size field `tlv_len` which covers the size of the entry header and the
- data. After this structure comes the actual data.
- ```c
- struct shared_data_tlv_entry {
- uint16_t tlv_type;
- uint16_t tlv_len;
- };
- ```
- - Arbitrary number and size of data entry can be in the shared memory area.
-
-The table below gives of overview about the `tlv_type` field in the entry
-header. The `tlv_type` always composed from a major and minor number. Major
-number identifies the addressee in runtime software, which the data entry is
-sent to. Minor number used to encode more info about the data entry. The actual
-definition of minor number could change per major number. In case of boot
-status data, which is going to be processed by initial attestation service
-the minor number is split further to two part: `sw_module` and `claim`. The
-`sw_module` identifies the SW component in the system which the data item
-belongs to and the `claim` part identifies the exact type of the data.
-
-`tlv_type` description:
-```
-|------------------------------------------------ |
-| tlv_type (16 bits) |
-|-------------------------------------------------|
-| tlv_major(4 bits) | tlv_minor(12 bits) |
-|-------------------------------------------------|
-| MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
-|-------------------------------------------------|
-| MAJOR_CORE | TBD |
-|-------------------------------------------------|
-```
-
-Overall structure of shared data:
-```
----------------------------------------------------------------
-| Magic number(uint16_t) | Shared data total length(uint16_t) |
----------------------------------------------------------------
-| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
----------------------------------------------------------------
-| Raw data |
----------------------------------------------------------------
-| . |
-| . |
-| . |
----------------------------------------------------------------
-| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
----------------------------------------------------------------
-| Raw data |
----------------------------------------------------------------
-```
-
-### Crypto interface
-Device **must** contain an asymmetric key pair. The private part of it is used
-to sign the initial attestation token. Current implementation supports only the
-ECDSA P256 signature over SHA256. The public part of the key pair is used to
-create the key identifier (kid) in the unprotected part of the COSE header. The
-kid is used by verification entity to look up the corresponding public key to
-verify the signature in the token. The `t_cose` part of the initial attestation
-service implements the signature generation and kid creation. But the actual
-calculation of token's hash and signature is done by the Crypto service in the
-device. System integrators might need to re-implement the following functions
-if they want to use initial attestation service with a different cryptographic
-library than Crypto service:
-- `t_cose_crypto_pub_key_sign()`: Calculates the signature over a hash value.
-- `t_cose_crypto_get_ec_pub_key()`: Get the public key to create the key
-identifier.
-- `t_cose_crypto_hash_start()`: Start a multipart hash operation.
-- `t_cose_crypto_hash_update()`: Add a message fragment to a multipart hash
-operation.
-- `t_cose_crypto_hash_finish()`:Finish the calculation of the hash of a message.
-
-Interface needed by verification code:
-- `t_cose_crypto_pub_key_verify()`: Verify the signature over a hash value.
-
-#### Key handling
-The provisioning of the initial attestation key is out of scope of the service
-and this document. It is assumed that device maker provisions the unique
-asymmetric key pair during the manufacturing process. The following API is
-defined to retrieve the attestation key pair from platform layer. Software
-integrators **must** port this interface according to their SoC design and make
-sure that key pair is available by Crypto service:
-- `tfm_plat_get_initial_attest_key()`: Retrieve the initial attestation key pair
-from platform layer.
-
-In TF-M project the attestation key is retrieved by initial attestation service.
-The key is registered and unregistered to the Crypto service by attestation
-service with `psa_import_key()` and `psa_destroy_key()` API calls for further
-usage. See in `attestation_key.c`. In other implementation if the attestation
-key is directly retrieved by the Crypto service then this key handling is not
-necessary.
-
- --------------
-
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_attestation_integration_guide.rst b/docs/user_guides/services/tfm_attestation_integration_guide.rst
new file mode 100644
index 0000000..e4d49a2
--- /dev/null
+++ b/docs/user_guides/services/tfm_attestation_integration_guide.rst
@@ -0,0 +1,440 @@
+##################################################
+TF-M Initial Attestation Service Integration Guide
+##################################################
+
+************
+Introduction
+************
+TF-M Initial Attestation Service allows the application to prove the device
+identity during an authentication process to a verification entity. The initial
+attestation service can create a token on request, which contains a fix set of
+device specific data. Device must contain an attestation key pair, which is
+unique per device. The token is signed with the private part of attestation key
+pair. The public part of the key pair is known by the verification entity. The
+public key is used to verify the token authenticity. The data items in the token
+used to verify the device integrity and assess its trustworthiness. Attestation
+key provisioning is out of scope for the attestation service and is expected to
+take part during manufacturing of the device.
+
+***************************
+Current service limitations
+***************************
+**Signing of token**: In the current implementation the token is not properly
+signed. Signature is generated according to the
+`COSE <https://datatracker.ietf.org/doc/rfc8152/>`__ format. But its actual
+value is not a correct ECDSA P256 signature, due to the lack of support of the
+ECDSA algorithm in the current implementation of the TF-M Crypto service. A fake
+signature is created, which is the concatenation of the token's hash value
+twice.
+
+***************************************
+Claims in the initial attestation token
+***************************************
+The initial attestation token is formed of claims. A claim is a data item,
+which is represented in a key - value structure. The following fixed set of
+claims are included in the token:
+
+ - **Challenge**: Input object from caller. Can be a single nonce from
+ server or hash of nonce and attested data. It is intended to provide
+ freshness to report and the caller has responsibility to arrange
+ this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be
+ eventually represented by the EAT standard claim nonce. Until such a
+ time as that standard exists, the claim will be represented by a custom
+ claim. Value is encoded as byte string.
+
+ - **Instance ID**: It represents the unique identifier of the instance. In
+ the PSA definition it is a hash of the public attestation key of the
+ instance. The claim is modeled to be eventually represented by the EAT
+ standard claim UEID of type GUID. Until such a time as that standard
+ exists, the claim will be represented by a custom claim Value is encoded
+ as byte string.
+
+ - **Verification service indicator**: Optional, recommended claim. It
+ is used by a Relying Party to locate a validation service for the
+ token. The value is a text string that can be used to locate the service
+ or a URL specifying the address of the service. The claim is modelled to
+ be eventually represented by the EAT standard claim origination. Until
+ such a time as that standard exists, the claim will be represented by
+ a custom claim. Value is encoded as text string.
+
+ - **Profile definition**: Optional, recommended claim. It contains the
+ name of a document that describes the 'profile' of the token, being
+ a full description of the claims, their usage, verification and token
+ signing. The document name may include versioning. Custom claim with a
+ value encoded as text string.
+
+ - **Implementation ID**: It represents the original implementation
+ signer of the attestation key and identifies the contract between the
+ report and verification. A verification service will use this claim
+ to locate the details of the verification process. Custom claim with a
+ value encoded as byte string.
+
+ - **Security lifecycle**: It represents the current lifecycle state of
+ the instance. Custom claim with a value encoded as an integer.
+
+ - **Client ID**: The partition ID of that secure partition or non-secure
+ thread who called the initial attestation API. Custom claim with a value
+ encoded as a `signed` integer. Negative number represents non-secure
+ caller, positive numbers represents secure callers, zero is invalid.
+
+ - **HW version**: Optional claim. Globally unique number in EAN-13 format
+ identifying the GDSII that went to fabrication, HW and ROM. It can be
+ used to reference the security level of the PSA-ROT via a certification
+ website. Custom claim with a value is encoded as text string.
+
+ - **Boot seed**: It represents a random value created at system boot
+ time that will allow differentiation of reports from different system
+ sessions. The size is 32 bytes. Custom claim with a value is encoded as
+ byte string.
+
+ - **Software components**: Optional, recommended claim. It represents
+ the software state of the system. The value of the claim is an array
+ of CBOR map entries, with one entry per software component within the
+ device. Each map contains multiple claims that describe evidence about
+ the details of the software component.
+
+ - **Measurement type**: Optional claim. It represents the role of the
+ software component. Value is encoded as 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 byte string.
+
+ - **Security epoch**: Optional claim. It represents the security control
+ point of the software component. Value is encoded as unsigned integer.
+
+ - **Version**: Optional claim. It represents the issued software
+ version. Value is encoded as text string.
+
+ - **Signer ID**: It represents the hash of a signing authority public key.
+ Value is encoded as byte string.
+
+ - **Measurement description**: Optional claim. 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.
+
+ - **No software measurements**: In the event that the implementation
+ does not contain any software measurements then the software components
+ claim above can be omitted but instead it is mandatory to include this
+ claim to indicate this is a deliberate state. Custom claim a value is
+ encoded as an unsigned integer set to 1.
+
+*********************************************
+Initial attestation token (IAT) data encoding
+*********************************************
+The initial attestation token is planned to be aligned with future version of
+`Entity Attestation Token <https://tools.ietf.org/html/draft-mandyam-eat-01>`__
+format. The token is encoded according to the
+`CBOR <https://tools.ietf.org/html/rfc7049>`__ format and signed according to
+`COSE <https://tools.ietf.org/html/rfc8152>`__ standard.
+
+**************
+Code structure
+**************
+The PSA interface for the Initial Attestation Service is located in
+``interface/include``. The only header to be included by applications that want
+to use functions from the PSA API is ``psa_initial_attestation.h``.
+
+The TF-M Initial Attestation Service source files are located in
+``secure_fw/services/initial_attestation``.
+The CBOR library is located in ``lib/ext/qcbor`` folder.
+
+Service source files
+====================
+- CBOR library
+ - ``lib/ext/qcbor`` This library is used to create a proper CBOR token.
+ It can be used on 32-bit and 64-bit machines. It was designed to suite
+ constrained devices with low memory usage and without dynamic memory
+ allocation.
+ It is a fork of this external `QCBOR library <https://github.com/laurencelundblade/QCBOR>`__.
+ - ``lib/ext/qcbor/inc/qcbor.h``: Public API documentation of CBOR
+ library.
+
+- COSE library:
+ - ``lib/t_cose``: This library is used to sign a CBOR token and create
+ the COSE header and signature around the initial attestation token. Only
+ a subset of the `COSE <https://tools.ietf.org/html/rfc8152>`__ standard
+ is implemented. Only the cose_sign1 signature schema is supported.
+ - ``lib/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose``
+ library with available crypto library in the device.
+ - ``lib/t_cose/src/t_cose_psa_crypto.c``: Implements the exposed API
+ and ports ``t_cose`` to psa_crypto library.
+ - Initial Attestation Service:
+ - ``attestation_core.c`` : Implements core functionalities such as
+ implementation of APIs, retrieval of claims and token creation.
+ - ``attest_token.c``: Implements the token creation function such as
+ start and finish token creation and adding claims to the token.
+ - ``attestation_crypto_stub.c``: Temporary file, it implements the
+ missing psa_crypto APIs.
+ - ``attestation_key.c``: Get the attestation key from platform layer
+ and register it to psa_crypto service for further usage.
+ - ``tfm_attestation.c``: Implements the SPM abstraction layer, and bind
+ the attestation service to the SPM implementation in TF-M project.
+ - ``tfm_attestation_secure_api.c``: Implements the secure API layer to
+ allow other services in the secure domain to request functionalities
+ from the attestation service using the PSA API interface.
+
+Service interface definitions
+=============================
+- **Boot loader interface**: The attestation service might include data
+ in the token about the distinct software components in the device. This data
+ is provided by the boot loader and must be encoded in the TLV format,
+ definition is described below in the boot loader interface paragraph. Possible
+ claims in the boot status are describe above in the software components
+ paragraph.
+- **Hardware abstraction layer**:
+ - Headers are located in ``platform/include`` folder.
+ - ``tfm_attest_hal.h``: Expose an API to get the following claims:
+ security lifecycle, verification service indicator, profile definition.
+ - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim.
+ - ``tfm_plat_device_id.h``: Expose an API to get the following claims:
+ implementation ID, hardware version, instance ID.
+- **SPM interface**:
+ - ``attestation.h``: Expose an API to bind attestation service to an SPM
+ implementation.
+- **PSA interface**:
+ - ``psa_initial_attestation.h``: Public API definition of initial
+ attestation service.
+- **Crypto interface**:
+ - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation
+ to any cryptographic library.
+ - ``tfm_plat_crypto_keys.h``: Expose an API to get the attestation key from
+ platform layer.
+
+PSA interface
+=============
+The TF-M Initial Attestation Service exposes the following PSA
+interface:
+
+.. code-block:: c
+
+ enum psa_attest_err_t
+ psa_initial_attest_get_token(const uint8_t *challenge_obj,
+ uint32_t challenge_size,
+ uint8_t *token,
+ uint32_t *token_size);
+
+ enum psa_attest_err_t
+ psa_initial_attest_get_token_size(uint32_t challenge_size,
+ uint32_t *token_size);
+
+The caller must allocate a large enough buffer, where the token is going to be
+created by Initial Attestation Service. The size of the created token is highly
+dependent on the number of software components in the system and the provided
+attributes of these. The ``psa_initial_attest_get_token_size()`` function can be
+called to get the exact size of the created token.
+
+System integrators might need to port these interfaces to a custom secure
+partition manager implementation (SPM). Implementation in TF-M project can be
+found here:
+
+- ``interface/src/tfm_initial_attestation_api.c``: non-secure interface
+ implementation
+- ``secure_fw/services/initial_attestation/tfm_attestation_secure_api.c``:
+ secure interface implementation
+
+Secure Partition Manager (SPM) interface
+========================================
+The Initial Attestation Service defines the following interface towards the
+secure partition manager (SPM). System integrators **must** port this interface
+according to their SPM implementation.
+
+.. code:: c
+
+ enum psa_attest_err_t
+ attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
+
+ enum psa_attest_err_t
+ attest_get_caller_client_id(int32_t *caller_id);
+
+ enum psa_attest_err_t
+ attest_check_memory_access(void *addr,
+ uint32_t size,
+ enum attest_memory_access access);
+
+- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared
+ memory area between boot loader and runtime software. It might be the case
+ that only SPM has direct access to the shared memory area, therefore this
+ function can be used to copy the service related data from shared memory to
+ a local memory buffer. In TF-M implementation this function must be called
+ during service initialization phase, because the shared memory region is
+ deliberately overlapping with secure main stack to spare some memory and reuse
+ this area during execution. If boot loader is not available in the system to
+ provide attributes of software components then this function must be
+ implemented in a way that just initialize service's memory buffer to:
+
+ .. code-block:: c
+
+ struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr;
+ tlv_header->tlv_magic = 2016;
+ tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
+
+- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread.
+- ``attest_check_memory_access()``: Validates the availability and access rights
+ of memory regions received as input data: challenge object, token buffer, etc.
+- ``tfm_client.h``: Service relies on the following external definitions, which
+ must be present or included in this header file:
+
+ .. code-block:: c
+
+ typedef struct psa_invec {
+ const void *base;
+ size_t len;
+ } psa_invec;
+
+ typedef struct psa_outvec {
+ void *base;
+ size_t len;
+ } psa_outvec;
+
+Hardware abstraction layer
+==========================
+The following API definitions are intended to retrieve the platform specific
+claims. System integrators **must** implement these interface according to their
+SoC and software design. Detailed definition of the claims are above
+in the claims in the initial attestation token paragraph.
+
+- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the
+ device.
+- ``tfm_attest_hal_get_verification_service()``: Get the verification
+ service indicator for initial attestation.
+- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile
+ definition document for initial attestation.
+- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random
+ number during a boot cycle.
+- ``tfm_plat_get_instance_id()``: Get the UEID of the device.
+- ``tfm_plat_get_implementation_id``: Get the implementation ID of the
+ device.
+- ``tfm_plat_get_hw_version``: Get the hardware version of the device.
+
+Boot loader interface
+=====================
+It is **recommended** to have a secure boot loader in the boot chain, which is
+capable of measuring the runtime firmware components (calculates the hash value
+of firmware images) and provide other attributes of these (version, type, etc).
+
+The shared data between boot loader and runtime software is TLV encoded. The
+definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``.
+The shared data is stored in a well known location in secure internal memory
+and this is a contract between boot loader and runtime SW.
+
+The structure of shared data must be the following:
+
+- At the beginning there must be a header: ``struct shared_data_tlv_header``
+ This contains a magic number and a size field which covers the entire size
+ of the shared data area including this header.
+
+ .. code-block:: c
+
+ struct shared_data_tlv_header {
+ uint16_t tlv_magic;
+ uint16_t tlv_tot_len;
+ };
+
+- After the header there come the entries which are composed from an
+ entry header structure: ``struct shared_data_tlv_entry`` and the data. In
+ the entry header is a type field ``tlv_type`` which identify the consumer of
+ the entry in the runtime software and specify the subtype of that data item.
+ There is a size field ``tlv_len`` which covers the size of the entry header
+ and the data. After this structure comes the actual data.
+
+ .. code-block:: c
+
+ struct shared_data_tlv_entry {
+ uint16_t tlv_type;
+ uint16_t tlv_len;
+ };
+
+- Arbitrary number and size of data entry can be in the shared memory
+ area.
+
+The figure below gives of overview about the ``tlv_type`` field in the entry
+header. The ``tlv_type`` always composed from a major and minorbnumber. Major
+number identifies the addressee in runtime software, which the databentry is
+sent to. Minor number used to encode more info about the data entry. The actual
+definition of minor number could change per major number. In case of boot
+status data, which is going to be processed by initial attestation service
+the minor number is split further to two part: ``sw_module`` and ``claim``. The
+``sw_module`` identifies the SW component in the system which the data item
+belongs to and the ``claim`` part identifies the exact type of the data.
+
+``tlv_type`` description::
+
+ |------------------------------------------------ |
+ | tlv_type (16 bits) |
+ |-------------------------------------------------|
+ | tlv_major(4 bits) | tlv_minor(12 bits) |
+ |-------------------------------------------------|
+ | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
+ |-------------------------------------------------|
+ | MAJOR_CORE | TBD |
+ |-------------------------------------------------|
+
+Overall structure of shared data::
+
+ ---------------------------------------------------------------
+ | Magic number(uint16_t) | Shared data total length(uint16_t) |
+ ---------------------------------------------------------------
+ | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
+ ---------------------------------------------------------------
+ | Raw data |
+ ---------------------------------------------------------------
+ | . |
+ | . |
+ | . |
+ ---------------------------------------------------------------
+ | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
+ ---------------------------------------------------------------
+ | Raw data |
+ ---------------------------------------------------------------
+
+Crypto interface
+================
+Device **must** contain an asymmetric key pair. The private part of it is used
+to sign the initial attestation token. Current implementation supports only the
+ECDSA P256 signature over SHA256. The public part of the key pair is used to
+create the key identifier (kid) in the unprotected part of the COSE header. The
+kid is used by verification entity to look up the corresponding public key to
+verify the signature in the token. The `t_cose` part of the initial attestation
+service implements the signature generation and kid creation. But the actual
+calculation of token's hash and signature is done by the Crypto service in the
+device. System integrators might need to re-implement the following functions
+if they want to use initial attestation service with a different cryptographic
+library than Crypto service:
+
+- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value.
+- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key
+ identifier.
+- ``t_cose_crypto_hash_start()``: Start a multipart hash operation.
+- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash
+ operation.
+- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a
+ message.
+
+Interface needed by verification code:
+
+- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value.
+
+Key handling
+------------
+The provisioning of the initial attestation key is out of scope of the service
+and this document. It is assumed that device maker provisions the unique
+asymmetric key pair during the manufacturing process. The following API is
+defined to retrieve the attestation key pair from platform layer. Software
+integrators **must** port this interface according to their SoC design and make
+sure that key pair is available by Crypto service:
+
+- ``tfm_plat_get_initial_attest_key()``: Retrieve the initial attestation key
+ pair from platform layer.
+
+In TF-M project the attestation key is retrieved by initial attestation service.
+The key is registered and unregistered to the Crypto service by attestation
+service with ``psa_import_key()`` and ``psa_destroy_key()`` API calls for
+further usage. See in ``attestation_key.c``. In other implementation if the
+attestation key is directly retrieved by the Crypto service then this key
+handling is not necessary.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_audit_integration_guide.md b/docs/user_guides/services/tfm_audit_integration_guide.md
deleted file mode 100644
index 3bd0ba8..0000000
--- a/docs/user_guides/services/tfm_audit_integration_guide.md
+++ /dev/null
@@ -1,116 +0,0 @@
-# TF-M Audit Logging Service Integration Guide
-
-## Introduction
-
-TF-M Audit logging service allows secure services in the system to log critical
-system events and information that have security implications. This is required
-to post analyse the system behaviour, system events and triage system issues
-offline. This offers a mitigation against the repudiation threat.
-
-The types of information that can be logged are the ID of the entity that
-originated a secure service request, or the relevant output or data
-associated to the authentication mechanism that the requesting service
-has performed on the entity that originated the request. The possible types of
-information that can be logged can be easily extended to accomodate various
-requirements from other secure services.
-
-## Current service limitations
-
-**Policy manager** - Currently, there is no policy manager implemented, which
-means that there are no restrictions on the entities which can add or remove
-items from the log. Also, the item replacement in the log is just replacing
-older elements first.
-
-**Encryption** - Support for encryption and authentication is not available yet.
-
-**Permanent storage** - Currently the Audit Logging service supports only a RAM
-based storage of the log, permanent storage is not supported yet.
-
-## Code structure
-
-The PSA interfaces for the Audit logging service are located in
-`interface/include`.
-The TF-M Audit logging service source files are located in
-`secure_fw/services/audit_logging`.
-
-### PSA interfaces
-
-The TF-M Audit logging service exposes the following PSA interfaces:
-
- - `enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
- const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
- uint8_t *buffer, uint32_t *record_size);`
- - `enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
- *size);`
- - `enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
- uint32_t *size);`
- - `enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
- const uint8_t *token, const uint32_t token_size);`
-
-The TF-M Audit logging service exposes an additional PSA interface which can
-only be called from secure services:
-
- - `enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
- *record);`
-
-### Service source files
-
- - `audit_core.c` : This file implements core functionalities such as log
- management, record addition and deletion and extraction of record information;
- - `audit_wrappers.c` : This file implements TF-M compatible wrappers in
- case they are needed by the functions exported by the core.
-
-## Audit logging service integration guide
-
-In this section, a brief description of each field of a log record is given,
-with an example on how to perform a logging request from a secure service.
-The secure service that requests the addition of a record to the log has to
-provide data as described by the `psa_audit_record` type, defined in
-`interface\include\psa_audit_defs.h`:
-
-```
-/*!
- * \struct psa_audit_record
- *
- * \brief This structure contains the record that is added to the audit log
- * by the requesting secure service
- */
-struct psa_audit_record {
- uint32_t size; /*!< Size in bytes of the id and payload fields */
- uint32_t id; /*!< ID of the record */
- uint8_t payload[]; /*!< Flexible array member for payload */
-};
-```
-
-Each field is described as follows:
-
-- `size` - This is the size, in bytes, of the `id` and `payload[]` fields that
-follow. Given that the `payload[]` field is optional, in the current
-implementation the minimum value to be provided in `size` is 4 bytes;
-- `id` - This field is meant to be used to store an ID of the log record from
-the requesting service;
-- `payload[]` - The payload is an optional content which can be made of one or
-more Type-Length-Value entries as described by the following type:
-
- ```
- /*!
- * \struct audit_tlv_entry
- *
- * \brief TLV entry structure with a flexible
- * array member
- */
- struct audit_tlv_entry {
- enum audit_tlv_type type;
- uint32_t length;
- uint8_t value[];
- };
- ```
-
-The possible TLV types described by `enum audit_tlv_type` can be extended by
-system integrators modifying `audit_core.h` as needed.
-A logging request is performed by a secure service which calls the Secure-only
-API function `psa_audit_add_record()`.
-
- --------------
-
-*Copyright (c) 2018, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_audit_integration_guide.rst b/docs/user_guides/services/tfm_audit_integration_guide.rst
new file mode 100644
index 0000000..314128d
--- /dev/null
+++ b/docs/user_guides/services/tfm_audit_integration_guide.rst
@@ -0,0 +1,134 @@
+############################################
+TF-M Audit Logging Service Integration Guide
+############################################
+
+************
+Introduction
+************
+TF-M Audit logging service allows secure services in the system to log critical
+system events and information that have security implications. This is required
+to post analyse the system behaviour, system events and triage system issues
+offline. This offers a mitigation against the repudiation threat.
+
+The types of information that can be logged are the ID of the entity that
+originated a secure service request, or the relevant output or data
+associated to the authentication mechanism that the requesting service
+has performed on the entity that originated the request. The possible types of
+information that can be logged can be easily extended to accommodate various
+requirements from other secure services.
+
+***************************
+Current service limitations
+***************************
+
+- **Policy manager** - Currently, there is no policy manager implemented, which
+ means that there are no restrictions on the entities which can add or remove
+ items from the log. Also, the item replacement in the log is just replacing
+ older elements first.
+
+- **Encryption** - Support for encryption and authentication is not available
+ yet.
+
+- **Permanent storage** - Currently the Audit Logging service supports only a
+ RAM based storage of the log, permanent storage is not supported yet.
+
+
+**************
+Code structure
+**************
+The PSA interfaces for the Audit logging service are located in
+``interface/include``.
+
+The TF-M Audit logging service source files are located in
+``secure_fw/services/audit_logging``.
+
+PSA interfaces
+==============
+The TF-M Audit logging service exposes the following PSA interfaces:
+
+.. code-block:: c
+
+ enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
+ const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
+ uint8_t *buffer, uint32_t *record_size);
+
+ enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
+ *size);
+
+ enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
+ uint32_t *size);
+
+ enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
+ const uint8_t *token, const uint32_t token_size);
+
+The TF-M Audit logging service exposes an additional PSA interface which can
+only be called from secure services:
+
+.. code-block:: c
+
+ enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
+ *record);
+
+Service source files
+====================
+
+- ``audit_core.c`` : This file implements core functionalities such as log
+ management, record addition and deletion and extraction of record information.
+- ``audit_wrappers.c`` : This file implements TF-M compatible wrappers in case
+ they are needed by the functions exported by the core.
+
+***************************************
+Audit logging service integration guide
+***************************************
+In this section, a brief description of each field of a log record is given,
+with an example on how to perform a logging request from a secure service.
+The secure service that requests the addition of a record to the log has to
+provide data as described by the ``psa_audit_record`` type, defined in
+``interface\include\psa_audit_defs.h``:
+
+.. code-block:: c
+
+ /*!
+ * \struct psa_audit_record
+ *
+ * \brief This structure contains the record that is added to the audit log
+ * by the requesting secure service
+ */
+ struct psa_audit_record {
+ uint32_t size; /*!< Size in bytes of the id and payload fields */
+ uint32_t id; /*!< ID of the record */
+ uint8_t payload[]; /*!< Flexible array member for payload */
+ };
+
+Each field is described as follows:
+
+- ``size`` - This is the size, in bytes, of the ``id`` and ``payload[]`` fields
+ that follow. Given that the ``payload[]`` field is optional, in the current
+ implementation the minimum value to be provided in ``size`` is 4 bytes;
+- ``id`` - This field is meant to be used to store an ID of the log record from
+ the requesting service
+- ``payload[]`` - The payload is an optional content which can be made
+ of one or more Type-Length-Value entries as described by the following type:
+
+.. code-block:: c
+
+ /*!
+ * \struct audit_tlv_entry
+ *
+ * \brief TLV entry structure with a flexible
+ * array member
+ */
+ struct audit_tlv_entry {
+ enum audit_tlv_type type;
+ uint32_t length;
+ uint8_t value[];
+ };
+
+The possible TLV types described by ``enum audit_tlv_type`` can be extended by
+system integrators modifying ``audit_core.h`` as needed. A logging request is
+performed by a secure service which calls the
+Secure-only API function ``psa_audit_add_record()``.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_crypto_integration_guide.md b/docs/user_guides/services/tfm_crypto_integration_guide.md
deleted file mode 100644
index d60cd6f..0000000
--- a/docs/user_guides/services/tfm_crypto_integration_guide.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# TF-M Crypto Service Integration Guide
-
-## Introduction
-
-TF-M Crypto service allows application to use cryptography primitives such as
-symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
-authenticated encryption with associated data (AEAD).
-
-## Code structure
-
-The PSA interfaces for the Crypto service are located in `interface\include`.
-The only header to be included by applications that want to use functions from
-the PSA API is `psa_crypto.h`.
-The TF-M Crypto service source files are located in `secure_fw\services\crypto`.
-
-### PSA interfaces
-
-The TF-M Crypto service exposes the PSA interfaces detailed in the header
-`psa_crypto.h`. There are two additional header files, named
-`psa_crypto_extra.h` and `psa_crypto_platform.h`, which are meant to be included
-only by the `psa_crypto.h` header itself, that specify, respectively, extensions
-to the API that are vendor specific, and provide definitions and types which are
-platform specific. For a detailed description of the PSA API interface, please
-refer to the comments in the `psa_crypto.h` header itself.
-
-### Service source files
-
- - `crypto_cipher.c` : This file implements functionalities related to the
- ciphering module;
- - `crypto_hash.c` : This file implements functionalities related to the
- hashing module;
- - `crypto_init.c` : This file provides basic functions to initialise the
- secure service during TF-M boot;
- - `crypto_key.c` : This file implements functionalities related to the key
- management module. The `TFM_CRYPTO_KEY_STORAGE_NUM` determines how many key
- stores are available, while the `TFM_CRYPTO_MAX_KEY_LENGTH` defines the
- maximum allowed key length in bytes supported in a key storage. These two
- items can be modfied at the build configuration step by defining the
- following variables, `-DCRYPTO_KEY_STORAGE_NUM=<value>` and the
- `-DCRYPTO_KEY_MAX_KEY_LENGTH=<value>`;
- - `crypto_alloc.c` : This file implements extensions to the PSA interface
- which are specifically required by the TF-M Crypto service, in particular
- related to the allocation and deallocation of crypto operation contexts in
- the secure world. The `TFM_CRYPTO_CONC_OPER_NUM`, defined in this file,
- determines how many concurrent contexts are supported (8 for the current
- implementation). For multipart cipher/hash/MAC operations, a context is
- associated to the handle provided during the setup phase, and is explicitly
- cleared only following a successful termination or an abort;
- - `crypto_engine.c` : This file implements the layer which the other modules
- use to interact with the cryptography primitives available (in SW or HW). The
- `TFM_CRYPTO_ENGINE_BUF_SIZE` determines the size in bytes of the static scratch
- buffer used by this layer for its internal allocations. This item can be
- modified at the build configuration step by defining
- `-DCRYPTO_ENGINE_BUF_SIZE=<value>`. The current implementation provides only SW
- primitives based on Mbed TLS functions;
- - `crypto_mac.c` : This file implements functionalities related to the
- MAC (Message Authentication Code) module;
- - `crypto_aead.c` : This file implements functionalities related to the AEAD
- (Authenticated Encryption with Associated Data) module.
-
-## Crypto service integration guide
-
-In this section, a brief description of the required flow of operation for the
-functionalities exported by the PSA Crypto interface is given, with particular
-focus on the TF-M Crypto service specific operations. For the details of the
-generic PSA Crypto interface operations, please refer directly to the header
-`psa_crypto.h`.
-
-Most of the PSA Crypto APIs require an operation context to be allocated by the
-application and then to be passed as a pointer during the following API calls.
-These operation contexts are of four main types describes below:
-
- - `psa_key_policy_t` - Operation context to be used when setting key policies;
- - `psa_hash_operation_t` - Operation context for multipart hash operations;
- - `psa_mac_operation_t` - Operation context for multipart MAC operations;
- - `psa_cipher_operation_t` - Operation context for multipart cipher operations.
-
-The user applications are not allowed to make any assumption about the original
-types behind these typedefs, which are defined inside `psa_crypto.h`.
-In the scope of the TF-M Crypto service, these types are regarded as
-handles to the corresponding implementation defined structures which are stored
-in the Secure world.
-
- --------------
-
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_crypto_integration_guide.rst b/docs/user_guides/services/tfm_crypto_integration_guide.rst
new file mode 100644
index 0000000..82faea9
--- /dev/null
+++ b/docs/user_guides/services/tfm_crypto_integration_guide.rst
@@ -0,0 +1,92 @@
+#####################################
+TF-M Crypto Service Integration Guide
+#####################################
+
+************
+Introduction
+************
+TF-M Crypto service allows application to use cryptography primitives such as
+symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
+authenticated encryption with associated data (AEAD).
+
+**************
+Code structure
+**************
+The PSA interfaces for the Crypto service are located in ``interface\include``.
+The only header to be included by applications that want to use functions from
+the PSA API is ``psa_crypto.h``.
+The TF-M Crypto service source files are located in
+``secure_fw\services\crypto``.
+
+PSA interfaces
+==============
+The TF-M Crypto service exposes the PSA interfaces detailed in the header
+``psa_crypto.h``. There are two additional header files, named
+``psa_crypto_extra.h`` and ``psa_crypto_platform.h``, which are meant to be
+included only by the ``psa_crypto.h`` header itself, that specify, respectively,
+extensions to the API that are vendor specific, and provide definitions and
+types which are platform specific. For a detailed description of the PSA API
+interface, please refer to the comments in the ``psa_crypto.h`` header itself.
+
+Service source files
+====================
+- ``crypto_cipher.c`` : This file implements functionalities related to the
+ ciphering module
+- ``crypto_hash.c`` : This file implements functionalities related to
+ the hashing module
+- ``crypto_init.c`` : This file provides basic functions to initialise
+ the secure service during TF-M boot;
+- ``crypto_key.c`` : This file implements functionalities related to
+ the key management module. The ``TFM_CRYPTO_KEY_STORAGE_NUM`` determines how
+ many key stores are available, while the ``TFM_CRYPTO_MAX_KEY_LENGTH`` defines
+ the maximum allowed key length in bytes supported in a key storage. These
+ two items can be modfied at the build configuration step by defining the
+ following variables, ``-DCRYPTO_KEY_STORAGE_NUM=<value>`` and the
+ ``-DCRYPTO_KEY_MAX_KEY_LENGTH=<value>``
+- ``crypto_alloc.c`` : This file implements extensions to the PSA interface
+ which are specifically required by the TF-M Crypto service, in particular
+ related to the allocation and deallocation of crypto operation contexts in
+ the secure world. The ``TFM_CRYPTO_CONC_OPER_NUM``, defined in this file,
+ determines how many concurrent contexts are supported (8 for the current
+ implementation). For multipart cipher/hash/MAC operations, a context is
+ associated to the handle provided during the setup phase, and is explicitly
+ cleared only following a successful termination or an abort
+- ``crypto_engine.c`` : This file implements the layer which the other
+ modules use to interact with the cryptography primitives available (in SW or
+ HW). The ``TFM_CRYPTO_ENGINE_BUF_SIZE`` determines the size in bytes of the
+ static scratch buffer used by this layer for its internal allocations. This
+ item can be modified at the build configuration step by defining
+ ``-DCRYPTO_ENGINE_BUF_SIZE=<value>``. The current implementation provides only
+ SW primitives based on Mbed TLS functions
+- ``crypto_mac.c`` : This file implements functionalities related to the
+ MAC (Message Authentication Code) module
+- ``crypto_aead.c`` : This file implements functionalities related to the AEAD
+ (Authenticated Encryption with Associated Data) module.
+
+********************************
+Crypto service integration guide
+********************************
+n this section, a brief description of the required flow of operation for the
+functionalities exported by the PSA Crypto interface is given, with particular
+focus on the TF-M Crypto service specific operations. For the details of the
+generic PSA Crypto interface operations, please refer directly to the header
+``psa_crypto.h``.
+
+Most of the PSA Crypto APIs require an operation context to be allocated by the
+application and then to be passed as a pointer during the following API calls.
+These operation contexts are of four main types describes below:
+
+- ``psa_key_policy_t`` - Operation context to be used when setting key policies
+- ``psa_hash_operation_t`` - Operation context for multipart hash operations
+- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
+- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
+
+The user applications are not allowed to make any assumption about the original
+types behind these typedefs, which are defined inside ``psa_crypto.h``.
+In the scope of the TF-M Crypto service, these types are regarded as handles to
+the corresponding implementation defined structures which are stored in the
+Secure world.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_platform_integration_guide.md b/docs/user_guides/services/tfm_platform_integration_guide.md
deleted file mode 100644
index ab193ed..0000000
--- a/docs/user_guides/services/tfm_platform_integration_guide.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# TF-M Platform Service Integration Guide
-
-## Introduction
-
-TF-M Platform service is a trusted service which allows secure partitions and
-non-secure applications to interact with some platform-specific components.
-There are a number of features which requires some interaction with
-platform-specific components which are at the same time essential for the
-security of the system.
-Therefore, those components need to be handled by a secure partition which is
-part of the trusted compute base.
-
-These platform-specific components include system reset, power management,
-Debug, GPIO, etc.
-
-## TF-M Platform interfaces
-
-The TF-M interfaces for the Platform service are located in
-`interface/include/`.
-The TF-M Platform service source files are located in
-`secure_fw/services/platform`.
-
-## TF-M Platform service
-
-The Platform service exposes the following interfaces:
- - `enum tfm_platform_err_t tfm_platform_system_reset(void)`
-
-The Platform service interfaces and types are defined and documented in
-`interface/include/tfm_platform_api.h`
-
- - `platform_sp.h/c` : These files define and implement functionalities related
- to the platform service;
- - `tfm_platform_secure_api.c` : This file implements `tfm_platform_api.h`
- functions to be called from the secure partitions. This is the entry point when
- the secure partitions request an action to the Platform service
- (e.g system reset).
-
-## Platform HAL system reset
-
-The Platform service service relies on a platform-specific implementation to
-perform some functionalities (e.g. system reset). The platform-specific
-implementation of those APIs will be located in the platform service code
-section (TF-M level 3 isolation) in order to protect it from a direct call from
-other secure partitions.
-
-For API specification, please check:
-`platform/include/tfm_platform_system.h`
-
-An implementation is provided in all the supported platforms. Please,
-check `platform/ext/target/<SPECIFIC_TARGET_FOLDER>/tfm_platform_system.c`
-
-The API **must** be implemented by the system integrators for their targets.
-
-## Platform pin service
-
-This service is designed to perform secure pin services of the platform
-(e.g alternate function setting, pin mode setting, etc).
-The veneer implementation follows IOVEC API implementation, which allows
-the NS application to pack many pin service requests into one service call
-to reduce the overhead of the Secure-Non-Secure context switch.
-Since packing many service requests into one call is application and use-case
-specific, the API implementations in tfm_platform_api.c and
-tfm_platform_secure_api.c follow the one service in one veneer call design but
-the service implementation in tfm_platform_system.c is prepared to serve packed
-requests.
-
-## Current Service Limitations
-
-The system reset functionality is only supported in isolation level 1.
-Currently, the mechanism by which PRoT services should run in privileged mode in
-level 3, it is not in place due to an ongoing work in TF-M Core. So, the
-NVIC_SystemReset call performed by the service, it is expected to generate a
-memory fault when it tries to access the SCB->AIRCR register in level 3
-isolation.
-
-## Debug authentication settings
-
-A platform may provide the option to configure debug authentication. TF-M core
-calls the HAL function `void tfm_spm_hal_init_debug(void)` which configures
-debug outhentication based on the following defines:
- - `DAUTH_NONE`: Debugging the system is not enabled.
- - `DAUTH_NS_ONLY`: Invasive and non invasive debugging of non-secure code is
- enabled.
- - `DAUTH_FULL`: Invasive and non-invasive debugging of non-secure and secure
- code is enabled.
- - `DAUTH_CHIP_DEFAULT`: The debug auhentication options are used that are set
- by the chip vendor.
-
-The desired debug authentication configuration can be selected by setting one of
-the options above to the cmake command with the
-`-DDEBUG_AUTHENTICATION="<define>"` option. The default value of
-`DEBUG_AUTHENTICATION` is `DAUTH_CHIP_DEFAULT`.
-
-*Note*: `void tfm_spm_hal_init_debug(void)` is called during the TF-M core
-initialisation phase, before initialising secure partition. This means that BL2
-runs with the chip default setting.
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_platform_integration_guide.rst b/docs/user_guides/services/tfm_platform_integration_guide.rst
new file mode 100644
index 0000000..a1733a4
--- /dev/null
+++ b/docs/user_guides/services/tfm_platform_integration_guide.rst
@@ -0,0 +1,117 @@
+#######################################
+TF-M Platform Service Integration Guide
+#######################################
+
+************
+Introduction
+************
+TF-M Platform service is a trusted service which allows secure partitions and
+non-secure applications to interact with some platform-specific components.
+There are a number of features which requires some interaction with
+platform-specific components which are at the same time essential for the
+security of the system.
+Therefore, those components need to be handled by a secure partition which is
+part of the trusted compute base.
+
+These platform-specific components include system reset, power management,
+Debug, GPIO, etc.
+
+************************
+TF-M Platform interfaces
+************************
+The TF-M interfaces for the Platform service are located in
+``interface/include/``.
+The TF-M Platform service source files are located in
+``secure_fw/services/platform``.
+
+*********************
+TF-M Platform service
+*********************
+The Platform service exposes the following interfaces:
+
+.. code-block:: c
+
+ enum tfm_platform_err_t tfm_platform_system_reset(void)
+
+The Platform service interfaces and types are defined and documented in
+``interface/include/tfm_platform_api.h``
+
+- ``platform_sp.h/c`` : These files define and implement functionalities related
+ to the platform service
+- ``tfm_platform_secure_api.c`` : This file implements ``tfm_platform_api.h``
+ functions to be called from the secure partitions. This is the entry point
+ when the secure partitions request an action to the Platform service
+ (e.g system reset).
+
+*************************
+Platform HAL system reset
+*************************
+
+The Platform service service relies on a platform-specific implementation to
+perform some functionalities (e.g. system reset). The platform-specific
+implementation of those APIs will be located in the platform service code
+section (TF-M level 3 isolation) in order to protect it from a direct call from
+other secure partitions.
+
+For API specification, please check: ``platform/include/tfm_platform_system.h``
+
+An implementation is provided in all the supported platforms. Please,
+check ``platform/ext/target/<SPECIFIC_TARGET_FOLDER>/tfm_platform_system.c``
+
+The API **must** be implemented by the system integrators for their targets.
+
+The API **must** be implemented by the system integrators for their
+targets.
+
+********************
+Platform pin service
+********************
+This service is designed to perform secure pin services of the platform
+(e.g alternate function setting, pin mode setting, etc).
+The veneer implementation follows IOVEC API implementation, which allows
+the NS application to pack many pin service requests into one service call
+to reduce the overhead of the Secure-Non-Secure context switch.
+Since packing many service requests into one call is application and use-case
+specific, the API implementations in ``tfm_platform_api.c`` and
+```tfm_platform_secure_api.c`` follow the one service in one veneer call design
+but the service implementation in tfm_platform_system.c is prepared to serve
+packed requests.
+
+***************************
+Current Service Limitations
+***************************
+- **system reset** - The system reset functionality is only supported in
+ isolation level 1. Currently, the mechanism by which PRoT services should run
+ in privileged mode in level 3, it is not in place due to an ongoing work in
+ TF-M Core. So, the ``NVIC_SystemReset`` call performed by the service, is
+ expected to generate a memory fault when it tries to access the ``SCB->AIRCR``
+ register in level 3 isolation.
+
+*****************************
+Debug authentication settings
+*****************************
+A platform may provide the option to configure debug authentication. TF-M core
+calls the HAL function ``void tfm_spm_hal_init_debug(void)`` which configures
+debug authentication based on the following defines:
+
+ - `DAUTH_NONE`: Debugging the system is not enabled.
+ - `DAUTH_NS_ONLY`: Invasive and non invasive debugging of non-secure code is
+ enabled.
+ - `DAUTH_FULL`: Invasive and non-invasive debugging of non-secure and secure
+ code is enabled.
+ - `DAUTH_CHIP_DEFAULT`: The debug auhentication options are used that are set
+ by the chip vendor.
+
+The desired debug authentication configuration can be selected by setting one of
+the options above to the cmake command with the
+`-DDEBUG_AUTHENTICATION="<define>"` option. The default value of
+`DEBUG_AUTHENTICATION` is `DAUTH_CHIP_DEFAULT`.
+
+.. Note::
+ `void tfm_spm_hal_init_debug(void)` is called during the TF-M core
+ initialisation phase, before initialising secure partition. This means that BL2
+ runs with the chip default setting.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_sst_integration_guide.md b/docs/user_guides/services/tfm_sst_integration_guide.md
deleted file mode 100644
index fc5cc0f..0000000
--- a/docs/user_guides/services/tfm_sst_integration_guide.md
+++ /dev/null
@@ -1,360 +0,0 @@
-# TF-M Secure Storage Service Integration Guide
-
-## Introduction
-TF-M secure storage (SST) service implements PSA Protected Storage APIs.
-
-The service is backed by hardware isolation of the flash access domain and, in
-the current version, relies on hardware to isolate the flash area from
-non-secure access. In absence of hardware level isolation, the secrecy and
-integrity of data is still maintained.
-
-The current SST service design relies on hardware abstraction level provided
-by TF-M. The SST service provides a non-hierarchical storage model, as a
-filesystem, where all the assets are managed by linearly indexed list of
-metadata.
-
-The SST service implements an AES-GCM based AEAD encryption policy, as a
-reference, to protect data integrity and authenticity.
-
-The design addresses the following high level requirements as well:
-
-**Confidentiality** - Resistance to unauthorised accesses through
-hardware/software attacks.
-
-**Access Authentication** - Mechanism to establish requester's identity (a
-non-secure entity, secure entity, or a remote server).
-
-**Integrity** - Resistant to tampering by either the normal users of a product,
-package, or system or others with physical access to it. If the content of the
-secure storage is changed maliciously, the service is able to detect it.
-
-**Reliability** - Resistant to power failure scenarios and
-incomplete write cycles.
-
-**Configurability** - High level configurability to scale up/down memory
-footprint to cater for a variety of devices with varying security requirements.
-
-**Performance** - Optimized to be used for resource constrained devices with
-very small silicon footprint, the PPA (power, performance, area) should be
-optimal.
-
-## Current SST Service Limitations
-
-**Fragmentation** - The current design does not support fragmentation, as an
-asset is stored in a contiguous space in a block. This means that the maximum
-asset size can only be up-to a block size. Detailed information about the
-maximum asset size can be found in the section `Maximum asset size` below.
-Each block can potentially store multiple assets.
-A delete operation implicitly moves all the assets towards the top of the block
-to avoid fragmentation within block. However, this may also result in unutilized
-space at the end of each block.
-
-**Asset size limitation** - An asset is stored in a contiguous space in a
-block/sector. Hence, the maximum asset size can be up-to the size of the
-data block/sector. Detailed information about the maximum asset size can be
-found in the section `Maximum asset size` below.
-
-**Non-hierarchical storage model** - The current design uses a non-hierarchical
-storage model, as a filesystem, where all the assets are managed by a linearly
-indexed list of metadata. This model locates the metadata in blocks which are
-always stored in the same flash location. That increases the number of writes
-in a specific flash location as every change in the storage area requires a
-metadata update.
-
-**PSA internal trusted storage API** - In the current design, the service does
-not use the PSA Internal Trusted Storage API to write the rollback protection
-values stored in the internal storage. The PSA Internal Trusted Storage API is
-not supported in TF-M yet.
-
-**Protection against physical storage medium failure** - Complete handling of
-inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
-is not supported by the current design.
-
-**Key diversification** - In a more robust design, each asset would be encrypted
-through a different key.
-
-**Lifecycle management** - Currently, it does not support any subscription based
-keys and certificates required in a secure lifecycle management. Hence, an
-asset's validity time-stamp can not be invalidated based on the system time.
-
-**Provisioning vs user/device data** - In the current design, all assets are
-treated in the same manner. In an alternative design, it may be required to
-create separate partitions for provisioning content and user/device generated
-content. This is to allow safe update of provisioning data during firmware
-updates without the need to wipe out the user/device generated data.
-
-## Code Structure
-
-Secure storage service code is located in `secure_fw/services/secure_storage/`
-and is divided as follows:
-
- - Core files
- - Flash filesystem interfaces
- - Flash interfaces
- - Cryptographic interfaces
- - Non-volatile (NV) counters interfaces
-
-The PSA PS interfaces for SST service are located in `interface/include`
-
-### PSA Protected Storage Interfaces
-
-The SST service exposes the following mandatory PSA PS interfaces version 1.0:
-
- - `psa_ps_status_t psa_ps_set(psa_ps_uid_t uid, uint32_t data_length, const void *p_data, psa_ps_create_flags_t create_flags)`
- - `psa_ps_status_t psa_ps_get(psa_ps_uid_t uid, uint32_t data_offset, uint32_t data_length, void *p_data)`
- - `psa_ps_status_t psa_ps_get_info(psa_ps_uid_t uid, struct psa_ps_info_t *p_info)`
- - `psa_ps_status_t psa_ps_remove(psa_ps_uid_t uid)`
- - `uint32_t psa_ps_get_support(void)`
-
-For the moment, it does not support the extended version of those APIs.
-
-These PSA PS interfaces and SST TF-M types are defined and documented in
-`interface/include/psa_protected_storage.h` and
-`interface/include/tfm_sst_defs.h`
-
-### Core Files
-
-`tfm_sst_req_mngr.c` - Contains the SST request manager implementation which
-handles all requests which arrive to the service. This layer extracts the
-arguments from the input and output vectors, and it calls the protected storage
-layer with the provided parameters.
-
-`tfm_protected_storage.c` - Contains the TF-M protected storage API
-implementations which are the entry points to the SST service.
-
-`sst_object_system.c` - Contains the object system implementation to manage
-all objects in SST area.
-
-`sst_object_table.c` - Contains the object system table implementation which
-complements the object system to manage all object in the SST area.
-The object table has an entry for each object stored in the object system
-and keeps track of its version and owner.
-
-`sst_encrypted_object.c` - Contains an implementation to manipulate
-encrypted objects in the SST object system.
-
-`sst_utils.c` - Contains common and basic functionalities used across the
-SST service code.
-
-### Flash Filesystem Interface
-`flash_fs/sst_flash_fs.h` - Abstracts the flash filesystem operations used by
-the secure storage service. The purpose of this abstraction is to have the
-ability to plug-in other filesystems or filesystem proxys (supplicant).
-
-`flash_fs/sst_flash_fs.c` - Contains the `sst_flash_fs` implementation for
-the required interfaces.
-
-`flash_fs/sst_flash_fs_mbloc.c` - Contains the metadata block manipulation
-functions required to implement the `sst_flash_fs` interfaces in
-`flash_fs/sst_flash_fs.c`.
-
-`flash_fs/sst_flash_fs_mbloc.c` - Contains the data block manipulation
-functions required to implement the `sst_flash_fs` interfaces in
-`flash_fs/sst_flash_fs.c`.
-
-The system integrator **may** replace this implementation with its own
-flash filesystem implementation or filesystem proxy (supplicant).
-
-### Flash Interface
-
-`flash/sst_flash.h` - Abstracts the flash operations for the secure storage
-service. It also defines the block size and number of blocks used by the SST
-service.
-
-`flash/sst_flash.c` - Contains the `sst_flash` implementation which sits on
-top of CMSIS flash interface implemented by the target.
-The CMSIS flash interface **must** be implemented for each target based on
-its flash controller.
-
-The block size (`SST_SECTOR_SIZE`) and number of blocks
-(`SST_NBR_OF_SECTORS`) used by the secure storage area, are defined in
-`flash_layout.h` located in `platform/ext/target/<TARGET_NAME>/partition`.
-Those values **must** be defined in that header file based on flash
-specifications and vendor specific considerations.
-It is also required to define the `SST_FLASH_AREA_ADDR` which defines the
-address of the first sector to be used as secure storage. The sectors reserved
-to be used as secure storage **must** be contiguous sectors starting at
-`SST_FLASH_AREA_ADDR`.
-
-### Cryptographic Interface
-
-`crypto/sst_crypto_interface.h` - Abstracts the cryptographic operations for
-the secure storage service.
-
-`crypto/sst_crypto_interface.c` - Currently, it implements the SST service
-cryptographic operations using Mbed TLS library. The system integrator **may**
-replace this implementation with calls to another service, crypto library or
-hardware crypto unit.
-
-### Non-volatile (NV) Counters Interface
-
-The current SST service provides rollback protection based on NV counters.
-SST defines and implements the following NV counters functionalities:
-
-`nv_counters/sst_nv_counters.h` - Abstracts SST non-volatile counters
-operations. This API detaches the use of NV counters from the TF-M NV counters
-implementation, provided by the platform, and provides a mechanism to compile
-in a different API implementation for test purposes. A SST test suite **may**
-provide its own custom implementation to be able to test different SST service
-use cases.
-
-`nv_counters/sst_nv_counters.c` - Implements the SST NV counters interfaces
-based on TF-M NV counters implementation provided by the platform.
-
-## SST Service Integration Guide
-
-This section describes mandatory (i.e. **must** implement) or optional
-(i.e. **may** implement) interfaces which the system integrator have to take
-in to account in order to integrate the secure storage service in a new
-platform.
-
-### Maximum Asset Size
-An asset is stored in a contiguous space in a block/sector. The maximum
-size of an asset can be up-to the size of the data block/sector minus the object
-header size (`SST_OBJECT_HEADER_SIZE`) which is defined in `sst_object_defs.h`.
-The `SST_OBJECT_HEADER_SIZE` changes based on the `SST_ENCRYPTION` flag status.
-
-### Secure Storage Service Definitions
-
-The SST service requires the following platform definitions:
-
- - `SST_FLASH_AREA_ADDR`
- Defines the flash address where the secure store area starts.
- - `SST_SECTOR_SIZE`
- Defines the size of the flash sectors.
- - `SST_NBR_OF_SECTORS`
- Defines the number of sectors available for the secure area. The sectors must
- be consecutive.
- - `SST_FLASH_DEV_NAME`
- Specifies the flash device used by SST to store the data.
- - `SST_FLASH_PROGRAM_UNIT`
- Defines the smallest flash programmable unit in bytes.
- Currently, SST supports 1, 2, 4 and 8.
- - `SST_MAX_ASSET_SIZE`
- Defines the maximum asset size to be stored in the SST area. This size is
- used to define the temporary buffers used by SST to read/write the asset
- content from/to flash. The memory used by the temporary buffers is allocated
- statically as SST does not use dynamic memory allocation.
- - `SST_NUM_ASSETS`
- Defines the maximum number of assets to be stored in the SST area. This
- number is used to dimension statically the object table size in RAM
- (fast access) and flash (persistent storage). The memory used by the
- object table is allocated statically as SST does not use dynamic memory
- allocation.
-
-Target must provide a header file, called `flash_layout.h`, which defines the
-information explained above. The defines must be named as they are specified
-above.
-
-More information about the `flash_layout.h` content, not SST related, is
-available in `platform/ext/readme.md` along with other platform information.
-
-### TF-M NV Counter Interface
-To have a platform independent way to access the NV counters, TF-M defines a
-platform NV counter interface. For API specification, please check:
-`platform/include/tfm_plat_nv_counters.h`
-
-The system integrators **may** implement this interface based on the target
-capabilities and set the `SST_ROLLBACK_PROTECTION` flag to compile in
-the rollback protection code.
-
-### Secret Platform Unique Key
-
-The encryption policy relies on a secret hardware unique key (HUK) per device.
-It is system integrator's responsibility to provide an implementation which
-**must** be a non-mutable target implementation.
-For API specification, please check:
-`platform/include/tfm_plat_crypto_keys.h`
-
-A stub implementation is provided in
-`platform/ext/<target>/dummy_crypto_keys.c`
-
-### Flash Interface
-
-For SST service operations, a contiguous set of blocks must be earmarked for
-the secure storage area. The design requires either 2 blocks, or any number of
-blocks greater than or equal to 4. Total number of blocks can not be 0, 1 or 3.
-This is a design choice limitation to provide power failure safe update
-operations.
-For API specification, please check:
-`secure_fw/services/secure_storage/flash/sst_flash.h`
-
-### Non-Secure Identity Manager
-
-TF-M core tracks the current client IDs running in the secure or non-secure
-processing environment. It provides a dedicated API to retrieve the client ID
-which performs the service request.
-
-[NS client identification documentation](../tfm_ns_client_identification.md)
-provides further details on how client identification works.
-
-SST service uses that TF-M core API to retrieve the client ID and associate it
-as the owner of an asset. Only the owner can read, write or delete that asset
-based on the creation flags.
-
-The [integration guide](../tfm_integration_guide.md) provides further
-details of non-secure implementation requirements for TF-M.
-
-### Cryptographic Interface
-
-The reference encryption policy is built on AES-GCM, and it **may** be replaced
-by a vendor specific implementation.
-The SST service abstracts all the cryptographic requirements and specifies the
-required cryptographic interface in
-`secure_fw/services/secure_storage/crypto/sst_crypto_interface.h`
-
-Currently, the SST service cryptographic operations are implemented in
-`secure_fw/services/secure_storage/crypto/sst_crypto_interface.c`, using
-Mbed TLS library.
-
-### SST Service Features Flags
-
-SST service defines a set of flags that can be used to compile in/out certain
-SST service features. The `CommonConfig.cmake` file sets the default values
-of those flags. However, those flags values can be overwritten by setting them
-in `platform/ext/<TARGET_NAME>.cmake` based on the target capabilities or needs.
-The list of SST services flags are:
-
- - `SST_ENCRYPTION`: this flag allows to enable/disable encryption option to
- encrypt the secure storage data.
- - `SST_CREATE_FLASH_LAYOUT`: this flag indicates that it is required to
- create a SST flash layout. If this flag is set, SST service will generate an
- empty and valid SST flash layout to store assets. It will erase all data
- located in the assigned SST memory area before generating the SST layout.
- This flag is required to be set if the SST memory area is located in a
- non-persistent memory.
- This flag can be set if the SST memory area is located in a persistent
- memory without a valid SST flash layout in it. That is the case when
- it is the first time in the device life that the SST service is executed.
- - `SST_VALIDATE_METADATA_FROM_FLASH`: this flag allows to enable/disable the
- validation mechanism to check the metadata store in flash every time the
- flash data is read from flash. This validation is required if the flash is
- not hardware protected against malicious writes. In case the flash is
- protected against malicious writes (i.e embedded flash, etc), this validation
- can be disabled in order to reduce the validation overhead.
- - `SST_ROLLBACK_PROTECTION`: this flag allows to enable/disable rollback
- protection in secure storage service. This flag takes effect only if the
- target has non-volatile counters and `SST_ENCRYPTION` flag is on.
- - `SST_RAM_FS`: this flag allows to enable/disable the use of RAM instead
- of the flash to store the FS in secure storage service. This flag is set
- by default in the regression tests, if it is not defined by the platform.
- The SST regression tests reduce the life of the flash memory as they
- write/erase multiple times in the memory.
- - `SST_TEST_NV_COUNTERS`: this flag enables the virtual implementation of the
- SST NV counters interface in `test/suites/sst/secure/nv_counters`, which
- emulates NV counters in RAM, and disables the hardware implementation of NV
- counters provided by the secure service. This flag is enabled by default when
- building the regression tests and disabled by default otherwise.
- - This flag can be overridden to `OFF` when building the regression tests. In
- this case, the SST rollback protection test suite will not be built, as it
- relies on extra functionality provided by the virtual NV counters to
- simulate different rollback scenarios. The remainder of the SST test suites
- will run using the hardware NV counters. Please note that running the tests
- in this configuration will quickly increase the hardware NV counter values,
- which cannot be decreased again.
- - Overriding this flag from its default value of `OFF` when not building the
- regression tests is not currently supported.
-
---------------
-
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_sst_integration_guide.rst b/docs/user_guides/services/tfm_sst_integration_guide.rst
new file mode 100644
index 0000000..87cf3ce
--- /dev/null
+++ b/docs/user_guides/services/tfm_sst_integration_guide.rst
@@ -0,0 +1,377 @@
+#############################################
+TF-M Secure Storage Service Integration Guide
+#############################################
+
+************
+Introduction
+************
+TF-M secure storage (SST) service implements PSA Protected Storage APIs.
+
+The service is backed by hardware isolation of the flash access domain and, in
+the current version, relies on hardware to isolate the flash area from
+non-secure access. In absence of hardware level isolation, the secrecy and
+integrity of data is still maintained.
+
+The current SST service design relies on hardware abstraction level provided
+by TF-M. The SST service provides a non-hierarchical storage model, as a
+filesystem, where all the assets are managed by linearly indexed list of
+metadata.
+
+The SST service implements an AES-GCM based AEAD encryption policy, as a
+reference, to protect data integrity and authenticity.
+
+The design addresses the following high level requirements as well:
+
+- **Confidentiality** - Resistance to unauthorised accesses through
+ hardware/software attacks.
+
+- **Access Authentication** - Mechanism to establish requester's identity (a
+ non-secure entity, secure entity, or a remote server).
+
+- **Integrity** - Resistant to tampering by either the normal users of a product,
+ package, or system or others with physical access to it. If the content of the
+ secure storage is changed maliciously, the service is able to detect it.
+
+- **Reliability** - Resistant to power failure scenarios and incomplete write
+ cycles.
+
+- **Configurability** - High level configurability to scale up/down memory
+ footprint to cater for a variety of devices with varying security
+ requirements.
+
+- **Performance** - Optimized to be used for resource constrained devices with
+ very small silicon footprint, the PPA (power, performance, area) should be
+ optimal.
+
+*******************************
+Current SST Service Limitations
+*******************************
+- **Fragmentation** - The current design does not support fragmentation, as an
+ asset is stored in a contiguous space in a block. This means that the maximum
+ asset size can only be up-to a block size. Detailed information about the
+ maximum asset size can be found in the section `Maximum asset size` below.
+ Each block can potentially store multiple assets.
+ A delete operation implicitly moves all the assets towards the top of the block
+ to avoid fragmentation within block. However, this may also result in
+ unutilized space at the end of each block.
+
+- **Asset size limitation** - An asset is stored in a contiguous space in a
+ block/sector. Hence, the maximum asset size can be up-to the size of the
+ data block/sector. Detailed information about the maximum asset size can be
+ found in the section `Maximum asset size` below.
+
+- **Non-hierarchical storage model** - The current design uses a
+ non-hierarchical storage model, as a filesystem, where all the assets are
+ managed by a linearly indexed list of metadata. This model locates the
+ metadata in blocks which are always stored in the same flash location. That
+ increases the number of writes in a specific flash location as every change in
+ the storage area requires a metadata update.
+
+- **PSA internal trusted storage API** - In the current design, the service does
+ not use the PSA Internal Trusted Storage API to write the rollback protection
+ values stored in the internal storage. The PSA Internal Trusted Storage API is
+ not supported in TF-M yet.
+
+- **Protection against physical storage medium failure** - Complete handling of
+ inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
+ is not supported by the current design.
+
+- **Key diversification** - In a more robust design, each asset would be
+ encrypted through a different key.
+
+- **Lifecycle management** - Currently, it does not support any subscription
+ based keys and certificates required in a secure lifecycle management. Hence,
+ an asset's validity time-stamp can not be invalidated based on the system
+ time.
+
+- **Provisioning vs user/device data** - In the current design, all assets are
+ treated in the same manner. In an alternative design, it may be required to
+ create separate partitions for provisioning content and user/device generated
+ content. This is to allow safe update of provisioning data during firmware
+ updates without the need to wipe out the user/device generated data.
+
+**************
+Code Structure
+**************
+Secure storage service code is located in ``secure_fw/services/secure_storage/``
+and is divided as follows:
+
+ - Core files
+ - Flash filesystem interfaces
+ - Flash interfaces
+ - Cryptographic interfaces
+ - Non-volatile (NV) counters interfaces
+
+The PSA PS interfaces for SST service are located in ``interface/include``
+
+PSA Protected Storage Interfaces
+================================
+
+The SST service exposes the following mandatory PSA PS interfaces
+version 1.0:
+
+.. code-block:: c
+
+ psa_ps_status_t psa_ps_set(psa_ps_uid_t uid, uint32_t data_length, const void *p_data, psa_ps_create_flags_t create_flags);
+ psa_ps_status_t psa_ps_get(psa_ps_uid_t uid, uint32_t data_offset, uint32_t data_length, void *p_data);
+ psa_ps_status_t psa_ps_get_info(psa_ps_uid_t uid, struct psa_ps_info_t *p_info);
+ psa_ps_status_t psa_ps_remove(psa_ps_uid_t uid);
+ uint32_t psa_ps_get_support(void);
+
+For the moment, it does not support the extended version of those APIs.
+
+These PSA PS interfaces and SST TF-M types are defined and documented in
+``interface/include/psa_protected_storage.h`` and
+``interface/include/tfm_sst_defs.h``
+
+Core Files
+==========
+- ``tfm_sst_req_mngr.c`` - Contains the SST request manager implementation which
+ handles all requests which arrive to the service. This layer extracts the
+ arguments from the input and output vectors, and it calls the protected
+ storage layer with the provided parameters.
+
+- ``tfm_protected_storage.c`` - Contains the TF-M protected storage API
+ implementations which are the entry points to the SST service.
+
+- ``sst_object_system.c`` - Contains the object system implementation to manage
+ all objects in SST area.
+
+- ``sst_object_table.c`` - Contains the object system table implementation which
+ complements the object system to manage all object in the SST area.
+ The object table has an entry for each object stored in the object system
+ and keeps track of its version and owner.
+
+- ``sst_encrypted_object.c`` - Contains an implementation to manipulate
+ encrypted objects in the SST object system.
+
+- ``sst_utils.c`` - Contains common and basic functionalities used across the
+ SST service code.
+
+Flash Filesystem Interface
+==========================
+- ``flash_fs/sst_flash_fs.h`` - Abstracts the flash filesystem operations used
+ by the secure storage service. The purpose of this abstraction is to have the
+ ability to plug-in other filesystems or filesystem proxys (supplicant).
+
+- ``flash_fs/sst_flash_fs.c`` - Contains the ``sst_flash_fs`` implementation for
+ the required interfaces.
+
+- ``flash_fs/sst_flash_fs_mbloc.c`` - Contains the metadata block manipulation
+ functions required to implement the ``sst_flash_fs`` interfaces in
+ ``flash_fs/sst_flash_fs.c``.
+
+- ``flash_fs/sst_flash_fs_dbloc.c`` - Contains the data block manipulation
+ functions required to implement the ``sst_flash_fs`` interfaces in
+ ``flash_fs/sst_flash_fs.c``.
+
+The system integrator **may** replace this implementation with its own
+flash filesystem implementation or filesystem proxy (supplicant).
+
+Flash Interface
+===============
+- ``flash/sst_flash.h`` - Abstracts the flash operations for the secure storage
+ service. It also defines the block size and number of blocks used by the SST
+ service.
+
+- ``flash/sst_flash.c`` - Contains the ``sst_flash`` implementation which sits
+ on top of CMSIS flash interface implemented by the target.
+ The CMSIS flash interface **must** be implemented for each target based on
+ its flash controller.
+
+The block size (``SST_SECTOR_SIZE``) and number of blocks
+(``SST_NBR_OF_SECTORS``) used by the secure storage area, are defined in
+``flash_layout.h`` located in ``platform/ext/target/<TARGET_NAME>/partition``.
+Those values **must** be defined in that header file based on flash
+specifications and vendor specific considerations.
+It is also required to define the ``SST_FLASH_AREA_ADDR`` which defines the
+address of the first sector to be used as secure storage. The sectors reserved
+to be used as secure storage **must** be contiguous sectors starting at
+``SST_FLASH_AREA_ADDR``.
+
+Cryptographic Interface
+=======================
+-``crypto/sst_crypto_interface.h`` - Abstracts the cryptographic
+ operations for the secure storage service.
+
+- ``crypto/sst_crypto_interface.c`` - Currently, it implements the SST
+ service cryptographic operations using Mbed TLS library. The system integrator
+ **may** replace this implementation with calls to another service, crypto
+ library or hardware crypto unit.
+
+Non-volatile (NV) Counters Interface
+====================================
+The current SST service provides rollback protection based on NV
+counters.
+SST defines and implements the following NV counters functionalities:
+
+- ``nv_counters/sst_nv_counters.h`` - Abstracts SST non-volatile
+ counters operations. This API detaches the use of NV counters from the TF-M NV
+ counters implementation, provided by the platform, and provides a mechanism to
+ compile in a different API implementation for test purposes. A SST test suite
+ **may** provide its own custom implementation to be able to test different SST
+ service use cases.
+
+- ``nv_counters/sst_nv_counters.c`` - Implements the SST NV counters interfaces
+ based on TF-M NV counters implementation provided by the platform.
+
+*****************************
+SST Service Integration Guide
+*****************************
+This section describes mandatory (i.e. **must** implement) or optional
+(i.e. **may** implement) interfaces which the system integrator have to take
+in to account in order to integrate the secure storage service in a new
+platform.
+
+Maximum Asset Size
+==================
+An asset is stored in a contiguous space in a block/sector. The maximum
+size of an asset can be up-to the size of the data block/sector minus the object
+header size (``SST_OBJECT_HEADER_SIZE``) which is defined in
+``sst_object_defs.h``. The ``SST_OBJECT_HEADER_SIZE`` changes based on the
+``SST_ENCRYPTION`` flag status.
+
+Secure Storage Service Definitions
+==================================
+The SST service requires the following platform definitions:
+
+- ``SST_FLASH_AREA_ADDR`` - Defines the flash address where the secure store
+ area starts.
+- ``SST_SECTOR_SIZE`` - Defines the size of the flash sectors.
+- ``SST_NBR_OF_SECTORS`` - Defines the number of sectors available for the
+ secure area. The sectors must be consecutive.
+- ``SST_FLASH_DEV_NAME`` - Specifies the flash device used by SST to store the
+ data.
+- ``SST_FLASH_PROGRAM_UNIT`` - Defines the smallest flash programmable unit in
+ bytes. Currently, SST supports 1, 2, 4 and 8.
+- ``SST_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ SST area. This size is used to define the temporary buffers used by SST to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as SST does not use dynamic memory allocation.
+- ``SST_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ SST area. This number is used to dimension statically the object table size in
+ RAM (fast access) and flash (persistent storage). The memory used by the
+ object table is allocated statically as SST does not use dynamic memory
+ allocation.
+
+Target must provide a header file, called ``flash_layout.h``, which defines the
+information explained above. The defines must be named as they are specified
+above.
+
+More information about the ``flash_layout.h`` content, not SST related, is
+available in :doc:`platform readme </platform/ext/readme>` along with other
+platform information.
+
+TF-M NV Counter Interface
+=========================
+To have a platform independent way to access the NV counters, TF-M defines a
+platform NV counter interface. For API specification, please check:
+``platform/include/tfm_plat_nv_counters.h``
+
+The system integrators **may** implement this interface based on the target
+capabilities and set the ``SST_ROLLBACK_PROTECTION`` flag to compile in
+the rollback protection code.
+
+Secret Platform Unique Key
+==========================
+The encryption policy relies on a secret hardware unique key (HUK) per device.
+It is system integrator's responsibility to provide an implementation which
+**must** be a non-mutable target implementation.
+For API specification, please check:
+``platform/include/tfm_plat_crypto_keys.h``
+
+A stub implementation is provided in
+``platform/ext/<target>/dummy_crypto_keys.c``
+
+Flash Interface
+===============
+For SST service operations, a contiguous set of blocks must be earmarked for
+the secure storage area. The design requires either 2 blocks, or any number of
+blocks greater than or equal to 4. Total number of blocks can not be 0, 1 or 3.
+This is a design choice limitation to provide power failure safe update
+operations.
+
+For API specification, please check:
+``secure_fw/services/secure_storage/flash/sst_flash.h``
+
+Non-Secure Identity Manager
+===========================
+TF-M core tracks the current client IDs running in the secure or non-secure
+processing environment. It provides a dedicated API to retrieve the client ID
+which performs the service request.
+
+:doc:`NS client identification documentation </docs/user_guides/tfm_ns_client_identification>`
+provides further details on how client identification works.
+
+SST service uses that TF-M core API to retrieve the client ID and associate it
+as the owner of an asset. Only the owner can read, write or delete that asset
+based on the creation flags.
+
+The :doc:`integration guide </docs/user_guides/tfm_integration_guide>` provides further
+details of non-secure implementation requirements for TF-M.
+
+Cryptographic Interface
+=======================
+The reference encryption policy is built on AES-GCM, and it **may** be replaced
+by a vendor specific implementation.
+
+The SST service abstracts all the cryptographic requirements and specifies the
+required cryptographic interface in
+``secure_fw/services/secure_storage/crypto/sst_crypto_interface.h``
+
+Currently, the SST service cryptographic operations are implemented in
+``secure_fw/services/secure_storage/crypto/sst_crypto_interface.c``, using
+Mbed TLS library.
+
+SST Service Features Flags
+==========================
+SST service defines a set of flags that can be used to compile in/out certain
+SST service features. The ``CommonConfig.cmake`` file sets the default values
+of those flags. However, those flags values can be overwritten by setting them
+in ``platform/ext/<TARGET_NAME>.cmake`` based on the target capabilities or
+needs. The list of SST services flags are:
+
+- ``SST_ENCRYPTION``- this flag allows to enable/disable encryption
+ option to encrypt the secure storage data.
+- ``SST_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create a SST flash layout. If this flag is set, SST service will
+ generate an empty and valid SST flash layout to store assets. It will
+ erase all data located in the assigned SST memory area before generating
+ the SST layout. This flag is required to be set if the SST memory area
+ is located in a non-persistent memory. This flag can be set if the SST
+ memory area is located in a persistent memory without a valid SST flash
+ layout in it. That is the case when it is the first time in the device
+ life that the SST service is executed.
+- ``SST_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
+ enable/disable the validation mechanism to check the metadata store in flash
+ every time the flash data is read from flash. This validation is required
+ if the flash is not hardware protected against malicious writes. In case
+ the flash is protected against malicious writes (i.e embedded flash, etc),
+ this validation can be disabled in order to reduce the validation overhead.
+- ``SST_ROLLBACK_PROTECTION``- this flag allows to enable/disable
+ rollback protection in secure storage service. This flag takes effect only
+ if the target has non-volatile counters and ``SST_ENCRYPTION`` flag is on.
+- ``SST_RAM_FS``- this flag allows to enable/disable the use of RAM
+ instead of the flash to store the FS in secure storage service. This flag
+ is set by default in the regression tests, if it is not defined by the
+ platform. The SST regression tests reduce the life of the flash memory
+ as they write/erase multiple times in the memory.
+- ``SST_TEST_NV_COUNTERS``- this flag enables the virtual
+ implementation of the SST NV counters interface in
+ ``test/suites/sst/secure/nv_counters``, which emulates NV counters in
+ RAM, and disables the hardware implementation of NV counters provided by
+ the secure service. This flag is enabled by default when building the
+ regression tests and disabled by default otherwise. This flag can be
+ overridden to ``OFF`` when building the regression tests. In this case,
+ the SST rollback protection test suite will not be built, as it relies
+ on extra functionality provided by the virtual NV counters to simulate
+ different rollback scenarios. The remainder of the SST test suites will
+ run using the hardware NV counters. Please note that running the tests in
+ this configuration will quickly increase the hardware NV counter values,
+ which cannot be decreased again.
+ Overriding this flag from its default value of ``OFF`` when not
+ building the regression tests is not currently supported.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_build_instruction.md b/docs/user_guides/tfm_build_instruction.md
deleted file mode 100644
index 368557a..0000000
--- a/docs/user_guides/tfm_build_instruction.md
+++ /dev/null
@@ -1,183 +0,0 @@
-# TF-M build instruction
-
-Please make sure you have all required software installed as explained in the
-[software requirements](tfm_sw_requirement.md).
-
-## TF-M build steps
-TF-M uses [cmake](https://cmake.org/overview/) to provide an out-of-tree build
-environment. The instructions are below.
-
-*Note:* In the cmake configuration step, to enable debug symbols, the following
-option should be added:
-`-DCMAKE_BUILD_TYPE=Debug`
-
-*Note:* `-DCMAKE_BUILD_TYPE=Debug` only enables debug symbols for TF-M code. To
-enable debug symbols for the Mbed TLS library, add the following option to the
-CMake command:
-`-DMBEDTLS_DEBUG=ON`
-
-### External dependency
-* CMSIS_5 is used to import RTX for the example non-secure app
-* Mbed TLS is used as a crypto library on the secure side
-
-Both need to be cloned manually in the current release.
-
-### Build steps for the AN521 target platform:
-
-```
-cd <TF-M base folder>
-git clone https://git.trustedfirmware.org/trusted-firmware-m.git
-git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.7.9
-git clone https://github.com/ARM-software/CMSIS_5.git -b 5.2.0
-cd trusted-firmware-m
-mkdir cmake_build
-cd cmake_build
-cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
-cmake --build ./ -- install
-```
-### Concept of build config files
-The build configuration for TF-M is provided to the build system by three
-different components:
-
-* The way applications are built is specified by providing one of the
-`Config<APP_NAME>.cmake` files to the build system. This can be done by adding
-the `` -DPROJ_CONFIG=<absolute file path> `` i.e. on Linux:
-`` -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` `` parameter to the
-cmake command. (See examples below.)
-* The target platform can be specified by adding the
-`-DTARGET_PLATFORM=<target platform name>` option to the cmake command (See
- examples below.)
-* Supported platforms:
- * Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
- `-DTARGET_PLATFORM=AN521`
- * Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
- `-DTARGET_PLATFORM=AN519`
- * Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
- `-DTARGET_PLATFORM=MUSCA_A`
- * Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
- `-DTARGET_PLATFORM=MUSCA_B1`
-* The compiler toolchain to be used for the build must be specified by adding
-the `-DCOMPILER=<compiler name>` option to the cmake command (See examples
-below.) The possible values are
- - ARMCLANG
- - GNUARM
-
-*Note* Follow [secure boot](./tfm_secure_boot.md) to build the binaries with or
-without BL2 bootloader.
-
-### Regression Tests for the AN521 target platform
-The default option build doesn't include regression tests. Procedure for
-building the regression tests is below. Compiling for other target hardware
-is possible by selecting a different build config file.
-
-`It is recommended that tests are built in a different directory.`
-
-*TF-M build regression tests on Linux*
-
-```
-cd <TF-M base folder>
-cd trusted-firmware-m
-mkdir cmake_test
-cd cmake_test
-cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
-cmake --build ./ -- install
-```
-
-*TF-M build regression tests on Windows*
-
-```
-cd <TF-M base folder>
-cd trusted-firmware-m
-mkdir cmake_test
-cd cmake_test
-cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -m ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
-cmake --build ./ -- install
-```
-
-## Location of build artefacts
-
-The build system defines an API which allow easy usage of build artefacts. The
-`install` build target copies all files which might be needed as a dependency by
-external tools or build systems to the `<build_dir>/install/outputs` directory,
-with the following directory hierarchy:
-```
-<build_dir>/install/outputs/fvp/
-<build_dir>/install/outputs/<target_platform>/
-```
-There is one folder for FVP testing, with more elaborate naming and there is an
-other for testing on target hardware platform (AN521, etc.), where naming
-convention is aligned with 8.3 format. The dependency tree of `install` build
-target ensures a proper update (i.e. build) of all output files before the
-actual installation step takes place. As such it is suggested to use this build
-target to build TF-M.
-
-## Export dependency files for NS applications
-
-An NS application requires a number of files to interface with TF-M. The build
-system exports these files as part of the `install` target and places them in to
-a single directory, `<build_dir>/install/export/tfm`. Further details on how to
-integrate a new NS app with TF-M are available in the
-[integration guide](tfm_integration_guide.md).
-
-## Build for PSA API compliance tests
-
-The build system provides the support for linking with prebuilt PSA API
-compliance NS test libraries when using the `ConfigPsaApiTest.cmake` config
-file. The build system assumes that the PSA API compliance test suite is
-checked out at the same level of the TF-M root folder and the default name for
-the build folder has been used when compiling the PSA API compliance tests. Each
-set of tests for the Secure Storage, Crypto and Attestation services needs to be
-enabled at the build configuration step by defining
-`-DPSA_API_TEST_SECURE_STORAGE`, `-DPSA_API_TEST_CRYPTO`,
-`-DPSA_API_TEST_ATTESTATION`, respectively for the corresponding service. For
-example, to enable the PSA API tests for the Crypto service only:
-
-```
-...
-cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
-cmake --build ./ -- install
-```
-
-## Building the Reference Manual
-Please ensure the dependencies for building the firmware and the documentation
-are installed as explained in the [software requirements](tfm_sw_requirement.md).
-
-*Note* For building the documentation all tools needed to build the firmware
-must be available.
-
-~~~
-cd <TF-M base folder>
-mkdir cmake_doc
-cd cmake_doc
-cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
-cmake --build ./ -- install_doc
-~~~
-
-The documentation files will be available under the directory:
-~~~
-cmake_doc/install/doc/reference_manual
-~~~
-
-## Building the User Guide
-Please ensure the dependencies for building the firmware and the documentation
-are installed as explained in the [software requirements](tfm_sw_requirement.md).
-
-*Note* For building the documentation all tools needed to build the firmware
-must be available.
-
-~~~
-cd <TF-M base folder>
-mkdir cmake_doc
-cd cmake_doc
-cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
-cmake --build ./ -- install_userguide
-~~~
-
-The documentation files will be available under the directory:
-~~~
-cmake_doc/install/doc/user_guide
-~~~
-
---------------
-
-*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_build_instruction.rst b/docs/user_guides/tfm_build_instruction.rst
new file mode 100644
index 0000000..4c180c9
--- /dev/null
+++ b/docs/user_guides/tfm_build_instruction.rst
@@ -0,0 +1,217 @@
+######################
+TF-M build instruction
+######################
+Please make sure you have all required software installed as explained in the
+:doc:`software requirements <tfm_sw_requirement>`.
+
+*********************
+Configuring the build
+*********************
+The build configuration for TF-M is provided to the build system using command
+line arguments:
+
+.. list-table::
+ :widths: 20 80
+
+ * - -DPROJ_CONFIG=<file>
+ - Specifies the way the application is built.
+
+ | <file> is the absolute path to configurations file
+ named as ``Config<APP_NAME>.cmake``.
+ | i.e. On Linux:
+ ``-DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake```
+
+ * - -DTARGET_PLATFORM=<target platform name>
+ - Specifies the target platform.
+ Supported platforms:
+
+ - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
+ ``-DTARGET_PLATFORM=AN521``
+ - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
+ ``-DTARGET_PLATFORM=AN519``
+ - Musca-A1 test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_A``
+ - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_B1``
+
+ * - -DCOMPILER=<compiler name>
+ - Specifies the compiler toolchain
+ The possible values are:
+
+ - ``ARMCLANG``
+ - ``GNUARM``
+ * - -DCMAKE_BUILD_TYPE=<build type>
+ - Configures debugging support.
+ The possible values are:
+
+ - ``Debug``
+ - ``Release``
+ - ``Relwithdebinfo``
+ - ``Minsizerel``
+ * - -DMBEDTLS_DEBUG=<ON|OFF>
+ - To enables debug symbols for the Mbed TLS library.
+
+.. Note::
+ Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
+ without BL2 bootloader.
+
+*******************
+External dependency
+*******************
+- CMSIS_5 is used to import RTX for the example non-secure app
+- Mbed TLS is used as a crypto library on the secure side
+
+****************
+TF-M build steps
+****************
+TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
+build environment. The instructions are below.
+
+.. Note::
+
+ It is recommended to build each different build configurations in separate
+ directories.
+
+Getting the source-code
+=======================
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ git clone https://git.trustedfirmware.org/trusted-firmware-m.git
+ git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.7.9
+ git clone https://github.com/ARM-software/CMSIS_5.git -b 5.2.0
+
+Build steps for the AN521 target platform:
+==========================================
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_build
+ cd cmake_build
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
+ cmake --build ./ -- install
+
+Regression Tests for the AN521 target platform
+==============================================
+*TF-M build regression tests on Linux*
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_test
+ cd cmake_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+*TF-M build regression tests on Windows*
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_test
+ cd cmake_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+Build for PSA API compliance tests
+==================================
+The build system provides the support for linking with prebuilt PSA API
+compliance NS test libraries when using the ``ConfigPsaApiTest.cmake``
+config file. The build system assumes that the PSA API compliance test suite
+is checked out at the same level of the TF-M root folder and the default
+name for the build folder has been used when compiling the PSA API compliance
+tests. Each set of tests for the Secure Storage, Crypto and Attestation services
+needs to be enabled at the build configuration step by defining::
+
+ -DPSA_API_TEST_SECURE_STORAGE -DPSA_API_TEST_CRYPTO -DPSA_API_TEST_ATTESTATION
+
+respectively for the corresponding service. For example, to enable the PSA API
+tests for the Crypto service only:
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_psa_test
+ cd cmake_psa_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+Location of build artifacts
+===========================
+The build system defines an API which allow easy usage of build
+artifacts. The ``install`` build target copies all files which might be needed
+as a dependency by external tools or build systems to the
+``<build_dir>/install/outputs``
+directory, with the following directory hierarchy:
+
+::
+
+ <build_dir>/install/outputs/fvp/
+ <build_dir>/install/outputs/<target_platform>/
+
+There is one folder for FVP testing, with more elaborate naming and
+there is an other for testing on target hardware platform (AN521, etc.), where
+naming convention is aligned with 8.3 format. The dependency tree of
+``install`` build target ensures a proper update (i.e. build) of all output
+files before the actual installation step takes place. As such it is suggested
+to use this build target to build TF-M.
+
+Export dependency files for NS applications
+-------------------------------------------
+An NS application requires a number of files to interface with TF-M.
+The build system exports these files as part of the ``install`` target and
+places them in to a single directory::
+
+ <build_dir>/install/export/tfm
+
+Further details on how to integrate a new NS app with TF-M are available in the
+:doc:`integration guide <tfm_integration_guide>`.
+
+Building the documentation
+==========================
+Please ensure the dependencies for building the firmware and the
+documentation are installed as explained in the
+:doc:`software requirements <tfm_sw_requirement>`.
+
+Building PDF output is optional and can be disabled by removing LaTex from the
+PATH.
+
+.. Note::
+ For building the documentation all tools needed to build the firmware must
+ be available.
+
+Building the Reference Manual
+-----------------------------
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ mkdir cmake_doc
+ cd cmake_doc
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
+ cmake --build ./ -- install_doc
+
+The documentation files will be available under the directory::
+
+ cmake_doc/install/doc/reference_manual
+
+Building the User Guide
+-----------------------
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ mkdir cmake_doc
+ cd cmake_doc
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
+ cmake --build ./ -- install_userguide
+
+The documentation files will be available under the directory::
+
+ cmake_doc/install/doc/user_guide
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_integration_guide.md b/docs/user_guides/tfm_integration_guide.md
deleted file mode 100644
index 4c028a4..0000000
--- a/docs/user_guides/tfm_integration_guide.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# TF-M integration guide
-The purpose of this document is to provide a guide on how to integrate TF-M with
-other hardware platforms and operating systems.
-## How to build TF-M
-Follow the [Build instructions](tfm_build_instruction.md).
-
-## How to export files for building non-secure applications
-Explained in the [Build instructions](tfm_build_instruction.md).
-
-## How to add a new platform
-The hardware platforms currently supported are:
-
-* Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
-* Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
-* Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
-* Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
-
-The files related to the supported platforms are contained under the `platform`
-subfolder. The platform specific files are under `platform/ext/target`, which is
-organized by boards (e.g. `platform/ext/target/mps2`), while the folder
-`platform/ext/common` is used to store source and header files which are
-platform generic.
-More information about subsystems supported by the MPS2+ board can be found in:
-[MPS2+ homepage](https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps2)
-More information about the Musca-A test chip board can be found in:
-[Musca-A homepage](https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board)
-More information about the Musca-B1 test chip board can be found in:
-[Musca-B1 homepage](https://www.arm.com/products/development-tools/development-boards/musca-b1-iot)
-
-#### generic drivers and startup/scatter files
-The addition of a new platform means the creation of a new subfolder inside
-`target/<board_name>` to provide an implementation of the drivers currently used
-by TF-M, in particular MPC, PPC, and USART drivers. In addition to the drivers,
-startup and scatter files need to be provided for the supported toolchains.
-There are also board specific drivers which are used by the board platform to
-interact with the external world, for example during tests, that have to be
-provided, e.g. to blink LEDs or count time in the MPS2 board.
-
-`Note: Currently SST and BL2 bootloader use different flash interface`
-
-#### target configuration files
-Inside the base root folder of the selected target, each implementation has to
-provide its own copy of `target_cfg.c/.h`. This file has target specific
-configuration functions and settings that are called by the TF-M during the
-platform configuration step during TF-M boot. Examples of the configurations
-performed during this phase are the MPC configuration, the SAU configuration,
-or eventually PPC configuration if supported by the hardware platform.
-Similarly, the `uart_stdout.c` is used to provide functions needed to redirect
-the stdout on UART (this is currently used by TF-M to log messages).
-
-#### platform retarget files
-An important part that each new platform has to provide is the set of retarget
-files which are contained inside the `retarget` folder. These files define the
-peripheral base addresses for the platform, both for the secure and non-secure
-aliases (when available), and bind those addresses to the base addresses used by
-the devices available in the hardware platform.
-
-## How to integrate another OS
-To work with TF-M, the OS needs to support the Armv8-M architecture and,
-in particular, it needs to be able to run in the non-secure world. More
-information about OS migration to the Armv8-M architecture can be found in the
-[OS requirements](os_migration_guide_armv8m.md). Depending upon the system
-configuration this may require configuring drivers to use appropriate address
-ranges.
-
-#### interface with TF-M
-The files needed for the interface with TF-M are exported at the
-`<build_dir>/install/export/tfm` path. The NS side is only allowed to call TF-M
-secure functions (veneers) from the NS Thread mode. For this reason, the API is
-a collection of functions in the `<build_dir>/install/export/tfm/inc`
-directory. For example, the interface for the Secure STorage (SST) service
-is described in the file `psa_sst_api.h` as a collection of
-functions that call service veneer functions. This API is a wrapper for the
-secure veneers, and returns the return value from the service to the caller.
-The secure storage service uses a numerical ID, to identify the clients that use
-the service. For details see
-[ns client identification documentation](tfm_ns_client_identification.md).
-
-#### interface with non-secure world regression tests
-A non-secure application that wants to run the non-secure regression tests
-needs to call the `tfm_non_secure_client_run_tests()`. This function is
-exported into the header file `test_framework_integ_test.h` inside the
-`<build_dir>/install` folder structure in the test specific files, i.e.
-`<build_dir>/install/export/tfm/test/inc`. The non-secure regression tests are
-precompiled and delivered as a static library which is available in
-`<build_dir>/install/export/tfm/test/lib`, so that the non-secure application
-needs to link against the library to be able to invoke the
-`tfm_non_secure_client_run_tests()` function. The SST non-secure side regression
-tests rely on some OS functionality e.g. threads, mutexes etc. These functions
-comply with CMSIS RTOS2 standard and have been exported as thin wrappers defined
-in `os_wrapper.h` contained in `<build_dir>/install/export/tfm/test/inc`. OS
-needs to provide the implementation of these wrappers to be able to run the
-tests.
-
-#### NS client Identification
-See [ns client identification documentation](tfm_ns_client_identification.md).
-
---------------
-
-*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_integration_guide.rst b/docs/user_guides/tfm_integration_guide.rst
new file mode 100644
index 0000000..41f10ed
--- /dev/null
+++ b/docs/user_guides/tfm_integration_guide.rst
@@ -0,0 +1,126 @@
+######################
+TF-M integration guide
+######################
+The purpose of this document is to provide a guide on how to integrate TF-M
+with other hardware platforms and operating systems.
+
+*****************
+How to build TF-M
+*****************
+Follow the :doc:`Build instructions <tfm_build_instruction>`.
+
+********************************************************
+How to export files for building non-secure applications
+********************************************************
+Explained in the :doc:`Build instructions <tfm_build_instruction>`.
+
+*************************
+How to add a new platform
+*************************
+The hardware platforms currently supported are:
+
+- Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
+- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
+- Musca-A1 test chip board (Cortex-M33 SSE-200 subsystem)
+- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+
+The files related to the supported platforms are contained under the
+``platform`` subfolder. The platform specific files are under
+``platform/ext/target``, which is organised by boards
+(e.g. ``platform/ext/target/mps2``), while the folder ``platform/ext/common``
+is used to store source and header files which are platform generic.
+
+More information about subsystems supported by the MPS2+ board can be found in:
+`MPS2+ homepage <https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps2>`__
+
+More information about the Musca-A1 test chip board can be found in:
+`Musca-A homepage <https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board>`__
+
+More information about the Musca-B1 test chip board can be found in:
+`Musca-B1 homepage <https://www.arm.com/products/development-tools/development-boards/musca-b1-iot>`__
+
+Generic drivers and startup/scatter files
+=========================================
+The addition of a new platform means the creation of a new subfolder inside
+``target/<board_name>`` to provide an implementation of the drivers currently
+used by TF-M, in particular MPC, PPC, and USART drivers. In addition to the
+drivers, startup and scatter files need to be provided for the supported
+toolchains.
+
+There are also board specific drivers which are used by the board
+platform to interact with the external world, for example during tests, that
+have to be provided, e.g. to blink LEDs or count time in the MPS2 board.
+
+.. Note::
+
+ Currently SST and BL2 bootloader use different flash interface
+
+Target configuration files
+==========================
+Inside the base root folder of the selected target, each implementation has to
+provide its own copy of ``target_cfg.c/.h``. This file has target specific
+configuration functions and settings that are called by the TF-M during the
+platform configuration step during TF-M boot. Examples of the configurations
+performed during this phase are the MPC configuration, the SAU configuration,
+or eventually PPC configuration if supported by the hardware platform.
+Similarly, the ``uart_stdout.c`` is used to provide functions needed to redirect
+the stdout on UART (this is currently used by TF-M to log messages).
+
+Platform retarget files
+=======================
+An important part that each new platform has to provide is the set of retarget
+files which are contained inside the ``retarget`` folder. These files define the
+peripheral base addresses for the platform, both for the secure and non-secure
+aliases (when available), and bind those addresses to the base addresses used by
+the devices available in the hardware platform.
+
+***************************
+How to integrate another OS
+***************************
+To work with TF-M, the OS needs to support the Armv8-M architecture and, in
+particular, it needs to be able to run in the non-secure world. More
+information about OS migration to the Armv8-M architecture can be found in the
+:doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon the system
+configuration this may require configuring drivers to use appropriate address
+ranges.
+
+Interface with TF-M
+===================
+The files needed for the interface with TF-M are exported at the
+``<build_dir>/install/export/tfm`` path. The NS side is only allowed to call
+TF-M secure functions (veneers) from the NS Thread mode. For this reason, the
+API is a collection of functions in the ``<build_dir>/install/export/tfm/inc``
+directory. For example, the interface for the Secure STorage (SST) service
+is described in the file ``psa_sst_api.h`` as a collection of functions that
+call service veneer functions. This API is a wrapper for the secure veneers,
+and returns the return value from the service to the caller.
+
+The secure storage service uses a numerical ID, to identify the clients that use
+the service. For details see
+:doc:`ns client identification documentation <tfm_ns_client_identification>`.
+
+Interface with non-secure world regression tests
+================================================
+A non-secure application that wants to run the non-secure regression tests
+needs to call the ``tfm_non_secure_client_run_tests()``. This function is
+exported into the header file ``test_framework_integ_test.h`` inside the
+``<build_dir>/install`` folder structure in the test specific files,
+i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression
+tests are precompiled and delivered as a static library which is available in
+``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application
+needs to link against the library to be able to invoke the
+``tfm_non_secure_client_run_tests()`` function. The SST non-secure side
+regression tests rely on some OS functionality e.g. threads, mutexes etc. These
+functions comply with CMSIS RTOS2 standard and have been exported as thin
+wrappers defined in ``os_wrapper.h`` contained in
+``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the
+implementation of these wrappers to be able to run the tests.
+
+NS client Identification
+========================
+See
+:doc:`ns client identification documentation <tfm_ns_client_identification>`.
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_ns_client_identification.md b/docs/user_guides/tfm_ns_client_identification.rst
similarity index 65%
rename from docs/user_guides/tfm_ns_client_identification.md
rename to docs/user_guides/tfm_ns_client_identification.rst
index fb6590b..9faccfb 100644
--- a/docs/user_guides/tfm_ns_client_identification.md
+++ b/docs/user_guides/tfm_ns_client_identification.rst
@@ -1,5 +1,6 @@
-# Non-Secure Identity Manager
-
+###########################
+Non-Secure Identity Manager
+###########################
The ID of the current application/thread is known by TF-M, and the SST service
queries the ID of the currently running client via a dedicated API.
@@ -9,34 +10,34 @@
Tracking of context changes are possible by relying on the NS OS calling the
Thread Context Management for Armv8-M TrustZone APIs, as described
-[here](https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html)
+`here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
However TF-M needs an extra API, to assign a client ID to the TZ context created
as a result of the
-`TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)` call.
+``TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)`` call.
To do this, the
-`enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)` have to be
+``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)`` have to be
called from an SVC handler, with the client ID of the currently running client.
In the current implementation of TF-M, an SVC call is provided for the NS
clients to be called at the beginning of their main function.
-```SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);```
+``SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);``
The SVC call handler of the above SVC maps the name of the current thread to a
hardcoded client id, and sends it to the TF-M core via the earlier discussed
API.
-The mapping is implemented in `interface/src/tfm_nspm_svc_handler.c`.
+The mapping is implemented in ``interface/src/tfm_nspm_svc_handler.c``.
The system integrators **may** implement the non-secure ID mapping based on
their application/threat model.
-In case the NS OS doesn't use the Thread Context Management for Armv8-M TrustZone
-APIs, then TF-M considers the NS SW as a single client, and assigns a client ID
-to it automatically.
+In case the NS OS doesn't use the Thread Context Management for Armv8-M
+TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a
+client ID to it automatically.
--------------
-*Copyright (c) 2018, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_secure_boot.md b/docs/user_guides/tfm_secure_boot.md
deleted file mode 100644
index 033c4e8..0000000
--- a/docs/user_guides/tfm_secure_boot.md
+++ /dev/null
@@ -1,365 +0,0 @@
-# Trusted Firmware M secure boot
-For secure devices it is security critical to enforce firmware authenticity to
-protect against execution of malicious software. This is implemented by building
-a trust chain where each step in the execution chain authenticates the next
-step before execution. The chain of trust in based on a "Root of Trust" which
-is implemented using asymmetric cryptography. The Root of Trust is a combination
-of an immutable bootloader and a public key(ROTPK).
-
-# Second stage bootloader in TF-M
-To implement secure boot functionality an external project MCUBoot has been
-integrated to TF-M. For further information please refer to the
-[MCUBoot homepage](https://www.mcuboot.com/).
-Original source-code is available at
-[GitHub](https://github.com/runtimeco/mcuboot).
-This document contains information about MCUBoot modifications and how MCUBoot
-has been integrated to TF-M.
-
-Bootloader is started when CPU is released from reset. It runs in secure mode.
-It authenticates the firmware image by hash (SHA-256) and digital signature
-(RSA-2048) validation. Public key, that the checks happens against, is built
-into the bootloader image. Metadata of the image is delivered together with the
-image itself in a header and trailer section. In case of successful
-authentication, bootloader passes execution to the secure image. Execution never
-returns to bootloader until next reset.
-
-A default RSA key pair is stored in the repository, public key is in `keys.c`
-and private key is in `root-rsa-2048.pem`. `DO NOT use them in production code,
-they are exclusively for testing!` Private key must be stored in a safe place
-outside of the repository. `Imgtool.py` can be used to generate new key pairs.
-
-The bootloader handles the secure and non-secure images as a single blob which
-is contiguous in the device memory. At compile time these images are
-concatenated and signed with RSA-2048 digital signature. Preparation of payload
-is done by Python scripts: `bl2/ext/mcuboot/scripts/`. At the end of a
-successful build signed TF-M payload can be found in:
-```
-<build_dir>/install/outputs/fvp/tfm_sign.bin
-```
-
-## Integration with TF-M
-MCUBoot assumes a predefined memory layout which is described below
-(applicable for AN521). It is mandatory to define slot 0, slot 1 and scratch
-partitions, but their size can be changed:
-```
-- 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
-- 0x0008_0000 - 0x000F_FFFF: Slot 0 : Single binary blob: Secure + Non-Secure
- image; Primary memory partition
- - 0x0008_0000 - 0x0008_03FF: Common image header
- - 0x0008_0400 - 0x0008_xxxx: Secure image
- - 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
- - 0x0010_0400 - 0x0010_xxxx: Non-secure image
- - 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256) and RSA signature
- of combined image
-
-- 0x0018_0000 - 0x0027_FFFF: Slot 1 : Secure + Non-Secure image; Secondary
- memory partition, structured identically to slot
- 0
-- 0x0028_0000 - 0x0037_FFFF: Scratch area, used during image swapping
-```
-
-## Firmware upgrade operation
-MCUBoot handles only the firmware authenticity check after start-up and the
-firmware switch part of the firmware update process. Downloading the new version
-of the firmware is out-of-scope for MCUBoot. MCUBoot supports two different ways
-to switch to the new firmware and it is assumed that firmware images are
-executed-in-place (XIP). The default behaviour is the image swapping. In this
-case active firmware is always executed from slot 0 and slot 1 is a staging area
-for new images. Before executing the new firmware image, the content of the two
-memory slots must be physically swapped. The other option is the non-swapping
-version, which eliminates the complexity of image swapping and its
-administration. Active image can be executed from either memory slot, but new
-firmware must be linked to the address space of the proper (currently inactive)
-memory slot.
-
-### Swapping operation
-Active image is stored in slot 0, and this image is started always by the
-bootloader. Therefore images must be linked to slot 0. If the bootloader finds a
-valid image in slot 1, which is marked for upgrade, then contents of slot 0 and
-slot 1 will be swapped, before starting the new image from slot 0. Scratch area
-is used as a temporary storage place during image swapping. Update mark from
-slot 1 is removed when the swapping is successful. The boot loader can revert
-the swapping as a fall-back mechanism to recover the previous working firmware
-version after a faulty update. The swap operation is fail-safe and resistant to
-power-cut failures. For more details please refer to the MCUBoot [documentation](https://www.mcuboot.com/mcuboot/design.html).
-
-### Non-swapping operation
-This operation can be turned on with `MCUBOOT_NO_SWAP` compile time switch. See
-[next chapter](#Build time configuration). When enabling non-swapping operation
-then the active image flag is moved between slots during firmware upgrade. If
-firmware is executed-in-place (XIP), then two firmware images must be generated.
-One of them is linked to be executed from slot 0 memory region and the other
-from slot 1. The firmware upgrade client, which downloads the new image, must be
-aware, which slot hosts the active firmware and which acts as a staging area and
-it is responsible for downloading the proper firmware image. At boot time
-MCUBoot inspects the version number in the image header and passes execution to
-the newer firmware version. New image must be marked for upgrade which is
-automatically done by Python scripts at compile time. Image verification is done
-the same way in both operational modes. If new image fails during authentication
-then MCUBoot erases the memory slot and starts the other image, after successful
-authentication.
-
-At build time automatically two binaries are generated:
-```
-<build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin : Image linked for slot 0
- memory partition
-<build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin : Image linked for slot 1
- memory partition
-```
-
-### RAM Loading firmware upgrade
-Musca-A supports an image upgrade mode that is separate to both the swapping
-and non-swapping modes. This is the `RAM loading` mode (please refer to the
-table below). Like the non-swapping mode, this selects the newest image by
-reading the image version numbers in the image headers, but instead of
-executing it in place, the newest image is copied to RAM for execution. The
-load address, the location in RAM where the image is copied to, is stored
-in the image header.
-
-### Summary of different modes for image upgrade
-
-Different implementations of the image upgrade operation (whether through
-swapping, non-swapping, or loading into RAM and executing from there)
-are supported by the platforms. The table below shows which of these modes
-are supported by which platforms:
-
-| - | Without BL2 <sup>1</sup> | With BL2 <sup>2</sup> | With BL2 <sup>2</sup> | With BL2 <sup>2</sup> |
-|:--------:|:------------------------:|:---------------------:|:---------------------:|:------------------------:|
-| - | XIP | XIP | XIP | Not XIP |
-| - | - | Swap <sup>3</sup> | No-swap <sup>4</sup> | RAM loading <sup>5</sup> |
-| AN521 | Yes | Yes | Yes | No |
-| AN519 | Yes | Yes | Yes | No |
-| Musca-A | No | No | No | Yes |
-| Musca-B1 | Yes | No | Yes | No |
-
-(1) To disable BL2, please turn off the `BL2` compiler switch in the
-top-level configuration files or in the command line
-
-(2) BL2 is enabled by default
-
-(3) The image executes in-place (XIP) and is in swapping mode for image update
-by default
-
-(4) To enable XIP No-swap, set the configuration variable `MCUBOOT_NO_SWAP` to
-`True` in the top-level configuration files, or include the `MCUBOOT_NO_SWAP`
-macro in the command line
-
-(5) To enable RAM loading, set the configuration variable `MCUBOOT_RAM_LOADING`
-to `True` in the top-level configuration files, or include the
-`MCUBOOT_RAM_LOADING` macro in the command line
-
-## Build time configuration
-MCUBoot related compile time switches can be set in the high level build
-configuration files:
-```
-ConfigDefault.cmake
-ConfigCoreTest.cmake
-ConfigRegression.cmake
-```
-
-Compile time switches:
-
-- BL2 (default: True):
- - **True:** TF-M built together with bootloader. MCUBoot is executed after
- reset and it authenticates TF-M and starts secure code.
- - **False:** TF-M built without bootloader. Secure image linked to the
- beginning of the device memory and executed after reset. If it is false then
- using any of the further compile time switches are invalid.
-- MCUBOOT\_NO\_SWAP (default: False):
- - **True:** Activate non-swapping firmware upgrade operation.
- - **False:** Original firmware upgrade operation with image swapping.
-- MCUBOOT\_RAM\_LOADING (default: False):
- - **True:** Activate RAM loading firmware upgrade operation, where latest
- image is copied to RAM and runs from there instead of being executed
- in-place.
- - **False:** Original firmware upgrade operation with image swapping.
-
-### Image versioning
-An image version number is written to its header by one of the python scripts,
-and this number is used by the bootloader when the non-swapping mode is
-enabled.
-
-The version number of the image can manually be passed in through the command
-line in the cmake configuration step:
-```
-cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DIMAGE_VERSION=1.2.3+4 ../
-```
-Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
-where the missing numbers are automatically set to zero. The image version
-number argument is optional, and if it is left out, then the version numbers of
-the image(s) being built in the same directory will automatically change. In
-this case, the last component (the build number) automatically increments from
-the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
-**until a number is explicitly provided**. If automatic versioning is in place
-and then an image version number is provided for the first time, the new number
-will take precedence and be used instead. All subsequent image versions are
-then set to the last number that has been specified, and the build number would
-stop incrementing. Any new version numbers that are provided will overwrite
-the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
-versioning, please start a clean build without specifying the image version
-number at all.
-
-## Testing firmware upgrade
-As downloading the new firmware image is out of scope for MCUBoot, the update
-process is started from a state where the original and the new image are already
-programmed to the appropriate memory slots. To generate the original and a new
-firmware package, TF-M is built twice with different build configurations.
-
-### Swapping firmware upgrade
-Run TF-M build twice with two different build configuration: default and
-regression. Save the artefacts between builds, because second run can overwrite
-original binaries. Download default build to slot 0 and regression build to
-slot 1.
-
-#### Executing firmware upgrade on FVP\_MPS2\_AEMv8M
-```
-<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
---parameter fvp_mps2.platform_type=2 \
---parameter cpu0.baseline=0 \
---parameter cpu0.INITVTOR_S=0x10000000 \
---parameter cpu0.semihosting-enable=0 \
---parameter fvp_mps2.DISABLE_GATING=0 \
---parameter fvp_mps2.telnetterminal0.start_telnet=1 \
---parameter fvp_mps2.telnetterminal1.start_telnet=0 \
---parameter fvp_mps2.telnetterminal2.start_telnet=0 \
---parameter fvp_mps2.telnetterminal0.quiet=0 \
---parameter fvp_mps2.telnetterminal1.quiet=1 \
---parameter fvp_mps2.telnetterminal2.quiet=1 \
---application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
---data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
---data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
-```
-
-#### Executing firmware upgrade on SSE 200 FPGA on MPS2 board
-```
-TITLE: Versatile Express Images Configuration File
-[IMAGES]
-TOTALIMAGES: 3 ;Number of Images (Max: 32)
-IMAGE0ADDRESS: 0x00000000
-IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
-IMAGE1ADDRESS: 0x10080000
-IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M example application binary blob
-IMAGE2ADDRESS: 0x10180000
-IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
-```
-
-The following message will be shown in case of successful firmware upgrade,
-`Swap type: test` indicates that images were swapped:
-```
-[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
-[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
-[INF] Boot source: slot 0
-[INF] Swap type: test
-[INF] Bootloader chainload address offset: 0x80000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-
-#### Execute test suites for the secure storage service ####
-Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
-...
-```
-
-### Non-swapping firmware upgrade
-Follow the same instructions as in case of swapping build including these
-changes:
-
-- Set MCUBOOT\_NO\_SWAP compile time switch to true before build.
-- Increase the image version number between the two build run.
-
-#### Executing firmware upgrade on FVP\_MPS2\_AEMv8M
-```
-<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
---parameter fvp_mps2.platform_type=2 \
---parameter cpu0.baseline=0 \
---parameter cpu0.INITVTOR_S=0x10000000 \
---parameter cpu0.semihosting-enable=0 \
---parameter fvp_mps2.DISABLE_GATING=0 \
---parameter fvp_mps2.telnetterminal0.start_telnet=1 \
---parameter fvp_mps2.telnetterminal1.start_telnet=0 \
---parameter fvp_mps2.telnetterminal2.start_telnet=0 \
---parameter fvp_mps2.telnetterminal0.quiet=0 \
---parameter fvp_mps2.telnetterminal1.quiet=1 \
---parameter fvp_mps2.telnetterminal2.quiet=1 \
---application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
---data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin@0x10080000 \
---data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin@0x10180000
-```
-
-#### Executing firmware upgrade on SSE 200 FPGA on MPS2 board
-```
-TITLE: Versatile Express Images Configuration File
-[IMAGES]
-TOTALIMAGES: 3 ;Number of Images (Max: 32)
-IMAGE0ADDRESS: 0x00000000
-IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
-IMAGE1ADDRESS: 0x10080000
-IMAGE1FILE: \Software\tfm_sig0.bin ; TF-M example application binary blob
-IMAGE2ADDRESS: 0x10180000
-IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
-```
-
-#### Executing firmware upgrade on Musca-B1 board
-After two images have been built, they can be concatenated to create the
-combined image using `srec_cat`:
-
-- Linux: `srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel`
-
-- Windows: `srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel`
-
-The following message will be shown in case of successful firmware upgrade,
-notice that image with higher version number (`version=1.2.3.5`) is executed:
-```
-[INF] Starting bootloader
-[INF] Image 0: version=1.2.3.4, magic= good, image_ok=0xff
-[INF] Image 1: version=1.2.3.5, magic= good, image_ok=0xff
-[INF] Booting image from slot 1
-[INF] Bootloader chainload address offset: 0x180000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-
-#### Execute test suites for the Secure area ####
-Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
-...
-```
-
-### RAM loading firmware upgrade
-To enable RAM loading, please set `MCUBOOT_RAM_LOADING` to True (either in the
-configuration file or through the command line), and then specify a destination
-load address in RAM where the image can be copied to and executed from. The
-`IMAGE_LOAD_ADDRESS` macro must be specified in the target dependent files,
-for example with Musca-A, its `flash_layout.h` file in the `platform` folder
-should include `#define IMAGE_LOAD_ADDRESS #0x10020000`
-
-#### Executing firmware upgrade on Musca-A board
-After two images have been built, they can be concatenated to create the
-combined image using `srec_cat`:
-
-```
-Windows:
-srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000
-tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset
-0x320000 -o tfm.hex -Intel
-
-Linux:
-srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin
--Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset
-0x320000 -o tfm.hex -Intel
-```
-
-The following message will be shown in case of successful firmware upgrade when,
-RAM loading is enabled, notice that image with higher version number
-(`version=0.0.0.2`) is executed:
-
-```
-[INF] Image 0: version=0.0.0.1, magic= good, image_ok=0xff
-[INF] Image 1: version=0.0.0.2, magic= good, image_ok=0xff
-[INF] Image has been copied from slot 1 in flash to SRAM address 0x10020000
-[INF] Booting image from SRAM at address 0x10020000
-[INF] Bootloader chainload address offset: 0x20000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-```
-
---------------
-
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_secure_boot.rst b/docs/user_guides/tfm_secure_boot.rst
new file mode 100644
index 0000000..bef546c
--- /dev/null
+++ b/docs/user_guides/tfm_secure_boot.rst
@@ -0,0 +1,398 @@
+##############################
+Trusted Firmware M secure boot
+##############################
+For secure devices it is security critical to enforce firmware authenticity to
+protect against execution of malicious software. This is implemented by building
+a trust chain where each step in the execution chain authenticates the next
+step before execution. The chain of trust in based on a "Root of Trust" which
+is implemented using asymmetric cryptography. The Root of Trust is a combination
+of an immutable bootloader and a public key (ROTPK).
+
+*******************************
+Second stage bootloader in TF-M
+*******************************
+To implement secure boot functionality an external project MCUBoot has been
+integrated to TF-M. For further information please refer to the
+`MCUBoot homepage <https://www.mcuboot.com/>`__. Original source-code is available at
+`GitHub <https://github.com/runtimeco/mcuboot>`__. This document contains
+information about MCUBoot modifications and how MCUBoot has been integrated to
+TF-M.
+
+Bootloader is started when CPU is released from reset. It runs in secure mode.
+It authenticates the firmware image by hash (SHA-256) and digital signature
+(RSA-2048) validation. Public key, that the checks happens against, is built
+into the bootloader image. Metadata of the image is delivered together with the
+image itself in a header and trailer section. In case of successful
+authentication, bootloader passes execution to the secure image. Execution never
+returns to bootloader until next reset.
+
+A default RSA key pair is stored in the repository, public key is in ``keys.c``
+and private key is in ``root-rsa-2048.pem``.
+.. Warning::
+
+ ``DO NOT use them in production code, they are exclusively for testing!``
+
+Private key must be stored in a safe place outside of the repository.
+``Imgtool.py`` can be used to generate new key pairs.
+
+The bootloader handles the secure and non-secure images as a single blob which
+is contiguous in the device memory. At compile time these images are
+concatenated and signed with RSA-2048 digital signature. Preparation of payload
+is done by Python scripts: ``bl2/ext/mcuboot/scripts/``. At the end of a
+successful build signed TF-M payload can be found in::
+
+ <build_dir>/install/outputs/fvp/tfm_sign.bin
+
+*********************
+Integration with TF-M
+*********************
+MCUBoot assumes a predefined memory layout which is described below (applicable
+for AN521). It is mandatory to define slot 0, slot 1 and scratch partitions, but
+their size can be changed::
+
+ - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
+ - 0x0008_0000 - 0x000F_FFFF: Slot 0 : Single binary blob: Secure + Non-Secure
+ image; Primary memory partition
+ - 0x0008_0000 - 0x0008_03FF: Common image header
+ - 0x0008_0400 - 0x0008_xxxx: Secure image
+ - 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
+ - 0x0010_0400 - 0x0010_xxxx: Non-secure image
+ - 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256) and RSA signature
+ of combined image
+
+ - 0x0018_0000 - 0x0027_FFFF: Slot 1 : Secure + Non-Secure image; Secondary
+ memory partition, structured identically to slot
+ 0
+ - 0x0028_0000 - 0x0037_FFFF: Scratch area, used during image swapping
+
+**************************
+Firmware upgrade operation
+**************************
+MCUBoot handles only the firmware authenticity check after start-up and the
+firmware switch part of the firmware update process. Downloading the new version
+of the firmware is out-of-scope for MCUBoot. MCUBoot supports two different ways
+to switch to the new firmware and it is assumed that firmware images are
+executed-in-place (XIP). The default behaviour is the image swapping. In this
+case active firmware is always executed from slot 0 and slot 1 is a staging area
+for new images. Before executing the new firmware image, the content of the two
+memory slots must be physically swapped. The other option is the non-swapping
+version, which eliminates the complexity of image swapping and its
+administration. Active image can be executed from either memory slot, but new
+firmware must be linked to the address space of the proper (currently inactive)
+memory slot.
+
+Swapping operation
+==================
+Active image is stored in slot 0, and this image is started always by the
+bootloader. Therefore images must be linked to slot 0. If the bootloader finds a
+valid image in slot 1, which is marked for upgrade, then contents of slot 0 and
+slot 1 will be swapped, before starting the new image from slot 0. Scratch area
+is used as a temporary storage place during image swapping. Update mark from
+slot 1 is removed when the swapping is successful. The boot loader can revert
+the swapping as a fall-back mechanism to recover the previous working firmware
+version after a faulty update. The swap operation is fail-safe and resistant to
+power-cut failures. For more details please refer to the MCUBoot
+`documentation <https://www.mcuboot.com/mcuboot/design.html>`__.
+
+Non-swapping operation
+======================
+This operation can be turned on with ``MCUBOOT_NO_SWAP`` compile time switch
+(see `Build time configuration`_). When enabling non-swapping operation then the
+active image flag is moved between slots during firmware upgrade. If firmware is
+executed-in-place (XIP), then two firmware images must be generated.
+One of them is linked to be executed from slot 0 memory region and the other
+from slot 1. The firmware upgrade client, which downloads the new image, must be
+aware, which slot hosts the active firmware and which acts as a staging area and
+it is responsible for downloading the proper firmware image. At boot time
+MCUBoot inspects the version number in the image header and passes execution to
+the newer firmware version. New image must be marked for upgrade which is
+automatically done by Python scripts at compile time. Image verification is done
+the same way in both operational modes. If new image fails during authentication
+then MCUBoot erases the memory slot and starts the other image, after successful
+authentication.
+
+At build time automatically two binaries are generated::
+
+ <build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin : Image linked for slot 0
+ memory partition
+ <build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin : Image linked for slot 1
+ memory partition
+
+RAM Loading firmware upgrade
+============================
+Musca A1 supports an image upgrade mode that is separate to both the swapping
+and non-swapping modes. This is the ``RAM loading`` mode (please refer to the
+table below). Like the non-swapping mode, this selects the newest image by
+reading the image version numbers in the image headers, but instead of
+executing it in place, the newest image is copied to RAM for execution. The
+load address, the location in RAM where the image is copied to, is stored
+in the image header.
+
+Summary of different modes for image upgrade
+============================================
+Different implementations of the image upgrade operation (whether through
+swapping, non-swapping, or loading into RAM and executing from there) are
+supported by the platforms. The table below shows which of these
+modes are supported by which platforms:
+
++------------+-----------------+--------------+--------------+-----------------+
+| | Without BL2 [1]_| With BL2 [2]_| With BL2 [2]_| With BL2 [2]_ |
++============+=================+==============+==============+=================+
+| | XIP | XIP | XIP | Not XIP |
++------------+-----------------+--------------+--------------+-----------------+
+| | | Swap [3]_ | No-swap [4]_ | RAM loading [5]_|
++------------+-----------------+--------------+--------------+-----------------+
+| AN521 | Yes | Yes | Yes | No |
++------------+-----------------+--------------+--------------+-----------------+
+| AN519 | Yes | Yes | Yes | No |
++------------+-----------------+--------------+--------------+-----------------+
+| Musca-A1 | No | No | No | Yes |
++------------+-----------------+--------------+--------------+-----------------+
+| Musca-B1 | Yes | No | Yes | No |
++------------+-----------------+--------------+--------------+-----------------+
+
+.. [1] To disable BL2, please turn off the ``BL2`` compiler switch in the
+ top-level configuration files or in the command line
+
+.. [2] BL2 is enabled by default
+
+.. [3] The image executes in-place (XIP) and is in swapping mode for image
+ update by default
+
+.. [4] To enable XIP No-swap, set the configuration variable ``MCUBOOT_NO_SWAP``
+ to ``True`` in the top-level configuration files, or include the
+ ``MCUBOOT_NO_SWAP`` macro in the command line
+
+.. [5] To enable RAM loading, set the configuration variable
+ ``MCUBOOT_RAM_LOADING`` to ``True`` in the top-level configuration files, or
+ include the ``MCUBOOT_RAM_LOADING`` macro in the command line
+
+************************
+Build time configuration
+************************
+MCUBoot related compile time switches can be set in the high level build
+configuration files::
+
+ ConfigDefault.cmake
+ ConfigCoreTest.cmake
+ ConfigRegression.cmake
+
+Compile time switches:
+
+- BL2 (default: True):
+ - **True:** TF-M built together with bootloader. MCUBoot is executed after
+ reset and it authenticates TF-M and starts secure code.
+ - **False:** TF-M built without bootloader. Secure image linked to the
+ beginning of the device memory and executed after reset. If it is false
+ then using any of the further compile time switches are invalid.
+- MCUBOOT_NO_SWAP (default: False):
+ - **True:** Activate non-swapping firmware upgrade operation.
+ - **False:** Original firmware upgrade operation with image swapping.
+- MCUBOOT_RAM_LOADING (default: False):
+ - **True:** Activate RAM loading firmware upgrade operation, where latest
+ image is copied to RAM and runs from there instead of being executed
+ in-place.
+ - **False:** Original firmware upgrade operation with image swapping.
+
+Image versioning
+================
+An image version number is written to its header by one of the python scripts,
+and this number is used by the bootloader when the non-swapping mode is
+enabled.
+
+The version number of the image can manually be passed in through the command
+line in the cmake configuration step::
+
+ cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DIMAGE_VERSION=1.2.3+4 ../
+
+Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
+where the missing numbers are automatically set to zero. The image version
+number argument is optional, and if it is left out, then the version numbers of
+the image(s) being built in the same directory will automatically change. In
+this case, the last component (the build number) automatically increments from
+the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
+**until a number is explicitly provided**. If automatic versioning is in place
+and then an image version number is provided for the first time, the new number
+will take precedence and be used instead. All subsequent image versions are
+then set to the last number that has been specified, and the build number would
+stop incrementing. Any new version numbers that are provided will overwrite
+the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
+versioning, please start a clean build without specifying the image version
+number at all.
+
+************************
+Testing firmware upgrade
+************************
+As downloading the new firmware image is out of scope for MCUBoot, the update
+process is started from a state where the original and the new image are already
+programmed to the appropriate memory slots. To generate the original and a new
+firmware package, TF-M is built twice with different build configurations.
+
+Swapping firmware upgrade
+=========================
+Run TF-M build twice with two different build configuration: default and
+regression. Save the artefacts between builds, because second run can overwrite
+original binaries. Download default build to slot 0 and regression build to
+slot 1.
+
+Executing firmware upgrade on FVP_MPS2_AEMv8M
+---------------------------------------------
+.. code-block:: bash
+
+ <DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
+ --data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
+
+Executing firmware upgrade on SSE 200 FPGA on MPS2 board
+--------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M example application binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
+
+The following message will be shown in case of successful firmware upgrade,
+``Swap type: test`` indicates that images were swapped:
+
+::
+
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: slot 0
+ [INF] Swap type: test
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Execute test suites for the secure storage service
+--------------------------------------------------
+Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)....
+
+Non-swapping firmware upgrade
+=============================
+Follow the same instructions as in case of swapping build including these
+changes:
+
+- Set MCUBOOT_NO_SWAP compile time switch to true before build.
+- Increase the image version number between the two build run.
+
+Executing firmware upgrade on FVP_MPS2_AEMv8M
+---------------------------------------------
+
+.. code-block:: bash
+
+ <DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
+ --data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin@0x10080000 \
+ --data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin@0x10180000
+
+Executing firmware upgrade on SSE 200 FPGA on MPS2 board
+--------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sig0.bin ; TF-M example application binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
+
+Executing firmware upgrade on Musca-B1 board
+--------------------------------------------
+After two images have been built, they can be concatenated to create the
+combined image using ``srec_cat``:
+
+- Linux::
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel
+
+- Windows::
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel
+
+The following message will be shown in case of successful firmware upgrade,
+notice that image with higher version number (``version=1.2.3.5``) is executed:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: version=1.2.3.4, magic= good, image_ok=0xff
+ [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0xff
+ [INF] Booting image from slot 1
+ [INF] Bootloader chainload address offset: 0x180000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Execute test suites for the Secure area
+---------------------------------------
+Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+
+RAM loading firmware upgrade
+============================
+To enable RAM loading, please set ``MCUBOOT_RAM_LOADING`` to True (either in the
+configuration file or through the command line), and then specify a destination
+load address in RAM where the image can be copied to and executed from. The
+``IMAGE_LOAD_ADDRESS`` macro must be specified in the target dependent files,
+for example with Musca A1, its ``flash_layout.h`` file in the ``platform``
+folder should include ``#define IMAGE_LOAD_ADDRESS #0x10020000``
+
+Executing firmware upgrade on Musca-A1 board
+--------------------------------------------
+After two images have been built, they can be concatenated to create the
+combined image using ``srec_cat``:
+
+- Linux:
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset 0x320000 -o tfm.hex -Intel
+
+- Windows::
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset 0x320000 -o tfm.hex -Intel
+
+The following message will be shown in case of successful firmware upgrade when,
+RAM loading is enabled, notice that image with higher version number
+(``version=0.0.0.2``) is executed:
+
+::
+
+ [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0xff
+ [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0xff
+ [INF] Image has been copied from slot 1 in flash to SRAM address 0x10020000
+ [INF] Booting image from SRAM at address 0x10020000
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_sw_requirement.md b/docs/user_guides/tfm_sw_requirement.md
deleted file mode 100644
index d474770..0000000
--- a/docs/user_guides/tfm_sw_requirement.md
+++ /dev/null
@@ -1,302 +0,0 @@
-# TF-M Software requirements
-
-## Supported build environments
-TF-M officially supports a limited set of build environments and setups. In
-this context, official support means that the environments listed below
-are actively used by team members and active developers hence users should
-be able to recreate the same configurations by following the instructions
-described below. In case of problems, the TF-M team provides support only for
-these environments, but building in other environments can still be possible.
-
-The following environments are supported:
-- Windows 10 x64 + Cygwin x64 (example configuration is provided for this
- Windows setup only).
-- Windows 10 x64 + msys2 x64.
-- Windows 10 x65 + git-bash (MinGW) + gnumake from DS-5 or msys2.
-- Ubuntu 16.04 x64
-- Ubuntu 18.04 x64
-
-## Supported C compilers
-To compile TF-M code, at least one of the supported compiler toolchains have to
-be available in the build environment.
-The currently supported compiler versions are:
-- Arm Compiler v6.7.1
-- Arm Compiler v6.9
-- Arm Compiler v6.10
-- Arm Compiler v6.11
-- GNU Arm compiler v6.3.1
-- GNU Arm compiler v7.3
-
-**Notes:**
-
- - The Arm compilers above are provided via Keil uVision v5.24.1 or greater,
- DS-5 v5.27.1 or greater, and Development Studio 2018.0, or they can be
- downloaded as standalone packages from [here](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6).
-
- - Arm compiler specific environment variable may need updating based
- on specific products and licenses as explained in
- [product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
-
- - The GNU Arm compiler can be downloaded from [here](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads).
- On the page select *GNU Arm Embedded Toolchain: 6-2017-q1-update* or
- *GNU Arm Embedded Toolchain: 7-2018-q2-update*
-
-## Supported CMake versions
-The build-system is CMake based and supports the following versions:
-- 3.7
-- 3.10
-- 3.11
-- 3.12
-- 3.13
-- 3.14
-
-Please use the latest build version available (i.e. 3.7.2 instead of 3.7.0).
-While it is preferable to use the newest version this is not required and any
-version from the above list should work.
-
-Recent versions of CMake can be downloaded from https://cmake.org/download/, and
-older releases are available from https://cmake.org/files.
-
-## Supported GNU make versions
-The TF-M team builds using the "Unix Makefiles" generator of CMake and thus
-GNU make is needed for the build. On Linux please use the version
-available from the official repository of your distribution.
-
-On Windows the following binaries are supported:
-- GNU make v4.2.1 executable from Cygwin
-- GNU make v4.2.1 executable from msys2
-- GNU make v4.2 executable from DS5 v5.29.1 (see <DS-5_PATH>/bin)
-
-CMake is quiet tolerant to GNU make versions and basically any "reasonably
-recent" GNU make version shall work.
-
-CMake generators other than "Unix Makefiles" may work, but are not officially
-supported.
-
-## Example setups
-This section lists dependencies and some exact and tested steps to set-up a
-TF-M-m build environment under various OSes.
-
-### Ubuntu
-- DS-5 v5.27.1.
-- Git tools v2.10.0
-- CMake (see the "Supported CMake versions" chapter)
-- GNU Make (see the "Supported make versions" chapter)
-- Python3, with the following libraries:
- - pycrypto
- - pyasn1
- - yaml
- - jinja2 v2.10
- - sudo apt-get install python3-crypto python3-pyasn1 python3-yaml python3-jinja2
-- SRecord v1.58 (for Musca test chip boards)
-
-#### Setup a shell to enable compiler toolchain and CMake after installation.
-
-To import Arm Compiler v6.7.1 in your bash shell console:
-
-**Note:** Arm compiler specific environment variable may need updating based
-on specific products and licenses as explained in
-[product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
-
-~~~
-export PATH=<DS-5_PATH>/sw/ARMCompiler6.7.1/bin:$PATH
-export ARM_TOOL_VARIANT="ult"
-export ARM_PRODUCT_PATH="<DS-5_PATH>/sw/mappings"
-export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
-~~~
-To import CMake in your bash shell console:
-~~~
-export PATH=<CMAKE_PATH>/bin:$PATH
-~~~
-To import GNU Arm in your bash shell console:
-~~~
-export PATH=<GNU_ARM_PATH>/bin:$PATH
-~~~
-
-### Windows + Cygwin
-- uVision v5.24.1 or DS-5 v5.27.1 (DS-5 Ultimate Edition) which provides the
- Arm Compiler v6.7.1 compiler or GNU Arm compiler v6.3.1.
-- Git client latest version (https://git-scm.com/download/win)
-- CMake (see the "Supported CMake versions" chapter)
-- [Cygwin]( https://www.cygwin.com/ ). Tests done with version 2.877 (64 bits)
-- GNU make should be installed by selecting appropriate package during cygwin
- installation.
-- Python3 [(native Windows version)](https://www.python.org/downloads/), with the following libraries:
- - pycryptodome (pip3 install --user pycryptodome)
- - pyasn1 (pip3 install --user pyasn1)
- - pyyaml (pip3 install --user pyyaml)
- - jinja2 (pip3 install --user jinja2)
-- Python3 pip
-- [SRecord v1.63](https://sourceforge.net/projects/srecord/) (for Musca test chip boards)
-
-#### Setup Cygwin to enable a compiler toolchain and CMake after installation.
-
-If applicable, import Arm Compiler v6.7.1 in your shell console. To make this
-change permanent, add the command line into ~/.bashrc
-
-**DS-5**
-
-**Notes:**
-
- - Arm compiler specific environment variable may need updating based
- on specific products and licenses as explained in
- [product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
-
- - Arm licensing related environment variables must use Windows paths,
- and not the Cygwin specific one relative to */cygrive*.
-
-~~~
-export PATH="/cygdrive/c/<DS-5_PATH>/sw/ARMCompiler6.7.1/bin":$PATH
-export ARM_PRODUCT_PATH="C:/<DS-5_PATH>/sw/mappings"
-export ARM_TOOL_VARIANT="ult"
-export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
-~~~
-
-**Keil MDK Arm**
-
-**Notes:**
-- Arm compiler specific environment variable may need updating based
- on specific products and licenses as explained in
- [product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
-
-~~~
-export PATH="/cygdrive/c/<uVision path>/ARM/ARMCLANG/bin":$PATH
-~~~
-
-If applicable, import GNU Arm compiler v6.3.1 in your shell console. To make
-this change permanent, add the command line into ~/.bashrc
-
-**GNU Arm**
-~~~
-export PATH=<GNU_ARM_PATH>/bin:$PATH
-~~~
-
-To import CMake in your bash shell console:
-
-**CMake**
-
-~~~
-export PATH=/cygdrive/c/<CMAKE_PATH>/bin:$PATH
-~~~
-
-### Building documentation
-The build system is prepared to support generation of two documents. The
-Reference Manual which is Doxygen based, and the User Guide which is Sphinx
-based.
-Both document can be generated in HTML and PDF format.
-
-*Note* support for document generation in the build environment is not
-mandatory. Missing document generation tools will not block building the TF-M
-firmware.
-
-#### To compile the TF-M Reference Manual
-The following additional tools are needed:
-- Doxygen v1.8.0 or later
-- Graphviz dot v2.38.0 or later
-- PlantUML v1.2018.11 or later
-- Java runtime environment 1.8 or later (for running PlantUML)
-
-For PDF generation the following tools are needed in addition to the above list:
-- LaTeX
-- PdfLaTeX
-
-##### Set-up the needed tools
-
-###### Linux
-- sudo apt-get install -y doxygen graphviz default-jre
-- mkdir ~/plantuml; curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
-
-For PDF generation:
-- sudo apt-get install -y doxygen-latex
-
-###### Windows
-- [Doxygen 1.8.8](https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download)
-- [Graphviz 2.38](https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi)
-- The Java runtime is part of the DS5 installation or can be
- [downloaded from here](https://www.java.com/en/download/)
-- [PlantUML](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download)
-
-For PDF generation:
-- [MikTeX](https://miktex.org/download)
-
-*Note* When building the documentation the first time, MikTeX might prompt for
-installing missing LaTeX components. Please allow the MikTeX package manager to
-set-up these.
-
-###### Configure the shell
-
-####### Linux
-~~~
-export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
-~~~
-
-####### Windows + Cygwin
-Assumptions for the settings below:
-- plantuml.jar is available at c:\plantuml\plantuml.jar
-- doxygen, dot, and MikTeX binaries are available on the PATH.
-
-~~~
-export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
-export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
-~~~
-
-#### To compile the TF-M User Guide
-The following additional tools are needed:
-- Python3 and the following modules:
- - Sphinx v1.7.9
- - m2r v0.2.0
-- Graphviz dot v2.38.0 or later
-- PlantUML v1.2018.11 or later
-- Java runtime environment 1.8 or later (for running PlantUML)
-
-For PDF generation the following tools are needed in addition to the above list:
-- LaTeX
-- PdfLaTeX
-
-##### Set-up the needed tools
-
-###### Linux
-- sudo apt-get install -y python3 graphviz default-jre
-- pip --user install m2r Sphinx sphinx-rtd-theme
-- mkdir ~/plantuml; curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
-
-For PDF generation:
-- sudo apt-get install -y doxygen-latex
-
-###### Windows
-- Python3 [(native Windows version)](https://www.python.org/downloads/)
-- pip --user install m2r Sphinx sphinx-rtd-theme
-- [Graphviz 2.38](https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi)
-- The Java runtime is part of the DS5 installation or can be
- [downloaded from here](https://www.java.com/en/download/)
-- [PlantUML](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download)
-
-For PDF generation:
-- [MikTeX](https://miktex.org/download)
-
-*Note* When building the documentation the first time, MikTeX might prompt for
-installing missing LaTeX components. Please allow the MikTeX package manager to
-set-up these.
-
-##### Configure the shell
-
-###### Linux
-
-~~~
-export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
-~~~
-
-###### Windows + Cygwin
-
-Assumptions for the settings below:
-- plantuml.jar is available at c:\plantuml\plantuml.jar
-- doxygen, dot, and MikTeX binaries are available on the PATH.
-
-~~~
-export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
-export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
-~~~
-
---------------
-
-*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_sw_requirement.rst b/docs/user_guides/tfm_sw_requirement.rst
new file mode 100644
index 0000000..be5165f
--- /dev/null
+++ b/docs/user_guides/tfm_sw_requirement.rst
@@ -0,0 +1,501 @@
+##########################
+TF-M Software requirements
+##########################
+
+To build the TF-M firmware the following tools are needed:
+
+.. csv-table:: Tool dependencies
+ :header: "Name", "Version", "Component"
+
+ "C compiler",See `Supported C compilers`_,"Firmware"
+ "CMake",See `Supported CMake versions`_,
+ "GNU Make",See `Supported GNU make versions`_,
+ "Python",3.x,"Firmware, User Guide"
+ "yaml",,"Firmware"
+ "pyasn1",,"Firmware"
+ "jinja2",,"Firmware"
+ "pycrypto",,"Firmware"
+ "Doxygen",">1.8","Reference manual"
+ "Sphinx",">1.4","User Guide"
+ "sphinxcontrib-plantuml",,"User Guide"
+ "sphinx-trd-theme",,"User Guide"
+ "Git",,
+ "PlantUML",">v1.2018.11","Reference Manual, User Guide"
+ "Graphviz dot",">v2.38.0","Reference manual"
+ "Java runtime environment (JRE)",">1.8","Reference Manual, User Guide"
+ "LaTex",,"pdf version of Reference Manual and User Guide"
+ "PdfLaTex",,"pdf version of Reference Manual and User Guide"
+
+Dependency chain:
+
+.. uml::
+
+ @startuml
+ skinparam state {
+ BackgroundColor #92AEE0
+ FontColor black
+ FontSize 16
+ AttributeFontColor black
+ AttributeFontSize 16
+ BackgroundColor<<pdf>> #A293E2
+ BackgroundColor<<doc>> #90DED6
+ }
+ state fw as "Firmware" : TF-M binary
+ state c_comp as "C Compiler" : C99
+ state gmake as "GNU make"
+ state u_guide as "User Guide" <<doc>>
+ state refman as "Reference Manual" <<doc>>
+ state rtd_theme as "sphinx-rtd-theme" <<doc>>
+ state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
+ state JRE as "JRE" <<doc>> : Java Runtime Environment
+ state gwiz as "Graphwiz dot" <<doc>>
+ state Sphinx as "Sphinx" <<doc>>
+ state m2r as "m2r" <<doc>>
+ state PlantUML as "PlantUML" <<doc>>
+ state LaTex as "LaTex" <<pdf>>
+ state PdfLaTex as "PdfLaTex" <<<<pdf>>>>
+ state Doxygen as "Doxygen" <<doc>>
+
+ [*] --> fw
+ fw --> c_comp
+ fw --> CMake
+ CMake --> gmake
+ fw --> pycrypto
+ fw --> pyasn1
+ fw --> yaml
+ fw --> jinja2
+ pycrypto --> Python3
+ pyasn1 --> Python3
+ yaml --> Python3
+ jinja2 --> Python3
+
+ [*] --> u_guide
+ u_guide --> Sphinx
+ Sphinx --> m2r
+ Sphinx --> rtd_theme
+ Sphinx --> sphnix_puml
+ m2r --> Python3
+ rtd_theme --> Python3
+ sphnix_puml --> Python3
+ Sphinx --> PlantUML
+ PlantUML --> JRE
+ PlantUML --> gwiz
+ Sphinx --> LaTex
+ LaTex --> PdfLaTex
+
+ [*] --> refman
+ refman --> Doxygen
+ Doxygen --> PlantUML
+ Doxygen --> LaTex
+ state Legend {
+ state x as "For PDF generation only" <<pdf>>
+ state y as "For document generation only" <<doc>>
+ state z as "Mandatory"
+ }
+
+ @enduml
+
+****************************
+Supported build environments
+****************************
+
+TF-M officially supports a limited set of build environments and setups. In
+this context, official support means that the environments listed below
+are actively used by team members and active developers hence users should
+be able to recreate the same configurations by following the instructions
+described below. In case of problems, the TF-M team provides support
+only for these environments, but building in other environments can still be
+possible.
+
+The following environments are supported:
+
+ - Windows 10 x64 + Cygwin x64 (example configuration is provided for
+ this Windows setup only).
+ - Windows 10 x64 + msys2 x64.
+ - Windows 10 x65 + git-bash (MinGW) + gnumake from DS-5 or msys2.
+ - Ubuntu 16.04 x64
+ - Ubuntu 18.04 x64
+
+*********************
+Supported C compilers
+*********************
+
+To compile TF-M code, at least one of the supported compiler toolchains have to
+be available in the build environment. The currently supported compiler
+versions are:
+
+ - Arm Compiler v6.7.1
+ - Arm Compiler v6.9
+ - Arm Compiler v6.10
+ - Arm Compiler v6.11
+ - GNU Arm compiler v6.3.1
+ - GNU Arm compiler v7.3
+
+.. Note::
+ - The Arm compilers above are provided via Keil uVision v5.24.1 or
+ greater, DS-5 v5.27.1 or greater, and Development Studio 2018.0, or they can
+ be downloaded as standalone packages from
+ `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__.
+
+ - Arm compiler specific environment variable may need updating based
+ on specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+ - The GNU Arm compiler can be downloaded from
+ `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__.
+ On the page select *GNU Arm Embedded Toolchain: 6-2017-q1-update*
+ or *GNU Arm Embedded Toolchain: 7-2018-q2-update*
+
+************************
+Supported CMake versions
+************************
+
+The build-system is CMake based and supports the following versions:
+
+ - 3.7
+ - 3.10
+ - 3.11
+ - 3.12
+ - 3.13
+ - 3.14
+
+.. Note::
+ - Please use the latest build version available (i.e. 3.7.2 instead of
+ 3.7.0).
+ While it is preferable to use the newest version this is not required
+ and any version from the above list should work.
+ - Recent versions of CMake can be downloaded from
+ https://cmake.org/download/, and older releases are available from
+ https://cmake.org/files.
+
+***************************
+Supported GNU make versions
+***************************
+
+The TF-M team builds using the "Unix Makefiles" generator of CMake and
+thus GNU make is needed for the build. On Linux please use the version
+available from the official repository of your distribution.
+
+On Windows the following binaries are supported:
+
+ - GNU make v4.2.1 executable from Cygwin
+ - GNU make v4.2.1 executable from msys2
+ - GNU make v4.2 executable from DS5 v5.29.1 (see <DS5 install root>/bin)
+
+CMake is quiet tolerant to GNU make versions and basically any
+"reasonably recent" GNU make version shall work.
+
+CMake generators other than "Unix Makefiles" may work, but are not
+officially supported.
+
+**************
+Example setups
+**************
+
+This section lists dependencies and some exact and tested steps to set-up a
+TF-M-m build environment under various OSes.
+
+Ubuntu
+======
+
+- DS-5 v5.27.1.
+- Git tools v2.10.0
+- CMake (see the "Supported CMake versions" chapter)
+- GNU Make (see the "Supported make versions" chapter)
+- Python3, with the following libraries:
+- pycrypto
+- pyasn1
+- yaml
+- jinja2 v2.10
+- sudo apt-get install python3-crypto python3-pyasn1 python3-yaml
+ python3-jinja2
+- SRecord v1.58 (for Musca test chip boards)
+
+Setup a shell to enable compiler toolchain and CMake after installation.
+------------------------------------------------------------------------
+
+To import Arm Compiler v6.7.1 in your bash shell console:
+
+.. Warning::
+ Arm compiler specific environment variable may need updating based on
+ specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+.. code-block:: bash
+
+ export PATH=<DS-5_PATH>/sw/ARMCompiler6.7.1/bin:$PATH
+ export ARM_TOOL_VARIANT="ult"
+ export ARM_PRODUCT_PATH="<DS-5_PATH>/sw/mappings"
+ export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/bin:$PATH
+
+To import GNU Arm in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/bin:$PATH
+
+Windows + Cygwin
+================
+
+- uVision v5.24.1 or DS-5 v5.27.1 (DS-5 Ultimate Edition) which
+ provides the
+ Arm Compiler v6.7.1 compiler or GNU Arm compiler v6.3.1.
+- Git client latest version (https://git-scm.com/download/win)
+- CMake (see the "Supported CMake versions" chapter)
+- `Cygwin <https://www.cygwin.com/>`__. Tests done with version 2.877
+ (64 bits)
+- GNU make should be installed by selecting appropriate package during
+ cygwin
+ installation.
+- Python3 `(native Windows
+ version) <https://www.python.org/downloads/>`__, with the following
+ libraries:
+- pycryptodome (pip3 install --user pycryptodome)
+- pyasn1 (pip3 install --user pyasn1)
+- pyyaml (pip3 install --user pyyaml)
+- jinja2 (pip3 install --user jinja2)
+- Python3 pip
+- `SRecord v1.63 <https://sourceforge.net/projects/srecord/>`__ (for
+ Musca-A1 test chip board)
+
+Setup Cygwin to enable a compiler toolchain and CMake after installation.
+-------------------------------------------------------------------------
+
+If applicable, import Arm Compiler v6.7.1 in your shell console. To make this
+change permanent, add the command line into ~/.bashrc
+
+Armclang + DS-5
+^^^^^^^^^^^^^^^
+.. Note::
+
+ - Arm compiler specific environment variable may need updating based on
+ specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+ - Arm licensing related environment variables must use Windows paths, and not
+ the Cygwin specific one relative to */cygrive*.
+
+.. code-block:: bash
+
+ export PATH="/cygdrive/c/<DS-5_PATH>/sw/ARMCompiler6.7.1/bin":$PATH
+ export ARM_PRODUCT_PATH="C:/<DS-5_PATH>/sw/mappings"
+ export ARM_TOOL_VARIANT="ult"
+ export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
+
+Armclang + Keil MDK Arm
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. Note::
+
+ - Arm compiler specific environment variable may need updating based
+ on specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+.. code-block:: bash
+
+ export PATH="/cygdrive/c/<uVision path>/ARM/ARMCLANG/bin":$PATH
+
+GNU Arm
+^^^^^^^
+
+If applicable, import GNU Arm compiler v6.3.1 in your shell console. To make
+this change permanent, add the command line into ~/.bashrc
+
+.. code-block:: bash
+
+ export PATH=<GNU Arm path>/bin:$PATH
+
+CMake
+^^^^^
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/cygdrive/c/<CMake path>/bin:$PATH
+
+Building the documentation
+==========================
+
+The build system is prepared to support generation of two documents.
+The Reference Manual which is Doxygen based, and the User Guide which is
+Sphinx based. Both document can be generated in HTML and PDF format.
+
+.. Note::
+
+ Support for document generation in the build environment is not mandatory.
+ Missing document generation tools will not block building the TF-M
+ firmware.
+
+To compile the TF-M Reference Manual
+------------------------------------
+
+The following additional tools are needed:
+
+ - Doxygen v1.8.0 or later
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+
+For PDF generation the following tools are needed in addition to the
+above list:
+
+ - LaTeX
+ - PdfLaTeX
+
+Set-up the needed tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen graphviz default-jre
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+
+For PDF generation:
+
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen-latex
+
+Windows + Cygwin
+""""""""""""""""
+
+Download and install the following tools:
+ - `Doxygen
+ 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
+ - `Graphviz
+ 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the DS5 installation or can be
+ `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+For PDF generation:
+
+ - `MikTeX <https://miktex.org/download>`__
+
+ .. Note::
+ When building the documentation the first time, MikTeX might prompt for
+ installing missing LaTeX components. Please allow the MikTeX package
+ manager to set-up these.
+
+Configure the shell
+^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+
+::
+
+ export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
+
+Windows + Cygwin
+""""""""""""""""
+
+Assumptions for the settings below:
+
+ - plantuml.jar is available at c:\\plantuml\\plantuml.jar
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from DS5 installation.
+
+::
+
+ export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
+ export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
+
+To compile the TF-M User Guide
+------------------------------
+
+The following additional tools are needed:
+
+ - Python3 and the following modules:
+ - Sphinx v1.7.9
+ - m2r v0.2.0
+ - sphinxcontrib-plantuml
+ - sphinx-rtd-theme
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+
+For PDF generation the following tools are needed in addition to the
+above list:
+
+ - LaTeX
+ - PdfLaTeX
+
+Set-up the needed tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+
+.. code-block:: bash
+
+ sudo apt-get install -y python3 graphviz default-jre
+ pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+
+For PDF generation:
+
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen-latex
+
+Windows + Cygwin
+""""""""""""""""
+Download and install the following tools:
+ - Python3 `(native Windows version) <https://www.python.org/downloads/>`__
+ - Pip packages *m2r, Sphinx, sphinx-rtd-theme sphinxcontrib-plantuml*
+
+ .. code-block:: bash
+
+ pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
+
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the DS5 installation or can be
+ `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+For PDF generation:
+
+- `MikTeX <https://miktex.org/download>`__
+
+.. Note::
+ When building the documentation the first time, MikTeX might
+ prompt for installing missing LaTeX components. Please allow the MikTeX
+ package manager to set-up these.
+
+Configure the shell
+^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
+
+Windows + Cygwin
+""""""""""""""""
+
+Assumptions for the settings below:
+
+ - plantuml.jar is available at c:\\plantuml\\plantuml.jar
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from DS5 installation.
+
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
+ export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_user_guide.md b/docs/user_guides/tfm_user_guide.md
deleted file mode 100644
index ec4b408..0000000
--- a/docs/user_guides/tfm_user_guide.md
+++ /dev/null
@@ -1,289 +0,0 @@
-# Trusted Firmware M user guide
-How to compile and run TF-M and example test application for CoreLink SSE-200
-subsystem on the MPS2 board and on the Fast Model(FVP).
-
-Follow [build instruction](./tfm_build_instruction.md) to build the binaries.
-Follow [secure boot](./tfm_secure_boot.md) to build the binaries with or without
-BL2 bootloader.
-
-## Execute TF-M example and regression tests on MPS2 boards and FVP ##
-The BL2 bootloader and TF-M example application and tests run correctly on
-SMM-SSE-200 for MPS2 (AN521) and on the Fixed Virtual Platform model
-FVP_MPS2_AEMv8M version 11.2.23.
-
-### To run the example code on FVP_MPS2_AEMv8M
-Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1.
-
-*FVP reference guide can be found
-[here](https://developer.arm.com/docs/100966/latest)*
-
-#### Example application and regression tests without BL2 bootloader
-Add `tfm_s.axf` and `tfm_ns.axf` to symbol files in Debug Configuration menu.
-```
-<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
---parameter fvp_mps2.platform_type=2 \
---parameter cpu0.baseline=0 \
---parameter cpu0.INITVTOR_S=0x10000000 \
---parameter cpu0.semihosting-enable=0 \
---parameter fvp_mps2.DISABLE_GATING=0 \
---parameter fvp_mps2.telnetterminal0.start_telnet=1 \
---parameter fvp_mps2.telnetterminal1.start_telnet=0 \
---parameter fvp_mps2.telnetterminal2.start_telnet=0 \
---parameter fvp_mps2.telnetterminal0.quiet=0 \
---parameter fvp_mps2.telnetterminal1.quiet=1 \
---parameter fvp_mps2.telnetterminal2.quiet=1 \
---application cpu0=<build_dir>/install/outputs/fvp/tfm_s.axf \
---data cpu0=<build_dir>/install/outputs/fvp/tfm_ns.bin@0x00100000
-
-```
-
-#### Example application and regression tests with BL2 bootloader
-To test TF-M with bootloader, one must apply the following changes:
-
-* Add `mcuboot.axf` to symbol files in DS-5 in Debug Configuration menu.
-* Replace the last two lines of the previous command with this:
-```
---application cpu0=<build_dir>/install/outputs/fvp/mcuboot.axf \
---data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000
-```
-
-#### Test software upgrade with BL2 bootloader
-BL2 bootloader is mandatory to test software update. Furthermore two TF-M blob
-must be built. Outputs of example application and regression test can be used to
-test it. Load output of example application to slot 0 (0x10080000) and output of
-regression test to slot 1 (0x10180000). Add the following line to the
-end of the previous chapter:
-```
---data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
-```
-
-### To run the example code on SSE 200 FPGA on MPS2 board
-FPGA image is available to download [here](https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2)
-
-To run BL2 bootloader and TF-M example application and tests in the MPS2 board,
-it is required to have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board
-SD card. The image should be located in
-`<MPS2 device name>/MB/HBI0263<board revision letter>/AN521`
-
-The MPS2 board tested is HBI0263C referred also as MPS2+.
-
-`Note: If you change the exe names, MPS2 expects file names in 8.3 format.`
-
-#### Example application
-
-1. Copy `mcuboot.bin` and `tfm_sign.bin` files from
- `<build_dir>/install/outputs/AN521/` to `<MPS2 device name>/SOFTWARE/`
-2. Open `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
-3. Update the `AN521/images.txt` file as follows:
-```
-TITLE: Versatile Express Images Configuration File
-[IMAGES]
-TOTALIMAGES: 2 ;Number of Images (Max: 32)
-IMAGE0ADDRESS: 0x10000000
-IMAGE0FILE: \Software\mcuboot.bin ; BL2 bootloader
-IMAGE1ADDRESS: 0x10080000
-IMAGE1FILE: \Software\tfm_sign.bin ; TF-M example application binary blob
-```
-4. Close `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
-5. Unmount/eject the `<MPS2 device name>` unit
-6. Reset the board to execute the TF-M example application
-7. After completing the procedure you should be able to visualize on the serial
- port (baud 115200 8n1) the following messages:
-
-
-```
-[INF] Starting bootloader
-[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
-[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
-[INF] Boot source: slot 0
-[INF] Swap type: none
-[INF] Bootloader chainload address offset: 0x80000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-```
-
-#### Regression tests
-
-After completing the procedure you should be able to visualize on the serial
-port (baud 115200 8n1) the following messages:
-
-```
-[INF] Starting bootloader
-[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
-[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
-[INF] Boot source: slot 0
-[INF] Swap type: none
-[INF] Bootloader chainload address offset: 0x80000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-
-#### Execute test suites for the secure storage service ####
-Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
-
-> Executing 'TFM_SST_TEST_2001'
- Description: 'Create interface'
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2002'
- Description: 'Get handle interface (DEPRECATED)'
-This test is DEPRECATED and the test execution was SKIPPED
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2003'
- Description: 'Get handle with null handle pointer (DEPRECATED)'
-This test is DEPRECATED and the test execution was SKIPPED
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2004'
- Description: 'Write interface'
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2005'
- Description: 'Read interface'
-....
-
-```
-
-Note: SST reliability tests take a few minutes to run on the MPS2.
-
-#### Example application without BL2 bootloader
-1. Copy `tfm_s.bin` and `tfm_ns.bin` files from
- `<build_dir>/install/outputs/AN521/` to `<MPS2 device name>/SOFTWARE/`
-2. Open `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
-3. Update the `AN521/images.txt` file as follows:
-```
-TITLE: Versatile Express Images Configuration File
-[IMAGES]
-TOTALIMAGES: 2 ;Number of Images (Max: 32)
-IMAGE0ADDRESS: 0x10000000
-IMAGE0FILE: \Software\tfm_s.bin ; Secure code
-IMAGE1ADDRESS: 0x00100000
-IMAGE1FILE: \Software\tfm_ns.bin ; Non-secure code
-```
-4. Close `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
-5. Unmount/eject the `<MPS2 device name>` unit
-6. Reset the board to execute the TF-M example application
-7. After completing the procedure you should be able to visualize on the serial
- port (baud 115200 8n1) the following messages:
-
-```
-[Sec Thread] Secure image initializing!
-```
-
-#### Regression tests without BL2 bootloader
-After completing the procedure you should be able to visualize on the serial
-port (baud 115200 8n1) the following messages:
-
-```
-[Sec Thread] Secure image initializing!
-
-#### Execute test suites for the secure storage service ####
-Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
-
-> Executing 'TFM_SST_TEST_2001'
- Description: 'Create interface'
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2002'
- Description: 'Get handle interface (DEPRECATED)'
-This test is DEPRECATED and the test execution was SKIPPED
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2003'
- Description: 'Get handle with null handle pointer (DEPRECATED)'
-This test is DEPRECATED and the test execution was SKIPPED
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2004'
- Description: 'Write interface'
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2005'
- Description: 'Read interface'
-....
-
-```
-
-## Execute TF-M example and regression tests on Musca test chip boards ##
-
-Note: Before executing any images on Musca-B1 board, please check the readme
-under platform/ext/target/musca_b1 to have the correct setup.
-
-#### Example application with BL2 bootloader
-
-1. Create a unified hex file comprising of both `mcuboot.bin` and `tfm_sign.bin`
- * For Musca-A
- * Windows
- `srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel`
- * Linux
- `srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel`
- * For Musca-B1
- * Windows
- `srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel`
- * Linux
- `srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel`
-2. Power up the Musca board by connecting it to a computer with a USB lead.
- Press the `PBON` button if the green `ON` LED does not immediately come on.
- The board should appear as a USB drive.
-3. Copy `tfm.hex` to the USB drive. The orange `PWR` LED should start blinking.
-4. Once the `PWR` LED stops blinking, power cycle or reset the board to boot
- from the new image.
-5. After completing the procedure you should see the following messages on the
- DAPLink UART (baud 115200 8n1):
-
-```
-[INF] Starting bootloader
-[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
-[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xd9
-[INF] Boot source: slot 0
-[INF] Swap type: none
-[INF] Bootloader chainload address offset: 0x20000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-```
-
-#### Regression tests with BL2 bootloader
-
-After completing the procedure you should see the following messages on the
-DAPLink UART (baud 115200 8n1):
-
-```
-[INF] Starting bootloader
-[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
-[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
-[INF] Boot source: slot 0
-[INF] Swap type: none
-[INF] Bootloader chainload address offset: 0x20000
-[INF] Jumping to the first image slot
-[Sec Thread] Secure image initializing!
-
-#### Execute test suites for the secure storage service ####
-Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
-> Executing 'TFM_SST_TEST_2001'
- Description: 'Create interface'
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2002'
- Description: 'Get handle interface (DEPRECATED)'
-This test is DEPRECATED and the test execution was SKIPPED
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2003'
- Description: 'Get handle with null handle pointer (DEPRECATED)'
-This test is DEPRECATED and the test execution was SKIPPED
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2004'
- Description: 'Get attributes interface'
- TEST PASSED!
-> Executing 'TFM_SST_TEST_2005'
- Description: 'Get attributes with null attributes struct pointer'
-....
-
-```
-
-#### Example application or regression tests on Musca-B1 without BL2 bootloader
-Follow the above procedures, but create a unified hex file out of `tfm_s.bin`
-and `tfm_ns.bin`:
-
-* Windows
-`srec_cat.exe app\secure_fw\tfm_s.bin -Binary -offset 0xA000000 app\tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel`
-* Linux
-`srec_cat app/secure_fw/tfm_s.bin -Binary -offset 0xA000000 app/tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel`
-
-## Firmware upgrade and image validation with BL2 bootloader
-High level operation of BL2 bootloader and instructions for testing firmware
-upgrade is described in [secure boot](tfm_secure_boot.md) document.
-
---------------
-
-*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_user_guide.rst b/docs/user_guides/tfm_user_guide.rst
new file mode 100644
index 0000000..c7f9026
--- /dev/null
+++ b/docs/user_guides/tfm_user_guide.rst
@@ -0,0 +1,317 @@
+#############################
+Trusted Firmware M user guide
+#############################
+How to compile and run TF-M and example test application for CoreLink
+SSE-200 subsystem on the MPS2 board and on the Fast Model(FVP).
+
+Follow :doc:`build instruction <tfm_build_instruction>` to build the binaries.
+Follow :doc:`secure boot <tfm_secure_boot>` to build the binaries with or
+without BL2 bootloader.
+
+****************************************************************
+Execute TF-M example and regression tests on MPS2 boards and FVP
+****************************************************************
+The BL2 bootloader and TF-M example application and tests run correctly on
+SMM-SSE-200 for MPS2 (AN521) and on the Fixed Virtual Platform model
+FVP_MPS2_AEMv8M version 11.2.23.
+
+To run the example code on FVP_MPS2_AEMv8M
+==========================================
+Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1.
+
+.. Note::
+ FVP reference guide can be found
+ `here <https://developer.arm.com/docs/100966/latest>`__
+
+Example application and regression tests without BL2 bootloader
+---------------------------------------------------------------
+Add ``tfm_s.axf`` and ``tfm_ns.axf`` to symbol files in Debug Configuration
+menu.
+
+.. code-block:: bash
+
+ <DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=<build_dir>/install/outputs/fvp/tfm_s.axf \
+ --data cpu0=<build_dir>/install/outputs/fvp/tfm_ns.bin@0x00100000
+
+Example application and regression tests with BL2 bootloader
+------------------------------------------------------------
+To test TF-M with bootloader, one must apply the following changes:
+
+- Add ``mcuboot.axf`` to symbol files in DS-5 in Debug Configuration
+ menu.
+- Replace the last two lines of the previous command with this:
+
+.. code-block:: bash
+
+ --application cpu0=<build_dir>/install/outputs/fvp/mcuboot.axf \
+ --data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000
+
+Test software upgrade with BL2 bootloader
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+BL2 bootloader is mandatory to test software update. Furthermore two TF-M blob
+must be built. Outputs of example application and regression test can be used to
+test it. Load output of example application to slot 0 (0x10080000) and output of
+regression test to slot 1 (0x10180000). Add the following line to the end of
+the previous chapter:
+
+.. code-block:: bash
+
+ --data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
+
+To run the example code on SSE 200 FPGA on MPS2 board
+=====================================================
+FPGA image is available to download
+`here <https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
+
+To run BL2 bootloader and TF-M example application and tests in the MPS2 board,
+it is required to have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board SD
+card. The image should be located in
+``<MPS2 device name>/MB/HBI0263<board revision letter>/AN521``
+
+The MPS2 board tested is HBI0263C referred also as MPS2+.
+
+.. Warning::
+
+ If you change the exe names, MPS2 expects file names in 8.3 format.
+
+Example application
+-------------------
+#. Copy ``mcuboot.bin`` and ``tfm_sign.bin`` files from
+ ``<build_dir>/install/outputs/AN521/`` to
+ ``<MPS2 device name>/SOFTWARE/``
+#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Update the ``AN521/images.txt`` file as follows::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x10000000
+ IMAGE0FILE: \Software\mcuboot.bin ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sign.bin ; TF-M example application binary blob
+
+#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Unmount/eject the ``<MPS2 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests
+----------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the secure storage service ####
+ Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+
+ > Executing 'TFM_SST_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2004'
+ Description: 'Write interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2005'
+ Description: 'Read interface'
+ ....
+
+.. Note::
+
+ SST reliability tests take a few minutes to run on the MPS2.
+
+Example application without BL2 bootloader
+------------------------------------------
+#. Copy ``tfm_s.bin`` and ``tfm_ns.bin`` files from
+ ``<build_dir>/install/outputs/AN521/`` to
+ ``<MPS2 device name>/SOFTWARE/``
+#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Update the ``AN521/images.txt`` file as follows::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x10000000
+ IMAGE0FILE: \Software\tfm_s.bin ; Secure code
+ IMAGE1ADDRESS: 0x00100000
+ IMAGE1FILE: \Software\tfm_ns.bin ; Non-secure code
+
+#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Unmount/eject the ``<MPS2 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+Regression tests without BL2 bootloader
+---------------------------------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the secure storage service ####
+ Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+
+ > Executing 'TFM_SST_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2004'
+ Description: 'Write interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2005'
+ Description: 'Read interface'
+ ....
+
+*******************************************************************
+Execute TF-M example and regression tests on Musca test chip boards
+*******************************************************************
+.. Note::
+
+ Before executing any images on Musca-B1 board, please check the
+ :doc:`target platform readme </platform/ext/target/musca_b1/readme>`
+ to have the correct setup.
+
+Example application with BL2 bootloader
+=======================================
+
+#. Create a unified hex file comprising of both mcuboot and tfm_sign
+ binary
+
+- For Musca-A1
+
+ - Windows::
+
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+
+- For Musca-B1
+
+ - Windows::
+
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+#. Plug the Musca board into your computer. The board should appear as a USB
+ drive
+#. Copy ``tfm.hex`` to the USB drive
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to see on the UART0
+ (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xd9
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests with BL2 bootloader
+====================================
+After completing the procedure you should see the following messages on the
+UART0 (baud 115200 8n1)::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the secure storage service ####
+ Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+ > Executing 'TFM_SST_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2004'
+ Description: 'Get attributes interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2005'
+ Description: 'Get attributes with null attributes struct pointer'
+ ....
+
+Example application or regression tests on Musca-B1 without BL2 bootloader
+==========================================================================
+
+Follow the above procedures, but create a unified hex file out of ``tfm_s.bin``
+and ``tfm_ns.bin``:
+
+- Windows::
+
+ srec_cat.exe app\secure_fw\tfm_s.bin -Binary -offset 0xA000000 app\tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
+
+- Linux::
+
+ srec_cat app/secure_fw/tfm_s.bin -Binary -offset 0xA000000 app/tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
+
+Firmware upgrade and image validation with BL2 bootloader
+=========================================================
+High level operation of BL2 bootloader and instructions for testing firmware
+upgrade is described in :doc:`secure boot <tfm_secure_boot>`.
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*