doc/services/tfm/build.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _tfm_build_system:

 TF-M Build System
 #################

 When building a valid ``_ns`` board target, TF-M will be built in the
 background, and linked with the Zephyr non-secure application. No knowledge
 of TF-M's build system is required in most cases, and the following will
 build a TF-M and Zephyr image pair, and run it in qemu with no additional
 steps required:

    .. code-block:: bash

      $ west build -p auto -b mps2/an521/cpu0/ns samples/tfm_integration/psa_protected_storage/ -t run

 The outputs and certain key steps in this build process are described here,
 however, since you will need to understand and interact with the outputs, and
 deal with signing the secure and non-secure images before deploying them.

 Images Created by the TF-M Build
 ********************************

 The TF-M build system creates the following executable files:

 * tfm_s - TF-M secure firmware
 * tfm_ns - TF-M non-secure app (only used by regression tests).
 * bl2 - TF-M MCUboot, if enabled

 For each of these, it creates .bin, .hex, .elf, and .axf files.

 The TF-M build system also creates signed variants of tfm_s and tfm_ns, and a
 file which combines them:

 * tfm_s_signed
 * tfm_ns_signed
 * tfm_s_ns_signed

 For each of these, only .bin files are created.

 The TF-M non-secure app is discarded in favor of Zephyr non-secure app except
 when running the TF-M regression test suite.

 The Zephyr build system usually signs both tfm_s and the Zephyr non-secure app itself.
 See below for details.

 The 'tfm' target contains properties for all these paths.
 For example, the following will resolve to ``<path>/tfm_s.hex``:

    .. code-block::

       $<TARGET_PROPERTY:tfm,TFM_S_HEX_FILE>

 See the top level CMakeLists.txt file in the tfm module for an overview of all
 the properties.

 Signing Images
 **************

 When :kconfig:option:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader
 (BL2) and firmware images must be signed with a private key. The firmware image
 is validated by the bootloader during updates using the corresponding public
 key, which is stored inside the secure bootloader firmware image.

 By default, ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure
 images, and ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign
 non-secure images. These default .pem keys can (and **should**) be overridden
 using the :kconfig:option:`CONFIG_TFM_KEY_FILE_S` and
 :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config flags.

 To satisfy `PSA Certified Level 1`_ requirements, **You MUST replace
 the default .pem file with a new key pair!**

 To generate a new public/private key pair, run the following commands:

    .. code-block:: bash

      $ imgtool keygen -k root-rsa-3072_s.pem -t rsa-3072
      $ imgtool keygen -k root-rsa-3072_ns.pem -t rsa-3072

 You can then place the new .pem files in an alternate location, such as your
 Zephyr application folder, and reference them in the ``prj.conf`` file via the
 :kconfig:option:`CONFIG_TFM_KEY_FILE_S` and :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config
 flags.

    .. warning::

      Be sure to keep your private key file in a safe, reliable location! If you
      lose this key file, you will be unable to sign any future firmware images,
      and it will no longer be possible to update your devices in the field!

 After the built-in signing script has run, it creates a ``tfm_merged.hex``
 file that contains all three binaries: bl2, tfm_s, and the zephyr app. This
 hex file can then be flashed to your development board or run in QEMU.

 .. _PSA Certified Level 1:
   https://www.psacertified.org/security-certification/psa-certified-level-1/

 Custom CMake arguments
 ======================

 When building a Zephyr application with TF-M it might be necessary to control
 the CMake arguments passed to the TF-M build.

 Zephyr TF-M build offers several Kconfig options for controlling the build, but
 doesn't cover every CMake argument supported by the TF-M build system.

 The ``TFM_CMAKE_OPTIONS`` property on the ``zephyr_property_target`` can be used
 to pass custom CMake arguments to the TF-M build system.

 To pass the CMake argument ``-DFOO=bar`` to the TF-M build system, place the
 following CMake snippet in your CMakeLists.txt file.

    .. code-block:: cmake

      set_property(TARGET zephyr_property_target
                   APPEND PROPERTY TFM_CMAKE_OPTIONS
                   -DFOO=bar
      )

 .. note::
    The ``TFM_CMAKE_OPTIONS`` is a list so it is possible to append multiple
    options. Also CMake generator expressions are supported, such as
    ``$<1:-DFOO=bar>``

 Since ``TFM_CMAKE_OPTIONS`` is a list argument it will be expanded before it is
 passed to the TF-M build system.
 Options that have list arguments must therefore be properly escaped to avoid
 being expanded as a list.

    .. code-block:: cmake

      set_property(TARGET zephyr_property_target
                   APPEND PROPERTY TFM_CMAKE_OPTIONS
                   -DFOO="bar\\\;baz"
      )

 Footprint and Memory Usage
 **************************

 The build system offers targets to view and analyse RAM and ROM usage in generated images.
 The tools run on the final images and give information about size of symbols and code being used in both RAM and ROM.
 For more information on these tools look here: :ref:`footprint_tools`

 Use the ``tfm_ram_report`` to get the RAM report for TF-M secure firmware (tfm_s).

 .. zephyr-app-commands::
     :tool: all
     :zephyr-app: samples/hello_world
     :board: mps2/an521/cpu0/ns
     :goals: tfm_ram_report

 Use the ``tfm_rom_report`` to get the ROM report for TF-M secure firmware (tfm_s).

 .. zephyr-app-commands::
     :tool: all
     :zephyr-app: samples/hello_world
     :board: mps2/an521/cpu0/ns
     :goals: tfm_rom_report

 Use the ``bl2_ram_report`` to get the RAM report for TF-M MCUboot, if enabled.

 .. zephyr-app-commands::
     :tool: all
     :zephyr-app: samples/hello_world
     :board: mps2/an521/cpu0/ns
     :goals: bl2_ram_report

 Use the ``bl2_rom_report`` to get the ROM report for TF-M MCUboot, if enabled.

 .. zephyr-app-commands::
     :tool: all
     :zephyr-app: samples/hello_world
     :board: mps2/an521/cpu0/ns
     :goals: bl2_rom_report
	.. _tfm_build_system:

	TF-M Build System
	#################

	When building a valid ``_ns`` board target, TF-M will be built in the
	background, and linked with the Zephyr non-secure application. No knowledge
	of TF-M's build system is required in most cases, and the following will
	build a TF-M and Zephyr image pair, and run it in qemu with no additional
	steps required:

	.. code-block:: bash

	$ west build -p auto -b mps2/an521/cpu0/ns samples/tfm_integration/psa_protected_storage/ -t run

	The outputs and certain key steps in this build process are described here,
	however, since you will need to understand and interact with the outputs, and
	deal with signing the secure and non-secure images before deploying them.

	Images Created by the TF-M Build
	********************************

	The TF-M build system creates the following executable files:

	* tfm_s - TF-M secure firmware
	* tfm_ns - TF-M non-secure app (only used by regression tests).
	* bl2 - TF-M MCUboot, if enabled

	For each of these, it creates .bin, .hex, .elf, and .axf files.

	The TF-M build system also creates signed variants of tfm_s and tfm_ns, and a
	file which combines them:

	* tfm_s_signed
	* tfm_ns_signed
	* tfm_s_ns_signed

	For each of these, only .bin files are created.

	The TF-M non-secure app is discarded in favor of Zephyr non-secure app except
	when running the TF-M regression test suite.

	The Zephyr build system usually signs both tfm_s and the Zephyr non-secure app itself.
	See below for details.

	The 'tfm' target contains properties for all these paths.
	For example, the following will resolve to ``<path>/tfm_s.hex``:

	.. code-block::

	$<TARGET_PROPERTY:tfm,TFM_S_HEX_FILE>

	See the top level CMakeLists.txt file in the tfm module for an overview of all
	the properties.

	Signing Images
	**************

	When :kconfig:option:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader
	(BL2) and firmware images must be signed with a private key. The firmware image
	is validated by the bootloader during updates using the corresponding public
	key, which is stored inside the secure bootloader firmware image.

	By default, ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure
	images, and ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign
	non-secure images. These default .pem keys can (and should) be overridden
	using the :kconfig:option:`CONFIG_TFM_KEY_FILE_S` and
	:kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config flags.

	To satisfy `PSA Certified Level 1`_ requirements, **You MUST replace
	the default .pem file with a new key pair!**

	To generate a new public/private key pair, run the following commands:

	.. code-block:: bash

	$ imgtool keygen -k root-rsa-3072_s.pem -t rsa-3072
	$ imgtool keygen -k root-rsa-3072_ns.pem -t rsa-3072

	You can then place the new .pem files in an alternate location, such as your
	Zephyr application folder, and reference them in the ``prj.conf`` file via the
	:kconfig:option:`CONFIG_TFM_KEY_FILE_S` and :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config
	flags.

	.. warning::

	Be sure to keep your private key file in a safe, reliable location! If you
	lose this key file, you will be unable to sign any future firmware images,
	and it will no longer be possible to update your devices in the field!

	After the built-in signing script has run, it creates a ``tfm_merged.hex``
	file that contains all three binaries: bl2, tfm_s, and the zephyr app. This
	hex file can then be flashed to your development board or run in QEMU.

	.. _PSA Certified Level 1:
	https://www.psacertified.org/security-certification/psa-certified-level-1/

	Custom CMake arguments
	======================

	When building a Zephyr application with TF-M it might be necessary to control
	the CMake arguments passed to the TF-M build.

	Zephyr TF-M build offers several Kconfig options for controlling the build, but
	doesn't cover every CMake argument supported by the TF-M build system.

	The ``TFM_CMAKE_OPTIONS`` property on the ``zephyr_property_target`` can be used
	to pass custom CMake arguments to the TF-M build system.

	To pass the CMake argument ``-DFOO=bar`` to the TF-M build system, place the
	following CMake snippet in your CMakeLists.txt file.

	.. code-block:: cmake

	set_property(TARGET zephyr_property_target
	APPEND PROPERTY TFM_CMAKE_OPTIONS
	-DFOO=bar
	)

	.. note::
	The ``TFM_CMAKE_OPTIONS`` is a list so it is possible to append multiple
	options. Also CMake generator expressions are supported, such as
	``$<1:-DFOO=bar>``

	Since ``TFM_CMAKE_OPTIONS`` is a list argument it will be expanded before it is
	passed to the TF-M build system.
	Options that have list arguments must therefore be properly escaped to avoid
	being expanded as a list.

	.. code-block:: cmake

	set_property(TARGET zephyr_property_target
	APPEND PROPERTY TFM_CMAKE_OPTIONS
	-DFOO="bar\\\;baz"
	)

	Footprint and Memory Usage
	**************************

	The build system offers targets to view and analyse RAM and ROM usage in generated images.
	The tools run on the final images and give information about size of symbols and code being used in both RAM and ROM.
	For more information on these tools look here: :ref:`footprint_tools`

	Use the ``tfm_ram_report`` to get the RAM report for TF-M secure firmware (tfm_s).

	.. zephyr-app-commands::
	:tool: all
	:zephyr-app: samples/hello_world
	:board: mps2/an521/cpu0/ns
	:goals: tfm_ram_report

	Use the ``tfm_rom_report`` to get the ROM report for TF-M secure firmware (tfm_s).

	.. zephyr-app-commands::
	:tool: all
	:zephyr-app: samples/hello_world
	:board: mps2/an521/cpu0/ns
	:goals: tfm_rom_report

	Use the ``bl2_ram_report`` to get the RAM report for TF-M MCUboot, if enabled.

	.. zephyr-app-commands::
	:tool: all
	:zephyr-app: samples/hello_world
	:board: mps2/an521/cpu0/ns
	:goals: bl2_ram_report

	Use the ``bl2_rom_report`` to get the ROM report for TF-M MCUboot, if enabled.

	.. zephyr-app-commands::
	:tool: all
	:zephyr-app: samples/hello_world
	:board: mps2/an521/cpu0/ns
	:goals: bl2_rom_report