Wrapper for FSBL images

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

1. Article purpose[edit source]

This article provides the basic information needed to start using the application tool stm32wrapper4dbg.

It explains how to use the tool to wrap an existing FSBL image and create a debug FSBL image, suitable for attaching a debugger at boot.

This article also covers the case of closed devices that require a signed image.

2. Introduction[edit source]

The following table provides a brief description of the tool, as well as its availability depending on the software packages:

: this tool is either present (ready to use or to be activated), or can be integrated and activated on the software package.

: this tool is not present and cannot be integrated, or it is present but cannot be activated on the software package.

Tool

STM32MPU Embedded Software distribution

STM32MPU Embedded Softwaredistribution for Android™

Warning

The STM32MPU distribution for Android™ is not yet available in the v3 ecosystem releases: refer to the Wrapper for FSBL images page for the v2 ecosystem releases (in archived wiki).

Name

2.1. Workaround (not recommended)[edit source]

To halt the execution at FSBL entry point, a possible workaround consists in modifying the FSBL code, adding an infinite loop at the entry point. The boot process stops looping at the entry point. The debugger can then attach the device and halt the execution. The debugger then skips the infinite loop, advancing the execution to the first real FSBL instruction.

The workaround above has few drawbacks:

By modifying and recompiling the FSBL code, the memory layout of the FSBL binary is also modified. This can prevent reproducing the error conditions that have to be debugged.
People in charge of debugging must have knowledge of FSBL recompiling and (only in case of closed devices) signing it.
Preexisting FSBL binary cannot be debugged.

2.2. Wrapper for FSBL[edit source]

To halt the execution at FSBL entry point, STMicroelectronics proposes a less invasive method through the tool stm32wrapper4dbg. The image below describes how stm32wrapper4dbg works.

The stm32wrapper4dbg tool takes an existing FSBL image and generates a new FSBL image by appending (or prepending) a binary wrapper to the image and updating the image header accordingly. Using the new image causes the FSBL binary to be loaded in memory at the same address as before. The memory layout does not change.

Since the new image entry point is in the wrapper, it will be executed before the FSBL. The wrapper opens the debug port, waits 2 seconds for the debugger to attach, then:

if no debugger attaches, the wrapper jumps to execute the FSBL, thus proceeding in the boot process while keeping the debug port open,
if a debugger attaches, the wrapper jumps and halts at the entry point of the FSBL. The debugger will identify the halt condition.

The new wrapped image has to replace the original image in Flash memory for the whole debug session.

For a complete description of the FSBL image header, go through header for STM32 binary files.

3. Prerequisites[edit source]

Use either the Distribution Package or the Developer Package.

4. Installing the stm32wrapper4dbg tool[edit source]

The tool is installed on the host PC as part of the Developer Package. It is also included as internal tool in the Distribution Package, which automatically creates a wrapped FSBL each time a new FSBL is built.

No installation is thus required.

5. Getting started with the Distribution Package[edit source]

The Distribution Package creates the wrapped FSBL each time a new FSBL is built. No additional commands are required from the user.

All the wrapped FSBLs are available in the dedicated "debug" subfolders of "arm-trusted-firmware".

5.1. Flashing the wrapped FSBL[edit source]

If a signed image is required, sign the image in "arm-trusted-firmware/debug/" following the description given in image signing.

If STM32CubeProgrammer is used for writing to the Flash memory, create a modified Flash layout "tsv" and replace the name and location of the original FSBL image file by the ones of the wrapped FSBL file, as described in flash layout description.

6. Getting started with Developer Package[edit source]

To generate a Trusted Firmware-A BL2 as FSBL, go through TF-A for how to compile.

6.1. Wrapping an FSBL image[edit source]

Use the following command to wrap an original.stm32 FSBL image and create a wrapped.stm32 wrapped FSBL image:

 source <Your_SDK_path>/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi
 stm32wrapper4dbg -s original.stm32 -d wrapped.stm32

All the FSBL images created by STMicroelectronics toolchains are loaded at the lower available memory address, thus stm32wrapper4dbg appends the wrapper at the end of the image memory map. Instead, on customized FSBLs, the memory map can be different and the only available space for the wrapper can be located at the beginning of image memory map. The -b flag can be used to generate a wrapped image that has the wrapper before the FSBL. This also means that the load address is decremented by the size of the wrapper.

 stm32wrapper4dbg -s original.stm32 -d wrapped.stm32 -b

6.2. Wrapping a signed FSBL image[edit source]

When stm32wrapper4dbg is used on a signed FSBL image, it detects the signature and displays a warning message. Since stm32wrapper4dbg cannot sign the wrapped image (it has no access to the user's private keys), the user has to sign the wrapped image using the usual signing process, as explained in image signing.

6.3. Loading the wrapped FSBL to Flash memory[edit source]

The wrapped FSBL image has to replace the FSBL present in the board Flash memory.

If STM32CubeProgrammer is used for writing to the Flash memory, modify the Flash layout "tsv" to replace the name and location of the original FSBL image file with the wrapped FSBL file, as described in flash layout description.

If the Flash memory is an SD card, it is also possible to plug the SD card in the Linux^® PC that runs the Development Package and let stm32wrapper4dbg write the wrapped image directly into the first partition of the SD card. Assuming the SD card is recognized as /dev/sdb by the Linux PC, run:

 stm32wrapper4dbg -s original.stm32 -d /dev/sdb1

In addition, since the second partition of the SD card contains a copy of the original image, it is possible to write into the first partition a wrapped version of the FSBL already stored in the second partition with the command

 stm32wrapper4dbg -s /dev/sdb2 -d /dev/sdb1

7. Modifying a Flash layout tsv file[edit source]

Create a copy of an existing Flash layout "tsv" file, compatible with your board, for example:

 cp flashlayout_st-image-weston/trusted/FlashLayout_sdcard_stm32mp157c-dk2-trusted.tsv flashlayout_st-image-weston/trusted/debug_FlashLayout_sdcard_stm32mp157c-dk2-trusted.tsv

then edit it and replace in the lines of FSBL

P 0x04 fsbl1 Binary mmc0 0x00004400 arm-trusted-firmware/tf-a-stm32mp157c-dk2-trusted.stm32
P 0x05 fsbl2 Binary mmc0 0x00044400 arm-trusted-firmware/tf-a-stm32mp157c-dk2-trusted.stm32

the path of the FSBL image with the debug version

P 0x04 fsbl1 Binary mmc0 0x00004400 arm-trusted-firmware/debug/debug-tf-a-stm32mp157c-dk2-trusted.stm32
P 0x05 fsbl2 Binary mmc0 0x00044400 arm-trusted-firmware/debug/debug-tf-a-stm32mp157c-dk2-trusted.stm32

8. References[edit source]

None