1##################
2Build instructions
3##################
4
5Please make sure you have all required software installed as explained in the
6:doc:`TF-M getting started </getting_started/tfm_getting_started>`.
7The additional building materials you can find in the following links:
8
9.. toctree::
10    :maxdepth: 1
11
12    Run TF-M examples <run_tfm_examples_on_arm_platforms>
13    Building the documentation <documentation_generation>
14    IAR toolchain <tfm_build_instruction_iar>
15
16****************
17TF-M build steps
18****************
19TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
20build environment. The instructions are below.
21
22Cmake version ``3.15.0`` or higher is required.
23
24.. _Getting the source-code:
25
26Getting the source-code
27=======================
28.. code-block:: bash
29
30    cd <base folder>
31    git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
32
33To simplify documentation commands, the new created repository under
34``trusted-firmware-m`` would be referenced as ``<TF-M base folder>`` and
35its parent, the ``<base folder>``. Dependency management is now handled by
36cmake. If you wish to alter this behaviour, see
37:ref:`building/tfm_build_instruction:Manual dependency management`
38
39.. Note::
40
41 - For building with Armclang compiler version 6.10.0+, please follow the note
42   in :doc:`TF-M getting started </getting_started/tfm_getting_started>`.
43 - For building with the IAR toolchain, please see the notes in
44   :doc:`IAR software requirements <tfm_build_instruction_iar>`
45
46Basic configuration
47===================
48
49TF-M has many options for configuration and fine-tuning. Please check the
50:ref:`tf-m_configuration` section for details. The **base** configuration
51will be build by default with only essential modules SPM and platform hence
52a platform must be selected via ``TFM_PLATFORM`` options, it can be:
53
54 - A relative path under ``<TF-M_root>/platform/ext/target``,
55   for example ``arm/mps2/an521``.
56 - An absolute path of target platform, mainly used for out-of-tree platform
57   build.
58 - A target platform name that is supported under
59   <TF-M_root>/platform/ext/target, for example ``an521``.
60
61Build type
62----------
63
64By default, a MinSizeRel configuration is built. Alternate build types can be
65specified with the ``CMAKE_BUILD_TYPE`` variable. The possible
66types are:
67
68 - ``Debug``
69 - ``RelWithDebInfo``
70 - ``Release``
71 - ``MinSizeRel`` - default
72
73Debug symbols are added by default to all builds, but can be removed
74from ``Release`` and ``MinSizeRel`` builds by setting
75``TFM_DEBUG_SYMBOLS`` to ``OFF``.
76
77``RelWithDebInfo``, ``Release`` and ``MinSizeRel`` all have different
78optimizations turned on and hence will produce smaller, faster code
79than ``Debug``. ``MinSizeRel`` will produce the smallest code, and
80hence is often a good idea on RAM or flash constrained systems.
81
82Other cmake parameters
83----------------------
84
85The full list of default options is in ``config/config_base.cmake`` and
86explained in :ref:`tfm_cmake_configuration`. Several important options
87are listed below.
88
89+----------------------------+------------------------------------------+---------------+
90| Parameter                  | Description                              | Default value |
91+============================+==========================================+===============+
92| BL2                        | Build level 2 secure bootloader.         | ON            |
93+----------------------------+------------------------------------------+---------------+
94| NS                         | Build NS app. Required for test code.    | ON            |
95+----------------------------+------------------------------------------+---------------+
96| PROJECT_CONFIG_HEADER_FILE | User defined header file for TF-M config |               |
97+----------------------------+------------------------------------------+---------------+
98| TFM_ISOLATION_LEVEL        | Set TFM isolation level.                 | 1             |
99+----------------------------+------------------------------------------+---------------+
100| TFM_PROFILE                | Set TFM profile.                         |               |
101+----------------------------+------------------------------------------+---------------+
102| TEST_S                     | Build secure regression tests.           | OFF           |
103+----------------------------+------------------------------------------+---------------+
104| TEST_NS                    | Build non-secure regression tests.       | OFF           |
105+----------------------------+------------------------------------------+---------------+
106| TEST_PSA_API               | Build PSA API TESTS for the given        |               |
107|                            | suite. Takes a PSA api ``SUITE`` as an   |               |
108|                            | argument (``CRYPTO`` etc).               |               |
109+----------------------------+------------------------------------------+---------------+
110
111Project Config Header File
112--------------------------
113
114CMake variable ``PROJECT_CONFIG_HEADER_FILE`` is set by users with the full path of the
115configuration header file, which is used to fine-tune component options. The detailed reference
116for project config header file is in :ref:`Header_configuration`.
117
118.. Note::
119
120    It is recommended to clean up build folder before re-build if config header file is updated.
121    CMake is unable to automatically recognize the dependency when the header file is defined as a macro.
122
123TF-M Profiles
124-------------
125
126TF-M Profiles are implemented as a single cmake configuration file, under the
127``config/profile`` directory. A good understanding can be gained quickly by
128looking at the Profile configuration files, but the ultimate reference for
129Profiles is in :ref:`tf-m_profiles`.
130
131*******************
132TF-M build examples
133*******************
134
135Example: building TF-M for AN521 platform using GCC:
136====================================================
137.. code-block:: bash
138
139    cd <TF-M base folder>
140    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521
141    cmake --build cmake_build -- install
142
143Alternately using traditional cmake syntax
144
145.. code-block:: bash
146
147    cd <TF-M base folder>
148    mkdir cmake_build
149    cd cmake_build
150    cmake .. -DTFM_PLATFORM=arm/mps2/an521
151    make install
152
153.. Note::
154
155    It is recommended to build each different build configuration in a separate
156    build directory.
157
158The default build uses Unix Makefiles. The ``-G`` option can be used to change
159this. The default build uses the GNU ARM toolchain and creates a Release build.
160These options can be overridden using the ``TFM_TOOLCHAIN_FILE`` and
161``CMAKE_BUILD_TYPE`` parameters, as shown below
162
163.. code-block:: bash
164
165    cd <TF-M base folder>
166    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -GNinja -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DCMAKE_BUILD_TYPE=Debug
167    cmake --build cmake_build -- install
168
169Regression Tests for the AN521 target platform
170==============================================
171
172Regression tests can be build by using the TEST_S and TEST_NS settings. Either
173can be used in isolation or both can be used to enable both suites. All tests
174for all enabled partitions are run, along with IPC and Multicore tests if those
175features are enabled.
176
177.. code-block:: bash
178
179    cd <TF-M base folder>
180    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
181    cmake --build cmake_build -- install
182
183Alternately using traditional cmake syntax
184
185.. code-block:: bash
186
187    cd <TF-M base folder>
188    mkdir cmake_build
189    cd cmake_build
190    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
191    make install
192
193Build for PSA API tests
194=======================
195The build system provides support for building and integrating the PSA API tests
196from https://github.com/ARM-software/psa-arch-tests. PSA API tests are
197controlled using the TEST_PSA_API variable. Enabling both regression tests and
198PSA API tests simultaneously is **not** supported.
199
200The value of the TEST_PSA_API variable is the suite to be run.
201
202.. code-block:: bash
203
204    -DTEST_PSA_API=INTERNAL_TRUSTED_STORAGE
205    -DTEST_PSA_API=PROTECTED_STORAGE
206    -DTEST_PSA_API=STORAGE
207    -DTEST_PSA_API=CRYPTO
208    -DTEST_PSA_API=INITIAL_ATTESTATION
209
210Respectively for the corresponding service. For example, to enable the PSA API
211tests for the Crypto service:
212
213.. code-block:: bash
214
215    cd <TF-M base folder>
216    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
217    cmake --build cmake_build -- install
218
219Alternately using traditional cmake syntax
220
221.. code-block:: bash
222
223    cd <TF-M base folder>
224    mkdir cmake_build
225    cd cmake_build
226    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
227    make install
228
229Location of build artifacts
230===========================
231
232All build artifacts are provided in the ``<build_dir>/bin`` directory. It is
233**not** required to run ``make install`` to generate artifacts in this location.
234
235
236For the purposes of maintaining compatibility with the legacy cmake build
237system, they are also provided in
238``<build_dir>/install/outputs/<target_platform>/``. In order to generate the
239artifacts in this location ``make install`` must be run.
240
241****************************
242Manual dependency management
243****************************
244
245The TF-M build system will by default fetch all dependencies with appropriate
246versions and store them inside the build tree. In this case, the build tree
247location is ``<build_dir>/lib/ext``, and the extra libraries can be cleaned by
248deleting that directory.
249
250If you have local copies already, and wish to avoid having the libraries
251downloaded every time the build directory is deleted, then the following
252variables can be set to the path to the root directory of the local repo. This
253will disable the automatic downloading for that dependency.
254
255+----------------+---------------------+-----------------------------------------------------+
256| Dependency     | Cmake variable      | Git repo URL                                        |
257+================+=====================+=====================================================+
258| Mbed Crypto    | MBEDCRYPTO_PATH     | https://github.com/ARMmbed/mbedtls                  |
259+----------------+---------------------+-----------------------------------------------------+
260| tf-m-tests     | TFM_TEST_REPO_PATH  | https://git.trustedfirmware.org/TF-M/tf-m-tests.git |
261+----------------+---------------------+-----------------------------------------------------+
262| MCUboot        | MCUBOOT_PATH        | https://github.com/mcu-tools/mcuboot                |
263+----------------+---------------------+-----------------------------------------------------+
264| psa-arch-tests | PSA_ARCH_TESTS_PATH | https://github.com/ARM-software/psa-arch-tests      |
265+----------------+---------------------+-----------------------------------------------------+
266
267For required versions of the dependencies, refer to ``config/config_base.cmake``.
268
269.. Note::
270 - Some patches are required to the mbedtls repo to allow building it as part of
271   TF-M. While these patches are being upstreamed they are stored in
272   ``lib/ext/mbedcrypo``. In order to use a local copy of Mbed Crypto it is
273   required to apply all patch files in this directory.
274
275.. Note::
276 - CMSIS 5 is provided by the TF-M tests repo. If you wish to use a different
277   source for CMSIS 5, it can be configured using CMSIS_5_PATH.
278
279TF-M Tests
280==========
281
282Dependency auto downloading is used by default.
283The TF-M build system downloads the tf-m-tests repo with a fixed version
284specified by ``TFM_TEST_REPO_VERSION`` in
285:file:`lib/ext/tf-m-tests/repo_config_base.cmake`.
286The version can be a release tag or a commit hash.
287
288Developers who want a different version of tf-m-tests can override
289``TFM_TEST_REPO_PATH`` to a local copy with the desired version.
290
291As the test repo is part of the TF-M project and coupled with TF-M repo,
292the version should be updated when there are dependency changes between the TF-M
293repo and the test repo and when there is a complete change merged in test repo.
294
295A complete change is one or more patches that are for the same purpose, for
296example a new test suite or enhancements on the test cases.
297Patches in one change can be merge individually provided they do not break
298anything or cause any regressions.
299But the version in the TF-M gets updated only when all the patches are merged.
300
301Example: building TF-M for AN521 platform with local Mbed Crypto
302================================================================
303
304Prepare Mbed Crypto repository
305------------------------------
306
307This is only required to be done once. For dependencies that do not have any
308``.patch`` files in their ``lib/ext`` directory the only required step is
309cloning the repo and checking out the correct branch.
310
311.. code-block:: bash
312
313    cd <Mbed Crypto base folder>
314    git clone https://github.com/ARMmbed/mbedtls
315    cd mbedtls
316    git checkout <MBEDCRYPTO_VERSION from config_base.cmake>
317    git apply <TF-M base folder>/trusted-firmware-m/lib/ext/mbedcrypo/*.patch
318
319.. Note::
320 - <Mbed Crypto base folder> does not need to have any fixed posisition related
321   to the TF-M repo.
322
323Build TF-M
324----------
325
326With new cmake syntax
327
328.. code-block:: bash
329
330    cd <TF-M base folder>
331    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
332    cmake --build cmake_build -- install
333
334Alternately using traditional cmake syntax
335
336.. code-block:: bash
337
338    cd <TF-M base folder>
339    mkdir cmake_build
340    cd cmake_build
341    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
342    make install
343
344--------------
345
346*Copyright (c) 2017-2023, Arm Limited. All rights reserved.*
347*Copyright (c) 2022, Cypress Semiconductor Corporation. All rights reserved.*
348