aboutsummaryrefslogtreecommitdiff
path: root/docs/technical_references/instructions/tfm_build_instruction.rst
blob: 49bdeffc2b93aee0ee50c7fb3c6c0e4be807360b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
##################
Build instructions
##################
Please make sure you have all required software installed as explained in the
:doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`.

****************
TF-M build steps
****************
TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
build environment. The instructions are below.

Cmake version ``3.15.0`` or higher is required.

.. _Getting the source-code:

Getting the source-code
=======================
.. code-block:: bash

    cd <base folder>
    git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git

To simplify documentation commands, the new created repository under
``trusted-firmware-m`` would be referenced as ``<TF-M base folder>`` and
its parent, the ``<base folder>``. Dependency management is now handled by
cmake. If you wish to alter this behaviour, see
:ref:`docs/technical_references/instructions/tfm_build_instruction:Manual
dependency management`

.. Note::

 - For building with Armclang compiler version 6.10.0+, please follow the note
   in :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`.
 - For building with the IAR toolchain, please see the notes in
   :doc:`IAR software requirements <tfm_build_instruction_iar>`

.. _tfm_cmake_configuration:

Cmake configuration
===================

All configuration options are provided by cmake variables, and their default
values, with docstrings, can be found in ``config/config_default.cmake``.

Configuration is provided in multiple stages. Each stage will not override any
config that has already been set at any of the prior stages.

   1. Command-line variable settings are applied.
   2. If the ``TFM_EXTRA_CONFIG_PATH`` variable has been set, that file is
      loaded.
   3. If TEST_PSA_TEST is set, then PSA API test related config is applied from
      ``config/tests/config_test_psa_api.cmake``.
   4. If it exists, CMAKE_BUILD_TYPE specific config is applied from
      ``config/build_type/<build_type>.cmake``.
   5. Target specific config from ``platform/ext/target/<target_platform>/config.cmake``
      is applied.
   6. If CRYPTO_HW_ACCELERATOR is set, then a config specific to the
      accelerator type is applied if it exists.
   7. If it exists, TFM Profile specific config is applied from
      ``config/profile/<tfm_profile>.cmake``.
   8. ``config/config_default.cmake`` is loaded.

.. Warning::
    This means that command-line settings are not applied when they conflict
    with required platform settings. If it is required to override platform
    settings (this is not usually a good idea) then TFM_EXTRA_CONFIG_PATH should be
    used.

Required cmake parameters for building TF-M
-------------------------------------------

+----------------------+-------------------------------------------------------+
| Parameter            | Description                                           |
+======================+=======================================================+
| TFM_PLATFORM         | The target platform as a path from the base directory |
|                      | ``/platform/ext/target``, or as an absolute path.     |
+----------------------+-------------------------------------------------------+

By default release configuration builds. Alternate build types can be controlled
by the CMAKE_BUILD_TYPE variable.

Build type
----------

Build type is controlled by the ``CMAKE_BUILD_TYPE`` variable. The possible
types are:

 - ``Debug``
 - ``Relwithdebinfo``
 - ``Release``
 - ``Minsizerel``

``Release`` is default.

Both ``Debug`` and ``Relwithdebinfo`` will include debug symbols in the output
files. ``Relwithdebinfo``, ``Release`` and ``Minsizerel`` have optimization
turned on and hence will produce smaller, faster code. ``Minsizerel`` will
produce the smallest code, and hence is often a good idea on RAM or flash
constrained systems.

Other cmake parameters
----------------------

The full list of default options is in ``config/config_default.cmake``. Several
important options are listed below.


+---------------------+----------------------------------------+---------------+
| Parameter           | Description                            | Default value |
+=====================+========================================+===============+
| BL2                 | Build level 2 secure bootloader.       | ON            |
+---------------------+----------------------------------------+---------------+
| NS                  | Build NS app. Required for test code.  | ON            |
+---------------------+----------------------------------------+---------------+
| TFM_PSA_API         | Use PSA api (IPC mode) instead of      | OFF           |
|                     | secure library mode.                   |               |
+---------------------+----------------------------------------+---------------+
| TFM_ISOLATION_LEVEL | Set TFM isolation level.               | 1             |
+---------------------+----------------------------------------+---------------+
| TFM_PROFILE         | Set TFM profile.                       |               |
+---------------------+----------------------------------------+---------------+
| TEST_S              | Build secure regression tests.         | OFF           |
+---------------------+----------------------------------------+---------------+
| TEST_NS             | Build non-secure regression tests.     | OFF           |
+---------------------+----------------------------------------+---------------+
| TEST_PSA_API        | Build PSA API TESTS for the given      |               |
|                     | suite. Takes a PSA api ``SUITE`` as an |               |
|                     | argument (``CRYPTO`` etc).             |               |
+---------------------+----------------------------------------+---------------+

