1#################
2Integration Guide
3#################
4The purpose of this document is to provide a guide on how to integrate TF-M
5with other hardware platforms and operating systems.
6
7
8.. toctree::
9    :maxdepth: 1
10
11    SPM Backends <spm_backends.rst>
12    NS client integration <non-secure_client_extension_integration_guide.rst>
13    OS migration to Armv8-M <os_migration_guide_armv8m.rst>
14    tfm_fpu_support
15    Secure Interrupt <tfm_secure_irq_integration_guide.rst>
16
17.. toctree::
18    :maxdepth: 2
19
20    platform/index
21    services/index
22
23
24*****************
25How to build TF-M
26*****************
27Follow the :doc:`Build instructions </building/tfm_build_instruction>`.
28
29********************************************************
30How to export files for building non-secure applications
31********************************************************
32Explained in the :doc:`Build instructions </building/tfm_build_instruction>`.
33
34*************************
35How to add a new platform
36*************************
37
38:doc:`Porting TF-M to a New Hardware </integration_guide/platform/porting_TFM_to_a_new_hardware>`
39contains guidance on how to add a new platform.
40
41***************************
42How to integrate another OS
43***************************
44
45OS migration to Armv8-M platforms
46=================================
47To work with TF-M on Armv8-M platforms, the OS needs to support the Armv8-M
48architecture and, in particular, it needs to be able to run in the non-secure
49world. More information about OS migration to the Armv8-M architecture can be
50found in the :doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon
51the system configuration this may require configuring drivers to use appropriate
52address ranges.
53
54Interface with TF-M
55===================
56The files needed for the interface with TF-M are exported at the
57``<install_dir>/interface`` path. The NS side is only allowed to call
58TF-M secure functions (veneers) from the NS Thread mode.
59
60TF-M interface header files are exported in ``<install_dir>/interface/include``
61directory. For example, the Protected Storage (PS) service PSA API is declared
62in the file ``<install_dir>/interface/include/psa/protected_storage.h``.
63
64TF-M also exports a reference implementation of PSA APIs for NS clients in the
65``<install_dir>/interface/src``.
66
67On Armv8-M TrustZone based platforms, NS OS shall implement interface API
68``tfm_ns_interface_dispatch()`` to integrate with TF-M implementation of PSA
69APIs. See ``interface/include/tfm_ns_interface.h`` for the detailed declaration
70of ``tfm_ns_interface_dispatch()``.
71TF-M provides an example of ``tfm_ns_interface_dispatch()`` implementation on
72Armv8-M TrustZone based platforms. In this example, NS OS calls mutex in
73``tfm_ns_interface_dispatch()`` to synchronize multiple NS client calls to TF-M.
74See ``interface/src/tfm_ns_interface.c.example`` for more details.
75
76TF-M provides a reference implementation of NS mailbox on multi-core platforms,
77under folder ``interface/src/multi_core``.
78See :doc:`Mailbox design </technical_references/design_docs/dual-cpu/mailbox_design_on_dual_core_system>`
79for TF-M multi-core mailbox design.
80
81Interface with non-secure world regression tests
82================================================
83A non-secure application that wants to run the non-secure regression tests
84needs to call the ``tfm_non_secure_client_run_tests()``. This function is
85exported into the header file ``test_framework_integ_test.h`` inside the
86``<build_dir>/install`` folder structure in the test specific files,
87i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression
88tests are precompiled and delivered as a static library which is available in
89``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application
90needs to link against the library to be able to invoke the
91``tfm_non_secure_client_run_tests()`` function. The PS non-secure side
92regression tests rely on some OS functionality e.g. threads, mutexes etc. These
93functions comply with CMSIS RTOS2 standard and have been exported as thin
94wrappers defined in ``os_wrapper.h`` contained in
95``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the
96implementation of these wrappers to be able to run the tests.
97
98NS client Identification
99========================
100
101The NS client identification (NSID) is specified by either SPM or NSPE RTOS.
102If SPM manages the NSID (default option), then the same NSID (-1) will be used
103for all connections from NS clients.
104For the case that NSPE RTOS manages the NSID and/or different NSIDs should be
105used for different NS clients. See
106:doc:`Non-secure Client Extension Integration Guide </integration_guide/non-secure_client_extension_integration_guide>`.
107
108*********************
109Non-secure interrupts
110*********************
111Non-secure interrupts are allowed to preempt Secure thread mode.
112With the current implementation, a NSPE task can spoof the identity of another
113NSPE task. This is an issue only when NSPE has provisions for task isolation.
114Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
115to NS interrupts to the lower half of available priorities so that it wouldn't
116be possible for any non-secure interrupt to preempt a higher-priority secure
117interrupt.
118
119**********************************
120Integration with non-Cmake systems
121**********************************
122
123Generated Files
124===============
125
126Files that are derived from PSA manifests are generated at build-time by cmake.
127For integration with systems that do no use cmake, the files must be generated
128manually.
129
130The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
131arguments will be needed to be provided. Please refer to
132``tfm_parse_manifest_list.py --help`` for more details.
133
134Some variables are used in the template files, these will need to be set in the
135environment before the script will succeed when the script is not run via cmake.
136
137--------------
138
139*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
140