[U-Boot] [PATCH 1/8] doc: dfu: tftp: README entry for TFTP extension of DFU

[Lukasz Majewski]

Documentation file for DFU extension. With this functionality it is now
possible to transfer FIT images with firmware updates via TFTP and use
DFU backend for storing them.

Signed-off-by: Lukasz Majewski <l.majewski at majess.pl>
---
 doc/README.dfutftp | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 doc/README.dfutftp

diff --git a/doc/README.dfutftp b/doc/README.dfutftp
new file mode 100644
index 0000000..4636321
--- /dev/null
+++ b/doc/README.dfutftp
@@ -0,0 +1,153 @@
+Device Firmware Upgrade (DFU) - extension to use TFTP
+=====================================================
+
+Why?
+----
+
+* Update TFTP (CONFIG_UPDATE_TFTP) only supports writing
+code to NAND memory via TFTP.
+* DFU supports writing data to variety of mediums (NAND,
+eMMC, SD, partitions, RAM, etc) via USB.
+
+Combination of both solves their shortcomings!
+
+
+Overview
+--------
+
+This document briefly describes how to use BF for
+upgrading firmware (e.g. kernel, u-boot, rootfs, etc.)
+via TFTP protocol.
+
+By using Ethernet (TFTP protocol to be precise) it was
+possible to overcome the major problem of USB based DFU -
+the relatively low transfer speed for large files.
+This was caused by DFU standard, which imposed utilization
+of only EP0 for transfer. By using Ethernet we can circumvent
+this shortcoming.
+
+Beagle Bone Black (BBB) powered by TI's am335x CPU has been used
+as a demo board.
+
+To utilize this feature, one needs to first enable support
+for USB based DFU (CONFIG_DFU_*) and TFTP update
+(CONFIG_UPDATE_TFTP) described in ./doc/README.update.
+
+New "dfutftp" command has been introduced to comply with present
+USB related commands' syntax.
+
+This code works without "fitupd" command enabled.
+
+As of this writing (SHA1:241746e618fa725491e9ff689710c5f73ffd9139) the
+update.c code is not enabled (CONFIG_UPDATE_TFTP) by any board in the
+contemporary u-boot tree.
+
+
+Environment variables
+---------------------
+
+To preserve legacy behavior of TFTP update (./common/update.c)
+code following new environment variables had been introduced:
+
+* "update_tftp_exec_at_boot" ["true"|"false"]
+
+  New usage of update_tftp allows setting the
+  "update_tftp_exec_at_boot" env variable to allow it running
+  at boot time.
+  In this way update_tftp will not be executed at startup and reduce
+  boot time.
+
+  To preserve backward compatibility for legacy boards this variable
+  should be set to "true".
+
+  BBB note:
+	    When update tftp is not working after boot one need to
+	    increase values of following two configs:
+	    CONFIG_UPDATE_TFTP_MSEC_MAX and CONFIG_UPDATE_TFTP_CNT_MAX.
+	    Values of namely 1000 and 5 solve the issue for BBB.
+
+* "update_tftp_dfu" ["true"|"false"]
+
+  By "update_tftp_dfu" env variable we inform update_tftp that
+  it should use dfu for writing data - in this way support for
+  legacy usage is preserved.
+
+* "update_tftp_dfu_interface" ["mmc"]
+* "update_tftp_dfu_devstring" ["1"]
+
+  Both variables - namely "update_tftp_dfu_{interface|devstring}" are
+  only taken into account when "update_tftp_dfu" is defined.
+  They store information about interface (e.g. "mmc") and device number
+  string (e.g. "1").
+
+  In the "dfutftp" command they are explicitly overridden.
+  It is done deliberately, since in this command we may use arbitrary values.
+
+  Default values, when available during boot, are used by update_tftp
+  (when dfu support is enabled) to properly setup medium device
+  (e.g. mmc 1).
+
+
+
+Beagle Bone Black (BBB) setup
+-----------------------------
+
+1. Setup tftp env variables:
+   *  select desired eth device - 'ethact' variable ["ethact=cpsw"]
+      (use "bdinfo" to check current setting)
+   *  setup "serverip" and "ipaddr" variables
+   *  set "loadaddr" as a fixed buffer where incoming data is placed
+      ["loadaddr=0x81000000"]
+
+#########
+# BONUS #
+#########
+It is possible to use USB interface to emulate ETH connection by setting
+"ethact=usb_ether". In this way one can have very fast DFU transfer via USB.
+
+For 33MiB test image the transfer rate is 1MiB/s
+
+2. Setup update_tftp variables:
+   *  set "updatefile" - the file name to be downloaded via TFTP (stored on
+      the HOST at e.g. /srv/tftp)
+
+3. Setup dfutftp specific variables (as explained in "Environment Variables")
+   * "update_tftp_exec_at_boot=true"
+   * "update_tftp_dfu=true"
+
+4. Inspect "dfu" specific variables:
+   * "dfu_alt_info" - information about available DFU entities
+   * "dfu_bufsiz"   - variable to set buffer size [in bytes] - when it is not
+		      possible to set large enough default buffer (8 MiB @ BBB)
+
+
+
+FIT image format for download
+-----------------------------
+
+To create FIT image for download one should follow the update tftp README file
+(./doc/README.update) with one notable difference:
+
+The original snippet of ./doc/uImage.FIT/update_uboot.its
+
+	images {
+		update at 1 {
+			description = "U-Boot binary";
+
+should look like
+
+	images {
+		u-boot.bin at 1 {
+			description = "U-Boot binary";
+
+where "u-boot.bin" is the DFU entity name to be stored.
+
+
+
+To do
+-----
+
+* Extend dfu-util command (or write new one - e.g. dfueth-util) to support
+  TFTP based transfers
+
+* Upload support (via TFTP)
\ No newline at end of file
-- 
2.1.4