1.. zephyr:code-sample:: tfm_ipc
2   :name: TF-M IPC
3
4   Implement communication between the secure and non-secure images using IPC.
5
6Overview
7********
8
9This is a simple TF-M integration example that can be used with an ARMv8-M
10supported board.
11
12It uses **IPC Mode** for communication, where TF-M API calls are made to the
13secure image via an IPC mechanism, as opposed to **Library Mode**, where the
14IPC mechanism is bypassed in favor of direct calls.
15
16Zephyr uses Trusted Firmware (TF-M) Platform Security Architecture (PSA) APIs
17to run this sample in a secure configuration, with Zephyr itself running in a
18non-secure configuration.
19
20The sample prints test info to the console either as a single-thread or
21multi-thread application.
22
23The sample reboots after 5 seconds to demonstrate rebooting with TF-M.
24The sys_reboot call is routed to TF-M, since the nonsecure app is not allowed
25to perform the reboot directly.
26
27Building and Running
28********************
29
30This project outputs test status and info to the console. It can be built and
31executed on MPS2+ AN521 and ST Nucleo L552ZE Q.
32
33On MPS2+ AN521:
34===============
35
36#. Build Zephyr with a non-secure configuration (``-DBOARD=mps2/an521/cpu0/ns``).
37
38   .. code-block:: bash
39
40      cd $ZEPHYR_ROOT/samples/tfm_integration/tfm_ipc/
41      mkdir build
42      cd build
43      cmake -DBOARD=mps2/an521/cpu0/ns ..
44      make
45
46You can also use west as follows:
47
48   .. code-block:: bash
49
50      $ west build -p -b mps2/an521/cpu0/ns zephyr/samples/tfm_integration/tfm_ipc
51
52
53#. Copy application binary files (mcuboot.bin and tfm_sign.bin) to ``<MPS2 device name>/SOFTWARE/``.
54#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``. Edit the ``AN521/images.txt`` file as follows:
55
56   .. code-block:: bash
57
58      TITLE: Versatile Express Images Configuration File
59
60      [IMAGES]
61      TOTALIMAGES: 2 ;Number of Images (Max: 32)
62
63      IMAGE0ADDRESS: 0x10000000
64      IMAGE0FILE: \SOFTWARE\mcuboot.bin  ; BL2 bootloader
65
66      IMAGE1ADDRESS: 0x10080000
67      IMAGE1FILE: \SOFTWARE\tfm_sign.bin ; TF-M with application binary blob
68
69#. Reset MPS2+ board.
70
71If you get the following error when running cmake:
72
73   .. code-block:: bash
74
75      CMake Error at cmake/Common/FindGNUARM.cmake:121 (message):
76      arm-none-eabi-gcc can not be found.  Either put arm-none-eabi-gcc on the
77      PATH or set GNUARM_PATH properly.
78
79You may need to edit the ``CMakeLists.txt`` file in the ``tfm_ipc`` project
80folder to update the ``-DGNUARM_PATH=/opt/toolchain/arm-none-eabi`` path.
81
82On QEMU:
83========
84
85The MPS2+ AN521 target (``mps2/an521/cpu0/ns``), which is based on a
86dual core ARM Cortex-M33 setup, also allows you to run TF-M tests using QEMU if
87you don't have access to a supported ARMv8-M development board.
88
89As part of the normal build process above, a binary is also produced that can
90be run via ``qemu-system-arm``. The binary can be executed as follows:
91
92   .. code-block:: bash
93
94      qemu-system-arm -M mps2-an521 -device loader,file=build/zephyr/tfm_merged.hex -serial stdio
95
96You can also run the binary as part of the ``west`` build process by appending
97the ``-t run`` flag to the end of your build command, or in the case of
98ninja or make, adding the ``run`` commands:
99
100   .. code-block:: bash
101
102      $ west build -b mps2/an521/cpu0/ns zephyr/samples/tfm_integration/tfm_ipc -t run
103
104Or, post build:
105
106   .. code-block:: bash
107
108      $ ninja run
109
110On ST Nucleo L552ZE Q or STM32L562E-DK Discovery:
111=================================================
112
113This sample was tested on Ubuntu 18.04 with Zephyr SDK 0.11.3.
114
115Build Zephyr with a non-secure configuration:
116
117   Example, for building non-secure configuration for Nucleo L552ZE Q
118
119   .. code-block:: bash
120
121      $ west build -b nucleo_l552ze_q/stm32l552xx/ns samples/tfm_integration/tfm_ipc/
122
123   Example, for building non-secure configuration for STM32L562E-DK Discovery
124
125   .. code-block:: bash
126
127      $ west build -b stm32l562e_dk/stm32l562xx/ns samples/tfm_integration/tfm_ipc/
128
129The script to initialize the device is available in the ``build/tfm`` folder:
130
131  - ``regression.sh``: Sets platform option bytes config and erase platform.
132
133Run them in the following order to flash the board:
134
135   .. code-block:: bash
136
137      $ ./build/tfm/api_ns/regression.sh
138      $ west flash
139
140 .. note::
141      Note that ``arm-none-eabi-gcc`` should be available in the PATH variable and that
142      ``STM32_Programmer_CLI`` is required to run ``regression.sh``
143      (see https://www.st.com/en/development-tools/stm32cubeprog.html). If you are still having
144      trouble running these scripts, check the Programming and Debugging section of the
145      :zephyr:board:`nucleo_l552ze_q` or :zephyr:board:`stm32l562e_dk` documentation.
146
147On LPCxpresso55S69:
148===================
149
150Build Zephyr with a non-secure configuration:
151
152   .. code-block:: bash
153
154      $ west build -p -b lpcxpresso55s69_ns samples/tfm_integration/tfm_ipc/ --
155
156Make sure your board is set up with :ref:`lpclink2-jlink-onboard-debug-probe`,
157since this isn't the debug interface boards ship with from the factory;
158
159Next we need to manually flash the resulting image (``tfm_merged.bin``) with a
160J-Link as follows:
161
162   .. code-block:: console
163
164      JLinkExe -device lpc55s69 -if swd -speed 2000 -autoconnect 1
165      J-Link>r
166      J-Link>erase
167      J-Link>loadfile build/zephyr/tfm_merged.bin
168
169Resetting the board and erasing it will unlock the board, this is useful in case
170it's in an unknown state and can't be flashed.
171
172We need to reset the board manually after flashing the image to run this code.
173
174On nRF5340 and nRF9160:
175=======================
176
177Build Zephyr with a non-secure configuration
178(``-DBOARD=nrf5340dk/nrf5340/cpuapp/ns`` or ``-DBOARD=nrf9160dk/nrf9160/ns``).
179
180   Example, for nRF9160, using ``cmake`` and ``ninja``
181
182   .. code-block:: bash
183
184      cd <ZEPHYR_ROOT>/samples/tfm_integration/tfm_ipc/
185      rm -rf build
186      mkdir build && cd build
187      cmake -GNinja -DBOARD=nrf9160dk/nrf9160/ns ..
188
189If building with BL2 (MCUboot bootloader) enabled, manually flash
190the MCUboot bootloader image binary (``bl2.hex``).
191
192   Example, using ``nrfjprog`` on nRF9160:
193
194   .. code-block:: bash
195
196      nrfjprog -f NRF91 --program tfm/bin/bl2.hex --sectorerase
197
198Finally, flash the concatenated TF-M + Zephyr binary.
199
200   Example, for nRF9160, using ``cmake`` and ``ninja``
201
202   .. code-block:: bash
203
204      ninja flash
205
206On BL5340:
207==========
208
209Build Zephyr with a non-secure configuration
210(``-DBOARD=bl5340_dvk/nrf5340/cpuapp/ns``).
211
212   Example using ``cmake`` and ``ninja``
213
214   .. code-block:: bash
215
216      cd <ZEPHYR_ROOT>/samples/tfm_integration/tfm_ipc/
217      rm -rf build
218      mkdir build && cd build
219      cmake -GNinja -DBOARD=bl5340_dvk/nrf5340/cpuapp/ns ..
220
221Flash the concatenated TF-M + Zephyr binary.
222
223   Example using ``west``
224
225   .. code-block:: bash
226
227      west flash --hex-file zephyr/tfm_merged.hex
228
229Sample Output
230=============
231
232.. code-block:: console
233
234   [INF] Starting bootloader
235   [INF] Beginning BL2 provisioning
236   [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
237   [INF] Image index: 1, Swap type: none
238   [INF] Image index: 0, Swap type: none
239   [INF] Bootloader chainload address offset: 0x80000
240   [INF] Jumping to the first image slot
241   [INF] Beginning TF-M provisioning
242   [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
243   [WRN] This device was provisioned with dummy keys. This device is NOT SECURE
244   [Sec Thread] Secure image initializing!
245   Booting TF-M v2.0.0
246   Creating an empty ITS flash layout.
247   Creating an empty PS flash layout.
248   [INF][Crypto] Provisioning entropy seed... complete.
249   Timer with period zero, disabling
250   *** Booting Zephyr OS build v3.6.0 ***
251   TF-M IPC on (.*)
252   The version of the PSA Framework API is 257.
253   The PSA Crypto service minor version is 1.
254   Generating 256 bytes of random data:
255   [...]
256
257.. _TF-M build instruction:
258   https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/+/refs/heads/main/docs/building/tfm_build_instruction.rst
259
260.. _TF-M secure boot:
261   https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/+/refs/heads/main/docs/design_docs/booting/tfm_secure_boot.rst
262