OpenWrt sysupgrade support

sysupgrade is an OpenWrt invention that allows the rootfs to be updated to another firmware.

The sysupgrade script for the Gateworks products provides:

  • the /sbin/sysupgrade script on the target will flash the kernel/rootfs contained in a specified image
  • the image contents will be validated via an md5 checksum in the image header
  • the kernel and rootfs will be updated (squashfs+jffs2, jffs2 supported, or ubi)
  • standard system config files will be retained (saved, then restored) (unless the -n cmdline option is provided)
  • the -c command-line argument will save all files on the overlay filesystem

A standard make in the OpenWrt buildroot tree will create a sysupgrade image for your target by default named:

  • avila/cambria/laguna: bin/<target>/*-sysupgrade.bin.
  • ventana: bin/imx6/*-squashfs-nand_*.ubi

You can find more information about sysupgrade on the OpenWrt wiki here

Special Note

OpenWrt 'sysupgrade' only updates the root/boot filesystem. If you want to update the SPL, bootloader, or GSC firmware you have to perform those steps outside of sysupgrade.

Read more here #other

Sysupgrade via command line


  • Upgrade a 256MB flash device:
    cd /tmp
    sysupgrade -v gateworks-imx6-ventana-squashfs-nand_normal.ubi
  • from a URL:
    sysupgrade -v

Using LuCI Web-Admin

To perform a sysupgrade using the OpenWrt WebGUI, please use an ubi file, such as ventana-owrt-14.08-normal.ubi

Go to the top System tab, then the lower tab should be selected as Backup/Flash? Firmware.

Under 'Flash new firmware image' please select the ubi from the location on the desktop PC.

In the background, this is what is happening on the serial console

Switching to ramdisk...
[  447.449487] UBIFS: background thread "ubifs_bgt0_0" stops
[  447.519016] UBIFS: un-mount UBI device 0, volume 0
[  447.585743] UBI: detaching mtd2 from ubi0
[  447.591108] UBI: mtd2 is detached from ubi0
ubiformat: mtd2 (nand), size 250609664 bytes (239.0 MiB), 1912 eraseblocks of 131072 bytes (128.0 KiB), min. I/O size 2048 bytes
libscan: scanning eraseblock 1911 -- 100 % complete
ubiformat: 1912 eraseblocks have valid erase counter, mean value is 1
ubiformat: flashing eraseblock 154 -- 100 % complete
ubiformat: formatting eraseblo[  467.802383] UBI: attaching mtd2 to ubi0
ubiformat: formatting eraseblock 1911 -- 100 % complete
[  468.505882] UBI: scanning is finished
[  468.525333] UBI: volume 0 ("rootfs") re-sized from 153 to 1868 LEBs
[  468.532619] UBI: attached mtd2 (name "rootfs", size 239 MiB) to ubi0
[  468.539101] UBI: PEB size: 131072 bytes (128 KiB), LEB size: 126976 bytes
[  468.545937] UBI: min./max. I/O unit sizes: 2048/2048, sub-page size 2048
[  468.552783] UBI: VID header offset: 2048 (aligned 2048), data offset: 4096
[  468.559702] UBI: good PEBs: 1912, bad PEBs: 0, corrupted PEBs: 0
[  468.565719] UBI: user volume: 1, internal volumes: 1, max. volumes count: 128
[  468.572885] UBI: max/mean erase counter: 4/2, WL threshold: 4096, image sequence number: 250308913
[  468.581878] UBI: available PEBs: 0, total reserved PEBs: 1912, PEBs reserved for bad PEB handling: 40
[  468.591156] UBI: background thread "ubi_bgt0d" started, PID 4603
UBI device number 0, total 1912 LEBs (242778112 bytes, 231.5 MiB), available 0 LEBs (0 bytes), LEB size 126976 bytes (124.0 KiB)
[  468.666681] UBIFS: background thread "ubifs_bgt0_0" started, PID 4621
[  468.686194] UBIFS: start fixing up free space
[  469.759179] UBIFS: free space fixup complete
[  469.782548] UBIFS: mounted UBI device 0, volume 0, name "rootfs"
[  469.788572] UBIFS: LEB size: 126976 bytes (124 KiB), min./max. I/O unit sizes: 2048 bytes/2048 bytes
[  469.797786] UBIFS: FS size: 235794432 bytes (224 MiB, 1857 LEBs), journal size 9023488 bytes (8 MiB, 72 LEBs)
[  469.807805] UBIFS: reserved for root: 0 bytes (0 KiB)
[  469.812924] UBIFS: media format: w4/r0 (latest is w4/r0), UUID 58020D53-74F0-4A4C-83AA-B2FB6B08508F, small LPT model
[  469.877200] UBIFS: un-mount UBI device 0, volume 0
[  469.882090] UBIFS: background thread "ubifs_bgt0_0" stops
sysupgrade successful
[  469.904545] imx2-wdt 20bc000.wdog: Device shutdown: Expect reboot!
[  469.910875] reboot: Restarting system

Product Family Notes


If wanting to use sysupgrade to upgrade from 14.08 to 16.02 a bug in sysupgrade will cause it to not preserve configuration settings. This bug is only triggered if moving from a single partition ubifs (14.08) to a dual-partition squashfs+ubifs overlay (in 16.02).

If you wish to upgrade from 14.08 to 16.02 'and' preserve configuration please do the following to fix your sysupgrade script on 14.08 prior to using it:

sed -i -e "s~.*if ! mount -t ubifs /dev/\$ubivol /tmp/new_root; then.*~if ! mount -t ubifs ubi0:rootfs_data /tmp/new_root; then~" /lib/upgrade/


If you are using sysupgrade on an Avila family product you must use the bootloader that sets the machine-type to the unique avila type of 526 instead of the IXDP425 machine-type of 245. For historical reasons the Avila boards are shipped with the bootloader that tells the kernel its an IXDP425 in which case only the 'openwrt-avila-zImage' which ignores the bootloader's machine-type will work and the generic openwrt-ixp4xx-generic-zImage which relies on a properly set machine-type will not work. Alternatively you could generate a sysupgrade image comprised of the openwrt-avila-zImage. You can find rb-526 here

Other Upgrade Areas - Bootloader, GSC, etc

You could use a script from /etc/rc.local or /etc/init.d that checks version details and updates if necessary, or on OpenWrt you could create a package that installs a script into /etc/uci-defaults/ as those scripts are executed and removed once successfully executed (you can see examples by looking at the files placed in the default firmware at 'build_dir/target-arm_cortex-a9*/root-imx6/etc/uci-defaults/').

