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