[[PageOutline]]

= Updating Venice Firmware / Software

This page is all about updating / flashing firmware / software onto a Venice SBC. 

The various components of the 'firmware' on a Venice board which you may want to update from time to time are (lowest level components listed first):
- GSC firmware
- SPL
- Linux device-tree
- U-Boot bootloader
- Linux kernel
- root filesystem

Some components above you can update individually in Linux using {{{dd}}} or in U-Boot using {{{mmc write}}} taking care to place them at the right offset.

= Pre-Built Firmware
[wiki:venice/bsp#images Venice Pre-Built Firmware / Software]

JTAG binary images
 - flash with Gateworks JTAG dongle on a Linux hsot
 - see http://trac.gateworks.com/wiki/jtag_instructions
 - firmware-venice-imx8mm.bin
                       - JTAG image of first 16MiB of Flash containing:
                         partition table SPL, U-Boot, ATF, DDR firmware,
                         device-trees and default U-Boot env.
                         Flash with JTAG if recovering a board from an
                         unknown state.
 - venice-imx8mm-u-boot_spl.bin
 - venice-imx8mn-u-boot_spl.bin
                       - JTAG image of SPL, U-Boot, ATF, DDR firmware and DTBs
                         (does not modify partition table or U-Boot env)
 - gsc_7000_v57.txt    - Latest GSC firmware release for GW7000 SoM used on all
                         GW7xxx product.

Disk Images (Update via Bootloader gzwrite - contains boot firmware + OS):
 - see http://trac.gateworks.com/wiki/venice/firmware
 - focal-venice-imx8mm.img.gz - for IMX8M Mini
 - focal-venice-imx8mn.img.gz - for IMX8M Nano

[=#firmware-version]
= Firmware Versioning

You can determine the firmware version of various portions of the firmware by looking for banners on the serial console. For example:
{{{#!bash
U-Boot SPL 2020.04-g0a0109fcfb (Oct 07 2020 - 19:30:09 +0000)
GSC     : v57 0x4d20 RST:VIN Thermal Protection Enabled
Model   : GW7301-00-B1B
...
U-Boot 2020.04-g0a0109fcfb (Oct 07 2020 - 19:30:09 +0000), Build: jenkins-venice-bsp-24
...
[    0.000000] Linux version 5.4.45-g43e409dc8906 (jenkins@bionic_builder) (gcc version 8.4.0 (Buildroot 2020.05.2-109-g32cec2af36)) #1 SMP Wed Oct 7 18:43:20 UTC 2020
...
Ubuntu 20.04.1 LTS focal-venice ttymxc1

Gateworks-Ubuntu-gateworks-g65dac90 Tue Oct  6 23:54:49 UTC 2020
...
}}}


The above output shows you:
 * Secondary Program Loader (SPL) GIT revision and build date
 * GSC firmware version
 * U-Boot GIT revision and build date
 * Linux kernel version, GIT revision, build date and build source
 * Ubuntu root filesystem version and GIT revision of the Gateworks [https://github.com/gateworks/ubuntu-rootfs ubuntu-rootfs.sh] that created it (use {{{dpkg -l | grep "^ii"}}} to see what packages and versions are installed


[=#firmware-update]
= Updating Firmware
This section provides instructions for updating both GSC firmware as well as boot device firmware.

There are two methods for updating firmware:
 * on a live board using Serial Console and Ethernet
 * using a GW16099 JTAG dongle (see [#jtag below])

The various items that can be easily updated:
 * GSC Firmware - Can be updated via JTAG or at runtime - see [#gsc below])
 * Boot Firmware (Everything up to and including the Bootloader)
 * Root Filesystem (Operating System)

[=#jtag]
== JTAG Programming
The Gateworks JTAG adapter (GW16099) is available in the Venice Dev Kit as well as on the Gateworks web store [http://shop.gateworks.com/index.php?route=product/category&path=70_80 here]

All Venice boards have a 10-pin JTAG header which provides:
 * JTAG Programming for embedded emmc flash - see [wiki:jtag_instructions here] for instructions
 * Serial Console access via UART2 (/dev/ttymxc1)

Please Note:
 * Linux software is supported for programming Venice (jtag_usbv4 required). Windows is not supported. (serial console through Windows does work).
 * JTAG Programming of eMMC is supported by [http://dev.gateworks.com/jtag/jtag_usbv4 jtag_usbv4] - see [wiki:jtag_instructions here]. Due to this being a slow process for large eMMC devices it is recommended to program boot firmware via JTAG if you brick your board and use the bootloader to install firmware when possible for speed (see [#serial-ethernet] below).
 * JTAG Programming of the GSC firmware is supported by [http://dev.gateworks.com/jtag/jtag_usbv4 jtag_usbv4] - see [#jtag-gsc below]


[=#serial-ethernet]
== Update Firmware via Serial Console and Ethernet from Bootloader
The quickest and easiest way to update your firmware is via Serial Console and Ethernet. You can do this either in the U-Boot bootloader (recommended) or within a Linux OS.

If updating firmware via !Bootloader/Serial/Ethernet (recommended for speed) you need to setup a TFTP server to host the files for transfer. Alternatively you could load firmware files from removable storage (microSD, or USB Mass Storage for example) however you will need to deviate from the examples below. For details on setting up a TFTP server see [wiki:tftpserver here].

The following instructions assume your board target IP address is 192.168.1.1 and you have a TFTP server at 192.168.1.146. Adjust environment according to your network via 'setenv ipaddr <ipaddr>' and 'setenv serverip <serverip>'.

The methods you use to update the firmware depends on what specifically you are trying to update.


==== Update Entire Firmware (recommended)
Update the entire device from a Compressed Disk Image. This image includes the partition table, boot firmware, bootloader environment, as well as entire OS and kernel:

Complete Compressed Disk Images are available for download here: [http://dev.gateworks.com/venice/images/]

Procedure:
 * Via U-Boot:
{{{#!bash
#First, setup the IP and server IP as described above (example IPs below)
setenv ipaddr 192.168.1.1
setenv serverip 192.168.1.2 
# setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
setenv autoload 0; bootp  # use dhcp for network config but do not fetch a file
# choose the device to update
setenv dev 2 # sets MMC device to be flashed - see mmc list
# set your image
setenv image focal-venice.img.gz # or whatever filename is used, with any tftp server directories in front of the filename
# update
run update_all
}}}
  - This is what the update_all script does if your curious:
{{{#!bash
update_all=tftpboot ${loadaddr} ${image} && gzwrite mmc ${dev} ${loadaddr} ${filesize}
}}}
 * Via Linux (when the volume is unmounted):
{{{#!bash
# fetch your file
cd /tmp
wget http://dev.gateworks.com/venice/images/focal-venice.img.gz
# uncompress and write to the emmc device
zcat focal-venice.img.gz | dd of=/dev/mmcblk0 bs=4M
}}}


==== Updating just the boot firmware
Updating the [wiki:venice/boot 'Boot firmware'] via this method includes the SPL, U-Boot, the device-tree, and the ATF. The method here specifically does not update the disk partition table at the beginning of the boot device as that really has nothing to do with the boot firmware. This method also does not destroy any current U-Boot environment.

Note that the IMX8 BOOT ROM fetches code starting at a 33K offset (in order to reserve everything below that for things like disk partition tables).

The latest pre-built Bootloader images for Venice are available for download here: 
 - [http://dev.gateworks.com/venice/boot_firmware/venice-imx8mm-flash.bin venice-imx8mm-flash.bin] for IMX8M Mini boards
 - [http://dev.gateworks.com/venice/boot_firmware/venice-imx8mn-flash.bin venice-imx8mn-flash.bin] for IMX8M Nano boards

Procedure: **(Make sure you use the right variant per your processor imx8mm/imx8mn and the correct device for the emmc device)**
 * Via U-Boot:
  - for IMX8M Mini board variants:
{{{#!bash
# setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
setenv autoload 0; bootp  # use dhcp for network config but do not fetch a file
# choose the device to update
setenv dev 2 # sets MMC device to be flashed - see mmc list
# set your image
setenv image venice-imx8mm-flash.bin # with any tftp server directories in front of the filename
# update
run update_firmware
}}}
   - This is what the update_firmware script does if your curious:
{{{#!bash
update_firmware=tftpboot $loadaddr $image && setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 && mmc dev $dev && mmc write $loadaddr 0x42 $blkcnt
}}}
  - for IMX8M Nano board variants:
{{{#!bash
# setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
setenv autoload 0; bootp  # use dhcp for network config but do not fetch a file
# choose the device to update
setenv dev 2 # sets MMC device to be flashed - see mmc list
# set your image
setenv image venice-imx8mn-flash.bin # with any tftp server directories in front of the filename
# update
run update_firmware
}}}
   - This is what the update_firmware script does if your curious:
{{{#!bash
update_firmware=tftpboot $loadaddr $image && setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 && mmc dev $dev && mmc write $loadaddr 0x40 $blkcnt
}}}
 * Via Linux:
  - for IMX8M Mini board variants:
{{{#!bash
# fetch your file
cd /tmp
wget http://dev.gateworks.com/venice/boot_firmware/venice-imx8mm-flash.bin
# uncompress and write to the emmc device to 33K offset
dd if=venice-imx8mm-flash.bin of=/dev/mmcblk2 bs=1K seek=33
}}}
  - for IMX8M Nano board variants:
{{{#!bash
# fetch your file
cd /tmp
wget http://dev.gateworks.com/venice/boot_firmware/venice-imx8mn-flash.bin
# uncompress and write to the emmc device to 32K offset
dd if=venice-imx8mn-flash.bin of=/dev/mmcblk2 bs=1K seek=32
}}}


==== Updating just the root filesystem
Updating the root filesystem from a 'compressed filesystem image' is easily done in U-Boot or Linux.

Note that Gateworks does not host any pre-built filesystem images on our servers but the Venice BSP builds one for you from a downloaded rootfs tarball when you build the {{{ubuntu-image}}} target. The file is in the bsp directory as {{{focal-venice.ext4}}} and can be compressed with {{{gzip focal-venice.ext4}}}


Procedure:
 * Via U-Boot:
{{{#!bash
# setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
setenv autoload 0; bootp  # use dhcp for network config but do not fetch a file
# choose the device to update
setenv dev 2 # sets MMC device to be flashed - see mmc list
# set your image
setenv image rootfs.ext4.gz # with any tftp server directories in front of the filename
# update
run update_rootfs
}}}
  - This is what the update_rootfs script does if your curious:
{{{#!bash
update_rootfs=tftpboot $loadaddr $image && gzwrite mmc $dev $loadaddr $filesize 100000 1000000
}}}
  - Note gzwrite is used so the filesystem image must be compressed with 'gzip' (otherwise you could use mmc write manually). The data (ie type of filesystem or content ) does not matter here
  - Note the flash offset is 0x1000000 blocks which is 16MiB
  - Note the {{{dev}}} and {{{image}}} env variables are used by this script
 * Via Linux:
{{{#!bash
# fetch your file
cd /tmp
wget http://sever/rootfs.ext4.gz
# uncompress and write to the emmc device to 16M offset
dd if=venice-imx8mm-flash.bin of=/dev/mmcblk0 bs=1M seek=16
}}}


=== TFTP Error Troubleshooting
There are many reasons why TFTP may fail including:
 * firewall issue keeping your TFTP server for being accessible (make sure you can ping it!)
 * invalid network configuration (netmask, gatewayip, ipaddr, serverip) - again make sure you can ping it!
 * 'TFTP error: trying to overwrite reserved memory...' - indicates you are trying to transfer a file that is larger than system memory. You will need to split the file into chunks and flash them individually at the right offsets


= Updating GSC firmware
The GSC firmware is updated via the {{{gsc_update}}} application running under Linux as described at on the [wiki:gsc#firmware gsc wiki]. While it takes only a few seconds to update there is no recovery for a failed update. Gateworks has ensured that this update is robust but can not survive a power-cut or kernel crash in the middle of the update. Updates to the GSC firmware are expected to be rare.


[=#jtag-gsc]
=== Update GSC Firmware via JTAG ===
To update the GSC firmware via JTAG download the {{{jtag_usbv4}}} application on a Linux x86 host from [http://dev.gateworks.com/jtag/jtag_usbv4 here] and execute as follows:
{{{#!bash
./jtag_usbv4 -m gsc_7000_v57.txt
}}}

Note that the {{{ftdi_sio}}} kernel module must not be loaded (sudo rmmod ftdi_sio) and you may need to run this command as root by pre-pending a sudo depending on the configuration of your linux host.

For more details please see:
 * [wiki:jtag Gateworks JTAG wiki page]