diff options
Diffstat (limited to 'docs/user_guides/tfm_integration_guide.rst')
-rw-r--r-- | docs/user_guides/tfm_integration_guide.rst | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/docs/user_guides/tfm_integration_guide.rst b/docs/user_guides/tfm_integration_guide.rst new file mode 100644 index 0000000000..41f10ed940 --- /dev/null +++ b/docs/user_guides/tfm_integration_guide.rst @@ -0,0 +1,126 @@ +###################### +TF-M integration guide +###################### +The purpose of this document is to provide a guide on how to integrate TF-M +with other hardware platforms and operating systems. + +***************** +How to build TF-M +***************** +Follow the :doc:`Build instructions <tfm_build_instruction>`. + +******************************************************** +How to export files for building non-secure applications +******************************************************** +Explained in the :doc:`Build instructions <tfm_build_instruction>`. + +************************* +How to add a new platform +************************* +The hardware platforms currently supported are: + +- Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521) +- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519) +- Musca-A1 test chip board (Cortex-M33 SSE-200 subsystem) +- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem) + +The files related to the supported platforms are contained under the +``platform`` subfolder. The platform specific files are under +``platform/ext/target``, which is organised by boards +(e.g. ``platform/ext/target/mps2``), while the folder ``platform/ext/common`` +is used to store source and header files which are platform generic. + +More information about subsystems supported by the MPS2+ board can be found in: +`MPS2+ homepage <https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps2>`__ + +More information about the Musca-A1 test chip board can be found in: +`Musca-A homepage <https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board>`__ + +More information about the Musca-B1 test chip board can be found in: +`Musca-B1 homepage <https://www.arm.com/products/development-tools/development-boards/musca-b1-iot>`__ + +Generic drivers and startup/scatter files +========================================= +The addition of a new platform means the creation of a new subfolder inside +``target/<board_name>`` to provide an implementation of the drivers currently +used by TF-M, in particular MPC, PPC, and USART drivers. In addition to the +drivers, startup and scatter files need to be provided for the supported +toolchains. + +There are also board specific drivers which are used by the board +platform to interact with the external world, for example during tests, that +have to be provided, e.g. to blink LEDs or count time in the MPS2 board. + +.. Note:: + + Currently SST and BL2 bootloader use different flash interface + +Target configuration files +========================== +Inside the base root folder of the selected target, each implementation has to +provide its own copy of ``target_cfg.c/.h``. This file has target specific +configuration functions and settings that are called by the TF-M during the +platform configuration step during TF-M boot. Examples of the configurations +performed during this phase are the MPC configuration, the SAU configuration, +or eventually PPC configuration if supported by the hardware platform. +Similarly, the ``uart_stdout.c`` is used to provide functions needed to redirect +the stdout on UART (this is currently used by TF-M to log messages). + +Platform retarget files +======================= +An important part that each new platform has to provide is the set of retarget +files which are contained inside the ``retarget`` folder. These files define the +peripheral base addresses for the platform, both for the secure and non-secure +aliases (when available), and bind those addresses to the base addresses used by +the devices available in the hardware platform. + +*************************** +How to integrate another OS +*************************** +To work with TF-M, the OS needs to support the Armv8-M architecture and, in +particular, it needs to be able to run in the non-secure world. More +information about OS migration to the Armv8-M architecture can be found in the +:doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon the system +configuration this may require configuring drivers to use appropriate address +ranges. + +Interface with TF-M +=================== +The files needed for the interface with TF-M are exported at the +``<build_dir>/install/export/tfm`` path. The NS side is only allowed to call +TF-M secure functions (veneers) from the NS Thread mode. For this reason, the +API is a collection of functions in the ``<build_dir>/install/export/tfm/inc`` +directory. For example, the interface for the Secure STorage (SST) service +is described in the file ``psa_sst_api.h`` as a collection of functions that +call service veneer functions. This API is a wrapper for the secure veneers, +and returns the return value from the service to the caller. + +The secure storage service uses a numerical ID, to identify the clients that use +the service. For details see +:doc:`ns client identification documentation <tfm_ns_client_identification>`. + +Interface with non-secure world regression tests +================================================ +A non-secure application that wants to run the non-secure regression tests +needs to call the ``tfm_non_secure_client_run_tests()``. This function is +exported into the header file ``test_framework_integ_test.h`` inside the +``<build_dir>/install`` folder structure in the test specific files, +i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression +tests are precompiled and delivered as a static library which is available in +``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application +needs to link against the library to be able to invoke the +``tfm_non_secure_client_run_tests()`` function. The SST non-secure side +regression tests rely on some OS functionality e.g. threads, mutexes etc. These +functions comply with CMSIS RTOS2 standard and have been exported as thin +wrappers defined in ``os_wrapper.h`` contained in +``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the +implementation of these wrappers to be able to run the tests. + +NS client Identification +======================== +See +:doc:`ns client identification documentation <tfm_ns_client_identification>`. + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* |