Regression test configuration
-----------------------------

Regression test configuration is controlled entirely by the ``TEST_S`` and
``TEST_NS`` cmake variables.

If regression testing is enabled, it will then enable all tests for the enabled
secure partitions. If IPC mode is enabled via ``TFM_PSA_API`` the IPC tests will
be enabled. QCBOR and T_COSE tests are linked to the Initial Attestation
partition, as they are only used there. Multicore tests will be enabled if
``TFM_MULTI_CORE_TOPOLOGY`` is enabled.

Some cryptographic tests can be enabled and disabled. This is done to prevent
false failures from being reported when a smaller Mbed Crypto config is being
used which does not support all features.

+-----------------------------+-------------------------------------+---------------+
| Parameter                   | Description                         | Default value |
+=============================+=====================================+===============+
| TFM_CRYPTO_TEST_ALG_CBC     | Test CBC cryptography mode          | ON            |
+-----------------------------+-------------------------------------+---------------+
| TFM_CRYPTO_TEST_ALG_CCM     | Test CCM cryptography mode          | ON            |
+-----------------------------+-------------------------------------+---------------+
| TFM_CRYPTO_TEST_ALG_CFB     | Test CFB cryptography mode          | ON            |
+-----------------------------+-------------------------------------+---------------+
| TFM_CRYPTO_TEST_ALG_CTR     | Test CTR cryptography mode          | ON            |
+-----------------------------+-------------------------------------+---------------+
| TFM_CRYPTO_TEST_ALG_GCM     | Test GCM cryptography mode          | ON            |
+-----------------------------+-------------------------------------+---------------+
| TFM_CRYPTO_TEST_ALG_SHA_512 | Test SHA-512 cryptography algorithm | ON            |
+-----------------------------+-------------------------------------+---------------+
| TFM_CRYPTO_TEST_HKDF        | Test SHA-512 cryptography algorithm | ON            |
+-----------------------------+-------------------------------------+---------------+

TF-M Profiles
-------------

TF-M Profiles are implemented as a single cmake configuration file, under the
``config/profile`` directory. A good understanding can be gained quickly by
looking at the Profile configuration files, but the ultimate reference for
Profiles are the design documents in the ``docs/technical_references/profiles/``
directory.

PSA test configuration
----------------------

PSA tests are configured by using the ``TEST_PSA_API`` cmake variable. The
variable should be set to the name of the test suite that is desired. It is
_not_ supported to set both ``TEST_PSA_API`` and ``TEST_S`` or ``TEST_NS``.

The Functional API tests are:
 - ``CRYPTO``
 - ``INITIAL_ATTESTATION``
 - ``STORAGE`` (INTERNAL_TRUSTED_STORAGE and PROTECTED_STORAGE)
 - ``INTERNAL_TRUSTED_STORAGE``
 - ``PROTECTED_STORAGE``

The Firmware Framework test suites are:
 - ``IPC``

Note that these map directly to the ``SUITE`` cmake variable used in the
psa-arch-tests documentation.

.. _Migration from legacy buildsystem:

Migration from legacy buildsystem
---------------------------------

The previous (legacy) cmake buildsystem made use of separate configuration
files, where now build options are controlled by variables. For ease of
transition, a table below is provided that maps the legacy files to the current
variables, in the format of cmake command line parameters.

