doc/README.dfu - platform/external/u-boot - Gitiles

 # SPDX-License-Identifier: GPL-2.0+

 Device Firmware Upgrade (DFU)

 Overview:

   The Device Firmware Upgrade (DFU) allows to download and upload firmware
   to/from U-Boot connected over USB.

   U-boot follows the Universal Serial Bus Device Class Specification for
   Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).

   U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
   (cmd/dfu.c / CONFIG_CMD_DFU) based on:
   - the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
     USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
   - The access to mediums is done in DFU backends (driver/dfu)

   Today the supported DFU backends are:
   - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system)
   - NAND
   - RAM
   - SF (serial flash)
   - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)

   These DFU backends are also used by
   - the dfutftp (see README.dfutftp)
   - the thordown command (cmd/thordown.c and gadget/f_thor.c)

 Configuration Options:
   CONFIG_DFU
   CONFIG_DFU_OVER_USB
   CONFIG_DFU_MMC
   CONFIG_DFU_MTD
   CONFIG_DFU_NAND
   CONFIG_DFU_RAM
   CONFIG_DFU_SF
   CONFIG_DFU_SF_PART
   CONFIG_CMD_DFU

 Environment variables:
   the dfu command use 3 environments variables:
   "dfu_alt_info" : the DFU setting for the USB download gadget with a comma
                    separated string of information on each alternate:
                    dfu_alt_info="<alt1>;<alt2>;....;<altN>"

                    when only several device are used, the format is:
                    - <interface> <dev>'='alternate list (';' separated)
                    - each interface is separated by '&'
                 dfu_alt_info=\
                    "<interface1> <dev1>=<alt1>;....;<altN>&"\
                    "<interface2> <dev2>=<altN+1>;....;<altM>&"\
                    ...\
                    "<interfaceI> <devI>=<altY+1>;....;<altZ>&"

   "dfu_bufsiz" : size of the DFU buffer, when absent, use
                  CONFIG_SYS_DFU_DATA_BUF_SIZE (8MiB by default)

   "dfu_hash_algo" : name of the hash algorithm to use

 Commands:
   dfu <USB_controller> [<interface> <dev>] list
     list the alternate device defined in "dfu_alt_info"

   dfu <USB_controller> [<interface> <dev>]
     start the dfu stack on the USB instance with the selected medium
     backend and use the "dfu_alt_info" variable to configure the
     alternate setting and link each one with the medium
     The dfu command continue until receive a ^C in console or
     a DFU detach transaction from HOST.

   The possible values of <interface> are :
   (with <USB controller> = 0 in the dfu command example)

   "mmc" (for eMMC and SD card)
     cmd: dfu 0 mmc <dev>
     each element in "dfu_alt_info" =
       <name> raw <offset> <size>   raw access to mmc device
       <name> part <dev> <part_id>  raw acces to partition
       <name> fat <dev> <part_id>   file in FAT partition
       <name> ext4 <dev> <part_id>  file in EXT4 partition

       with <partid> is the GPT or DOS partition index

   "nand" (raw slc nand device)
     cmd: dfu 0 nand <dev>
     each element in "dfu_alt_info" =
       <name> raw <offset> <size>   raw access to mmc device
       <name> part <dev> <part_id>  raw acces to partition
       <name> partubi <dev> <part_id>  raw acces to ubi partition

       with <partid> is the MTD partition index

   "ram"
     cmd: dfu 0 ram <dev>
     (<dev> is not used for RAM target)
     each element in "dfu_alt_info" =
       <name> ram <offset> <size>  raw access to ram

   "sf" (serial flash : NOR)
     cmd: dfu 0 sf <dev>
     each element in "dfu_alt_info" =
       <name> ram <offset> <size>  raw access to sf device
       <name> part <dev> <part_id>  raw acces to partition
       <name> partubi <dev> <part_id>  raw acces to ubi partition

       with <partid> is the MTD partition index

   "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
     cmd: dfu 0 mtd <dev>
       with <dev> the mtd identifier as defined in mtd command
       (nand0, nor0, spi-nand0,...)
     each element in "dfu_alt_info" =
       <name> raw <offset> <size>  raw access to mtd device
       <name> part <dev> <part_id>  raw acces to partition
       <name> partubi <dev> <part_id>  raw acces to ubi partition

       with <partid> is the MTD partition index

   <interface> and <dev> are absent:
     the dfu command to use multiple devices
     cmd: dfu 0 list
     cmd: dfu 0
    "dfu_alt_info" variable provides the list of <interface> <dev> with
    alternate list separated by '&' with the same format for each <alt>
        mmc <dev>=<alt1>;....;<altN>
        nand <dev>=<alt1>;....;<altN>
        ram <dev>=<alt1>;....;<altN>
        sf <dev>=<alt1>;....;<altN>
        mtd <dev>=<alt1>;....;<altN>


 Host tools:
   When U-Boot runs the dfu stack, the DFU host tools can be used
   to send/receive firmwares on each configurated alternate.

   For example dfu-util is a host side implementation of the DFU 1.1
   specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.

 Usage:
   Example 1: firmware located in eMMC or SD card, with:
   - alternate 1 (alt=1) for SPL partition (GPT partition 1)
   - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)

   The U-Boot configuration is:

   U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"

   U-Boot> dfu 0 mmc 0 list
   DFU alt settings list:
   dev: eMMC alt: 0 name: spl layout: RAW_ADDR
   dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR

   Boot> dfu 0 mmc 0

   On the Host side:

   list the available alternate setting:

   $> dfu-util -l
   dfu-util 0.9

   Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
   Copyright 2010-2016 Tormod Volden and Stefan Schmidt
   This program is Free Software and has ABSOLUTELY NO WARRANTY
   Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
      alt=1, name="u-boot", serial="003A00203438510D36383238"
   Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
      alt=0, name="spl", serial="003A00203438510D36383238"

   To download to U-Boot, use -D option

   $> dfu-util -a 0 -D u-boot-spl.bin
   $> dfu-util -a 1 -D u-boot.bin

   To upload from U-Boot, use -U option

   $> dfu-util -a 0 -U u-boot-spl.bin
   $> dfu-util -a 1 -U u-boot.bin

   To request a DFU detach and reset the USB connection:
   $> dfu-util -a 0 -e  -R


   Example 2: firmware located in NOR (sf) and NAND, with:
   - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
   - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
   - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
   - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)

   U-Boot> env set dfu_alt_info \
   "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
   u-boot-env part 0 3&nand 0=UBI partubi 0,1"

   U-Boot> dfu 0 list

   DFU alt settings list:
   dev: SF alt: 0 name: spl layout: RAW_ADDR
   dev: SF alt: 1 name: ssbl layout: RAW_ADDR
   dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
   dev: NAND alt: 3 name: UBI layout: RAW_ADDR

   U-Boot> dfu 0

   $> dfu-util -l
   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
      intf=0, alt=3, name="UBI", serial="002700333338511934383330"
   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
      intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
      intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
   Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
      intf=0, alt=0, name="spl", serial="002700333338511934383330"

   Same example with MTD backend

    U-Boot> env set dfu_alt_info \
       "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
       "mtd nand0=UBI partubi 1"

   U-Boot> dfu 0 list
   using id 'nor0,0'
   using id 'nor0,1'
   using id 'nor0,2'
   using id 'nand0,0'
   DFU alt settings list:
   dev: MTD alt: 0 name: spl layout: RAW_ADDR
   dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
   dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
   dev: MTD alt: 3 name: UBI layout: RAW_ADDR
	# SPDX-License-Identifier: GPL-2.0+

	Device Firmware Upgrade (DFU)

	Overview:

	The Device Firmware Upgrade (DFU) allows to download and upload firmware
	to/from U-Boot connected over USB.

	U-boot follows the Universal Serial Bus Device Class Specification for
	Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).

	U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
	(cmd/dfu.c / CONFIG_CMD_DFU) based on:
	- the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
	USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
	- The access to mediums is done in DFU backends (driver/dfu)

	Today the supported DFU backends are:
	- MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system)
	- NAND
	- RAM
	- SF (serial flash)
	- MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)

	These DFU backends are also used by
	- the dfutftp (see README.dfutftp)
	- the thordown command (cmd/thordown.c and gadget/f_thor.c)

	Configuration Options:
	CONFIG_DFU
	CONFIG_DFU_OVER_USB
	CONFIG_DFU_MMC
	CONFIG_DFU_MTD
	CONFIG_DFU_NAND
	CONFIG_DFU_RAM
	CONFIG_DFU_SF
	CONFIG_DFU_SF_PART
	CONFIG_CMD_DFU

	Environment variables:
	the dfu command use 3 environments variables:
	"dfu_alt_info" : the DFU setting for the USB download gadget with a comma
	separated string of information on each alternate:
	dfu_alt_info="<alt1>;<alt2>;....;<altN>"

	when only several device are used, the format is:
	- <interface> <dev>'='alternate list (';' separated)
	- each interface is separated by '&'
	dfu_alt_info=\
	"<interface1> <dev1>=<alt1>;....;<altN>&"\
	"<interface2> <dev2>=<altN+1>;....;<altM>&"\
	...\
	"<interfaceI> <devI>=<altY+1>;....;<altZ>&"

	"dfu_bufsiz" : size of the DFU buffer, when absent, use
	CONFIG_SYS_DFU_DATA_BUF_SIZE (8MiB by default)

	"dfu_hash_algo" : name of the hash algorithm to use

	Commands:
	dfu <USB_controller> [<interface> <dev>] list
	list the alternate device defined in "dfu_alt_info"

	dfu <USB_controller> [<interface> <dev>]
	start the dfu stack on the USB instance with the selected medium
	backend and use the "dfu_alt_info" variable to configure the
	alternate setting and link each one with the medium
	The dfu command continue until receive a ^C in console or
	a DFU detach transaction from HOST.

	The possible values of <interface> are :
	(with <USB controller> = 0 in the dfu command example)

	"mmc" (for eMMC and SD card)
	cmd: dfu 0 mmc <dev>
	each element in "dfu_alt_info" =
	<name> raw <offset> <size> raw access to mmc device
	<name> part <dev> <part_id> raw acces to partition
	<name> fat <dev> <part_id> file in FAT partition
	<name> ext4 <dev> <part_id> file in EXT4 partition

	with <partid> is the GPT or DOS partition index

	"nand" (raw slc nand device)
	cmd: dfu 0 nand <dev>
	each element in "dfu_alt_info" =
	<name> raw <offset> <size> raw access to mmc device
	<name> part <dev> <part_id> raw acces to partition
	<name> partubi <dev> <part_id> raw acces to ubi partition

	with <partid> is the MTD partition index

	"ram"
	cmd: dfu 0 ram <dev>
	(<dev> is not used for RAM target)
	each element in "dfu_alt_info" =
	<name> ram <offset> <size> raw access to ram

	"sf" (serial flash : NOR)
	cmd: dfu 0 sf <dev>
	each element in "dfu_alt_info" =
	<name> ram <offset> <size> raw access to sf device
	<name> part <dev> <part_id> raw acces to partition
	<name> partubi <dev> <part_id> raw acces to ubi partition

	with <partid> is the MTD partition index

	"mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
	cmd: dfu 0 mtd <dev>
	with <dev> the mtd identifier as defined in mtd command
	(nand0, nor0, spi-nand0,...)
	each element in "dfu_alt_info" =
	<name> raw <offset> <size> raw access to mtd device
	<name> part <dev> <part_id> raw acces to partition
	<name> partubi <dev> <part_id> raw acces to ubi partition

	with <partid> is the MTD partition index

	<interface> and <dev> are absent:
	the dfu command to use multiple devices
	cmd: dfu 0 list
	cmd: dfu 0
	"dfu_alt_info" variable provides the list of <interface> <dev> with
	alternate list separated by '&' with the same format for each <alt>
	mmc <dev>=<alt1>;....;<altN>
	nand <dev>=<alt1>;....;<altN>
	ram <dev>=<alt1>;....;<altN>
	sf <dev>=<alt1>;....;<altN>
	mtd <dev>=<alt1>;....;<altN>


	Host tools:
	When U-Boot runs the dfu stack, the DFU host tools can be used
	to send/receive firmwares on each configurated alternate.

	For example dfu-util is a host side implementation of the DFU 1.1
	specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.

	Usage:
	Example 1: firmware located in eMMC or SD card, with:
	- alternate 1 (alt=1) for SPL partition (GPT partition 1)
	- alternate 2 (alt=2) for U-Boot partition (GPT partition 2)

	The U-Boot configuration is:

	U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"

	U-Boot> dfu 0 mmc 0 list
	DFU alt settings list:
	dev: eMMC alt: 0 name: spl layout: RAW_ADDR
	dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR

	Boot> dfu 0 mmc 0

	On the Host side:

	list the available alternate setting:

	$> dfu-util -l
	dfu-util 0.9

	Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
	Copyright 2010-2016 Tormod Volden and Stefan Schmidt
	This program is Free Software and has ABSOLUTELY NO WARRANTY
	Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

	Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
	alt=1, name="u-boot", serial="003A00203438510D36383238"
	Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
	alt=0, name="spl", serial="003A00203438510D36383238"

	To download to U-Boot, use -D option

	$> dfu-util -a 0 -D u-boot-spl.bin
	$> dfu-util -a 1 -D u-boot.bin

	To upload from U-Boot, use -U option

	$> dfu-util -a 0 -U u-boot-spl.bin
	$> dfu-util -a 1 -U u-boot.bin

	To request a DFU detach and reset the USB connection:
	$> dfu-util -a 0 -e -R


	Example 2: firmware located in NOR (sf) and NAND, with:
	- alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
	- alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
	- alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
	- alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)

	U-Boot> env set dfu_alt_info \
	"sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
	u-boot-env part 0 3&nand 0=UBI partubi 0,1"

	U-Boot> dfu 0 list

	DFU alt settings list:
	dev: SF alt: 0 name: spl layout: RAW_ADDR
	dev: SF alt: 1 name: ssbl layout: RAW_ADDR
	dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
	dev: NAND alt: 3 name: UBI layout: RAW_ADDR

	U-Boot> dfu 0

	$> dfu-util -l
	Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
	intf=0, alt=3, name="UBI", serial="002700333338511934383330"
	Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
	intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
	Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
	intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
	Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
	intf=0, alt=0, name="spl", serial="002700333338511934383330"

	Same example with MTD backend

	U-Boot> env set dfu_alt_info \
	"mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
	"mtd nand0=UBI partubi 1"

	U-Boot> dfu 0 list
	using id 'nor0,0'
	using id 'nor0,1'
	using id 'nor0,2'
	using id 'nand0,0'
	DFU alt settings list:
	dev: MTD alt: 0 name: spl layout: RAW_ADDR
	dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
	dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
	dev: MTD alt: 3 name: UBI layout: RAW_ADDR