.. _tfm_psa_firmware:

TF-M PSA Firmware
#################

Overview
********
This TF-M integration example demonstrates how to use the PSA Firmware API
to retrieve information about the current firmware, or implement a custom
firmware update process.

Trusted Firmware (TF-M) Platform Security Architecture (PSA) APIs
are used for the secure processing environment, with Zephyr running in the
non-secure processing environment.

It uses **IPC Mode** for communication, where an IPC mechanism is inserted to
handle secure TF-M API calls and responses. The OS-specific code to handle
the IPC calls is in ``tfm_ipc.c``.

The sample prints test info to the console either as a single-thread or
multi-thread application.

Building and Running
********************

This project needs another firmware as the update payload. It must use another
example's hex file, and should be specified on the command line
as ZEPHYR_FIRMWARE_UPDATE_SAMPLE_BUILD. For example, to use the sample
`tfm_integration/tfm_ipc` as the payload:

.. code-block:: bash

   cd <ZEPHYR_ROOT>
   west build -p -b lpcxpresso5s69_ns samples/tfm_integration/psa_firmware \
       -d build/lpcxpresso55s69_ns/tfm_integration/psa_firmware
       -- -DCONFIG_FIRMWARE_UPDATE_IMAGE=`realpath build/lpcxpresso55s69_ns/tfm_integration/tfm_ipc/zephyr_ns_signed.hex`


This project outputs startup status and info to the console. It can be built and
executed on an ARM Cortex M33 target board or QEMU.

This sample will only build on a Linux or macOS development system
(not Windows), and has been tested on the following setups:

- macOS Big Sur using QEMU 6.0.0 with gcc-arm-none-eabi-9-2020-q2-update
- Linux (NixOS) using QEMU 6.2.50 with gcc from Zephyr SDK 0.13.2

On MPS3 AN547:
===============

1. Build Zephyr with a non-secure configuration
   (``-DBOARD=mps3_an547_ns``).
   Using ``west``

.. zephyr-app-commands::
  :zephyr-app: samples/tfm_integration/psa_firmware
  :host-os: unix
  :board: mps3_an547_ns
  :goals: run
  :compact:

2. Copy application binary files (mcuboot.bin and tfm_sign.bin) to
   ``<MPS3 device name>/SOFTWARE/``.

3. Edit (e.g., with vim) the ``<MPS3 device name>/MB/HBI0263C/AN547/images.txt``
   file, and update it as shown below:

   .. code-block:: bash

      TITLE: Versatile Express Images Configuration File

      [IMAGES]
      TOTALIMAGES: 2 ;Number of Images (Max: 32)

      IMAGE0ADDRESS: 0x10000000
      IMAGE0FILE: \SOFTWARE\mcuboot.bin  ; BL2 bootloader

      IMAGE1ADDRESS: 0x10080000
      IMAGE1FILE: \SOFTWARE\tfm_sign.bin ; TF-M with application binary blob

4. Save the file, exit the editor, and reset the MPS3 board.

On QEMU:
========

Build Zephyr with a non-secure configuration (``-DBOARD=mps3_an547_ns``)
and run it in qemu via the ``run`` command.

Using ``west``

.. zephyr-app-commands::
  :zephyr-app: samples/tfm_integration/psa_firmware
  :host-os: unix
  :board: mps3_an547_ns
  :goals: run
  :compact:

On LPCxpresso55S69:
======================

Build Zephyr with a non-secure configuration:

   .. code-block:: bash

      $ west build -p -b lpcxpresso55s69_ns samples/tfm_integration/psa_firmware/ --

Make sure your board is set up with :ref:`lpclink2-jlink-onboard-debug-probe`,
since this isn't the debug interface boards ship with from the factory;

Next we need to manually flash the resulting image (``tfm_merged.bin``) with a
J-Link as follows:

   .. code-block:: console

      JLinkExe -device lpc55s69 -if swd -speed 2000 -autoconnect 1
      J-Link>r
      J-Link>erase
      J-Link>loadfile build/tfm_merged.bin

Resetting the board and erasing it will unlock the board, this is useful in case
it's in an unknown state and can't be flashed.

We need to reset the board manually after flashing the image to run this code.

Sample Output
=============

   .. code-block:: console

      [INF] Beginning TF-M provisioning
      [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
      [Sec Thread] Secure image initializing!
      TF-M FP mode: Software
      Booting TFM v1.5.0
      Creating an empty ITS flash layout.
      Creating an empty PS flash layout.
      *** Booting Zephyr OS build v3.0.0-rc1-321-gbe26b6a260d6  ***
      PSA Firmware API test
      Active NS image version: 0.0.0-0
      Starting FWU; Writing Firmware from 21000000 size 58466 bytes
      Wrote Firmware; Writing Header from 2100e462 size   432 bytes
      Wrote Header; Installing Image
      Installed New Firmware; Reboot Needed; Rebooting
      [WRN] This device was provisioned with dummy keys. This device is NOT SECURE
      [Sec Thread] Secure image initializing!
      TF-M FP mode: Software
      Booting TFM v1.5.0
      *** Booting Zephyr OS build v3.0.0-rc1-35-g03f2993ef07b  ***
      Hello World from UserSpace! mps3_an547