diff --git a/README.md b/README.md index 9b2ce865..08acd7ac 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ Cortex-M55, Cortex-M85 processors) and dual-core platforms. It is the platform security architecture reference implementation aligning with PSA Certified guidelines, enabling chips, Real Time Operating Systems and devices to become PSA Certified. Follow the [link](https://tf-m-user-guide.trustedfirmware.org/introduction/readme.html) -for more information on Trusted Firmware M. +for more information on Trusted Firmware M. To have a better overview of how Trusted Firmware M is integrated with the FRI project, you're kindly asked to check [Trusted Firmware M component document](docs/components/security/trusted_firmware-m/trusted_firmware-m.md) ### Mbed TLS diff --git a/docs/components/security/trusted_firmware-m/trusted_firmware-m.md b/docs/components/security/trusted_firmware-m/trusted_firmware-m.md index 00a9dad7..99e5ce38 100644 --- a/docs/components/security/trusted_firmware-m/trusted_firmware-m.md +++ b/docs/components/security/trusted_firmware-m/trusted_firmware-m.md @@ -15,3 +15,115 @@ A software stack running Trusted Firmware-M consists of three executable binarie The non-secure firmware can make API calls (such as cryptography, protected storage, etc.) to the secure firmware via a library known as the NS (non-secure) interface. + +## Configuration + +You need to specify a list of Trusted Firmware-M configuration options in `ARM_CORSTONE_BSP_TARGET_PLATFORM_TFM_CMAKE_ARGS` CMake variable, for example: + +```cmake +set(ARM_CORSTONE_BSP_TARGET_PLATFORM_TFM_CMAKE_ARGS + -DMCUBOOT_LOG_LEVEL=INFO +) +``` + +> You must always set `TFM_PLATFORM` according to your target platform. For example, `arm/mps4/corstone315` is the `TFM_PLATFORM` value for Corstone-315 target. The official list of supported platforms is documented in the [TF-M Platforms] webpage. + +> Additionally, your application may require more options to be set depending on what features it needs: +> * For all available options, see the [Configuration] documentation page +> * For an example of setting multiple options, check how the `ARM_CORSTONE_BSP_TARGET_PLATFORM_TFM_CMAKE_ARGS` CMake variable is defined in [this `CMakeLists.txt`](../../../../bsp/CMakeLists.txt) + +> For our reference platforms, Corstone-315, Corstone-310, and Corstone-300, their `TFM_PLATFORM` respective values are +> `arm/mps4/corstone315`, `arm/mps3/corstone310/fvp`, `arm/mps3/corstone300/fvp`. + +## Integration + +### Build dependency + +Trusted Firmware-M must be built before your application, because your application depends on the NS interface (described in the [Overview](#overview) section) and the BL2 signing scripts, both of which are generated as parts of the Trusted Firmware-M build process. To ensure the order is correct, call `add_dependencies()` in your +`CMakeLists.txt`: + +```cmake +add_dependencies(my_application trusted_firmware-m-build) +``` + +> Replace `my_application` with the actual name of your application executable. + +### Linking + +You need to link your application against the `tfm-ns-interface` library so that your application can make API calls (such as cryptography, protected storage, etc.) to the secure firmware. + +### Image signing + +Your non-secure application image must be signed using the signing script from Trusted Firmware-M. In the signed image, the executable binary is prepended with a header area containing information such as the image size, version, checksum, signature, etc. The bootloader uses this information to validate the image during the boot process. + +To sign your application image, you can include the CMake module [`SignTfmImage`](../../../../components/security/trusted_firmware-m/integration/cmake/SignTfmImage.cmake) and call the helper function `iot_reference_arm_corstone3xx_tf_m_sign_image()` in your `CMakeLists.txt`: + +```cmake +list(APPEND CMAKE_MODULE_PATH ${IOT_REFERENCE_ARM_CORSTONE3XX_SOURCE_DIR}/components/security/trusted_firmware-m/integration/cmake) +include(SignTfmImage) + +iot_reference_arm_corstone3xx_tf_m_sign_image( + my_application + my_application_signed + ${MCUBOOT_IMAGE_VERSION_NS} + TRUE +) +``` + +This will generate a signed image, `my_application_signed.bin`, in your build directory. + +> Replace `my_application` with the actual name of your application executable. +> +> Replace `MCUBOOT_IMAGE_VERSION_NS` with a version of your choice. + +You can merge the bootloader, the secure image, the non-secure application,image, secure provisioning bundle binary, non-secure provisioning bundle binary, and DDR binary into a single `.elf` image to ease loading of the code onto the target. To do this: + +```cmake +iot_reference_arm_corstone3xx_tf_m_merge_images( + my_application + + + + +) +``` + +This will generate a merged image, `my_application_merged.elf`, in your build directory. + +> Replace `my_application` with the actual name of your application executable. Also, replace the following: +> * `NS_PROVISIONING_BUNDLE_LOAD_ADDRESS` with the actual non-secure provisioning bundle load address. +> * `location_of_non_secure_provisioning_bundle_binary` with the actual location of non-secure provisioning bundle binary. +> * `NS_DDR4_IMAGE_LOAD_ADDRESS` with the actual DDR image load address. +> * `location_of_ddr_binary` with the actual location of DDR image binary. + +### Running + +After building your application, you can run it on an FVP. For instance, if you would like to use `FVP_Corstone_SSE-315` for running an application built for `Corstone-315` target: + +* Load the merged `.elf` image, after you have called `iot_reference_arm_corstone3xx_tf_m_merge_images()` during [image signing](#image-signing). + + ```bash + FVP_Corstone_SSE-315 -a /my_application_merged.elf + ``` +> Replace `FVP_OPTIONS` with the options you wish to use with your FVP while running your application. For inspiration, please have a look on the `OPTIONS` shell variable available in the [run script](../../../../tools/scripts/run.sh). +> +> In case your application uses Arm's Virtual Streaming Interface (VSI), replace `AVH_AUDIO_OPTIONS` with the options you wish to use with your FVP while running your application with VSI feature. For inspiration, please have a look on `AVH_AUDIO_OPTIONS` shell variable available in the [run script](../../../../tools/scripts/run.sh). + +## Examples + +To see the full context of the information in the sections above, you are advised to take a look at: +* How TF-M is integrated into Arm FreeRTOS Reference Integration project using [this CMakeLists.txt](https://github.com/FreeRTOS/iot-reference-arm-corstone3xx/blob/main/components/security/trusted_firmware-m/integration/CMakeLists.txt) to generate `tfm-ns-interface` library which is linked to the desired application's executable. +* One of our reference applications [CMakeLists.txt](../../../../applications/blinky/CMakeLists.txt) + +## Documentation + +For more details of how to use Trusted Firmware-M, see its [official documentation]. + +## Support + +If you encounter any issues or have questions regarding the integration of Trusted Firmware M into your IoT project, feel free to reach out to the Arm support community or consult the official documentation for assistance. + +[Configuration]: https://tf-m-user-guide.trustedfirmware.org/configuration +[official documentation]: https://tf-m-user-guide.trustedfirmware.org/ +[TF-M Platforms]: https://tf-m-user-guide.trustedfirmware.org/platform +[Trusted Firmware-M]: https://www.trustedfirmware.org/projects/tf-m/ diff --git a/release_changes/202403221755.change b/release_changes/202403221755.change index c6f763a1..e02de90f 100644 --- a/release_changes/202403221755.change +++ b/release_changes/202403221755.change @@ -1,2 +1,3 @@ mbedtls: Improve integration and simply usage of component within apps mbedtls: Add documentation +tf-m: Update the document by adding missing sections