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>

1 files changed, 144 insertions, 0 deletions

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