aboutsummaryrefslogtreecommitdiff
path: root/docs/user_guides/tfm_user_guide.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/user_guides/tfm_user_guide.rst')
-rw-r--r--docs/user_guides/tfm_user_guide.rst317
1 files changed, 317 insertions, 0 deletions
diff --git a/docs/user_guides/tfm_user_guide.rst b/docs/user_guides/tfm_user_guide.rst
new file mode 100644
index 0000000000..c7f9026331
--- /dev/null
+++ b/docs/user_guides/tfm_user_guide.rst
@@ -0,0 +1,317 @@
+#############################
+Trusted Firmware M user guide
+#############################
+How to compile and run TF-M and example test application for CoreLink
+SSE-200 subsystem on the MPS2 board and on the Fast Model(FVP).
+
+Follow :doc:`build instruction <tfm_build_instruction>` to build the binaries.
+Follow :doc:`secure boot <tfm_secure_boot>` to build the binaries with or
+without BL2 bootloader.
+
+****************************************************************
+Execute TF-M example and regression tests on MPS2 boards and FVP
+****************************************************************
+The BL2 bootloader and TF-M example application and tests run correctly on
+SMM-SSE-200 for MPS2 (AN521) and on the Fixed Virtual Platform model
+FVP_MPS2_AEMv8M version 11.2.23.
+
+To run the example code on FVP_MPS2_AEMv8M
+==========================================
+Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1.
+
+.. Note::
+ FVP reference guide can be found
+ `here <https://developer.arm.com/docs/100966/latest>`__
+
+Example application and regression tests without BL2 bootloader
+---------------------------------------------------------------
+Add ``tfm_s.axf`` and ``tfm_ns.axf`` to symbol files in Debug Configuration
+menu.
+
+.. code-block:: bash
+
+ <DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=<build_dir>/install/outputs/fvp/tfm_s.axf \
+ --data cpu0=<build_dir>/install/outputs/fvp/tfm_ns.bin@0x00100000
+
+Example application and regression tests with BL2 bootloader
+------------------------------------------------------------
+To test TF-M with bootloader, one must apply the following changes:
+
+- Add ``mcuboot.axf`` to symbol files in DS-5 in Debug Configuration
+ menu.
+- Replace the last two lines of the previous command with this:
+
+.. code-block:: bash
+
+ --application cpu0=<build_dir>/install/outputs/fvp/mcuboot.axf \
+ --data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000
+
+Test software upgrade with BL2 bootloader
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+BL2 bootloader is mandatory to test software update. Furthermore two TF-M blob
+must be built. Outputs of example application and regression test can be used to
+test it. Load output of example application to slot 0 (0x10080000) and output of
+regression test to slot 1 (0x10180000). Add the following line to the end of
+the previous chapter:
+
+.. code-block:: bash
+
+ --data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
+
+To run the example code on SSE 200 FPGA on MPS2 board
+=====================================================
+FPGA image is available to download
+`here <https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
+
+To run BL2 bootloader and TF-M example application and tests in the MPS2 board,
+it is required to have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board SD
+card. The image should be located in
+``<MPS2 device name>/MB/HBI0263<board revision letter>/AN521``
+
+The MPS2 board tested is HBI0263C referred also as MPS2+.
+
+.. Warning::
+
+ If you change the exe names, MPS2 expects file names in 8.3 format.
+
+Example application
+-------------------
+#. Copy ``mcuboot.bin`` and ``tfm_sign.bin`` files from
+ ``<build_dir>/install/outputs/AN521/`` to
+ ``<MPS2 device name>/SOFTWARE/``
+#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Update the ``AN521/images.txt`` file as follows::
+
+ 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 example application binary blob
+
+#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Unmount/eject the ``<MPS2 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests
+----------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the secure storage service ####
+ Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+
+ > Executing 'TFM_SST_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2004'
+ Description: 'Write interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2005'
+ Description: 'Read interface'
+ ....
+
+.. Note::
+
+ SST reliability tests take a few minutes to run on the MPS2.
+
+Example application without BL2 bootloader
+------------------------------------------
+#. Copy ``tfm_s.bin`` and ``tfm_ns.bin`` files from
+ ``<build_dir>/install/outputs/AN521/`` to
+ ``<MPS2 device name>/SOFTWARE/``
+#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Update the ``AN521/images.txt`` file as follows::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x10000000
+ IMAGE0FILE: \Software\tfm_s.bin ; Secure code
+ IMAGE1ADDRESS: 0x00100000
+ IMAGE1FILE: \Software\tfm_ns.bin ; Non-secure code
+
+#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Unmount/eject the ``<MPS2 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+Regression tests without BL2 bootloader
+---------------------------------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the secure storage service ####
+ Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+
+ > Executing 'TFM_SST_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2004'
+ Description: 'Write interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2005'
+ Description: 'Read interface'
+ ....
+
+*******************************************************************
+Execute TF-M example and regression tests on Musca test chip boards
+*******************************************************************
+.. Note::
+
+ Before executing any images on Musca-B1 board, please check the
+ :doc:`target platform readme </platform/ext/target/musca_b1/readme>`
+ to have the correct setup.
+
+Example application with BL2 bootloader
+=======================================
+
+#. Create a unified hex file comprising of both mcuboot and tfm_sign
+ binary
+
+- For Musca-A1
+
+ - Windows::
+
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+
+- For Musca-B1
+
+ - Windows::
+
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+#. Plug the Musca board into your computer. The board should appear as a USB
+ drive
+#. Copy ``tfm.hex`` to the USB drive
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to see on the UART0
+ (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xd9
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests with BL2 bootloader
+====================================
+After completing the procedure you should see the following messages on the
+UART0 (baud 115200 8n1)::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the secure storage service ####
+ Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
+ > Executing 'TFM_SST_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2004'
+ Description: 'Get attributes interface'
+ TEST PASSED!
+ > Executing 'TFM_SST_TEST_2005'
+ Description: 'Get attributes with null attributes struct pointer'
+ ....
+
+Example application or regression tests on Musca-B1 without BL2 bootloader
+==========================================================================
+
+Follow the above procedures, but create a unified hex file out of ``tfm_s.bin``
+and ``tfm_ns.bin``:
+
+- Windows::
+
+ srec_cat.exe app\secure_fw\tfm_s.bin -Binary -offset 0xA000000 app\tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
+
+- Linux::
+
+ srec_cat app/secure_fw/tfm_s.bin -Binary -offset 0xA000000 app/tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
+
+Firmware upgrade and image validation with BL2 bootloader
+=========================================================
+High level operation of BL2 bootloader and instructions for testing firmware
+upgrade is described in :doc:`secure boot <tfm_secure_boot>`.
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*