[[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.

[=#images]
= Pre-Built Images

Various Pre-built images can be found on http://dev.gateworks.com/venice including:
 * '''Compressed Disk Images''': (*.img.gz files) OS Images (everything but boot firmware)
  - [http://dev.gateworks.com/venice/images/ubuntu-venice.img.gz ubuntu-venice.img.gz] - Gateworks Ubuntu based OS details are available [wiki:venice/ubuntu here]
  - [http://dev.gateworks.com/venice/images/openwrt-venice.img.gz openwrt-venice.img.gz] - Gateworks OpenWrt OS details are available [wiki:OpenWrt here]
  * '''[#disk-images Install compressed disk images via U-Boot or Linux using instructions here]'''
 * '''Gateworks System Controller Firmware''': (board specific gsc*.txt files)
  - [http://dev.gateworks.com/venice/images/gsc_7000.txt gsc_7000.txt] - for boards with a GW700x IMX8MM SOM module
  - [http://dev.gateworks.com/venice/images/gsc_7000.txt gsc_7020.txt] - for boards with a GW702x IMX8MP SOM module
  - [http://dev.gateworks.com/venice/images/gsc_7400.txt gsc_7400.txt] - for GW74xx IMX8MP boards
  * '''[wiki:gsc#firmware Install GSC firmware via JTAG or Linux via instructions here]'''
 * '''Boot Firmware''': (SOC specific) Everything up to the OS (SPL, ATF, U-Boot, U-Boot env)
  - For updating via U-Boot or Linux or booting via SDP (does not contain U-Boot env)
   * [http://dev.gateworks.com/venice/boot_firmware/venice-imx8mm-flash.bin venice-imx8mm-flash.bin] - for IMX8MM SOC
   * [http://dev.gateworks.com/venice/boot_firmware/venice-imx8mp-flash.bin venice-imx8mp-flash.bin] - for IMX8MP SOC
   - '''[#boot-firmware For updating via U-Boot or Linux see here]'''
   - '''[wiki:venice/SDP For booting over USB via the SDP protocol (helpful during bootloader development or customization) see here]'''
  - For updating via JTAG:
   * [http://dev.gateworks.com/venice/images/firmware-venice-imx8mm.bin firmware-venice-imx8mm.bin] - for IMX8MM SOC
   * [http://dev.gateworks.com/venice/images/firmware-venice-imx8mp.bin firmware-venice-imx8mp.bin] - for IMX8MP SOC
   - '''[wiki:jtag_instructions for details For JTAG programming instructions see here]'''
 * '''Venice Kernel Tarball''' useful for installing on top of root filesystem manually
  * [http://dev.gateworks.com/venice/kernel/linux-venice.tar.xz linux-venice.tar.xz] - Compressed TAR archive of pre-built Linux kernel

Gateworks System Controller files are 'board specific' meaning the file used depends on the baseboard or SOM model. Boot firmware images are 'SOC specific' meaning there is a specific one to match the SOC on your board - IMX8M Mini (imx8mm) vs IMX8M Nano (imx8mn) vs IMX8M Plus (imx8mp). Compressed Disk Images are written to the eMMC user partition which contains a disk partition table and the various OS partitions (assuming the boot firmware is booting from emmc boot0 or boot1 hardware partition).



[=#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 already-booting board using Serial Console and Ethernet via U-Boot or Linux booted from a ramdisk
 * using JTAG via a GW16099 JTAG dongle

[=#jtag]
== Updating Firmware via JTAG
The GSC firmware and eMMC boot firmware can be easily updated via JTAG. Technically you can also use JTAG to update any size or section of the eMMC in order to update an entire OS but you will find that for anything over about 32MiB using U-Boot and/or a Linux image with ramdisk will be much quicker.

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:
 * Only flash files intended for JTAG using the JTAG programmer and jtag_usbv4
 * 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]

=== Updating 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.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]


=== Updating eMMC boot firmware via JTAG
To flash an eMMC image via JTAG such as a boot firmware image:
{{{
sudo ./jtag_usbv4 –p firmware-venice-imx8mm.bin
}}}
 * You must use firmware appropriate for the SoC on your board:
  - GW730x-0x/GW720x-0x/GW710x-0x with an IMX8MM: [http://dev.gateworks.com/venice/images/firmware-venice-imx8mm.bin firmware-venice-imx8mm.bin]
  - GW740x with an IMX8MP: [http://dev.gateworks.com/venice/images/firmware-venice-imx8mp.bin firmware-venice-imx8mm.bin]


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

If updating via U-Boot you will need to setup a TFTP server to host the files for transfer or alternatively you could load firmware files from removable storage (microSD, or USB Mass Storage for example). For details on setting up a TFTP server see [wiki:tftpserver here]. Also note that 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


[=#disk-images]
=== Update OS via Compressed Disk Images
A compressed disk image is relatively easy to create and is easy to install on a running board via U-Boot or Linux running from a ramdisk. Assuming boot firmware is booting from another device or hardware partition (ie eMMC boot0 hardware partition) the compressed disk image contains only the disk partition table and OS filesystem partitions.

Note that Gateworks used to place boot firmware in the eMMC user partition meaning the compressed disk image would also include the boot firmware. This is now considered 'legacy' but to keep users from bricking boards that still have boot firmware on the eMMC user hardware partition the Gateworks Venice BSP still places imx8mm boot firmware in the compressed disk image.

==== Compressed disk image via U-Boot
A Compressed disk image can be installed from U-Boot as long as you can load it into memory (ie via ethernet/TFTP or removable storage):
 * using ethernet and a TFTP server using the 'update_all' script:
{{{#!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 ubuntu-venice.img.gz
# 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}
}}}
 * using a microSD:
{{{#!bash
# load image via microSD device and partition (use 'mmc list' and 'mmc part' to see a list)
load mmc 1:1 $loadaddr ubuntu-venice.img.gz && gzwrite mmc $dev $loadaddr $filesize
}}}
 * using a USB Mass Storage device:
{{{#!bash
usb start && load usb 0:1 $loadaddr ubuntu-venice.img.gz && gzwrite mmc $dev $loadaddr $filesize
}}}

==== Compressed disk image via Linux
A Compressed disk image can be installed from Linux as long as you can load it into memory (ie via network or removable storage) and do not have the flash device mounted (ie booted from a kernel+ramdisk rescue image):
{{{#!bash
# fetch your file
cd /tmp
wget http://dev.gateworks.com/venice/images/ubuntu-venice.img.gz
# uncompress and write to the emmc device
zcat ubuntu-venice.img.gz | dd of=/dev/mmcblk0 bs=4M
}}}



[=#boot-firmware]
=== Updating just the boot firmware via U-Boot or Linux
The boot firmware containing everything up to the OS (SOC specific SPL, ATF, and U-Boot) can be updated at runtime via U-Boot or Linux. This method does not update the boot firmware U-boot environment. Assuming your boot firmware is installed on the eMMC boot0 partition this does not affect the disk partition table or filesystems on the eMMC user partition.

'''Note that if you use the firmware for the wrong SOC or flash it at the wrong device, hardware partition or offset you will not be able to boot your board and will need to recover via JTAG using instructions [wiki:jtag_instructions]'''

The latest pre-built Bootloader images for Venice are available for download here: 
[http://dev.gateworks.com/venice/boot_firmware/]

'''It is important to use the correct file compatible with the SOC on your board''':
||= Board =||= SoC =||= Notes =||
|| GW710x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
|| GW720x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
|| GW730x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
|| GW7905-2x-* || i.MX8M Plus (aka IMX8MP) || use firmware with 'imx8mp' in the name ||
|| GW740x-*    || i.MX8M Plus (aka IMX8MP) || use firmware with 'imx8mp' in the name ||

You can tell what you are using by watching the board boot. For example consider the following U-Boot console messages:
{{{#!bash
U-Boot 2022.07-g1050480603 (Aug 19 2022 - 17:02:47 +0000), Build: jenkins-venice-bsp-122

CPU:   Freescale i.MX8MP[8] rev1.1 1600 MHz (running at 1200 MHz)
CPU:   Industrial temperature grade (-40C to 105C) at 28C
...
Hit any key to stop autoboot:  0 
u-boot=> print soc
soc=imx8mp
}}}
 - The above CPU banner shows 'i.MX8MP' which requires firmware with a 'imx8mp' in its name
 - Additionally the latest firmware images set the 'soc' U-Boot env variable to match the SoC you are using

Note that the eMMC hardware partition that is active on power-up must agree with the hardware partition you flash your boot firmware to and can be [wiki:MMC#emmc-partconf set via the eMMC PARTITION_CONFIG CSD register].


==== Boot firmware update via U-Boot
Updating the boot firmware via U-Boot is made easy by the 'update_firmware' U-Boot env script which takes care of determining the correct device, partition, and offset based on env variables set on boot:
{{{#!bash
# setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
bootp  # optional: use dhcp for network config
# set the tftp directory your image is in
setenv dir venice
# update
run update_firmware
}}}
 * Alternatively you can load the image from removable storage


==== Boot firmware update via Linux
Updating the boot firmware via Linux requires you to manually determine the correct device, hardware partition and offset:
 * for IMX8M Mini board variants:
  - with boot firmware in user hardware partition:
{{{#!bash
# write to the emmc device to 33K offset
dd if=venice-imx8mm-flash.bin of=/dev/mmcblk2 bs=1K seek=33
}}}
  - with boot firmware in boot0 hardware partition:
{{{#!bash
# write to the emmc device to 33K offset
dd if=venice-imx8mm-flash.bin of=/dev/mmcblk2boot0 bs=1K seek=33
}}}
 * for IMX8M Nano board variants:
  - with boot firmware in user hardware partition:
{{{#!bash
# write to the emmc device to 32K offset
dd if=venice-imx8mn-flash.bin of=/dev/mmcblk2 bs=1K seek=32
}}}
  - with boot firmware in boot0 hardware partition:
{{{#!bash
# write to the emmc device to 0K offset
dd if=venice-imx8mn-flash.bin of=/dev/mmcblk2boot0 bs=1K seek=0
}}}
 * for IMX8M Plus board variants:
  - with boot firmware in user hardware partition:
{{{#!bash
# write to the emmc device to 32K offset
dd if=venice-imx8mp-flash.bin of=/dev/mmcblk2 bs=1K seek=32
}}}
  - with boot firmware in boot0 hardware partition:
{{{#!bash
# write to the emmc device to 0K offset
dd if=venice-imx8mp-flash.bin of=/dev/mmcblk2boot0 bs=1K seek=0
}}}


[=#rootfs]
=== 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
}}}



[=#gsc-udpate]
=== Updating GSC firmware
The GSC firmware can be 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.



[=#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