View source for Wrapper for FSBL images

==Article purpose==
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 '''[[STM32MP15 secure boot#Closing the device | closed devices]]''' that require a signed image.

== Introduction ==

{{:Trace_and_debug_tools_assignment_table_template}}
<onlyinclude>
| rowspan="2" | [[Wrapper for FSBL images|stm32wrapper4dbg]]
| rowspan="2" | [[:Category:Debugging tools|Debugging tools]]
| rowspan="2" style="text-align:left;" | The stm32wrapper4dbg tool wraps an STM32 FSBL image to enable a debugger to halt the boot at the first executable instruction of FSBL.<br>
| {{N}}&#42; || {{Y}} || {{Y}}&#42;&#42;
| {{N}} || {{N}} || {{N}}
|-
| colspan="3" style="text-align:left;font-size:70%;" | &#42; ''Cross compiled gdb and openocd binaries are required and only available from the Developer Package.''<br>&#42;&#42; ''It is recommended to use the Developer Package to run the gdb debug session, which provides all dependencies.''
| colspan="3"  |
|-
</onlyinclude>
|}

Please refer to [[Boot chain overview | boot chain overview]] for a complete description of the boot process.

To debug the FSBL code, the debugger must 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. In case of closed devices, it cannot be halted at all. The stm32wrapper4dbg tool enables the debugger to halt the execution at FSBL entry point.

=== Workaround (not recommended) ===

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.

=== Wrapper for FSBL ===

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.

[[File:stm32wrapper4dbg.png | center | | 400px]]

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 [[STM32 header for binary files | header for STM32 binary files]].

== Prerequisites ==

Use either the Distribution Package or the Developer Package.

== Installing the stm32wrapper4dbg tool ==

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.

== Getting started with the Distribution Package ==

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".

=== Flashing the wrapped FSBL ===

If a signed image is required, sign the image in "arm-trusted-firmware/debug/" following the description given in [[STM32MP15 secure boot#Image signing | 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 [[STM32CubeProgrammer flashlayout | flash layout description]].

== Getting started with Developer Package ==

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

=== Wrapping an FSBL image ===

Use the following command to wrap an ''original.stm32'' FSBL image and create a ''wrapped.stm32'' wrapped FSBL image:
 {{PC$}} source {{HighlightParam|''<Your_SDK_path>''}}/{{EcosystemRelease/Package | revision=2.0.0 | package=SDK setup script | request=name}}
 {{PC$}} 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.
 {{PC$}} stm32wrapper4dbg -s original.stm32 -d wrapped.stm32 -b

=== Wrapping a signed FSBL image ===

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 [[STM32MP15 secure boot#Image signing | image signing]].

=== Loading the wrapped FSBL to Flash memory  ===

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 [[STM32CubeProgrammer flashlayout | flash layout description]].

If the Flash memory is an SD card, it is also possible to plug the SD card in the Linux<sup>&reg;</sup> 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 {{green |'''/dev/sdb'''}} by the Linux PC, run:
 {{PC$}} stm32wrapper4dbg -s original.stm32 -d {{green |'''/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
 {{PC$}} stm32wrapper4dbg -s {{green |'''/dev/sdb2'''}} -d {{green |'''/dev/sdb1'''}}

== Modifying a Flash layout tsv file ==

Create a copy of an existing Flash layout "tsv" file, compatible with your board, for example:
 {{PC$}} 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 {{orange |arm-trusted-firmware/tf-a-stm32mp157c-dk2-trusted.stm32}}
 P 0x05 fsbl2 Binary mmc0 0x00044400 {{orange |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 {{orange |arm-trusted-firmware/}}{{red |'''debug/debug-'''}}{{orange |tf-a-stm32mp157c-dk2-trusted.stm32}}
 P 0x05 fsbl2 Binary mmc0 0x00044400 {{orange |arm-trusted-firmware/}}{{red |'''debug/debug-'''}}{{orange |tf-a-stm32mp157c-dk2-trusted.stm32}}

== References ==
None
<references />


<noinclude>
{{ ArticleBasedOnModel | Trace and debug tools article model }}
{{PublicationRequestId | 16810 | 09-07-2020 |first publication}}

[[Category:Debugging tools]]
</noinclude>