Docs: Clean and restructure the Integration guide
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I8dca6e3d5cf5cae3a5cd3dc8f2b1e518ab3c20cf
diff --git a/docs/platform/ext/index.rst b/docs/platform/ext/index.rst
index 22861e5..da883ef 100644
--- a/docs/platform/ext/index.rst
+++ b/docs/platform/ext/index.rst
@@ -50,13 +50,6 @@
target/nuvoton/**
-.. toctree::
- :maxdepth: 1
- :caption: Rules and processes
-
- platform_deprecation.rst
- platform_provisioning.rst
-
--------------
*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/platform/ext/platform_deprecation.rst b/docs/platform/ext/platform_deprecation.rst
deleted file mode 100644
index dff0937..0000000
--- a/docs/platform/ext/platform_deprecation.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-################################
-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 | |
-+======================================+===========+===========================+
-| mps2/an539 | v1.2.0 | N.A |
-+--------------------------------------+-----------+---------------------------+
-| mps2/sse-200_aws | v1.3.0 | N.A |
-+--------------------------------------+-----------+---------------------------+
-| 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/platform/ext/platform_introduction.rst b/docs/platform/ext/platform_introduction.rst
index 2d2eb68..b6fecda 100644
--- a/docs/platform/ext/platform_introduction.rst
+++ b/docs/platform/ext/platform_introduction.rst
@@ -66,5 +66,5 @@
- :doc:`RSS. </platform/ext/target/arm/rss/readme>`
-The document :doc:`Platform Deprecation and Removal </platform/ext/platform_deprecation>`
-lists the deprecated platforms planned to be removed from upstream.
+The document :doc:`Platform Deprecation and Removal </integration_guide/platform/platform_deprecation>`
+lists the deprecated platforms, removed from the upstream.
diff --git a/docs/platform/ext/platform_provisioning.rst b/docs/platform/ext/platform_provisioning.rst
deleted file mode 100644
index 52d96aa..0000000
--- a/docs/platform/ext/platform_provisioning.rst
+++ /dev/null
@@ -1,89 +0,0 @@
-#####################
-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.*
diff --git a/docs/platform/ext/readme.rst b/docs/platform/ext/readme.rst
deleted file mode 100644
index da37c46..0000000
--- a/docs/platform/ext/readme.rst
+++ /dev/null
@@ -1,300 +0,0 @@
-###################################
-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.*