Difference between revisions of "TF-A BL2 overview"

[quality revision] [quality revision]
m
m

1 Article purpose[edit]

This section details the TF-A BL2 stage (Trusted Firmware-A Boot Loader stage 2) used as FSBL (First Stage Boot Loader). TF-A BL2 is the FSBL for ST boot chain. It is loaded by the ROM code in internal SYSRAM.
The main goal of this stage is to configure the DDR to load (and authenticate) other components from a FIP binary.

2 STM32 binary file[edit]

To be properly loaded into SYSRAM by the ROM code, the TF-A BL2 firmware needs to be encapsulated in a binary that starts with an STM32 header. The STM32 header information is mandatory for the ROM code to be able to load, authenticate and start the firmware.
As the ROM code can only load a single binary, the STM32 file must embed in a single image, the header, the device tree and the BL2 firmware.

TF-A BL2 is part of the trusted boot and can be signed to be authenticated by ROM code. See Secure boot process for more details.

3 Device tree[edit]

TF-A BL2 is based on device tree configuration. It uses the same device tree as the kernel but keeping only the mandatory nodes for the boot stage (to reduce binary size) thanks to a dedicated device tree file (such as fdts/stm32mp15-bl2.dtsi ). The device tree is part of the final STM32 file in order to be authenticated by the ROM code and loaded at the same time in the SYSRAM.
It must be configured or updated depending on your platform.

4 Storage management3 STM32 binary file[edit]

To be properly loaded into SYSRAM by the ROM code, the TF-A BL2 firmware needs to access storage devices to load the FIP binary. By default, it uses the boot device selected by boot pins or OTP.
The selected device needs to be properly set up:

  • Device tree configuration (all devices)
  • BL2 boot device configuration for Flash memories .

Each device support needs a specific framework in the BL2 firmware.
By default, STMicroelectronics chose to select one single device support per binary. A BL2 with full storage support cannot fit in the SYSRAM size.
Storage build flags allow the BL2 firmware to be configured to support the requested boot storage.

5 DDR[edit]

TF-A BL2 needs to set up the DDR to load the next binaries. DDR settings come from the device tree and must be adapted by the customer depending on DDR type, DDR configuration and boards. This can be done using STM32CubeMX.

6 Clock management[edit]

An initial clock tree must be set up to allow accessing the DDR and the external storage devices.
It also improves the performance by increasing the default CPU speed and the storage transfer speed.

7

be encapsulated in a binary that starts with a STM32 header.
The STM32 header information is mandatory for the ROM code to be able to load, authenticate and start the firmware.
As the ROM code can only load a single binary, the STM32 file must embed in a single image, the header, the device tree and the BL2 binary firmware.

TF-A BL2 is part of the trusted boot and can be signed to be authenticated by ROM code. See Secure boot process for more details.

4 Binary mapping[edit]

Below the TF-A BL2 mapping including the STM32 header layout:

Atf.stm32.png

The different sizes can be customized depending on build options and device tree customization. All sizes can be changed in the platform definition file. STM32MP1 platform uses plat/st/stm32mp1/stm32mp1_def.h :

  • STM32MP_BL2_DTB_BASE: device tree base address in SYSRAM with its associated SIZE
  • STM32MP_BL2_RO_BASE: start address from which the code is loaded and executed
  • STM32MP_BL2_RW_BASE: start address of the read and write data used by the code. It depends on the STM32MP_BL2_RO_SIZE, which cannot exceed SYSRAM size.

8 BL2 load processing5 Boot device[edit]

Based on FIP and firmware configuration file, the same BL2 can dynamically manage different secure environments:

The BL2 process is executed as described below:
Bl2 load fconf.png
  1. The ROM Code loads (and authenticates if required) the STM32 TF-A BL2 file together with its device tree.
  2. BL2 loads (and authenticates) FW_CONFIG file from FIP. BL2 parses the firmware configuration file to identify the load binary properties.
  3. BL2 loads (and authenticates) all the binaries listed in FW_CONFIG from FIP.

8.1 FW_CONFIG[edit]

The FW_CONFIG file is based on the device tree. It describes the properties of the binaries to be loaded. This file is mandatory in the FIP binary to dynamically configure BL2 so that it properly loads all images. It depends on the DDR size, defined mapping and selected binaries. More details on FW_CONFIG and its configuration can be found here.

8.2 BL2 load in Programmer mode5.1 External memory[edit]

TF-A BL2 needs to access storage devices to load the other software components. By default, it uses the boot device selected by boot pins or OTP.
The selected device needs to be properly set up:

  • Device tree configuration (all devices)
  • BL2 boot device configuration for Flash memories .

Each device support needs a specific framework in the BL2 firmware.
By default, STMicroelectronics chose to select one single device support per binary. A BL2 with full storage support cannot fit in the SYSRAM size.
Storage build flags allow the BL2 firmware to be configured to support the requested boot storage.

5.2 Serial mode (USB/UART)[edit]

