1. Overview[edit source]
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 for writing into external flash memory (such as eMMC or SDMMC).
Fastboot (FB) is a protocol originally created for Android™. It is primarily used to modify the flash memory file system 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
- Copyright: STMicroelectronics
- License: Apache v2.0
The functional chart of the tool, describing all involved components, is available below:
2. Prerequisites[edit source]
The tool is available in console mode. The next subsections present a few important points to keep in mind before preparing your development environment.
2.1. Hardware prerequisites[edit source]
- Make sure that the STM32 MPU device used is supported by the tool.
2.2. Software prerequisites[edit source]
- Use the OpenSTLinux distribution software v5.0.3 release (or later). 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 an OTP partition.
- U-Boot in Fastboot mode is running on the target, refer to How to configure U-Boot to support Fastboot mode.
2.3. Linux host environment[edit source]
To ensure that PRG-TOOLBOX-FB has read and write access to the USB Fastboot devices running by the STM32 MPU device, you must 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[edit source]
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.
Once the installation is complete, the STM32 Fastboot Device is identified as the Fastboot stack running on the STM32 MPU device. This device is then ready to provide the programming service through the Fastboot interface.
3. License[edit source]
PRG-TOOLBOX-FB is released under the Apache v2.0 .
A copy of the GNU General Public License version 2 is delivered with the source code of the tool.
4. How to build the PRG-TOOLBOX-FB project[edit source]
The package provides a preconfigured Qt® project (see ".pro" file). There are three ways to compile the project:
- Qt® Creator IDE: Open the project in the IDE, configure your kit compiler, and run the build.
- Qmake: It is possible to compile the project in the command line without using the 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®)
- Makefile: First create your own Makefile to be able to build the project without the need to install Qt® Creator. Then execute the "make" command.
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 C++ compiler is already installed on your machine or install it if it is not the case.
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 must install Qt® Creator on your machine.
5. Command usage[edit source]
The tools includes a set of command lines that enable users to easily program and manage their 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 exit follows 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[edit source]
To show the help menu:
Syntax: -?, -h, --help
5.2. Version[edit source]
To display the version of the tool in format x.y.z [Major.Minor.Patch]:
Syntax: -v, --version
5.3. Download[edit source]
To 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 program the list of partitions. At the end of the programming 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[edit source]
Refer to the following link to find the PRG-TOOLBOX-FB GitHub repository.
7. FAQ[edit source]
- Which partitions does the tool update?
The tool parses the TSV file containing the list of firmware paths and updates 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.