1# Target of this port
2
3This port adds the support that FreeRTOS applications can call the secure
4services in Trusted Firmware M(TF-M) through Platform Security Architecture
5(PSA) API based on the ARM Cortex-M23, Cortex-M33, Cortex-M55 and Cortex-M85
6platform.
7
8The Platform Security Architecture (PSA) makes it quicker, easier and cheaper
9to design security into a device from the ground up. PSA is made up of four key
10stages: analyze, architect, implement, and certify. See [PSA Resource Page](https://www.arm.com/architecture/security-features/platform-security).
11
12TF-M is an open source project. It provides a reference implementation of PSA
13for Arm M-profile architecture. Please get the details from this [link](https://www.trustedfirmware.org/projects/tf-m/).
14
15# Derivation of the source code
16
17* `os_wrapper_freertos.c`
18  The implementation of APIs which are defined in `/interface/include/os_wrapper/mutex.h`
19  in trusted-firmware-m (tag: TF-Mv2.0.0). The implementation is based on
20  FreeRTOS mutex type semaphore.
21
22# Usage notes
23
24To build a project based on this port:
25* Step 1: build the secure image. Please follow the **Build the Secure Side** section for details.
26* Step 2: build the nonsecure image. Please follow the **Build the Non-Secure Side** for details.
27
28## Build the Secure Side
29
30### Get the TF-M source code
31
32See the [link](https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/) to get the source code. This port is supported by TF-M version **tag: TF-Mv2.0.0**.
33
34### Build TF-M
35
36Please refer to this [link](https://trustedfirmware-m.readthedocs.io/en/latest/getting_started/) to build the secure side.
37_**Note:** `TFM_NS_MANAGE_NSID` must be configured as "OFF" when building TF-M_.
38
39## Build the Non-Secure Side
40
41Please copy all the files in `freertos_kernel/portable/GCC/ARM_CM[23|33|55|85]_NTZ` into the `freertos_kernel/portable/ThirdParty/GCC/ARM_TFM` folder before using this port. Note that TrustZone is enabled in this port. The TF-M runs in the Secure Side.
42
43Please call the API `tfm_ns_interface_init()` which is defined in `/interface/src/os_wrapper/tfm_ns_interface_rtos.c` by trusted-firmware-m (tag: TF-Mv2.0.0) at the very beginning of your application. Otherwise, it will always fail when calling a TF-M service in the Nonsecure Side.
44
45### Configuration in FreeRTOS kernel
46
47* `configRUN_FREERTOS_SECURE_ONLY`
48This macro should be configured as 0. In this port, TF-M runs in the Secure Side while FreeRTOS
49Kernel runs in the Non-Secure Side.
50
51* `configENABLE_FPU`
52The setting of this macro is decided by the setting in Secure Side which is platform-specific.
53If the Secure Side enables Non-Secure access to FPU, then this macro can be configured as 0 or 1. Otherwise, this macro can only be configured as 0.
54Please note that Cortex-M23 does not support FPU.
55Please refer to [TF-M documentation](https://tf-m-user-guide.trustedfirmware.org/integration_guide/tfm_fpu_support.html) for FPU usage on the Non-Secure side.
56
57* `configENABLE_MVE`
58The setting of this macro is decided by the setting in Secure Side which is platform-specific.
59If the Secure Side enables Non-Secure access to MVE, then this macro can be configured as 0 or 1. Otherwise, this macro can only be configured as 0.
60Please note that only Cortex-M55 and Cortex-M85 support MVE.
61Please refer to [TF-M documentation](https://tf-m-user-guide.trustedfirmware.org/integration_guide/tfm_fpu_support.html) for MVE usage on the Non-Secure side.
62
63* `configENABLE_TRUSTZONE`
64This macro should be configured as 0 because TF-M doesn't use the secure context management function of FreeRTOS. New secure context management might be introduced when TF-M supports multiple secure context.
65
66
67### Integrate TF-M Non-Secure interface with FreeRTOS project
68
69To enable calling TF-M services by the Non-Secure Side, the files below should be included in the FreeRTOS project and built together.
70* files in `trusted-firmware-m/build/api_ns/interface/src`
71  These files contain the implementation of PSA Functional Developer APIs which can be called by Non-Secure Side directly and PSA Firmware Framework APIs in the IPC model. These files should be taken as part of the Non-Secure source code.
72* files in `trusted-firmware-m/build/api_ns/interface/include`
73  These files are the necessary header files to call TF-M services.
74* `trusted-firmware-m/build/api_ns/interface/lib/s_veneers.o`
75  This object file contains all the Non-Secure callable functions exported by
76  TF-M and it should be linked when generating the Non-Secure image.
77
78
79
80*Copyright (c) 2020-2024, Arm Limited. All rights reserved.*
81