mbed-os5 only for TYBLE16
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
components/TARGET_PSA/TARGET_TFM/tf-m-integration.md@1:9db0e321a9f4, 2019-12-31 (annotated)
- Committer:
- kenjiArai
- Date:
- Tue Dec 31 06:02:27 2019 +0000
- Revision:
- 1:9db0e321a9f4
- Parent:
- 0:5b88d5760320
updated based on mbed-os5.15.0
Who changed what in which revision?
User | Revision | Line number | New 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. |