diff options
author | Bartlomiej Sieka <tur@semihalf.com> | 2008-10-01 15:26:31 +0200 |
---|---|---|
committer | Wolfgang Denk <wd@denx.de> | 2008-10-18 21:54:00 +0200 |
commit | 4bae90904b69ce3deb9f7c334ef12ed74e18a275 (patch) | |
tree | 609ddd18652c6289cfd43dfd6447377bd3fb12fc /doc | |
parent | 3f0cf51dabacc2724731c5079a60ea989103bb8f (diff) |
Automatic software update from TFTP server
The auto-update feature allows to automatically download software updates
from a TFTP server and store them in Flash memory during boot. Updates are
contained in a FIT file and protected with SHA-1 checksum.
More detailed description can be found in doc/README.update.
Signed-off-by: Rafal Czubak <rcz@semihalf.com>
Signed-off-by: Bartlomiej Sieka <tur@semihalf.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README.update | 90 | ||||
-rw-r--r-- | doc/uImage.FIT/update3.its | 41 | ||||
-rw-r--r-- | doc/uImage.FIT/update_uboot.its | 21 |
3 files changed, 152 insertions, 0 deletions
diff --git a/doc/README.update b/doc/README.update new file mode 100644 index 0000000000..a4760025bf --- /dev/null +++ b/doc/README.update @@ -0,0 +1,90 @@ +Automatic software update from a TFTP server +============================================ + +Overview +-------- + +This feature allows to automatically store software updates present on a TFTP +server in NOR Flash. In more detail: a TFTP transfer of a file given in +environment variable 'updatefile' from server 'serverip' is attempted during +boot. The update file should be a FIT file, and can contain one or more +updates. Each update in the update file has an address in NOR Flash where it +should be placed, updates are also protected with a SHA-1 checksum. If the +TFTP transfer is successful, the hash of each update is verified, and if the +verification is positive, the update is stored in Flash. + +The auto-update feature is enabled by the CONFIG_UPDATE_TFTP macro: + +#define CONFIG_UPDATE_TFTP 1 + + +Note that when enabling auto-update, Flash support must be turned on. Also, +one must enable FIT and LIBFDT support: + +#define CONFIG_FIT 1 +#define CONFIG_OF_LIBFDT 1 + +The auto-update feature uses the following configuration knobs: + +- CONFIG_UPDATE_LOAD_ADDR + + Normally, TFTP transfer of the update file is done to the address specified + in environment variable 'loadaddr'. If this variable is not present, the + transfer is made to the address given in CONFIG_UPDATE_LOAD_ADDR (0x100000 + by default). + +- CONFIG_UPDATE_TFTP_CNT_MAX + CONFIG_UPDATE_TFTP_MSEC_MAX + + These knobs control the timeouts during initial connection to the TFTP + server. Since a transfer is attempted during each boot, it is undesirable to + have a long delay when a TFTP server is not present. + CONFIG_UPDATE_TFTP_MSEC_MAX specifies the number of seconds to wait for the + server to respond to initial connection, and CONFIG_UPDATE_TFTP_CNT_MAX + gives the number of such connection retries. CONFIG_UPDATE_TFTP_CNT_MAX must + be non-negative and is 0 by default, CONFIG_UPDATE_TFTP_MSEC_MAX must be + positive and is 1 by default. + +Since the update file is in FIT format, it is created from an *.its file using +the mkimage tool. dtc tool with support for binary includes, e.g. in version +1.2.0 or later, must also be available on the system where the update file is +to be prepared. Refer to the doc/uImage.FIT/ directory for more details on FIT +images. + + +Example .its files +------------------ + +- doc/uImage.FIT/update_uboot.its + + A simple example that can be used to create an update file for automatically + replacing U-Boot image on a system. + + Assuming that an U-Boot image u-boot.bin is present in the current working + directory, and that the address given in the 'load' property in the + 'update_uboot.its' file is where the U-Boot is stored in Flash, the + following command will create the actual update file 'update_uboot.itb': + + mkimage -f update_uboot.its update_uboot.itb + + Place 'update_uboot.itb' on a TFTP server, for example as + '/tftpboot/update_uboot.itb', and set the 'updatefile' variable + appropriately, for example in the U-Boot prompt: + + setenv updatefile /tftpboot/update_uboot.itb + saveenv + + Now, when the system boots up and the update TFTP server specified in the + 'serverip' environment variable is accessible, the new U-Boot image will be + automatically stored in Flash. + + NOTE: do make sure that the 'u-boot.bin' image used to create the update + file is a good, working image. Also make sure that the address in Flash + where the update will be placed is correct. Making mistake here and + attempting the auto-update can render the system unusable. + +- doc/uImage.FIT/update3.its + + An example containing three updates. It can be used to update Linux kernel, + ramdisk and FDT blob stored in Flash. The procedure for preparing the update + file is similar to the example above. diff --git a/doc/uImage.FIT/update3.its b/doc/uImage.FIT/update3.its new file mode 100644 index 0000000000..285cf73b4d --- /dev/null +++ b/doc/uImage.FIT/update3.its @@ -0,0 +1,41 @@ +/* + * Example Automatic software update file. + */ +/ { + description = "Automatic software updates: kernel, ramdisk, FDT"; + #address-cells = <1>; + + images { + update@1 { + description = "Linux kernel binary"; + data = /incbin/("./vmlinux.bin.gz"); + compression = "none"; + type = "firmware"; + load = <FF700000>; + hash@1 { + algo = "sha1"; + }; + }; + update@2 { + description = "Ramdisk image"; + data = /incbin/("./ramdisk_image.gz"); + compression = "none"; + type = "firmware"; + load = <FF8E0000>; + hash@1 { + algo = "sha1"; + }; + }; + + update@3 { + description = "FDT blob"; + data = /incbin/("./blob.fdt"); + compression = "none"; + type = "firmware"; + load = <FFAC0000>; + hash@1 { + algo = "sha1"; + }; + }; + }; +}; diff --git a/doc/uImage.FIT/update_uboot.its b/doc/uImage.FIT/update_uboot.its new file mode 100644 index 0000000000..e0d27eacc9 --- /dev/null +++ b/doc/uImage.FIT/update_uboot.its @@ -0,0 +1,21 @@ +/* + * Automatic software update for U-Boot + * Make sure the flashing addresses ('load' prop) is correct for your board! + */ +/ { + description = "Automatic U-Boot update"; + #address-cells = <1>; + + images { + update@1 { + description = "U-Boot binary"; + data = /incbin/("./u-boot.bin"); + compression = "none"; + type = "firmware"; + load = <FFFC0000>; + hash@1 { + algo = "sha1"; + }; + }; + }; +}; |