In order to check the current versions of the SPL and bootloader you can look at the strings that come from the 'uboot' mtd partition:

root@ventana:~# cat /proc/mtd 
dev:    size   erasesize  name
mtd0: 01000000 00020000 "uboot"
mtd1: 00100000 00020000 "env"
mtd2: 0ef00000 00020000 "rootfs"
root@ventana:~# strings /dev/mtd0 | grep ^U-Boot
U-Boot SPL 2015.04-g3126d82 (Apr 29 2016 - 11:03:42)
U-Boot 2015.04-g3126d82 for gw_v
U-Boot SPL 2015.04-g3126d82 (Apr 29 2016 - 11:03:42)
U-Boot 2015.04-g3126d82 for gw_v
U-Boot 2015.04-00147-g19f901e-di
U-Boot BUG at %s:%d!
U-Boot 2015.04-00147-g19f901e-dirty (May 24 2017 - 13:47:43)

To update the SPL you use the kobs-ng application as described here: ventana/bootloader

To update the U-Boot bootloader you can use the various 'nand' commands as described here: ventana/bootloader

In order to check the current version of the GSC firmware you can look at /sys/bus/i2c/devices/0-0020/fw_version:

root@ventana:~# cat /sys/bus/i2c/devices/0-0020/fw_version 

To update the GSC firmware you use the 'gsc_update' application located here: GSC Wiki Page

Note that power loss during any of these updates would more than likely render a board unbootable.

Last modified 5 weeks ago Last modified on 05/26/17 15:46:10

Attachments (2)

Download all attachments as: .zip