Docs: Update code structure doc
- fix the number of CPU to 8 to avoid Sphinx crash in OpenCI
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I4f05857a639ec2609f5b21cb739a6e91e5372fc0
diff --git a/docs/integration_guide/source_structure/index.rst b/docs/integration_guide/source_structure/index.rst
new file mode 100644
index 0000000..426e2a9
--- /dev/null
+++ b/docs/integration_guide/source_structure/index.rst
@@ -0,0 +1,8 @@
+.. toctree::
+ :maxdepth: 1
+
+ source_structure.rst
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/source_structure/platform_ext_folder.rst b/docs/integration_guide/source_structure/platform_ext_folder.rst
new file mode 100644
index 0000000..ec52d26
--- /dev/null
+++ b/docs/integration_guide/source_structure/platform_ext_folder.rst
@@ -0,0 +1,309 @@
+.. _platform_ext_folder:
+
+###################################
+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_base.cmake``. These options should be set as ``CACHE`` variables, as
+they are in ``config_base.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.
+
+install.cmake
+^^^^^^^^^^^^^
+
+This optional cmake file is required only if additional files need to be
+installed for the platform.
+
+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-2023, 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/source_structure/platform_folder.rst b/docs/integration_guide/source_structure/platform_folder.rst
new file mode 100644
index 0000000..8b36222
--- /dev/null
+++ b/docs/integration_guide/source_structure/platform_folder.rst
@@ -0,0 +1,99 @@
+.. _platform_folder:
+
+###############################
+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.
+
+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-2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/source_structure/source_structure.rst b/docs/integration_guide/source_structure/source_structure.rst
new file mode 100644
index 0000000..126bd9c
--- /dev/null
+++ b/docs/integration_guide/source_structure/source_structure.rst
@@ -0,0 +1,126 @@
+.. _source_structure:
+
+################
+Source Structure
+################
+
+TF-M is designed to provide a user-friendly source structure to ease
+integration and service development. This document introduces the source
+structure and its design intention of TF-M. Additionally, the folders below are
+important for TF-M integration and descibed in a separate documents:
+
+.. toctree::
+ :maxdepth: 1
+
+ Details for the /platform folder <platform_folder.rst>
+ Details for the /platform/ext folder <platform_ext_folder.rst>
+
+/ (TF-M root)
+=============
+This table describes the structure under the root folder with part of
+possible folders.
+
+========================= ====================================
+Folder name Description
+========================= ====================================
+bl1 The 1st stage immutable bootloader
+bl2 MCUBoot based 2nd stage bootloader
+cmake Cmake files of the build system
+config Configuration system files
+docs The documentation
+interface RoT service API for client calls
+lib The 3rd party libraries
+`platform`_ Platform intermedia files
+`secure_fw`_ The secure firmware
+tools Tools in scripts for building
+========================= ====================================
+
+platform
+========
+The `platform` folder contains SW ports of all :ref:`supported platforms
+<supported_platforms>` and the files necessary for :ref:`adding a new platform
+<adding_platform>`. Please refer to :ref:`platform folder document
+<platform_folder>` for more information.
+
+========================= =============================================
+Folder name Description
+========================= =============================================
+include HAL and platform public headers
+ext Platform ports and related files
+========================= =============================================
+
+platform/ext
+------------
+This folder can include imported files licensed differently from TF-M's
+BSD-3 license. More details are in the dedicated document :ref:`platform_ext_folder`.
+
+========================= =============================================
+Folder name Description
+========================= =============================================
+accelerator Supported Crypto HW accelerators
+cmsis A copy of essential CMSIS headers
+common Common HAL implementation
+driver Driver headers for porting
+target/<vendor> Vendor specific folders with ported platforms
+========================= =============================================
+
+Each `vendor` is assigned one folder for usage under `target/`.
+A `vendor` contributes platform's ports and manages the structure inside it.
+
+secure_fw
+=========
+This folder contains components needed by secure firmware and the exported
+interfaces for application, service development and HAL integration.
+
+========================= =============================================
+Folder name Description
+========================= =============================================
+include Public headers of `secure_fw`
+partitions Default services and SPRTL
+spm PSA FF-M SPM implementation
+shared Sources shared out of SPRTL
+========================= =============================================
+
+The shared sources can be referenced by the building system out of SPRTL.
+Generally, they are runtime and PSA APIs.
+
+secure_fw/include
+-----------------
+This folder holds public headers for external references by clients,
+services and platforms. Avoid putting private headers, not referenced by
+other modules in this `include` folder.
+
+secure_fw/partitions
+--------------------
+This folder contains default services implemented as partitions and runtime
+utilities used and provided by TF-M.
+
+============================== =============================================
+Folder name Description
+============================== =============================================
+lib/runtime The SPRTL sources and intermedia files
+<partition_x> Sources of `partition_x`
+<partition_x>/include RoT Service API headers of `partition_x`
+<partition_y> Sources of `partition_y`
+<partition_y>/include RoT Service API headers of `partition_y`
+============================== =============================================
+
+Here `partition_x` and `partition_y` are examples of RoT services without
+detailed structure of them.
+
+secure_fw/spm
+-------------
+The SPM is the core component to provide a mechanism for providing secure
+services complied with PSA FF-M.
+
+============================== =============================================
+Folder name Description
+============================== =============================================
+include SPM public headers.
+ffm SPM logic complies with PSA FF-M specification
+cmsis_psa CMSIS implementation for PSA FF-M SPM
+============================== =============================================
+
+--------------
+
+*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*