1######################
2Floating-Point Support
3######################
4
5TF-M adds several configuration flags to control Floating point (FP) [1]_
6support in TF-M Secure Processing Environment (SPE) and Non Secure Processing
7Environment (NSPE).
8
9* Support FP in SPE or NSPE.
10* Support FP Application Binary Interface (ABI) [2]_ types: software, hardware.
11  SPE and NSPE shall use the same FP ABI type.
12* Support lazy stacking enable/disable in SPE only, NSPE is not allowed to
13  enable/disable this feature.
14* Support GNU Arm Embedded Toolchain [3]_. ``GNU Arm Embedded Toolchain 10.3-
15  2021.10`` and later version shall be used to mitigate VLLDM instruction
16  security vulnerability [4]_.
17* Support both IPC [5]_ and SFN [11]_ models in TF-M.
18* Support Armv8-M mainline.
19* Support isolation level 1,2,3.
20* Support Arm Compiler for Embedded [10]_. ``Arm Compiler for Embedded 6.17``
21  and later version shall be used to mitigate VLLDM instruction security
22  vulnerability [4]_.
23* Does not support use FPU in First-Level Interrupt Handling (FLIH) [6]_ at
24  current stage.
25
26Please refer to Arm AN521 or AN552 platform as a reference implementation when
27you enable FP support on your platforms.
28
29.. Note::
30    Alternatively, if you intend to use FP in your own NSPE application but the
31    TF-M SPE services that you enable do not require FP, you can set the CMake
32    configuration ``CONFIG_TFM_ENABLE_CP10CP11`` to ``ON`` and **ignore** any
33    configurations described below.
34
35.. Note::
36    FPU test issue has not been fixed yet on Musca-S1 [7]_. When running FPU
37    tests on Musca-S1, secure thread fails to trigger secure interrupt. FPU test
38    is disabled by default on Musca-S1 until the issue is fixed.
39
40.. Note::
41    ``GNU Arm Embedded Toolchain 10.3-2021.10`` may have issue that reports
42    ``'-mcpu=cortex-m55' conflicts with '-march=armv8.1-m.main'`` warning [8]_.
43    This issue has been fixed in the later version.
44
45============================
46FP ABI type for SPE and NSPE
47============================
48FP design in Armv8.0-M [9]_ architecture requires consistent FP ABI types
49between SPE and NSPE. Furthermore, both sides shall set up CPACR individually
50when FPU is used. Otherwise, No Coprocessor (NOCP) usage fault will be asserted
51during FP context switch between security states.
52
53Secure and non-secure libraries are compiled with ``COMPILER_CP_FLAG`` and
54linked with ``LINKER_CP_OPTION`` for different FP ABI types. All those
55libraries shall be built with ``COMPLIER_CP_FLAG``.
56
57If FP ABI types mismatch error is generated during build, pleae check whether
58the library is compiled with ``COMPILER_CP_FLAG``.
59Example:
60
61.. code-block:: cmake
62
63      target_compile_options(lib
64          PRIVATE
65              ${COMPILER_CP_FLAG}
66      )
67
68===================================
69CMake configurations for FP support
70===================================
71The following CMake configurations configure ``COMPILER_CP_FLAG`` in TF-M SPE.
72
73* ``CONFIG_TFM_ENABLE_FP`` is used to enable/disable FPU usage.
74
75  +--------------------------+---------------------------+
76  | CONFIG_TFM_ENABLE_FP     | FP support                |
77  +==========================+===========================+
78  | off (default)            | FP disabled               |
79  +--------------------------+---------------------------+
80  | on                       | FP enabled                |
81  +--------------------------+---------------------------+
82
83.. Note::
84    ``CONFIG_TFM_FLOAT_ABI`` depends on ``CONFIG_TFM_ENABLE_FP``. If
85    ``CONFIG_TFM_ENABLE_FP is set ``CONFIG_TFM_FLOAT_ABI`` is automatically
86    set to ``hard``.
87
88.. Note::
89    If you build TF-M SPE with ``CONFIG_TFM_ENABLE_FP=on`` and provide your own
90    NSPE application, your own NSPE **must** take care of enabling floating point
91    coprocessors CP10 and CP11 on the NS side to avoid aforementioned NOCP usage
92    fault.
93
94* ``CONFIG_TFM_LAZY_STACKING`` is used to enable/disable lazy stacking
95  feature. This feature is only valid for FP hardware ABI type.
96  NSPE is not allowed to enable/disable this feature. Let SPE decide the
97  secure/non-secure shared setting of lazy stacking to avoid the possible
98  side-path brought by flexibility.
99
100  +------------------------------+---------------------------+
101  | CONFIG_TFM_LAZY_STACKING     | Description               |
102  +==============================+===========================+
103  | 0FF                          | Disable lazy stacking     |
104  +------------------------------+---------------------------+
105  | ON (default)                 | Enable lazy stacking      |
106  +------------------------------+---------------------------+
107
108* ``CONFIG_TFM_FP_ARCH`` specifies which FP architecture is available on the
109  target, valid for FP hardware ABI type.
110
111  FP architecture is processor dependent. For GNUARM compiler, example value
112  are: auto, fpv5-d16, fpv5-sp-d16, etc. For armclang, example value are: none,
113  softvfp, fpv5-d16, fpv5-sp-d16, etc.
114
115  This parameter shall be specified by platform in preload.cmake. Please check
116  compiler reference manual and processor hardware manual for more details to
117  set correct FPU configuration for platform.
118
119* ``CONFIG_TFM_FP_ARCH_ASM`` specifies the target FPU architecture name shared
120  by Arm Compiler armasm and armlink. It is only used in the ``--fpu=`` argument
121  by Arm Compiler and shall be aligned with ``CONFIG_TFM_FP_ARCH``.
122
123  FP architecture is processor dependent. For armasm and armlink, example value
124  are: SoftVFP, FPv5_D16, etc.
125
126  This parameter shall be specified by platform in preload.cmake. Please check
127  compiler reference manual and processor hardware manual for more details to
128  set correct FPU configuration for platform.
129
130*********
131Reference
132*********
133.. [1] `High-Performance Hardware Support for Floating-Point Operations <https://www.arm.com/why-arm/technologies/floating-point>`_
134
135.. [2] `Float Point ABI <https://www.keil.com/support/man/docs/armclang_ref/armclang_ref_chr1417451577871.htm>`_
136
137.. [3] `GNU Arm Embedded Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
138
139.. [4] `VLLDM instruction Security Vulnerability <https://developer.arm.com/support/arm-security-updates/vlldm-instruction-security-vulnerability>`_
140
141.. [5] `Arm® Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/documentation/den0063/latest/>`_
142
143.. [6] :doc:`Secure Interrupt Integration Guide </integration_guide/tfm_secure_irq_integration_guide>`
144
145.. [7] `Musca-S1 Test Chip Board <https://developer.arm.com/tools-and-software/development-boards/iot-test-chips-and-boards/musca-s1-test-chip-board>`_
146
147.. [8] `GCC Issue on '-mcpu=cortex-m55' conflicts with '-march=armv8.1-m.main' Warning <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=97327>`_
148
149.. [9] `Armv8-M Architecture Reference Manual <https://developer.arm.com/documentation/ddi0553/latest>`_
150
151.. [10] `Arm Compiler for Embedded <https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded>`_
152
153.. [11] `FF-M v1.1 Extension <https://developer.arm.com/documentation/aes0039/latest/>`__
154
155--------------
156
157*Copyright (c) 2021-2023, Arm Limited. All rights reserved.*
158