uboot/doc/README.update
<<
>>
Prefs
   1Automatic 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.
  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
  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
  46  positive and is 100 by default.
  47
  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
  54This mechanism can be also triggered by the command "fitupd".
  55If an optional, non-zero address is provided as argument, the TFTP transfer
  56is skipped and the image at this address is used.
  57The fitupd command is enabled by CONFIG_CMD_FITUPD.
  58
  59
  60Example .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.
  96
  97TFTP 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.
 103