xref: /openbmc/u-boot/doc/README.dfutftp (revision b432b1eb)
1#
2#  Copyright (C) 2015
3#
4#  Lukasz Majewski <l.majewski@majess.pl>
5#
6#
7# SPDX-License-Identifier:	GPL-2.0+
8
9Device Firmware Upgrade (DFU) - extension to use TFTP
10=====================================================
11
12Why?
13----
14
15* Update TFTP (CONFIG_UPDATE_TFTP) only supports writing
16code to NAND memory via TFTP.
17* DFU supports writing data to the variety of mediums (NAND,
18eMMC, SD, partitions, RAM, etc) via USB.
19
20Combination of both solves their shortcomings!
21
22
23Overview
24--------
25
26This document briefly describes how to use DFU for
27upgrading firmware (e.g. kernel, u-boot, rootfs, etc.)
28via TFTP protocol.
29
30By using Ethernet (TFTP protocol to be precise) it is
31possible to overcome the major problem of USB based DFU -
32the relatively low transfer speed for large files.
33This was caused by DFU standard, which imposed utilization
34of only EP0 for transfer. By using Ethernet we can circumvent
35this shortcoming.
36
37Beagle Bone Black rev. C (BBB) powered by TI's am335x CPU has
38been used as a demo board.
39
40To utilize this feature, one needs to first enable support
41for USB based DFU (CONFIG_DFU_*) and DFU TFTP update
42(CONFIG_DFU_TFTP) described in ./doc/README.update.
43
44The "dfu" command has been extended to support transfer via TFTP - one
45needs to type for example "dfu tftp 0 mmc 0"
46
47This feature does not depend on "fitupd" command enabled.
48
49As of this writing (SHA1:8d77576371381ade83de475bb639949b44941e8c v2015.10-rc2)
50the update.c code is not enabled (CONFIG_UPDATE_TFTP) by any board in the
51contemporary u-boot tree.
52
53
54Environment variables
55---------------------
56
57The "dfu tftp" command can be used in the "preboot" environment variable
58(when it is enabled by defining CONFIG_PREBOOT).
59This is the preferable way of using this command in the early boot stage
60as opposed to legacy update_tftp() function invocation.
61
62
63Beagle Bone Black (BBB) setup
64-----------------------------
65
661. 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#########
76It 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
79For 33MiB test image the transfer rate was 1MiB/s for ETH over USB and 200KiB/s
80for pure DFU USB transfer.
81
822. 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
863. 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
894. 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
96FIT image format for download
97-----------------------------
98
99To create FIT image for download one should follow the update tftp README file
100(./doc/README.update) with one notable difference:
101
102The original snippet of ./doc/uImage.FIT/update_uboot.its
103
104	images {
105		update@1 {
106			description = "U-Boot binary";
107
108should look like
109
110	images {
111		u-boot.bin@1 {
112			description = "U-Boot binary";
113
114where "u-boot.bin" is the DFU entity name to be stored.
115
116
117
118To do
119-----
120
121* Extend dfu-util command to support TFTP based transfers
122* Upload support (via TFTP)
123