docs/integration_guide/tfm_fpu_support.rst

######################
Floating-Point Support
######################

TF-M adds several configuration flags to control Floating point (FP) [1]_
support in TF-M Secure Processing Environment (SPE) and Non Secure Processing
Environment (NSPE).

* Support FP in SPE or NSPE.
* Support FP Application Binary Interface (ABI) [2]_ types: software, hardware.
  SPE and NSPE shall use the same FP ABI type.
* Support lazy stacking enable/disable in SPE only, NSPE is not allowed to
  enable/disable this feature.
* Support GNU Arm Embedded Toolchain [3]_. ``GNU Arm Embedded Toolchain 10.3-
  2021.10`` and later version shall be used to mitigate VLLDM instruction
  security vulnerability [4]_.
* Support Inter-Process Communication (IPC) [5]_ model in TF-M, and doesn't
  support SFN model.
* Support Armv8-M mainline.
* Support isolation level 1,2,3.
* Support Arm Compiler for Embedded [10]_. ``Arm Compiler for Embedded 6.17``
  and later version shall be used to mitigate VLLDM instruction security
  vulnerability [4]_.
* Does not support use FPU in First-Level Interrupt Handling (FLIH) [6]_ at
  current stage.

Please refer to Arm AN521 or AN552 platform as a reference implementation when
you enable FP support on your platforms.

.. Note::
    Alternatively, if you intend to use FP in your own NSPE application but the
    TF-M SPE services that you enable do not require FP, you can set the CMake
    configuration ``CONFIG_TFM_ENABLE_CP10CP11`` to ``ON`` and **ignore** any
    configurations described below.

.. Note::
    FPU test issue has not been fixed yet on Musca-S1 [7]_. When running FPU
    tests on Musca-S1, secure thread fails to trigger secure interrupt. FPU test
    is disabled by default on Musca-S1 until the issue is fixed.

.. Note::
    ``GNU Arm Embedded Toolchain 10.3-2021.10`` may have issue that reports
    ``'-mcpu=cortex-m55' conflicts with '-march=armv8.1-m.main'`` warning [8]_.
    This issue has been fixed in the later version.

============================
FP ABI type for SPE and NSPE
============================
FP design in Armv8.0-M [9]_ architecture requires consistent FP ABI types
between SPE and NSPE. Furthermore, both sides shall set up CPACR individually
when FPU is used. Otherwise, No Coprocessor (NOCP) usage fault will be asserted
during FP context switch between security states.

Secure and non-secure libraries are compiled with ``COMPILER_CP_FLAG`` and
linked with ``LINKER_CP_OPTION`` for different FP ABI types. All those
libraries shall be built with ``COMPLIER_CP_FLAG``.

If FP ABI types mismatch error is generated during build, pleae check whether
the library is compiled with ``COMPILER_CP_FLAG``.
Example:

.. code-block:: cmake

      target_compile_options(lib
          PRIVATE
              ${COMPILER_CP_FLAG}
      )

===================================
CMake configurations for FP support
===================================
The following CMake configurations configure ``COMPILER_CP_FLAG`` in TF-M SPE.

* ``CONFIG_TFM_ENABLE_FP`` is used to enable/disable FPU usage.

  +--------------------------+---------------------------+
  | CONFIG_TFM_ENABLE_FP     | FP support                |
  +==========================+===========================+
  | off (default)            | FP disabled               |
  +--------------------------+---------------------------+
  | on                       | FP enabled                |
  +--------------------------+---------------------------+

.. Note::
    ``CONFIG_TFM_FLOAT_ABI`` depends on ``CONFIG_TFM_ENABLE_FP``. If
    ``CONFIG_TFM_ENABLE_FP is set ``CONFIG_TFM_FLOAT_ABI`` is automatically
    set to ``hard``.

.. Note::
    If you build TF-M SPE with ``CONFIG_TFM_ENABLE_FP=on`` and provide your own
    NSPE application, your own NSPE **must** take care of enabling floating point
    coprocessors CP10 and CP11 on the NS side to avoid aforementioned NOCP usage
    fault.

* ``CONFIG_TFM_LAZY_STACKING`` is used to enable/disable lazy stacking
  feature. This feature is only valid for FP hardware ABI type.
  NSPE is not allowed to enable/disable this feature. Let SPE decide the
  secure/non-secure shared setting of lazy stacking to avoid the possible
  side-path brought by flexibility.

  +------------------------------+---------------------------+
  | CONFIG_TFM_LAZY_STACKING     | Description               |
  +==============================+===========================+
  | 0FF                          | Disable lazy stacking     |
  +------------------------------+---------------------------+
  | ON (default)                 | Enable lazy stacking      |
  +------------------------------+---------------------------+

* ``CONFIG_TFM_FP_ARCH`` specifies which FP architecture is available on the
  target, valid for FP hardware ABI type.

  FP architecture is processor dependent. For GNUARM compiler, example value
  are: auto, fpv5-d16, fpv5-sp-d16, etc. For armclang, example value are: none,
  softvfp, fpv5-d16, fpv5-sp-d16, etc.

  This parameter shall be specified by platform in preload.cmake. Please check
  compiler reference manual and processor hardware manual for more details to
  set correct FPU configuration for platform.

* ``CONFIG_TFM_FP_ARCH_ASM`` specifies the target FPU architecture name shared
  by Arm Compiler armasm and armlink. It is only used in the ``--fpu=`` argument
  by Arm Compiler and shall be aligned with ``CONFIG_TFM_FP_ARCH``.

  FP architecture is processor dependent. For armasm and armlink, example value
  are: SoftVFP, FPv5_D16, etc.

  This parameter shall be specified by platform in preload.cmake. Please check
  compiler reference manual and processor hardware manual for more details to
  set correct FPU configuration for platform.

*********
Reference
*********
.. [1] `High-Performance Hardware Support for Floating-Point Operations <https://www.arm.com/why-arm/technologies/floating-point>`_

.. [2] `Float Point ABI <https://www.keil.com/support/man/docs/armclang_ref/armclang_ref_chr1417451577871.htm>`_

.. [3] `GNU Arm Embedded Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_

.. [4] `VLLDM instruction Security Vulnerability <https://developer.arm.com/support/arm-security-updates/vlldm-instruction-security-vulnerability>`_

.. [5] `Arm® Platform Security Architecture Firmware Framework 1.0 <https://armkeil.blob.core.windows.net/developer/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf>`_

.. [6] :doc:`Secure Interrupt Integration Guide </integration_guide/tfm_secure_irq_integration_guide>`

.. [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>`_

.. [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>`_

.. [9] `Armv8-M Architecture Reference Manual <https://developer.arm.com/documentation/ddi0553/latest>`_

.. [10] `Arm Compiler for Embedded <https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded>`_

--------------

*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*