README.update 3.9 KB

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