The Programmer mode (USB or UART boot device) requires the complete FIP binary to start the load image process as previously explained. This is achieved by loading the complete FIP binary into DDR before starting the normal boot sequence. The FIP load address is fixed and must not override the next loaded address:
configurable with DWL_BUFFER_BASE used parameter. The default value is in plat/st/common/stm32_io_storage.c

8.3 Low-power mode

stm32mp1/platform.mk

6 DDR[edit]

When exiting from low-power mode, BL2 has to wake TF-A BL2 needs to set up the DDR from self-refresh mode and reload only the binaries that have been lost.

Warning white.png Warning
When OP-TEE OS is used in Pager mode (using SYSRAM), it can restore its content by itself thanks to the DDR backup and backup context
.

9 Trusted boot support[edit]

This is a key feature for the secure boot. It completes the STM32 ROM code secure boot process. This feature is enabled by defining the TRUSTED_BOARD_BOOT = 1 build flag (not enabled by default).
As soon as the flag is enabled, all the binaries loaded by the BL2 stage are authenticated. The certificates listed in the CoT are mandatory into the FIP binary.

9.1 MBEDTLS[edit]

When FIP is used, X509.v3 certificates are embedded in the package to authenticate all loaded binaries. The certificate parsing is done using MBEDTLS. The MBEDTLS[1] project is partially used during the trusted boot build process to retrieve part of the library and parse the certificates. The project must be downloaded close to the TF-A sources and the path using the MBEDTLS_DIR variable must be defined.

9.2 Disabling dynamic authentication[edit]

A DYN_DISABLE_AUTH flag can be used to build the full BL2 content (including the disable MDEBTLS files). It allows the authentication to be enabled or disabled using a device tree property:


disable_auth = <0x0>; // To enable authentication
disable_auth = <0x1>; // To bypass authentication

This device tree property is located in the BL2 device tree (trusted boot device tree).

9.3 Cryptographic Library[edit]

The STM32 MPU uses its own cryptographic library (thanks to hardware accelerators or ROM Code services (STM32MP15 Only)) to verify certificate signatures: plat/st/common/stm32mp_crypto_lib.c

9.4 Keys[edit]

The authentication is based on different keys and certificates. By default, the Arm® TBBR CoT is used. The topology is defined in the BL2 device tree fdts/cot_descriptors.dtsi and can be customized using <link here to authentication article>. The STM32 MPU uses the default public root key hash in OTP as main root key for the CoT.
It can be modified by the customer in device tree by redefining pkh_otp.

During the development, the ROTPK hash is not mandatory. If it is not fused in OTP, it is seen as NOT DEPLOYED and the final ROTPK hash control is bypassed. However the entire CoT is verified.

Warning white.png Warning
The ROTPK hash must be in OTP before closing the chip
10 Secure secret provisioning (SSP)[edit]
Warning white.png Warning
This feature is only available for STM32 MPU with cryptographic accelerators

The STM32 MPU supports the SSP feature. Part of this feature is based on TF-A BL2:

  • Exchange with STM32_CubeProgrammer
  • Secure programing secret OTPs
https://github.com/ARMmbed/mbedtls

to load the next binaries. DDR settings come from the device tree and must be adapted by the customer depending on DDR type, DDR configuration and boards. This can be done using STM32CubeMX.

6.1 DDR encryption[edit]

On STM32MP13x lines Warning.png, a region of the DDR can be encrypted, thanks to DDRMCE. Its configuration is done in TF-A Firmware configuration device tree, with the DDRMCE configuration.

7 Clock management[edit]

An initial clock tree must be set up to allow accessing the DDR and the external storage devices.
It also improves the performance by increasing the default CPU speed and the storage transfer speed.

8 FIP[edit]

The Firmware Image Package (FIP)[1] is a TF-A archive binary that encapsulates bootloader images into a single archive. It can also contain other data such as certificates that are required to complete the boot process.

See the page How to configure TF-A FIP for more information.

9 FCONF[edit]

The Firmware Configuration Framework (FCONF)[2] is a way to offer more flexibility in the firmware.

It is used to provide most of the platform-specific data that were previously hard coded inside the firmware. This framework uses device tree (one or multiple) that are passed to the firmware during load processing. BL2 uses it for several purposes:

  • list images to be loaded, with their load addresses and max sizes
  • DDR firewall configuration
  • describe the chain of trust parameters

TF-A BL2 configuration is done with a dedicated device tree file named FW_CONFIG. More details about the FW_CONFIG file are given by the page How to configure TF-A FW CONFIG.

10 Authentication[edit]

TF-A BL2 manages authentication thanks to Trusted Board Boot activation.


== Article purpose ==
This section details the TF-A BL2 stage (Trusted Firmware-A Boot Loader stage 2) used as FSBL (First Stage Boot Loader).
TF-A BL2 is the FSBL for ST boot chain. It is loaded by the [[STM32MP15_STM32_MPU_ROM_code_overview|ROM code]] in internal [[SYSRAM_internal_memory|SYSRAM]].<br>

