blob: bf4379279e20fb35a8254516eefdf9ce96d52a3d [file] [log] [blame]
Bartlomiej Sieka4bae9092008-10-01 15:26:31 +02001Automatic software update from a TFTP server
2============================================
3
4Overview
5--------
6
7This feature allows to automatically store software updates present on a TFTP
8server in NOR Flash. In more detail: a TFTP transfer of a file given in
9environment variable 'updatefile' from server 'serverip' is attempted during
10boot. The update file should be a FIT file, and can contain one or more
11updates. Each update in the update file has an address in NOR Flash where it
12should be placed, updates are also protected with a SHA-1 checksum. If the
13TFTP transfer is successful, the hash of each update is verified, and if the
14verification is positive, the update is stored in Flash.
15
16The auto-update feature is enabled by the CONFIG_UPDATE_TFTP macro:
17
18#define CONFIG_UPDATE_TFTP 1
19
20
21Note that when enabling auto-update, Flash support must be turned on. Also,
22one must enable FIT and LIBFDT support:
23
24#define CONFIG_FIT 1
25#define CONFIG_OF_LIBFDT 1
26
27The auto-update feature uses the following configuration knobs:
28
29- CONFIG_UPDATE_LOAD_ADDR
30
31 Normally, TFTP transfer of the update file is done to the address specified
32 in environment variable 'loadaddr'. If this variable is not present, the
33 transfer is made to the address given in CONFIG_UPDATE_LOAD_ADDR (0x100000
34 by default).
35
36- CONFIG_UPDATE_TFTP_CNT_MAX
37 CONFIG_UPDATE_TFTP_MSEC_MAX
38
39 These knobs control the timeouts during initial connection to the TFTP
40 server. Since a transfer is attempted during each boot, it is undesirable to
41 have a long delay when a TFTP server is not present.
Bartlomiej Sieka7c84fe62008-10-30 23:22:04 +010042 CONFIG_UPDATE_TFTP_MSEC_MAX specifies the number of milliseconds to wait for
43 the server to respond to initial connection, and CONFIG_UPDATE_TFTP_CNT_MAX
Bartlomiej Sieka4bae9092008-10-01 15:26:31 +020044 gives the number of such connection retries. CONFIG_UPDATE_TFTP_CNT_MAX must
45 be non-negative and is 0 by default, CONFIG_UPDATE_TFTP_MSEC_MAX must be
Bartlomiej Sieka7c84fe62008-10-30 23:22:04 +010046 positive and is 100 by default.
Bartlomiej Sieka4bae9092008-10-01 15:26:31 +020047
48Since the update file is in FIT format, it is created from an *.its file using
49the mkimage tool. dtc tool with support for binary includes, e.g. in version
501.2.0 or later, must also be available on the system where the update file is
51to be prepared. Refer to the doc/uImage.FIT/ directory for more details on FIT
52images.
53
Bartlomiej Sieka4bae9092008-10-01 15:26:31 +020054
55Example .its files
56------------------
57
58- doc/uImage.FIT/update_uboot.its
59
60 A simple example that can be used to create an update file for automatically
61 replacing U-Boot image on a system.
62
63 Assuming that an U-Boot image u-boot.bin is present in the current working
64 directory, and that the address given in the 'load' property in the
65 'update_uboot.its' file is where the U-Boot is stored in Flash, the
66 following command will create the actual update file 'update_uboot.itb':
67
68 mkimage -f update_uboot.its update_uboot.itb
69
70 Place 'update_uboot.itb' on a TFTP server, for example as
71 '/tftpboot/update_uboot.itb', and set the 'updatefile' variable
72 appropriately, for example in the U-Boot prompt:
73
74 setenv updatefile /tftpboot/update_uboot.itb
75 saveenv
76
77 Now, when the system boots up and the update TFTP server specified in the
78 'serverip' environment variable is accessible, the new U-Boot image will be
79 automatically stored in Flash.
80
81 NOTE: do make sure that the 'u-boot.bin' image used to create the update
82 file is a good, working image. Also make sure that the address in Flash
83 where the update will be placed is correct. Making mistake here and
84 attempting the auto-update can render the system unusable.
85
86- doc/uImage.FIT/update3.its
87
88 An example containing three updates. It can be used to update Linux kernel,
89 ramdisk and FDT blob stored in Flash. The procedure for preparing the update
90 file is similar to the example above.
Lukasz Majewski5a608722015-08-24 00:21:42 +020091
92TFTP update via DFU
93-------------------
94
95- It is now possible to update firmware (bootloader, kernel, rootfs, etc.) via
96 TFTP by using DFU (Device Firmware Upgrade). More information can be found in
97 ./doc/README.dfutftp documentation entry.