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