projects / u-boot.git / blame
| Commit | Line | Data |
|---|---|---|
| 4bae9090 BS |
1 | Automatic software update from a TFTP server |
| 2 | ============================================ | |
| 3 | ||
| 4 | Overview | |
| 5 | -------- | |
| 6 | ||
| 7 | This feature allows to automatically store software updates present on a TFTP | |
| 8 | server in NOR Flash. In more detail: a TFTP transfer of a file given in | |
| 9 | environment variable 'updatefile' from server 'serverip' is attempted during | |
| 10 | boot. The update file should be a FIT file, and can contain one or more | |
| 11 | updates. Each update in the update file has an address in NOR Flash where it | |
| 12 | should be placed, updates are also protected with a SHA-1 checksum. If the | |
| 13 | TFTP transfer is successful, the hash of each update is verified, and if the | |
| 14 | verification is positive, the update is stored in Flash. | |
| 15 | ||
| 16 | The auto-update feature is enabled by the CONFIG_UPDATE_TFTP macro: | |
| 17 | ||
| 18 | #define CONFIG_UPDATE_TFTP 1 | |
| 19 | ||
| 20 | ||
| 21 | Note that when enabling auto-update, Flash support must be turned on. Also, | |
| 22 | one must enable FIT and LIBFDT support: | |
| 23 | ||
| 24 | #define CONFIG_FIT 1 | |
| 25 | #define CONFIG_OF_LIBFDT 1 | |
| 26 | ||
| 27 | The 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. | |
| 7c84fe6a BS |
42 | 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 | |
| 4bae9090 BS |
44 | 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 | |
| 7c84fe6a | 46 | positive and is 100 by default. |
| 4bae9090 BS |
47 | |
| 48 | Since the update file is in FIT format, it is created from an *.its file using | |
| 49 | the mkimage tool. dtc tool with support for binary includes, e.g. in version | |
| 50 | 1.2.0 or later, must also be available on the system where the update file is | |
| 51 | to be prepared. Refer to the doc/uImage.FIT/ directory for more details on FIT | |
| 52 | images. | |
| 53 | ||
| 3f42dc87 | 54 | This mechanism can be also triggered by the command "fitupd". |
| 7130a579 AP |
55 | If an optional, non-zero address is provided as argument, the TFTP transfer |
| 56 | is skipped and the image at this address is used. | |
| 57 | The fitupd command is enabled by CONFIG_CMD_FITUPD. | |
| 58 | ||
| 4bae9090 BS |
59 | |
| 60 | Example .its files | |
| 61 | ------------------ | |
| 62 | ||
| 63 | - doc/uImage.FIT/update_uboot.its | |
| 64 | ||
| 65 | A simple example that can be used to create an update file for automatically | |
| 66 | replacing U-Boot image on a system. | |
| 67 | ||
| 68 | Assuming that an U-Boot image u-boot.bin is present in the current working | |
| 69 | directory, and that the address given in the 'load' property in the | |
| 70 | 'update_uboot.its' file is where the U-Boot is stored in Flash, the | |
| 71 | following command will create the actual update file 'update_uboot.itb': | |
| 72 | ||
| 73 | mkimage -f update_uboot.its update_uboot.itb | |
| 74 | ||
| 75 | Place 'update_uboot.itb' on a TFTP server, for example as | |
| 76 | '/tftpboot/update_uboot.itb', and set the 'updatefile' variable | |
| 77 | appropriately, for example in the U-Boot prompt: | |
| 78 | ||
| 79 | setenv updatefile /tftpboot/update_uboot.itb | |
| 80 | saveenv | |
| 81 | ||
| 82 | Now, when the system boots up and the update TFTP server specified in the | |
| 83 | 'serverip' environment variable is accessible, the new U-Boot image will be | |
| 84 | automatically stored in Flash. | |
| 85 | ||
| 86 | NOTE: do make sure that the 'u-boot.bin' image used to create the update | |
| 87 | file is a good, working image. Also make sure that the address in Flash | |
| 88 | where the update will be placed is correct. Making mistake here and | |
| 89 | attempting the auto-update can render the system unusable. | |
| 90 | ||
| 91 | - doc/uImage.FIT/update3.its | |
| 92 | ||
| 93 | An example containing three updates. It can be used to update Linux kernel, | |
| 94 | ramdisk and FDT blob stored in Flash. The procedure for preparing the update | |
| 95 | file is similar to the example above. | |
| 5a608727 LM |
96 | |
| 97 | TFTP update via DFU | |
| 98 | ------------------- | |
| 99 | ||
| 100 | - It is now possible to update firmware (bootloader, kernel, rootfs, etc.) via | |
| 101 | TFTP by using DFU (Device Firmware Upgrade). More information can be found in | |
| 102 | ./doc/README.dfutftp documentation entry. |