Changes between Initial Version and Version 1 of catalina/firmware

Timestamp:

04/28/2026 04:59:34 PM (42 hours ago)

Author:

Tim Harvey

Comment:

initial page

catalina/firmware

@@ +1 @@
+[[PageOutline]]
+
+= Updating Catalina Firmware / Software
+
+This page is all about updating / flashing firmware / software onto a Catalina SBC. 
+
+The various components of the 'firmware' on a Catalina board which you may want to update from time to time are (lowest level components listed first):
+- GSC firmware
+- Boot Firmware (oei/sm/atf/uboot)
+- 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 Catalina images can be found on https://dev.gateworks.com/catalina including:
+ * '''Compressed Disk Images''': (*.img.gz files) OS Images (everything but boot firmware)
+  - [https://dev.gateworks.com/catalina/images/ubuntu-catalina.img.gz ubuntu-catalina.img.gz] - Gateworks Ubuntu based OS details are available [wiki:catalina/ubuntu here]
+  * '''[#disk-images Install compressed disk images via U-Boot or Linux using instructions here]'''
+ * '''Gateworks System Controller Firmware''': (board specific gsc*.txt files)
+  - [https://dev.gateworks.com/catalina/images/gsc_9200.txt gsc_9200.txt]
+ * '''Boot Firmware''': Everything up to the OS (OEI, SM, SPL, ATF, U-Boot, U-Boot env)
+  - For updating via U-Boot or Linux or booting via SDP (does not contain U-Boot env)
+   * [https://dev.gateworks.com/catalina/boot_firmware/flash.bin flash.bin]
+ * '''Catalina Kernel Tarball''' useful for installing on top of root filesystem manually
+  * [https://dev.gateworks.com/catalina/kernel/linux-catalina.tar.xz linux-catalina.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 model. These images are flashed into the GSC itself.
+
+Boot firmware images are flashed to the eMMC boot0 partition.
+
+Compressed Disk Images are written to the eMMC user partition which contains a disk partition table and the various OS partitions.
+
+
+
+[=#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 (recommended for flashing new operating systems, etc)
+ * Using JTAG via a GW16099 JTAG dongle (recommended only for low level firmware in the .bin format) (*** Coming soon ***)
+
+[=#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 Catalina Dev Kit as well as on the Gateworks web store [http://shop.gateworks.com/index.php?route=product/category&path=70_80 here]
+
+All Catalina 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 Catalina (jtag_usbv4 required). Windows is not supported. (Serial console through Windows does work).
+ * JTAG Programming of eMMC is supported by [https://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 [https://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 [https://dev.gateworks.com/jtag/jtag_usbv4 here] and execute as follows:
+{{{#!bash
+./jtag_usbv4 -m gsc_9200.txt
+}}}
+
+For more details please see:
+ * [wiki:jtag Gateworks JTAG wiki page]
+
+
+=== Updating eMMC boot firmware via JTAG
+*** Coming Soon ***
+
+
+[=#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 either an HTTP or 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 HTTP/TFTP may fail including:
+ * Firewall issue keeping your server for being accessible (make sure you can ping it!)
+ * Invalid network configuration (netmask, gatewayip, ipaddr, serverip) - make sure you can ping it!
+
+
+[=#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.
+
+==== Compressed disk image via U-Boot
+A Compressed disk image (Ubuntu, OpenWrt, etc) in the .img.gz file format can be installed from U-Boot as long as you can load it into memory:
+ * using ethernet:
+{{{#!bash
+# setup your network addresses (ipaddr, serverip, gatewayip, netmask) manually, or via DHCP
+dhcp
+# set the protocol (http/tftp) (default env is http)
+setenv proto http
+# set the path on the server (default is 'catalina/')
+setenv path catalina/
+# choose the device to update (default env is sets this to 0 for eMMC)
+setenv dev 0 # sets MMC device to be flashed - see mmc list
+# choose the protocol (http/tftp) (default env is http)
+# specify the file name
+setenv image ubuntu-catalina.img.gz
+# update
+run update_os
+}}}
+ * using 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-catalina.img.gz && gzwrite mmc $dev $loadaddr $filesize
+}}}
+ * using a USB Mass Storage device:
+{{{#!bash
+usb start && load usb 0:1 $loadaddr ubuntu-catalina.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 https://dev.gateworks.com/catalina/images/ubuntu-catalina.img.gz
+# uncompress and write to the emmc device
+zcat ubuntu-catalina.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 (OEI, SM, 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 (which is the default) this does not affect the disk partition table or filesystems on the eMMC user partition.
+
+The latest pre-built boot-firmware image for Catalina are available for download here: 
+[https://dev.gateworks.com/catalina/boot_firmware/flash.bin]
+
+
+==== 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 your network addresses (ipaddr, serverip, gatewayip, netmask) manually, or via DHCP
+dhcp
+# choose the protocol (http/tftp) (default env is http)
+setenv proto http
+# set the path on the server (default is 'catalina/')
+setenv path catalina/
+# specify the file name (default is 'flash.bin')
+setenv firmware flash.bin
+# update
+run update_firmware
+# 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 specify the correct device, hardware partition and offset.
+
+To update boot firmware on the default eMMC boot0 hardware partition:
+{{{#!bash
+# allow writing to boot0
+echo 0 > /sys/block/mmcblk2boot0/force_ro
+# write to the emmc device to offset 0:
+dd if=flash.bin of=/dev/mmcblk2boot0
+}}}
+
+
+[=#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
+imx-oei lf-6.18.2-1.0.0-5-gd969478f mx95catalina (Apr 27 2026 16:50:04)
+...
+imx-sm lf-6.18.2-1.0.0-5-g7da12332 (Apr 27 2026 16:50:04)
+...
+U-Boot SPL 2026.04-00012-gd586e3508c07-dirty (Apr 27 2026 - 16:50:08 -0700)
+...
+U-Boot 2026.04-00012-gd586e3508c07-dirty (Apr 27 2026 - 16:50:08 -0700)
+...
+[    0.000000] Linux version 6.18.20-g4b3767a0c7d8 (buildbot@74809c9e98bd) (aarch64-linux-gcc.br_real (Buildroot 2026.02
+) 14.3.0, GNU ld (GNU Binutils) 2.44) #1 SMP Mon Apr 27 22:32:53 UTC 2026
+...
+Ubuntu 24.04.3 LTS catalina ttyLP0
+
+Gateworks Ubuntu (g8940973 Mon Apr 27 22:48:18 UTC 2026)
+}}}
+
+
+The above output shows you:
+ * OEI GIT revision and build date
+ * SM GIT revision and build date
+ * 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 BSP that built it
+ * For an Ubuntu based rootfs you can use {{{dpkg -l | grep "^ii"}}} to see what packages and versions are installed