Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | |
| 3 | Device Firmware Upgrade (DFU) |
| 4 | ============================= |
| 5 | |
| 6 | Overview |
| 7 | -------- |
| 8 | |
| 9 | The Device Firmware Upgrade (DFU) allows to download and upload firmware |
| 10 | to/from U-Boot connected over USB. |
| 11 | |
Michal Simek | 50fa118 | 2023-05-17 09:17:16 +0200 | [diff] [blame] | 12 | U-Boot follows the Universal Serial Bus Device Class Specification for |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 13 | Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org). |
| 14 | |
| 15 | U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu |
| 16 | (cmd/dfu.c / CONFIG_CMD_DFU) based on: |
| 17 | |
| 18 | - the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the |
| 19 | USB DFU download gadget (drivers/usb/gadget/f_dfu.c) |
| 20 | - The access to mediums is done in DFU backends (driver/dfu) |
| 21 | |
| 22 | Today the supported DFU backends are: |
| 23 | |
| 24 | - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT) |
| 25 | - NAND |
| 26 | - RAM |
| 27 | - SF (serial flash) |
| 28 | - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...) |
| 29 | - virtual |
| 30 | |
| 31 | These DFU backends are also used by |
| 32 | |
| 33 | - the dfutftp (see README.dfutftp) |
| 34 | - the thordown command (cmd/thordown.c and gadget/f_thor.c) |
| 35 | |
| 36 | The "virtual" backend is a generic DFU backend to support a board specific |
| 37 | target (for example OTP), only based on the weak functions: |
| 38 | |
| 39 | - dfu_write_medium_virt |
| 40 | - dfu_get_medium_size_virt |
| 41 | - dfu_read_medium_virt |
| 42 | |
| 43 | Configuration Options |
| 44 | --------------------- |
| 45 | |
| 46 | The following configuration option are relevant for device firmware upgrade: |
| 47 | |
| 48 | * CONFIG_DFU |
| 49 | * CONFIG_DFU_OVER_USB |
| 50 | * CONFIG_DFU_MMC |
| 51 | * CONFIG_DFU_MTD |
| 52 | * CONFIG_DFU_NAND |
| 53 | * CONFIG_DFU_RAM |
| 54 | * CONFIG_DFU_SF |
| 55 | * CONFIG_DFU_SF_PART |
| 56 | * CONFIG_DFU_TIMEOUT |
| 57 | * CONFIG_DFU_VIRTUAL |
| 58 | * CONFIG_CMD_DFU |
| 59 | |
| 60 | Environment variables |
| 61 | --------------------- |
| 62 | |
| 63 | The dfu command uses 3 environments variables: |
| 64 | |
| 65 | dfu_alt_info |
| 66 | The DFU setting for the USB download gadget with a semicolon separated |
| 67 | string of information on each alternate:: |
| 68 | |
| 69 | dfu_alt_info="<alt1>;<alt2>;....;<altN>" |
| 70 | |
| 71 | When several devices are used, the format is: |
| 72 | |
| 73 | - <interface> <dev>'='alternate list (';' separated) |
| 74 | - each interface is separated by '&':: |
| 75 | |
| 76 | dfu_alt_info=\ |
| 77 | "<interface1> <dev1>=<alt1>;....;<altN>&"\ |
| 78 | "<interface2> <dev2>=<altN+1>;....;<altM>&"\ |
| 79 | ...\ |
| 80 | "<interfaceI> <devI>=<altY+1>;....;<altZ>&" |
| 81 | |
| 82 | dfu_bufsiz |
| 83 | size of the DFU buffer, when absent, defaults to |
| 84 | CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default) |
| 85 | |
| 86 | dfu_hash_algo |
| 87 | name of the hash algorithm to use |
| 88 | |
| 89 | Commands |
| 90 | -------- |
| 91 | |
| 92 | dfu <USB_controller> [<interface> <dev>] list |
| 93 | list the alternate device defined in *dfu_alt_info* |
| 94 | |
| 95 | dfu <USB_controller> [<interface> <dev>] [<timeout>] |
| 96 | start the dfu stack on the USB instance with the selected medium |
| 97 | backend and use the *dfu_alt_info* variable to configure the |
| 98 | alternate setting and link each one with the medium |
| 99 | The dfu command continue until receive a ^C in console or |
| 100 | a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option |
| 101 | is enabled and <timeout> parameter is present in the command line, |
| 102 | the DFU operation will be aborted automatically after <timeout> |
| 103 | seconds of waiting remote to initiate DFU session. |
| 104 | |
| 105 | The possible values of <interface> are (with <USB controller> = 0 in the dfu |
| 106 | command example) |
| 107 | |
| 108 | mmc |
| 109 | for eMMC and SD card:: |
| 110 | |
| 111 | dfu 0 mmc <dev> |
| 112 | |
| 113 | each element in *dfu_alt_info* being |
| 114 | |
| 115 | * <name> raw <offset> <size> [mmcpart <num>] raw access to mmc device |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 116 | * <name> part <dev> <part_id> [offset <byte>] raw access to partition |
| 117 | * <name> fat <dev> <part_id> file in FAT partition |
| 118 | * <name> ext4 <dev> <part_id> file in EXT4 partition |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 119 | * <name> skip 0 0 ignore flashed data |
| 120 | * <name> script 0 0 execute commands in shell |
| 121 | |
| 122 | with |
| 123 | |
Marek Vasut | 3ed7faf | 2023-10-29 23:37:22 +0100 | [diff] [blame] | 124 | offset |
| 125 | is the offset in the device (hexadecimal without "0x") |
| 126 | size |
| 127 | is the size of the access area (hexadecimal without "0x") |
| 128 | or 0 which means whole device |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 129 | partid |
| 130 | being the GPT or DOS partition index, |
| 131 | num |
| 132 | being the eMMC hardware partition number. |
| 133 | |
| 134 | A value of environment variable *dfu_alt_info* for eMMC could be:: |
| 135 | |
| 136 | u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1 |
| 137 | |
| 138 | A value of environment variable *dfu_alt_info* for SD card could be:: |
| 139 | |
| 140 | u-boot raw 0x80 0x800;uImage ext4 0 2 |
| 141 | |
| 142 | If don't want to flash given image file to storage, use "skip" type |
| 143 | entity. |
| 144 | |
| 145 | - It can be used to protect flashing wrong image for the specific board. |
| 146 | - Especailly, this layout will be useful when thor protocol is used, |
| 147 | which performs flashing in batch mode, where more than one file is |
| 148 | processed. |
| 149 | |
| 150 | For example, if one makes a single tar file with support for the two |
| 151 | boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one |
| 152 | can use it to flash a proper u-boot image on both without a failure:: |
| 153 | |
| 154 | u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0 |
| 155 | |
| 156 | When flashing new system image requires do some more complex things |
| 157 | than just writing data to the storage medium, one can use 'script' |
| 158 | type. Data written to such entity will be executed as a command list |
| 159 | in the u-boot's shell. This for example allows to re-create partition |
| 160 | layout and even set new *dfu_alt_info* for the newly created paritions. |
| 161 | Such script would look like:: |
| 162 | |
| 163 | setenv dfu_alt_info ... |
| 164 | setenv mbr_parts ... |
| 165 | mbr write ... |
| 166 | |
| 167 | Please note that this means that user will be able to execute any |
| 168 | arbitrary commands just like in the u-boot's shell. |
| 169 | |
| 170 | nand |
| 171 | raw slc nand device:: |
| 172 | |
| 173 | dfu 0 nand <dev> |
| 174 | |
| 175 | each element in *dfu_alt_info* being either of |
| 176 | |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 177 | * <name> raw <offset> <size> raw access to nand device |
| 178 | * <name> part <dev_id> <part_id> raw access to partition |
| 179 | * <name> partubi <dev_id> <part_id> raw access to ubi partition |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 180 | |
| 181 | with |
| 182 | |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 183 | offset |
| 184 | is the offset in the nand device (hexadecimal without "0x") |
| 185 | size |
| 186 | is the size of the access area (hexadecimal without "0x") |
| 187 | dev_id |
| 188 | is the NAND device index (decimal only) |
| 189 | part_id |
| 190 | is the NAND partition index (decimal only) |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 191 | |
| 192 | ram |
| 193 | raw access to ram:: |
| 194 | |
| 195 | dfu 0 ram <dev> |
| 196 | |
| 197 | dev |
| 198 | is not used for RAM target |
| 199 | |
| 200 | each element in *dfu_alt_info* being:: |
| 201 | |
| 202 | <name> ram <offset> <size> raw access to ram |
| 203 | |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 204 | with |
| 205 | |
| 206 | offset |
| 207 | is the offset in the ram device (hexadecimal without "0x") |
| 208 | size |
| 209 | is the size of the access area (hexadecimal without "0x") |
| 210 | |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 211 | sf |
| 212 | serial flash : NOR:: |
| 213 | |
| 214 | cmd: dfu 0 sf <dev> |
| 215 | |
| 216 | each element in *dfu_alt_info* being either of: |
| 217 | |
| 218 | * <name> raw <offset> <size> raw access to sf device |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 219 | * <name> part <dev_id> <part_id> raw acces to partition |
| 220 | * <name> partubi <dev_id> <part_id> raw acces to ubi partition |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 221 | |
| 222 | with |
| 223 | |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 224 | offset |
| 225 | is the offset in the sf device (hexadecimal without "0x") |
| 226 | size |
| 227 | is the size of the access area (hexadecimal without "0x") |
| 228 | dev_id |
| 229 | is the sf device index (the device is "nor<dev_id>") (deximal only) |
| 230 | part_id |
| 231 | is the MTD partition index (decimal only) |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 232 | |
| 233 | mtd |
| 234 | all MTD device: NAND, SPI-NOR, SPI-NAND,...:: |
| 235 | |
| 236 | cmd: dfu 0 mtd <dev> |
| 237 | |
| 238 | with |
| 239 | |
| 240 | dev |
| 241 | the mtd identifier as defined in mtd command |
| 242 | (nand0, nor0, spi-nand0,...) |
| 243 | |
| 244 | each element in *dfu_alt_info* being either of: |
| 245 | |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 246 | * <name> raw <offset> <size> for raw access to mtd device |
| 247 | * <name> part <part_id> for raw access to partition |
| 248 | * <name> partubi <part_id> for raw access to ubi partition |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 249 | |
| 250 | with |
| 251 | |
Masami Hiramatsu | d2760f3 | 2022-01-31 11:52:46 +0900 | [diff] [blame] | 252 | offset |
| 253 | is the offset in the mtd device (hexadecimal without "0x") |
| 254 | size |
| 255 | is the size of the access area (hexadecimal without "0x") |
| 256 | part_id |
| 257 | is the MTD partition index (decimal only) |
Heinrich Schuchardt | 22a5074 | 2021-03-05 12:58:37 +0100 | [diff] [blame] | 258 | |
| 259 | virt |
| 260 | virtual flash back end for DFU |
| 261 | |
| 262 | :: |
| 263 | |
| 264 | cmd: dfu 0 virt <dev> |
| 265 | |
| 266 | each element in *dfu_alt_info* being: |
| 267 | |
| 268 | * <name> |
| 269 | |
| 270 | <interface> and <dev> are absent, the dfu command to use multiple devices:: |
| 271 | |
| 272 | cmd: dfu 0 list |
| 273 | cmd: dfu 0 |
| 274 | |
| 275 | *dfu_alt_info* variable provides the list of <interface> <dev> with |
| 276 | alternate list separated by '&' with the same format for each <alt>:: |
| 277 | |
| 278 | mmc <dev>=<alt1>;....;<altN> |
| 279 | nand <dev>=<alt1>;....;<altN> |
| 280 | ram <dev>=<alt1>;....;<altN> |
| 281 | sf <dev>=<alt1>;....;<altN> |
| 282 | mtd <dev>=<alt1>;....;<altN> |
| 283 | virt <dev>=<alt1>;....;<altN> |
| 284 | |
| 285 | Callbacks |
| 286 | --------- |
| 287 | |
| 288 | The weak callback functions can be implemented to manage specific behavior |
| 289 | |
| 290 | dfu_initiated_callback |
| 291 | called when the DFU transaction is started, used to initiase the device |
| 292 | |
| 293 | dfu_flush_callback |
| 294 | called at the end of the DFU write after DFU manifestation, used to manage |
| 295 | the device when DFU transaction is closed |
| 296 | |
| 297 | Host tools |
| 298 | ---------- |
| 299 | |
| 300 | When U-Boot runs the dfu stack, the DFU host tools can be used |
| 301 | to send/receive firmwares on each configurated alternate. |
| 302 | |
| 303 | For example dfu-util is a host side implementation of the DFU 1.1 |
| 304 | specifications(http://dfu-util.sourceforge.net/) which works with U-Boot. |
| 305 | |
| 306 | Usage |
| 307 | ----- |
| 308 | |
| 309 | Example 1: firmware located in eMMC or SD card, with: |
| 310 | |
| 311 | - alternate 1 (alt=1) for SPL partition (GPT partition 1) |
| 312 | - alternate 2 (alt=2) for U-Boot partition (GPT partition 2) |
| 313 | |
| 314 | The U-Boot configuration is:: |
| 315 | |
| 316 | U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2" |
| 317 | |
| 318 | U-Boot> dfu 0 mmc 0 list |
| 319 | DFU alt settings list: |
| 320 | dev: eMMC alt: 0 name: spl layout: RAW_ADDR |
| 321 | dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR |
| 322 | |
| 323 | Boot> dfu 0 mmc 0 |
| 324 | |
| 325 | On the Host side: |
| 326 | |
| 327 | list the available alternate setting:: |
| 328 | |
| 329 | $> dfu-util -l |
| 330 | dfu-util 0.9 |
| 331 | |
| 332 | Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. |
| 333 | Copyright 2010-2016 Tormod Volden and Stefan Schmidt |
| 334 | This program is Free Software and has ABSOLUTELY NO WARRANTY |
| 335 | Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ |
| 336 | |
| 337 | Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ |
| 338 | alt=1, name="u-boot", serial="003A00203438510D36383238" |
| 339 | Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ |
| 340 | alt=0, name="spl", serial="003A00203438510D36383238" |
| 341 | |
| 342 | To download to U-Boot, use -D option |
| 343 | |
| 344 | $> dfu-util -a 0 -D u-boot-spl.bin |
| 345 | $> dfu-util -a 1 -D u-boot.bin |
| 346 | |
| 347 | To upload from U-Boot, use -U option |
| 348 | |
| 349 | $> dfu-util -a 0 -U u-boot-spl.bin |
| 350 | $> dfu-util -a 1 -U u-boot.bin |
| 351 | |
| 352 | To request a DFU detach and reset the USB connection: |
| 353 | $> dfu-util -a 0 -e -R |
| 354 | |
| 355 | |
| 356 | Example 2: firmware located in NOR (sf) and NAND, with: |
| 357 | |
| 358 | - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1) |
| 359 | - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2) |
| 360 | - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3) |
| 361 | - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1) |
| 362 | |
| 363 | :: |
| 364 | |
| 365 | U-Boot> env set dfu_alt_info \ |
| 366 | "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \ |
| 367 | u-boot-env part 0 3&nand 0=UBI partubi 0,1" |
| 368 | |
| 369 | U-Boot> dfu 0 list |
| 370 | |
| 371 | DFU alt settings list: |
| 372 | dev: SF alt: 0 name: spl layout: RAW_ADDR |
| 373 | dev: SF alt: 1 name: ssbl layout: RAW_ADDR |
| 374 | dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR |
| 375 | dev: NAND alt: 3 name: UBI layout: RAW_ADDR |
| 376 | |
| 377 | U-Boot> dfu 0 |
| 378 | |
| 379 | :: |
| 380 | |
| 381 | $> dfu-util -l |
| 382 | Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ |
| 383 | intf=0, alt=3, name="UBI", serial="002700333338511934383330" |
| 384 | Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ |
| 385 | intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330" |
| 386 | Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ |
| 387 | intf=0, alt=1, name="u-boot", serial="002700333338511934383330" |
| 388 | Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ |
| 389 | intf=0, alt=0, name="spl", serial="002700333338511934383330" |
| 390 | |
| 391 | Same example with MTD backend |
| 392 | |
| 393 | :: |
| 394 | |
| 395 | U-Boot> env set dfu_alt_info \ |
| 396 | "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\ |
| 397 | "mtd nand0=UBI partubi 1" |
| 398 | |
| 399 | U-Boot> dfu 0 list |
| 400 | using id 'nor0,0' |
| 401 | using id 'nor0,1' |
| 402 | using id 'nor0,2' |
| 403 | using id 'nand0,0' |
| 404 | DFU alt settings list: |
| 405 | dev: MTD alt: 0 name: spl layout: RAW_ADDR |
| 406 | dev: MTD alt: 1 name: u-boot layout: RAW_ADDR |
| 407 | dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR |
| 408 | dev: MTD alt: 3 name: UBI layout: RAW_ADDR |
| 409 | |
| 410 | Example 3 |
| 411 | |
| 412 | firmware located in SD Card (mmc) and virtual partition on OTP and PMIC not |
| 413 | volatile memory |
| 414 | |
| 415 | - alternate 1 (alt=1) for scard |
| 416 | - alternate 2 (alt=2) for OTP (virtual) |
| 417 | - alternate 3 (alt=3) for PMIC NVM (virtual) |
| 418 | |
| 419 | :: |
| 420 | |
| 421 | U-Boot> env set dfu_alt_info \ |
| 422 | "mmc 0=sdcard raw 0 0x100000&"\ |
| 423 | "virt 0=otp" \ |
| 424 | "virt 1=pmic" |
| 425 | |
| 426 | :: |
| 427 | |
| 428 | U-Boot> dfu 0 list |
| 429 | DFU alt settings list: |
| 430 | dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR |
| 431 | dev: VIRT alt: 1 name: otp layout: RAW_ADDR |
| 432 | dev: VIRT alt: 2 name: pmic layout: RAW_ADDR |