10 Oct
2019
10 Oct
'19
12:04 p.m.
Hi Patrick,
Add documentation for dfu stack and "dfu" command.
Reviewed-by: Lukasz Majewski lukma@denx.de
Signed-off-by: Patrick Delaunay patrick.delaunay@st.com
Changes in v2:
- Add dfu documentation
doc/README.dfu | 144 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 doc/README.dfu
diff --git a/doc/README.dfu b/doc/README.dfu new file mode 100644 index 0000000000..f5344e236c --- /dev/null +++ b/doc/README.dfu @@ -0,0 +1,144 @@ +# 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)
- 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_NAND
- CONFIG_DFU_RAM
- CONFIG_DFU_SF
- 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>"- "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 partitionwith <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 partitionwith <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+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 for 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
Best regards,
Lukasz Majewski
--
DENX Software Engineering GmbH, Managing Director: Wolfgang Denk HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany Phone: (+49)-8142-66989-59 Fax: (+49)-8142-66989-80 Email: lukma@denx.de