Docs: Update for new build system
Update docs to use new build commands. Document new build options Remove
mentions of manifest generation. Remove mentions of hex file generation.
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I01c49c462403468c3e3650534893160cdfb6f5c5
diff --git a/docs/design_documents/profiles/tfm_profile_medium.rst b/docs/design_documents/profiles/tfm_profile_medium.rst
index a17b41b..cb744d4 100644
--- a/docs/design_documents/profiles/tfm_profile_medium.rst
+++ b/docs/design_documents/profiles/tfm_profile_medium.rst
@@ -204,9 +204,9 @@
Overview
========
-The basic idea is to add dedicated top-level CMake configuration files under
-folder ``configs`` for TF-M Profile Medium default configuration, as the same as
-Profile Small does.
+The basic idea is to add dedicated profile CMake configuration files under
+folder ``config/profile`` for TF-M Profile Medium default configuration, the
+same as Profile Small does.
The top-level Profile Medium config file collects all the necessary
configuration flags and set them to default values, to explicitly enable the
@@ -216,46 +216,11 @@
A platform/use case can provide a configuration extension file to overwrite
Profile Medium default setting and append other configurations.
This configuration extension file can be added via parameter
-``TFM_PROFILE_CONFIG_EXT`` in build command line. The top-level config file will
-include the device configuration extension file to load platform/use case
-specific configurations.
+``TFM_EXTRA_CONFIG_PATH`` in build command line.
-The overall build flow of Profile Medium is shown as the flowchart below.
-
-.. uml::
-
- @startuml
-
- title Overall build flow
-
- start
-
- :Profile Medium CMake file;
- note left
- Top-level CMake config file under ""configs"".
- Set configurations to default values.
- endnote
-
- if (Platform config\nextension specified?) then (Yes)
- :Include platform specific\nconfig extension file;
- note left
- Platform specific configuration extension file
- is provided via ""TFM_PROFILE_CONFIG_EXT"" in
- build command line.
- endnote
-
- :Overwrite default configurations;
- else (No)
- endif
-
- :CommonConfig.cmake;
- note left
- Normal building sequence
- endnote
-
- stop
-
- @enduml
+The behaviour of the Profile Medium build flow (particularly the order of
+configuration loading and overriding) can be found at
+:ref:`tfm_cmake_configuration`
The details of configurations will be covered in each module in
`Implementation details`_.
@@ -268,80 +233,89 @@
Top-level configuration files
-----------------------------
-Profile Medium provides ``ConfigDefaultProfileM`` as a default top-level
-configuration file without test cases.
-
-The firmware framework configurations in ``ConfigDefaultProfileM`` are shown
-below.
+The firmware framework configurations in ``config/profile/profile_medium`` are
+shown below.
.. table:: Config flags in Profile Medium top-level CMake config file
:widths: auto
:align: center
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+=====================================+=====================================+
- | ``TFM_LVL`` | ``2`` | Select level 2 isolation |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``CORE_IPC`` | ``True`` | Select IPC model |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``MBEDTLS_CONFIG_FILE`` | ``tfm_profile_m_mbedcrypto_config`` | Default Mbed Crypto config file for |
- | | | Profile Medium under |
- | | | ``platform/ext/common`` |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
- +--------------------------------------------+-------------------------------------+-------------------------------------+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PSA_API`` | ``True`` | Select IPC model |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
.. [1] PS service is enabled by default. Platforms without off-chip storage
devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
service. See `Protected Storage Secure Partition`_ for details.
-Profile Medium provides ``ConfigRegressionProfileM`` as the default top-level
-configuration file with regression tests.
+.. Note::
-The table below collects ``ConfigRegressionProfileM`` major configurations
-which are not covered or different from those in ``ConfigDefaultProfileM``.
+ Where a configuration is the same as the default in
+ ``config/config_default.cmake``, it is omitted from the profile configuration
+ file.
-.. table:: Major config flags in Profile Medium top-level CMake config file with tests
+Test configuration
+^^^^^^^^^^^^^^^^^^
+
+Standard regression test configuration applies. This means that enabling
+regression testing via
+
+``-DTEST_S=ON -DTEST_NS=ON``
+
+Will enable testing for all enabled partitions. See above for details of enabled
+partitions. Because Profile Medium enables IPC mode, the IPC tests are also
+enabled.
+
+Some cryptography tests are disabled due to the reduced Mbed Crypto config.
+
+.. table:: TFM options in Profile Medium top-level CMake config file
:widths: auto
:align: center
- +------------------+---------------+------------------------+
- | Configs | Default value | Descriptions |
- +==================+===============+========================+
- | ``REGRESSION`` | ``ON`` | Enable Regression test |
- +------------------+---------------+------------------------+
- | ``CORE_TEST`` | ``ON`` | Enable Core test |
- +------------------+---------------+------------------------+
- | ``IPC_TEST`` | ``ON`` | Enable IPC test |
- +------------------+---------------+------------------------+
- | ``PSA_API_TEST`` | ``OFF`` | Disable PSA API test |
- +------------------+---------------+------------------------+
-
-The test cases should be disabled in ``ConfigRegressionProfileM`` if the
-corresponding feature is not selected in Profile Medium by default.
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
Device configuration extension
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To change default configurations and add platform specific configurations,
-a platform can set the path to its own configuration extension file in parameter
-``TFM_PROFILE_CONFIG_EXT`` in command line.
-
-A platform can also add its device specific configurations into its specific
-CMake file under ``platform/ext/`` folder.
+a platform can add a platform configuration file at
+``platform/ext<TFM_PLATFORM>/config.cmake``
Crypto service configurations
-----------------------------
@@ -356,10 +330,9 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^
TF-M Profile Medium adds a dedicated Mbed Crypto config file
-``tfm_profile_m_mbedcrypto_config.h`` under ``platform/ext/common``.
-TF-M Profile Medium specifies ``tfm_profile_m_mbedcrypto_config.h`` as the
-default Mbed Crypto config in ``MBEDTLS_CONFIG_FILE`` in top-level CMake config
-file, instead of the common one ``tfm_mbedcrypto_config.h`` [CRYPTO-DESIGN]_.
+``tfm_mbedcrypto_config_profile_medium.h`` at
+``/lib/ext/mbedcrypto/mbedcrypto_config``
+file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [CRYPTO-DESIGN]_.
Major Mbed Crypto configurations are set as listed below:
@@ -376,10 +349,12 @@
Other configurations can be selected to optimize the memory footprint of Crypto
module.
-A device/use case can replace Profile Medium default Mbed Crypto config file
-with its specific one to overwrite the default configurations. Alternatively, a
-device can overwrite the configurations by appending a config file via
-``MBEDTLS_USER_CONFIG_FILE``.
+A device/use case can append an extra config header to the Profile Medium
+default Mbed Crypto config file. This can be done by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform
+config file ``platform/ext<TFM_PLATFORM>/config.cmake``. This cmake variable is
+a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as
+it keeps all configuration in cmake.
Internal Trusted Storage configurations
---------------------------------------
@@ -405,16 +380,14 @@
If platforms don't integrate any off-chip storage device, platforms can disable
PS in platform specific configuration extension file via
-``TFM_PROFILE_CONFIG_EXT``.
-Profile Medium provides a configuration extension file example
-``profile_m_config_ext_ps_disabled.cmake`` which disables PS service.
+``platform/ext<TFM_PLATFORM>/config.cmake``.
BL2 setting
-----------
Profile Medium enables MCUBoot provided by TF-M by default. A platform can
overwrite this configuration by disabling MCUBoot in its configuration extension
-file or in its specific CMake file under ``platform/ext/`` folder.
+file ``platform/ext<TFM_PLATFORM>/config.cmake``.
If MCUBoot provided by TF-M is enabled, multiple image boot is selected by
default in TF-M Profile Medium top-level CMake config file.
@@ -433,11 +406,8 @@
Building Profile Medium
=======================
-To build Profile Medium, argument ``PROJ_CONFIG`` in build command line should
-be set to following config files
-
- - ``ConfigDefaultProfileM.cmake``
- - ``ConfigRegressionProfileM.cmake``.
+To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be
+set to ``profile_medium``.
Take AN521 as an example:
@@ -446,42 +416,40 @@
.. code-block:: bash
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigDefaultProfileM.cmake` \
- -DTARGET_PLATFORM=AN521 \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ cd <TFM root dir>
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DCMAKE_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_medium \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ ../
+ cmake --build ./ -- install
The following commands build Profile Medium with regression test cases on
**AN521** with build type **MinSizeRel**, built by **Armclang**.
.. code-block:: bash
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegressionProfileM.cmake` \
- -DTARGET_PLATFORM=AN521 \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ cd <TFM root dir>
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DCMAKE_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_medium \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ -DTEST_S=ON -DTEST_NS=ON \
+ ../
+ cmake --build ./ -- install
+
+.. Note::
+
+ - For devices with more contrained memory and flash requirements, it is
+ possible to build with either only TEST_S enabled or only TEST_NS enabled.
+ This will decrease the size of the test images. Note that both test suites
+ must still be run to ensure correct operation.
More details of building instructions and parameters can be found TF-M build
instruction guide [TFM-BUILD]_.
-The following commands include platform specific configuration extension file
-via ``TFM_PROFILE_CONFIG_EXT`` in command line. ``TFM_PROFILE_CONFIG_EXT`` can
-be an absolute path or a relative one to TF-M code root directory.
-The configuration extension file ``profile_m_config_ext_ps_disabled.cmake`` in
-the example below overwrites and disables PS service.
-
-.. code-block:: bash
-
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigDefaultProfileM.cmake` \
- -DTARGET_PLATFORM=AN521 \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DCOMPILER=ARMCLANG \
- -DTFM_PROFILE_CONFIG_EXT=configs/profile_m_config_ext_ps_disabled.cmake ../
- cmake --build ./ -- install
-
-
*********
Reference
*********
diff --git a/docs/design_documents/profiles/tfm_profile_small.rst b/docs/design_documents/profiles/tfm_profile_small.rst
index 051dd3d..c500f50 100644
--- a/docs/design_documents/profiles/tfm_profile_small.rst
+++ b/docs/design_documents/profiles/tfm_profile_small.rst
@@ -331,147 +331,69 @@
Overview
========
-The basic idea is to add dedicated top-level CMake configuration files under
-folder ``configs`` for TF-M Profile Small default configuration.
+The basic idea is to add dedicated profile CMake configuration files under
+folder ``config/profile`` for TF-M Profile Small default configuration.
-The top-level Profile Small config file collects all the necessary configuration
-flags and set them to default values, to explicitly enable the features required
-in TF-M Profile Small and disable the unnecessary ones, during TF-M build.
-
-An alternative option is to set only a global flag in top-level Profile Small
-CMake file and configure the remaining configurations in dedicated CMake files
-of each module/secure service. However, since configuration flags are
-distributed in multiple CMake files, it will become difficult for a platform/use
-case to overwrite default configurations.
-Therefore it is more reasonable to explicitly set all critical configurations in
-a top-level CMake file.
+The top-level Profile Small config file collects all the necessary
+configuration flags and set them to default values, to explicitly enable the
+features required in Profile Small and disable the unnecessary ones, during
+TF-M build.
A platform/use case can provide a configuration extension file to overwrite
Profile Small default setting and append other configurations.
This configuration extension file can be added via parameter
-``TFM_PROFILE_CONFIG_EXT`` in build command line. The top-level config file will
-include the device configuration extension file to load platform/use case
-specific configurations.
+``TFM_EXTRA_CONFIG_PATH`` in build command line.
-The overall build flow of Profile Small is shown as the flowchart below.
+The behaviour of the Profile Small build flow (particularly the order of
+configuration loading and overriding) can be found at
+:ref:`tfm_cmake_configuration`
-.. uml::
-
- @startuml
-
- title Overall build flow
-
- start
-
- :Profile Small CMake file;
- note left
- Top-level CMake config file under ""configs"".
- Set configurations to default values.
- endnote
-
- if (Platform config\nextension specified?) then (Yes)
- :Include platform specific\nconfig extension file;
- note left
- Platform specific configuration extension file
- is provided via ""TFM_PROFILE_CONFIG_EXT"" in
- build command line.
- endnote
-
- :Overwrite default configurations;
- else (No)
- endif
-
- :CommonConfig.cmake;
- note left
- Normal building sequence
- endnote
-
- stop
-
- @enduml
-
-The control flags set in the top-level Profile Small config file are listed
-below.
-The details will be covered in each module in `Implementation details`_.
-
-.. list-table:: Config flags in Profile S top-level CMake config file
- :widths: 20 15 30
- :header-rows: 1
-
- * - Configs
- - Default value
- - Descriptions
- * - ``CORE_IPC``
- - ``False``
- - Library model is selected
- * - ``TFM_LVL``
- - ``1``
- - Level 1 isolation
- * - ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE``
- - ``ON``
- - Enable ITS SP
- * - ``ITS_BUF_SIZE``
- - ``32``
- - ITS internal transient buffer size
- * - ``TFM_PARTITION_CRYPTO``
- - ``ON``
- - Enable Crypto service
- * - ``CRYPTO_ASYMMETRIC_MODULE_DISABLED``
- - ``ON``
- - Disable asymmetric cipher in Crypto service
- * - ``CRYPTO_AEAD_MODULE_DISABLED``
- - ``OFF``
- - Enable AEAD in Crypto service
- * - ``MBEDTLS_CONFIG_FILE``
- - ``tfm_profile_s_mbedcrypto_config``
- - Default mbed-crypto config file for Profile Small under
- ``platform/ext/common``
- * - ``TFM_PARTITION_AUDIT_LOG``
- - ``OFF``
- - Disable Audit Logging Logging service
- * - ``TFM_PARTITION_SECURE_STORAGE``
- - ``OFF``
- - Disable Protected Storage service
- * - ``TFM_PARTITION_INITIAL_ATTESTATION``
- - ``ON``
- - Enable Initial Attestation service
- * - ``SYMMETRIC_INITIAL_ATTESTATION``
- - ``ON``
- - Select Initial Attestation based on symmetric key algorithms
- * - ``TFM_PARTITION_PLATFORM``
- - ``OFF``
- - Disable Platform service
-
-Test cases settings in top-level Profile Small config files are listed below.
-The ``Default config`` stands for configuration without tests and the
-``Regression config`` stands for configuration with regression tests.
-
-.. list-table:: Test config flags in Profile S top-level CMake config file
- :widths: 20 20 15 15
- :header-rows: 1
-
- * - Test cases
- - Configs
- - Default config
- - Regression config
- * - Regression test
- - ``REGRESSION``
- - ``OFF``
- - ``ON``
- * - Core test
- - ``CORE_TEST``
- - ``OFF``
- - ``ON``
- * - PSA API test
- - ``PSA_API_TEST``
- - ``OFF``
- - ``OFF``
+The details of configurations will be covered in each module in
+`Implementation details`_.
Implementation details
======================
This section discusses the details of Profile Small implementation.
+Top-level configuration files
+-----------------------------
+
+The firmware framework configurations in ``config/profile/profile_small`` are
+shown below.
+
+.. table:: TFM options in Profile Small top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_ISOLATION_LEVEL`` | ``1`` | Select level 2 isolation |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PSA_API`` | ``FALSE`` | Select IPC model |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h`` | Mbed Crypto config file path |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``CRYPTO_ASYMMETRIC_MODULE_DISABLED`` | ``ON`` | Disable asymmetric crypto |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``SYMMETRIC_INITIAL_ATTESTATION`` | ``ON`` | Enable symmetric attestation |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PROTECTED_STORAGE`` | ``OFF`` | Enable PS service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PLATFORM`` | ``OFF`` | Enable TF-M Platform SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
.. note ::
**Implementation note**
@@ -480,29 +402,48 @@
setting.
Dedicated optimization on memory footprint is not covered in this document.
-Top-level Profile Small CMake config file
------------------------------------------
+Test configuration
+^^^^^^^^^^^^^^^^^^
-There are two top-level Profile Small CMake config files under folder
-``configs``.
+Standard regression test configuration applies. This means that enabling
+regression testing via
-- ``ConfigDefaultProfileS.cmake`` completes Profile Small default configurations
- without test cases.
-- ``ConfigRegressionProfileS.cmake`` enables regression and core test cases for
- the features defined Profile Small, besides default configurations.
+``-DTEST_S=ON -DTEST_NS=ON``
-The details of configuration control flags set in top-level configuration file
-are listed in following sections.
+Will enable testing for all enabled partitions. See above for details of enabled
+partitions. Because Profile Small does not enable IPC mode, the IPC tests are
+not enabled.
+
+Some cryptography tests are disabled due to the reduced Mbed Crypto config.
+
+.. table:: TFM options in Profile Small top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
Device configuration extension
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To overwrite default configurations and add platform specific configurations,
-a platform can set the path to its own configuration extension file in parameter
-``TFM_PROFILE_CONFIG_EXT`` in command line.
-
-A platform can also add its device specific configurations into its specific
-CMake file under ``platform/ext/`` folder.
+To change default configurations and add platform specific configurations,
+a platform can add a platform configuration file at
+``platform/ext<TFM_PLATFORM>/config.cmake``
TF-M framework setting
----------------------
@@ -531,10 +472,9 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^
TF-M Profile Small adds a dedicated Mbed Crypto config file
-``tfm_profile_s_mbedcrypto_config.h`` under ``platform/ext/common``.
-TF-M Profile Small specifies ``tfm_profile_s_mbedcrypto_config.h`` as the
-default Mbed Crypto config in ``MBEDTLS_CONFIG_FILE`` in top-level CMake config
-file, instead of the common one ``tfm_mbedcrypto_config.h`` [10]_.
+``tfm_mbedcrypto_config_profile_small.h`` at
+``/lib/ext/mbedcrypto/mbedcrypto_config``
+file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [10]_.
Major Mbed Crypto configurations are set as listed below:
@@ -549,10 +489,12 @@
Other configurations can be selected to optimize the memory footprint of Crypto
module.
-A device/use case can replace Profile Small default Mbed Crypto config file with
-its specific one to overwrite the default configurations. Alternatively, a
-device can overwrite the configurations by appending a config file via
-``MBEDTLS_USER_CONFIG_FILE``.
+A device/use case can append an extra config header to the Profile Small
+default Mbed Crypto config file. This can be done by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform
+config file ``platform/ext<TFM_PLATFORM>/config.cmake``. This cmake variable is
+a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as
+it keeps all configuration in cmake.
Internal Trusted Storage configurations
---------------------------------------
@@ -601,44 +543,35 @@
Profile Small enables MCUBoot provided by TF-M by default. A platform can
overwrite this configuration by disabling MCUBoot in its configuration extension
-file or in its specific CMake file under ``platform/ext/`` folder.
+file ``platform/ext<TFM_PLATFORM>/config.cmake``.
If MCUBoot provided by TF-M is enabled, single image boot is selected in TF-M
Profile Small top-level CMake config file.
-The following table lists the configurations specified in Profile Small
-top-level config file for MCUBoot provided by TF-M.
-
-.. list-table:: MCUBoot config flags in Profile S top-level CMake config file
- :widths: 30 15 30
- :header-rows: 1
-
- * - Configs
- - Default value
- - Descriptions
- * - ``BL2``
- - ``True``
- - MCUBoot is enabled
- * - ``MCUBOOT_IMAGE_NUMBER``
- - ``1``
- - Single image boot
-
If a device implements its own boot loader, the configurations are
implementation defined.
+.. table:: BL2 options in Profile Small top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``BL2`` | ``ON`` | Enable MCUBoot bootloader |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``MCUBOOT_IMAGE_NUMBER`` | ``1`` | Combine S and NS images |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
****************
Platform support
****************
-To enable Profile Small on a platform, the platform specific CMake file should
-be added into the platform support list in top-level Profile Small CMake config
-file.
-
Building Profile Small
======================
-To build Profile Small, argument ``PROJ_CONFIG`` in build command line should be
-set to ``ConfigRegressionProfileS.cmake`` or ``ConfigRegressionProfileS.cmake``.
+To build Profile Small, argument ``TFM_PROFILE`` in build command line should be
+set to ``profile_small``.
Take AN521 as an example.
@@ -647,39 +580,40 @@
.. code-block:: bash
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigDefaultProfileS.cmake` \
- -DTARGET_PLATFORM=AN521 \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ cd <TFM root dir>
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DCMAKE_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_small \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ ../
+ cmake --build ./ -- install
The following commands build Profile Small with regression test cases on **AN521**
with build type **MinSizeRel**, built by **Armclang**.
.. code-block:: bash
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegressionProfileS.cmake` \
- -DTARGET_PLATFORM=AN521 \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ cd <TFM root dir>
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DCMAKE_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_small \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ -DTEST_S=ON -DTEST_NS=ON \
+ ../
+ cmake --build ./ -- install
+
+.. Note::
+
+ - For devices with more contrained memory and flash requirements, it is
+ possible to build with either only TEST_S enabled or only TEST_NS enabled.
+ This will decrease the size of the test images. Note that both test suites
+ must still be run to ensure correct operation.
More details of building instructions and parameters can be found TF-M build
instruction guide [11]_.
-The following commands include platform specific configuration extension file
-via ``TFM_PROFILE_CONFIG_EXT`` in command line. ``TFM_PROFILE_CONFIG_EXT`` can
-be an absolute path or a relative one to TF-M code root directory.
-
-.. code-block:: bash
-
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigDefaultProfileS.cmake` \
- -DTARGET_PLATFORM=AN521 \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DCOMPILER=ARMCLANG \
- -DTFM_PROFILE_CONFIG_EXT=path/to/config_ext_file ../
- cmake --build ./ -- install
-
*********
Reference
*********
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
index 2fb81c4..a270d46 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -4,175 +4,368 @@
Please make sure you have all required software installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.
-The external dependecies are briefly listed in the
-:ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.
-
-The configuration-table
-:ref:`docs/getting_started/tfm_build_instruction:Configuring the build` section
-explains all the supported build parameters:
-
****************
TF-M build steps
****************
TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
build environment. The instructions are below.
-.. Note::
-
- It is recommended to build each different build configurations in separate
- directories.
-
Getting the source-code
=======================
.. code-block:: bash
cd <base folder>
git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
- git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.23.0
- git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git
- git clone https://github.com/JuulLabs-OSS/mcuboot.git -b v1.6.0
+
+Dependency management is now handled by cmake. If you wish to alter this
+behaviour, see :ref:`docs/getting_started/tfm_build_instruction:Manual
+dependency management`
.. Note::
- For building with Armclang compiler version 6.10.0, please follow the note
+
+ - For building with Armclang compiler version 6.10.0, please follow the note
in :ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.
-
-.. Note::
- For building with the IAR toolchain, please see the notes in
+ - For building with the IAR toolchain, please see the notes in
:doc:`software requirements <tfm_build_instruction_iar>`
-Build steps for the AN521 target platform:
-==========================================
+.. _tfm_cmake_configuration:
+
+Cmake configuration
+===================
+
+All configuration options are provided by cmake variables, and their default
+values, with docstrings, can be found in ``config/config_default.cmake``.
+
+Configuration is provided in multiple stages, with multiple priorities.
+
+ 1. ``config/config_default.cmake`` is loaded.
+ 2. Command-line variable settings are applied, overriding all previous settings.
+ 3. If it exists, CMAKE_BUILD_TYPE specific config is applied from ``config/build_type/<build_type>.cmake``, overriding all previous settings.
+ 4. If it exists, TFM Profile specific config is applied from ``config/profile/<tfm_profile>.cmake``, overriding all previous settings.
+ 5. Target specific config from ``platform/ext/target/<target_platform>/config.cmake`` is applied, overriding all previous settings.
+ 6. If the ``TFM_EXTRA_CONFIG_PATH`` variable has been set, that file is loaded and overrides all previous settings.
+
+.. Warning::
+ This means that command-line settings are not applied when they conflict
+ with required platform settings. If it is required to override platform
+ settings (this is not usually a good idea) then TFM_EXTRA_CONFIG_PATH should be
+ used.
+
+Required cmake parameters for building TF-M
+-------------------------------------------
+
++----------------------+-------------------------------------------------------+
+| Parameter | Description |
++======================+=======================================================+
+| TFM_PLATFORM | The target platform as a path from the base directory |
+| | ``/platform/ext/target`` |
++----------------------+-------------------------------------------------------+
+| CMAKE_TOOLCHAIN_FILE | The path to the toolchain file that corresponds to |
+| | the desired compiler. |
++----------------------+-------------------------------------------------------+
+
+By default release configuration builds. Alternate build types can be controlled
+by the CMAKE_BUILD_TYPE variable.
+
+Build type
+----------
+
+Build type is controlled by the ``CMAKE_BUILD_TYPE`` variable. The possible
+types are:
+
+ - ``Debug``
+ - ``Relwithdebinfo``
+ - ``Release``
+ - ``Minsizerel``
+
+``Release`` is default.
+
+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
+produce the smallest code, and hence is often a good idea on RAM or flash
+constrained systems.
+
+Other cmake parameters
+----------------------
+
+The full list of default options is in ``config/config_default.cmake``. Several
+important options are listed below.
+
+
++---------------------+----------------------------------------+---------------+
+| Parameter | Description | Default value |
++=====================+========================================+===============+
+| BL2 | Build level 2 secure bootloader. | ON |
++---------------------+----------------------------------------+---------------+
+| NS | Build NS app. Required for test code. | ON |
++---------------------+----------------------------------------+---------------+
+| TFM_PSA_API | Use PSA api (IPC mode) instead of | OFF |
+| | secure library mode. | |
++---------------------+----------------------------------------+---------------+
+| TFM_ISOLATION_LEVEL | Set TFM isolation level. | 1 |
++---------------------+----------------------------------------+---------------+
+| TFM_PROFILE | Set TFM profile. | |
++---------------------+----------------------------------------+---------------+
+| TEST_S | Build secure regression tests. | OFF |
++---------------------+----------------------------------------+---------------+
+| TEST_NS | Build non-secure regression tests. | OFF |
++---------------------+----------------------------------------+---------------+
+| TEST_PSA_API | Build PSA API TESTS for the given | |
+| | suite. Takes a PSA api ``SUITE`` as an | |
+| | argument (``CRYPTO`` etc). | |
++---------------------+----------------------------------------+---------------+
+
+Regression test configuration
+-----------------------------
+
+Regression test configuration is controlled entirely by the ``TEST_S`` and
+``TEST_NS`` cmake variables.
+
+If regression testing is enabled, it will then enable all tests for the enabled
+secure partitions. If IPC mode is enabled via ``TFM_PSA_API`` the IPC tests will
+be enabled. QCBOR and T_COSE tests are linked to the Initial Attestation
+partition, as they are only used there. Multicore tests will be enabled if
+``TFM_MULTI_CORE_TOPOLOGY`` is enabled.
+
+Some cryptographic tests can be enabled and disabled. This is done to prevent
+false failures from being reported when a smaller Mbed Crypto config is being
+used which does not support all features.
+
++-----------------------------+-------------------------------------+---------------+
+| Parameter | Description | Default value |
++=============================+=====================================+===============+
+| TFM_CRYPTO_TEST_ALG_CBC | Test CBC cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CCM | Test CCM cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CFB | Test CFB cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CTR | Test CTR cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_GCM | Test GCM cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_SHA_512 | Test SHA-512 cryptography algorithm | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_HKDF | Test SHA-512 cryptography algorithm | ON |
++-----------------------------+-------------------------------------+---------------+
+
+
+PSA test configuration
+----------------------
+
+PSA tests are configured by using the ``TEST_PSA_API`` cmake variable. The
+variable should be set to the name of the test suite that is desired. It is
+_not_ supported to set both ``TEST_PSA_API`` and ``TEST_S`` or ``TEST_NS``.
+
+The Developer api tests are:
+ - ``CRYPTO``
+ - ``INITIAL_ATTESTATION``
+ - ``STORAGE`` (INTERNAL_TRUSTED_STORAGE and PROTECTED_STORAGE)
+ - ``INTERNAL_TRUSTED_STORAGE``
+ - ``PROTECTED_STORAGE``
+
+The Firmware framework test suites are:
+ - ``IPC``
+
+Note that these map directly to the ``SUITE`` cmake variable used in the
+psa-arch-tests documentation.
+
+Migration from legacy buildsystem
+---------------------------------
+
+The previous (legacy) cmake buildsystem made use of separate configuration
+files, where now build options are controlled by variables. For ease of
+transition, a table below is provided that maps the legacy files to the current
+variables, in the format of cmake command line parameters.
+
++------------------------------------------+-----------------------------------+
+| File | Cmake command line |
++==========================================+===================================+
+| ConfigDefault.cmake | <No options> |
++------------------------------------------+-----------------------------------+
+| ConfigCoreIPC.cmake | -DTFM_PSA_API=ON |
++------------------------------------------+-----------------------------------+
+| ConfigCoreIPCTfmLevel2.cmake | -DTFM_PSA_API=ON |
+| | -DTFM_ISOLATION_LEVEL=2 |
++------------------------------------------+-----------------------------------+
+| ConfigDefaultProfileS.cmake | -DTFM_PROFILE=profile_small |
++------------------------------------------+-----------------------------------+
+| ConfigDefaultProfileM.cmake | -DTFM_PROFILE=profile_medium |
++------------------------------------------+-----------------------------------+
+| ConfigRegression.cmake | -DTEST_NS=ON -DTEST_S=ON |
++------------------------------------------+-----------------------------------+
+| ConfigRegressionIPC.cmake | -DTEST_NS=ON -DTEST_S=ON |
+| | -DTFM_PSA_API=ON |
++------------------------------------------+-----------------------------------+
+| ConfigRegressionIPCTfmLevel2.cmake | -DTEST_NS=ON -DTEST_S=ON |
+| | -DTFM_PSA_API=ON |
+| | -DTFM_ISOLATION_LEVEL=2 |
++------------------------------------------+-----------------------------------+
+| ConfigRegressionProfileS.cmake | -DTFM_PROFILE=profile_small |
+| | -DTEST_NS=ON -DTEST_S=ON |
++------------------------------------------+-----------------------------------+
+| ConfigRegressionProfileM.cmake | -DTFM_PROFILE=profile_medium |
+| | -DTEST_NS=ON -DTEST_S=ON |
++------------------------------------------+-----------------------------------+
+| ConfigPsaApiTest.cmake | -DTEST_PSA_API=<test_suite> |
++------------------------------------------+-----------------------------------+
+| ConfigPsaApiTestIPC.cmake | -DTEST_PSA_API=<test_suite> |
+| | -DTFM_PSA_API=ON |
++------------------------------------------+-----------------------------------+
+| ConfigPsaApiTestIPCTfmLevel2.cmake | -DTEST_PSA_API=<test_suite> |
+| | -DTFM_PSA_API=ON |
+| | -DTFM_ISOLATION_LEVEL=2 |
++------------------------------------------+-----------------------------------+
+| ConfigDefaultProfileM.cmake | -DTFM_PROFILE=profile_medium |
+| + profile_m_config_ext_ps_disabled.cmake | -DTFM_PARTITION_PS=OFF |
++------------------------------------------+-----------------------------------+
+
+There has also been some changes to the PSA manifest file generation. The files
+are now generated into a seperate tree in the ``<tfm build dir>/generated``
+directory. Therefore they have been removed from the source tree. Any changes
+should be made only to the template files.
+
+The api for the ``tools/tfm_parse_manifest_list.py`` script has also changed
+slightly. It is no longer required to be run manually as it is run as part of
+cmake.
+
+*******************
+TF-M build examples
+*******************
+
+Example: building TF-M for AN521 platform using GCC:
+====================================================
+.. 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
+ 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 ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
- cmake --build ./ -- install
+ cmake .. -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
+ make install
+
+.. Note::
+ Unix Makefiles is the default generator. Ninja is also supported by setting
+ -GNinja
+
+.. Note::
+
+ It is recommended to build each different build configuration in a separate
+ build directory.
Regression Tests for the AN521 target platform
==============================================
-*TF-M build regression tests on Linux*
+
+Regression tests can be build by using the TEST_S and TEST_NS settings. Either
+can be used in isolation or both can be used to enable both suites. All tests
+for all enabled partitions are run, along with IPC and Multicore tests if those
+features are enabled.
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- mkdir cmake_test
- cd cmake_test
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON
+ cmake --build cmake_build -- install
-*TF-M build regression tests on Windows*
+Alternately using traditional cmake syntax
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- mkdir cmake_test
- cd cmake_test
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ mkdir cmake_build
+ cd cmake_build
+ cmake .. -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON
+ make install
Build for PSA Developer API compliance tests
============================================
-The build system provides the support for linking with prebuilt PSA Developer
-API compliance NS test libraries when using the ``ConfigPsaApiTest.cmake``,
-``ConfigPsaApiTestIPC.cmake`` or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config
-file. The build system assumes that the PSA API compliance test suite is checked
-out at the same level of the TF-M root folder and the default name for the build
-folder has been used when compiling the PSA API compliance tests. Each set of
-tests for the Internal Trusted Storage, Protected Storage, Crypto and Attestation
-services needs to be enabled at the build configuration step by defining::
+The build system provides support for building and integrating the PSA API tests
+from https://github.com/ARM-software/psa-arch-tests. PSA API tests are
+controlled using the TEST_PSA_API variable. Enabling both regression tests and
+PSA API tests simultaneously is **not** supported.
- -DPSA_API_TEST_INTERNAL_TRUSTED_STORAGE=ON
- -DPSA_API_TEST_PROTECTED_STORAGE=ON
- -DPSA_API_TEST_STORAGE=ON
- -DPSA_API_TEST_CRYPTO=ON
- -DPSA_API_TEST_INITIAL_ATTESTATION=ON
+The value of the TEST_PSA_API variable is the suite to be run.
-respectively for the corresponding service. For example, to enable the PSA API
-tests for the Crypto service only:
+.. code-block::
+
+ -DTEST_PSA_API=INTERNAL_TRUSTED_STORAGE
+ -DTEST_PSA_API=PROTECTED_STORAGE
+ -DTEST_PSA_API=STORAGE
+ -DTEST_PSA_API=CRYPTO
+ -DTEST_PSA_API=INITIAL_ATTESTATION
+
+Respectively for the corresponding service. For example, to enable the PSA API
+tests for the Crypto service:
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- mkdir cmake_psa_test
- cd cmake_psa_test
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DTEST_PSA_API=CRYPTO
+ 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 -DTEST_PSA_API=CRYPTO
+ make install
Build for PSA FF (IPC) compliance tests
=======================================
-The build system assumes that the PSA FF compliance test suite is checked out
-at the same level of the TF-M root folder and the default name for the build
-folder has been used when compiling the PSA FF compliance tests.
+The build system provides support for building and integrating the PSA FF
+compliance test. This support is controlled by the TEST_PSA_API variable:
-Parse the PSA FF compliance tests partition manifests using a tool script named
-as ``tfm_parse_manifest_list.py``. This tool updates the TFM partitions data
-structure with PSA test suite partitions detail and creates the manifest output
-files that are required for the PSA test suite build. Using these manifest
-output files, build the PSA FF compliance tests as per the instructions
-given in the PSA FF compliance tests README.
+.. code-block::
+
+ -DTEST_PSA_API=IPC
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- python tools/tfm_parse_manifest_list.py -m tools/tfm_psa_ff_test_manifest_list.yaml append
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DTEST_PSA_API=IPC
+ cmake --build cmake_build -- install
-The build system provides the support for linking with prebuilt PSA FF
-compliance NS and S test libraries when using the ``ConfigPsaApiTestIPC.cmake``
-or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config file. The PSA FF compliance
-tests need to be enabled at the build configuration step by defining::
-
- -DPSA_API_TEST_IPC=ON.
-
-For example, to enable the PSA FF tests for ConfigPsaApiTestIPCTfmLevel2.cmake
-config :
+Alternately using traditional cmake syntax
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- mkdir cmake_psa_test
- cd cmake_psa_test
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTestIPCTfmLevel2.cmake` -DPSA_API_TEST_IPC=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
- cmake --build ./ -- install
+ mkdir cmake_build
+ cd cmake_build
+ cmake .. -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DTEST_PSA_API=IPC
+ make install
Location of build artifacts
===========================
-The build system defines an API which allow easy usage of build
-artifacts. The ``install`` build target copies all files which might be needed
-as a dependency by external tools or build systems to the
-``<build_dir>/install/outputs``
-directory, with the following directory hierarchy:
-::
+All build artifacts are provided in the ``<build_dir>/bin`` directory. It is
+**not** required to run ``make install`` to generate artifacts in this location.
- <build_dir>/install/outputs/fvp/
- <build_dir>/install/outputs/<target_platform>/
-There is one folder for FVP testing, with more elaborate naming and
-there is an other for testing on target hardware platform (AN521, etc.), where
-naming convention is aligned with 8.3 format. The dependency tree of
-``install`` build target ensures a proper update (i.e. build) of all output
-files before the actual installation step takes place. As such it is suggested
-to use this build target to build TF-M.
-
-Export dependency files for NS applications
--------------------------------------------
-An NS application requires a number of files to interface with TF-M.
-The build system exports these files as part of the ``install`` target and
-places them in to a single directory::
-
- <build_dir>/install/export/tfm
-
-Further details on how to integrate a new NS app with TF-M are available in the
-:doc:`integration guide <tfm_integration_guide>`.
+For the purposes of maintaining compatibility with the legacy cmake build
+system, they are also provided in
+``<build_dir>/install/outputs/<target_platform>/``. In order to generate the
+artifacts in this location ``make install`` must be run.
Building the documentation
==========================
@@ -200,11 +393,8 @@
.. code-block:: bash
cd <TF-M base folder>
- mkdir cmake_doc
- cd cmake_doc
- cmake -S .. -B . -G "Unix Makefiles" -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
- make tfm_docs_refman_html
- make tfm_docs_refman_pdf
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_GNUARM.cmake
+ cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf
The documentation files will be available under the directory::
@@ -215,11 +405,8 @@
.. code-block:: bash
cd <TF-M base folder>
- mkdir cmake_doc
- cd cmake_doc
- cmake -S .. -B . -G "Unix Makefiles" -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
- make tfm_docs_userguide_html
- make tfm_docs_userguide_pdf
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_GNUARM.cmake
+ cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf
The documentation files will be available under the directory::
@@ -245,134 +432,36 @@
cd <TF-M base folder>/OTHER_DIR/OTHER_DIR2
sphinx-build <TF-M base folder>/build_docs/ DESIRED_OUTPUT_DIR
-*********************
-Configuring the build
-*********************
-The build configuration for TF-M is provided to the build system using command
-line arguments:
+****************************
+Manual dependency management
+****************************
-.. list-table::
- :widths: 20 80
+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.
- * - -DPROJ_CONFIG=<file>
- - Specifies the way the application is built.
++--------------+--------------------+-----------------------------------------------------+
+| 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 |
++--------------+--------------------+-----------------------------------------------------+
- | <file> is the absolute path to configurations file
- named as ``Config<APP_NAME>.cmake``.
- | i.e. On Linux:
- ``-DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake```
-
- * - -DTARGET_PLATFORM=<target platform name>
- - Specifies the target platform.
- Supported platforms:
-
- - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
- ``-DTARGET_PLATFORM=AN521``
- - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
- ``-DTARGET_PLATFORM=AN519``
- - Arm SSE-123 Example Subsystem for MPS2+ (AN539)
- ``-DTARGET_PLATFORM=AN539``
- - Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+)
- ``-DTARGET_PLATFORM=FVP_SSE300_MPS2``
- - Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
- ``-DTARGET_PLATFORM=MUSCA_A``
- - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
- ``-DTARGET_PLATFORM=MUSCA_B1``
- - Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
- ``-DTARGET_PLATFORM=MUSCA_S1``
- - Cortex-M33 SSE-200 subsystem for MPS3 (AN524)
- ``-DTARGET_PLATFORM=AN524``
- - Cypress CYS0644ABZI-S2D44 board (PSoC64 platform)
- ``-DTARGET_PLATFORM=psoc64``
- See :doc:`Cypress PSoC 64 platform specifics </platform/ext/target/cypress/psoc64/cypress_psoc64_spec>`
- - DesignStart FPGA on Cloud: Cortex-M33 based platform (SSE-200_AWS platform)
- ``-DTARGET_PLATFORM=SSE-200_AWS``
- - DISCO_L562QE board (Cortex-M33 STM32L562)
- ``-DTARGET_PLATFORM=STM_DISCO_L562QE``
- See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`
- - NUCLEO_L552ZE_Q (Cortex-M33 STM32L552)
- ``-DTARGET_PLATFORM=STM_NUCLEO_L552ZE_Q``
- See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`
-
- * - -DCOMPILER=<compiler name>
- - Specifies the compiler toolchain
- The possible values are:
-
- - ``ARMCLANG``
- - ``GNUARM``
- * - -DCMAKE_BUILD_TYPE=<build type>
- - Configures debugging support.
- The possible values are:
-
- - ``Debug``
- - ``Release``
- - ``Relwithdebinfo``
- - ``Minsizerel``
- * - -DMBEDCRYPTO_DEBUG=<ON|OFF>
- - Enables debug symbols for Mbed Crypto(MbedTLS) library. If a
- cryptographic accelerator is enabled then this will also enable
- debug symbols and logging for any accelerator libraries.
- * - -DBUILD_DWARF_VERSION=<dwarf version>
- - Configures DWARF version.
- The possible values are:
-
- - 2
- - 3
- - 4
+For required versions of the dependencies, refer to ``config/config_default.cmake``.
.. Note::
- Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
- without BL2 bootloader.
+ - 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.
-**************
-Configurations
-**************
-Configurations files under `configs` are TF-M provided configurations for building.
-They are used by the `-DPROJ_CONFIG` argument for the build command line.
-The following table describes the differences between the configurations:
-
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| Configuration | Model [1]_ | TF-M LVL [2]_ | Regression [3]_ | Core Test [4]_ | IPC Test [5]_ | PSA API Test [6]_ | Comment |
-+========================+============+===============+=================+================+===============+===================+=========================+
-| Default | Library | 1 | No | No | No | No | TF-M, no tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| Regression | Library | 1 | Yes | Yes | No | No | TF-M & Regression tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| CoreIPC | IPC | 1 | No | No | No | No | TF-M, no tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| CoreIPCTfmLevel2 | IPC | 2 | No | No | No | No | TF-M, no tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| RegressionIPC | IPC | 1 | Yes | Yes | Yes | No | TF-M & Regression tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| RegressionIPCTfmLevel2 | IPC | 2 | Yes | Yes | Yes | No | TF-M & Regression tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| PsaApiTest | Library | 1 | No | No | No | Yes | TF-M & PSA API tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| PsaApiTestIPC | IPC | 1 | No | No | No | Yes | TF-M & PSA API tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| PsaApiTestIPCTfmLevel2 | IPC | 2 | No | No | No | Yes | TF-M & PSA API tests |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| DefaultProfileS | Library | 1 | No | No | No | No | TF-M Profile Small, |
-| | | | | | | | no tests [7]_ |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-| RegressionProfileS | Library | 1 | Yes | Yes | No | No | TF-M Profile Small & |
-| | | | | | | | Regression tests [7]_ |
-+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
-
-.. [1] Which TF-M Model is set: `CORE_IPC`. If `CORE_IPC` is set to true then the model is IPC model, otherwise it's library model.
-
-.. [2] The TF-M isolation level `TFM_LVL`. Currently Library model supports level 1. IPC model supports level 1 and 2.
-
-.. [3] Build regression tests or not: `REGRESSION`.
-
-.. [4] Build core tests or not: `CORE_TEST`.
-
-.. [5] Build IPC tests or not: `IPC_TEST`. It can be only enabled in IPC model
-
-.. [6] Build for PSA API compliance tests or not: `PSA_API_TEST`.
-
-.. [7] Profile Small config doesn't cover all the platforms. Please check
- Profile Small config files to find out the supported platforms.
+.. Note::
+ - CMSIS 5 is provided by the TF-M tests repo. If you wish to use a different
+ source for CMSIS 5, it can be configured using CMSIS_5_PATH.
.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
.. _Doxygen: https://www.doxygen.nl
diff --git a/docs/getting_started/tfm_build_instruction_iar.rst b/docs/getting_started/tfm_build_instruction_iar.rst
index facb744..8df576f 100644
--- a/docs/getting_started/tfm_build_instruction_iar.rst
+++ b/docs/getting_started/tfm_build_instruction_iar.rst
@@ -3,7 +3,7 @@
###################################################
Follow the instructions in
-:doc:`software requirements <tfm_build_instruction>`, but replace the -DCOMPILER= setting with IARARM.
+:doc:`software requirements <tfm_build_instruction>`, but replace the -DCMAKE_TOOLCHAIN_FILE setting with toolchain_IARARM.cmake.
Notes for building with IARARM
@@ -23,55 +23,45 @@
For all configurations and build options some of the QCBOR tests fail due to the tests not handling
double float NaN:s according to the Arm Runtime ABI. This should be sorted out in the future.
- Some minor changes to the mbed-crypto pack is required to allow building TF-M with the
- IAR tools. This will be sorted out once tf-m upgrades to >3.1.0
-
- For mbed-crypto (CMakeLists.txt):
-
+Example: building TF-M for AN521 platform using IAR:
+====================================================
.. code-block:: bash
- if(CMAKE_COMPILER_IS_IAR)
- - set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warn_about_c_style_casts --warnings_are_errors -Ohz")
- + set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warn_about_c_style_casts")
- + set(CMAKE_C_FLAGS_RELEASE "-Ohz")
- + set(CMAKE_C_FLAGS_DEBUG "--debug -On")
- + set(CMAKE_C_FLAGS_CHECK "--warnings_are_errors")
- endif(CMAKE_COMPILER_IS_IAR)
+ cd <base folder>
+ cd trusted-firmware-m
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_IARARM.cmake
+ cmake --build cmake_build -- install
+Alternately using traditional cmake syntax
-Build steps:
-============
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
mkdir cmake_build
cd cmake_build
- cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=IARARM
- cmake --build ./ -- install
+ cmake .. -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_IARARM.cmake
+ make install
Regression Tests for the AN521 target platform
==============================================
-*TF-M build regression tests on Linux*
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- mkdir cmake_test
- cd cmake_test
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=IARARM ../
- cmake --build ./ -- install
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=toolchain_IARARM.cmake -DTEST_S=ON -DTEST_NS=ON
+ cmake --build cmake_build -- install
-*TF-M build regression tests on Windows*
+Alternately using traditional cmake syntax
.. code-block:: bash
cd <base folder>
cd trusted-firmware-m
- mkdir cmake_test
- cd cmake_test
- cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=IARARM ../
- cmake --build ./ -- install
+ mkdir cmake_build
+ cd cmake_build
+ cmake .. -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_IARARM.cmake -DTEST_S=ON -DTEST_NS=ON
+ make install
*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_secure_boot.rst b/docs/getting_started/tfm_secure_boot.rst
index cec838a..6c15a4b 100644
--- a/docs/getting_started/tfm_secure_boot.rst
+++ b/docs/getting_started/tfm_secure_boot.rst
@@ -44,7 +44,7 @@
next reset.
A default RSA key pair is stored in the repository, public key is in ``keys.c``
-and private key is in ``root-rsa-3072.pem``.
+and private key is in ``root-RSA-3072.pem``.
.. Warning::
DO NOT use them in production code, they are exclusively for testing!
@@ -64,7 +64,7 @@
signed. In case of multiple image boot they are separately signed first and then
concatenated. Preparation of payload is done by Python scripts:
``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M
-payload can be found in: ``<build_dir>/install/outputs/fvp/tfm_sign.bin``
+payload can be found in: ``<build_dir>/bin/tfm_s_ns_signed.bin``
*********************
Integration with TF-M
@@ -187,11 +187,10 @@
during authentication then MCUBoot erases the memory slot and starts the other
image, after successful authentication.
-At build time automatically two binaries are generated::
-
- <build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin : Image linked for the primary slot memory partition
-
- <build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin : Image linked for the secondary slot memory partition
+To select which slot the image is to be executed from, set
+``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create
+two build directories when building images using this mode, as intermediate
+dependencies cannot be reused due to changes in the flash layout.
.. Note::
@@ -252,9 +251,7 @@
| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No |
+---------------------+-----------------+---------------+----------+-------------+-----------------+
-.. [1] To disable BL2, please turn off the ``BL2`` compiler switch in the
- build configuration file (``bl2/ext/mcuboot/MCUBootConfig.cmake``) or
- in the command line
+.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF``
.. [2] BL2 is enabled by default
@@ -278,19 +275,16 @@
*******
By default, the original MCUBoot from
`GitHub <https://github.com/JuulLabs-OSS/mcuboot>`__ is used as the bootloader
-in TF-M. The repository must be cloned into the base folder (into which TF-M
-was cloned previously).::
+in TF-M. The repository will be automatically downloaded by cmake. The version
+downloaded can be controlled by the ``MCUBOOT_VERSION`` cmake variable. If you
+wish to use a locally downloaded copy, the cmake variable ``MCUBOOT_PATH`` can
+be set to its location.
- cd <base folder>
- git clone https://github.com/JuulLabs-OSS/mcuboot.git -b v1.6.0
- cd <TF-M build folder>
- cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DMCUBOOT_REPO=UPSTREAM ../
-
-However, please note that it doesn't support the ``No-swap`` and ``RAM loading``
-upgrade strategies, therefore the platforms that don't support other upgrade
-strategies (e.g. ``Overwrite``) cannot be used with the original MCUBoot at the
-moment. To use the TF-M project's fork, the ``MCUBOOT_REPO=TF-M`` option
-must be added to the command line at the CMake configuration step.
+Upstream MCUboot does not support the ``No-swap`` and ``RAM loading`` upgrade
+strategies, therefore the platforms that don't support other upgrade strategies
+(e.g. ``Overwrite``) cannot be used with the original MCUBoot at the moment. To
+use the TF-M project's fork, set the ``TFM_INTERNAL_MCUBOOT`` cmake variable to
+``ON``.
*******************
Multiple image boot
@@ -316,14 +310,14 @@
Dependencies can be added to the images at compile time with the following
compile time switches:
- - ``S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the
+ - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the
minimum required version of the secure image.
- - ``NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the
+ - ``MCUBOOT_NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the
minimum required version of the non-secure image.
Example of how to provide the secure image minimum version::
- cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DS_IMAGE_MIN_VER=1.2.3+4 ../
+ cmake -DTFM_PLATFORM=musca_b1 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMCUBOOT_S_IMAGE_MIN_VER=1.2.3+4 ..
********************
Signature algorithms
@@ -336,24 +330,19 @@
Example keys stored in:
- - ``root-rsa-2048.pem`` : Used to sign single image (S+NS) or secure image
+ - ``root-RSA-2048.pem`` : Used to sign single image (S+NS) or secure image
in case of multiple image boot
- - ``root-rsa-2048_1.pem`` : Used to sign non-secure image in case of multiple
+ - ``root-RSA-2048_1.pem`` : Used to sign non-secure image in case of multiple
image boot
- - ``root-rsa-3072.pem`` : Used to sign single image (S+NS) or secure image
+ - ``root-RSA-3072.pem`` : Used to sign single image (S+NS) or secure image
in case of multiple image boot
- - ``root-rsa-3072_1.pem`` : Used to sign non-secure image in case of multiple
+ - ``root-RSA-3072_1.pem`` : Used to sign non-secure image in case of multiple
image boot
************************
Build time configuration
************************
-MCUBoot related compile time switches can be set in the build configuration
-file::
-
- bl2/ext/mcuboot/MCUBootConfig.cmake
-
-Compile time switches:
+MCUBoot related compile time switches can be set by cmake variables.
- BL2 (default: True):
- **True:** TF-M built together with bootloader. MCUBoot is executed after
@@ -361,10 +350,10 @@
- **False:** TF-M built without bootloader. Secure image linked to the
beginning of the device memory and executed after reset. If it is false
then using any of the further compile time switches is invalid.
-- MCUBOOT_REPO (default: "UPSTREAM"):
- - **"TF-M":** Use TF-M's MCUBoot fork as bootloader which is located in the
+- TFM_INTERNAL_MCUBOOT (default: False):
+ - **"True":** Use TF-M's MCUBoot fork as bootloader which is located in the
bl2/ext/mcuboot folder.
- - **"UPSTREAM":** Use the original (upstream) MCUBoot as bootloader. Before
+ - **"False":** Use the original (upstream) MCUBoot as bootloader. Before
selecting this option please read the `MCUBoot`_ section for more
information and the limitations of using this option.
- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"):
@@ -374,9 +363,11 @@
- **"RAM_LOADING":** Activate RAM loading firmware upgrade operation, where
the latest image is copied to RAM and runs from there instead of being
executed in-place.
-- MCUBOOT_SIGNATURE_TYPE (default: RSA-3072):
- - **RSA-3072:** Image is signed with RSA-3072 algorithm
- - **RSA-2048:** Image is signed with RSA-2048 algorithm
+- MCUBOOT_SIGNATURE_TYPE (default: RSA):
+ - **RSA:** Image is signed with RSA algorithm
+- MCUBOOT_SIGNATURE_KEY_LEN (default: 3072):
+ - **2048:** Image is signed with 2048 bit key.
+ - **3072:** Image is signed with 3072 bit key.
- MCUBOOT_IMAGE_NUMBER (default: 2):
- **1:** Single image boot, secure and non-secure images are signed and
updated together.
@@ -384,20 +375,21 @@
updatable independently.
- MCUBOOT_HW_KEY (default: True):
- **True:** The hash of public key is provisioned to the SoC and the image
- manifest contains the whole public key. MCUBoot validates the key before
- using it for firmware authentication, it calculates the hash of public key
- from the manifest and compare against the retrieved key-hash from the
- hardware. This way MCUBoot is independent from the public key(s).
- Key(s) can be provisioned any time and by different parties.
+ manifest contains the whole public key (imgtool uses
+ ``--public_key_format=full``). MCUBoot validates the key before using it
+ for firmware authentication, it calculates the hash of public key from the
+ manifest and compare against the retrieved key-hash from the hardware.
+ This way MCUBoot is independent from the public key(s). Key(s) can be
+ provisioned any time and by different parties.
- **False:** The whole public key is embedded to the bootloader code and the
- image manifest contains only the hash of the public key. MCUBoot validates
- the key before using it for firmware authentication, it calculates the
- hash of built-in public key and compare against the retrieved key-hash
- from the image manifest. After this the bootloader can verify that the
- image was signed with a private key that corresponds to the retrieved
- key-hash (it can have more public keys embedded in and it may have to look
- for the matching one). All the public key(s) must be known at MCUBoot
- build time.
+ image manifest contains only the hash of the public key (imgtool uses
+ ``--public_key_format=hash``). MCUBoot validates the key before using it
+ for firmware authentication, it calculates the hash of built-in public key
+ and compare against the retrieved key-hash from the image manifest. After
+ this the bootloader can verify that the image was signed with a private
+ key that corresponds to the retrieved key-hash (it can have more public
+ keys embedded in and it may have to look for the matching one). All the
+ public key(s) must be known at MCUBoot build time.
- MCUBOOT_LOG_LEVEL:
Can be used to configure the level of logging in MCUBoot. The possible
values are the following:
@@ -415,7 +407,7 @@
``LOG_LEVEL_INFO`` by default. In case of different kinds of ``Release``
builds its value is set to ``LOG_LEVEL_OFF`` (any other value will be
overridden).
-- MCUBOOT_ENCRYPT_RSA (default: False):
+- MCUBOOT_ENC_IMAGES (default: False):
- **True:** Adds encrypted image support in the source and encrypts the
resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot
repository.
@@ -448,7 +440,7 @@
The version number of the image (single image boot) can manually be passed in
through the command line in the cmake configuration step::
- cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DIMAGE_VERSION=1.2.3+4 ../
+ cmake -DTFM_PLATFORM=musca_b1 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DIMAGE_VERSION_S=1.2.3+4 ..
Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
where the missing numbers are automatically set to zero. The image version
@@ -465,7 +457,7 @@
versioning, please start a clean build without specifying the image version
number at all. In case of multiple image boot there are separate compile time
switches for both images to provide their version: ``IMAGE_VERSION_S`` and
-``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION``.
+``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION_S``.
Security counter
================
@@ -482,7 +474,7 @@
current image version. The value of the security counter (single image boot) can
be specified at build time in the cmake configuration step::
- cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DSECURITY_COUNTER=42 ../
+ cmake -DTFM_PLATFORM=musca_b1 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DSECURITY_COUNTER_S=42 ../
The security counter can be independent from the image version, but not
necessarily. Alternatively, if it is not specified at build time with the
@@ -491,7 +483,7 @@
will be added to the signed image. In case of multiple image boot there are
separate compile time switches for both images to provide their security counter
value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used
-instead of ``SECURITY_COUNTER``. If these are not defined then the security
+instead of ``SECURITY_COUNTER_S``. If these are not defined then the security
counter values will be derived from the corresponding image version similar to
the single image boot.
@@ -506,7 +498,7 @@
information about the mandatory and optional arguments. The tool takes an image
in binary or Intel Hex format and adds a header and trailer that MCUBoot is
expecting. In case of single image boot after a successful build the
-``tfm_full.bin`` build artifact (contains the concatenated secure and non-secure
+``tfm_s_ns.bin`` build artifact (contains the concatenated secure and non-secure
images) must be passed to the script and in case of multiple image boot the
``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed
images.
@@ -517,16 +509,16 @@
::
python3 bl2/ext/mcuboot/scripts/imgtool.py sign \
- --layout <build_dir>/image_macros_preprocessed_s.c \
- -k <tfm_dir>/bl2/ext/mcuboot/root-rsa-3072.pem \
+ --layout <build_dir>/bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \
+ -k <tfm_dir>/bl2/ext/mcuboot/root-RSA-3072.pem \
--public-key-format full \
--align 1 \
-v 1.2.3+4 \
-d "(1,1.2.3+0)" \
-s 42 \
-H 0x400 \
- <build_dir>/install/outputs/AN521/tfm_s.bin \
- <build_dir>/tfm_s_signed.bin
+ <build_dir>/bin/tfm_s.bin \
+ <build_dir>/bin/tfm_s_signed.bin
************************
Testing firmware upgrade
@@ -561,8 +553,8 @@
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
- --data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
- --data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
+ --data cpu0=<default_build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=<regresssion_build_dir>/bin/tfm_s_ns_signed.bin@0x10180000
Executing firmware upgrade on SSE 200 FPGA on MPS2 board
--------------------------------------------------------
@@ -681,6 +673,7 @@
- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "NO_SWAP"
before build.
+- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir.
- Make sure the image version number was increased between the two build runs
either by specifying it manually or by checking in the build log that it was
incremented automatically.
@@ -703,8 +696,8 @@
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
- --data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
- --data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin@0x10180000
+ --data cpu0=<default_build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=<regresssion_build_dir>/bin/tfm_s_ns_signed.bin@0x10180000
Executing firmware upgrade on SSE 200 FPGA on MPS2 board
--------------------------------------------------------
diff --git a/docs/getting_started/tfm_sw_requirement.rst b/docs/getting_started/tfm_sw_requirement.rst
index 1edf7d4..fdc2d33 100644
--- a/docs/getting_started/tfm_sw_requirement.rst
+++ b/docs/getting_started/tfm_sw_requirement.rst
@@ -124,35 +124,9 @@
External dependencies
*********************
-In order to build TF-M the following external projects are required:
-
- - `Mbed-crypto(MbedTLS) library <https://github.com/ARMmbed/mbedtls>`__ v2.23.0
- is used as crypto library on the secure side.
- - `MCUboot <https://github.com/JuulLabs-OSS/mcuboot>`__ v1.6.0 is used as
- the default bootloader in TF-M
-
-And the following TF-M projects as well:
-
- - `TF-M tests <https://git.trustedfirmware.org/TF-M/tf-m-tests.git>`__
-
-.. Note::
-
- The development of Mbed-crypto has moved to MbedTLS project and hence
- wherever mbed-crypto is referred to in TF-M, it refers to the component
- within MbedTLS project. More details of the move can be found
- `here <https://github.com/ARMmbed/mbed-crypto/issues/374>`__.
-
-
-Each of the listed dependencies should be placed in a common root directory
-with trustedfirmware-m
-
-.. code-block:: bash
-
- .
- ├── mbedtls
- ├── mcuboot
- ├── tf-m-tests
- └── trusted-firmware-m
+Dependency management is now handled by cmake. If you wish to alter this
+behaviour, see :ref:`docs/getting_started/tfm_build_instruction:Manual
+dependency management`
********************************************
Tools for configuring and programming boards
diff --git a/docs/reference/services/tfm_crypto_integration_guide.rst b/docs/reference/services/tfm_crypto_integration_guide.rst
index 6eaa5e0..a124bdf 100644
--- a/docs/reference/services/tfm_crypto_integration_guide.rst
+++ b/docs/reference/services/tfm_crypto_integration_guide.rst
@@ -68,20 +68,24 @@
****************************
The Crypto service can use either a hardware crypto accelerator backend like
-CC-312 or a software crypto library which by default is MbedTLS. If using
-MbedTLS as backend, then the library configuration is supplied using the
-MBEDTLS_CONFIG_FILE header option. TF-M Crypto provides a default
-configuration header ``tfm_mbedcrypto_config.h`` and this can be overridden
-based on TF-M configuration or platform. Platforms can also use
-``MBEDTLS_USER_CONFIG_FILE`` to override specific options from default.
+CC-312 or a software crypto library which by default is MbedTLS.
+
+If using MbedTLS as backend, then the library configuration is supplied using
+the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option.
+
+Platforms can specify an extra config file by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
+around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform
+configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with
+config changes due to TFM Profile.
.. Note::
The default entropy source configured for MbedTLS is
MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness
- for production devices. It is must for production devices to select
+ for production devices. It is required for production devices to select
either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or
- provision a unique seed for the device during production and use
+ provision a unique seed for the device during production and use the
MBEDTLS_ENTROPY_NV_SEED option.
**************************
diff --git a/docs/reference/services/tfm_secure_partition_addition.rst b/docs/reference/services/tfm_secure_partition_addition.rst
index 9a5663d..a9c3759 100644
--- a/docs/reference/services/tfm_secure_partition_addition.rst
+++ b/docs/reference/services/tfm_secure_partition_addition.rst
@@ -59,7 +59,6 @@
- `Add source folder`_
- `Add manifest`_
- `Add configuration`_
-- `Generate files`_
- `Implement the RoT services`_
Add source folder
@@ -263,20 +262,11 @@
Add CMake configure files
-------------------------
-Two CMake configure files need to be added:
-
-- CMakeLists.inc, which is used to add the definition of what files are needed
- to build.
- CMakeLists.txt, which is the compilation configuration for this module.
-.. Note::
- The CMakeLists.inc is not mandatory, the user can put everything in
- CMakeLists.txt.
-
The current CMake configuration should also be updated, by updating
-CommonConfig.cmake to include the definition of the newly introduced partition
+config_default.cmake to include the definition of the newly introduced partition
and adding the relevant subdirectoy in ``secure_fw/CMakeLists.txt``.
-
Please refer to the source code of TF-M for more detail.
Update manifest list
@@ -311,16 +301,10 @@
"pid": 256
}
-Generate files
-==============
-After finishing the configuration works, the user needs to generate necessary
-files from manifest by using TF-M tools.
-
-.. code-block:: bash
-
- cd <base folder>
- cd trusted-firmware-m
- python ./tools/tfm_parse_manifest_list.py
+.. Note::
+ The manifest configuration can be placed in a different external manifest
+ list. In this case, the cmake variable TFM_EXTRA_MANIFEST_LIST_PATH should be
+ set to the path of the external manifest list.
Implement the RoT services
==========================