DFU file format: DfuSe prefix and images

DfuSe is STMicroelectronics’ form of the DFU file, described in its user manual UM0391, DfuSe File Format Specification. A plain DFU file holds one block of bytes with no address. A DfuSe file can hold several images, one per USB alternate setting (for example the internal flash and the option bytes), and each image is split into elements that carry the memory address they are written to. The file is a prefix, the images, then the ordinary DFU suffix with bcdDFU set to 0x011A.

Overall layout

0DfuSe prefix: signature, version, size, number of images11 bytes
11image 1: Target prefix, then its elements274 + elements
…images 2 to bTargets, each laid out the same wayvaries
−16DFU suffix, with bcdDFU = 0x011A16 bytes

A DfuSe file.

All numbers are little-endian, as every DfuSe tool writes and reads them. UM0391 in places calls its buffers big-endian; that wording does not match the files ST’s own tools produce. Images and elements follow each other with no padding.

DfuSe prefix

Offset	Size	Name	Meaning
`0`	5	`szSignature`	The ASCII text `DfuSe` (`44 66 75 53 65`), with no terminating NUL.
`5`	1	`bVersion`	Format version, `0x01`.
`6`	4	`DFUImageSize`	Size of the file in bytes; see below.
`10`	1	`bTargets`	Number of images (Target sections) that follow, 1 to 255.

UM0391 describes DFUImageSize as the total DFU file length. ST’s own DFU File Manager, and the open-source tools that copy it (dfuse-pack, MicroPython’s dfu.py), write the length of the prefix and images only, that is the file length less the 16-byte suffix. A reader should accept either and rely on bTargets and the sizes inside each image instead.

Target prefix

Each image starts with a 274-byte Target prefix.

Offset	Size	Name	Meaning
`0`	6	`szSignature`	The ASCII text `Target` (`54 61 72 67 65 74`), no NUL.
`6`	1	`bAlternateSetting`	The USB alternate setting of the DFU interface this image is downloaded through. DfuSe devices list different memory units or address spaces (for example internal flash and option bytes) as separate alternate settings.
`7`	4	`bTargetNamed`	Non-zero (normally `1`) when `szTargetName` holds a name; zero when it is unused. Despite the `b` prefix it is four bytes.
`11`	255	`szTargetName`	The image’s name, ASCII, NUL-terminated and padded with zeros to 255 bytes (MicroPython’s tool writes `ST...`).
`266`	4	`dwTargetSize`	Size in bytes of the elements that follow, not counting this prefix.
`270`	4	`dwNbElements`	Number of elements in the image.

Image element

Each element is an 8-byte header and its data: one contiguous run of bytes to be written at one address.

Offset	Size	Name	Meaning
`0`	4	`dwElementAddress`	Address in the target’s memory where the first data byte goes.
`4`	4	`dwElementSize`	Number of data bytes.
`8`	`dwElementSize`	`Data`	The bytes to write.

So dwTargetSize is the sum of (8 + dwElementSize) over the image’s elements. A gap in the firmware (for example code at the start of flash and a configuration block near its end) becomes two elements, so the file does not carry the empty space in between.

Suffix

The last 16 bytes are the standard DFU suffix. DfuSe sets bcdDFU to 0x011A, which is how a reader tells a DfuSe file from a plain one before looking for the DfuSe signature. The CRC covers the prefix, every image and the first 12 bytes of the suffix, and is calculated as in plain DFU (CRC-32 without the final inversion).

How a tool sends it

For each image the host selects the image’s alternate setting. For each element it uses DfuSe’s special commands, which plain DFU lacks: a “set address” command that points the device at dwElementAddress and an “erase page” command, before sending the data with DFU_DNLOAD. These commands belong to ST’s DfuSe protocol, not to the file format; their byte values are not given here because no source read for this page lists them.

Worked example

A file with one image (alternate setting 0, named ST...) holding one element: four bytes DE AD BE EF at 0x08000000. The prefix and image take 11 + 274 + 8 + 4 = 297 bytes (0x129), and the file is 313 bytes with its suffix.

Offset  Bytes                                  Field
0       44 66 75 53 65                         szSignature "DfuSe"
5       01                                     bVersion 1
6       29 01 00 00                            DFUImageSize 297 (without the suffix)
10      01                                     bTargets 1

11      54 61 72 67 65 74                      szSignature "Target"
17      00                                     bAlternateSetting 0
18      01 00 00 00                            bTargetNamed 1
22      53 54 2E 2E 2E 00 … 00                 szTargetName "ST..." padded to 255
277     0C 00 00 00                            dwTargetSize 12 (8 + 4)
281     01 00 00 00                            dwNbElements 1

285     00 00 00 08                            dwElementAddress 0x08000000
289     04 00 00 00                            dwElementSize 4
293     DE AD BE EF                            Data

297     00 00 CD AB 34 12 1A 01 55 46 44 10    suffix: bcdDevice 0, PID 0xABCD,
                                               VID 0x1234 (made up), bcdDFU 0x011A, "UFD", 16
309     xx xx xx xx                            dwCRC

A complete DfuSe file with one image and one element, laid out as MicroPython’s dfu.py writes it.

Sources

UM0391, DfuSe File Format Specification – STMicroelectronics’ user manual; the ST PDF could not be fetched, so its wording on DFUImageSize, the field names and the endianness remark come from quotations in search results and the ST community forum
tools/dfu.py – MicroPython’s DfuSe reader and writer (after Antonio Galea’s dfuse-pack): the exact struct layouts, field sizes and byte order used on this page
Using dfu-util with DfuSe devices – dfu-util’s notes on alternate settings, the special commands and DfuSe files

.DFU File Format – DfuSe prefix and images