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| TFM_ISOLATION_LEVEL | Set TFM isolation level.               | 1             |
97+---------------------+----------------------------------------+---------------+
98| TFM_PROFILE         | Set TFM profile.                       |               |
99+---------------------+----------------------------------------+---------------+
100| TEST_S              | Build secure regression tests.         | OFF           |
101+---------------------+----------------------------------------+---------------+
102| TEST_NS             | Build non-secure regression tests.     | OFF           |
103+---------------------+----------------------------------------+---------------+
104| TEST_PSA_API        | Build PSA API TESTS for the given      |               |
105|                     | suite. Takes a PSA api ``SUITE`` as an |               |
106|                     | argument (``CRYPTO`` etc).             |               |
107+---------------------+----------------------------------------+---------------+
108
109TF-M Profiles
110-------------
111
112TF-M Profiles are implemented as a single cmake configuration file, under the
113``config/profile`` directory. A good understanding can be gained quickly by
114looking at the Profile configuration files, but the ultimate reference for
115Profiles is in :ref:`tf-m_profiles`.
116
117*******************
118TF-M build examples
119*******************
120
121Example: building TF-M for AN521 platform using GCC:
122====================================================
123.. code-block:: bash
124
125    cd <TF-M base folder>
126    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521
127    cmake --build cmake_build -- install
128
129Alternately using traditional cmake syntax
130
131.. code-block:: bash
132
133    cd <TF-M base folder>
134    mkdir cmake_build
135    cd cmake_build
136    cmake .. -DTFM_PLATFORM=arm/mps2/an521
137    make install
138
139.. Note::
140
141    It is recommended to build each different build configuration in a separate
142    build directory.
143
144The default build uses Unix Makefiles. The ``-G`` option can be used to change
145this. The default build uses the GNU ARM toolchain and creates a Release build.
146These options can be overridden using the ``TFM_TOOLCHAIN_FILE`` and
147``CMAKE_BUILD_TYPE`` parameters, as shown below
148
149.. code-block:: bash
150
151    cd <TF-M base folder>
152    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -GNinja -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DCMAKE_BUILD_TYPE=Debug
153    cmake --build cmake_build -- install
154
155Regression Tests for the AN521 target platform
156==============================================
157
158Regression tests can be build by using the TEST_S and TEST_NS settings. Either
159can be used in isolation or both can be used to enable both suites. All tests
160for all enabled partitions are run, along with IPC and Multicore tests if those
161features are enabled.
162
163.. code-block:: bash
164
165    cd <TF-M base folder>
166    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
167    cmake --build cmake_build -- install
168
169Alternately using traditional cmake syntax
170
171.. code-block:: bash
172
173    cd <TF-M base folder>
174    mkdir cmake_build
175    cd cmake_build
176    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
177    make install
178
179Build for PSA API tests
180=======================
181The build system provides support for building and integrating the PSA API tests
182from https://github.com/ARM-software/psa-arch-tests. PSA API tests are
183controlled using the TEST_PSA_API variable. Enabling both regression tests and
184PSA API tests simultaneously is **not** supported.
185
186The value of the TEST_PSA_API variable is the suite to be run.
187
188.. code-block:: bash
189
190    -DTEST_PSA_API=INTERNAL_TRUSTED_STORAGE
191    -DTEST_PSA_API=PROTECTED_STORAGE
192    -DTEST_PSA_API=STORAGE
193    -DTEST_PSA_API=CRYPTO
194    -DTEST_PSA_API=INITIAL_ATTESTATION
195
196Respectively for the corresponding service. For example, to enable the PSA API
197tests for the Crypto service:
198
199.. code-block:: bash
200
201    cd <TF-M base folder>
202    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
203    cmake --build cmake_build -- install
204
205Alternately using traditional cmake syntax
206
207.. code-block:: bash
208
209    cd <TF-M base folder>
210    mkdir cmake_build
211    cd cmake_build
212    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
213    make install
214
215Location of build artifacts
216===========================
217
218All build artifacts are provided in the ``<build_dir>/bin`` directory. It is
219**not** required to run ``make install`` to generate artifacts in this location.
220
221
222For the purposes of maintaining compatibility with the legacy cmake build
223system, they are also provided in
224``<build_dir>/install/outputs/<target_platform>/``. In order to generate the
225artifacts in this location ``make install`` must be run.
226
227****************************
228Manual dependency management
229****************************
230
231The TF-M build system will by default fetch all dependencies with appropriate
232versions and store them inside the build tree. In this case, the build tree
233location is ``<build_dir>/lib/ext``, and the extra libraries can be cleaned by
234deleting that directory.
235
236If you have local copies already, and wish to avoid having the libraries
237downloaded every time the build directory is deleted, then the following
238variables can be set to the path to the root directory of the local repo. This
239will disable the automatic downloading for that dependency.
240
241+----------------+---------------------+-----------------------------------------------------+
242| Dependency     | Cmake variable      | Git repo URL                                        |
243+================+=====================+=====================================================+
244| Mbed Crypto    | MBEDCRYPTO_PATH     | https://github.com/ARMmbed/mbedtls                  |
245+----------------+---------------------+-----------------------------------------------------+
246| tf-m-tests     | TFM_TEST_REPO_PATH  | https://git.trustedfirmware.org/TF-M/tf-m-tests.git |
247+----------------+---------------------+-----------------------------------------------------+
248| MCUboot        | MCUBOOT_PATH        | https://github.com/mcu-tools/mcuboot                |
249+----------------+---------------------+-----------------------------------------------------+
250| psa-arch-tests | PSA_ARCH_TESTS_PATH | https://github.com/ARM-software/psa-arch-tests      |
251+----------------+---------------------+-----------------------------------------------------+
252
253For required versions of the dependencies, refer to ``config/config_base.cmake``.
254
255.. Note::
256 - Some patches are required to the mbedtls repo to allow building it as part of
257   TF-M. While these patches are being upstreamed they are stored in
258   ``lib/ext/mbedcrypo``. In order to use a local copy of Mbed Crypto it is
259   required to apply all patch files in this directory.
260
261.. Note::
262 - CMSIS 5 is provided by the TF-M tests repo. If you wish to use a different
263   source for CMSIS 5, it can be configured using CMSIS_5_PATH.
264
265TF-M Tests
266==========
267
268Dependency auto downloading is used by default.
269The TF-M build system downloads the tf-m-tests repo with a fixed version
270specified by ``TFM_TEST_REPO_VERSION`` in
271:file:`lib/ext/tf-m-tests/repo_config_base.cmake`.
272The version can be a release tag or a commit hash.
273
274Developers who want a different version of tf-m-tests can override
275``TFM_TEST_REPO_PATH`` to a local copy with the desired version.
276
277As the test repo is part of the TF-M project and coupled with TF-M repo,
278the version should be updated when there are dependency changes between the TF-M
279repo and the test repo and when there is a complete change merged in test repo.
280
281A complete change is one or more patches that are for the same purpose, for
282example a new test suite or enhancements on the test cases.
283Patches in one change can be merge individually provided they do not break
284anything or cause any regressions.
285But the version in the TF-M gets updated only when all the patches are merged.
286
287Example: building TF-M for AN521 platform with local Mbed Crypto
288================================================================
289
290Prepare Mbed Crypto repository
291------------------------------
292
293This is only required to be done once. For dependencies that do not have any
294``.patch`` files in their ``lib/ext`` directory the only required step is
295cloning the repo and checking out the correct branch.
296
297.. code-block:: bash
298
299    cd <Mbed Crypto base folder>
300    git clone https://github.com/ARMmbed/mbedtls
301    cd mbedtls
302    git checkout <MBEDCRYPTO_VERSION from config_base.cmake>
303    git apply <TF-M base folder>/trusted-firmware-m/lib/ext/mbedcrypo/*.patch
304
305.. Note::
306 - <Mbed Crypto base folder> does not need to have any fixed posisition related
307   to the TF-M repo.
308
309Build TF-M
310----------
311
312With new cmake syntax
313
314.. code-block:: bash
315
316    cd <TF-M base folder>
317    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
318    cmake --build cmake_build -- install
319
320Alternately using traditional cmake syntax
321
322.. code-block:: bash
323
324    cd <TF-M base folder>
325    mkdir cmake_build
326    cd cmake_build
327    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
328    make install
329
330--------------
331
332*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
333*Copyright (c) 2022, Cypress Semiconductor Corporation. All rights reserved.*
334