Skip to content

Commit 0ba963a

Browse files
Alexander ZilberkantMichael Schwarcz
Alexander Zilberkant
authored and
Michael Schwarcz
committed
Adding TF-M integration guide
1 parent 60c6740 commit 0ba963a

File tree

1 file changed

+119
-0
lines changed

1 file changed

+119
-0
lines changed

‎components/TARGET_PSA/TARGET_TFM/tf-m-integration.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# TF-M integration to Mbed-OS
2+
This document is an initial draft for TF-M for Mbed-OS porting guide .
3+
4+
## Audience
5+
This guide is intended for developers wishing to port Mbed-OS with TF-M used as a secure kernel for ARMv8-M targets.
6+
7+
Prior knowledge with both TF-M & Mbed-OS concepts is assumed.
8+
9+
## Build system concepts:
10+
11+
Mbed-OS build system is based on [Mbed-CLI](https://github.com/ARMmbed/mbed-cli).
12+
Mbed-CLI build system performs lookup for source and header files within project directory and adds them all to a build. All folders will be scanned for sources except for:
13+
- folders starting with `TARGET_*`
14+
- folders starting with `COMPONENT_*`
15+
- folders starting with `FEATURE_*`
16+
- folders starting with `TESTS_*` (not true for `mbed test` builds)
17+
- files and folders listed in `.mbedignore`
18+
19+
The ignored folders listed above can be explicitly added to a compilation by adding following keys to a target description in `targets.json`:
20+
- adding `extra_labels_add`, `inherits` and `sub_target` for adding `TARGET_*`
21+
- adding `components_add` for adding `COMPONENT_*`
22+
- `features_add` for adding `FEATURE_*`
23+
24+
TF-M is built as bare-metal in a secure target, in order to build a secure target with TF-M as its' kernel need to add `--app-config <MBED-OS-ROOT>/tools/psa/tfm/mbed_app.json` to the build command of the secure target.
25+
26+
## Build hooks
27+
28+
Mbed-OS testing tools are designed to work with a single image (`.bin` or `.hex`).
29+
When building mbed-os for ARMv8-M targets two images are created. One for normal world(NW) and one for TrustZone(TZ).
30+
Mbed-OS build system provides `post_binary_hook` that allows executing arbitrary Python script for merging NW and TZ images. Typically `post_binary_hook` is added to NW target and assumes TZ target images as a prerequisite.
31+
32+
## Porting ARMv8-M targets
33+
34+
Typically firmware for ARMv8-M targets consist of 2 or more images: normal world and TrustZone image. More images can be present in case boot loaders are used.
35+
Two images must be built and linked separately. TrustZone image must be built first.
36+
37+
There may be code and/or header files sharing between the two targets.
38+
Nested folder layout typically provides more easy code reuse between two targets:
39+
Example:
40+
41+
```txt
42+
└── tragets
43+
└── TARGET_<VENDOR>
44+
└── TARGET_<BOARD>
45+
├── common_files <-- files shared between NW and TZ images
46+
├── TARGET_<BOARD>_NS
47+
│   └── normal_world_files <-- files only to be included for NW build
48+
└── TARGET_<BOARD>_S
49+
└── trustzone_files <-- files only to be included for TZ build
50+
```
51+
52+
The target should be represented in a following way in `target.json` (`MUSCA_A1` is taken for example and should be substituted):
53+
```json
54+
...
55+
"ARM_MUSCA_A1": {
56+
"public": false,
57+
"inherits": ["Target"],
58+
"supported_toolchains": ["ARMC6", "GCC_ARM"],
59+
"default_toolchain": "ARMC6",
60+
"extra_labels": ["ARM_SSG", "MUSCA_A1"],
61+
},
62+
"ARM_MUSCA_A1_NS": {
63+
"inherits": ["NSPE_Target", "ARM_MUSCA_A1"],
64+
"core": "Cortex-M33-NS",
65+
"device_has_add": ["INTERRUPTIN", "LPTICKER", "SERIAL", "SLEEP", "USTICKER"],
66+
"macros": [
67+
"MBED_TZ_DEFAULT_ACCESS=1",
68+
"MBED_FAULT_HANDLER_DISABLED",
69+
"TFM_PSA_API",
70+
"MBEDTLS_PSA_CRYPTO_C"
71+
],
72+
"extra_labels_add": ["MUSCA_A1_NS", "PSA", "TFM"],
73+
"post_binary_hook": {"function": "ArmMuscaA1Code.binary_hook"}
74+
},
75+
"ARM_MUSCA_A1_S": {
76+
"inherits": ["SPE_Target", "ARM_MUSCA_A1"],
77+
"core": "Cortex-M33",
78+
"device_has_add": ["FLASH"],
79+
"macros": [
80+
"MBED_FAULT_HANDLER_DISABLED",
81+
"MBED_MPU_CUSTOM",
82+
"BYPASS_NVSTORE_CHECK",
83+
"TFM_LVL=1",
84+
"TFM_PSA_API",
85+
"MBEDTLS_PSA_CRYPTO_SPM",
86+
"MBEDTLS_PSA_CRYPTO_C",
87+
"MBEDTLS_ENTROPY_NV_SEED",
88+
"MBEDTLS_PLATFORM_NV_SEED_READ_MACRO=mbed_default_seed_read",
89+
"MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO=mbed_default_seed_write"
90+
],
91+
"components_add": ["FLASHIAP"],
92+
"extra_labels_add": ["MUSCA_A1_S", "PSA", "TFM"]
93+
},
94+
```
95+
96+
Example details:
97+
- Secure target:
98+
- `"device_has_add": ["FLASH"]` and `"components_add": ["FLASHIAP"]` for enabling storage stack. Required by PSA Internal storage service.
99+
- `"extra_labels_add": ["PSA", "TFM"]` are required to add PSA services and TF-M SPM implementation sources to a compilation
100+
- all the macros from the example above are required
101+
- must inherit from `SPE_Target`
102+
- Nonsecure target:
103+
- must inherit from `NSPE_Target`
104+
- `"extra_labels_add": ["PSA", "TFM"]` are required to add PSA services and TF-M SPM implementation sources to a compilation
105+
- all the macros from the example above are required
106+
- `post_binary_hook` is used to combine secure and non-secure images
107+
108+
### HAL
109+
For porting Mbed-OS & TF-M both Mbed-OS and TF-M HAL layers should be created.
110+
111+
#### Mbed-OS HAL:
112+
Follow instructions for [Mbed-OS HAL porting](https://os.mbed.com/docs/mbed-os/v5.11/porting/porting-hal-modules.html)
113+
114+
#### TF-M:
115+
Mbed-OS contains customized TF-M version. TF-M services reference implementation was replaced by Mbed-OS version. Thus TF-M has different HAL layer comparing to vanilla [TF-M reference implementation](https://git.trustedfirmware.org/trusted-firmware-m.git/about/).
116+
117+
The porting layer consists of:
118+
- All functions listed in: `components/TARGET_PSA/TARGET_TFM/COMPONENT_SPE/platform/include/tfm_spm_hal.h`
119+
- Flash API `mbed-os/hal/flash_api.h` implementation is required for TZ image. It is used by PSA Internal trusted storage implementation.

0 commit comments

Comments
 (0)