- Last edited 3 weeks ago ago
PRG-TOOLBOX-DFU
Contents
1 Overview[edit]
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 Fastboot mode, without requiring any manual hardware setting. It is based on 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 whose characteristics are the following:
- Language: Native C++ 11
- IDE: Qt® Creator
- Cross-platform: Windows, Linux®
- Dependency: dfu-util
- Copyrights: STMicroelectronics
- License": GPL v2.0
The functional chart of the tool, describing all involved components, is available below:
2 Prerequisites[edit]
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[edit]
- Check the boot pins to establish connection in DFU mode (Refer to "Boot related switches" sections of hardware description articles for STM32MP1 series' boards
) - Make sure that the used STM32 MPU device is supported by the tool.
2.2 Software prerequisites[edit]
- Use the OpenSTLinux distribution software v5.0.3 release (or later), refer to OpenSTLinux distribution software v5.0.3 release.
- Make sure to use firmware binaries that correspond to the specific board you are using, otherwise an error occurs.
- 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).
- Note that OTP management is only possible when U-Boot is running in DFU mode. Once Fastboot mode is active, OTP management is no longer possible.
- It is possible to manage the OTP memory using STM32PRGFW-UTIL
- STM32PRGFW-UTIL is not intended for activating Fastboot mode.
2.3 Linux host environment[edit]
To ensure that PRG-TOOLBOX-DFU has read and write access to the USB DFU devices, exposed 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-DFU/rules
sudo cp *.* /etc/udev/rules.d
2.4 dfu-util[edit]
PRG-TOOLBOX-DFU includes the "dfu-util" program in the project tree for Windows platforms only.
For Linux® machines, the tool uses the dfu-util program, that should be already installed on the system. If it is not the case, you need to 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]
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 tool's source code.
4 How to build the PRG-TOOLBOX-DFU project[edit]
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-DFU.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[edit]
The tool includes a set of command lines that enable users to easily configure and manage the STM32 MPU devices.
If an error occurs during the execution of an 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[edit]
Show the help menu
Syntax: -?, -h, --help
5.2 Version[edit]
Display the tool’s version in format x.y.z [Major.Minor.Patch]
Syntax: -v, --version
5.3 Download[edit]
Download 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.
- <fastboot=0/1> : Optional flag, if it equals to 1, the tool initiates the flashing process and launch Fastboot. If the argument is equal to 0, the tool initiates the flashing process, but Fastboot is not be launched, and the device remains in DFU mode (case to manage the OTP partition in 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 flash boot partitions and to establish the Fastboot mode. At the end of the flashing 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
5.4 OTP[edit]
Read and write 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 in order to manage the OTP memory, an OTP partition must be exposed in DFU mode. If this partition is not available, the command ill absolutely fails.
The tool can program the STM32PRGFW-UTIL and handle the OTP partition without activating 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 !
Please refer to this wiki page to obtain all the necessary information regarding the write operation and specifications of the fuse: 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 How to get PRG-TOOLBOX-DFU[edit]
Refer to the following link to find PRG-TOOLBOX-DFU GitHub repository.
7 FAQ[edit]
- What are the supported STM32 MPU products?
It is a generic code for all STM32 MPU devices, but you need to use the corresponding binaries. Please take into consideration that the boot sequence to install U-Boot may be different from one STM32 MPU series to another. (refer to Install U-Boot).
- Can I manage the OTP partition using U-Boot?
Yes, it is possible in the case that U-Boot implements the management of the OTP partition.
- Is it possible to select the STM32 DFU device by its serial number?
The current version does not have the capability to select a USB device by its serial number. Instead, the tool automatically selects the first STM32 USB device that is plugged in and has a Product ID of 0x483 and a Vendor ID of 0xDF11. (plan to include the feature of selecting a device by its serial number in a future release)