Last edited one month ago

PRG-TOOLBOX-DFU

Applicable for STM32MP13x lines, STM32MP15x lines


1. Overview[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 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:

Toolbox-dfu-overview.jpg


2. Prerequisites[edit source]

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 source]

  • Check the boot pins to establish connection in DFU mode (Refer to "Boot related switches" sections of hardware description articles for STM32MP1 series' boards More info green.png)
  • Make sure that the used STM32 MPU device 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.
  • 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 source]

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 source]

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 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 tool's source code.

4. How to build the PRG-TOOLBOX-DFU project[edit source]

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 source]

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 source]

Show the help menu

Syntax: -?, -h, --help

5.2. Version[edit source]

Display the tool’s version in format x.y.z [Major.Minor.Patch]

Syntax: -v, --version

5.3. Download[edit source]

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 More info green.png:

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 source]

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.

Info white.png Information
In order 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 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 source]

Refer to the following link to find PRG-TOOLBOX-DFU GitHub repository.

7. FAQ[edit source]

  • 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)