Hi Patrick, > Add documentation for dfu stack and "dfu" command. >
Reviewed-by: Lukasz Majewski <lu...@denx.de> > Signed-off-by: Patrick Delaunay <patrick.delau...@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 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 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: lu...@denx.de
pgp3Qq5xesuJc.pgp
Description: OpenPGP digital signature
_______________________________________________ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot