Approved version. Approved on: 09:13, 9 May 2022
You are viewing an old version of this page. Return to the latest version.
Difference between revisions of "How to configure TF-A FIP"
| [quality revision] | [quality revision] |
|
m
|
m
|
Contents
1 Article purpose[edit]
This section details the Trusted Firmware-A FIP (Firmware Image Package) usage in the STM32 MPU boot chain. It explains how to use it in STM32 MPU context and describes the build/update process that is required to deploy it on your target.
2 Overview[edit]
The FIP is used by the Trusted Firmware-A BL2 firmware to load and authenticate the next stage binaries.
The FIP follows the Trusted Firmware-A specification[1].
It must contains:
- All the boot stage firmware loaded by Trusted Firmware-A BL2.
- Configuration files.
3 Firmware Image Package creation tool[edit]
Trusted Firmware-A provides a dedicated tool name fiptool to create a FIP.[2]
If you want to regenerate it, you must follow the official documentation..[3]
The official documentation introduces the different available options.
Here is the list of the most useful options:
| Options | Description | Example |
|---|---|---|
| help | Show all available options supported | fiptool help |
| info | List the content of a FIP:
|
fiptool info fip.bin Secure Payload BL32 (Trusted OS): offset=0x128, size=0x2C, cmdline="--tos-fw" Secure Payload BL32 Extra1 (Trusted OS Extra1): offset=0x154, |
| update | Update allows one or more images to be replaced in an existing FIP binary | fiptool update --tos-fw bl32.bin fip.bin |
| unpack | Extracts all binaries from a FIP binary | fiptool unpack fip.bin |
| remove | Removes a binary from FIP binary | fiptool remove --tos-fw bl32.bin fip.bin |
4 FIP binary creation[edit]
Below the list of the different ways by which the FIP binary can be generated:
- Using the dedicated
fiptoolcommand - Using the Trusted Firmware-A official Makefile
4.1 STM32MP1[edit]
The OpenSTLinux boot flow requires the following stages to be loaded:
- BL32: Secure OS OP-TEE OS (or Secure Monitor SP-MIN on STM32MP15x lines
) - BL33: The non-secure firmware (recommended U-Boot)
- HW_config: The OpenSTLinux uses the hw_config as the non-secure device tree
- FW_config: Firmware configuration file listing the previous images and defining their size and the load address
The Trusted Firmware-A Makefile with fip target and some variables uses fiptool to automatically create the new FIP after the Trusted Firmware-A compilation.
With U-Boot as a non-secure firmware, the paths for the files used in next chapters are the following:
| Description | Makefile variable |
fiptool option | File path for OP-TEE | File path for SP_MIN Limited to STM32MP15x lines
|
|---|---|---|---|---|
| Secure OS (OP-TEE) or Secure Monitor (SPMIN) |
BL32 | --tos-fw | <optee_path>/tee-header_v2.bin | <tfa_path>/bl32.bin |
| OP-TEE pager | BL32_EXTRA1 | --tos-fw-extra1 | <optee_path>/tee-pager_v2.bin | - |
| OPTEE pageable | BL32_EXTRA2 | --tos-fw-extra2 | <optee_path>/tee-pageable_v2.bin | - |
| Firmware configuration file | FW_CONFIG | --fw-config | <tfa_path>/fw-config.dtb | |
| U-Boot device tree | BL33_CFG | --hw-config | <u-boot_path>/u-boot.dtb | |
| U-Boot | BL33 | --nt-fw | <u-boot_path>/u-boot-nodtb.bin | |
4.2 Updating the FIP binary[edit]
When modifying a component included in the FIP binary, it is possible to update only part of the binary. To do this, use the fiptool update command.
Example when a new U-Boot is generated, the FIP must be updated using the following commands:
- Full U-Boot update (U-Boot Binary and U-Boot Device tree)
fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config <u-boot_path>/u-boot.dtb fip.bin
5 Updating the software on board[edit]
5.1 Partitioning of binaries[edit]
The FIP build provides a binary named fip.bin (or fip-<board-name>-<bootchain>.bin from official release) that MUST be copied to a dedicated partition named fip, fip-a or fip-b when Secure Firmware Update is enabled.
5.2 Updating via SDCard[edit]
If you use an SDCard, simply update the FIP binary by using the dd command on your host.
Plug your SDCard into the computer and copy the binary to the dedicated partition; on an SDCard/USB disk the fip partition or fip-a/fip-b when Secure Firmware Update is enabled:
- SDCard: /dev/mmcblkXpY (where X is the instance number, Y is the partition number of the FIP) - SDCard via USB reader: /dev/sdXY (where X is the instance number, Y is the partition number of the FIP))
- Under Linux®
dd if=<fip binary file> of=/dev/<device partition> bs=1M conv=fdatasync
- Under Windows®
CoreUtils [4] that includes the dd command is available for Windows.
5.3 Updating via USB mass storage on U-boot[edit]
See How to use USB mass storage in U-Boot.
Refer to the previous section to put FIP binary into SDCard/USB disk.
5.4 Updating your boot device via STM32CubeProgrammer[edit]
Refer to the STM32CubeProgrammer documentation for details on how to update your target.
6 References[edit]
{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}<noinclude></noinclude>
== Article purpose ==
This section details the Trusted Firmware-A FIP (Firmware Image Package) usage in the STM32 MPU boot chain. It explains how to use it in STM32 MPU context and describes the build/update process that is required to deploy it on your target.
== Overview ==
The FIP is used by the [[How to configure TF-A BL2|Trusted Firmware-A BL2]] firmware to load and authenticate the next stage binaries.
The FIP follows the Trusted Firmware-A specification<ref>{{DocSource | domain=TF-A | path=design/firmware-design.html#firmware-image-package-fip | text=Firmware Image Package design}}</ref>.
It must contains:
* All the boot stage firmware loaded by [[TF-A_BL2_overview|Trusted Firmware-A BL2]].
* Configuration files.
{{Warning| If [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[TODO link to secure bootTF-A_BL2_Trusted_Board_Boot|TRUSTED_BOARD_BOOT]] enabled, the FIP must also contains:
* Certificates (X509.3 based) for authentication.
}}
== Firmware Image Package creation tool ==
Trusted Firmware-A provides a dedicated tool name <code>fiptool</code> to create a FIP.<ref>{{DocSource | domain=TF-A | path=design/firmware-design.html#firmware-image-package-creation-tool | text=Firmware Image Package tool}}</ref>
{{Info|By default, the OpenSTLinux SDK provides the <code>fiptool</code> command. You do not need to regenerate it to update (or create) a FIP binary.}}
If you want to regenerate it, you must follow the official documentation..<ref>{{DocSource | domain=TF-A | path=getting_started/tools-build.html#building-and-using-the-fip-tool | text= Building and using the fiptool}}</ref><br>
The official documentation introduces the different available options.
Here is the list of the most useful options:
{| class="st-table"
|-
! Options !! Description !! Example
|-
| help || Show all available options supported || {{PC$}} fiptool help
|-
| info || List the content of a FIP:
*offset in the FIP
*size in the FIP
*cmdline option to modify the binary
|| {{PC$}} fiptool info fip.bin
Secure Payload BL32 (Trusted OS): offset=0x128, size=0x2C, cmdline="--tos-fw"
Secure Payload BL32 Extra1 (Trusted OS Extra1): offset=0x154,<br> size=0x18750, cmdline="--tos-fw-extra1"
Secure Payload BL32 Extra2 (Trusted OS Extra2): offset=0x188A4,<br> size=0x56000, cmdline="--tos-fw-extra2"
Non-Trusted Firmware BL33: offset=0x6E8A4, size=0xECE98, cmdline="--nt-fw"
FW_CONFIG: offset=0x15B73C, size=0x1FA, cmdline="--fw-config"
HW_CONFIG: offset=0x15B936, size=0x1BC08, cmdline="--hw-config"
|-
| update || Update allows one or more images to be replaced in an existing FIP binary || {{PC$}} fiptool update --tos-fw bl32.bin fip.bin
|-
| unpack || Extracts all binaries from a FIP binary || {{PC$}} fiptool unpack fip.bin
|-
| remove || Removes a binary from FIP binary || {{PC$}} fiptool remove --tos-fw bl32.bin fip.bin
|}
== FIP binary creation ==
Below the list of the different ways by which the FIP binary can be generated:
* Using the dedicated <code>fiptool</code> command
* Using the Trusted Firmware-A official Makefile
=== STM32MP1 ===
The OpenSTLinux boot flow requires the following stages to be loaded:
* BL32: Secure OS [[How to configure OP-TEE|OP-TEE OS]] (or Secure Monitor [[How to configure TF-A SP-MIN|SP-MIN]] on {{MicroprocessorDevice | device=15}})
* BL33: The non-secure firmware (recommended [[U-Boot|U-Boot]])
* HW_config: The OpenSTLinux uses the hw_config as the non-secure device tree
* FW_config: [[How to configure TF-A FW CONFIG|Firmware configuration file]] listing the previous images and defining their size and the load address
The Trusted Firmware-A Makefile with '''fip''' target and some variables uses <code>fiptool</code> to automatically create the new FIP after the Trusted Firmware-A compilation.
With U-Boot as a non-secure firmware, the paths for the files used in next chapters are the following:
{| class="st-table"
|-
! Description !! Makefile<br/>variable!! fiptool option !! File path for OP-TEE !! File path for SP_MIN <br> Limited to {{MicroprocessorDevice | device=15}}
|-
| Secure OS (OP-TEE) <br/>or Secure Monitor (SPMIN) || BL32 || --tos-fw || [[How to configure OP-TEE #Build_OP-TEE_OS|<optee_path>/tee-header_v2.bin]] || [[How to configure TF-A SP-MIN#Build_Process|<tfa_path>/bl32.bin]]
|-
| OP-TEE pager || BL32_EXTRA1 || --tos-fw-extra1 || [[How to configure OP-TEE #Build_OP-TEE_OS|<optee_path>/tee-pager_v2.bin]] || -
|-
| OPTEE pageable || BL32_EXTRA2 || --tos-fw-extra2 || [[How to configure OP-TEE#Build_OP-TEE_OS|<optee_path>/tee-pageable_v2.bin]]|| -
|-
| Firmware configuration file || FW_CONFIG|| --fw-config || colspan="2" | [[How to configure TF-A FW CONFIG|<tfa_path>/fw-config.dtb]]
|-
| U-Boot device tree || BL33_CFG || --hw-config || colspan="2" | [[STM32MP15_U-Boot#Compilation|<u-boot_path>/u-boot.dtb]]
|-
| U-Boot || BL33|| --nt-fw || colspan="2" | [[STM32MP15_U-Boot#Compilation|<u-boot_path>/u-boot-nodtb.bin]]
|-
|}
{{Warning| If [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[TODO link to secure boot|TRUSTED_BOARD_BOOT]] enabled, some specific options and files are required. See the [[TODO|Trusted boot page]] for more details.}}
=== Updating the FIP binary ===
When modifying a component included in the FIP binary, it is possible to update only part of the binary. To do this, use the <code>fiptool</code> update command.
Example when a new U-Boot is generated, the FIP must be updated using the following commands:
* Full U-Boot update (U-Boot Binary and U-Boot Device tree)
{{PC$}} fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config <u-boot_path>/u-boot.dtb fip.bin
{{Warning | When updating a binary in the FIP when the [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[TODO link to secure bootTF-A_BL2_Trusted_Board_Boot|TRUSTED_BOARD_BOOT]] enabled, the content certificate must be updated too. See the [[TODO|Trusted boot pageTF-A_BL2_Trusted_Board_Boot|Trusted Board Boot]] for more details.}}
== Updating the software on board ==
=== Partitioning of binaries ===
The FIP build provides a binary named fip.bin (or fip-<board-name>-<bootchain>.bin from official release) that MUST be copied to a dedicated partition named '''fip''', '''fip-a''' or '''fip-b''' when [[Secure Firmware Update]] is enabled.
=== Updating via SDCard ===
If you use an SDCard, simply update the FIP binary by using the dd command on your host.<br>
Plug your SDCard into the computer and copy the binary to the dedicated partition; on an SDCard/USB disk the '''fip''' partition or '''fip-a'''/'''fip-b''' when [[Secure Firmware Update]] is enabled:
- SDCard: /dev/mmcblkXpY (where X is the instance number, Y is the partition number of the FIP)
- SDCard via USB reader: /dev/sdXY (where X is the instance number, Y is the partition number of the FIP))
* Under Linux<sup>®</sup>
{{PC$}} dd if=<fip binary file> of=/dev/<device partition> bs=1M conv=fdatasync
{{Info| To find the partition associated to a specific label, just plug the SDCard/USB disk into your PC and call the following command:
{{PC$}} ls -l /dev/disk/by-partlabel/
total 0
lrwxrwxrwx 1 root root 10 May 3 15:14 bootfs -> ../../sda8
lrwxrwxrwx 1 root root 10 May 3 15:14 fip-a -> ../../sda5 FIP (Image A)
lrwxrwxrwx 1 root root 10 May 3 15:14 fip-b -> ../../sda6 FIP (Image B)
lrwxrwxrwx 1 root root 10 May 3 15:14 fsbl1 -> ../../sda1 FSBL1 (Trusted Firmware-A BL2)
lrwxrwxrwx 1 root root 10 May 3 15:14 fsbl2 -> ../../sda2 FSBL2 (Trusted Firmware-A BL2 backup)
lrwxrwxrwx 1 root root 10 May 3 15:14 metadata1 -> ../../sda3
lrwxrwxrwx 1 root root 10 May 3 15:14 metadata2 -> ../../sda4
lrwxrwxrwx 1 root root 11 May 3 15:14 rootfs -> ../../sda10
lrwxrwxrwx 1 root root 10 May 3 15:14 u-boot-env -> ../../sda7
lrwxrwxrwx 1 root root 11 May 3 15:14 userfs -> ../../sda11
lrwxrwxrwx 1 root root 10 May 3 15:14 vendorfs -> ../../sda9
}}<br>
* Under Windows<sup>®</sup>
CoreUtils <ref>http://gnuwin32.sourceforge.net/packages/coreutils.htm</ref> that includes the dd command is available for Windows.
=== Updating via USB mass storage on U-boot ===
See [[How to use USB mass storage in U-Boot]].
Refer to the previous section to put FIP binary into SDCard/USB disk.
=== Updating your boot device via STM32CubeProgrammer ===
Refer to the [[STM32CubeProgrammer]] documentation for details on how to update your target.
== References ==<references />
<noinclude>
[[Category:Platform configuration]]
{{PublicationRequestId | 19289 | 2120-03-10 | }}</noinclude>| Line 16: | Line 16: | ||
* Configuration files. |
* Configuration files. |
||
| − | {{Warning| If [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[ |
+ | {{Warning| If [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[TF-A_BL2_Trusted_Board_Boot|TRUSTED_BOARD_BOOT]] enabled, the FIP must also contains: |
* Certificates (X509.3 based) for authentication. |
* Certificates (X509.3 based) for authentication. |
||
}} |
}} |
||
| Line 98: | Line 98: | ||
{{PC$}} fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config <u-boot_path>/u-boot.dtb fip.bin |
{{PC$}} fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config <u-boot_path>/u-boot.dtb fip.bin |
||
| − | {{Warning | When updating a binary in the FIP when the [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[ |
+ | {{Warning | When updating a binary in the FIP when the [[TF-A_BL2_overview|Trusted Firmware-A BL2]] is built with [[TF-A_BL2_Trusted_Board_Boot|TRUSTED_BOARD_BOOT]] enabled, the content certificate must be updated too. See the [[TF-A_BL2_Trusted_Board_Boot|Trusted Board Boot]] for more details.}} |
== Updating the software on board == |
== Updating the software on board == |
||