Docs: Clean and restructure the Integration guide
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I8dca6e3d5cf5cae3a5cd3dc8f2b1e518ab3c20cf
diff --git a/docs/integration_guide/platform/index.rst b/docs/integration_guide/platform/index.rst
index 9fd2f2c..c76e327 100644
--- a/docs/integration_guide/platform/index.rst
+++ b/docs/integration_guide/platform/index.rst
@@ -1,12 +1,15 @@
-Porting to a new platform
-=========================
+#####################
+Adding a new platform
+#####################
.. toctree::
:maxdepth: 1
+ platform_folder.rst
+ platform_ext_folder.rst
porting_TFM_to_a_new_hardware
- /platform/readme
- /platform/ext/readme
+ platform_provisioning.rst
+ platform_deprecation.rst
--------------
diff --git a/docs/integration_guide/platform/platform_deprecation.rst b/docs/integration_guide/platform/platform_deprecation.rst
new file mode 100644
index 0000000..eb981f6
--- /dev/null
+++ b/docs/integration_guide/platform/platform_deprecation.rst
@@ -0,0 +1,68 @@
+################################
+Platform deprecation and removal
+################################
+
+********************************************
+Process for Platform deprecation and removal
+********************************************
+
+A platform may need to be removed from upstream code due to lack of community
+interest or it may have reached end of life. The below section calls out the
+process for removing platform support from TF-M.
+
+ 1. An email to the TF-M mailing list proposing the removal of the platform.
+
+ 2. The merit of the proposal will be considered by the maintainers for a
+ period of 4 weeks and community can express their opinion on the same
+ during this time window. The platform owner can veto the proposal and
+ incase of multiple platform owners with differing opinion or community
+ having interest in the platform, then the project maintainer can work
+ with the platform owner and use their discretion to decide on the
+ proposal.
+
+ 3. Once a decision is made to remove the platform, the platform is
+ considered to be in `deprecated` state as per platform support lifecyle
+ defined here: "https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/".
+ The platform will be marked as deprecated and the TF-M version after
+ which it will be removed will also be mentioned. Suitable build time
+ or runtime messages needs to be incorporated to the platform to warn
+ about the `deprecation`.
+
+ 4. The project should strive to keep the `deprecated` platforms
+ building/running till the removal. This relies on platform owners being
+ still actively involved with the project and maintaining the platform.
+
+ 5. Although this will be the usual process for platform deprecation and
+ eventual removal, the process still leaves room for the platform
+ deprecation to be cancelled after it has been marked as `deprecated`
+ due to evolving project and market requirements. This is left to
+ consensus between project maintainers and platform owner/s.
+
+ 6. Once a platform has been removed, it can be added back in future and
+ this would follow the same guidelines as for a new platform contribution.
+
+****************************
+List of Deprecated Platforms
+****************************
+
+The below list calls out platforms marked for deprecation according to the
+above process and the platform will be removed soon after the mentioned
+release.
+
++--------------------------------------+-----------+---------------------------+
+| Deprecated Platform | Removed | Comments |
+| | after | |
+| | release | |
++======================================+===========+===========================+
+| arm/mps2/an539 | v1.2.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+| arm/mps2/sse-200_aws | v1.3.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+| arm/musca_a | v1.3.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+| arm/mps2/fvp_sse300 | v1.4.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/platform/platform_ext_folder.rst b/docs/integration_guide/platform/platform_ext_folder.rst
new file mode 100644
index 0000000..aa2122c
--- /dev/null
+++ b/docs/integration_guide/platform/platform_ext_folder.rst
@@ -0,0 +1,301 @@
+###################################
+Details for the platform/ext folder
+###################################
+
+This folder has code that has been imported from other projects. This means the
+files in this folder and subfolders have Apache 2.0 license which is different
+to BSD 3.0 license applied to the parent TF-M project.
+
+.. Note::
+ This folder is strictly Apache 2.0 with the exception of cmake files.
+ Maintainers should be consulted if this needs to be revisited.
+
+***********
+Sub-folders
+***********
+
+accelerator
+===========
+This folder contains cmake and code files to interact cryptographic
+accelerators.
+
+In order to use a cryptographic accelerator, a platform must set
+``CRYPTO_HW_ACCELERATOR_TYPE`` in preload.cmake. This option maps directly to
+the subdirectories of the accelerator directory. Currently available
+accelerators are : the CryptoCell ``cc312``, the STMicroelectronics accelerator
+``stm`` .
+
+A minimal API is exposed to interact with accelerators, the details of this api
+are in ``accelerator/interface/crypto_hw.h``. Implementation of the API is
+inside the subdirectory of the individual accelerator.
+
+To configure a cryptographic accelerator at build time, two cmake options can be
+specified.
+
+- ``CRYPTO_HW_ACCELERATOR``
+ - ``ON`` All possible mbedtls cryptographic operations will be offloaded to
+ the accelerator.
+ - ``OFF`` The cryptographic accelerator will be ignored and software
+ cryptography will be used.
+
+cmsis
+=====
+This folder contains core and compiler specific header files imported from the
+``CMSIS_5`` project.
+
+common
+======
+
+armclang and gcc
+----------------
+These contain the linker scripts used to configure the memory regions in TF-M
+regions.
+
+template
+--------
+This directory contains platform-independent dummy implementations of the
+interfaces in ``platform/include``. These implementations can be built directly
+for initial testing of a platform port, or used as a basic template for a real
+implementation for a particular target. They **must not** be used in production
+systems.
+
+driver
+======
+This folder contains the headers with CMSIS compliant driver definitions that
+that TF-M project expects a target to provide.
+
+target_cfg.h
+------------
+This file is expected to define the following macros respectively.
+
+- ``TFM_DRIVER_STDIO`` - This macro should expand to a structure of type
+ ``ARM_DRIVER_USART``. TFM redirects its standard input and output to this
+ instance of USART.
+- ``NS_DRIVER_STDIO`` - This macro should expand to a structure of type
+ ``ARM_DRIVER_USART``. Non-Secure application redirects its standard input and
+ output to this instance of USART.
+
+target
+======
+This folder contains the files for individual target. For a buildable target,
+the directory path from the ``target`` directory to its ``CMakeLists.txt`` file
+is the argument that would be given to ``-DTFM_PLATFORM=``.
+
+The standard directory structure is as follows:
+
+- target
+ - <Vendor name>
+ - common
+ - <buildable target 1>
+ - <buildable target 2>
+ - <buildable target 3>
+
+Each buildable target must contain the cmake files mandated in the section
+below.
+
+The ``common`` directory is not required, but can be used to contain code that
+is used by multiple targets.
+
+There must not be any directories inside the vendor directory that is not either
+the ``common`` directory or a buildable platform, to avoid confusion about what
+directories are a valid ``TFM_PLATFORM``.
+
+Buildable target required cmake files
+-------------------------------------
+
+A buildable target must provide 3 mandatory cmake files. These files must all be
+placed in the root of the buildable target directory.
+
+preload.cmake
+^^^^^^^^^^^^^
+
+This file contains variable definitions that relate to the underlying hardware
+of the target.
+
+- ``TFM_SYSTEM_PROCESSOR``: The processor used by the target. The format is that
+ same as the format used in the ``-mcpu=`` argument of GNUARM or ARMCLANG. The
+ special ``+modifier`` syntax must not be used.
+
+- ``TFM_SYSTEM_ARCHITECTURE``: The architecture used by the target. The format is
+ that same as the format used in the ``-march=`` argument of GNUARM or ARMCLANG.
+ The special ``+modifier`` syntax must not be used.
+
+- ``TFM_SYSTEM_DSP``: Whether the target has the DSP feature of the given
+ ``TFM_SYSTEM_PROCESSOR``
+- ``CRYPTO_HW_ACCELERATOR_TYPE``: The type of cryptographic accelerator the
+ target has, if it has one. This maps exactly to the subdirectories of
+ ``platform/ext/accelerator``
+
+Other than these particular cmake variables, it is permissible for the
+``preload.cmake`` file to contain ``add_definitions`` statements, in order for
+set compile definitions that are global for the hardware. This is commonly used
+to select a particular set of code from a vendor SDK.
+
+It is not permissible to contains code other than the above in a
+``preload.cmake`` file, any general cmake code should be placed in
+``CMakeLists.txt`` and any configuration options should be contained in
+``config.cmake``
+
+config.cmake
+^^^^^^^^^^^^
+
+This file collects platform-specific overrides to the configuration options.
+This should only contain cmake options that are included in
+``config_default.cmake``. These options should be set as ``CACHE`` variables, as
+they are in ``config_default.cmake``.
+
+CMakeLists.txt
+^^^^^^^^^^^^^^
+
+This file should contain all other required cmake code for the platform. This
+primarily consists of the following:
+
+- Adding an include directory to the target ``platform_region_defs``, which
+ contains the headers ``flash_layout.h`` and ``region_defs.h``
+
+- Adding startup and scatter files to the ``tfm_s``, ``tfm_ns`` and ``bl2``
+ targets.
+
+- linking ``CMSIS_5_tfm_ns`` to the correct version of the CMSIS RTX libraries,
+ as defined in ``lib/ext/CMSIS_5/CMakeLists.txt``
+
+- Adding required source files, include directories and compile definitions to
+ the ``platform_s``, ``platform_ns`` and ``platform_bl2`` targets.
+
+preload_ns.cmake
+^^^^^^^^^^^^^^^^
+
+This optional cmake file is required only if the target runs the NSPE on a
+core that requires different compiler options than the SPE core. This file has
+the same format as ``preload.cmake``, but instead details the hardware of the
+NS core that is **not** running the main TF-M secure code.
+
+Flash layout header file
+------------------------
+Target must provide a header file, called ``flash_layout.h``, which defines the
+information explained in the follow subsections. The defines must be named
+as they are in the subsections.
+
+BL2 bootloader
+^^^^^^^^^^^^^^
+The BL2 bootloader requires the following definitions:
+
+- ``FLASH_BASE_ADDRESS`` - Defines the first valid address in the flash.
+- ``FLASH_AREA_BL2_OFFSET`` - Defines the offset from the flash base address
+ where the BL2 - MCUBOOT area starts.
+- ``FLASH_AREA_BL2_SIZE`` - Defines the size of the BL2 area.
+- ``FLASH_AREA_SCRATCH_OFFSET`` - Defines the offset from the flash base
+ address where the scratch area starts, which is used during image swapping.
+- ``FLASH_AREA_SCRATCH_SIZE`` - Defines the size of the scratch area. The
+ minimal size must be as the biggest sector size in the flash.
+- ``FLASH_DEV_NAME`` - Specifies the flash device used by BL2.
+
+The BL2 requires further definitions depending on the number of images, the
+meaning of these macros are also slightly different:
+
+- Required definitions in case of 1 image (S and NS images are concatenated
+ and handled together as one binary blob):
+
+ - ``FLASH_AREA_0_OFFSET`` - Defines the offset from the flash base address
+ where the primary image area starts, which hosts the active firmware
+ image.
+ - ``FLASH_AREA_0_SIZE`` - Defines the size of the primary image area.
+ - ``FLASH_AREA_2_OFFSET`` - Defines the offset from the flash base address
+ where the secondary image area starts, which is a placeholder for new
+ firmware images.
+ - ``FLASH_AREA_2_SIZE`` - Defines the size of the secondary image area.
+
+- Required definitions in case of 2 images (S and NS images are handled and
+ updated separately):
+
+ - ``FLASH_AREA_0_OFFSET`` - Defines the offset from the flash base address
+ where the primary image areas start, which host the active firmware
+ images. It is also the offset of the primary (active) secure image area.
+ - ``FLASH_AREA_0_SIZE`` - Defines the size of the primary secure image area.
+ - ``FLASH_AREA_1_OFFSET`` - Defines the offset from the flash base address
+ where the primary (active) non-secure image area starts.
+ - ``FLASH_AREA_1_SIZE`` - Defines the size of the primary non-secure image
+ area.
+ - ``FLASH_AREA_2_OFFSET`` - Defines the offset from the flash base address
+ where the secondary image areas start, which are placeholders for new
+ firmware images. It is also the offset of the secondary secure image area.
+ - ``FLASH_AREA_2_SIZE`` - Defines the size of the secondary secure image
+ area.
+ - ``FLASH_AREA_3_OFFSET`` - Defines the offset from the flash base address
+ where the secondary non-secure image area starts.
+ - ``FLASH_AREA_3_SIZE`` - Defines the size of the secondary non-secure image
+ area.
+
+The table below shows a fraction of the flash layout in case of 2 and 1
+updatable images with the related flash areas that hold the firmware images:
+
++-----------------------+--------------------+-----------------------+-----------------------------+
+| Image number: 2 | Image number: 1 |
++=======================+====================+=======================+=============================+
+| **Flash area** | **Content** | **Flash area** | **Content** |
++-----------------------+--------------------+-----------------------+-----------------------------+
+| FLASH_AREA_0 | | Secure image | FLASH_AREA_0 | | Secure + Non-secure image |
+| | | primary slot | | | primary slot |
++-----------------------+--------------------+-----------------------+ +
+| FLASH_AREA_1 | | Non-secure image | | |
+| | | primary slot | | |
++-----------------------+--------------------+-----------------------+-----------------------------+
+| FLASH_AREA_2 | | Secure image | FLASH_AREA_2 | | Secure + Non-secure image |
+| | | secondary slot | | | secondary slot |
++-----------------------+--------------------+-----------------------+ +
+| FLASH_AREA_3 | | Non-secure image | | |
+| | | secondary slot | | |
++-----------------------+--------------------+-----------------------+-----------------------------+
+| FLASH_AREA_SCRATCH | Scratch area | FLASH_AREA_SCRATCH | Scratch area |
++-----------------------+--------------------+-----------------------+-----------------------------+
+
+- ``IMAGE_EXECUTABLE_RAM_START`` - Defines the start of the region to which
+ images are allowed to be loaded. Only used if ``MCUBOOT_UPGRADE_STRATEGY`` is
+ configured to be ``RAM_LOAD``.
+
+- ``IMAGE_EXECUTABLE_RAM_SIZE`` - Defines the size of the region to which images
+ are allowed to be loaded. Only used if ``MCUBOOT_UPGRADE_STRATEGY`` is
+ configured to be ``RAM_LOAD``.
+
+Assemble tool
+^^^^^^^^^^^^^
+The ``assemble.py`` tool is used to concatenate secure and non-secure binary
+to a single binary blob. It requires the following definitions:
+
+- ``SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob base
+ address, where the secure image starts.
+- ``SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the secure image area.
+- ``NON_SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob
+ base address, where the non-secure image starts.
+- ``NON_SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the non-secure
+ image area.
+
+Image tool
+^^^^^^^^^^^^^
+The ``imgtool.py`` tool is used to handle the tasks related to signing the
+binary. It requires the following definition:
+
+- ``S_IMAGE_LOAD_ADDRESS`` - Defines the address to where the Secure (or
+ combined Secure and Non-secure) image is loaded and is executed from. Only
+ used if ``MCUBOOT_UPGRADE_STRATEGY`` is configured to be ``RAM_LOAD``.
+
+- ``NS_IMAGE_LOAD_ADDRESS`` - Defines the address to where the Non-secure image
+ is loaded and is executed from. Only used if ``MCUBOOT_UPGRADE_STRATEGY`` is
+ configured to be ``RAM_LOAD`` and ``MCUBOOT_IMAGE_NUMBER`` is greater than 1.
+
+***************************************
+Expose target support for HW components
+***************************************
+Services may require HW components to be supported by the target to enable some
+features (e.g. PS service with rollback protection, etc). The following
+definitions need to be set in the .cmake file if the target has the following
+HW components:
+
+- ``TARGET_NV_COUNTERS_ENABLE`` - Specifies that the target has non-volatile
+ (NV) counters.
+
+--------------
+
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2022 Cypress Semiconductor Corporation (an Infineon company)
+or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/integration_guide/platform/platform_folder.rst b/docs/integration_guide/platform/platform_folder.rst
new file mode 100644
index 0000000..13b2845
--- /dev/null
+++ b/docs/integration_guide/platform/platform_folder.rst
@@ -0,0 +1,102 @@
+###############################
+Details for the platform folder
+###############################
+
+*********************
+Interfacing with TF-M
+*********************
+
+platform/ext/target/tfm_peripherals_def.h
+=========================================
+This file should enumerate the hardware peripherals that are available for TF-M
+on the platform. The name of the peripheral used by a service is set in its
+manifest file. The platform have to provide a macro for each of the provided
+peripherals, that is substituted to a pointer to type
+``struct platform_data_t``. The memory that the pointer points
+to is allocated by the platform code. The pointer gets stored in the partitions
+database in SPM, and it is provided to the SPM HAL functions.
+
+Peripherals currently used by the services in TF-M
+--------------------------------------------------
+- ``TFM_PERIPHERAL_UART1``- UART1
+
+.. Note::
+
+ If a platform doesn't support a peripheral, that is used by a service, then
+ the service cannot be used on the given platform. Using a peripheral in
+ TF-M that is not supported by the platform results in compile error.
+
+platform/include/tfm_spm_hal.h
+==============================
+This file contains the declarations of functions that a platform implementation
+has to provide for TF-M's SPM. For details see the comments in the file.
+
+secure_fw/core/include/tfm_platform_core_api.h
+==============================================
+This file contains declarations of functions that can be or have to be called
+from platform implementations. For details see the comments in the file.
+
+platform/include/tfm_platform_system.h
+======================================
+This file contains the declarations of functions that a platform implementation
+has to provide for TF-M's Platform Service. For details see
+``docs/user_guides/services/tfm_platform_integration_guide.rst``
+
+**************
+System Startup
+**************
+
+Before calling ``main()``, platform startup code should initialise all system
+clocks, perform runtime initialisation and other steps such as setting the
+vector table. Configuration of the following features is optional as TF-M
+architecture code will check and initialise them:
+
+ - The Security Extension.
+ - The Floating-point Extension.
+
+*****************************
+Debug authentication settings
+*****************************
+
+A platform may provide the option to configure debug authentication. TF-M core
+calls the HAL function ``enum tfm_hal_status_t tfm_hal_platform_init(void)``
+in which debug authentication is configured based on the following defines:
+
+ - `DAUTH_NONE`: Debugging the system is not enabled.
+ - `DAUTH_NS_ONLY`: Invasive and non invasive debugging of non-secure code is
+ enabled.
+ - `DAUTH_FULL`: Invasive and non-invasive debugging of non-secure and secure
+ code is enabled.
+ - `DAUTH_CHIP_DEFAULT`: The debug authentication options are used that are set
+ by the chip vendor.
+
+The desired debug authentication configuration can be selected by setting one of
+the options above to the cmake command with the
+`-DDEBUG_AUTHENTICATION="<define>"` option. The default value of
+`DEBUG_AUTHENTICATION` is `DAUTH_CHIP_DEFAULT`.
+
+.. Note::
+ ``enum tfm_hal_status_t tfm_hal_platform_init(void)`` is called during the
+ TF-M core initialisation phase, before initialising secure partition. This
+ means that BL2 runs with the chip default setting.
+
+***********
+Sub-folders
+***********
+
+include
+=======
+This folder contains the interfaces that TF-M expects every target to provide.
+The code in this folder is created as a part of the TF-M project therefore it
+adheres to the BSD 3.0 license.
+
+ext
+===
+This folder contains code that has been imported from other projects so it may
+have licenses other than the BSD 3.0 used by the TF-M project.
+
+Please see the :doc:`platform_ext_folder` for details.
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/platform/platform_provisioning.rst b/docs/integration_guide/platform/platform_provisioning.rst
new file mode 100644
index 0000000..52d96aa
--- /dev/null
+++ b/docs/integration_guide/platform/platform_provisioning.rst
@@ -0,0 +1,89 @@
+#####################
+Platform Provisioning
+#####################
+
+TF-M stores any data that should be provisioned at the factory in OTP memory.
+The default is that this OTP memory is actually implemented using on-chip flash,
+the same that is used to implement the ITS service.
+
+If the lifecycle state is in the ``TFM_SLC_ASSEMBLY_AND_TEST`` [1]_ state (which
+is the default for non-provisioned boards), then TF-M will attempt to provision
+the:
+- HUK
+instead of booting. It will read the data from the
+``assembly_and_test_prov_data`` struct, and will then provision it to OTP. The
+lifecycle state will then transition to ``TFM_SLC_PSA_ROT_PROVISIONING`` [1]_.
+
+If the lifecycle state is in the ``TFM_SLC_PSA_ROT_PROVISIONING`` [1]_ state,
+then TF-M will attempt to provision the:
+
+- IAK
+- boot seed
+- implementation id
+- hw version
+- bl2 ROTPKs (of which there are up to 4)
+- entropy seed
+
+Once all of these have been loaded from the ``psa_rot_prov_data`` struct and
+provisioned to OTP, the LCS will transition to ``TFM_SLC_SECURED`` [1]_. Note
+that this provisioning step will be run immediately after the
+``TFM_SLC_ASSEMBLY_AND_TEST`` [1]_ provisioning stage if the lifecycle
+transition completed successfully.
+
+Provisioning development hardware
+=================================
+
+If ``TFM_DUMMY_PROVISIONING`` is enabled in the cmake config (as it is by
+default), a set of dummy keys / data will be provisioned. The dummy IAK matches
+the IAK tested by the TF-M tests, and the dummy bl2 ROTPKs match the dummy bl2
+keys used by default. ``TFM_DUMMY_PROVISIONING`` _MUST_ not be used in
+production hardware, as the keys are insecure.
+
+Provisioning production hardware
+================================
+
+For provisioning of real hardware, firstly ``TFM_DUMMY_PROVISIONING`` must be
+disabled. Then it is required to inject the keys into RAM so they populate the
+``assembly_and_test_prov_data`` and ``psa_rot_prov_data`` structs, at the
+beginning of the TF-M boot. These structs each require a magic value to be set
+to be accepted by the provisioning code, which is detailed in
+``platform/ext/common/provisioning.c``. Two suggestions for how to do this are:
+
+- Attach a debugger, and inject the values into RAM.
+- Flash an image that contains the required data. Care must be taken with this
+ approach that the keys are not left in RAM after provisioning, so a different
+ image (without provisioning data embedded) must be flashed afterwards, without
+ erasing the OTP flash area.
+
+************************************************
+Provisioning on CryptoCell-312 enabled platforms
+************************************************
+
+On boards that have a CC312 accelerator, and that have the default flash-backed
+OTP disabled by setting ``PLATFORM_DEFAULT_OTP=OFF`` in cmake, the CC312 OTP
+will be used as a backing for the OTP HAL.
+
+Due to the CC312 requiring a power-cycle to transition LCS, you will be prompted
+to manually power-cycle the board between provisioning stages.
+
+Boards with real OTP memory cannot be reprovisioned - care should be taken that
+the data being provisioned is the desired data.
+
+*****************************
+Platform-specific OTP backing
+*****************************
+
+If a platform has a medium that is suitable for storing data with OTP semantics
+(Where a bit cannot transition from a 1 to a 0), such as physical OTP memory,
+then it can provide a backing for the OTP HAL by implementing the methods
+described in ``tfm_plat_otp.h``.
+
+--------------
+
+.. [1] For the definitions of these lifecycle states, please refer to the
+ Platform Security Model
+ https://developer.arm.com/documentation/den0128/0100/
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*