1. Overview[edit | edit source]
PRG-TOOLBOX-DFU is an open-source tool provided by STMicroelectronics. This tool automates the preparation of STM32 MPU devices through the USB DFU protocol, with the purpose to fuse OTP memory, and to run U-Boot in Fastboot mode.
The tool achieves the startup of the Fastboot mode without requiring any manual hardware setting. It is based on the U-Boot script.
The tool is a wrapper of dfu-util. It is specifically designed for STM32 MPU devices.
PRG-TOOLBOX-DFU provides a source application with the following characteristics:
- Language: Native C++ 11
- Compile: Qt® Creator pre-configured project or MakeFile
- Cross-platform: Windows®, Linux®
- Dependency: dfu-util
- Copyright: STMicroelectronics
- License: GPL v2.0
- More details about supported STM32MPU devices, supported target memory types and features are available in PRG-TOOLBOX-DFU Release Note.
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]
- Check the boot pins to establish a connection in DFU mode (Refer to "Boot related switches" sections of hardware description articles (available here) for the used STM32 MPU boards
- Make sure that the STM32 MPU device used is supported by the tool (for that check the "Applicable for" field , on the top of article)
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.
You can also use any ecosystem release ≥ v5.1.0 in such case refer to STM32_MPU_OpenSTLinux_release_note_-_v5.1.0. - Activate U-Boot compiled with Fastboot. Refer to How to configure U-Boot to support Fastboot mode.
- Prepare a TSV flashlayout file describing the partitions and the memory map (refer to STM32CubeProgrammer flashlayout).
 Information
|
|
2.3. Linux host environment[edit | edit source]
To ensure that PRG-TOOLBOX-DFU has read and write access to the USB DFU devices exposed 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-DFU/rules
sudo cp *.* /etc/udev/rules.d
2.4. dfu-util[edit | edit source]
For Windows® host, the PRG-TOOLBOX-DFU includes the "dfu-util" program in the project tree.
For Linux® machines, the tool uses the dfu-util program already installed on the system. Install "dfu-util" yourself if it is not already installed on your system (refer to https://dfu-util.sourceforge.net).
sudo apt-get install dfu-util
At the start of execution, PRG-TOOLBOX-DFU checks whether" dfu-util" is installed and can be run.
If there is an issue with the execution of "dfu-util", an error message is displayed (refer to source file Src/DFU.cpp):
dfu-util is not installed or cannot be found. Please install it and try again.
3. License[edit | edit source]
PRG-TOOLBOX-DFU is released under the GNU General Public License version 2.
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-DFU[edit | edit source]
Refer to the following link to find the PRG-TOOLBOX-DFU GitHub repository.
5. How to build the PRG-TOOLBOX-DFU 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-DFU.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-DFU[edit | edit source]
The tool includes a set of command lines that enable users to easily configure and manage their STM32 MPU devices.
If an error occurs during the execution of an 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 STM32 DFU devices[edit | edit source]
To print the list of available STM32 DFU 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. U-Boot Installing[edit | edit source]
To download/install the boot partitions and prepare the device to switch to Fastboot mode:
Syntax: -d, --download <filePath.tsv> <fastboot=0/1>
- <filePath.tsv>: Indicates the TSV file path describing the flash memory layout (refer to STM32MP flashlayout).
- <fastboot=0/1>: Optional flag. If it is equal to 1, the tool initiates the programming process and launches Fastboot. If the argument is equal to 0, the tool initiates the programming process, but Fastboot is not be launched, and the device remains in DFU mode (this is the case to manage the OTP partition in the next step). If this option is not specified, the tool operates with fastboot=1 by default.
Example for STM32MP157F-EV1 Evaluation board :
PRG-TOOLBOX-DFU -d FlashLayout_emmc_stm32mp157f-ev1-fastboot.tsv fastboot=1
The tool makes several checks and follows a specific sequence to program the boot partitions and to establish the Fastboot mode. At the end of the programming process, the tool displays the total elapsed time in the following format: [x] minutes, [y] seconds, [z] milliseconds.
- Start U-Boot in Fastboot mode
PRG-TOOLBOX-DFU -d FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv
[Output example] ----------------------------------------- TSV DFU downloading... TSV path : FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv Partitions number : 2 U-Boot script size : 106 Bytes Start Fastboot : Yes Boot Application : U-Boot ----------------------------------------- [Info]: No U-Boot in Fastboot mode is running ! can't get debug descriptor: No such file or directory STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l [Info]: U-Boot in DFU mode is not running ! Partition index : 1 Firmware path : mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -a 1 -D mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 Warning: Invalid DFU suffix signature A valid DFU suffix will be required in a future dfu-util release OUTPUT: dfu-util 0.11 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright 2010-2021 Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #1 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 1024 Copying data from PC to DFU device Download [=========================] 100% 226117 bytes Download done. DFU state(7) = dfuMANIFEST, status(0) = No error condition is present DFU state(2) = dfuIDLE, status(0) = No error condition is present Done! Phase ID 1 : Download Done . . . Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #0 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 4096 Detach Done U-Boot in Fastboot mode is running ! Time elapsed to start fastboot: 00:14:513!
- Start U-Boot in DFU mode
PRG-TOOLBOX-DFU -d FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv fastboot=0
----------------------------------------- TSV DFU downloading... TSV path : FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv Partitions number : 2 U-Boot script size : 106 Bytes Start Fastboot : No Boot Application : U-Boot ----------------------------------------- [Info]: No U-Boot in Fastboot mode is running ! can't get debug descriptor: No such file or directory STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l [Info]: U-Boot in DFU mode is not running ! Partition index : 1 Firmware path : mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -a 1 -D mp15-dk2-otp/tf-a-stm32mp157c-dk2-usb.stm32 Warning: Invalid DFU suffix signature A valid DFU suffix will be required in a future dfu-util release OUTPUT: dfu-util 0.11 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright 2010-2021 Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #1 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 1024 Copying data from PC to DFU device Download [=========================] 100% 226117 bytes Download done. DFU state(7) = dfuMANIFEST, status(0) = No error condition is present DFU state(2) = dfuIDLE, status(0) = No error condition is present Done! Phase ID 1 : Download Done . . . Opening DFU capable USB device... Device ID 0483:df11 Device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Interface #0 ... Determining device status... DFU state(2) = dfuIDLE, status(0) = No error condition is present DFU mode device DFU version 0110 Device returned transfer size 1024 Detach Done DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l U-Boot in DFU mode is running ! Time elapsed to launch U-Boot in DFU mode: 00:12:296
6.6. OTP[edit | edit source]
Read and write from and to the OTP partition.
Syntax: -otp, --otp <operationType> <filePath.bin>
- <operationType>: read/write
- <filePath.bin>: Indicates the binary file path including the OTP contents (input binary for write operation and output binary for read operation).
Note that to manage the OTP memory, an OTP partition must be exposed in DFU mode. If this partition is not available, the command fails.
| Information
|
| To properly manage the OTP partition, it is essential that the embedded application being used is capable of exposing the OTP partition [0xF2] and supporting fuse operations. |
The tool can program the STM32PRGFW-UTIL and handle the OTP partition without activating the Fastboot mode “fastboot=0” (-d FlashLayout_STM32PRGFW_UTIL.tsv fastboot=0 -otp read otp_memory_mp15.bin).
PRG-TOOLBOX-DFU -otp read otp_read_mp15_dk.bin [Output example] ----------------------------------------- DFU reading... OTP partition : 0xF2 Output file path : otp_read_mp15_dk.bin ----------------------------------------- STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l OTP partition name="@OTP/0xf2/1*776Be" U-Boot in DFU mode is running ! DFU-UTIL command: dfu-util.exe -d 0483:df11 -a "@OTP/0xf2/1*776Be" -U otp_read_mp15_dk.bin Read OTP partition is done successfully !
To obtain all the necessary information regarding the write operation and specifications of the fuse, refer to this wiki page : STM32CubeProgrammer OTP management.
PRG-TOOLBOX-DFU -otp write otp_mp15_dk.bin ----------------------------------------- DFU downloading... OTP partition : 0xF2 Input file path : otp_mp15_dk.bin ----------------------------------------- STM32 device ID = 0x500 DFU-UTIL command: dfu-util\Windows\dfu-util.exe -d 483:df11 -l OTP partition name="@OTP/0xf2/1*776Be" U-Boot in DFU mode is running ! DFU-UTIL command: dfu-util.exe -d 0483:df11 -a "@OTP/0xf2/1*776Be" -D otp_mp15_dk.bin Warning: Invalid DFU suffix signature A valid DFU suffix will be required in a future dfu-util release Write OTP partition is done successfully !
6.7. DFU flashing[edit | edit source]
To prepare the device, launch U-Boot in DFU mode, and flash the list of partitions through DFU interface
Syntax: -f, --flash <filePath.tsv>
- <filePath.tsv>: Indicates the TSV file path describing the flash memory layout (refer to STM32MP flashlayout).
7. FAQ[edit | edit source]
- Does the U-Boot manage the OTP partition ?
The U-Boot delivered with OpenSTLinux distribution software v5.0.3 release (or later) does not designed to manage by default the OTP partition, so you need to add this functionality by yourself. Refer to OpenSTLinux distribution software v5.0.3 release
The STM32PRGFW-UTIL is the recommended application to install and to manage the OTP fuses.