Add documentation enhancements

README.md

@@ -106,6 +106,10 @@ of the verification fails, then MCUBoot stops the booting process.
 
 ## Software Components
 
+### Fetching
+
+Generally all the components used within the FRI project are fetched using `git submodules` from their official repositories into `components/` directory. Exact location and the version are recorded in the [manifest.yml](manifest.yml).
+
 ### Trusted Firmware M
 
 Trusted Firmware-M (TF-M) implements the Secure Processing Environment (SPE)
@@ -114,7 +118,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
 
@@ -123,7 +127,7 @@ the SSL/TLS and DTLS protocols. The project provides reference implementation
 of [PSA Cryptography API Specification](https://developer.arm.com/documentation/ihi0086/b)
 by supporting the cryptographic operations via. PSA Crypto APIs. Follow the
 [link](https://www.trustedfirmware.org/projects/mbed-tls/) for more information
-on Mbed TLS.
+on Mbed TLS. To have a better overview of how Mbed TLS is integrated with the FRI project, you're kindly asked to check [Mbed TLS component document](docs/components/security/mbedtls/mbedtls.md)
 
 ### PKCS11 PSA Shim
 

applications/freertos_iot_libraries_tests/CMakeLists.txt

@@ -110,7 +110,6 @@ target_link_libraries(${CMAKE_PROJECT_NAME}
         ota-for-aws-iot-embedded-sdk
         provisioning-lib
         mbedtls
-        mbedtls-threading-freertos
         tfm-ns-interface
 )
 

applications/keyword_detection/CMakeLists.txt

@@ -142,7 +142,6 @@ target_link_libraries(keyword-detection
         helpers-events
         helpers-sntp
         mbedtls
-        mbedtls-threading-freertos
         ota-for-aws-iot-embedded-sdk
         provisioning-lib
         tfm-ns-interface

applications/object_detection/CMakeLists.txt

@@ -126,7 +126,6 @@ target_link_libraries(object-detection
         isp-config
         isp_platform_driver
         mbedtls
-        mbedtls-threading-freertos
         ota-for-aws-iot-embedded-sdk
         provisioning-lib
         tfm-ns-interface

applications/speech_recognition/CMakeLists.txt

@@ -152,7 +152,6 @@ target_link_libraries(speech-recognition
         fri-bsp
         helpers-events
         mbedtls
-        mbedtls-threading-freertos
         ota-for-aws-iot-embedded-sdk
         provisioning-lib
         speexdsp

components/security/mbedtls/integration/CMakeLists.txt

@@ -21,6 +21,11 @@ target_link_libraries(mbedtls-threading-freertos
         mbedtls
 )
 
+target_link_libraries(mbedtls-config
+    INTERFACE
+        mbedtls-threading-freertos
+)
+
 target_link_libraries(mbedx509
     PUBLIC
         mbedtls-config

docs/components/security/mbedtls/mbedtls.md

@@ -0,0 +1,77 @@
+# MbedTLS
+
+## Overview
+
+MbedTLS is a lightweight crytographic and SSL/TLS library designed for embedded systems and IoT devices.
+
+It provides a wide range of cryptographic and security features including:
+* SSL/TLS support
+* Cryptography
+* Certificate handling
+* Key Management
+* Secure communication
+
+In the FRI, MbedTLS is a crucial component for ensuring secure communication between IoT devices and
+cloud services. It is primarily used for transport layer security, authentication, encryption and certificate management.
+
+Consult the FRI `manifest.yml` for the currently supported version of MbedTLS.
+
+## Configuration
+
+User must provide an MbedTLS configuration file. It can be an empty file or override MbedTLS default [configurations](https://tls.mbed.org/api/config_8h.html).
+
+The configuration file specified by the application is retrieved by adding the C macro `MBEDTLS_CONFIG_FILE=<filename>` to the `mbedtls-config` target and its include path.
+
+Example:
+
+```cmake
+target_include_directories(mbedtls-config
+    INTERFACE
+        mbedtls-config
+)
+
+target_compile_definitions(mbedtls-config
+    INTERFACE
+        MBEDTLS_CONFIG_FILE="aws_mbedtls_config.h"
+)
+```
+
+To enable the FreeRTOS threading protection `#define MBEDTLS_THREADING_ALT` should be present in the user provided mbedtls configuration file.
+
+## Integration
+
+### FreeRTOS threading support
+
+The library *`mbedtls-threading-freertos`* is implemented in the FRI to provide a threading implementation for MbedTLS using FreeRTOS threading API.
+
+The application must call `mbedtls_threading_set_alt()` to enable the multi threading protection.
+
+### Linking
+
+In your application's `CMakeLists.txt`, link the application executable against the `mbedtls` library alongside
+any other libraries you need:
+
+```cmake
+target_link_libraries(my-application
+    ...
+    mbedtls
+)
+```
+
+> :bulb: Replace `my-application` with the actual name of your application.
+
+This not only enables the linking of the `mbedtls` static library, but also makes its API headers' include paths
+available to your application.
+
+## Documentation
+
+For detailed documentation and API reference of MbedTLS, refer to the official [MbedTLS documentation][mbedtls-doc] or [GitHub repository][mbedtls-doc].
+
+## Support
+
+If you encounter any issues or have questions regarding the integration of MbedTLS into your IoT
+project, feel free to reach out to the Arm support community or consult the official documentation for
+assistance.
+
+[mbedtls-doc]: https://mbed-tls.readthedocs.io/en/latest/
+[mbedtls-repo]: https://github.com/Mbed-TLS/mbedtls

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
+    <NS_PROVISIONING_BUNDLE_LOAD_ADDRESS>
+    <location_of_non_secure_provisioning_bundle_binary>
+    <NS_DDR4_IMAGE_LOAD_ADDRESS>
+    <location_of_ddr_binary>
+)
+```
+
+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 <build_directory>/my_application_merged.elf <FVP_OPTIONS> <AVH_AUDIO_OPTIONS>
+    ```
+> 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/

release_changes/202403221755.change

@@ -0,0 +1,3 @@
+mbedtls: Improve integration and simply usage of component within apps
+mbedtls: Add documentation
+tf-m: Update the document by adding missing sections