doc/README.dfu

   1 # SPDX-License-Identifier: GPL-2.0+
   2
   3 Device Firmware Upgrade (DFU)
   4
   5 Overview:
   6
   7   The Device Firmware Upgrade (DFU) allows to download and upload firmware
   8   to/from U-Boot connected over USB.
   9
  10   U-boot follows the Universal Serial Bus Device Class Specification for
  11   Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).
  12
  13   U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
  14   (cmd/dfu.c / CONFIG_CMD_DFU) based on:
  15   - the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
  16     USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
  17   - The access to mediums is done in DFU backends (driver/dfu)
  18
  19   Today the supported DFU backends are:
  20   - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system)
  21   - NAND
  22   - RAM
  23   - SF (serial flash)
  24   - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
  25   - virtual
  26
  27   These DFU backends are also used by
  28   - the dfutftp (see README.dfutftp)
  29   - the thordown command (cmd/thordown.c and gadget/f_thor.c)
  30
  31   The "virtual" backend is a generic DFU backend to support a board specific
  32   target (for example OTP), only based on the weak functions:
  33   - dfu_write_medium_virt
  34   - dfu_get_medium_size_virt
  35   - dfu_read_medium_virt
  36
  37 Configuration Options:
  38   CONFIG_DFU
  39   CONFIG_DFU_OVER_USB
  40   CONFIG_DFU_MMC
  41   CONFIG_DFU_MTD
  42   CONFIG_DFU_NAND
  43   CONFIG_DFU_RAM
  44   CONFIG_DFU_SF
  45   CONFIG_DFU_SF_PART
  46   CONFIG_DFU_TIMEOUT
  47   CONFIG_DFU_VIRTUAL
  48   CONFIG_CMD_DFU
  49
  50 Environment variables:
  51   the dfu command uses 3 environments variables:
  52   "dfu_alt_info" : the DFU setting for the USB download gadget with a semicolon
  53                    separated string of information on each alternate:
  54                    dfu_alt_info="<alt1>;<alt2>;....;<altN>"
  55
  56                    when several devices are used, the format is:
  57                    - <interface> <dev>'='alternate list (';' separated)
  58                    - each interface is separated by '&'
  59                 dfu_alt_info=\
  60                    "<interface1> <dev1>=<alt1>;....;<altN>&"\
  61                    "<interface2> <dev2>=<altN+1>;....;<altM>&"\
  62                    ...\
  63                    "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
  64
  65   "dfu_bufsiz" : size of the DFU buffer, when absent, use
  66                  CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default)
  67
  68   "dfu_hash_algo" : name of the hash algorithm to use
  69
  70 Commands:
  71   dfu <USB_controller> [<interface> <dev>] list
  72     list the alternate device defined in "dfu_alt_info"
  73
  74   dfu <USB_controller> [<interface> <dev>] [<timeout>]
  75     start the dfu stack on the USB instance with the selected medium
  76     backend and use the "dfu_alt_info" variable to configure the
  77     alternate setting and link each one with the medium
  78     The dfu command continue until receive a ^C in console or
  79     a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option
  80     is enabled and <timeout> parameter is present in the command line,
  81     the DFU operation will be aborted automatically after <timeout>
  82     seconds of waiting remote to initiate DFU session.
  83
  84   The possible values of <interface> are :
  85   (with <USB controller> = 0 in the dfu command example)
  86
  87   "mmc" (for eMMC and SD card)
  88     cmd: dfu 0 mmc <dev>
  89     each element in "dfu_alt_info" =
  90       <name> raw <offset> <size> [mmcpart <num>]   raw access to mmc device
  91       <name> part <dev> <part_id> [mmcpart <num>]  raw access to partition
  92       <name> fat <dev> <part_id> [mmcpart <num>]   file in FAT partition
  93       <name> ext4 <dev> <part_id> [mmcpart <num>]  file in EXT4 partition
  94
  95       with <partid> being the GPT or DOS partition index,
  96       with <num> being the eMMC hardware partition number.
  97
  98     A value of environment variable dfu_alt_info for eMMC could be:
  99
 100       "u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1"
 101
 102     A value of environment variable dfu_alt_info for SD card could be:
 103
 104       "u-boot raw 0x80 0x800;uImage ext4 0 2"
 105
 106   "nand" (raw slc nand device)
 107     cmd: dfu 0 nand <dev>
 108     each element in "dfu_alt_info" =
 109       <name> raw <offset> <size>   raw access to mmc device
 110       <name> part <dev> <part_id>  raw acces to partition
 111       <name> partubi <dev> <part_id>  raw acces to ubi partition
 112
 113       with <partid> is the MTD partition index
 114
 115   "ram"
 116     cmd: dfu 0 ram <dev>
 117     (<dev> is not used for RAM target)
 118     each element in "dfu_alt_info" =
 119       <name> ram <offset> <size>  raw access to ram
 120
 121   "sf" (serial flash : NOR)
 122     cmd: dfu 0 sf <dev>
 123     each element in "dfu_alt_info" =
 124       <name> ram <offset> <size>  raw access to sf device
 125       <name> part <dev> <part_id>  raw acces to partition
 126       <name> partubi <dev> <part_id>  raw acces to ubi partition
 127
 128       with <partid> is the MTD partition index
 129
 130   "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
 131     cmd: dfu 0 mtd <dev>
 132       with <dev> the mtd identifier as defined in mtd command
 133       (nand0, nor0, spi-nand0,...)
 134     each element in "dfu_alt_info" =
 135       <name> raw <offset> <size>  raw access to mtd device
 136       <name> part <dev> <part_id>  raw acces to partition
 137       <name> partubi <dev> <part_id>  raw acces to ubi partition
 138
 139       with <partid> is the MTD partition index
 140
 141   "virt"
 142     cmd: dfu 0 virt <dev>
 143     each element in "dfu_alt_info" =
 144       <name>
 145
 146   <interface> and <dev> are absent:
 147     the dfu command to use multiple devices
 148     cmd: dfu 0 list
 149     cmd: dfu 0
 150    "dfu_alt_info" variable provides the list of <interface> <dev> with
 151    alternate list separated by '&' with the same format for each <alt>
 152        mmc <dev>=<alt1>;....;<altN>
 153        nand <dev>=<alt1>;....;<altN>
 154        ram <dev>=<alt1>;....;<altN>
 155        sf <dev>=<alt1>;....;<altN>
 156        mtd <dev>=<alt1>;....;<altN>
 157        virt <dev>=<alt1>;....;<altN>
 158
 159 Callbacks:
 160   The weak callback functions can be implemented to manage specific behavior
 161   - dfu_initiated_callback  : called when the DFU transaction is started,
 162                               used to initiase the device
 163   - dfu_flush_callback      : called at the end of the DFU write after DFU
 164                               manifestation, used to manage the device when
 165                               DFU transaction is closed
 166
 167 Host tools:
 168   When U-Boot runs the dfu stack, the DFU host tools can be used
 169   to send/receive firmwares on each configurated alternate.
 170
 171   For example dfu-util is a host side implementation of the DFU 1.1
 172   specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
 173
 174 Usage:
 175   Example 1: firmware located in eMMC or SD card, with:
 176   - alternate 1 (alt=1) for SPL partition (GPT partition 1)
 177   - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
 178
 179   The U-Boot configuration is:
 180
 181   U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
 182
 183   U-Boot> dfu 0 mmc 0 list
 184   DFU alt settings list:
 185   dev: eMMC alt: 0 name: spl layout: RAW_ADDR
 186   dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
 187
 188   Boot> dfu 0 mmc 0
 189
 190   On the Host side:
 191
 192   list the available alternate setting:
 193
 194   $> dfu-util -l
 195   dfu-util 0.9
 196
 197   Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
 198   Copyright 2010-2016 Tormod Volden and Stefan Schmidt
 199   This program is Free Software and has ABSOLUTELY NO WARRANTY
 200   Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
 201
 202   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
 203      alt=1, name="u-boot", serial="003A00203438510D36383238"
 204   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
 205      alt=0, name="spl", serial="003A00203438510D36383238"
 206
 207   To download to U-Boot, use -D option
 208
 209   $> dfu-util -a 0 -D u-boot-spl.bin
 210   $> dfu-util -a 1 -D u-boot.bin
 211
 212   To upload from U-Boot, use -U option
 213
 214   $> dfu-util -a 0 -U u-boot-spl.bin
 215   $> dfu-util -a 1 -U u-boot.bin
 216
 217   To request a DFU detach and reset the USB connection:
 218   $> dfu-util -a 0 -e  -R
 219
 220
 221   Example 2: firmware located in NOR (sf) and NAND, with:
 222   - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
 223   - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
 224   - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
 225   - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
 226
 227   U-Boot> env set dfu_alt_info \
 228   "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
 229   u-boot-env part 0 3&nand 0=UBI partubi 0,1"
 230
 231   U-Boot> dfu 0 list
 232
 233   DFU alt settings list:
 234   dev: SF alt: 0 name: spl layout: RAW_ADDR
 235   dev: SF alt: 1 name: ssbl layout: RAW_ADDR
 236   dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
 237   dev: NAND alt: 3 name: UBI layout: RAW_ADDR
 238
 239   U-Boot> dfu 0
 240
 241   $> dfu-util -l
 242   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 243      intf=0, alt=3, name="UBI", serial="002700333338511934383330"
 244   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 245      intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
 246   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 247      intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
 248   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 249      intf=0, alt=0, name="spl", serial="002700333338511934383330"
 250
 251   Same example with MTD backend
 252
 253    U-Boot> env set dfu_alt_info \
 254       "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
 255       "mtd nand0=UBI partubi 1"
 256
 257   U-Boot> dfu 0 list
 258   using id 'nor0,0'
 259   using id 'nor0,1'
 260   using id 'nor0,2'
 261   using id 'nand0,0'
 262   DFU alt settings list:
 263   dev: MTD alt: 0 name: spl layout: RAW_ADDR
 264   dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
 265   dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
 266   dev: MTD alt: 3 name: UBI layout: RAW_ADDR
 267
 268   Example 3: firmware located in SD Card (mmc) and virtual partition on
 269              OTP and PMIC not volatile memory
 270   - alternate 1 (alt=1) for scard
 271   - alternate 2 (alt=2) for OTP (virtual)
 272   - alternate 3 (alt=3) for PMIC NVM (virtual)
 273
 274    U-Boot> env set dfu_alt_info \
 275       "mmc 0=sdcard raw 0 0x100000&"\
 276       "virt 0=otp" \
 277       "virt 1=pmic"
 278
 279    U-Boot> dfu 0 list
 280    DFU alt settings list:
 281    dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
 282    dev: VIRT alt: 1 name: otp layout: RAW_ADDR
 283    dev: VIRT alt: 2 name: pmic layout: RAW_ADDR