1. Overview
This article describes PRG-TOOLBOX-FB , an open-source tool provided by STMicroelectronics. This tool is designed to take advantage of Fastboot high transfer bandwidth, to write into external flash memory (like eMMC, SDMMC…).
Fastboot (FB) is a protocol that was originally created for Android™ and is primarily used to modify the flash filesystem via a USB connection from a host computer.
The tool is a wrapper for Fastboot. It is specifically designed for STM32 MPU products.
PRG-TOOLBOX-FB provides a source application whose characteristics are the following:
- Language: Native C++ 11
- IDE: Qt® Creator
- Cross-platform: Windows, Linux®
- Dependency: Fastboot application v34.0.5
- Copyrights: STMicroelectronics
- License": Apache v2.0
The functional chart of the tool, describing all involved components, is available below:
2. Prerequisites
The tool is available in console mode, and there are a few important points to keep in mind before preparing your development environment.
2.1. Hardware prerequisites
- Make sure that the used STM32 MPU device is supported.
2.2. Software prerequisites
- The OpenSTLinux distribution software v5.0.3 release (or later) must be used, refer to OpenSTLinux distribution software v5.0.3 release.
- The firmware binaries used must correspond to the specific board you are using, otherwise an error occurs.
- A TSV flashlayout file, describing the partitions and the memory map, must be prepared (refer to STM32CubeProgrammer flashlayout).
- PRG-TOOLBOX-FB is not intended for handling OTP partition.
- U-Boot in Fastboot mode is running, refer to How to configure U-Boot to support Fastboot mode.
2.3. Linux host environment
To ensure that PRG-TOOLBOX-FB has read and write access to the USB Fastboot devices running by the STM32 MPU device, you need to install udev rules. This can be done by copying the rules file located in the "/rules" folder to the "/etc/udev/rules.d/" directory.
Example on Ubuntu:
cd /PRG-TOOLBOX-FB/rules
sudo cp *.* /etc/udev/rules.d
2.4. Windows Fastboot driver
To install the Fastboot driver in your Windows machine and to well identify the STM32 MPU device, you first need to locate the driver in the project tree under the "Fastboot_usb_driver" folder. Once you have found the driver, right-click on the ".info" file and select "Install" from the context menu.
After the installation is complete, the STM32 Fastboot Device be identified as the Fastboot stack running on the STM32 MPU device. This device is then ready to provide the flashing service through the Fastboot interface.
3. License
PRG-TOOLBOX-FB is released under the Apache v2.0 .
A copy of the GNU General Public License version 2 is delivered with the tool's source code.
4. How to build the PRG-TOOLBOX-FB project
The package provides a pre-configured Qt® project (see ".pro" file). There are three ways to compile the project:
- 1. Qt® Creator IDE : Open the project in the IDE, configure your kit compiler, and run the build.
- 2. Qmake : It is possible to compile the project in the command line without using Qt® Creator IDE by following the next steps:
- Run the qmake command: qmake PRG-TOOLBOX-FB.pro
- Run the make command to build your project: make (or "mingw32-make.exe" on Windows)
In case you do not intend to use Qt® Creator IDE on your Linux® machine, you can simply install the "qmake" component along with its Qt® libraries. To do so, execute the following commands in the terminal before launching qmake:
sudo apt update
sudo apt install qtbase5-dev
sudo apt install qt5-qmake qttools5-dev-tools
Make sure that a G++ compiler is already installed on your machine; otherwise, you need to install it.
sudo apt install build-essential
Once the build process is complete, an executable file is generated in the same directory as the ".pro" file. (On Windows, you should install Qt® Creator on your machine.)
- 3. Makefile : You need to create your own Makefile to be able to build the project without need to install Qt® Creator, then you can execute "make".
5. Command usage
The tools includes a set of command lines that enable users to easily flash and manage the STM32 MPU devices. The program "Fastboot" is integrated into this tool to facilitate communication and execute Fastboot commands. If an error occurs during the execution of a command operation, the return code is set to 1 (EXIT_FAILURE) and exits immediately. However, if the command operation is executed successfully, the return code is set to 0 (EXIT_SUCCESS), indicating a successful operation.
5.1. Help
Show the help menu
Syntax: -?, -h, --help
5.2. Version
Display the tool’s version in format x.y.z [Major.Minor.Patch]
Syntax: -v, --version
5.3. Download
Download the list of firmware files mentioned in the TSV file into the flash memory except boot partitions.
Syntax: -d, --download <filePath.tsv>
- <filePath.tsv> : Indicates the TSV file path describing the flash memory layout.
Example:
PRG-TOOLBOX-FB -d FlashLayout_sdcard_stm32mp157f-dk2-Fastboot.tsv
The tool makes several checks and follows a specific sequence to establish a connection in Fastboot mode and flash the list of partitions. At the end of the flashing process, the tool displays the total elapsed time in the following format: [x] minutes, [y] seconds, [z] milliseconds.
PRG-TOOLBOX-FB -d FlashLayout_sdcard_stm32mp157f-dk2-Fastboot.tsv [Output example] Fastboot application path : /local/home/stm/Desktop/PRG-TOOLBOX-FB/Fastboot/Linux/Fastboot U-Boot in Fastboot mode is running ! ----------------------------------------- TSV Fastboot downloading... TSV path : /local/home/stm/Desktop/baseline_stm32mp1_Fastboot/baseline_Fastboot_citools/FlashLayout_sdcard_stm32mp157f-dk2-Fastboot.tsv Partitions number : 13 ----------------------------------------- Memory partitioning... Fastboot application path : /local/home/stm/Desktop/PRG-TOOLBOX-FB/Fastboot/Linux/Fastboot Fastboot command: /local/home/stm/Desktop/PRG-TOOLBOX-FB/Fastboot/Linux/Fastboot oem format 2>&1 OKAY [ 0.352s] Finished. Total time: 0.352s Target memory partitioning is done. Start flashing service... Partition name : fsbl1 Firmware path : "arm-trusted-firmware/tf-a-stm32mp157f-dk2-sdcard.stm32" Fastboot application path : /local/home/stm/Desktop/PRG-TOOLBOX-FB/Fastboot/Linux/Fastboot Fastboot command: /local/home/stm/Desktop/PRG-TOOLBOX-FB/Fastboot/Linux/Fastboot flash fsbl1 "arm-trusted-firmware/tf-a-stm32mp157f-dk2-sdcard.stm32" 2>&1 Sending 'fsbl1' (220 KB) OKAY [ 0.014s] Writing 'fsbl1' OKAY [ 0.019s] Finished. Total time: 0.066s Patition fsbl1 : Download Done . . . Partition name : userfs Firmware path : "st-image-userfs-openstlinux-weston-stm32mp1.ext4" Fastboot application path : /local/home/stm/Desktop/PRG-TOOLBOX-FB/Fastboot/Linux/Fastboot Fastboot command: /local/home/stm/Desktop/PRG-TOOLBOX- FB/Fastboot/Linux/Fastboot flash userfs "st-image-userfs-openstlinux-weston-stm32mp1.ext4" 2>&1 Sending sparse 'userfs' 1/2 (32380 KB) OKAY [ 1.894s] Writing 'userfs' OKAY [ 4.021s] Sending sparse 'userfs' 2/2 (11072 KB) OKAY [ 0.686s] Writing 'userfs' OKAY [ 6.195s] Finished. Total time: 13.265s Patition userfs : Download Done Flashing service finished. Time elapsed to flash all partitions: 1 min, 48 s, 003 ms
6. How to get PRG-TOOLBOX-FB
Refer to the following link to find PRG-TOOLBOX-FB GitHub repository.
7. FAQ
- Which partitions the tool updates?
The tool parses the TSV file containing the list of firmware paths and update all the mentioned partitions except for the boot partitions.
- Can I manage the OTP partition using PRG-TOOLBOX-FB?
No, it is not possible. Effectively, U-Boot does not currently expose the OTP partition in Fastboot mode.
- Is it possible to select the STM32 Fastboot device by its serial number?
The current version does not have the capability to select a Fastboot USB device by its serial number. Instead, the tool automatically selects the first Fastboot USB device that is plugged in. The feature, selecting a device by its serial number, is under construction and will be delivered in a future release.