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/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
--------------------------------------------------------