Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

components/TARGET_PSA/TARGET_TFM/tf-m-integration.md@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
mbed-os5 only for TYBLE16

Who changed what in which revision?

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