+------------------------------------------+---------------------------------------+
| File                                     | Cmake command line                    |
+==========================================+=======================================+
| ConfigDefault.cmake                      | <No options>                          |
+------------------------------------------+---------------------------------------+
| ConfigCoreIPC.cmake                      | -DTFM_PSA_API=ON                      |
+------------------------------------------+---------------------------------------+
| ConfigCoreIPCTfmLevel2.cmake             | -DTFM_PSA_API=ON                      |
|                                          | -DTFM_ISOLATION_LEVEL=2               |
+------------------------------------------+---------------------------------------+
| ConfigDefaultProfileS.cmake              | -DTFM_PROFILE=profile_small           |
+------------------------------------------+---------------------------------------+
| ConfigDefaultProfileM.cmake              | -DTFM_PROFILE=profile_medium          |
+------------------------------------------+---------------------------------------+
| ConfigRegression.cmake                   | -DTEST_NS=ON -DTEST_S=ON              |
+------------------------------------------+---------------------------------------+
| ConfigRegressionIPC.cmake                | -DTEST_NS=ON -DTEST_S=ON              |
|                                          | -DTFM_PSA_API=ON                      |
+------------------------------------------+---------------------------------------+
| ConfigRegressionIPCTfmLevel2.cmake       | -DTEST_NS=ON -DTEST_S=ON              |
|                                          | -DTFM_PSA_API=ON                      |
|                                          | -DTFM_ISOLATION_LEVEL=2               |
+------------------------------------------+---------------------------------------+
| ConfigRegressionProfileS.cmake           | -DTFM_PROFILE=profile_small           |
|                                          | -DTEST_NS=ON -DTEST_S=ON              |
+------------------------------------------+---------------------------------------+
| ConfigRegressionProfileM.cmake           | -DTFM_PROFILE=profile_medium          |
|                                          | -DTEST_NS=ON -DTEST_S=ON              |
+------------------------------------------+---------------------------------------+
| ConfigPsaApiTest.cmake                   | -DTEST_PSA_API=<test_suite>           |
+------------------------------------------+---------------------------------------+
| ConfigPsaApiTestIPC.cmake                | -DTEST_PSA_API=<test_suite>           |
|                                          | -DTFM_PSA_API=ON                      |
+------------------------------------------+---------------------------------------+
| ConfigPsaApiTestIPCTfmLevel2.cmake       | -DTEST_PSA_API=<test_suite>           |
|                                          | -DTFM_PSA_API=ON                      |
|                                          | -DTFM_ISOLATION_LEVEL=2               |
+------------------------------------------+---------------------------------------+
| ConfigDefaultProfileM.cmake              | -DTFM_PROFILE=profile_medium          |
| + profile_m_config_ext_ps_disabled.cmake | -DTFM_PARTITION_PROTECTED_STORAGE=OFF |
+------------------------------------------+---------------------------------------+

There has also been some changes to the PSA manifest file generation. The files
are now generated into a seperate tree in the ``<tfm build dir>/generated``
directory. Therefore they have been removed from the source tree. Any changes
should be made only to the template files.

The api for the ``tools/tfm_parse_manifest_list.py`` script has also changed
slightly. It is no longer required to be run manually as it is run as part of
cmake.

*******************
TF-M build examples
*******************

.. Note::
   By default, CMAKE_BUILD_TYPE is set to Release, for debug support change
   this to Debug. See below for an example.

Example: building TF-M for AN521 platform using GCC:
====================================================
.. code-block:: bash

    cd <TF-M base folder>
    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug
    cmake --build cmake_build -- install

Alternately using traditional cmake syntax

.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_build
    cd cmake_build
    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
    make install

.. Note::
   Unix Makefiles is the default generator. Ninja is also supported by setting
   -GNinja

.. Note::

    It is recommended to build each different build configuration in a separate
    build directory.

As seen above, the toolchain can be set using the -DTFM_TOOLCHAIN_FILE parameter. Without
it, the build command takes the GNU ARM toolchain as default, so there is no need
to explicitly include it. In case other toolchain is required, i.e. ARM Clang, simply
specify in the command line

.. code-block:: bash

    cd <TF-M base folder>
    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DTEST_S=ON -DTEST_NS=ON
    cmake --build cmake_build -- install

Regression Tests for the AN521 target platform
==============================================

Regression tests can be build by using the TEST_S and TEST_NS settings. Either
can be used in isolation or both can be used to enable both suites. All tests
for all enabled partitions are run, along with IPC and Multicore tests if those
features are enabled.

.. code-block:: bash

    cd <TF-M base folder>
    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
    cmake --build cmake_build -- install

Alternately using traditional cmake syntax

.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_build
    cd cmake_build
    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
    make install

Build for PSA Functional API compliance tests
=============================================
The build system provides support for building and integrating the PSA API tests
from https://github.com/ARM-software/psa-arch-tests. PSA API tests are
controlled using the TEST_PSA_API variable. Enabling both regression tests and
PSA API tests simultaneously is **not** supported.

The value of the TEST_PSA_API variable is the suite to be run.

.. code-block:: bash

    -DTEST_PSA_API=INTERNAL_TRUSTED_STORAGE
    -DTEST_PSA_API=PROTECTED_STORAGE
    -DTEST_PSA_API=STORAGE
    -DTEST_PSA_API=CRYPTO
    -DTEST_PSA_API=INITIAL_ATTESTATION

Respectively for the corresponding service. For example, to enable the PSA API
tests for the Crypto service:

.. code-block:: bash

    cd <TF-M base folder>
    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
    cmake --build cmake_build -- install

Alternately using traditional cmake syntax

