doc: dfu: Add dfu documentation
Add documentation for dfu stack and "dfu" command. Reviewed-by: Lukasz Majewski <lukma@denx.de> Signed-off-by: Patrick Delaunay <patrick.delaunay@st.com>
This commit is contained in:
Patrick Delaunay
Marek Vasut
parent
909b690b31
commit
321179eec5
|
|
@ -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 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
|
||||||
|
|
||||||
|
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
|
||||||
Loading…
Reference in New Issue