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 / SKIP / SCRIPT)
  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       <name> skip 0 0                              ignore flashed data
  95       <name> script 0 0                            execute commands in shell
  96
  97       with <partid> being the GPT or DOS partition index,
  98       with <num> being the eMMC hardware partition number.
  99
 100     A value of environment variable dfu_alt_info for eMMC could be:
 101
 102       "u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1"
 103
 104     A value of environment variable dfu_alt_info for SD card could be:
 105
 106       "u-boot raw 0x80 0x800;uImage ext4 0 2"
 107
 108     If don't want to flash given image file to storage, use "skip" type
 109     entity.
 110     - It can be used to protect flashing wrong image for the specific board.
 111     - Especailly, this layout will be useful when thor protocol is used,
 112       which performs flashing in batch mode, where more than one file is
 113       processed.
 114     For example, if one makes a single tar file with support for the two
 115     boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one
 116     can use it to flash a proper u-boot image on both without a failure:
 117
 118       "u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0"
 119
 120     When flashing new system image requires do some more complex things
 121     than just writing data to the storage medium, one can use 'script'
 122     type. Data written to such entity will be executed as a command list
 123     in the u-boot's shell. This for example allows to re-create partition
 124     layout and even set new dfu_alt_info for the newly created paritions.
 125     Such script would look like:
 126         --->8---
 127         setenv dfu_alt_info ...
 128         setenv mbr_parts ...
 129         mbr write ...
 130         --->8---
 131     Please note that this means that user will be able to execute any
 132     arbitrary commands just like in the u-boot's shell.
 133
 134   "nand" (raw slc nand device)
 135     cmd: dfu 0 nand <dev>
 136     each element in "dfu_alt_info" =
 137       <name> raw <offset> <size>   raw access to mmc device
 138       <name> part <dev> <part_id>  raw acces to partition
 139       <name> partubi <dev> <part_id>  raw acces to ubi partition
 140
 141       with <partid> is the MTD partition index
 142
 143   "ram"
 144     cmd: dfu 0 ram <dev>
 145     (<dev> is not used for RAM target)
 146     each element in "dfu_alt_info" =
 147       <name> ram <offset> <size>  raw access to ram
 148
 149   "sf" (serial flash : NOR)
 150     cmd: dfu 0 sf <dev>
 151     each element in "dfu_alt_info" =
 152       <name> raw <offset> <size>  raw access to sf device
 153       <name> part <dev> <part_id>  raw acces to partition
 154       <name> partubi <dev> <part_id>  raw acces to ubi partition
 155
 156       with <partid> is the MTD partition index
 157
 158   "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
 159     cmd: dfu 0 mtd <dev>
 160       with <dev> the mtd identifier as defined in mtd command
 161       (nand0, nor0, spi-nand0,...)
 162     each element in "dfu_alt_info" =
 163       <name> raw <offset> <size>  raw access to mtd device
 164       <name> part <dev> <part_id>  raw acces to partition
 165       <name> partubi <dev> <part_id>  raw acces to ubi partition
 166
 167       with <partid> is the MTD partition index
 168
 169   "virt"
 170     cmd: dfu 0 virt <dev>
 171     each element in "dfu_alt_info" =
 172       <name>
 173
 174   <interface> and <dev> are absent:
 175     the dfu command to use multiple devices
 176     cmd: dfu 0 list
 177     cmd: dfu 0
 178    "dfu_alt_info" variable provides the list of <interface> <dev> with
 179    alternate list separated by '&' with the same format for each <alt>
 180        mmc <dev>=<alt1>;....;<altN>
 181        nand <dev>=<alt1>;....;<altN>
 182        ram <dev>=<alt1>;....;<altN>
 183        sf <dev>=<alt1>;....;<altN>
 184        mtd <dev>=<alt1>;....;<altN>
 185        virt <dev>=<alt1>;....;<altN>
 186
 187 Callbacks:
 188   The weak callback functions can be implemented to manage specific behavior
 189   - dfu_initiated_callback  : called when the DFU transaction is started,
 190                               used to initiase the device
 191   - dfu_flush_callback      : called at the end of the DFU write after DFU
 192                               manifestation, used to manage the device when
 193                               DFU transaction is closed
 194
 195 Host tools:
 196   When U-Boot runs the dfu stack, the DFU host tools can be used
 197   to send/receive firmwares on each configurated alternate.
 198
 199   For example dfu-util is a host side implementation of the DFU 1.1
 200   specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
 201
 202 Usage:
 203   Example 1: firmware located in eMMC or SD card, with:
 204   - alternate 1 (alt=1) for SPL partition (GPT partition 1)
 205   - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
 206
 207   The U-Boot configuration is:
 208
 209   U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
 210
 211   U-Boot> dfu 0 mmc 0 list
 212   DFU alt settings list:
 213   dev: eMMC alt: 0 name: spl layout: RAW_ADDR
 214   dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
 215
 216   Boot> dfu 0 mmc 0
 217
 218   On the Host side:
 219
 220   list the available alternate setting:
 221
 222   $> dfu-util -l
 223   dfu-util 0.9
 224
 225   Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
 226   Copyright 2010-2016 Tormod Volden and Stefan Schmidt
 227   This program is Free Software and has ABSOLUTELY NO WARRANTY
 228   Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
 229
 230   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
 231      alt=1, name="u-boot", serial="003A00203438510D36383238"
 232   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
 233      alt=0, name="spl", serial="003A00203438510D36383238"
 234
 235   To download to U-Boot, use -D option
 236
 237   $> dfu-util -a 0 -D u-boot-spl.bin
 238   $> dfu-util -a 1 -D u-boot.bin
 239
 240   To upload from U-Boot, use -U option
 241
 242   $> dfu-util -a 0 -U u-boot-spl.bin
 243   $> dfu-util -a 1 -U u-boot.bin
 244
 245   To request a DFU detach and reset the USB connection:
 246   $> dfu-util -a 0 -e  -R
 247
 248
 249   Example 2: firmware located in NOR (sf) and NAND, with:
 250   - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
 251   - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
 252   - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
 253   - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
 254
 255   U-Boot> env set dfu_alt_info \
 256   "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
 257   u-boot-env part 0 3&nand 0=UBI partubi 0,1"
 258
 259   U-Boot> dfu 0 list
 260
 261   DFU alt settings list:
 262   dev: SF alt: 0 name: spl layout: RAW_ADDR
 263   dev: SF alt: 1 name: ssbl layout: RAW_ADDR
 264   dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
 265   dev: NAND alt: 3 name: UBI layout: RAW_ADDR
 266
 267   U-Boot> dfu 0
 268
 269   $> dfu-util -l
 270   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 271      intf=0, alt=3, name="UBI", serial="002700333338511934383330"
 272   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 273      intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
 274   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 275      intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
 276   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
 277      intf=0, alt=0, name="spl", serial="002700333338511934383330"
 278
 279   Same example with MTD backend
 280
 281    U-Boot> env set dfu_alt_info \
 282       "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
 283       "mtd nand0=UBI partubi 1"
 284
 285   U-Boot> dfu 0 list
 286   using id 'nor0,0'
 287   using id 'nor0,1'
 288   using id 'nor0,2'
 289   using id 'nand0,0'
 290   DFU alt settings list:
 291   dev: MTD alt: 0 name: spl layout: RAW_ADDR
 292   dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
 293   dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
 294   dev: MTD alt: 3 name: UBI layout: RAW_ADDR
 295
 296   Example 3: firmware located in SD Card (mmc) and virtual partition on
 297              OTP and PMIC not volatile memory
 298   - alternate 1 (alt=1) for scard
 299   - alternate 2 (alt=2) for OTP (virtual)
 300   - alternate 3 (alt=3) for PMIC NVM (virtual)
 301
 302    U-Boot> env set dfu_alt_info \
 303       "mmc 0=sdcard raw 0 0x100000&"\
 304       "virt 0=otp" \
 305       "virt 1=pmic"
 306
 307    U-Boot> dfu 0 list
 308    DFU alt settings list:
 309    dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
 310    dev: VIRT alt: 1 name: otp layout: RAW_ADDR
 311    dev: VIRT alt: 2 name: pmic layout: RAW_ADDR