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>
diff --git a/doc/README.update b/doc/README.update
new file mode 100644
index 0000000..a476002
--- /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 0000000..285cf73
--- /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 0000000..e0d27ea
--- /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";
+ };
+ };
+ };
+};