Docs: Restructure the documents
Restructure the file category to let it more friendly to users.
Signed-off-by: Summer Qin <summer.qin@arm.com>
Change-Id: I7ced0e2d700ce03423e472e0098608f3445ba169
diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst
new file mode 100644
index 0000000..41bc4d2
--- /dev/null
+++ b/docs/integration_guide/index.rst
@@ -0,0 +1,12 @@
+Integration Guide
+=================
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ */index
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/os_migration_guide_armv8m.rst b/docs/integration_guide/os_migration_guide_armv8m.rst
new file mode 100644
index 0000000..1ca4e3d
--- /dev/null
+++ b/docs/integration_guide/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 </docs/technical_references/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-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/core_test_services_integration_guide.rst b/docs/integration_guide/services/core_test_services_integration_guide.rst
new file mode 100644
index 0000000..fb34795
--- /dev/null
+++ b/docs/integration_guide/services/core_test_services_integration_guide.rst
@@ -0,0 +1,114 @@
+###########################
+Core Test integration guide
+###########################
+
+************
+Introduction
+************
+
+The core test suites test some of the features of the TF-M core. There are
+multiple services that are used by the core test suites. The services are
+defined in the ``test/test_services`` folder.
+
+Currently there are two test suites, *interactive* and *positive*. The positive
+test suite can be run by building using non-secure regression tests using
+``-DTEST_NS``.
+
+The interactive test suite is only available by setting
+``-DTFM_INTERACTIVE_TEST=ON`` while the non-secure regression testsuite is
+enabled.
+
+In order to enable the IRQ test module of the postive testsuite, the non-secure
+regression testsuite must be enabled and ``-DTFM_IRQ_TEST=ON`` must be set.
+
+In order to enable the peripheral access test module of the positive testsuite,
+the non-secure regression testsuite must be enabled and
+``-DTFM_PERIPH_ACCESS_TEST=ON`` must be set.
+
+**************************
+Platform specific features
+**************************
+For certain test cases the core test services rely on platform functionality.
+The required features are:
+
+- Access to LEDs or registers that can be used as scratch registers for
+ read/write access tests
+- Get a button state that can be pressed by the user to simulate a secure
+ service with an arbitrarily long blocking execution.
+- Access to a timer that is able to interrupt the core running TF-M.
+
+The functionality that have to be implemented by the platform is described in
+``platform/include/tfm_plat_test.h``. For details see the documentation of the
+functions.
+
+It is the responsibility of the platform implementation to ensure that the
+resources needed for the core test services are properly linked to the service.
+This can be achieved by using the
+``TFM_LINK_SET_<memory_type>_IN_PARTITION_SECTION(...)`` macros in
+``platform/include/tfm_plat_defs.h``. More details regarding the usage of these
+macros are available in the header file.
+
+It is possible that a platform implementation mocks the implementation of some
+or all of the functions, by returning the values expected by the test cases,
+without actually executing the action expected by the test. A platform can also
+set the corresponding control flag to ``OFF`` to skip a test case. For example,
+A platform can skip peripheral access test case by setting
+``TFM_PERIPH_ACCESS_TEST`` to ``OFF`` in its cmake configuration file.
+
+******************
+IRQ handling tests
+******************
+
+The IRQ handling test currently tests the following scenarios:
+
+- NS code execution is interrupted by a secure IRQ (``IRQ_TEST_SCENARIO_1``)
+- S code execution is interrupted by a secure IRQ, The handler is not the
+ interrupted service (``IRQ_TEST_SCENARIO_2``)
+- S code execution is interrupted by a secure IRQ, The handler is the
+ interrupted service (``IRQ_TEST_SCENARIO_3``)
+- S code waits for an interrupt (calling ``psa_wait()``), the handler is in
+ the service that is waiting, ``psa_eoi()`` is called after ``psa_wait()``
+ returns (``IRQ_TEST_SCENARIO_4``)
+- S code waits for a non-secure interrupt to be triggered
+ (``IRQ_TEST_SCENARIO_5``)
+
+The following test services participate in the test execution:
+
+- ``TFM_IRQ_TEST_1`` has the role of the interrupted partition with the IRQ
+ handler
+- ``TFM_SP_CORE_TEST_2`` has the role of the interrupted partition without the
+ IRQ handler
+
+All the test executions are initiated from the NS positive test suite. For each
+scenario the non-secure testcase calls the following secure functions in order:
+
+#. prepare_test_scenario for ``TFM_IRQ_TEST_1``
+#. prepare_test_scenario for ``TFM_SP_CORE_TEST_2``
+#. prepare_test_scenario_ns
+#. execute_test_scenario for ``TFM_IRQ_TEST_1``
+#. execute_test_scenario for ``TFM_SP_CORE_TEST_2``
+#. execute_test_scenario_ns
+
+For scenarios 1-4 during the steps above the ``TFM_IRQ_TEST_1`` sets up a timer
+with a convenient init value, and depending on the scenario, one of the
+services, or the NS code enters a busy wait waiting for the timer interrupt to
+be raised. In case of ``IRQ_TEST_SCENARIO_3``, when ``PSA API`` is used, the
+execute_test_scenario request of the NS code is only replied when the IRQ is
+handled, so no explicit busy wait is required. In all the other cases, handling
+of the irq is signalled to the waiting party by setting a variable in a
+non-secure memory location.
+
+For scenario 5 a Non-secure timer is set up and ``TFM_SP_CORE_TEST_2`` waits for
+it to be triggered
+
+A platform can skip IRQ handling test by setting ``TFM_IRQ_TEST`` to
+``OFF`` in its cmake configuration file.
+
+The irq test services also demonstrate how to use the ``IRQ_TEST_TOOL_*``
+(``IRQ_TEST_TOOL_CODE_LOCATION``) macros. These macros should be defined to
+substitute empty string, and are used by the ``tools\generate_breakpoints.py``
+script in the `IRQ testing tool <https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/irq_test_tool>`_.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/index.rst b/docs/integration_guide/services/index.rst
new file mode 100644
index 0000000..30a2a8a
--- /dev/null
+++ b/docs/integration_guide/services/index.rst
@@ -0,0 +1,12 @@
+Services
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_attestation_integration_guide.rst b/docs/integration_guide/services/tfm_attestation_integration_guide.rst
new file mode 100644
index 0000000..2c43ea7
--- /dev/null
+++ b/docs/integration_guide/services/tfm_attestation_integration_guide.rst
@@ -0,0 +1,671 @@
+#############################################
+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.
+
+TF-M Initial Attestation Service by default enables asymmetric key algorithm
+based attestation (*asymmetric attestation* for short). Symmetric key algorithm
+based attestation (*symmetric attestation* for short) can be enabled instead by
+selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``.
+
+ - In asymmetric attestation, 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.
+ - In symmetric attestation, device should contain a symmetric attestation
+ key to generate the authentication tag of token content. The verification
+ entity uses the same symmetric key 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.
+
+***************************************
+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:
+
+ - **Auth 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 in asymmetric
+ attestation.
+ - hashes of the symmetric attestation key of the instance in symmetric
+ attestation.
+
+ 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**: Uniquely identifies the underlying immutable PSA
+ RoT. A verification service can use this claim to locate the details of
+ the verification process. Such details include the implementation's origin
+ and associated certification state. Custom claim with a value encoded as
+ byte string.
+
+ - **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.
+
+ - **Security lifecycle**: It represents the current lifecycle state of
+ the instance. Custom claim with a value encoded as an integer.
+
+ - **Hardware 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, but required in order to be compliant
+ with the PSA-SM. 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.
+
+ - **No software measurements**: Optional, but required if no software
+ component claims are made. In the event that the implementation does not
+ contain any software measurements then it is mandatory to include this
+ claim to indicate this is a deliberate state. Custom claim with a value
+ encoded as an unsigned integer set to 1.
+
+Each software component claim can include the following properties. Any property
+that is not optional must be included:
+
+ - **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.
+
+ - **Version**: Optional claim. It represents the issued software
+ version. Value is encoded as text string.
+
+ - **Signer ID**: Optional claim, but required in order to be compliant with
+ the PSA-SM. 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.
+
+*********************************************
+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/partitions/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/ext/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. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork)
+ signature schemas are supported.
+ - It is a fork of this external `t_cose library <https://github.com/laurencelundblade/t_cose>`__.
+ - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose``
+ library with available crypto library in the device.
+ - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the
+ exposed API and ports ``t_cose`` to the PSA Crypto API.
+- Initial Attestation Service:
+ - ``attest_core.c`` : Implements core functionalities such as implementation
+ of APIs, retrieval of claims and token creation.
+ - ``attest_token_encode.c``: Implements the token creation functions such as
+ start and finish token creation and adding claims to the token.
+ - ``attest_asymmetric_key.c``: Get the asymmetric attestation key from
+ platform layer and register it to the TF-M Crypto service for further
+ usage.
+ - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the
+ attestation service to the SPM implementation in TF-M project.
+ - ``tfm_attest_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.
+ - ``tfm_attest_req_mngr.c``: Includes the initialization entry of
+ attestation service and handles attestation service requests in IPC
+ model.
+ - ``attest_symmetric_key.c``: Get the symmetric initial attestation key
+ from platform layer and register it into TF-M Crypto service for further
+ usage. Also calculate the Instance ID value based on symmetric initial
+ attestation key.
+
+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.
+- **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
+
+ psa_status_t
+ psa_initial_attest_get_token(const uint8_t *auth_challenge,
+ size_t challenge_size,
+ uint8_t *token_buf,
+ size_t token_buf_size,
+ size_t *token_size);
+
+ psa_status_t
+ psa_initial_attest_get_token_size(size_t challenge_size,
+ size_t *token_size);
+
+ psa_status_t
+ tfm_initial_attest_get_public_key(uint8_t *public_key,
+ size_t public_key_buf_size,
+ size_t *public_key_len,
+ psa_ecc_family_t *elliptic_curve_type);
+
+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). Implementations in TF-M project can be
+found here:
+
+- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface
+ implementation for library model
+- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface
+ implementation for IPC model
+- ``secure_fw/partitions/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);
+
+- ``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.
+- ``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_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).
+If the used boot loader is not capable of sharing these information with the
+runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be
+set to OFF (see `Related compile time options`_).
+
+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.
+
+ .. Note::
+
+ There is a size field ``tlv_len`` which has different definitions in the
+ upstream MCUboot repository and in its TF-M forked version:
+
+ - Upstream MCUboot: Covers only the length of data but not the header
+ size.
+ - TF-M MCUboot: Covers the size of the entry header and the data
+ together.
+
+ This difference is handled by TF-M code based on which bootloader is used
+ along with TF-M runtime.
+
+ After the entry header 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
+================
+
+Asymmetric key algorithm based attestation
+------------------------------------------
+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.
+
+Symmetric key algorithm based attestation
+-----------------------------------------
+Device **must** contain a symmetric key to generate the authentication tag of
+the initial attestation token. A key identifier (kid) can be encoded in the
+unprotected part of the COSE header. It helps verification entity look up the
+symmetric key to verify the authentication tag in the token.
+
+The `t_cose` part of the initial attestation service implements the
+authentication tag generation. The authentication tag generation is done by the
+Crypto service. System integrators might need to re-implement the following
+functions if platforms provide a different cryptographic library than Crypto
+service:
+
+- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation
+ operation.
+- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC
+ operation.
+- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a
+ message.
+
+Interface needed by verification code:
+
+- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification
+ operation.
+- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of
+ a message.
+
+It also requires the same hash operations as listed in asymmetric key algorithm
+based initial attestation above, in attestation test cases.
+
+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 symmetric key
+during the manufacturing process. The following API is defined to retrieve the
+symmetric attestation key from platform layer. Software integrators **must**
+port this interface according to their SoC design and make sure that key is
+available by Crypto service:
+
+- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key
+ raw data.
+- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric
+ initial attestation key. The key identifier can be used as ``kid`` parameter
+ in COSE header. Optional.
+
+.. note:
+
+ Asymmetric initial attestation and symmetric initial attestation may share
+ the same HAL APIs in future development.
+
+Initial Attestation Service compile time options
+================================================
+There is a defined set of flags that can be used to compile in/out certain
+service features. The ``CommonConfig.cmake`` file sets the default values of
+those flags. The list of flags are:
+
+- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the
+ attestation token. Default value: ON.
+- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from
+ attestation test suite if it is OFF. Its default value depends on the build
+ type. It is ON if build type is ``Debug``, otherwise OFF (different kinds
+ of ``Release`` builds).
+- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE
+ unprotected header. Key-id is calculated and added to the COSE header based
+ on the value of this flag. Default value: OFF.
+- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded
+ values found in ``platform/ext/common/template/attest_hal.c``. Default value
+ is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet
+ properly ported to it.
+- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation.
+ Default value: OFF.
+
+Related compile time options
+----------------------------
+- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared
+ data area between the boot loader and the runtime firmware when it's ON.
+ Otherwise, when it's OFF does not check the content of the shared data area.
+ Also assume that the TLV header is present and valid (the magic number is
+ correct) and there are no other data entries. Its default value depends on
+ the BL2 flag.
+
+***************************************************************************
+Comparison of asymmetric and symmetric algorithm based token authentication
+***************************************************************************
+The symmetric key based authentication requires a more complex infrastructure
+for key management. Symmetric keys must be kept secret because they are
+sensitive asset, like the private key in case of asymmetric cryptographic
+algorithms. The main difference is that private keys are only stored on
+device, with proper hardware protection against external access, but symmetric
+keys must be known by both party (device and verifier), so they must also be
+stored in a central server of a relying party (who verifies the tokens).
+If keys are revealed then devices can be impersonated. If the database with
+the symmetric keys becomes compromised then all corresponding devices become
+untrusted. Since a centralised database of symmetric keys may need to be network
+connected, this can be considered to be a valuable target for attackers. The
+advantage of ECDSA based token authentication is that sensitive assets is only
+stored one place (in the device) and only one unique key per device. So if a
+device is compromised then only that single device become untrusted. In this
+case, the database of the relying party contains the corresponding public keys,
+which are not considered to be a confidential assets, so they can be shared with
+anybody. This shows the main advantage of asymmetric based authentication,
+because verification of attestation tokens can be done by a third party,
+such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM)
+does not need to operate such a service.
+
++-------------------------+-----------------------------------------+-----------------------------------------+
+| | Symmetric | Asymmetric |
++=========================+=========================================+=========================================+
+| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Supported APIs | - psa_initial_attest_get_token(..) | - psa_initial_attest_get_token(..) |
+| | - psa_initial_attest_get_token_size(..) | - psa_initial_attest_get_token_size(..) |
+| | | - tfm_initial_attest_get_public_key(..) |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Secrets are stored | Device and database | Device only |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Verification database | Same symmetric key | Public keys |
+| contains | | |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| COSE authentication tag | COSE_Mac0 | COSE_Sign1 |
+| in the token | | |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning|
+| | symmetric key | service, cloud service provider, CM, DM |
++-------------------------+-----------------------------------------+-----------------------------------------+
+
+************
+Verification
+************
+The initial attestation token is verified by the attestation test suite in
+``test/suites/attestation``. The test suite is responsible for verifying the
+token signature and parsing the token to verify its encoding and the presence of
+the mandatory claims. This test suite can be executed on the device. It is part
+of the regression test suite. When the user builds TF-M with any of the
+``ConfigRegression*.cmake`` configurations then this test is executed
+automatically. The test suite is configurable in the
+``test/suites/attestation/attest_token_test_values.h`` header file. In this file
+there are two attributes for each claim which are configurable (more details
+in the header file):
+
+ - Requirements of presence: optional or mandatory
+ - Expected value: Value check can be disabled or expected value can be provided
+ here.
+
+There is another possibility to verify the attestation token. This addresses
+the off-device testing when the token is already retrieved from the device and
+verification is done on the requester side. There is a Python script for this
+purpose in ``tools/iat-verifier``. It does the same checking as the
+attestation test suite. The following steps describe how to simulate an
+off-device token verification on a host computer. It is described how to
+retrieve an initial attestation token when TF-M code is executed on FVP
+and how to use the iat_verifier script to check the token. This example assumes
+that user has license for DS-5 and FVP models:
+
+ - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations
+ for MPS2 AN521 platform. More info in
+ :doc:`tfm_build_instruction </docs/getting_started/tfm_build_instruction>`.
+ - Lunch FVP model in DS-5. More info in
+ :doc:`tfm_user_guide </docs/getting_started/tfm_user_guide>`.
+ - Set a breakpoint in ``test/suites/attestation/attest_token_test.c``
+ in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned,
+ i.e. on line 859. Execute the code in the model until the breakpoint hits
+ second time. At this point the console prints the test case name:
+
+ - For asymmetric initial attestation, the console prints
+ ``ECDSA signature test of attest token``.
+ - For symmetric initial attestation, the console prints
+ ``Symmetric key algorithm based Initial Attestation test``.
+
+ - At this point the token resides in the model memory and can be dumped to host
+ computer.
+ - The ADDRESS and SIZE attributes of the initial attestation token is stored in
+ the ``completed_token`` local variable. Their value can be extracted in the
+ ``(x)=Variables`` debug window.
+ - Apply commands below in the ``Commands`` debug window to dump the token in
+ binary format to the host computer:
+
+ - For asymmetric initial attestation
+ ``dump memory <PATH>/iat_01.cbor <ADDRESS> +<SIZE>``
+ - For symmetric initial attestation
+ ``dump memory <PATH>/iat_hmac_02.cbor <ADDRESS> +<SIZE>``
+
+ - Execute commands below on the host computer to verify the token:
+
+ - For asymmetric initial attestation
+ ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem <PATH>/iat_01.cbor``
+ - For symmetric initial attestation
+ ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key <PATH>/iat_hmac_02.cbor``
+
+ - Documentation of the iat-verifier can be found
+ :doc:`here </tools/iat-verifier/README>`.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_audit_integration_guide.rst b/docs/integration_guide/services/tfm_audit_integration_guide.rst
new file mode 100644
index 0000000..248f0f9
--- /dev/null
+++ b/docs/integration_guide/services/tfm_audit_integration_guide.rst
@@ -0,0 +1,134 @@
+#######################################
+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/partitions/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
+*********************************
+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/integration_guide/services/tfm_crypto_integration_guide.rst b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
new file mode 100644
index 0000000..a124bdf
--- /dev/null
+++ b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
@@ -0,0 +1,118 @@
+################################
+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/partitions/crypto``.
+
+PSA interfaces
+==============
+The TF-M Crypto service exposes the PSA interfaces detailed in the header
+``psa/crypto.h``. This header, in turn, includes several other headers which
+are not meant to be included directly by user applications. 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 module handles requests for symmetric cipher
+ operations
+- ``crypto_hash.c`` : This module handles requests for hashing operations
+- ``crypto_mac.c`` : This module handles requests for MAC operations
+- ``crypto_aead.c`` : This module handles requests for AEAD operations
+- ``crypto_key_derivation.c`` : This module handles requests for key derivation
+ related operations
+- ``crypto_key.c`` : This module handles requests for key related operations
+- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
+ cryptographic operations
+- ``crypto_init.c`` : This module provides basic functions to initialise the
+ secure service during TF-M boot. When the service is built for IPC mode
+ compatibility, this layer handles as well the connection requests and the
+ proper dispatching of requests to the corresponding functions, and it holds
+ the internal buffer used to allocate temporarily the IOVECs needed. The size
+ of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define.
+ This module also provides a static buffer which is used by the Mbed Crypto
+ library for its own allocations. The size of this buffer is controlled by
+ the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define
+- ``crypto_alloc.c`` : This module is required for the allocation and release of
+ crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``,
+ defined in this file, determines how many concurrent contexts are supported
+ for multipart operations (8 for the current implementation). For multipart
+ cipher/hash/MAC/generator operations, a context is associated to the handle
+ provided during the setup phase, and is explicitly cleared only following a
+ termination or an abort
+- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API
+ client interface exposed to the Secure Processing Environment
+- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
+ implements the PSA Crypto API client interface exposed to the Non-Secure
+ Processing Environment.
+- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
+ Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
+ Small by default.
+
+****************************
+Crypto Backend configuration
+****************************
+
+The Crypto service can use either a hardware crypto accelerator backend like
+CC-312 or a software crypto library which by default is MbedTLS.
+
+If using MbedTLS as backend, then the library configuration is supplied using
+the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option.
+
+Platforms can specify an extra config file by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
+around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform
+configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with
+config changes due to TFM Profile.
+
+.. Note::
+
+ The default entropy source configured for MbedTLS is
+ MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness
+ for production devices. It is required for production devices to select
+ either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or
+ provision a unique seed for the device during production and use the
+ MBEDTLS_ENTROPY_NV_SEED option.
+
+**************************
+Crypto service integration
+**************************
+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 multipart 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 described
+below:
+
+- ``psa_key_derivation_operation_t`` - Operation context for key derivation
+- ``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-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_its_integration_guide.rst b/docs/integration_guide/services/tfm_its_integration_guide.rst
new file mode 100644
index 0000000..6082e73
--- /dev/null
+++ b/docs/integration_guide/services/tfm_its_integration_guide.rst
@@ -0,0 +1,318 @@
+#######################################################
+TF-M Internal Trusted Storage Service Integration Guide
+#######################################################
+
+************
+Introduction
+************
+TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted
+Storage APIs.
+
+The service is backed by hardware isolation of the flash access domain and
+relies on hardware to isolate the flash area from access by the Non-secure
+Processing Environment, as well as the Application Root of Trust at higher
+levels of isolation.
+
+The current ITS service design relies on hardware abstraction provided by TF-M.
+The ITS service provides a non-hierarchical storage model, as a filesystem,
+where all the assets are managed by a linearly indexed list of metadata.
+
+The design addresses the following high level requirements as well:
+
+- **Confidentiality** - Resistance to unauthorised accesses through
+ hardware/software attacks. Assumed to be provided by the internal flash
+ device, backed by hardware isolation.
+
+- **Access Authentication** - Mechanism to establish requester's identity (a
+ non-secure entity, secure entity, or a remote server).
+
+- **Integrity** - Resistance to tampering by attackers with physical access is
+ assumed to be provided by the internal flash device itself, while resistance
+ to tampering by Non-secure or App RoT attackers also requires hardware
+ isolation.
+
+- **Reliability** - Resistance to power failure scenarios and incomplete write
+ cycles.
+
+- **Configurability** - High level of configurability to scale up/down memory
+ footprint to cater for a variety of devices with varying requirements.
+
+- **Performance** - Optimized to be used for resource constrained devices with
+ very small silicon footprint, the PPA (power, performance, area) should be
+ optimal.
+
+*******************************
+Current ITS 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. 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.
+
+- **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.
+
+- **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.
+
+- **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
+**************
+TF-M Internal Trusted Storage service code is located in
+``secure_fw/partitions/internal_trusted_storage/`` and is divided as follows:
+
+ - Core files
+ - Flash filesystem interfaces
+ - Flash interfaces
+
+The PSA ITS interfaces for the TF-M ITS service are located in
+``interface/include/psa``.
+
+PSA Internal Trusted Storage Interfaces
+=======================================
+
+The TF-M ITS service exposes the following mandatory PSA ITS interfaces
+version 1.0:
+
+.. code-block:: c
+
+ psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
+ psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
+ psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
+ psa_status_t psa_its_remove(psa_storage_uid_t uid);
+
+These PSA ITS interfaces and TF-M ITS types are defined and documented in
+``interface/include/psa/storage_common.h``,
+``interface/include/psa/internal_trusted_storage.h``, and
+``interface/include/tfm_its_defs.h``
+
+Core Files
+==========
+- ``tfm_its_req_mngr.c`` - Contains the ITS 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 internal trusted
+ storage layer with the provided parameters.
+
+- ``tfm_internal_trusted_storage.c`` - Contains the TF-M internal trusted
+ storage API implementations which are the entry points to the ITS service.
+ Constructs a filesystem configuration using information from the ITS HAL,
+ allocates a filesystem context for ITS and makes appropriate FS calls. Also
+ handles requests from the PS partition with a separate FS config and context.
+
+- ``its_utils.c`` - Contains common and basic functionalities used across the
+ ITS service code.
+
+Flash Filesystem Interface
+==========================
+- ``flash_fs/its_flash_fs.h`` - Abstracts the flash filesystem operations used
+ by the internal trusted storage service. The purpose of this abstraction is to
+ have the ability to plug-in other filesystems or filesystem proxies
+ (supplicant).
+
+- ``flash_fs/its_flash_fs.c`` - Contains the ``its_flash_fs`` implementation for
+ the required interfaces.
+
+- ``flash_fs/its_flash_fs_mblock.c`` - Contains the metadata block manipulation
+ functions required to implement the ``its_flash_fs`` interfaces in
+ ``flash_fs/its_flash_fs.c``.
+
+- ``flash_fs/its_flash_fs_dblock.c`` - Contains the data block manipulation
+ functions required to implement the ``its_flash_fs`` interfaces in
+ ``flash_fs/its_flash_fs.c``.
+
+The system integrator **may** replace this implementation with its own
+flash filesystem implementation or filesystem proxy (supplicant).
+
+Flash Interface
+===============
+The ITS filesystem flash interface is defined by ``struct its_flash_fs_ops_t``
+in ``flash_fs/its_flash_fs.h``.
+
+Implementations of the ITS filesystem flash interface for different types of
+storage can be found in the ```internal_trusted_storage/flash`` directory.
+
+- ``flash/its_flash.h`` - Helper header that includes the correct ITS flash
+ interface implementation for the target, and abstracts the allocation of
+ different flash device types.
+
+- ``flash/its_flash_nand.c`` - Implements the ITS flash interface for a NAND
+ flash device, on top of the CMSIS flash interface implemented by the target.
+ This implementation writes entire block updates in one-shot, so the CMSIS
+ flash implementation **must** be able to detect incomplete writes and return
+ an error the next time the block is read.
+
+- ``flash/its_flash_nor.c`` - Implements the ITS flash interface for a NOR flash
+ device, on top of the CMSIS flash interface implemented by the target.
+
+- ``flash/its_flash_ram.c`` - Implements the ITS flash interface for an emulated
+ flash device using RAM, on top of the CMSIS flash interface implemented by the
+ target.
+
+The CMSIS flash interface **must** be implemented for each target based on its
+flash controller.
+
+The ITS flash interface depends on target-specific definitions from
+``platform/ext/target/<TARGET_NAME>/partition/flash_layout.h``.
+Please see the `Internal Trusted Storage Service HAL` section for details.
+
+*****************************
+ITS Service Integration Guide
+*****************************
+This section describes mandatory (i.e. **must** implement) or optional
+(i.e. **may** implement) interfaces which the system integrator has to take in
+to account in order to integrate the internal trusted storage service in a new
+platform.
+
+Flash Interface
+===============
+For ITS service operations, a contiguous set of blocks must be earmarked for
+the internal trusted 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.
+
+Maximum Asset Size
+==================
+An asset is stored in a contiguous space in a logical filesystem block. The
+maximum size of an asset can be up-to the size of the data block. Typically,
+each logical block corresponds to one physical flash erase sector (the smallest
+unit that can erased), but the ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` configuration
+below allows a number of contiguous erase sectors to form one logical block.
+
+Internal Trusted Storage Service HAL
+====================================
+The ITS service requires the platform to implement the ITS HAL, defined in
+``platform/include/tfm_hal_its.h``.
+
+The following C definitions in the HAL are mandatory, and must be defined by the
+platform in a header named ``flash_layout.h``:
+
+- ``TFM_HAL_ITS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash
+ ARM_DRIVER_FLASH object to use for ITS. It must have been allocated by the
+ platform and will be declared extern in the HAL header.
+
+- ``TFM_HAL_ITS_PROGRAM_UNIT`` - Defines the size of the ITS flash device's
+ physical program unit (the smallest unit of data that can be individually
+ programmed to flash). It must be equal to
+ ``TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at
+ compile time so that filesystem structures can be statically sized. Valid
+ values are powers of two between 1 and the flash sector size, inclusive.
+
+The following C definitions in the HAL may optionally be defined by the platform
+in the ``flash_layout.h`` header:
+
+- ``TFM_HAL_ITS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated
+ flash area for ITS.
+
+- ``TFM_HAL_ITS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
+ for ITS in bytes.
+
+- ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical
+ flash erase sectors that form a logical erase block in the filesystem. The
+ typical value is ``1``, but it may be increased so that the maximum required
+ asset size will fit in one logical block.
+
+If any of the above definitions are not provided by the platform, then the
+``tfm_hal_its_fs_info()`` HAL API must be implemented instead. This function is
+documented in ``tfm_hal_its.h``.
+
+The sectors reserved to be used for Internal Trusted Storage **must** be
+contiguous.
+
+Internal Trusted Storage Service Optional Platform Definitions
+==============================================================
+The following optional platform definitions may be defined in
+``flash_layout.h``:
+
+- ``ITS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the
+ RAM FS emulated flash implementation. The buffer must be at least as large as
+ the area earmarked for the filesystem by the HAL.
+- ``ITS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using
+ the NAND flash implementation. The buffer must be at least as large as a
+ logical filesystem block.
+- ``ITS_MAX_BLOCK_DATA_COPY`` - Defines the buffer size used when copying data
+ between blocks, in bytes. If not provided, defaults to 256. Increasing this
+ value will increase the memory footprint of the service.
+
+More information about the ``flash_layout.h`` content, not ITS related, is
+available in :doc:`platform readme </platform/ext/readme>` along with other
+platform information.
+
+ITS Service Build Definitions
+=============================
+The ITS service uses a set of C definitions to compile in/out certain features,
+as well as to configure certain service parameters. When using the TF-M build
+system, these definitions are controlled by build flags of the same name. The
+``config/config_default.cmake`` file sets the default values of those flags, but
+they can be overwritten based on platform capabilities by setting them in
+``platform/ext/target/<TARGET_NAME>/config.cmake``. The list of ITS service
+build definitions is:
+
+- ``ITS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create an ITS flash layout. If this flag is set, ITS service will
+ generate an empty and valid ITS flash layout to store assets. It will
+ erase all data located in the assigned ITS memory area before generating
+ the ITS layout. This flag is required to be set if the ITS memory area
+ is located in a non-persistent memory. This flag can be set if the ITS
+ memory area is located in a persistent memory without a valid ITS flash
+ layout in it. That is the case when it is the first time in the device
+ life that the ITS service is executed.
+- ``ITS_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 data corruption.
+- ``ITS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of
+ the persistent storage device to store the FS in the Internal Trusted Storage
+ service. This flag is ``OFF`` by default. The ITS regression tests write/erase
+ storage multiple time, so enabling this flag can increase the life of flash
+ memory when testing.
+ If this flag is set to ``ON``, ITS_RAM_FS_SIZE must also be provided. This
+ specifies the size of the block of RAM to be used to simulate the flash.
+
+ .. Note::
+ If this flag is disabled when running the regression tests, then it is
+ recommended that the persistent storage area is erased before running the
+ tests to ensure that all tests can run to completion. The type of persistent
+ storage area is platform specific (eFlash, MRAM, etc.) and it is described
+ in corresponding flash_layout.h
+
+- ``ITS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ ITS area. This size is used to define the temporary buffers used by ITS to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as ITS does not use dynamic memory allocation.
+- ``ITS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ ITS area. This number is used to dimension statically the filesystem metadata
+ tables in RAM (fast access) and flash (persistent storage). The memory used by
+ the filesystem metadata tables is allocated statically as ITS does not use
+ dynamic memory allocation.
+- ``ITS_BUF_SIZE``- Defines the size of the partition's internal data transfer
+ buffer. If not provided, then ``ITS_MAX_ASSET_SIZE`` is used to allow asset
+ data to be copied between the client and the filesystem in one iteration.
+ Reducing the buffer size will decrease the RAM usage of the partition at the
+ expense of latency, as data will be copied in multiple iterations. *Note:*
+ when data is copied in multiple iterations, the atomicity property of the
+ filesystem is lost in the case of an asynchronous power failure.
+
+--------------
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_platform_integration_guide.rst b/docs/integration_guide/services/tfm_platform_integration_guide.rst
new file mode 100644
index 0000000..7858435
--- /dev/null
+++ b/docs/integration_guide/services/tfm_platform_integration_guide.rst
@@ -0,0 +1,113 @@
+##################################
+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/partitions/platform``.
+
+*********************
+TF-M Platform service
+*********************
+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
+************
+
+The Platform Service relies on a platform-specific implementation to
+perform some functionalities. Mandatory functionality (e.g. system reset)
+that are required to be implemented for a platform to be supported by TF-M have
+their dedicated HAL API functions. Additional platform-specific services can be
+provided using the IOCTL function call.
+
+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>/services/src/tfm_platform_system.c``
+for examples.
+
+The API **must** be implemented by the system integrators for their targets.
+
+IOCTL
+=====
+
+A single entry point to platform-specific code across the HAL is provided by the
+IOCTL service and HAL function:
+
+.. code-block:: c
+
+ enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request,
+ psa_invec *in_vec,
+ psa_outvec *out_vec);
+
+A request type is provided by the client, with additional parameters contained
+in the optional ``in_vec`` parameter. An optional output buffer can be passed to
+the service in ``out_vec``.
+An IOCTL request type not supported on a particular platform should return
+``TFM_PLATFORM_ERR_NOT_SUPPORTED``
+
+Non-Volatile counters
+=====================
+
+The Platform Service provides an abstracted service for exposing the NV counters
+to the secure world. The following operations are supported:
+
+- Increment a counter.
+- Read a counter value to a preallocated buffer.
+
+.. code-block:: c
+
+ enum tfm_platform_err_t
+ tfm_platform_nv_counter_increment(uint32_t counter_id);
+
+ enum tfm_platform_err_t
+ tfm_platform_nv_counter_read(uint32_t counter_id,
+ uint32_t size, uint8_t *val);
+
+The range of counters id is defined in :
+``platform/include/tfm_plat_nv_counters.h``
+
+For Level 2,3 isolation implementations, secure partitions in the
+Application Root of Trust, should have ``TFM_SP_PLATFORM_NV_COUNTER`` set as a
+dependency for access to the NV counter API.
+
+***************************
+Current Service Limitations
+***************************
+- **system reset** - The system reset functionality is only supported in
+ isolation level 1. Currently the mechanism by which PSA-RoT services should
+ run in privileged mode in level 3 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.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_ps_integration_guide.rst b/docs/integration_guide/services/tfm_ps_integration_guide.rst
new file mode 100644
index 0000000..2c6da7b
--- /dev/null
+++ b/docs/integration_guide/services/tfm_ps_integration_guide.rst
@@ -0,0 +1,392 @@
+###########################################
+Protected Storage Service Integration Guide
+###########################################
+
+************
+Introduction
+************
+TF-M Protected Storage (PS) 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 PS service implements an AES-GCM based AEAD encryption policy, as a
+reference, to protect data integrity and authenticity.
+
+PS reuses the non-hierarchical filesystem provided by the TF-M Internal Trusted
+Storage service to store encrypted, authenticated objects on the external flash
+device.
+
+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
+ protected 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 PS 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.
+
+- **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
+**************
+Protected storage service code is located in
+``secure_fw/partitions/protected_storage/`` and is divided as follows:
+
+ - Core files
+ - Cryptographic interfaces
+ - Non-volatile (NV) counters interfaces
+
+The PSA PS interfaces for PS service are located in ``interface/include/psa``
+
+PSA Protected Storage Interfaces
+================================
+
+The PS service exposes the following mandatory PSA PS interfaces, version 1.0:
+
+.. code-block:: c
+
+ psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
+ psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
+ psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
+ psa_status_t psa_ps_remove(psa_storage_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 PS TF-M types are defined and documented in
+``interface/include/psa/protected_storage.h``,
+``interface/include/psa/storage_common.h`` and
+``interface/include/tfm_ps_defs.h``
+
+Core Files
+==========
+- ``tfm_ps_req_mngr.c`` - Contains the PS 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 PS service.
+
+- ``ps_object_system.c`` - Contains the object system implementation to manage
+ all objects in PS area.
+
+- ``ps_object_table.c`` - Contains the object system table implementation which
+ complements the object system to manage all object in the PS area.
+ The object table has an entry for each object stored in the object system
+ and keeps track of its version and owner.
+
+- ``ps_encrypted_object.c`` - Contains an implementation to manipulate
+ encrypted objects in the PS object system.
+
+- ``ps_utils.c`` - Contains common and basic functionalities used across the
+ PS service code.
+
+Flash Filesystem and Flash Interfaces
+=====================================
+The PS service reuses the non-hierarchical filesystem and flash interfaces
+provided by the TF-M Internal Trusted Storage service. It stores encrypted,
+authenticated objects on the external flash device by making service calls to
+the ITS service. When the ITS service receives requests from the PS partition,
+it handles the request by using a separate filesystem context initialised to use
+the external flash device.
+
+The ITS filesystem and flash interfaces and their implementation can be found in
+``secure_fw/partitions/internal_trusted_storage/flash_fs`` and
+``secure_fw/partitions/internal_trusted_storage/flash`` respectively. More
+information about the filesystem and flash interfaces can be found in the
+:doc:`ITS integration guide
+</docs/integration_guide/services/tfm_its_integration_guide>`.
+
+The ITS service implementation in
+``secure_fw/partitions/internal_trusted_storage/tfm_internal_trusted_storage.c``,
+constructs a filesystem configuration for Protected Storage based on
+target-specific definitions from the Protected Storage HAL. Please see the
+`Protected Storage Service HAL` section for details of these.
+
+Cryptographic Interface
+=======================
+- ``crypto/ps_crypto_interface.h`` - Abstracts the cryptographic operations for
+ the protected storage service.
+
+- ``crypto/ps_crypto_interface.c`` - Implements the PS service cryptographic
+ operations with calls to the TF-M Crypto service.
+
+Non-volatile (NV) Counters Interface
+====================================
+The current PS service provides rollback protection based on NV
+counters.
+PS defines and implements the following NV counters functionalities:
+
+- ``nv_counters/ps_nv_counters.h`` - Abstracts PS 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 PS test suite
+ **may** provide its own custom implementation to be able to test different PS
+ service use cases.
+
+- ``nv_counters/ps_nv_counters.c`` - Implements the PS NV counters interfaces
+ based on TF-M NV counters implementation provided by the platform.
+
+****************************
+PS 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 protected 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 (``PS_OBJECT_HEADER_SIZE``) which is defined in
+``ps_object_defs.h``. The ``PS_OBJECT_HEADER_SIZE`` changes based on the
+``PS_ENCRYPTION`` flag status.
+
+Protected Storage Service HAL
+=============================
+The PS service requires the platform to implement the PS HAL, defined in
+``platform/include/tfm_hal_ps.h``.
+
+The following C definitions in the HAL are mandatory, and must be defined by the
+platform in a header named ``flash_layout.h``:
+
+- ``TFM_HAL_PS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash
+ ARM_DRIVER_FLASH object to use for PS. It must have been allocated by the
+ platform and will be declared extern in the HAL header.
+
+- ``TFM_HAL_PS_PROGRAM_UNIT`` - Defines the size of the PS flash device's
+ physical program unit (the smallest unit of data that can be individually
+ programmed to flash). It must be equal to
+ ``TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at
+ compile time so that filesystem structures can be statically sized. Valid
+ values are powers of two between 1 and the flash sector size, inclusive.
+
+The following C definitions in the HAL may optionally be defined by the platform
+in the ``flash_layout.h`` header:
+
+- ``TFM_HAL_PS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated
+ flash area for PS.
+
+- ``TFM_HAL_PS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
+ for PS in bytes.
+
+- ``TFM_HAL_PS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical
+ flash erase sectors that form a logical erase block in the filesystem. The
+ typical value is ``1``, but it may be increased so that the maximum required
+ asset size will fit in one logical block.
+
+If any of the above definitions are not provided by the platform, then the
+``tfm_hal_ps_fs_info()`` HAL API must be implemented instead. This function is
+documented in ``tfm_hal_ps.h``.
+
+The sectors reserved to be used for Protected Storage **must** be contiguous
+sectors starting at ``TFM_HAL_PS_FLASH_AREA_ADDR``.
+
+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.
+
+Protected Storage Service Optional Platform Definitions
+=======================================================
+The following optional platform definitions may be defined in
+``flash_layout.h``:
+
+- ``PS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the
+ RAM FS emulated flash implementation. The buffer must be at least as large as
+ the area earmarked for the filesystem by the HAL.
+- ``PS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using
+ the NAND flash implementation. The buffer must be at least as large as a
+ logical filesystem block.
+
+More information about the ``flash_layout.h`` content, not PS 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 ``PS_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/common/template/crypto_keys.c``
+
+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/technical_references/tfm_ns_client_identification>`
+provides further details on how client identification works.
+
+PS 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/integration_guide/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 PS service abstracts all the cryptographic requirements and specifies the
+required cryptographic interface in
+``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.h``
+
+The PS service cryptographic operations are implemented in
+``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.c``, using
+calls to the TF-M Crypto service.
+
+PS Service Build Definitions
+============================
+The PS service uses a set of C definitions to compile in/out certain features,
+as well as to configure certain service parameters. When using the TF-M build
+system, these definitions are controlled by build flags of the same name. The
+``config/config_default.cmake`` file sets the default values of those flags, but
+they can be overwritten based on platform capabilities by setting them in
+``platform/ext/target/<TARGET_NAME>/config.cmake``. The list of PS service build
+definitions is:
+
+- ``PS_ENCRYPTION``- this flag allows to enable/disable encryption
+ option to encrypt the protected storage data.
+- ``PS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create a PS flash layout. If this flag is set, PS service will
+ generate an empty and valid PS flash layout to store assets. It will
+ erase all data located in the assigned PS memory area before generating
+ the PS layout. This flag is required to be set if the PS memory area
+ is located in a non-persistent memory. This flag can be set if the PS
+ memory area is located in a persistent memory without a valid PS flash
+ layout in it. That is the case when it is the first time in the device
+ life that the PS service is executed.
+- ``PS_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.
+- ``PS_ROLLBACK_PROTECTION``- this flag allows to enable/disable
+ rollback protection in protected storage service. This flag takes effect only
+ if the target has non-volatile counters and ``PS_ENCRYPTION`` flag is on.
+- ``PS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of
+ the persistent storage device to store the FS in the Protected Storage
+ service. This flag is ``OFF`` by default. The PS regression tests write/erase
+ storage multiple time, so enabling this flag can increase the life of flash
+ memory when testing.
+ If this flag is set to ``ON``, PS_RAM_FS_SIZE must also be provided. This
+ specifies the size of the block of RAM to be used to simulate the flash.
+
+ .. Note::
+ If this flag is disabled when running the regression tests, then it is
+ recommended that the persistent storage area is erased before running the
+ tests to ensure that all tests can run to completion. The type of persistent
+ storage area is platform specific (eFlash, MRAM, etc.) and it is described
+ in corresponding flash_layout.h
+
+- ``PS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ PS area. This size is used to define the temporary buffers used by PS to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as PS does not use dynamic memory allocation.
+- ``PS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ PS 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 PS does not use dynamic memory
+ allocation.
+- ``PS_TEST_NV_COUNTERS``- this flag enables the virtual implementation of the
+ PS NV counters interface in ``test/suites/ps/secure/nv_counters`` of the
+ ``tf-m-tests`` repo, 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, but has no effect when
+ the secure regression test is disabled. This flag can be
+ overridden to ``OFF`` when building the regression tests. In this case,
+ the PS 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 PS 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-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst b/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst
new file mode 100644
index 0000000..2c0509b
--- /dev/null
+++ b/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst
@@ -0,0 +1,83 @@
+#####################################
+PSA Proxy Partition Integration Guide
+#####################################
+
+************
+Introduction
+************
+TF-M PSA Proxy partition is responsible for forwarding all the PSA RoT messages
+to a Secure Enclave, this way virtually providing all the PSA RoT services.
+Proxy can only be used in IPC model, for context and design details please
+check the
+:doc:`Secure Enclave design document </docs/technical_references/secure_enclave_solution>`.
+
+Currently to forward the PSA Client call parameters Proxy must read them with
+``psa_read`` into a memory area shared with the Secure Enclave. (Similarily
+``psa_write`` is used to give back the results to the caller.) By default this
+memory is allocated from BSS, but if that is not accessible to the Secure
+Enclave other memory area can be used. To communicate with the Secure Enclave
+the mailbox solution is used, and Proxy uses the Non-secure side of mailbox.
+(The secure side of the mailbox is handled by the Secure Enclave.)
+
+***************************************
+Current PSA Proxy partition limitations
+***************************************
+- Client IDs are not forwarded to Secure Enclave. For Non-secure clients this
+ is straightforward, but for calls coming from other secure partitions the IDs
+ must be translated to a negative value. The reason is all clients on Host
+ are treated as non-secure from Secure Enclave's point of view. (This is the
+ cause why Protected Storage messages also forwarded. Protected Storage uses
+ Internal Trusted Storage partition to manage the PS flash area. But as client
+ IDs are not forwarded the ITS partition running on Secure Enclave can not
+ know whether should work on ITS or PS flash.)
+- Sending of the mailbox messages is a blocking call in Proxy, so control is
+ not given back to Host's SPM while waiting for Secure Enclave's answer.
+- Only one message can be put into the mailbox at a time.
+- Current platform partition provides Non Volatile (NV) counter, System Reset,
+ and IOCTL services. But while NV counters and System Reset shall be provided
+ by the Secure Enclave, IOCTL probably shall be provided by Host, as the
+ underlaying HW probably placed in Host subsystem. So the current platform
+ partition should be split into two halves by conditional compilation, and
+ Proxy should forward only the calls provided by Secure Enclave.
+- PSA Proxy can only get the IPC parameters by PSA read, so the parameters need
+ to be copied to a shared memory, because the partition cannot forward the
+ original pointers. This copy might be omitted on platforms where Secure
+ Enclave has access to all Host memory areas, if all security risks are
+ addressed. Note that IOVECs shall be verified by Host's SPM and sent to SE
+ with the mailbox message.
+
+**************
+Code Structure
+**************
+PSA Proxy partition code is located in ``secure_fw/partitions/psa_proxy/``.
+As Proxy can be treated as an alternative implementation of all the PSA RoT
+services, the Secure and Non-secure interface implementations of the forwarded
+services are reused without modification.
+
+Files
+=====
+- ``psa_proxy.c`` - Handles IPC messages and manages communication with the
+ Secure Enclave.
+
+- ``psa_proxy_shared_mem_mngr.c`` - Responsible to manage the shared memory
+ area used to share the input and output parameters with Secure Enclave.
+
+*****************
+Integration Guide
+*****************
+- Non-secure mailbox interface must be provided.
+- Shared memory must be configured:
+ - If Secure Enclave can access TF-M's BSS section it is enough to set the
+ area's size by the ``SHARED_BUFFER_SIZE`` macro.
+ - If a special memory region must be used as the shared memory the
+ ``PSA_PROXY_SHARED_MEMORY_BASE`` and ``PSA_PROXY_SHARED_MEMORY_SIZE``
+ macros must be set. (Not just for compilation but for linking as well,
+ becuase these macros used in the linker script/scatter file too.)
+- If memories are mapped to different addresses for Host and Secure Enclave
+ address translation can be turned on by setting
+ ``PSA_PROXY_ADDR_TRANSLATION`` macro and implementing the interface defined
+ by ``platform/include/tfm_plat_psa_proxy_addr_trans.h`` header.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_secure_partition_addition.rst b/docs/integration_guide/services/tfm_secure_partition_addition.rst
new file mode 100644
index 0000000..9343aab
--- /dev/null
+++ b/docs/integration_guide/services/tfm_secure_partition_addition.rst
@@ -0,0 +1,467 @@
+#######################
+Adding Secure Partition
+#######################
+
+***********************
+Terms and abbreviations
+***********************
+This document uses the following terms and abbreviations.
+
+.. table:: term table
+ :widths: auto
+
+ ================== ==================================
+ **Term** **Meaning**
+ ================== ==================================
+ FF Firmware Framework
+ ID Identifier
+ IPC Interprocess communication
+ IPC model The secure IPC framework
+ irqs Interrupt requests
+ Library model The secure function call framework
+ MMIO Memory Mapped I/O
+ PSA Platform Security Architecture
+ RoT Root of Trust
+ SID RoT Service ID
+ SP Secure Partition
+ SPM Secure Partition Manager
+ TF-M Trusted firmware M
+ ================== ==================================
+
+************
+Introduction
+************
+Secure Partition is an execution environment that provides the following
+functions to Root of Trust (RoT) Services:
+
+- Access to resources, protection of its own code and data.
+- Mechanisms to interact with other components in the system.
+
+Each Secure Partition is a single thread of execution and the smallest unit of
+isolation.
+
+This document mainly describes how to add a secure partition in TF-M and
+focuses on the configuration, manifest, implement rules. The actual
+source-level implementation is not included in this document.
+
+.. Note::
+ If not otherwise specified, the steps are identical for library and IPC
+ model.
+
+ The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to
+ `PSA Firmware Framework specification`_ for details.
+
+*******
+Process
+*******
+The main steps to add a secure partition are as follows:
+
+- `Add source folder`_
+- `Add manifest`_
+- `Add configuration`_
+- `Implement the RoT services`_
+
+Add source folder
+=================
+Add a source folder under ``<TF-M base folder>/secure_fw/partitions`` for the new
+secure partition (Let's take EXAMPLE as the folder name):
+
+This folder should include those parts:
+
+- Manifest file: EXAMPLE.yaml
+- CMake configuration files
+- Source code files
+
+Add manifest
+============
+Each Secure Partition must have resource requirements declared in a manifest
+file. The Secure Partition Manager (SPM) uses the manifest file to assemble and
+allocate resources within the SPE. The manifest includes the following:
+
+- A Secure Partition name.
+- A list of implemented RoT Services.
+- Access to other RoT Services.
+- Memory requirements.
+- Scheduling hints.
+- Peripheral memory-mapped I/O regions and interrupts.
+
+.. Note::
+ The current manifest format in TF-M is "yaml" which is different from the
+ requirement of PSA FF.
+
+Here is a manifest reference example for the IPC model, please refer to
+`Library model support`_ for the library extend:
+
+.. code-block:: yaml
+
+ {
+ "psa_framework_version": 1.0,
+ "name": "TFM_SP_EXAMPLE",
+ "type": "PSA-ROT",
+ "priority": "HIGH",
+ "entry_point": "example_main",
+ "stack_size": "0x0200",
+ "services" : [
+ {
+ "name": "ROT_A",
+ "sid": "0x0000F000",
+ "non_secure_clients": true,
+ "version": 1,
+ "version_policy": "STRICT"
+ }
+ ],
+ "mmio_regions": [
+ {
+ "name": "TFM_PERIPHERAL_A",
+ "permission": "READ-WRITE"
+ }
+ ],
+ "irqs": [
+ {
+ "source": "TFM_A_IRQ",
+ "signal": "SPM_CORE_A_IRQ",
+ "tfm_irq_priority": 64,
+ }
+ ],
+ "linker_pattern": {
+ "object_list": [
+ "*EXAMPLE.*"
+ ]
+ }
+ }
+
+Secure Partition ID Distribution
+--------------------------------
+Every Secure Partition has an identifier (ID). TF-M will generate a header file
+that includes definitions of the Secure Partition IDs. The header file is
+``<TF-M base folder>/interface/include/psa_manifest/pid.h``. Each definition
+uses the ``name`` attribute in the manifest as its name and the value is
+allocated by SPM.
+
+.. code-block:: c
+
+ #define name id-value
+
+Here is the Secure Partition ID table used in TF-M.
+
+.. table:: PID table
+ :widths: auto
+
+ =============================== =================
+ **Partition name** **Partition ID**
+ =============================== =================
+ Reserved 0-255
+ TFM_SP_PS 256
+ TFM_SP_ITS 257
+ TFM_SP_AUDIT_LOG 258
+ TFM_SP_CRYPTO 259
+ TFM_SP_PLATFORM 260
+ TFM_SP_INITIAL_ATTESTATION 261
+ TFM_SP_CORE_TEST 262
+ TFM_SP_CORE_TEST_2 263
+ TFM_SP_SECURE_TEST_PARTITION 264
+ TFM_SP_IPC_SERVICE_TEST 265
+ TFM_SP_IPC_CLIENT_TEST 266
+ TFM_IRQ_TEST_1 267
+ TFM_SP_PS_TEST 268
+ =============================== =================
+
+About where to add the definition, please refer to the chapter `Add
+configuration`_.
+
+RoT Service ID (SID) Distribution
+---------------------------------
+An RoT Service is identified by its RoT Service ID (SID). A SID is a 32-bit
+number that is associated with a symbolic name in the Secure Partition
+manifest. The bits [31:12] uniquely identify the vendor of the RoT Service.
+The remaining bits [11:0] can be used at the discretion of the vendor.
+
+Here is the RoT Service ID table used in TF-M.
+
+.. table:: SID table
+ :widths: auto
+
+ =========================== ====================== ========================
+ **Services** **Vendor ID(20 bits)** **Function ID(12 bits)**
+ =========================== ====================== ========================
+ audit_logging 0x00000 0x000-0x01F
+ initial_attestation 0x00000 0x020-0x03F
+ platform 0x00000 0x040-0x05F
+ protected_storage 0x00000 0x060-0x06F
+ internal_trusted_storage 0x00000 0x070-0x07F
+ crypto 0x00000 0x080-0x09F
+ firmware_update 0x00000 0x0A0-0x0BF
+ test_secure_service 0x0000F 0x000-0x01F
+ core_test 0x0000F 0x020-0x03F
+ core_test_2 0x0000F 0x040-0x05F
+ tfm_ipc_client 0x0000F 0x060-0x07F
+ tfm_ipc_service 0x0000F 0x080-0x09F
+ tfm_irq_test_service_1 0x0000F 0x0A0-0x0BF
+ tfm_ps_test_service 0x0000F 0x0C0-0x0DF
+ =========================== ====================== ========================
+
+mmio_regions
+------------
+This attribute is a list of MMIO region objects which the Secure Partition
+needs access to. TF-M only supports the ``named_region`` current. Please refer
+to PSA FF for more details about it. The user needs to provide a name macro to
+indicate the variable of the memory region.
+
+TF-M uses the below structure to indicate a peripheral memory.
+
+.. code-block:: c
+
+ struct platform_data_t {
+ uint32_t periph_start;
+ uint32_t periph_limit;
+ int16_t periph_ppc_bank;
+ int16_t periph_ppc_loc;
+ };
+
+.. Note::
+ This structure is not expected by TF-M, it's only that the current
+ implementations are using. Other peripherals that need different information
+ to create isolation need to define a different structure with the same name.
+
+Here is a example for it:
+
+.. code-block:: c
+
+ struct platform_data_t tfm_peripheral_A;
+ #define TFM_PERIPHERAL_A (&tfm_peripheral_A)
+
+linker_pattern
+--------------
+``linker_pattern`` is a legacy region which contains the minimum information
+required to link a Secure Partition’s compiled static objects. Now, it is
+required as 'IMPLEMENTATION DEFINED' in PSA FF 1.0.0.
+
+Library model support
+---------------------
+For the library model, the user needs to add a ``secure_functions`` item. The
+main difference between ``secure_function`` and ``services`` is the extra
+``signal`` key for secure function entry.
+
+The ``signal`` must be the upper case of the secure function name.
+
+.. code-block:: yaml
+
+ "secure_functions": [
+ {
+ "name": "TFM_EXAMPLE_A",
+ "signal": "EXAMPLE_A_FUNC",
+ "sid": "0x00000000",
+ "non_secure_clients": true,
+ "version": 1,
+ "version_policy": "STRICT"
+ },
+
+Add configuration
+=================
+The following configuration tasks are required for the newly added secure
+partition:
+
+Add CMake configure files
+-------------------------
+- CMakeLists.txt, which is the compilation configuration for this module.
+
+The current CMake configuration should also be updated, by updating
+config_default.cmake to include the definition of the newly introduced partition
+and adding the relevant subdirectoy in ``secure_fw/CMakeLists.txt``.
+Please refer to the source code of TF-M for more detail.
+
+Update manifest list
+--------------------
+The ``<TF-M base folder>/tools/tfm_manifest_list.yaml`` is used to collect
+necessary information of secure partition.
+
+- ``name``: The name string of the secure partition.
+- ``short_name``: should be the same as the ``name`` in the secure partition
+ manifest file.
+- ``manifest``: the relative path of the manifest file to TF-M root.
+- ``tfm_partition_ipc``: indicate if this partition is compatible with the IPC
+ model.
+- ``conditional``: Optional. Configure control macro for this partition.
+- ``version_major``: major version the partition manifest.
+- ``version_minor``: minor version the partition manifest.
+- ``pid``: Secure Partition ID value distributed in chapter `Secure Partition
+ ID Distribution`_.
+
+Reference configuration example:
+
+.. code-block:: yaml
+
+ {
+ "name": "Example Service",
+ "short_name": "TFM_SP_EXAMPLE",
+ "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml",
+ "tfm_partition_ipc": true,
+ "conditional": "TFM_PARTITION_EXAMPLE",
+ "version_major": 0,
+ "version_minor": 1,
+ "pid": 256
+ }
+
+.. Note::
+ The manifest configuration can be placed in a different external manifest
+ list. In this case, the cmake variable TFM_EXTRA_MANIFEST_LIST_PATH should be
+ set to the path of the external manifest list.
+
+Implement the RoT services
+==========================
+To implement RoT services, the partition needs a source file which contains the
+implementations of the services, as well as the partition entry point. The user
+can create this source file under
+``<TF-M base folder>/secure_fw/partitions/EXAMPLE/EXAMPLE.c``. The linker
+detects source files according to the pattern matching defined by the
+"linker_pattern" attribute in the ``tfm_manifest_list.yaml`` file.
+
+As an example, the RoT service with SID **ROT_A** will be implemented.
+
+Entry point function
+--------------------
+This function acts as a main() function for the partition.
+On incoming signals for service calls, the entry point function handles
+signals by calling the relevant service function.
+An example entry point is given
+
+.. code-block:: c
+
+ void example_main(void)
+ {
+ psa_signal_t signals = 0;
+
+ while (1) {
+ signals = psa_wait(PSA_WAIT_ANY, PSA_BLOCK);
+ if (signals & ROT_A_SIGNAL) {
+ rot_A();
+ } else {
+ /* Should not come here */
+ psa_panic();
+ }
+ }
+ }
+
+Service implementation
+----------------------
+The service is implemented by the ``rot_A()`` function, which is called upon an
+incoming signal. This implementation is up to the user, however an example
+service has been included for reference. The following example sends a message
+"Hello World" when called.
+
+.. code-block:: c
+
+ static void rot_A(void)
+ {
+ const int BUFFER_LEN = 32;
+ psa_msg_t msg;
+ psa_status_t r;
+ int i;
+ uint8_t rec_buf[BUFFER_LEN];
+ uint8_t send_buf[BUFFER_LEN] = "Hello World";
+
+ psa_get(ROT_A_SIGNAL, &msg);
+ switch (msg.type) {
+ case PSA_IPC_CONNECT:
+ if (service_in_use & ROT_A_SIGNAL) {
+ r = PSA_ERROR_CONNECTION_REFUSED;
+ } else {
+ service_in_use |= ROT_A_SIGNAL;
+ r = PSA_SUCCESS;
+ }
+ psa_reply(msg.handle, r);
+ break;
+ case PSA_IPC_CALL:
+ for (i = 0; i < PSA_MAX_IOVEC; i++) {
+ if (msg.in_size[i] != 0) {
+ psa_read(msg.handle, i, rec_buf, BUFFER_LEN);
+ }
+ if (msg.out_size[i] != 0) {
+ psa_write(msg.handle, i, send_buf, BUFFER_LEN);
+ }
+ }
+ psa_reply(msg.handle, PSA_SUCCESS);
+ break;
+ case PSA_IPC_DISCONNECT:
+ assert((service_in_use & ROT_A_SIGNAL) != 0);
+ service_in_use &= ~ROT_A_SIGNAL;
+ psa_reply(msg.handle, PSA_SUCCESS);
+ break;
+ default:
+ /* cannot get here [broken SPM] */
+ psa_panic();
+ break;
+ }
+ }
+
+Test connection
+---------------
+To test that the service has been implemented correctly, the user needs to call
+it from somewhere. One option is to create a new testsuite, such as
+``<TF-M-test base folder>/test/suites/example/non_secure/example_ns_interface_testsuite.c``.
+
+.. code-block:: c
+
+ static void tfm_example_test_1001(struct test_result_t *ret)
+ {
+ char str1[] = "str1";
+ char str2[] = "str2";
+ char str3[128], str4[128];
+ struct psa_invec invecs[2] = {{str1, sizeof(str1)},
+ {str2, sizeof(str2)}};
+ struct psa_outvec outvecs[2] = {{str3, sizeof(str3)},
+ {str4, sizeof(str4)}};
+ psa_handle_t handle;
+ psa_status_t status;
+ uint32_t version;
+
+ version = psa_version(ROT_A_SID);
+ TEST_LOG("TFM service support version is %d.\r\n", version);
+ handle = psa_connect(ROT_A_SID, ROT_A_VERSION);
+ status = psa_call(handle, PSA_IPC_CALL, invecs, 2, outvecs, 2);
+ if (status >= 0) {
+ TEST_LOG("psa_call is successful!\r\n");
+ } else {
+ TEST_FAIL("psa_call is failed!\r\n");
+ return;
+ }
+
+ TEST_LOG("outvec1 is: %s\r\n", outvecs[0].base);
+ TEST_LOG("outvec2 is: %s\r\n", outvecs[1].base);
+ psa_close(handle);
+ ret->val = TEST_PASSED;
+ }
+
+Once the test and service has been implemented, the project can be built and
+executed. The user should see the "Hello World" message in the console as
+received by the testsuite.
+
+Further Notes
+-------------
+
+- In the IPC model, Use PSA FF proposed memory accessing mechanism. SPM
+ provides APIs and checking between isolation boundaries, a free accessing
+ of memory can cause program panic.
+- In the IPC model, the memory checking inside partition runtime is
+ unnecessary. SPM handles the checking while memory accessing APIs are
+ called.
+- In the IPC model, the client ID had been included in the message structure
+ and secure partition can get it when calling psa_get() function. The secure
+ partition does not need to call ``tfm_core_get_caller_client_id()`` to get
+ the caller client ID anymore.
+- In the IPC model, SPM will check the security policy and partition
+ dependence between client and service. So the service does not need to
+ validate the secure caller anymore.
+
+*********
+Reference
+*********
+
+| `PSA Firmware Framework specification`_
+
+.. _PSA Firmware Framework specification: https://pages.arm.com/psa-
+ resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
+
+--------------
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/tfm_integration_guide.rst b/docs/integration_guide/tfm_integration_guide.rst
new file mode 100644
index 0000000..c398fbf
--- /dev/null
+++ b/docs/integration_guide/tfm_integration_guide.rst
@@ -0,0 +1,180 @@
+#################
+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 </docs/getting_started/tfm_build_instruction>`.
+
+********************************************************
+How to export files for building non-secure applications
+********************************************************
+Explained in the :doc:`Build instructions </docs/getting_started/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)
+- Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+)
+- Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3)
+- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+- Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
+- CoreLink SSE-200 Subsystem for MPS3 (AN524)
+- Corstone SSE-300 with Ethos-U55 Example Subsystem for MPS3 (AN547)
+- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs)
+- nRF9160 DK (Cortex-M33)
+- nRF5340 PDK/DK (Cortex-M33 Application MCU)
+
+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 subsystems supported by the MPS3 board can be found in:
+`MPS3 homepage <https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps3>`__
+
+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>`__
+
+More information about the Musca-S1 test chip board can be found in:
+`Musca-S1 homepage <https://www.arm.com/company/news/2019/05/arm-demonstrates-new-iot-test-chip-and-board>`__
+
+More information about subsystems supported by the MPS3 board can be found in:
+`MPS3 homepage <https://www.arm.com/products/development-tools/development-boards/mps3>`__
+
+More information about the Corstone-300 FVPs can be found in:
+`Arm Ecosystem FVPs homepage <https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps>`__
+
+More information about the STM32L5xx platform can be found in:
+`STM32L5 series product page <https://www.st.com/content/st_com/en/products/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus/stm32-ultra-low-power-mcus/stm32l5-series.html>`__
+
+More information about the nRF5340 PDK platform can be found in:
+`nRF5340 PDK product page <https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF5340-PDK>`__
+
+More information about the nRF9160 DK platform can be found in:
+`nRF9160 DK product page <https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF9160-DK>`__
+
+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 ITS, PS 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
+``<install_dir>/interface`` 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 ``<install_dir>/interface/include``
+directory. For example, the interface for the Protected Storage (PS) service
+is described in the file ``psa_ps_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 protected storage service uses a numerical ID, to identify the clients that
+use the service. For details see
+:doc:`ns client identification documentation </docs/technical_references/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 PS 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 </docs/technical_references/tfm_ns_client_identification>`.
+
+*********************
+Non-secure interrupts
+*********************
+Non-secure interrupts are allowed to preempt Secure thread mode.
+With the current implementation, a NSPE task can spoof the identity of another
+NSPE task. This is an issue only when NSPE has provisions for task isolation.
+Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
+to NS interrupts to the lower half of available priorities so that it wouldn't
+be possible for any non-secure interrupt to preempt a higher-priority secure
+interrupt.
+
+**********************************
+Integration with non-Cmake systems
+**********************************
+
+Generated Files
+===============
+
+Files that are derived from PSA manifests are generated at build-time by cmake.
+For integration with systems that do no use cmake, the files must be generated
+manually.
+
+The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
+arguments will be needed to be provided. Please refer to
+``tfm_parse_manifest_list.py --help`` for more details.
+
+Some variables are used in the template files, these will need to be set in the
+environment before the script will succeed when the script is not run via cmake.
+
+--------------
+
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*