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 covers also 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™ | ||||||
|---|---|---|---|---|---|---|---|---|
| Name | Category | Purpose | Starter Package | Developer Package | Distribution Package | Starter Package | Developer Package | Distribution Package |
| stm32wrapper4dbg | Debugging tools | The tool stm32wrapper4dbg wraps a STM32 FSBL image to allows a debugger to halt the boot at the first executable instruction of FSBL. |
* |
|
**
|
|
|
|
| * Cross compile gdb and openocd binaries are required and only available from Developer Package. ** It is recommended to use the Developer Package to run the gdb debug session, which provided all dependencies |
||||||||
Please refer to boot chains overview for a complete description of the boot process.
To debug the FSBL code, the debugger should halt the execution:
- either at the very first instruction (entry point) of the FSBL
- or earlier in the ROM code and then proceed till the FSBL entry point.
The ROM code execution cannot be halted deterministically, while in case of closed devices cannot be halted at all. The tool stm32wrapper4dbg allows the debugger to halt the execution at FSBL entry point.
2.1. Workaround (not suggested)[edit source]
To halt the execution at FSBL entry point, one possible workaround consists by modifying the FSBL code, adding an infinite loop at the entry point. The boot process will stop looping at the entry point; the debugger can then attach the device and halt the execution; the debugger would then skip the infinite loop, advancing the execution to the real first instruction of FSBL.
The workaround above has few drawbacks:
- by modify and recompile 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 debug are required to have knowledge on recompiling FSBL and (only in case of closed devices) signing it;
- pre-existing binary FSBL cannot be debugged.
2.2. Wrapper for FSBL[edit source]
To halt the execution at FSBL entry point, ST proposes a less invasive method through the tool stm32wrapper4dbg. The image below describes how stm32wrapper4dbg works.
The tool stm32wrapper4dbg 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 will cause the binary FSBL to be loaded in memory at the same address as before; no change occurs in the memory layout.
The new image entry point is in the wrapper, so 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 will jump to execute the FSBL, thus continuing in the boot process while keeping the debug port open;
- if a debugger attaches, the wrapper will jump and halt 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 for all the degug session.
For a complete description of the FSBL image header, check header for STM32 binary files.
3. Prerequisites[edit source]
Either Distribution Package or Developer Package should be used.
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 Distribution Package[edit source]
The Distribution Package creates the wrapped FSBL each time a new FSBL is build. No additional commands are required from the user.
All the wrapped FSBL are available in dedicated sub-folders "debug" of "arm-trusted-firmware".
5.1. Flash the wrapped FSBL[edit source]
If a signed image is required, user has to sign the image in "arm-trusted-firmware/debug/" following the description in image signing.
If STM32CubeProgrammer is used for writing in the flash, user has to create a modified flash layout "tsv" in which he/she replaces the name and location of the original FSBL image file with the ones of wrapped FSBL file, as described in flash layout description.
6. Getting started with Developer Package[edit source]
To know how to compile TF-A and thus generating a BL2 FSBL, check how to compile TF-A.
6.1. Wrap a FSBL image[edit source]
To wrap a FSBL image original.stm32 and create a wrapped FSBL image wrapped.stm32 use the command:
stm32wrapper4dbg -f original.stm32 -t wrapped.stm32
All the FSBL created by ST toolchains are loaded at the lower available memory address, thus stm32wrapper4dbg appends the wrapper at the end of the image's memory map. On customized FSBL, instead, the memory map could be different and the only available space for the wrapper could be at the beginning of image's memory map. The flag -b 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 -f original.stm32 -t wrapped.stm32 -b
6.2. Wrap a signed FSBL image[edit source]
When stm32wrapper4dbg is executed on a signed FSBL image, it will detect the signature and show 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. Flash the wrapped FSBL[edit source]
The wrapped FSBL image has to replace the FSBL present in the board's flash.
If STM32CubeProgrammer is used for writing in the flash, user has to 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 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 to write the wrapped image directly on the first partition of the SD card. Assuming the SD card is recognized as /dev/sdb by the Linux PC, run:
stm32wrapper4dbg -f original.stm32 -t /dev/sdb1
Also, since the second partition of the SD card contains a copy of the original image, it is possible to write in the first partition a wrapped version of the FSBL from the second partition with the command
stm32wrapper4dbg -f /dev/sdb2 -t /dev/sdb1
7. How to modify a flash layout tsv file[edit source]
Create a copy of an existing flash layout "tsv" file, compatible with your board, e.g.
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