[U-Boot] [PATCH v2 02/16] doc: dfu: Add dfu documentation

Lukasz Majewski
2019-10-10T10:04:13Z

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 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: lukma at denx.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20191010/3cf9570a/attachment.sig>