.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_build
    cd cmake_build
    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
    make install

Build for PSA FF (IPC) compliance tests
=======================================

The build system provides support for building and integrating the PSA FF
compliance test. This support is controlled by the TEST_PSA_API variable:

.. code-block:: bash

    -DTEST_PSA_API=IPC

.. code-block:: bash

    cd <TF-M base folder>
    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=IPC -DTFM_PSA_API=ON
    cmake --build cmake_build -- install

Alternately using traditional cmake syntax

.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_build
    cd cmake_build
    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=IPC -DTFM_PSA_API=ON
    make install

Location of build artifacts
===========================

All build artifacts are provided in the ``<build_dir>/bin`` directory. It is
**not** required to run ``make install`` to generate artifacts in this location.


For the purposes of maintaining compatibility with the legacy cmake build
system, they are also provided in
``<build_dir>/install/outputs/<target_platform>/``. In order to generate the
artifacts in this location ``make install`` must be run.

****************************
Manual dependency management
****************************

The TF-M build system will by default fetch all dependencies with appropriate
versions and store them inside the build tree. In this case, the build tree
location is ``<build_dir>/lib/ext``, and the extra libraries can be cleaned by
deleting that directory.

If you have local copies already, and wish to avoid having the libraries
downloaded every time the build directory is deleted, then the following
variables can be set to the path to the root directory of the local repo. This
will disable the automatic downloading for that dependency.

+----------------+---------------------+-----------------------------------------------------+
| Dependency     | Cmake variable      | Git repo URL                                        |
+================+=====================+=====================================================+
| Mbed Crypto    | MBEDCRYPTO_PATH     | https://github.com/ARMmbed/mbedtls                  |
+----------------+---------------------+-----------------------------------------------------+
| tf-m-tests     | TFM_TEST_REPO_PATH  | https://git.trustedfirmware.org/TF-M/tf-m-tests.git |
+----------------+---------------------+-----------------------------------------------------+
| MCUboot        | MCUBOOT_PATH        | https://github.com/mcu-tools/mcuboot                |
+----------------+---------------------+-----------------------------------------------------+
| psa-arch-tests | PSA_ARCH_TESTS_PATH | https://github.com/ARM-software/psa-arch-tests      |
+----------------+---------------------+-----------------------------------------------------+

For required versions of the dependencies, refer to ``config/config_default.cmake``.

.. Note::
 - Some patches are required to the mbedtls repo to allow building it as part of
   TF-M. While these patches are being upstreamed they are stored in
   ``lib/ext/mbedcrypo``. In order to use a local copy of Mbed Crypto it is
   required to apply all patch files in this directory.

.. Note::
 - CMSIS 5 is provided by the TF-M tests repo. If you wish to use a different
   source for CMSIS 5, it can be configured using CMSIS_5_PATH.

TF-M Tests
==========

Dependency auto downloading is used by default.
The TF-M build system downloads the tf-m-tests repo with a fixed version
specified by ``TFM_TEST_REPO_VERSION`` in ``config/config_default.cmake``.
The version can be a release tag or a commit hash.

Developers who want a different version of tf-m-tests can override
``TFM_TEST_REPO_PATH`` to a local copy with the desired version.

As the test repo is part of the TF-M project and coupled with TF-M repo a lot,
The version should be updated when there are dependency changes between the TF-M
repo and the test repo and when there is a complete change merged in test repo.

A complete change is one or more patches that are for the same purpose, for
example a new test suite or enhancements on the test cases.
Patches in one change can be merge individually provided they do not break
anything or cause any regressions.
But the version in the TF-M gets updated only when all the patches are merged.

Example: building TF-M for AN521 platform with local Mbed Crypto
================================================================

Prepare Mbed Crypto repository
------------------------------

This is only required to be done once. For dependencies that do not have any
``.patch`` files in their ``lib/ext`` directory the only required step is
cloning the repo and checking out the correct branch.

.. code-block:: bash

    cd <Mbed Crypto base folder>
    git clone https://github.com/ARMmbed/mbedtls
    cd mbedtls
    git checkout <MBEDCRYPTO_VERSION from config_default.cmake>
    git apply <TF-M base folder>/trusted-firmware-m/lib/ext/mbedcrypo/*.patch

.. Note::
 - <Mbed Crypto base folder> does not need to have any fixed posisition related
   to the TF-M repo.

Build TF-M
----------

With new cmake syntax

.. code-block:: bash

    cd <TF-M base folder>
    cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
    cmake --build cmake_build -- install

Alternately using traditional cmake syntax

.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_build
    cd cmake_build
    cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
    make install

--------------

*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*