1Trusted Firmware-M Integration
2##############################
3
4The Trusted Firmware-M (TF-M) section contains information about the
5integration between TF-M and Zephyr RTOS. Use this information to help
6understand how to integrate TF-M with Zephyr for Cortex-M platforms and make
7use of its secure run-time services in Zephyr applications.
8
9Board Definitions
10*****************
11
12TF-M will be built for the secure processing environment along with Zephyr if
13the :kconfig:option:`CONFIG_BUILD_WITH_TFM` flag is set to ``y``.
14
15Generally, this value should never be set at the application level, however,
16and all config flags required for TF-M should be set in a board variant with
17the ``_ns`` suffix.
18
19This board variant must define an appropriate flash, SRAM and peripheral
20configuration that takes into account the initialisation process in the secure
21processing environment. :kconfig:option:`CONFIG_TFM_BOARD` must also be set via
22`modules/trusted-firmware-m/Kconfig.tfm <https://github.com/zephyrproject-rtos/zephyr/blob/main/modules/trusted-firmware-m/Kconfig.tfm>`__
23to the board name that TF-M expects for this target, so that it knows which
24target to build for the secure processing environment.
25
26Example: ``mps2/an521/cpu0/ns``
27===============================
28
29The ``mps2/an521/cpu0`` board target is a dual-core Arm Cortex-M33 evaluation board that generates
30a secure Zephyr binary.
31
32The optional ``mps2/an521/cpu0/ns`` board target, however, sets these additional
33kconfig flags that indicate that Zephyr should be built as a
34non-secure image, linked with TF-M as an external project, and optionally the
35secure bootloader:
36
37* :kconfig:option:`CONFIG_TRUSTED_EXECUTION_NONSECURE` ``y``
38* :kconfig:option:`CONFIG_ARM_TRUSTZONE_M` ``y``
39
40Comparing the :zephyr_file:`boards/arm/mps2/mps2_an521_cpu0.dts` and
41:zephyr_file:`boards/arm/mps2/mps2_an521_cpu0_ns.dts` files,
42we can see that the ``ns`` version defines offsets in flash and SRAM memory, which leave
43the required space for TF-M and the secure bootloader:
44
45::
46
47    reserved-memory {
48		#address-cells = <1>;
49		#size-cells = <1>;
50		ranges;
51
52		/* The memory regions defined below must match what the TF-M
53		 * project has defined for that board - a single image boot is
54		 * assumed. Please see the memory layout in:
55		 * https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/platform/ext/target/mps2/an521/partition/flash_layout.h
56		 */
57
58		code: memory@100000 {
59			reg = <0x00100000 DT_SIZE_K(512)>;
60		};
61
62		ram: memory@28100000 {
63			reg = <0x28100000 DT_SIZE_M(1)>;
64		};
65	};
66
67This reserves 1 MB of code memory and 1 MB of RAM for secure boot and TF-M,
68such that our non-secure Zephyr application code will start at 0x10000, with
69RAM at 0x28100000. 512 KB code memory is available for the NS zephyr image,
70along with 1 MB of RAM.
71
72This matches the flash memory layout we see in ``flash_layout.h`` in TF-M:
73
74::
75
76    * 0x0000_0000 BL2 - MCUBoot (0.5 MB)
77    * 0x0008_0000 Secure image     primary slot (0.5 MB)
78    * 0x0010_0000 Non-secure image primary slot (0.5 MB)
79    * 0x0018_0000 Secure image     secondary slot (0.5 MB)
80    * 0x0020_0000 Non-secure image secondary slot (0.5 MB)
81    * 0x0028_0000 Scratch area (0.5 MB)
82    * 0x0030_0000 Protected Storage Area (20 KB)
83    * 0x0030_5000 Internal Trusted Storage Area (16 KB)
84    * 0x0030_9000 NV counters area (4 KB)
85    * 0x0030_A000 Unused (984 KB)
86
87``mps2/an521`` will be passed in to Tf-M as the board target, specified via
88:kconfig:option:`CONFIG_TFM_BOARD`.
89