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