Changes between Version 15 and Version 16 of venice/firmware


Ignore:
Timestamp:
06/08/2023 09:34:44 PM (13 months ago)
Author:
Tim Harvey
Comment:

general cleanup pass

Legend:

Unmodified
Added
Removed
Modified
  • venice/firmware

    v15 v16  
    5050
    5151There are two methods for updating firmware:
    52  * on a live board using Serial Console and Ethernet
    53  * using a GW16099 JTAG dongle (see [#jtag below])
    54 
    55 The various items that can be easily updated:
    56  * GSC Firmware - Can be updated via JTAG or at runtime - see [#gsc below])
    57  * Boot Firmware (Everything up to and including the Bootloader)
    58  * Root Filesystem (Operating System)
     52 * on a live already-booting board using Serial Console and Ethernet via U-Boot or Linux booted from a ramdisk
     53 * using JTAG via a GW16099 JTAG dongle
    5954
    6055[=#jtag]
    61 == JTAG Programming
     56== Updating Firmware via JTAG
     57The 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.
     58
    6259The 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]
    6360
     
    6764
    6865Please Note:
    69  * Only flash .bin files via the JTAG programmer and jtag_usbv4
     66 * Only flash files intended for JTAG using the JTAG programmer and jtag_usbv4
    7067 * Linux software is supported for programming Venice (jtag_usbv4 required). Windows is not supported. (Serial console through Windows does work).
    7168 * 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).
    72  * JTAG Programming of the GSC firmware is supported by [http://dev.gateworks.com/jtag/jtag_usbv4 jtag_usbv4] - see [#jtag-gsc below]
    73 
    74 To flash the Venice boot firmware (no operating system), use the following command:
     69 * JTAG Programming of the GSC firmware is supported by [http://dev.gateworks.com/jtag/jtag_usbv4 jtag_usbv4]
     70
     71=== Updating GSC Firmware via JTAG
     72To 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:
     73{{{#!bash
     74./jtag_usbv4 -m gsc_7000.txt
     75}}}
     76
     77Note 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.
     78
     79For more details please see:
     80 * [wiki:jtag Gateworks JTAG wiki page]
     81
     82
     83=== Updating eMMC boot firmware via JTAG
     84To flash an eMMC image via JTAG such as a boot firmware image:
    7585{{{
    7686sudo ./jtag_usbv4 –p firmware-venice-imx8mm.bin
     
    8292
    8393[=#serial-ethernet]
    84 == Update Firmware via Serial Console and Ethernet from Bootloader
    85 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.
    86 
    87 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].
    88 
    89 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>'.
    90 
    91 The methods you use to update the firmware depends on what specifically you are trying to update.
    92 
    93 Be care to use firmware images built for the specific SOC on the board you are using. Venice boards use a variety of IMX8M SoC's which have different boot firmware:
    94 ||= Board =||= SoC =||= Notes =||
    95 || GW710x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
    96 || GW720x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
    97 || GW730x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
    98 || GW740x-*    || i.MX8M Plus (aka IMX8MP) || use firmware with 'imx8mp' in the name ||
    99 
    100 You can tell what you are using by watching the board boot:
    101 {{{#!bash
    102 U-Boot 2022.07-g1050480603 (Aug 19 2022 - 17:02:47 +0000), Build: jenkins-venice-bsp-122
    103 
    104 CPU:   Freescale i.MX8MP[8] rev1.1 1600 MHz (running at 1200 MHz)
    105 CPU:   Industrial temperature grade (-40C to 105C) at 28C
    106 ...
    107 Hit any key to stop autoboot:  0
    108 u-boot=> print soc
    109 soc=imx8mp
    110 }}}
    111  - The above CPU banner shows 'i.MX8MP' which requires firmware with a 'imx8mp' in its name
    112  - The latest firmware images set the 'soc' U-Boot env variable to match the SoC you are using
     94== Update Firmware via Serial Console and Ethernet
     95The 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.
     96
     97If 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:
     98 * firewall issue keeping your TFTP server for being accessible (make sure you can ping it!)
     99 * invalid network configuration (netmask, gatewayip, ipaddr, serverip) - again make sure you can ping it!
     100 * '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
    113101
    114102
    115103[=#disk-images]
    116 ==== Update OS via Compressed Disk Images
     104=== Update OS via Compressed Disk Images
    117105A 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.
    118106
    119 Procedure:
    120  * Via U-Boot:
    121 {{{#!bash
    122 #First, setup the IP and server IP as described above (example IPs below)
     107Note 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.
     108
     109==== Compressed disk image via U-Boot
     110A 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):
     111 * using ethernet and a TFTP server using the 'update_all' script:
     112{{{#!bash
     113# First, setup the IP and server IP as described above (example IPs below)
    123114setenv ipaddr 192.168.1.1
    124115setenv serverip 192.168.1.2
     
    128119setenv dev 2 # sets MMC device to be flashed - see mmc list
    129120# set your image
    130 setenv image <distro>-venice.img.gz
     121setenv image ubuntu-venice.img.gz
    131122# update
    132123run update_all
     
    136127update_all=tftpboot ${loadaddr} ${image} && gzwrite mmc ${dev} ${loadaddr} ${filesize}
    137128}}}
    138  * Via Linux (when the volume is unmounted):
     129 * using a microSD:
     130{{{#!bash
     131# load image via microSD device and partition (use 'mmc list' and 'mmc part' to see a list)
     132load mmc 1:1 $loadaddr ubuntu-venice.img.gz && gzwrite mmc $dev $loadaddr $filesize
     133}}}
     134 * using a USB Mass Storage device:
     135{{{#!bash
     136usb start && load usb 0:1 $loadaddr ubuntu-venice.img.gz && gzwrite mmc $dev $loadaddr $filesize
     137}}}
     138
     139==== Compressed disk image via Linux
     140A 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):
    139141{{{#!bash
    140142# fetch your file
    141143cd /tmp
    142 wget http://dev.gateworks.com/venice/images/<distro>-venice.img.gz
     144wget http://dev.gateworks.com/venice/images/ubuntu-venice.img.gz
    143145# uncompress and write to the emmc device
    144 zcat <disro>-venice.img.gz | dd of=/dev/mmcblk0 bs=4M
    145 }}}
    146 
    147 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.
     146zcat ubuntu-venice.img.gz | dd of=/dev/mmcblk0 bs=4M
     147}}}
     148
    148149
    149150
    150151[=#boot-firmware]
    151 ==== Updating just the boot firmware
    152 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.
    153 
    154 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).
     152=== Updating just the boot firmware via U-Boot or Linux
     153The 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.
     154
     155'''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]'''
    155156
    156157The latest pre-built Bootloader images for Venice are available for download here:
    157158[http://dev.gateworks.com/venice/boot_firmware/]
    158  * Be sure to use one that is compatible with the SoC on your board
    159 
    160 Procedure:
    161  * Via U-Boot:
    162   - for IMX8M Mini board variants:
     159
     160'''It is important to use the correct file compatible with the SOC on your board''':
     161||= Board =||= SoC =||= Notes =||
     162|| GW710x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
     163|| GW720x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
     164|| GW730x-0x-* || i.MX8M Mini (aka IMX8MM) || use firmware with 'imx8mm' in the name ||
     165|| GW7905-2x-* || i.MX8M Plus (aka IMX8MP) || use firmware with 'imx8mp' in the name ||
     166|| GW740x-*    || i.MX8M Plus (aka IMX8MP) || use firmware with 'imx8mp' in the name ||
     167
     168You can tell what you are using by watching the board boot. For example consider the following U-Boot console messages:
     169{{{#!bash
     170U-Boot 2022.07-g1050480603 (Aug 19 2022 - 17:02:47 +0000), Build: jenkins-venice-bsp-122
     171
     172CPU:   Freescale i.MX8MP[8] rev1.1 1600 MHz (running at 1200 MHz)
     173CPU:   Industrial temperature grade (-40C to 105C) at 28C
     174...
     175Hit any key to stop autoboot:  0
     176u-boot=> print soc
     177soc=imx8mp
     178}}}
     179 - The above CPU banner shows 'i.MX8MP' which requires firmware with a 'imx8mp' in its name
     180 - Additionally the latest firmware images set the 'soc' U-Boot env variable to match the SoC you are using
     181
     182Note 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].
     183
     184
     185==== Boot firmware update via U-Boot
     186Updating 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:
    163187{{{#!bash
    164188# setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
    165189bootp  # optional: use dhcp for network config
    166 # choose the device to update
    167 setenv dev 2 # sets MMC device to be flashed - see mmc list
    168 # set your image
    169 setenv image venice-$soc-flash.bin # with any tftp server directories in front of the filename
     190# set the tftp directory your image is in
     191setenv dir venice
    170192# update
    171193run update_firmware
    172194}}}
    173    - This is what the update_firmware script does if your curious:
    174 {{{#!bash
    175 update_firmware=tftpboot $loadaddr $image && setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 && mmc dev $dev && mmc write $loadaddr 0x42 $blkcnt
    176 }}}
    177   - for IMX8M Nano board variants:
    178 {{{#!bash
    179 # setup network environment (use bootp or static by setting ipaddr/serverip and optional netmask/gatewayip)
    180 setenv autoload 0; bootp  # use dhcp for network config but do not fetch a file
    181 # choose the device to update
    182 setenv dev 2 # sets MMC device to be flashed - see mmc list
    183 # set your image
    184 setenv image venice-$soc-flash.bin # with any tftp server directories in front of the filename
    185 # update
    186 run update_firmware
    187 }}}
    188    - This is what the update_firmware script does if your curious:
    189 {{{#!bash
    190 update_firmware=tftpboot $loadaddr $image && setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 && mmc dev $dev && mmc write $loadaddr $splblk $blkcnt
    191 }}}
    192  * Via Linux:
    193   - Updating via Linux requires you to download the 'venice-<soc>-flash.bin' file (pre-built images can be found [http://dev.gateworks.com/venice/boot_firmware/ here] and to use the correct offset in the boot device which varies per SoC:
    194   - for IMX8M Mini board variants:
    195 {{{#!bash
    196 # fetch your file
    197 cd /tmp
    198 wget http://dev.gateworks.com/venice/boot_firmware/venice-imx8mm-flash.bin
    199 # uncompress and write to the emmc device to 33K offset
     195 * Alternatively you can load the image from removable storage
     196
     197
     198==== Boot firmware update via Linux
     199Updating the boot firmware via Linux requires you to manually determine the correct device, hardware partition and offset:
     200 * for IMX8M Mini board variants:
     201  - with boot firmware in user hardware partition:
     202{{{#!bash
     203# write to the emmc device to 33K offset
    200204dd if=venice-imx8mm-flash.bin of=/dev/mmcblk2 bs=1K seek=33
    201205}}}
    202   - for IMX8M Nano board variants:
    203 {{{#!bash
    204 # fetch your file
    205 cd /tmp
    206 wget http://dev.gateworks.com/venice/boot_firmware/venice-imx8mn-flash.bin
    207 # uncompress and write to the emmc device to 32K offset
     206  - with boot firmware in boot0 hardware partition:
     207{{{#!bash
     208# write to the emmc device to 33K offset
     209dd if=venice-imx8mm-flash.bin of=/dev/mmcblk2boot0 bs=1K seek=33
     210}}}
     211 * for IMX8M Nano board variants:
     212  - with boot firmware in user hardware partition:
     213{{{#!bash
     214# write to the emmc device to 32K offset
    208215dd if=venice-imx8mn-flash.bin of=/dev/mmcblk2 bs=1K seek=32
    209216}}}
    210   - for IMX8M Plus board variants:
    211 {{{#!bash
    212 # fetch your file
    213 cd /tmp
    214 wget http://dev.gateworks.com/venice/boot_firmware/venice-imx8mp-flash.bin
    215 # uncompress and write to the emmc device to 32K offset
     217  - with boot firmware in boot0 hardware partition:
     218{{{#!bash
     219# write to the emmc device to 0K offset
     220dd if=venice-imx8mn-flash.bin of=/dev/mmcblk2boot0 bs=1K seek=0
     221}}}
     222 * for IMX8M Plus board variants:
     223  - with boot firmware in user hardware partition:
     224{{{#!bash
     225# write to the emmc device to 32K offset
    216226dd if=venice-imx8mp-flash.bin of=/dev/mmcblk2 bs=1K seek=32
    217227}}}
    218 
    219 
    220 ==== Updating just the root filesystem
     228  - with boot firmware in boot0 hardware partition:
     229{{{#!bash
     230# write to the emmc device to 0K offset
     231dd if=venice-imx8mp-flash.bin of=/dev/mmcblk2boot0 bs=1K seek=0
     232}}}
     233
     234
     235[=#rootfs]
     236=== Updating just the root filesystem
    221237Updating the root filesystem from a 'compressed filesystem image' is easily done in U-Boot or Linux.
    222238
     
    253269
    254270
    255 === TFTP Error Troubleshooting
    256 There are many reasons why TFTP may fail including:
    257  * firewall issue keeping your TFTP server for being accessible (make sure you can ping it!)
    258  * invalid network configuration (netmask, gatewayip, ipaddr, serverip) - again make sure you can ping it!
    259  * '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
    260 
    261 
    262 = Updating GSC firmware
    263 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.
    264 
    265 
    266 [=#jtag-gsc]
    267 === Update GSC Firmware via JTAG ===
    268 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:
    269 {{{#!bash
    270 ./jtag_usbv4 -m gsc_7000_v57.txt
    271 }}}
    272 
    273 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.
    274 
    275 For more details please see:
    276  * [wiki:jtag Gateworks JTAG wiki page]
     271
     272[=#gsc-udpate]
     273=== Updating GSC firmware
     274The 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.
    277275
    278276