The main goal of this stage is to configure the DDR to load (and authenticate) other components from a [[How to configure TF-A FIP|FIP binary]].<br>


== STM32 binary file ==
To be properly loaded into [[SYSRAM_internal_memory|SYSRAM]] by the [[STM32MP15_ROM_code_overview|ROM code]], the TF-A BL2 firmware needs to be encapsulated in a binary that starts with an STM32 header.
The [[STM32_header_for_binary_files|STM32 header]] information is mandatory for the [[STM32MP15_ROM_code_overview|ROM code]] to be able to load, authenticate and start the firmware.<br>

As the ROM code can only load a single binary, the STM32 file must embed in a single image, the header, the device tree and the BL2 firmware. <br>


TF-A BL2 is part of the trusted boot and can be signed to be authenticated by [[STM32MP15_ROM_code_overview|ROM code]]. See [[Security_overview#Secure_boot|Secure boot]] process for more details.

== Device tree ==
TF-A BL2 is based on device tree configuration. It uses the same device tree as the kernel but keeping only the mandatory nodes for the boot stage (to reduce binary size) thanks to a dedicated device tree file (such as {{CodeSource | TF-A | fdts/stm32mp15-bl2.dtsi}}).
The device tree is part of the final STM32 file in order to be authenticated by the [[STM32MP15_STM32_MPU_ROM_code_overview|ROM code]] and loaded at the same time in the [[SYSRAM_internal_memory|SYSRAM]].<br>

It must be configured or updated depending on your platform.<br>


== Storage management ==
TF-A BL2 needs to access storage devices to load the [[How to configure TF-A FIP|FIP binary]]. By default, it uses the boot device selected by [[STM32MP15_ROM_code_overview#Boot_device_selection_via_the_boot_pins_and_OTP|boot pins or OTP]].<br>

The selected device needs to be properly set up:
* Device tree configuration (all devices)
* BL2 boot device configuration for [[How to configure flash memory for TF-A BL2| Flash memories ]].

Each device support needs a specific framework in the BL2 firmware.<br>

By default, STMicroelectronics chose to select one single device support per binary. A BL2 with full storage support cannot fit in the [[SYSRAM_internal_memory|SYSRAM]] size.<br>

Storage build flags allow the BL2 firmware to be configured to support the requested boot storage.

== DDR ==
TF-A BL2 needs to set up the DDR to load the next binaries.
DDR settings come fromSTM32 binary file ==
To be properly loaded into [[SYSRAM_internal_memory|SYSRAM]] by the [[STM32_MPU_ROM_code_overview|ROM code]], the TF-A BL2 firmware needs to be encapsulated in a binary that starts with a [[STM32_header_for_binary_files|STM32 header]].<br>

The [[STM32_header_for_binary_files|STM32 header]] information is mandatory for the [[STM32_MPU_ROM_code_overview|ROM code]] to be able to load, authenticate and start the firmware.<br>

As the ROM code can only load a single binary, the STM32 file must embed in a single image, the header, the device tree and must be adapted by the customer depending on DDR type, DDR configuration and boards.
This can be done using [[DDRCTRL_and_DDRPHYC_device_tree_configuration#How_to_configure_the_DT_using_STM32CubeMX|STM32CubeMX]].

== Clock management ==
An initial [[Clock_device_tree_configuration_-_Bootloader_specific|clock tree]] must be set up to allow accessing the DDR and the external storage devices.<br>

It also improves the performance by increasing the default CPU speed and the storage transfer speed.
the BL2 binary firmware. <br>


TF-A BL2 is part of the trusted boot and can be signed to be authenticated by [[STM32_MPU_ROM_code_overview|ROM code]]. See [[Security_overview#Secure_boot|Secure boot]] process for more details.
== Binary mapping ==
Below the TF-A BL2 mapping including the STM32 header layout:
[[File:Atf.stm32.png|600px|center|link=]]

The different sizes can be customized depending on build options and device tree customization. All sizes can be changed in the platform definition file. STM32MP1 platform uses {{ CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h }}:
* STM32MP_BL2_DTB_BASE: device tree base address in SYSRAM with its associated SIZE
* STM32MP_BL2_RO_BASE: start address from which the code is loaded and executed
* STM32MP_BL2_RW_BASE: start address of the read and write data used by the code. It depends on the STM32MP_BL2_RO_SIZE, which cannot exceed [[SYSRAM_internal_memory|SYSRAM]] size.

== BL2 load processing ==
Based on [[How to configure TF-A FIP|FIP]] and [[How to configure TF-A FW CONFIG|firmware configuration file]], the '''same''' BL2 can dynamically manage different secure environments:
* [[How to configure TF-A SP-MIN| TF-A SP_MIN]]
* [[OP-TEE_overview|OP-TEE]]<br>

The BL2 process is executed as described below:
[[File:bl2_load_fconf.png|center|link=]]<br>

# The [[STM32MP15_ROM_code_overview|ROM Code]] loads (and authenticates if required) the STM32 TF-A BL2 file together with its device tree.
# BL2 loads (and authenticates) [[How to configure TF-A FW CONFIG|FW_CONFIG]] file from [[How to configure TF-A FIP|FIP]]. BL2 parses the [[How to configure TF-A FW CONFIG|firmware configuration file]] to identify the load binary properties.
# BL2 loads (and authenticates) all the binaries listed in [[How to configure TF-A FW CONFIG|FW_CONFIG]] from [[How to configure TF-A FIP|FIP]].

=== FW_CONFIG ===
The [[How to configure TF-A FW CONFIG|FW_CONFIG]] file is based on the device tree. It describes the properties of the binaries to be loaded.
This file is mandatory in the [[How to configure TF-A FIP|FIP binary]] to dynamically configure BL2 so that it properly loads all images.
It depends on the DDR size, defined mapping and selected binaries.
More details on FW_CONFIG and its configuration can be found [[How to configure TF-A FW CONFIG|here]].

=== BL2 load in Programmer mode Boot device ==
=== External memory ===
TF-A BL2 needs to access storage devices to load the other software components. By default, it uses the boot device selected by [[STM32_MPU_ROM_code_overview#Boot_device_selection_via_the_boot_pins_and_OTP|boot pins or OTP]].<br>

The selected device needs to be properly set up:
* Device tree configuration (all devices)
* BL2 boot device configuration for [[How to configure flash memory for TF-A BL2| Flash memories ]].

Each device support needs a specific framework in the BL2 firmware.<br>

By default, STMicroelectronics chose to select one single device support per binary. A BL2 with full storage support cannot fit in the [[SYSRAM_internal_memory|SYSRAM]] size.<br>

Storage [[How_to_configure_TF-A_BL2#TF-A_Build_flags|build flags]] allow the BL2 firmware to be configured to support the requested boot storage.

=== Serial mode (USB/UART) ===
The Programmer mode (USB or UART boot device) requires the complete [[How to configure TF-A FIP|FIP binary]] to start the load image process as previously explained.
This is achieved by loading the complete [[How to configure TF-A FIP|FIP binary]] into DDR before starting the normal boot sequence.
The FIP load address is fixed and must not override the next loaded address: <br>

DWL_BUFFER_BASE used configurable with DWL_BUFFER_BASE parameter. The default value is in {{CodeSource | TF-A | plat/st/common/stm32_io_storage.c}}

=== Low-power mode ===
When exiting from low-power mode, BL2 has to wake up the DDR from self-refresh mode and reload only the binaries that have been lost.
{{Warning | When OP-TEE OS is used in Pager mode (using [[SYSRAM_internal_memory|SYSRAM]]), it can restore its content by itself thanks to the DDR backup and backup context}}.

== Trusted boot support ==
This is a key feature for the secure boot. It completes the [[STM32MP15_ROM_code_secure_boot|STM32 ROM code secure boot]] process.
This feature is enabled by defining the '''TRUSTED_BOARD_BOOT = 1''' build flag (not enabled by default).<br>

As soon as the flag is enabled, all the binaries loaded by the BL2 stage are authenticated. The certificates listed in the CoT are mandatory into the [[How to configure TF-A FIP|FIP binary]].

=== MBEDTLS ===
When FIP is used, X509.v3 certificates are embedded in the package to authenticate all loaded binaries.
The certificate parsing is done using MBEDTLS. The MBEDTLS<ref name=mbedtls>https://github.com/ARMmbed/mbedtls</ref> project is partially used during the trusted boot build process to retrieve part of the library and parse the certificates.
The project must be downloaded close to the TF-A sources and the path using the MBEDTLS_DIR variable must be defined.

=== Disabling dynamic authentication ===
A '''DYN_DISABLE_AUTH''' flag can be used to build the full BL2 content (including the disable MDEBTLS files). It allows the authentication to be enabled or disabled using a device tree property:<pre>

disable_auth = <0x0>; // To enable authentication
disable_auth = <0x1>; // To bypass authentication</pre>

This device tree property is located in the BL2 device tree (trusted boot device tree).

=== Cryptographic Library ===
The STM32 MPU uses its own cryptographic library (thanks to hardware accelerators or [[STM32MP15_ROM_code_overview|ROM Code]] services (STM32MP15 Only)) to verify certificate signatures: {{ CodeSource | TF-A | plat/st/common/stm32mp_crypto_lib.c }}

=== Keys ===
The authentication is based on different keys and certificates. By default, the Arm<sup>&reg;</sup> TBBR CoT is used. The topology is defined in the BL2 device tree {{ CodeSource | TF-A | fdts/cot_descriptors.dtsi }} and can be customized using <link here to authentication article>.
The STM32 MPU uses the default [[STM32MP15_ROM_code_overview#OTP_WORD_24_to_31_-_Public_Key_Hash_-28PKH-29|public root key hash in OTP]] as main root key for the CoT. <br>

It can be modified by the customer [[BSEC_device_tree_configuration#STM32MP1_nvmem_layout_node_-28bootloader_specific-29| in device tree]] by redefining '''pkh_otp'''.

During the development, the ROTPK hash is not mandatory. If it is not fused in OTP, it is seen as NOT DEPLOYED and the final ROTPK hash control is bypassed. However the entire CoT is verified.
{{Warning|The ROTPK hash must be in OTP before closing the chip}}

== Secure secret provisioning (SSP) ==
{{Warning| This feature is only available for STM32 MPU with cryptographic accelerators}}
The STM32 MPU supports the [[Security_overview#Secure_Secret_Provisioning|SSP feature]]. Part of this feature is based on TF-A BL2:
* Exchange with STM32_CubeProgrammer
* Secure programing secret OTPs
<noinclude>

{{PublicationRequestId | 19288| 2021-03-10 | PhilipSstm32mp1/platform.mk}}

== DDR ==
TF-A BL2 needs to set up the DDR to load the next binaries.
DDR settings come from the device tree and must be adapted by the customer depending on DDR type, DDR configuration and boards.
This can be done using [[DDRCTRL_and_DDRPHYC_device_tree_configuration#How_to_configure_the_DT_using_STM32CubeMX|STM32CubeMX]].

=== DDR encryption ===
On {{MicroprocessorDevice | device=13}}, a region of the DDR can be encrypted, thanks to [[DDRMCE_internal_peripheral|DDRMCE]]. Its configuration is done in TF-A [[TF-A_overview#Firmware_Configuration|Firmware configuration]] device tree, with the [[How_to_configure_TF-A_FW_CONFIG#DDR_Encryption_area|DDRMCE configuration]].

== Clock management ==
An initial [[Clock_device_tree_configuration|clock tree]] must be set up to allow accessing the DDR and the external storage devices.<br>

It also improves the performance by increasing the default CPU speed and the storage transfer speed.

== FIP ==
The Firmware Image Package (FIP)<ref name=fip>{{DocSource | domain=TF-A | path=design/firmware-design.html#firmware-image-package-fip | text=Firmware Image Package}}</ref> is a TF-A archive binary that encapsulates bootloader images into a single archive.</br> 

It can also contain other data such as certificates that are required to complete the boot process.

See the page [[How to configure TF-A FIP]] for more information.

== FCONF ==
The Firmware Configuration Framework (FCONF)<ref name=fconf>{{DocSource | domain=TF-A | path=components/fconf/index.html | text=Firmware Configuration Framework}}</ref> is a way to offer more flexibility in the firmware.

It is used to provide most of the platform-specific data that were previously hard coded inside the firmware.
This framework uses device tree (one or multiple) that are passed to the firmware during load processing.
BL2 uses it for several purposes:
* list images to be loaded, with their load addresses and max sizes
* DDR firewall configuration
* describe the chain of trust parameters

TF-A BL2 configuration is done with a dedicated device tree file named FW_CONFIG.
More details about the FW_CONFIG file are given by the page [[How to configure TF-A FW CONFIG]].

== Authentication ==
TF-A BL2 manages authentication thanks to [[TF-A_BL2_Trusted_Board_Boot|Trusted Board Boot]] activation.
<noinclude>

{{PublicationRequestId | 19288| 2021-03-10 | reviewed by AnneJ in the article STM32 MPU TF-A (BL2) which has been split in 2 articles How_to_configure_TF-A_BL2 and this one}}
[[Category:Trusted Firmware-A (BL2)| 02]]</noinclude>
(24 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Article purpose ==
 
== Article purpose ==
 
This section details the TF-A BL2 stage (Trusted Firmware-A Boot Loader stage 2) used as FSBL (First Stage Boot Loader).
 
This section details the TF-A BL2 stage (Trusted Firmware-A Boot Loader stage 2) used as FSBL (First Stage Boot Loader).
TF-A BL2 is the FSBL for ST boot chain. It is loaded by the [[STM32MP15_ROM_code_overview|ROM code]] in internal [[SYSRAM_internal_memory|SYSRAM]].<br>
+
TF-A BL2 is the FSBL for ST boot chain. It is loaded by the [[STM32_MPU_ROM_code_overview|ROM code]] in internal [[SYSRAM_internal_memory|SYSRAM]].<br>
 
The main goal of this stage is to configure the DDR to load (and authenticate) other components from a [[How to configure TF-A FIP|FIP binary]].<br>
 
The main goal of this stage is to configure the DDR to load (and authenticate) other components from a [[How to configure TF-A FIP|FIP binary]].<br>
  +
  +
== Device tree ==
  +
TF-A BL2 is based on device tree configuration. It uses the same device tree as the kernel but keeping only the mandatory nodes for the boot stage (to reduce binary size) thanks to a dedicated device tree file (such as {{CodeSource | TF-A | fdts/stm32mp15-bl2.dtsi}}).
  +
The device tree is part of the final STM32 file in order to be authenticated by the [[STM32_MPU_ROM_code_overview|ROM code]] and loaded at the same time in the [[SYSRAM_internal_memory|SYSRAM]].<br>
  +
It must be configured or updated depending on your platform.<br>
   
 
== STM32 binary file ==
 
== STM32 binary file ==
To be properly loaded into [[SYSRAM_internal_memory|SYSRAM]] by the [[STM32MP15_ROM_code_overview|ROM code]], the TF-A BL2 firmware needs to be encapsulated in a binary that starts with an STM32 header.
+
To be properly loaded into [[SYSRAM_internal_memory|SYSRAM]] by the [[STM32_MPU_ROM_code_overview|ROM code]], the TF-A BL2 firmware needs to be encapsulated in a binary that starts with a [[STM32_header_for_binary_files|STM32 header]].<br>
The [[STM32_header_for_binary_files|STM32 header]] information is mandatory for the [[STM32MP15_ROM_code_overview|ROM code]] to be able to load, authenticate and start the firmware.<br>
+
The [[STM32_header_for_binary_files|STM32 header]] information is mandatory for the [[STM32_MPU_ROM_code_overview|ROM code]] to be able to load, authenticate and start the firmware.<br>
As the ROM code can only load a single binary, the STM32 file must embed in a single image, the header, the device tree and the BL2 firmware. <br>
+
As the ROM code can only load a single binary, the STM32 file must embed in a single image, the header, the device tree and the BL2 binary firmware. <br>
  +
 
  +
TF-A BL2 is part of the trusted boot and can be signed to be authenticated by [[STM32_MPU_ROM_code_overview|ROM code]]. See [[Security_overview#Secure_boot|Secure boot]] process for more details.
   
TF-A BL2 is part of the trusted boot and can be signed to be authenticated by [[STM32MP15_ROM_code_overview|ROM code]]. See [[Security_overview#Secure_boot|Secure boot]] process for more details.
+
== Binary mapping ==
  +
Below the TF-A BL2 mapping including the STM32 header layout:
  +
[[File:Atf.stm32.png|600px|center|link=]]
   
== Device tree ==
+
The different sizes can be customized depending on build options and device tree customization. All sizes can be changed in the platform definition file. STM32MP1 platform uses {{ CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h }}:
TF-A BL2 is based on device tree configuration. It uses the same device tree as the kernel but keeping only the mandatory nodes for the boot stage (to reduce binary size) thanks to a dedicated device tree file (such as {{CodeSource | TF-A | fdts/stm32mp15-bl2.dtsi}}).
+
* STM32MP_BL2_DTB_BASE: device tree base address in SYSRAM with its associated SIZE
The device tree is part of the final STM32 file in order to be authenticated by the [[STM32MP15_ROM_code_overview|ROM code]] and loaded at the same time in the [[SYSRAM_internal_memory|SYSRAM]].<br>
+
* STM32MP_BL2_BASE: start address from which the code is loaded and executed
It must be configured or updated depending on your platform.<br>
+
* STM32MP_BL2_SIZE, which cannot exceed [[SYSRAM_internal_memory|SYSRAM]] size.
   
== Storage management ==
+
== Boot device ==
TF-A BL2 needs to access storage devices to load the [[How to configure TF-A FIP|FIP binary]]. By default, it uses the boot device selected by [[STM32MP15_ROM_code_overview#Boot_device_selection_via_the_boot_pins_and_OTP|boot pins or OTP]].<br>
+
=== External memory ===
  +
TF-A BL2 needs to access storage devices to load the other software components. By default, it uses the boot device selected by [[STM32_MPU_ROM_code_overview#Boot_device_selection_via_the_boot_pins_and_OTP|boot pins or OTP]].<br>
 
The selected device needs to be properly set up:
 
The selected device needs to be properly set up:
 
* Device tree configuration (all devices)
 
* Device tree configuration (all devices)
Line 24: Line 34:
 
Each device support needs a specific framework in the BL2 firmware.<br>
 
Each device support needs a specific framework in the BL2 firmware.<br>
 
By default, STMicroelectronics chose to select one single device support per binary. A BL2 with full storage support cannot fit in the [[SYSRAM_internal_memory|SYSRAM]] size.<br>
 
By default, STMicroelectronics chose to select one single device support per binary. A BL2 with full storage support cannot fit in the [[SYSRAM_internal_memory|SYSRAM]] size.<br>
Storage build flags allow the BL2 firmware to be configured to support the requested boot storage.
+
Storage [[How_to_configure_TF-A_BL2#TF-A_Build_flags|build flags]] allow the BL2 firmware to be configured to support the requested boot storage.
  +
 
  +
=== Serial mode (USB/UART) ===
  +
The Programmer mode (USB or UART boot device) requires the complete [[How to configure TF-A FIP|FIP binary]] to start the load image process as previously explained.
  +
This is achieved by loading the complete [[How to configure TF-A FIP|FIP binary]] into DDR before starting the normal boot sequence.
  +
The FIP load address configurable with DWL_BUFFER_BASE parameter. The default value is in {{CodeSource | TF-A | plat/st/stm32mp1/platform.mk}}
   
 
== DDR ==
 
== DDR ==
Line 30: Line 45:
 
DDR settings come from the device tree and must be adapted by the customer depending on DDR type, DDR configuration and boards.
 
DDR settings come from the device tree and must be adapted by the customer depending on DDR type, DDR configuration and boards.
 
This can be done using [[DDRCTRL_and_DDRPHYC_device_tree_configuration#How_to_configure_the_DT_using_STM32CubeMX|STM32CubeMX]].
 
This can be done using [[DDRCTRL_and_DDRPHYC_device_tree_configuration#How_to_configure_the_DT_using_STM32CubeMX|STM32CubeMX]].
  +
  +
=== DDR encryption ===
  +
On {{MicroprocessorDevice | device=13}}, a region of the DDR can be encrypted, thanks to [[DDRMCE_internal_peripheral|DDRMCE]]. Its configuration is done in TF-A [[TF-A_overview#Firmware_Configuration|Firmware configuration]] device tree, with the [[How_to_configure_TF-A_FW_CONFIG#DDR_Encryption_area|DDRMCE configuration]].
   
 
== Clock management ==
 
== Clock management ==
An initial [[Clock_device_tree_configuration_-_Bootloader_specific|clock tree]] must be set up to allow accessing the DDR and the external storage devices.<br>
+
An initial [[Clock_device_tree_configuration|clock tree]] must be set up to allow accessing the DDR and the external storage devices.<br>
 
It also improves the performance by increasing the default CPU speed and the storage transfer speed.
 
It also improves the performance by increasing the default CPU speed and the storage transfer speed.
   
== Binary mapping ==
+
== FIP ==
Below the TF-A BL2 mapping including the STM32 header layout:
+
The Firmware Image Package (FIP)<ref name=fip>{{DocSource | domain=TF-A | path=design/firmware-design.html#firmware-image-package-fip | text=Firmware Image Package}}</ref> is a TF-A archive binary that encapsulates bootloader images into a single archive.</br>  
[[File:Atf.stm32.png|600px|center|link=]]
+
It can also contain other data such as certificates that are required to complete the boot process.
 
 
The different sizes can be customized depending on build options and device tree customization. All sizes can be changed in the platform definition file. STM32MP1 platform uses {{ CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h }}:
 
* STM32MP_BL2_DTB_BASE: device tree base address in SYSRAM with its associated SIZE
 
* STM32MP_BL2_RO_BASE: start address from which the code is loaded and executed
 
* STM32MP_BL2_RW_BASE: start address of the read and write data used by the code. It depends on the STM32MP_BL2_RO_SIZE, which cannot exceed [[SYSRAM_internal_memory|SYSRAM]] size.
 
 
 
== BL2 load processing ==
 
Based on [[How to configure TF-A FIP|FIP]] and [[How to configure TF-A FW CONFIG|firmware configuration file]], the '''same''' BL2 can dynamically manage different secure environments:
 
* [[How to configure TF-A SP-MIN| TF-A SP_MIN]]
 
* [[OP-TEE_overview|OP-TEE]]
 
<br>
 
The BL2 process is executed as described below:
 
[[File:bl2_load_fconf.png|center|link=]]
 
<br>
 
# The [[STM32MP15_ROM_code_overview|ROM Code]] loads (and authenticates if required) the STM32 TF-A BL2 file together with its device tree.
 
# BL2 loads (and authenticates) [[How to configure TF-A FW CONFIG|FW_CONFIG]] file from [[How to configure TF-A FIP|FIP]]. BL2 parses the [[How to configure TF-A FW CONFIG|firmware configuration file]] to identify the load binary properties.
 
# BL2 loads (and authenticates) all the binaries listed in [[How to configure TF-A FW CONFIG|FW_CONFIG]] from [[How to configure TF-A FIP|FIP]].
 
 
 
=== FW_CONFIG ===
 
The [[How to configure TF-A FW CONFIG|FW_CONFIG]] file is based on the device tree. It describes the properties of the binaries to be loaded.
 
This file is mandatory in the [[How to configure TF-A FIP|FIP binary]] to dynamically configure BL2 so that it properly loads all images.
 
It depends on the DDR size, defined mapping and selected binaries.
 
More details on FW_CONFIG and its configuration can be found [[How to configure TF-A FW CONFIG|here]].
 
 
 
=== BL2 load in Programmer mode ===
 
The Programmer mode (USB or UART boot device) requires the complete [[How to configure TF-A FIP|FIP binary]] to start the load image process as previously explained.
 
This is achieved by loading the complete [[How to configure TF-A FIP|FIP binary]] into DDR before starting the normal boot sequence.
 
The FIP load address is fixed and must not override the next loaded address: <br>
 
DWL_BUFFER_BASE used in {{CodeSource | TF-A | plat/st/common/stm32_io_storage.c}}
 
 
 
=== Low-power mode ===
 
When exiting from low-power mode, BL2 has to wake up the DDR from self-refresh mode and reload only the binaries that have been lost.
 
{{Warning | When OP-TEE OS is used in Pager mode (using [[SYSRAM_internal_memory|SYSRAM]]), it can restore its content by itself thanks to the DDR backup and backup context}}.
 
 
 
== Trusted boot support ==
 
This is a key feature for the secure boot. It completes the [[STM32MP15_ROM_code_secure_boot|STM32 ROM code secure boot]] process.
 
This feature is enabled by defining the '''TRUSTED_BOARD_BOOT = 1''' build flag (not enabled by default).<br>
 
As soon as the flag is enabled, all the binaries loaded by the BL2 stage are authenticated. The certificates listed in the CoT are mandatory into the [[How to configure TF-A FIP|FIP binary]].
 
   
=== MBEDTLS ===
+
See the page [[How to configure TF-A FIP]] for more information.
When FIP is used, X509.v3 certificates are embedded in the package to authenticate all loaded binaries.
 
The certificate parsing is done using MBEDTLS. The MBEDTLS<ref name=mbedtls>https://github.com/ARMmbed/mbedtls</ref> project is partially used during the trusted boot build process to retrieve part of the library and parse the certificates.
 
The project must be downloaded close to the TF-A sources and the path using the MBEDTLS_DIR variable must be defined.
 
   
=== Disabling dynamic authentication ===
+
== FCONF ==
A '''DYN_DISABLE_AUTH''' flag can be used to build the full BL2 content (including the disable MDEBTLS files). It allows the authentication to be enabled or disabled using a device tree property:
+
The Firmware Configuration Framework (FCONF)<ref name=fconf>{{DocSource | domain=TF-A | path=components/fconf/index.html | text=Firmware Configuration Framework}}</ref> is a way to offer more flexibility in the firmware.
<pre>
 
disable_auth = <0x0>; // To enable authentication
 
disable_auth = <0x1>; // To bypass authentication
 
</pre>
 
This device tree property is located in the BL2 device tree (trusted boot device tree).
 
 
=== Cryptographic Library ===
 
The STM32 MPU uses its own cryptographic library (thanks to hardware accelerators or [[STM32MP15_ROM_code_overview|ROM Code]] services (STM32MP15 Only)) to verify certificate signatures: {{ CodeSource | TF-A | plat/st/common/stm32mp_crypto_lib.c }}
 
   
=== Keys ===
+
It is used to provide most of the platform-specific data that were previously hard coded inside the firmware.
The authentication is based on different keys and certificates. By default, the Arm<sup>&reg;</sup> TBBR CoT is used. The topology is defined in the BL2 device tree {{ CodeSource | TF-A | fdts/cot_descriptors.dtsi }} and can be customized using <link here to authentication article>.
+
This framework uses device tree (one or multiple) that are passed to the firmware during load processing.
The STM32 MPU uses the default [[STM32MP15_ROM_code_overview#OTP_WORD_24_to_31_-_Public_Key_Hash_-28PKH-29|public root key hash in OTP]] as main root key for the CoT. <br>
+
BL2 uses it for several purposes:
It can be modified by the customer [[BSEC_device_tree_configuration#STM32MP1_nvmem_layout_node_-28bootloader_specific-29| in device tree]] by redefining '''pkh_otp'''.
+
* list images to be loaded, with their load addresses and max sizes
  +
* DDR firewall configuration
  +
* describe the chain of trust parameters
   
During the development, the ROTPK hash is not mandatory. If it is not fused in OTP, it is seen as NOT DEPLOYED and the final ROTPK hash control is bypassed. However the entire CoT is verified.
+
TF-A BL2 configuration is done with a dedicated device tree file named FW_CONFIG.
{{Warning|The ROTPK hash must be in OTP before closing the chip}}
+
More details about the FW_CONFIG file are given by the page [[How to configure TF-A FW CONFIG]].
   
== Secure secret provisioning (SSP) ==
+
== Authentication ==
{{Warning| This feature is only available for STM32 MPU with cryptographic accelerators}}
+
TF-A BL2 manages authentication thanks to [[TF-A_BL2_Trusted_Board_Boot|Trusted Board Boot]] activation.
The STM32 MPU supports the [[Security_overview#Secure_Secret_Provisioning|SSP feature]]. Part of this feature is based on TF-A BL2:
 
* Exchange with STM32_CubeProgrammer
 
* Secure programing secret OTPs
 
   
 
<noinclude>
 
<noinclude>
{{PublicationRequestId | 19288| 2021-03-10 | PhilipS}}
+
{{PublicationRequestId | 19288| 2021-03-10 | reviewed by AnneJ in the article STM32 MPU TF-A (BL2) which has been split in 2 articles How_to_configure_TF-A_BL2 and this one}}
 
[[Category:Trusted Firmware-A (BL2)| 02]]
 
[[Category:Trusted Firmware-A (BL2)| 02]]
 
</noinclude>
 
</noinclude>