1.. SPDX-License-Identifier: GPL-2.0+ 2 3Device Firmware Upgrade (DFU) 4============================= 5 6Overview 7-------- 8 9The Device Firmware Upgrade (DFU) allows to download and upload firmware 10to/from U-Boot connected over USB. 11 12U-boot follows the Universal Serial Bus Device Class Specification for 13Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org). 14 15U-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 22Today 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 31These 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 36The "virtual" backend is a generic DFU backend to support a board specific 37target (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 43Configuration Options 44--------------------- 45 46The 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 60Environment variables 61--------------------- 62 63The dfu command uses 3 environments variables: 64 65dfu_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 82dfu_bufsiz 83 size of the DFU buffer, when absent, defaults to 84 CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default) 85 86dfu_hash_algo 87 name of the hash algorithm to use 88 89Commands 90-------- 91 92dfu <USB_controller> [<interface> <dev>] list 93 list the alternate device defined in *dfu_alt_info* 94 95dfu <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 105The possible values of <interface> are (with <USB controller> = 0 in the dfu 106command example) 107 108mmc 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 116 * <name> part <dev> <part_id> [mmcpart <num>] raw access to partition 117 * <name> fat <dev> <part_id> [mmcpart <num>] file in FAT partition 118 * <name> ext4 <dev> <part_id> [mmcpart <num>] file in EXT4 partition 119 * <name> skip 0 0 ignore flashed data 120 * <name> script 0 0 execute commands in shell 121 122 with 123 124 partid 125 being the GPT or DOS partition index, 126 num 127 being the eMMC hardware partition number. 128 129 A value of environment variable *dfu_alt_info* for eMMC could be:: 130 131 u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1 132 133 A value of environment variable *dfu_alt_info* for SD card could be:: 134 135 u-boot raw 0x80 0x800;uImage ext4 0 2 136 137 If don't want to flash given image file to storage, use "skip" type 138 entity. 139 140 - It can be used to protect flashing wrong image for the specific board. 141 - Especailly, this layout will be useful when thor protocol is used, 142 which performs flashing in batch mode, where more than one file is 143 processed. 144 145 For example, if one makes a single tar file with support for the two 146 boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one 147 can use it to flash a proper u-boot image on both without a failure:: 148 149 u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0 150 151 When flashing new system image requires do some more complex things 152 than just writing data to the storage medium, one can use 'script' 153 type. Data written to such entity will be executed as a command list 154 in the u-boot's shell. This for example allows to re-create partition 155 layout and even set new *dfu_alt_info* for the newly created paritions. 156 Such script would look like:: 157 158 setenv dfu_alt_info ... 159 setenv mbr_parts ... 160 mbr write ... 161 162 Please note that this means that user will be able to execute any 163 arbitrary commands just like in the u-boot's shell. 164 165nand 166 raw slc nand device:: 167 168 dfu 0 nand <dev> 169 170 each element in *dfu_alt_info* being either of 171 172 * <name> raw <offset> <size> raw access to mmc device 173 * <name> part <dev> <part_id> raw acces to partition 174 * <name> partubi <dev> <part_id> raw acces to ubi partition 175 176 with 177 178 partid 179 is the MTD partition index 180 181ram 182 raw access to ram:: 183 184 dfu 0 ram <dev> 185 186 dev 187 is not used for RAM target 188 189 each element in *dfu_alt_info* being:: 190 191 <name> ram <offset> <size> raw access to ram 192 193sf 194 serial flash : NOR:: 195 196 cmd: dfu 0 sf <dev> 197 198 each element in *dfu_alt_info* being either of: 199 200 * <name> raw <offset> <size> raw access to sf device 201 * <name> part <dev> <part_id> raw acces to partition 202 * <name> partubi <dev> <part_id> raw acces to ubi partition 203 204 with 205 206 partid 207 is the MTD partition index 208 209mtd 210 all MTD device: NAND, SPI-NOR, SPI-NAND,...:: 211 212 cmd: dfu 0 mtd <dev> 213 214 with 215 216 dev 217 the mtd identifier as defined in mtd command 218 (nand0, nor0, spi-nand0,...) 219 220 each element in *dfu_alt_info* being either of: 221 222 * <name> raw <offset> <size> forraw access to mtd device 223 * <name> part <dev> <part_id> for raw acces to partition 224 * <name> partubi <dev> <part_id> for raw acces to ubi partition 225 226 with 227 228 partid 229 is the MTD partition index 230 231virt 232 virtual flash back end for DFU 233 234 :: 235 236 cmd: dfu 0 virt <dev> 237 238 each element in *dfu_alt_info* being: 239 240 * <name> 241 242<interface> and <dev> are absent, the dfu command to use multiple devices:: 243 244 cmd: dfu 0 list 245 cmd: dfu 0 246 247*dfu_alt_info* variable provides the list of <interface> <dev> with 248alternate list separated by '&' with the same format for each <alt>:: 249 250 mmc <dev>=<alt1>;....;<altN> 251 nand <dev>=<alt1>;....;<altN> 252 ram <dev>=<alt1>;....;<altN> 253 sf <dev>=<alt1>;....;<altN> 254 mtd <dev>=<alt1>;....;<altN> 255 virt <dev>=<alt1>;....;<altN> 256 257Callbacks 258--------- 259 260The weak callback functions can be implemented to manage specific behavior 261 262dfu_initiated_callback 263 called when the DFU transaction is started, used to initiase the device 264 265dfu_flush_callback 266 called at the end of the DFU write after DFU manifestation, used to manage 267 the device when DFU transaction is closed 268 269Host tools 270---------- 271 272When U-Boot runs the dfu stack, the DFU host tools can be used 273to send/receive firmwares on each configurated alternate. 274 275For example dfu-util is a host side implementation of the DFU 1.1 276specifications(http://dfu-util.sourceforge.net/) which works with U-Boot. 277 278Usage 279----- 280 281Example 1: firmware located in eMMC or SD card, with: 282 283- alternate 1 (alt=1) for SPL partition (GPT partition 1) 284- alternate 2 (alt=2) for U-Boot partition (GPT partition 2) 285 286The U-Boot configuration is:: 287 288 U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2" 289 290 U-Boot> dfu 0 mmc 0 list 291 DFU alt settings list: 292 dev: eMMC alt: 0 name: spl layout: RAW_ADDR 293 dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR 294 295 Boot> dfu 0 mmc 0 296 297On the Host side: 298 299list the available alternate setting:: 300 301 $> dfu-util -l 302 dfu-util 0.9 303 304 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. 305 Copyright 2010-2016 Tormod Volden and Stefan Schmidt 306 This program is Free Software and has ABSOLUTELY NO WARRANTY 307 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ 308 309 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ 310 alt=1, name="u-boot", serial="003A00203438510D36383238" 311 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ 312 alt=0, name="spl", serial="003A00203438510D36383238" 313 314 To download to U-Boot, use -D option 315 316 $> dfu-util -a 0 -D u-boot-spl.bin 317 $> dfu-util -a 1 -D u-boot.bin 318 319 To upload from U-Boot, use -U option 320 321 $> dfu-util -a 0 -U u-boot-spl.bin 322 $> dfu-util -a 1 -U u-boot.bin 323 324 To request a DFU detach and reset the USB connection: 325 $> dfu-util -a 0 -e -R 326 327 328Example 2: firmware located in NOR (sf) and NAND, with: 329 330- alternate 1 (alt=1) for SPL partition (NOR GPT partition 1) 331- alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2) 332- alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3) 333- alternate 4 (alt=4) for UBI partition (NAND GPT partition 1) 334 335:: 336 337 U-Boot> env set dfu_alt_info \ 338 "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \ 339 u-boot-env part 0 3&nand 0=UBI partubi 0,1" 340 341 U-Boot> dfu 0 list 342 343 DFU alt settings list: 344 dev: SF alt: 0 name: spl layout: RAW_ADDR 345 dev: SF alt: 1 name: ssbl layout: RAW_ADDR 346 dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR 347 dev: NAND alt: 3 name: UBI layout: RAW_ADDR 348 349 U-Boot> dfu 0 350 351:: 352 353 $> dfu-util -l 354 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ 355 intf=0, alt=3, name="UBI", serial="002700333338511934383330" 356 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ 357 intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330" 358 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ 359 intf=0, alt=1, name="u-boot", serial="002700333338511934383330" 360 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ 361 intf=0, alt=0, name="spl", serial="002700333338511934383330" 362 363Same example with MTD backend 364 365:: 366 367 U-Boot> env set dfu_alt_info \ 368 "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\ 369 "mtd nand0=UBI partubi 1" 370 371 U-Boot> dfu 0 list 372 using id 'nor0,0' 373 using id 'nor0,1' 374 using id 'nor0,2' 375 using id 'nand0,0' 376 DFU alt settings list: 377 dev: MTD alt: 0 name: spl layout: RAW_ADDR 378 dev: MTD alt: 1 name: u-boot layout: RAW_ADDR 379 dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR 380 dev: MTD alt: 3 name: UBI layout: RAW_ADDR 381 382Example 3 383 384firmware located in SD Card (mmc) and virtual partition on OTP and PMIC not 385volatile memory 386 387- alternate 1 (alt=1) for scard 388- alternate 2 (alt=2) for OTP (virtual) 389- alternate 3 (alt=3) for PMIC NVM (virtual) 390 391:: 392 393 U-Boot> env set dfu_alt_info \ 394 "mmc 0=sdcard raw 0 0x100000&"\ 395 "virt 0=otp" \ 396 "virt 1=pmic" 397 398:: 399 400 U-Boot> dfu 0 list 401 DFU alt settings list: 402 dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR 403 dev: VIRT alt: 1 name: otp layout: RAW_ADDR 404 dev: VIRT alt: 2 name: pmic layout: RAW_ADDR 405