doc/README.dfutftp

   1 #
   2 #  Copyright (C) 2015
   3 #
   4 #  Lukasz Majewski <l.majewski@majess.pl>
   5 #
   6 #
   7 # SPDX-License-Identifier:      GPL-2.0+
   8
   9 Device Firmware Upgrade (DFU) - extension to use TFTP
  10 =====================================================
  11
  12 Why?
  13 ----
  14
  15 * Update TFTP (CONFIG_UPDATE_TFTP) only supports writing
  16 code to NAND memory via TFTP.
  17 * DFU supports writing data to the variety of mediums (NAND,
  18 eMMC, SD, partitions, RAM, etc) via USB.
  19
  20 Combination of both solves their shortcomings!
  21
  22
  23 Overview
  24 --------
  25
  26 This document briefly describes how to use DFU for
  27 upgrading firmware (e.g. kernel, u-boot, rootfs, etc.)
  28 via TFTP protocol.
  29
  30 By using Ethernet (TFTP protocol to be precise) it is
  31 possible to overcome the major problem of USB based DFU -
  32 the relatively low transfer speed for large files.
  33 This was caused by DFU standard, which imposed utilization
  34 of only EP0 for transfer. By using Ethernet we can circumvent
  35 this shortcoming.
  36
  37 Beagle Bone Black rev. C (BBB) powered by TI's am335x CPU has
  38 been used as a demo board.
  39
  40 To utilize this feature, one needs to first enable support
  41 for USB based DFU (CONFIG_DFU_*) and DFU TFTP update
  42 (CONFIG_DFU_TFTP) described in ./doc/README.update.
  43
  44 The "dfu" command has been extended to support transfer via TFTP - one
  45 needs to type for example "dfu tftp 0 mmc 0"
  46
  47 This feature does not depend on "fitupd" command enabled.
  48
  49 As of this writing (SHA1:8d77576371381ade83de475bb639949b44941e8c v2015.10-rc2)
  50 the update.c code is not enabled (CONFIG_UPDATE_TFTP) by any board in the
  51 contemporary u-boot tree.
  52
  53
  54 Environment variables
  55 ---------------------
  56
  57 The "dfu tftp" command can be used in the "preboot" environment variable
  58 (when it is enabled by defining CONFIG_PREBOOT).
  59 This is the preferable way of using this command in the early boot stage
  60 as opposed to legacy update_tftp() function invocation.
  61
  62
  63 Beagle Bone Black (BBB) setup
  64 -----------------------------
  65
  66 1. Setup tftp env variables:
  67    *  select desired eth device - 'ethact' variable ["ethact=cpsw"]
  68       (use "bdinfo" to check current setting)
  69    *  setup "serverip" and "ipaddr" variables
  70    *  set "loadaddr" as a fixed buffer where incoming data is placed
  71       ["loadaddr=0x81000000"]
  72
  73 #########
  74 # BONUS #
  75 #########
  76 It is possible to use USB interface to emulate ETH connection by setting
  77 "ethact=usb_ether". In this way one can have very fast DFU transfer via USB.
  78
  79 For 33MiB test image the transfer rate was 1MiB/s for ETH over USB and 200KiB/s
  80 for pure DFU USB transfer.
  81
  82 2. Setup update_tftp variables:
  83    *  set "updatefile" - the file name to be downloaded via TFTP (stored on
  84       the HOST at e.g. /srv/tftp)
  85
  86 3. If required, to update firmware on boot, put the "dfu tftp 0 mmc 0" in the
  87     "preboot" env variable. Otherwise use this command from u-boot prompt.
  88
  89 4. Inspect "dfu" specific variables:
  90    * "dfu_alt_info" - information about available DFU entities
  91    * "dfu_bufsiz"   - variable to set buffer size [in bytes] - when it is not
  92                     possible to set large enough default buffer (8 MiB @ BBB)
  93
  94
  95
  96 FIT image format for download
  97 -----------------------------
  98
  99 To create FIT image for download one should follow the update tftp README file
 100 (./doc/README.update) with one notable difference:
 101
 102 The original snippet of ./doc/uImage.FIT/update_uboot.its
 103
 104         images {
 105                 update@1 {
 106                         description = "U-Boot binary";
 107
 108 should look like
 109
 110         images {
 111                 u-boot.bin@1 {
 112                         description = "U-Boot binary";
 113
 114 where "u-boot.bin" is the DFU entity name to be stored.
 115
 116
 117
 118 To do
 119 -----
 120
 121 * Extend dfu-util command to support TFTP based transfers
 122 * Upload support (via TFTP)