1. Overview[edit | 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
- Compile: Qt® Creator pre-configured project or MakeFile
- 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 | edit source]
The next subsections present a few important points to keep in mind before preparing your development environment.
2.1. Hardware prerequisites[edit | edit source]
- Supported boards : all boards of STM32MP1 series, STM32MP25 series
- Supported target memory: SD™ card, eMMC
2.2. Software prerequisites[edit | edit source]
- Use the OpenSTLinux distribution software v5.0.3 release (minor version of ecosystem release v5.0.0
). Refer to OpenSTLinux distribution software v5.0.3 release article for more information. - An 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.
 Information
|
| To properly program the list of firmware, it is mandatory that the U-Boot is operating in Fastboot mode. Verify beforehand that the Fastboot mode is activated and properly configured. Refer to OSTL v5.0.3, How to configure U-Boot to support Fastboot mode and STM32_MPU_OpenSTLinux_release_note |
2.3. Linux host environment[edit | 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 | 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 | 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 get PRG-TOOLBOX-FB[edit | edit source]
Refer to the following link to find the PRG-TOOLBOX-FB GitHub repository.
5. How to build the PRG-TOOLBOX-FB project[edit | edit source]
The package provides a preconfigured Qt® project (see .pro file) and a standard makefile. 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 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®)
- 3- Makefile: build the project without the need to pass by the Qt® tools. Execute the "make" command (or "mingw32-make.exe" on Windows®).
If you intend to follow the second compile solution 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.
6. How to use PRG-TOOLBOX-FB[edit | 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.
6.1. Help[edit | edit source]
To show the help menu and the list of available commands:
Syntax: -?, -h, --help
6.2. Version[edit | edit source]
To display the version of the tool in format x.y.z [Major.Minor.Patch]:
Syntax: -v, --version
6.3. List Fastboot devices[edit | edit source]
To print the list of available Fastboot devices:
Syntax: -l, --list
6.4. Serial number[edit | edit source]
To select the USB device by serial number:
Syntax: -sn, --serial <serialNumber>
6.5. Download[edit | 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 (refer to STM32MP flashlayout).
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
7. FAQ[edit | 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 (refer to STM32MP flashlayout).
- 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.