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)

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 will 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 some error condition;
• the 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

To halt the execution at FSBL entry point, ST proposes a less invasive method through the tool stm32wrapper4dbg, as described in the image below:

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. The new image will cause the 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 keeping the debug port open;
• if a debugger attaches, the wrapper will jump and halt at the entry point of the FSBL.

During the debug session, the new (wrapped) image has to replace the original image in flash.

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

Flash memory shortened to gain space in titles, tables and block diagrams