Docs: Fix buildsystem related documentation issues
Change-Id: I5d98b6a22cd206c6a0ef2cceac24b135282268f9
Signed-off-by: Raef Coles <raef.coles@arm.com>
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
index 003465d..5410fad 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -10,6 +10,9 @@
TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
build environment. The instructions are below.
+Cmake version ``3.13.0`` or higher is supported, but version ``3.15.0`` or
+higher is required for ARMclang support.
+
Getting the source-code
=======================
.. code-block:: bash
@@ -82,7 +85,7 @@
Both ``Debug`` and ``Relwithdebinfo`` will include debug symbols in the output
files. ``Relwithdebinfo``, ``Release`` and ``Minsizerel`` have optimization
-turned on and hence will produce smaller, faster code. ``Relwithdebinfo`` will
+turned on and hence will produce smaller, faster code. ``Minsizerel`` will
produce the smallest code, and hence is often a good idea on RAM or flash
constrained systems.
@@ -436,28 +439,35 @@
Manual dependency management
****************************
-TF-M build system will try to fetch all dependencies with appropriate versions
-and store them inside the build tree. If you have local copies already, or wish
-to avoid downloading whenever the build directory is completely cleaned, then
-the following paths can be set.
+The TF-M build system will by default fetch all dependencies with appropriate
+versions and store them inside the build tree. In this case, the build tree
+location is ``<build_dir>/lib/ext``, and the extra libraries can be cleaned by
+deleting that directory.
-+--------------+--------------------+-----------------------------------------------------+
-| Dependency | Cmake variable | Git repo URL |
-+==============+====================+=====================================================+
-| mbedcrypto | MBEDCRYPTO_PATH | https://github.com/ARMmbed/mbedtls |
-+--------------+--------------------+-----------------------------------------------------+
-| tf-m-tests | TFM_TEST_REPO_PATH | https://git.trustedfirmware.org/TF-M/tf-m-tests.git |
-+--------------+--------------------+-----------------------------------------------------+
-| mcuboot | MCUBOOT_PATH | https://github.com/JuulLabs-OSS/mcuboot |
-+--------------+--------------------+-----------------------------------------------------+
+If you have local copies already, and wish to avoid having the libraries
+downloaded every time the build directory is deleted, then the following
+variables can be set to the paths to those local copies. This will disable the
+automatic downloading for that dependency.
+
++----------------+--------------------+-----------------------------------------------------+
+| Dependency | Cmake variable | Git repo URL |
++================+====================+=====================================================+
+| Mbed Crypto | MBEDCRYPTO_PATH | https://github.com/ARMmbed/mbedtls |
++----------------+--------------------+-----------------------------------------------------+
+| tf-m-tests | TFM_TEST_REPO_PATH | https://git.trustedfirmware.org/TF-M/tf-m-tests.git |
++----------------+--------------------+-----------------------------------------------------+
+| MCUboot | MCUBOOT_PATH | https://github.com/JuulLabs-OSS/mcuboot |
++----------------+--------------------+-----------------------------------------------------+
+| psa-arch-tests | PSA_ARCH_TEST_PATH | https://github.com/ARM-software/psa-arch-tests |
++----------------+--------------------+-----------------------------------------------------+
For required versions of the dependencies, refer to ``config/config_default.cmake``.
.. Note::
- Some patches are required to the mbedtls repo to allow building it as part of
TF-M. While these patches are being upstreamed they are stored in
- lib/ext/mbedcrypo. In order to use a local copy of mbedcrypto it is required
- to apply all patch files in this directory.
+ ``lib/ext/mbedcrypo``. In order to use a local copy of Mbed Crypto it is
+ required to apply all patch files in this directory.
.. Note::
- CMSIS 5 is provided by the TF-M tests repo. If you wish to use a different
@@ -466,6 +476,51 @@
.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
.. _Doxygen: https://www.doxygen.nl
+Example: building TF-M for AN521 platform with local Mbed Crypto
+================================================================
+
+Prepare Mbed Crypto repository
+------------------------------
+
+This is only required to be done once. For dependencies that do not have any
+``.patch`` files in their ``lib/ext`` directory the only required step is
+cloning the repo and checking out the correct branch.
+
+.. code-block:: bash
+
+ cd <Mbed Crypto base folder>
+ git clone https://github.com/ARMmbed/mbedtls
+ cd mbedtls
+ git checkout <MBEDCRYPTO_VERSION from config_default.cmake>
+ git apply <TF-M base folder>/trusted-firmware-m/lib/ext/mbedcrypo/*.patch
+
+.. Note::
+ - <Mbed Crypto base folder> does not need to have any fixed posisition related
+ to the TF-M repo.
+
+Build TF-M
+----------
+
+With new cmake syntax
+
+.. code-block:: bash
+
+ cd <base folder>
+ cd trusted-firmware-m
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
+ cmake --build cmake_build -- install
+
+Alternately using traditional cmake syntax
+
+.. code-block:: bash
+
+ cd <base folder>
+ cd trusted-firmware-m
+ mkdir cmake_build
+ cd cmake_build
+ cmake .. -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
+ make install
+
--------------
*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_sw_requirement.rst b/docs/getting_started/tfm_sw_requirement.rst
index fdc2d33..673e4e7 100644
--- a/docs/getting_started/tfm_sw_requirement.rst
+++ b/docs/getting_started/tfm_sw_requirement.rst
@@ -81,14 +81,16 @@
The build-system is CMake based and supports the following versions:
- - 3.7
- - 3.10
- - 3.11
- - 3.12
- 3.13
- 3.14
+ - 3.15
+ - 3.16
+ - 3.17
+ - 3.18
.. Note::
+ - IAR requires version 3.14 or later.
+ - ARMClang requires version 3.15 or later.
- Please use the latest build version available (i.e. 3.7.2 instead of
3.7.0).
While it is preferable to use the newest version this is not required
@@ -98,7 +100,6 @@
https://cmake.org/files.
- For Cygwin users, please use a native windows CMake version
instead of the version installed with Cygwin.
- - IAR requires version 3.14 or later.
***************************
Supported GNU make versions
diff --git a/docs/getting_started/tfm_user_guide.rst b/docs/getting_started/tfm_user_guide.rst
index 992035c..8386eab 100644
--- a/docs/getting_started/tfm_user_guide.rst
+++ b/docs/getting_started/tfm_user_guide.rst
@@ -42,8 +42,8 @@
--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
+ --application cpu0=<build_dir>/bin/tfm_s.axf \
+ --data cpu0=<build_dir>/bin/tfm_ns.bin@0x00100000
Example application and regression tests with BL2 bootloader
------------------------------------------------------------
@@ -55,8 +55,8 @@
.. 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
+ --application cpu0=<build_dir>/bin/bl2.axf \
+ --data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10080000
Test software upgrade with BL2 bootloader
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -68,7 +68,7 @@
.. code-block:: bash
- --data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
+ --data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10180000
To run the example code on SSE 200 FPGA on MPS2 board
=====================================================
@@ -88,8 +88,8 @@
Example application
-------------------
-#. Copy ``mcuboot.bin`` and ``tfm_sign.bin`` files from
- ``<build_dir>/install/outputs/AN521/`` to
+#. Copy ``bl2.bin`` and ``tfm_s_ns_signed.bin`` files from
+ ``<build_dir>/bin`` to
``<MPS2 device name>/SOFTWARE/``
#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Update the ``AN521/images.txt`` file as follows::
@@ -98,9 +98,9 @@
[IMAGES]
TOTALIMAGES: 2 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x10000000
- IMAGE0FILE: \Software\mcuboot.bin ; BL2 bootloader
+ IMAGE0FILE: \Software\bl2.bin ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
- IMAGE1FILE: \Software\tfm_sign.bin ; TF-M example application binary blob
+ IMAGE1FILE: \Software\tfm_s_ns_signed.bin ; TF-M example application binary blob
#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Unmount/eject the ``<MPS2 device name>`` unit
@@ -159,7 +159,7 @@
Example application without BL2 bootloader
------------------------------------------
#. Copy ``tfm_s.bin`` and ``tfm_ns.bin`` files from
- ``<build_dir>/install/outputs/AN521/`` to
+ ``<build_dir>/bin`` to
``<MPS2 device name>/SOFTWARE/``
#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Update the ``AN521/images.txt`` file as follows::
@@ -220,38 +220,38 @@
Example application with BL2 bootloader
=======================================
-#. Create a unified hex file comprising of both ``mcuboot.bin`` and
- ``tfm_sign.bin``.
+#. Create a unified hex file comprising of both ``bl2.bin`` and
+ ``tfm_s_ns_signed.bin``.
- For Musca-A
- Windows::
- srec_cat.exe install\outputs\MUSCA_A\mcuboot.bin -Binary -offset 0x200000 install\outputs\MUSCA_A\tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+ srec_cat.exe bin\bl2.bin -Binary -offset 0x200000 bin\tfm_s_ns_signed.bin -Binary -offset 0x220000 -o tfm.hex -Intel
- Linux::
- srec_cat install/outputs/MUSCA_A/mcuboot.bin -Binary -offset 0x200000 install/outputs/MUSCA_A/tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+ srec_cat bin/bl2.bin -Binary -offset 0x200000 bin/tfm_s_ns_signed.bin -Binary -offset 0x220000 -o tfm.hex -Intel
- For Musca-B1
- Windows::
- srec_cat.exe install\outputs\MUSCA_B1\mcuboot.bin -Binary -offset 0xA000000 install\outputs\MUSCA_B1\tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+ srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 bin\tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
- Linux::
- srec_cat install/outputs/MUSCA_B1/mcuboot.bin -Binary -offset 0xA000000 install/outputs/MUSCA_B1/tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+ srec_cat bin/bl2.bin -Binary -offset 0xA000000 bin/tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
- For Musca-S1
- Windows::
- srec_cat.exe install\outputs\MUSCA_S1\mcuboot.bin -Binary -offset 0xA000000 install\outputs\MUSCA_S1\tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+ srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 bin\tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
- Linux::
- srec_cat install/outputs/MUSCA_S1/mcuboot.bin -Binary -offset 0xA000000 install/outputs/MUSCA_S1/tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+ srec_cat bin/bl2.bin -Binary -offset 0xA000000 bin/tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
#. Power up the Musca board by connecting it to a computer with a USB lead.
Press the ``PBON`` button if the green ``ON`` LED does not immediately turn
@@ -411,11 +411,11 @@
- Windows::
- srec_cat.exe install\outputs\MUSCA_B1\tfm_s.bin -Binary -offset 0xA000000 install\outputs\MUSCA_B1\tfm_ns.bin -Binary -offset 0xA080000 -o tfm.hex -Intel
+ srec_cat.exe bin\tfm_s.bin -Binary -offset 0xA000000 bin\tfm_ns.bin -Binary -offset 0xA080000 -o tfm.hex -Intel
- Linux::
- srec_cat install/outputs/MUSCA_B1/tfm_s.bin -Binary -offset 0xA000000 install/outputs/MUSCA_B1/tfm_ns.bin -Binary -offset 0xA080000 -o tfm.hex -Intel
+ srec_cat bin/tfm_s.bin -Binary -offset 0xA000000 bin/tfm_ns.bin -Binary -offset 0xA080000 -o tfm.hex -Intel
********************************************************
Execute TF-M example and regression tests on MPS3 boards
@@ -446,7 +446,7 @@
Example application
-------------------
-#. Copy ``mcuboot.bin`` and ``tfm_sign.bin`` files from
+#. Copy ``bl2.bin`` and ``tfm_s_ns_signed.bin`` files from
build dir to ``<MPS3 device name>/SOFTWARE/``
#. Open ``<MPS3 device name>/MB/HBI0309B/AN524/images.txt``
#. Update the ``images.txt`` file as follows::
@@ -458,10 +458,10 @@
IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
IMAGE0ADDRESS: 0x00000000 ;Please select the required executable program
- IMAGE0FILE: \SOFTWARE\mcuboot.bin
+ IMAGE0FILE: \SOFTWARE\bl2.bin
IMAGE1UPDATE: AUTO
IMAGE1ADDRESS: 0x00040000
- IMAGE1FILE: \SOFTWARE\tfm_sign.bin
+ IMAGE1FILE: \SOFTWARE\tfm_s_ns_signed.bin
#. Close ``<MPS3 device name>/MB/HBI0309B/AN524/images.txt``
#. Unmount/eject the ``<MPS3 device name>`` unit
diff --git a/docs/reference/services/core_test_services_integration_guide.rst b/docs/reference/services/core_test_services_integration_guide.rst
index ee0b3fa..6b28a72 100644
--- a/docs/reference/services/core_test_services_integration_guide.rst
+++ b/docs/reference/services/core_test_services_integration_guide.rst
@@ -11,23 +11,10 @@
defined in the ``test/test_services`` folder.
Currently there are two test suites, *interactive* and *positive*. The positive
-test suite can be run, by building using ``ConfigCoreTest.cmake`` as cmake
-config file. The interactive test suite is only available by manually setting
-CORE_TEST_INTERACTIVE to ON in the following block in ``CommonConfig.cmake``:
-
-.. code-block:: cmake
-
- if (CORE_TEST)
- set(CORE_TEST_POSITIVE ON)
- set(CORE_TEST_INTERACTIVE OFF)
- endif()
-
-A platform can skip Core Test by setting ``CORE_TEST`` to ``OFF`` in its cmake
-configuration file, even though ``CORE_TEST`` is enabled by default in current
-configuration.
-
-After making the change, the tests can be run by building using
-``ConfigCoreTest.cmake`` as cmake config file.
+test suite can be run by building using non-secure regression tests using
+``-DTEST_NS``. The interactive test suite is only available by setting
+``-DTFM_INTERACTIVE_TEST=ON`` while the non-secure regression testsuite is
+enabled.
**************************
Platform specific features
@@ -115,4 +102,4 @@
--------------
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*