1.. _tfm_build_system:
2
3TF-M Build System
4#################
5
6When building a valid ``_ns`` board target, TF-M will be built in the
7background, and linked with the Zephyr non-secure application. No knowledge
8of TF-M's build system is required in most cases, and the following will
9build a TF-M and Zephyr image pair, and run it in qemu with no additional
10steps required:
11
12   .. code-block:: bash
13
14     $ west build -p auto -b mps2_an521_ns samples/tfm_integration/psa_protected_storage/ -t run
15
16The outputs and certain key steps in this build process are described here,
17however, since you will need to understand and interact with the outputs, and
18deal with signing the secure and non-secure images before deploying them.
19
20Images Created by the TF-M Build
21********************************
22
23The TF-M build system creates the following executable files:
24
25* tfm_s - TF-M secure firmware
26* tfm_ns - TF-M non-secure app (only used by regression tests).
27* bl2 - TF-M MCUboot, if enabled
28
29For each of these, it creates .bin, .hex, .elf, and .axf files.
30
31The TF-M build system also creates signed variants of tfm_s and tfm_ns, and a
32file which combines them:
33
34* tfm_s_signed
35* tfm_ns_signed
36* tfm_s_ns_signed
37
38For each of these, only .bin files are created.
39
40The TF-M non-secure app is discarded in favor of Zephyr non-secure app except
41when running the TF-M regression test suite.
42
43The Zephyr build system usually signs both tfm_s and the Zephyr non-secure app itself.
44See below for details.
45
46The 'tfm' target contains properties for all these paths.
47For example, the following will resolve to ``<path>/tfm_s.hex``:
48
49   .. code-block::
50
51      $<TARGET_PROPERTY:tfm,TFM_S_HEX_FILE>
52
53See the top level CMakeLists.txt file in the tfm module for an overview of all
54the properties.
55
56Signing Images
57**************
58
59When :kconfig:option:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader
60(BL2) and firmware images must be signed with a private key. The firmware image
61is validated by the bootloader during updates using the corresponding public
62key, which is stored inside the secure bootloader firmware image.
63
64By default, ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure
65images, and ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign
66non-secure images. These default .pem keys can (and **should**) be overridden
67using the :kconfig:option:`CONFIG_TFM_KEY_FILE_S` and
68:kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config flags.
69
70To satisfy `PSA Certified Level 1`_ requirements, **You MUST replace
71the default .pem file with a new key pair!**
72
73To generate a new public/private key pair, run the following commands:
74
75   .. code-block:: bash
76
77     $ imgtool keygen -k root-rsa-3072_s.pem -t rsa-3072
78     $ imgtool keygen -k root-rsa-3072_ns.pem -t rsa-3072
79
80You can then place the new .pem files in an alternate location, such as your
81Zephyr application folder, and reference them in the ``prj.conf`` file via the
82:kconfig:option:`CONFIG_TFM_KEY_FILE_S` and :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config
83flags.
84
85   .. warning::
86
87     Be sure to keep your private key file in a safe, reliable location! If you
88     lose this key file, you will be unable to sign any future firmware images,
89     and it will no longer be possible to update your devices in the field!
90
91After the built-in signing script has run, it creates a ``tfm_merged.hex``
92file that contains all three binaries: bl2, tfm_s, and the zephyr app. This
93hex file can then be flashed to your development board or run in QEMU.
94
95.. _PSA Certified Level 1:
96  https://www.psacertified.org/security-certification/psa-certified-level-1/
97
98Custom CMake arguments
99======================
100
101When building a Zephyr application with TF-M it might be necessary to control
102the CMake arguments passed to the TF-M build.
103
104Zephyr TF-M build offers several Kconfig options for controlling the build, but
105doesn't cover every CMake argument supported by the TF-M build system.
106
107The ``TFM_CMAKE_OPTIONS`` property on the ``zephyr_property_target`` can be used
108to pass custom CMake arguments to the TF-M build system.
109
110To pass the CMake argument ``-DFOO=bar`` to the TF-M build system, place the
111following CMake snippet in your CMakeLists.txt file.
112
113   .. code-block:: cmake
114
115     set_property(TARGET zephyr_property_target
116                  APPEND PROPERTY TFM_CMAKE_OPTIONS
117                  -DFOO=bar
118     )
119
120.. note::
121   The ``TFM_CMAKE_OPTIONS`` is a list so it is possible to append multiple
122   options. Also CMake generator expressions are supported, such as
123   ``$<1:-DFOO=bar>``
124
125Since ``TFM_CMAKE_OPTIONS`` is a list argument it will be expanded before it is
126passed to the TF-M build system.
127Options that have list arguments must therefore be properly escaped to avoid
128being expanded as a list.
129
130   .. code-block:: cmake
131
132     set_property(TARGET zephyr_property_target
133                  APPEND PROPERTY TFM_CMAKE_OPTIONS
134                  -DFOO="bar\\\;baz"
135     )
136
137Footprint and Memory Usage
138**************************
139
140The build system offers targets to view and analyse RAM and ROM usage in generated images.
141The tools run on the final images and give information about size of symbols and code being used in both RAM and ROM.
142For more information on these tools look here: :ref:`footprint_tools`
143
144Use the ``tfm_ram_report`` to get the RAM report for TF-M secure firmware (tfm_s).
145
146.. zephyr-app-commands::
147    :tool: all
148    :app: samples/hello_world
149    :board: mps2_an521_ns
150    :goals: tfm_ram_report
151
152Use the ``tfm_rom_report`` to get the ROM report for TF-M secure firmware (tfm_s).
153
154.. zephyr-app-commands::
155    :tool: all
156    :app: samples/hello_world
157    :board: mps2_an521_ns
158    :goals: tfm_rom_report
159
160Use the ``bl2_ram_report`` to get the RAM report for TF-M MCUboot, if enabled.
161
162.. zephyr-app-commands::
163    :tool: all
164    :app: samples/hello_world
165    :board: mps2_an521_ns
166    :goals: bl2_ram_report
167
168Use the ``bl2_rom_report`` to get the ROM report for TF-M MCUboot, if enabled.
169
170.. zephyr-app-commands::
171    :tool: all
172    :app: samples/hello_world
173    :board: mps2_an521_ns
174    :goals: bl2_rom_report
175