Skip to content

Commit 08bf7fa

Browse files
author
Donatien Garnier
authored
Merge pull request ARMmbed#1416 from LDong-Arm/tf-m-v1.2-update
Update PSA porting guide
2 parents 6a19134 + 4bf6847 commit 08bf7fa

File tree

1 file changed

+45
-222
lines changed

1 file changed

+45
-222
lines changed

‎docs/porting/security/psa_targets_in_mbed-os.md‎

Lines changed: 45 additions & 222 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Porting PSA targets
22

3-
This document describes the process of adding new PSA targets to Mbed OS, focusing on target configurations, build and validation. Mbed OS relies on [TF-M](https://git.trustedfirmware.org/trusted-firmware-m.git/tree/) for its implementation of PSA, so the PSA target you are adding to Mbed OS **must** already be supported by TF-M.
3+
This document describes the process of adding new PSA targets to Mbed OS, focusing on target configurations, build and validation.
44

55
Before reading this document, please read [porting a custom board](../porting/porting-a-custom-board.html) and [porting targets](../porting/porting-the-hal-apis.html), which provide step-by-step instructions to porting a new target to Mbed OS.
66

@@ -16,7 +16,7 @@ Before reading this document, please read [porting a custom board](../porting/po
1616
To help create PSA targets, we have added a few generic targets to `targets/targets.json`:
1717

1818
* `PSA_Target`: Root level PSA target.
19-
* `PSA_V7_M`: Single v7-M generic PSA target, which doesn't employ hardware isolation between the NSPE and the SPE. PSA secure service emulation enables PSA API compatibility.
19+
* `PSA_V7_M`: Single-core v7-M generic PSA target, which doesn't employ hardware isolation between the NSPE and the SPE, so TF-M is not supported. PSA secure service emulation enables PSA API compatibility.
2020
* `PSA_DUAL_CORE`: Dual-core generic PSA target. A dual-core PSA target has at least two cores that are either Armv7-M or Armv6-M. One core will be used for the SPE and another for the NSPE. Hardware isolation between the cores enables PSA compliance. On dual-core targets, TF-M
2121
runs on the SPE and provides PSA services, and Mbed OS runs on the NSPE.
2222
* `PSA_V8_M`: Armv8-M generic PSA target, which employs hardware to isolate the NSPE from the SPE. TF-M runs on the SPE and provides PSA services, and Mbed OS runs on the NSPE.
@@ -39,20 +39,10 @@ Example of a single-core Armv7-M PSA target's inheritance:
3939
}
4040
```
4141

42-
### Naming convention for dual-core and Armv8-M targets
43-
44-
As explained above, dual-core and Armv8-M PSA targets require only an NSPE target name. For Armv8-M non-PSA targets, you can define both SPE and NSPE target names.
45-
46-
The naming convention is:
47-
48-
- `TargetName`: PSA non-secure target (NSPE).
49-
- `TargetName_NPSA_S`: Non-PSA secure target.
50-
- `TargetName_NPSA`: Non-PSA non-secure target.
51-
52-
### Adding single-core PSA targets
42+
### Adding single-core (non-TF-M) PSA targets
5343

5444
Mbed OS's PSA service emulation provides PSA compatibility for single-core PSA
55-
targets.
45+
targets which do not support TF-M.
5646

5747
The following example shows a PSA-enabled single-core target, `K64F`:
5848

@@ -173,16 +163,20 @@ In this case, you must add the following additional attributes:
173163
]
174164
```
175165

176-
### Adding dual-core PSA targets
166+
### Adding TF-M (dual-core or Armv8-M) PSA targets
177167

178-
A target can be categorized as a dual-core target if it has at least two cores that are either Armv7-M or Armv6-M. On dual-core PSA targets, TF-M runs on the SPE and provides PSA services.
168+
An Mbed OS (NSPE) target that supports TF-M must contain the following attributes (in addition to other target attributes defined in [porting a custom board](../porting/porting-a-custom-board.html) and [porting targets](../porting/porting-the-hal-apis.html)):
179169

180-
An Mbed OS (NSPE) target must contain the following attributes (in addition to other target attributes defined in [porting a custom board](../porting/porting-a-custom-board.html) and [porting targets](../porting/porting-the-hal-apis.html)):
181-
182-
* `inherits`: PSA generic target `PSA_DUAL_CORE`, unless the target has to inherit
170+
* `inherits`: PSA generic target `PSA_DUAL_CORE` or `PSA_V8_M`, unless the target has to inherit
183171
from one of its family targets.
172+
* `extra_labels`: `TARGET_`[label] paths to enable.
173+
* `TFM_LATEST`: If the current version of TF-M (that Mbed OS is integrated with) is supported by the target. The current version is indicated in [mbed-os-tf-m-regression-tests](https://github.com/ARMmbed/mbed-os-tf-m-regression-tests).
174+
* `TFM_V`[major]`_`[minor]: If a legacy release of TF-M is supported by the target.
175+
* `macros_add`: C/C++ macros that are globally set during compilation.
176+
* `BL2`: If the TF-M bootloader is supported by the target.
177+
* `MCUBOOT_IMAGE_NUMBER=2`: If the secure and non-secure images are in two separate bootloader slots.
184178
* `tfm_target_name`: Target name in TF-M.
185-
* `tfm_bootloader_supported`: If TF-M bootloader is supported by the target.
179+
* `tfm_bootloader_supported`: If the TF-M bootloader is supported by the target.
186180

187181
The supported values are `true` and `false`.
188182
* `tfm_supported_toolchains`: Supported TF-M toolchains.
@@ -193,129 +187,36 @@ An Mbed OS (NSPE) target must contain the following attributes (in addition to o
193187
The supported values are `ARMCLANG` and `GNUARM`.
194188
* `tfm_delivery_dir`: The directory to which TF-M binaries will be copied.
195189
* `TFM_OUTPUT_EXT`: Optional attribute that indicates the output extension of the TF-M secure binary.
190+
* `post_binary_hook`:
191+
* `function`: The target's post binary hook ([class].[method]) in `tools/targets/__init__.py` for image signing, required if the TF-M bootloader support is supported.
192+
* `secure_image_filename`: The file name of the TF-M secure binary, to be signed by the post binary hook.
196193

197-
The following example shows a PSA enabled dual-core target, `PSoC64`:
194+
**Note**: When `inherits` is used, some of attributes are set by the PSA generic target.
198195

199-
```json
200-
"CY8CKIT_064S2_4343W": {
201-
"inherits": [
202-
"MCU_PSOC6_M4"
203-
],
204-
"features_add": [
205-
"BLE",
206-
"PSA"
207-
],
208-
"components_add": [
209-
"WHD",
210-
"4343W",
211-
"CYW43XXX"
212-
],
213-
"components_remove": [
214-
"QSPIF"
215-
],
216-
"supported_form_factors": [
217-
"ARDUINO"
218-
],
219-
"device_has_remove": [
220-
"ANALOGOUT",
221-
"QSPI"
222-
],
223-
"extra_labels_add": [
224-
"PSOC6_02",
225-
"MXCRYPTO_02",
226-
"CORDIO",
227-
"TFM",
228-
"TFM_DUALCPU"
229-
],
230-
"macros_add": [
231-
"CYB0644ABZI_S2D44",
232-
"CYBSP_WIFI_CAPABLE",
233-
"TFM_MULTI_CORE_MULTI_CLIENT_CALL=1"
234-
],
235-
"detect_code": [
236-
"190A"
237-
],
238-
"post_binary_hook": {
239-
"function": "PSOC6Code.sign_image"
240-
},
241-
"forced_reset_timeout": 5,
242-
"overrides": {
243-
"network-default-interface-type": "WIFI"
244-
},
245-
"program_cycle_s": 10,
246-
"tfm_target_name": "psoc64",
247-
"tfm_bootloader_supported": false,
248-
"tfm_default_toolchain": "GNUARM",
249-
"tfm_supported_toolchains": [
250-
"GNUARM"
251-
],
252-
"tfm_delivery_dir": "TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_064S2_4343W",
253-
"TFM_OUTPUT_EXT": "hex"
254-
}
255-
```
256-
257-
Please note the config options `macros_add`, `extra_labels_add` and `device_has_remove`. To add or remove `macros`, `extra_labels` or target capabilities, a PSA target definition must use
258-
[macros/extra_labels/device_has]`_add` or [macros/extra_labels/device_has]`_remove` (not `macros`, `extra_labels` or `device_has`).
259-
260-
To add or remove a feature, use `feature_`[add/remove].
261-
262-
By default, a TF-M build generates a `bin` file. If the target requires a `hex` file, you need to add the attribute `"TFM_OUTPUT_EXT": "hex"` to the target definition. The build script will convert `bin` to `hex`, then copy the `hex` to `tfm_delivery_dir`.
263-
264-
This dual-core PSA target doesn't inherit from `PSA_DUAL_CORE` because it has to inherit from one of its family targets. Hence, we have added additional attributes:
196+
The following example shows a PSA-enabled Armv8-M PSA target, `ARM_MUSCA_S1`:
265197

266198
```json
267-
"features_add": [
268-
"PSA"
269-
],
270-
"extra_labels_add": [
271-
"TFM",
272-
"TFM_DUALCPU"
273-
]
274-
```
275-
276-
If a dual-core PSA target can inherit from `PSA_DUAL_CORE`, then there is no need to add these additional attributes.
277-
278-
### Adding Armv8-M PSA targets
279-
280-
An Mbed OS (NSPE) target must contain the following attributes (in addition to other target attributes defined in [porting a custom board](../porting/porting-a-custom-board.html)
281-
and [porting targets](../porting/porting-the-hal-apis.html)):
282-
283-
* `inherits`: PSA generic target `PSA_V8_M`, unless the target has to inherit from
284-
one of its family targets.
285-
* `tfm_target_name`: Target name in TF-M.
286-
* `tfm_bootloader_supported`: If TF-M bootloader is supported by the target.
287-
288-
The supported values are `true` and `false`.
289-
* `tfm_supported_toolchains`: Supported TF-M toolchains.
290-
291-
The supported values are `ARMCLANG` and `GNUARM`.
292-
* `tfm_default_toolchain`: Default TF-M toolchain.
293-
294-
The supported values are `ARMCLANG` and `GNUARM`.
295-
296-
* `tfm_delivery_dir`: The directory to which TF-M binary will be copied.
297-
* `TFM_OUTPUT_EXT`: Optional attribute that indicates the output extension of the TF-M secure binary.
298-
299-
The following example shows a PSA-enabled Armv8-M PSA target, `ARM_MUSCA_A1`:
300-
301-
```json
302-
"ARM_MUSCA_A1": {
199+
"ARM_MUSCA_S1": {
303200
"inherits": [
304201
"PSA_V8_M"
305202
],
306203
"default_toolchain": "ARMC6",
307-
"forced_reset_timeout": 7,
204+
"features_add": [
205+
"EXPERIMENTAL_API"
206+
],
207+
"forced_reset_timeout": 20,
308208
"release_versions": [
309209
"5"
310210
],
311211
"core": "Cortex-M33-NS",
312212
"supported_toolchains": [
313213
"ARMC6",
314-
"GCC_ARM",
315-
"IAR"
214+
"GCC_ARM"
316215
],
317216
"device_has_add": [
318217
"INTERRUPTIN",
218+
"I2C",
219+
"I2CSLAVE",
319220
"LPTICKER",
320221
"SERIAL",
321222
"SLEEP",
@@ -325,133 +226,55 @@ The following example shows a PSA-enabled Armv8-M PSA target, `ARM_MUSCA_A1`:
325226
"__STARTUP_CLEAR_BSS",
326227
"MBED_FAULT_HANDLER_DISABLED",
327228
"CMSIS_NVIC_VIRTUAL",
328-
"LPTICKER_DELAY_TICKS=1",
329-
"MBED_MPU_CUSTOM"
229+
"LPTICKER_DELAY_TICKS=3",
230+
"MBED_MPU_CUSTOM",
231+
"BL2",
232+
"MCUBOOT_IMAGE_NUMBER=2"
330233
],
331234
"extra_labels_add": [
332235
"ARM_SSG",
333-
"MUSCA_A1",
334-
"MUSCA_A1_NS"
236+
"MUSCA_S1"
335237
],
336238
"post_binary_hook": {
337-
"function": "ArmMuscaA1Code.binary_hook"
239+
"function": "ArmMuscaS1Code.binary_hook"
338240
},
339241
"secure_image_filename": "tfm_s.bin",
340-
"tfm_target_name": "MUSCA_A",
242+
"tfm_target_name": "musca_s1",
341243
"tfm_bootloader_supported": true,
342244
"tfm_default_toolchain": "ARMCLANG",
343245
"tfm_supported_toolchains": [
344246
"ARMCLANG",
345247
"GNUARM"
346248
],
347-
"tfm_delivery_dir": "TARGET_ARM_SSG/TARGET_MUSCA_A1"
249+
"tfm_delivery_dir": "TARGET_ARM_SSG/TARGET_MUSCA_S1",
250+
"detect_code": [
251+
"5009"
252+
]
348253
}
349254
```
350255

351-
Please note the config options `macros_add`, `extra_labels_add` and `device_has_remove`. To add or remove `macros`, `extra_labels` or target capabilities, a PSA target definition must use
352-
[macros/extra_labels/device_has]`_add` or [macros/extra_labels/device_has]`_remove` (not `macros`, `extra_labels` or `device_has`).
353-
354-
To add or remove a feature, use `feature_`[add/remove].
256+
Please note the config options `features_add`, `macros_add`, `extra_labels_add` and `device_has_add`. To add or remove `features`, `macros`, `extra_labels` or target capabilities, a PSA target definition must use
257+
[features/macros/extra_labels/device_has]`_add` or [features/macros/extra_labels/device_has]`_remove` (not `features`, `macros`, `extra_labels` or `device_has`).
355258

356259
By default, a TF-M build generates a `bin` file. If the target requires a `hex` file, you need to add the attribute `"TFM_OUTPUT_EXT": "hex"` to the target definition. The build script will convert `bin` to `hex`, then copy the `hex` to `tfm_delivery_dir`. You must also update `secure_image_filename` to match the new file extension.
357260

358-
If an Armv8-M PSA target cannot inherit from `PSA_V8_M` because it has to inherit from one of its family targets, you must add the following attributes:
261+
If a PSA target cannot inherit from `PSA_V8_M` or `PSA_DUAL_CORE` because it has to inherit from one of its family targets, you must declare PSA and TF-M attributes manually. For example,
359262

360263
```json
361264
"features_add": [
362265
"PSA"
363266
],
364267
"extra_labels_add": [
365268
"TFM",
269+
"TFM_LATEST",
366270
"TFM_V8M"
367271
]
368272
```
369-
370-
## Enabling PSA at application level
371-
372-
Having an entropy source is crucial for Mbed TLS and PSA. The [entropy source porting document](../porting/entropy-sources.html) discusses why and how to add an entropy source.
373-
374-
If your target doesn't have a True Random Number Generator (TRNG), configure it as a non-PSA target in `targets/targets.json`. In this scenario, if an application wants to use the target as a PSA target, then it is the application's responsibility to provide an entropy source and mark that target as a PSA target at the application level. To enable PSA for a target from an application, use the config option [target_overrides](../reference/configuration.html).
375-
376-
An example of `mbed_app.json`:
377-
378-
```json
379-
"target_overrides": {
380-
"K64F": {
381-
"inherits": ["PSA_V7_M"]
382-
}
383-
}
384-
```
273+
(Please adjust the TF-M version and target architecture accordingly.)
385274

386275
## Build and validation
387276

388-
The Python script `build_tfm.py` automates building TF-M and copying the TF-M binary to the location defined by the target attribute `tfm_delivery_dir`. Another Python script, `build_psa_compliance.py`, automates
389-
building PSA API compliance tests.
390-
391-
The [mbed-os-tf-m-regression-tests repository](https://github.com/ARMmbed/mbed-os-tf-m-regression-tests) contains build scripts, TF-M regression tests and PSA API compliance tests.
392-
393-
### Building TF-M and running regression tests
394-
395-
To build TF-M and regression tests:
396-
397-
1. Clone the [mbed-os-tf-m-regression-tests](https://github.com/ARMmbed/mbed-os-tf-m-regression-tests) repository.
398-
1. Update `mbed-os.lib` to the copy of Mbed OS that contains new target support, including the `targets.json` changes described in this document.
399-
1. Run:
400-
401-
```
402-
mbed deploy
403-
```
404-
405-
1. Run:
406-
407-
```
408-
python3 build_tfm.py -m <new target> -t <toolchain> -c ConfigRegressionIPC.cmake
409-
```
410-
411-
The command builds a TF-M binary the service necessary to run regression tests.
412-
413-
<span class="notes">**Note:** Use this `ConfigRegressionIPC.cmake` only to run regression tests. The secure binary copied to Mbed OS (when you are ready to merge your new target) must be generated using the config option `ConfigCoreIPC.cmake`.</span>
414-
415-
1. Ensure the TF-M binary was copied to the location defined by the target attribute `tfm_delivery_dir`. If no binary was created or copied, please raise an [issue on the Mbed OS repository](https://github.com/ARMmbed/mbed-os).
416-
417-
1. To build Mbed OS and run regression tests, run:
418-
419-
```
420-
mbed compile -m <new target> -t <toolchain>
421-
```
422-
1. Flash the regression tests binary to the target and ensure all regression tests pass.
423-
424-
### Building TF-M and running PSA compliance tests
425-
426-
To build TF-M and compliance tests:
427-
428-
1. Switch to the `mbed-os-tf-m-regression-tests` directory.
429-
1. Edit `mbed_app.json` and set:
430-
431-
- `regression-test` to `0`.
432-
- `psa-compliance-test` to `1`.
433-
1. Run:
434-
435-
```
436-
python3 build_psa_compliance.py -m <new target> -t <toolchain> -s CRYPTO
437-
```
438-
439-
The command builds PSA API compliance tests for the crypto suite.
440-
1. Run:
441-
442-
```
443-
python3 build_tfm.py -m <new target> -t <toolchain> -c configs/ConfigPsaApiTestIPC.cmake -s CRYPTO
444-
```
445-
446-
The command builds TF-M including PSA API compliance tests.
447-
1. To build Mbed OS and run PSA API compliance tests, run:
448-
449-
```
450-
mbed compile -m <new target> -t <toolchain>
451-
```
452-
1. Flash the PSA API compliance tests binary to the target and ensure all PSA API compliance tests pass.
453-
454-
<span class="notes">**Note:** Any PSA API compliance tests that fail in the TF-M example application will fail in Mbed OS as well.</span>
277+
The [mbed-os-tf-m-regression-tests repository](https://github.com/ARMmbed/mbed-os-tf-m-regression-tests) contains build scripts, TF-M regression tests and PSA API compliance tests. Please follow instructions there to build and validate your TF-M target.
455278

456279
### Building TF-M and creating an Mbed OS pull request
457280

@@ -466,7 +289,7 @@ To build TF-M and create an Mbed OS pull request:
466289
python3 build_tfm.py -m <new target> -t <toolchain> --commit
467290
```
468291
469-
The command builds TF-M with the config `ConfigCoreIPC.cmake`, copies the TF-M binary to the location defined by the target attribute `tfm_delivery_dir`, and commits the changes to Mbed OS.
292+
The command builds TF-M with the config `CoreIPC`, copies the TF-M binary to the location defined by the target attribute `tfm_delivery_dir`, and commits the changes to Mbed OS.
470293
471294
<span class="tips">**Tip:** When you run the Python script `build_tfm.py` without any options, TF-M is built for all supported targets and the secure binary (TF-M) for each target is copied to the location defined by the target attribute `tfm_delivery_dir`. When you use the `--commit` option, a new Mbed OS commit is created with the new or modified TF-M binaries and `features/FEATURE_EXPERIMENTAL_API/FEATURE_PSA/TARGET_TFM/VERSION.txt`.</span>
472295

0 commit comments

Comments
 (0)