1################################### 2Details for the platform/ext folder 3################################### 4 5This folder has code that has been imported from other projects. This means the 6files in this folder and subfolders have Apache 2.0 license which is different 7to BSD 3.0 license applied to the parent TF-M project. 8 9.. Note:: 10 This folder is strictly Apache 2.0 with the exception of cmake files. 11 Maintainers should be consulted if this needs to be revisited. 12 13*********** 14Sub-folders 15*********** 16 17accelerator 18=========== 19This folder contains cmake and code files to interact cryptographic 20accelerators. 21 22In order to use a cryptographic accelerator, a platform must set 23``CRYPTO_HW_ACCELERATOR_TYPE`` in preload.cmake. This option maps directly to 24the subdirectories of the accelerator directory. Currently available 25accelerators are : the CryptoCell ``cc312``, the STMicroelectronics accelerator 26``stm`` . 27 28A minimal API is exposed to interact with accelerators, the details of this api 29are in ``accelerator/interface/crypto_hw.h``. Implementation of the API is 30inside the subdirectory of the individual accelerator. 31 32To configure a cryptographic accelerator at build time, two cmake options can be 33specified. 34 35- ``CRYPTO_HW_ACCELERATOR`` 36 - ``ON`` All possible mbedtls cryptographic operations will be offloaded to 37 the accelerator. 38 - ``OFF`` The cryptographic accelerator will be ignored and software 39 cryptography will be used. 40 41cmsis 42===== 43This folder contains core and compiler specific header files imported from the 44``CMSIS_5`` project. 45 46common 47====== 48 49armclang and gcc 50---------------- 51These contain the linker scripts used to configure the memory regions in TF-M 52regions. 53 54template 55-------- 56This directory contains platform-independent dummy implementations of the 57interfaces in ``platform/include``. These implementations can be built directly 58for initial testing of a platform port, or used as a basic template for a real 59implementation for a particular target. They **must not** be used in production 60systems. 61 62driver 63====== 64This folder contains the headers with CMSIS compliant driver definitions that 65that TF-M project expects a target to provide. 66 67target_cfg.h 68------------ 69This file is expected to define the following macros respectively. 70 71- ``TFM_DRIVER_STDIO`` - This macro should expand to a structure of type 72 ``ARM_DRIVER_USART``. TFM redirects its standard input and output to this 73 instance of USART. 74- ``NS_DRIVER_STDIO`` - This macro should expand to a structure of type 75 ``ARM_DRIVER_USART``. Non-Secure application redirects its standard input and 76 output to this instance of USART. 77 78target 79====== 80This folder contains the files for individual target. For a buildable target, 81the directory path from the ``target`` directory to its ``CMakeLists.txt`` file 82is the argument that would be given to ``-DTFM_PLATFORM=``. 83 84The standard directory structure is as follows: 85 86- target 87 - <Vendor name> 88 - common 89 - <buildable target 1> 90 - <buildable target 2> 91 - <buildable target 3> 92 93Each buildable target must contain the cmake files mandated in the section 94below. 95 96The ``common`` directory is not required, but can be used to contain code that 97is used by multiple targets. 98 99There must not be any directories inside the vendor directory that is not either 100the ``common`` directory or a buildable platform, to avoid confusion about what 101directories are a valid ``TFM_PLATFORM``. 102 103Buildable target required cmake files 104------------------------------------- 105 106A buildable target must provide 3 mandatory cmake files. These files must all be 107placed in the root of the buildable target directory. 108 109preload.cmake 110^^^^^^^^^^^^^ 111 112This file contains variable definitions that relate to the underlying hardware 113of the target. 114 115- ``TFM_SYSTEM_PROCESSOR``: The processor used by the target. The format is that 116 same as the format used in the ``-mcpu=`` argument of GNUARM or ARMCLANG. The 117 special ``+modifier`` syntax must not be used. 118 119- ``TFM_SYSTEM_ARCHITECTURE``: The architecture used by the target. The format is 120 that same as the format used in the ``-march=`` argument of GNUARM or ARMCLANG. 121 The special ``+modifier`` syntax must not be used. 122 123- ``TFM_SYSTEM_DSP``: Whether the target has the DSP feature of the given 124 ``TFM_SYSTEM_PROCESSOR`` 125- ``CRYPTO_HW_ACCELERATOR_TYPE``: The type of cryptographic accelerator the 126 target has, if it has one. This maps exactly to the subdirectories of 127 ``platform/ext/accelerator`` 128 129Other than these particular cmake variables, it is permissible for the 130``preload.cmake`` file to contain ``add_definitions`` statements, in order for 131set compile definitions that are global for the hardware. This is commonly used 132to select a particular set of code from a vendor SDK. 133 134It is not permissible to contains code other than the above in a 135``preload.cmake`` file, any general cmake code should be placed in 136``CMakeLists.txt`` and any configuration options should be contained in 137``config.cmake`` 138 139config.cmake 140^^^^^^^^^^^^ 141 142This file collects platform-specific overrides to the configuration options. 143This should only contain cmake options that are included in 144``config_base.cmake``. These options should be set as ``CACHE`` variables, as 145they are in ``config_base.cmake``. 146 147CMakeLists.txt 148^^^^^^^^^^^^^^ 149 150This file should contain all other required cmake code for the platform. This 151primarily consists of the following: 152 153- Adding an include directory to the target ``platform_region_defs``, which 154 contains the headers ``flash_layout.h`` and ``region_defs.h`` 155 156- Adding startup and scatter files to the ``tfm_s``, ``tfm_ns`` and ``bl2`` 157 targets. 158 159- linking ``CMSIS_5_tfm_ns`` to the correct version of the CMSIS RTX libraries, 160 as defined in ``lib/ext/CMSIS_5/CMakeLists.txt`` 161 162- Adding required source files, include directories and compile definitions to 163 the ``platform_s``, ``platform_ns`` and ``platform_bl2`` targets. 164 165preload_ns.cmake 166^^^^^^^^^^^^^^^^ 167 168This optional cmake file is required only if the target runs the NSPE on a 169core that requires different compiler options than the SPE core. This file has 170the same format as ``preload.cmake``, but instead details the hardware of the 171NS core that is **not** running the main TF-M secure code. 172 173install.cmake 174^^^^^^^^^^^^^ 175 176This optional cmake file is required only if additional files need to be 177installed for the platform. 178 179Flash layout header file 180------------------------ 181Target must provide a header file, called ``flash_layout.h``, which defines the 182information explained in the follow subsections. The defines must be named 183as they are in the subsections. 184 185BL2 bootloader 186^^^^^^^^^^^^^^ 187The BL2 bootloader requires the following definitions: 188 189- ``FLASH_BASE_ADDRESS`` - Defines the first valid address in the flash. 190- ``FLASH_AREA_BL2_OFFSET`` - Defines the offset from the flash base address 191 where the BL2 - MCUBOOT area starts. 192- ``FLASH_AREA_BL2_SIZE`` - Defines the size of the BL2 area. 193- ``FLASH_AREA_SCRATCH_OFFSET`` - Defines the offset from the flash base 194 address where the scratch area starts, which is used during image swapping. 195- ``FLASH_AREA_SCRATCH_SIZE`` - Defines the size of the scratch area. The 196 minimal size must be as the biggest sector size in the flash. 197- ``FLASH_DEV_NAME`` - Specifies the flash device used by BL2. 198 199The BL2 requires further definitions depending on the number of images, the 200meaning of these macros are also slightly different: 201 202- Required definitions in case of 1 image (S and NS images are concatenated 203 and handled together as one binary blob): 204 205 - ``FLASH_AREA_0_OFFSET`` - Defines the offset from the flash base address 206 where the primary image area starts, which hosts the active firmware 207 image. 208 - ``FLASH_AREA_0_SIZE`` - Defines the size of the primary image area. 209 - ``FLASH_AREA_2_OFFSET`` - Defines the offset from the flash base address 210 where the secondary image area starts, which is a placeholder for new 211 firmware images. 212 - ``FLASH_AREA_2_SIZE`` - Defines the size of the secondary image area. 213 214- Required definitions in case of 2 images (S and NS images are handled and 215 updated separately): 216 217 - ``FLASH_AREA_0_OFFSET`` - Defines the offset from the flash base address 218 where the primary image areas start, which host the active firmware 219 images. It is also the offset of the primary (active) secure image area. 220 - ``FLASH_AREA_0_SIZE`` - Defines the size of the primary secure image area. 221 - ``FLASH_AREA_1_OFFSET`` - Defines the offset from the flash base address 222 where the primary (active) non-secure image area starts. 223 - ``FLASH_AREA_1_SIZE`` - Defines the size of the primary non-secure image 224 area. 225 - ``FLASH_AREA_2_OFFSET`` - Defines the offset from the flash base address 226 where the secondary image areas start, which are placeholders for new 227 firmware images. It is also the offset of the secondary secure image area. 228 - ``FLASH_AREA_2_SIZE`` - Defines the size of the secondary secure image 229 area. 230 - ``FLASH_AREA_3_OFFSET`` - Defines the offset from the flash base address 231 where the secondary non-secure image area starts. 232 - ``FLASH_AREA_3_SIZE`` - Defines the size of the secondary non-secure image 233 area. 234 235The table below shows a fraction of the flash layout in case of 2 and 1 236updatable images with the related flash areas that hold the firmware images: 237 238+-----------------------+--------------------+-----------------------+-----------------------------+ 239| Image number: 2 | Image number: 1 | 240+=======================+====================+=======================+=============================+ 241| **Flash area** | **Content** | **Flash area** | **Content** | 242+-----------------------+--------------------+-----------------------+-----------------------------+ 243| FLASH_AREA_0 | | Secure image | FLASH_AREA_0 | | Secure + Non-secure image | 244| | | primary slot | | | primary slot | 245+-----------------------+--------------------+-----------------------+ + 246| FLASH_AREA_1 | | Non-secure image | | | 247| | | primary slot | | | 248+-----------------------+--------------------+-----------------------+-----------------------------+ 249| FLASH_AREA_2 | | Secure image | FLASH_AREA_2 | | Secure + Non-secure image | 250| | | secondary slot | | | secondary slot | 251+-----------------------+--------------------+-----------------------+ + 252| FLASH_AREA_3 | | Non-secure image | | | 253| | | secondary slot | | | 254+-----------------------+--------------------+-----------------------+-----------------------------+ 255| FLASH_AREA_SCRATCH | Scratch area | FLASH_AREA_SCRATCH | Scratch area | 256+-----------------------+--------------------+-----------------------+-----------------------------+ 257 258- ``IMAGE_EXECUTABLE_RAM_START`` - Defines the start of the region to which 259 images are allowed to be loaded. Only used if ``MCUBOOT_UPGRADE_STRATEGY`` is 260 configured to be ``RAM_LOAD``. 261 262- ``IMAGE_EXECUTABLE_RAM_SIZE`` - Defines the size of the region to which images 263 are allowed to be loaded. Only used if ``MCUBOOT_UPGRADE_STRATEGY`` is 264 configured to be ``RAM_LOAD``. 265 266Assemble tool 267^^^^^^^^^^^^^ 268The ``assemble.py`` tool is used to concatenate secure and non-secure binary 269to a single binary blob. It requires the following definitions: 270 271- ``SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob base 272 address, where the secure image starts. 273- ``SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the secure image area. 274- ``NON_SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob 275 base address, where the non-secure image starts. 276- ``NON_SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the non-secure 277 image area. 278 279Image tool 280^^^^^^^^^^^^^ 281The ``imgtool.py`` tool is used to handle the tasks related to signing the 282binary. It requires the following definition: 283 284- ``S_IMAGE_LOAD_ADDRESS`` - Defines the address to where the Secure (or 285 combined Secure and Non-secure) image is loaded and is executed from. Only 286 used if ``MCUBOOT_UPGRADE_STRATEGY`` is configured to be ``RAM_LOAD``. 287 288- ``NS_IMAGE_LOAD_ADDRESS`` - Defines the address to where the Non-secure image 289 is loaded and is executed from. Only used if ``MCUBOOT_UPGRADE_STRATEGY`` is 290 configured to be ``RAM_LOAD`` and ``MCUBOOT_IMAGE_NUMBER`` is greater than 1. 291 292*************************************** 293Expose target support for HW components 294*************************************** 295Services may require HW components to be supported by the target to enable some 296features (e.g. PS service with rollback protection, etc). The following 297definitions need to be set in the .cmake file if the target has the following 298HW components: 299 300- ``TARGET_NV_COUNTERS_ENABLE`` - Specifies that the target has non-volatile 301 (NV) counters. 302 303-------------- 304 305*Copyright (c) 2017-2022, Arm Limited. All rights reserved.* 306*Copyright (c) 2020-2022 Cypress Semiconductor Corporation (an Infineon company) 307or an affiliate of Cypress Semiconductor Corporation. All rights reserved.* 308
