Wrapper for FSBL images

1. 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 covers also the case of closed devices.

2. Introduction

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 Software distribution 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.

2.1. Workaround (not suggested)

One possible workaround consists in modifying the FSBL code, by adding an infinite loop at the entry point; the boot stops looping at the entry point, the debugger can attach the device and halt the execution. Then the debugger skips the infinite loop to advance 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 changes too;
• the people in charge of debug are required to have knowledge on recompiling FSBL and signing it (only in case of closed devices);
• debugger cannot attach to a pre-existing binary FSBL.

2.2. Wrapper for FSBL

The solution proposed through stm32wrapper4dbg is to modify an existing FSBL image by adding a binary wrapper, as in the image below:

The existing FSBL is loaded in memory at the same address as before.

The new FSBL entry point is in the wrapper, that opens the debug port, waits 2 seconds for the debugger to attach, then

• if no debugger attaches, the wrapper will jump to execute the original FSBL keeping the debug port open;
• if a debugger attaches, the wrapper will jump and halt at the entry point of the original FSBL.

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

3. Installing the stm32wrapper4dbg tool

The tool is installed on the host PC as part of the Developer Package.

Note: the tool is also part of the Distribution Package, which automatically creates a wrapped FSBL each time a new FSBL is built.

4. Getting started

This chapter describes how to add a wrapper to an existing FSBL image.

4.1. Prerequisites

The distribution package should be already installed; the FSBL image to be wrapped should be already available.

4.3. Wrap a signed FSBL image

Link to image signing article.

First Stage Boot Loader

Read Only Memory