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
  25   These DFU backends are also used by
  26   - the dfutftp (see README.dfutftp)
  27   - the thordown command (cmd/thordown.c and gadget/f_thor.c)
  28
  29 Configuration Options:
  30   CONFIG_DFU
  31   CONFIG_DFU_OVER_USB
  32   CONFIG_DFU_MMC
  33   CONFIG_DFU_NAND
  34   CONFIG_DFU_RAM
  35   CONFIG_DFU_SF
  36   CONFIG_DFU_SF_PART
  37   CONFIG_CMD_DFU
  38
  39 Environment variables:
  40   the dfu command use 3 environments variables:
  41   "dfu_alt_info" : the DFU setting for the USB download gadget with a comma
  42                    separated string of information on each alternate:
  43                    dfu_alt_info="<alt1>;<alt2>;....;<altN>"
  44
  45   "dfu_bufsiz" : size of the DFU buffer, when absent, use
  46                  CONFIG_SYS_DFU_DATA_BUF_SIZE (8MiB by default)
  47
  48   "dfu_hash_algo" : name of the hash algorithm to use
  49
  50 Commands:
  51   dfu <USB_controller> <interface> <dev> list
  52     list the alternate device defined in "dfu_alt_info"
  53
  54   dfu <USB_controller> <interface> <dev>
  55     start the dfu stack on the USB instance with the selected medium
  56     backend and use the "dfu_alt_info" variable to configure the
  57     alternate setting and link each one with the medium
  58     The dfu command continue until receive a ^C in console or
  59     a DFU detach transaction from HOST.
  60
  61   The possible values of <interface> are :
  62   (with <USB controller> = 0 in the dfu command example)
  63
  64   "mmc" (for eMMC and SD card)
  65     cmd: dfu 0 mmc <dev>
  66     each element in "dfu_alt_info" =
  67       <name> raw <offset> <size>   raw access to mmc device
  68       <name> part <dev> <part_id>  raw acces to partition
  69       <name> fat <dev> <part_id>   file in FAT partition
  70       <name> ext4 <dev> <part_id>  file in EXT4 partition
  71
  72       with <partid> is the GPT or DOS partition index
  73
  74   "nand" (raw slc nand device)
  75     cmd: dfu 0 nand <dev>
  76     each element in "dfu_alt_info" =
  77       <name> raw <offset> <size>   raw access to mmc device
  78       <name> part <dev> <part_id>  raw acces to partition
  79       <name> partubi <dev> <part_id>  raw acces to ubi partition
  80
  81       with <partid> is the MTD partition index
  82
  83   "ram"
  84     cmd: dfu 0 ram <dev>
  85     (<dev> is not used for RAM target)
  86     each element in "dfu_alt_info" =
  87       <name> ram <offset> <size>  raw access to ram
  88
  89   "sf" (serial flash : NOR)
  90     cmd: dfu 0 sf <dev>
  91     each element in "dfu_alt_info" =
  92       <name> ram <offset> <size>  raw access to sf device
  93       <name> part <dev> <part_id>  raw acces to partition
  94       <name> partubi <dev> <part_id>  raw acces to ubi partition
  95
  96       with <partid> is the MTD partition index
  97
  98 Host tools:
  99   When U-Boot runs the dfu stack, the DFU host tools can be used
 100   to send/receive firmwares on each configurated alternate.
 101
 102   For example dfu-util is a host side implementation of the DFU 1.1
 103   specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
 104
 105 Usage:
 106   Example for firmware located in eMMC or SD card, with:
 107   - alternate 1 (alt=1) for SPL partition (GPT partition 1)
 108   - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
 109
 110   The U-Boot configuration is:
 111
 112   U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
 113
 114   U-Boot> dfu 0 mmc 0 list
 115   DFU alt settings list:
 116   dev: eMMC alt: 0 name: spl layout: RAW_ADDR
 117   dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
 118
 119   Boot> dfu 0 mmc 0
 120
 121   On the Host side:
 122
 123   list the available alternate setting:
 124
 125   $> dfu-util -l
 126   dfu-util 0.9
 127
 128   Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
 129   Copyright 2010-2016 Tormod Volden and Stefan Schmidt
 130   This program is Free Software and has ABSOLUTELY NO WARRANTY
 131   Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
 132
 133   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
 134      alt=1, name="u-boot", serial="003A00203438510D36383238"
 135   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
 136      alt=0, name="spl", serial="003A00203438510D36383238"
 137
 138   To download to U-Boot, use -D option
 139
 140   $> dfu-util -a 0 -D u-boot-spl.bin
 141   $> dfu-util -a 1 -D u-boot.bin
 142
 143   To upload from U-Boot, use -U option
 144
 145   $> dfu-util -a 0 -U u-boot-spl.bin
 146   $> dfu-util -a 1 -U u-boot.bin
 147
 148   To request a DFU detach and reset the USB connection:
 149   $> dfu-util -a 0 -e  -R