Changes between Initial Version and Version 1 of newport/firmware

Timestamp:

07/31/2018 08:50:10 PM (6 years ago)

Author:

Cale Collins

Comment:

Consolidation and restructuring of newport firmware info.

newport/firmware

@@ +1 @@
+[[PageOutline]]
+
+= Newport Firmware Update
+The various components of the 'firmware' on a Newport board which you may want to update from time to time are (lowest level components listed first):
+- GSC firmware
+- BDK components (boot.bin bootstub, board device-tree, init.bin app)
+- Linux device-tree
+- ATF
+- U-Boot bootloader
+- Linux kernel
+- root filesystem
+
+Some of the above components are contained within the embedded FAT12 filesystem and others are placed at offsets within the boot device specified by the Newport [wiki:newport/boot#firmware-image 'boot firmware' flash map]. Typically you do not want to update the entire boot firmware with a simple {{{dd if=firmware-newport.bin of=/dev/mmcblk0}}} as this would have the undesired affect of overwriting your U-Boot env and the contents of the embedded FAT12 filesystem that you may not want to alter.
+
+For components which are not contained in the embedded FAT12 fs such as the bootstub, the ATF, and the U-Boot FIP you can update them individually in Linux using {{{dd}}} or in U-Boot using {{{mmc write}}} taking care to place them at the right offset. Note that the BDK provided by Gateworks (modified from the Cavium SDK to support Newport) does not contain any support for redundancy or fallbacks although such features could be implemented in the BDK if you choose. The same can be said for the ARM Trusted Firmware provided by Gateworks (from the Cavium SDK) which loads/verifies/executes the bootloader. The only component that technically can not have a fallback is the bootstub unless you are using [wiki:newport/trusted-boot trusted boot] with flash jump enabled and consider the non-trusted bootstub a backup.
+
+To determine the versions of the various components of the firmware you can use the details stored in the 'version' file on the embedded FAT12 filesystem. These details are created by the Newport BSP Makefile (newport/Makefile) if you need to modify or add to them. The GSC firmware version details can be obtained via the Linux driver sysfs {{{fw_ver}}} and {{{fw_crc}}} properties in '/sys/bus/i2c/devices/0-0020/'.
+
+[=#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
+Gateworks Newport SPL (ea21abc Tue Dec 12 23:42:48 UTC 2017)
+
+GSC     : v49 0x832c WDT:disabled board temp:61C
+RTC     : 0
+Model   : GW6304-B
+...
+NOTICE:  BL1: v1.3(release):OCTEONTX_SDK_6_2_0_build_26
+NOTICE:  BL1: Built : 15:30:07, Dec  4 2017
+...
+U-Boot 2017.09-rc1-00023-g1fd1415 (Dec 12 2017 - 15:42:30 -0800) for Cavium OcteonTX CN81XX ARM V8 Core
+...
+[    0.000000] Linux version 4.14.4-00005-g9e5958b (tharvey@tharvey) (gcc version 5.3.0 (Cavium Inc. Version 0.99 build 440)) #141 SMP PREEMPT Fri Dec 15 10:18:19 PST 2017
+...
+Ubuntu 16.04 LTS xenial-newport ttyAMA0
+...
+}}}
+ - The above output shows you:
+  * Secondary Program Loader (SPL) is 'ea21abc' built on Tue Dec 12 23:42:48 2017. The git sha of 'ea21abc'.
+  * GSC v49 0x832c
+  * ATF (ARM Trusted Firmware) is v1.3 built on Dec 4 2017.
+  * U-Boot is '2017.09-rc1-00023-g1fd1415' built on Dec 12 2017.
+  * Linux version 4.14.4-00005-g9e5958b built on Fri Dec 15 10:18:19 PST 2017
+  * Ubuntu 16.04 (aka xenial) OS (use {{{dpkg -l | grep "^ii"}}} to see what packages and versions are installed
+
+If you want more detail on the versions of the various components of the [wiki:newport/boot Boot Firmware] you can look at the {{{version}}} file created/placed by the Newport BSP Makefile in the FAT12 filesystem. See [wiki:newport/boot#version newport/boot/version] for details.
+
+
+[=#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 ('''Note that currently the eMMC FLASH can only be updated on a live board booted from either eMMC or microSD''')
+ * on removable storage (ie recovery microSD)
+ * using a GW16099 JTAG dongle (see [#jtag below]) ('''Note that currently only the GSC firmware can be updated via JTAG''')
+
+The various items that can be updated:
+ * GSC Firmware - currently only JTAG updates are supported for Newport - see [#jtag-gsc below]
+ * Boot Firmware (Everything up to and including the Bootloader) - currently must be updated from U-Boot or Linux on a live system - see [#serial-ethernet below]
+ * Root Filesystem (Operating System) - currently must be updated from U-Boot or Linux on a live system - see [#serial-ethernet below]
+
+[=#jtag]
+== JTAG Programming ==
+The Gateworks JTAG adapter (GW16099) is available in the Newport Dev Kit as well as on the Gateworks web store [http://shop.gateworks.com/index.php?route=product/category&path=70_80 here]
+
+All Newport boards have a 10-pin JTAG header which provides:
+ * JTAG Programming for embedded FLASH - see [wiki:jtag_instructions here] for instructions
+ * Serial Console access via UART0 (/dev/ttyAMA0)
+
+Please Note:
+ * '''Linux software is supported for programming Newport (jtag_usbv4 required).''' Windows is not supported at this time.''' (serial console through Windows does work).
+ * '''JTAG Programming of eMMC has not been made available yet'''. You must boot from a microSD image to program or re-program eMMC flash
+ * '''JTAG Programming of the GSC firmware is supported by the most recent version of jtag_usbv4''' [http://svn.gateworks.com/jtag/linux/x86/jtag_usbv4 here]
+  * [wiki:/newport/firmware-update?action=edit#UpdateGSCFirmwareviaJTAG Guide for GSC update via Jtag]
+
+
+[=#serial-ethernet]
+== Update Firmware via Serial Console and Ethernet ==
+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 your primary boot device is corrupt, then you can boot via an alternate boot device (ie microSD) - see [#recovery newport/recovery] for details.
+
+
+[=#serial-ethernet-uboot]
+=== Update Firmware via Serial Console and Ethernet from Bootloader ===
+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, mSATA, or USB for example) however the transfer rate is typically very slow compared to Gigabit Ethernet. 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>'.
+
+Note that the {{{dev}}} variable needs to be set to the MMC device you are updating:
+ * setenv dev 0 # boot device
+ * setenv dev 1 # secondary device
+ * use {{{mmc list}}} to see how they are configured
+
+The methods you use to update the firmware depends on what specifically you are trying to update.
+
+Update the entire device from a Compressed Disk Image ('[wiki:newport/boot boot firmware]' as well as OS):
+{{{#!bash
+setenv dev 0 # use 'mmc list' to show which device to use for eMMC vs microSD
+tftpboot ${loadaddr} xenial-newport.img.gz && gzwrite mmc ${dev} ${loadaddr} ${filesize}
+}}}
+  - **If the image was created using a minimally sized filesystem you will want to resize it after booting to take advantage of the full partition space. For an {{{ext4}}} root filesystem on the primary MMC device run {{{resize2fs /dev/mmcblk0p2}}}.**
+
+To summarize:
+{{{#!bash
+setenv ipaddr 192.168.1.1 # sets device IP
+
+setenv serverip 192.168.1.146 # sets TFTP server IP
+
+setenv dev 0 # sets MMC device to be flashed 
+
+tftpboot ${loadaddr} xenial-newport.img.gz && gzwrite mmc ${dev} ${loadaddr} ${filesize} # will flash xenial-newport.img.gz which resides in the top most directory of the TFTP server  
+}}}
+
+Updating just the kernel can be done with {{{tftpboot}}} and {{{fatwrite}}}:
+{{{#!bash
+# kernel
+tftpboot $loadaddr kernel.itb && fatwrite mmc $dev:1 $loadaddr kernel.itb $filesize
+# bootscript
+tftpboot $loadaddr newport.scr && fatwrite mmc $dev:1 $loadaddr newport.scr $filesize
+}}}
+
+Updating the [wiki:newport/boot 'Boot firmware'] (everything up to and including the Bootloader): 
+On a Newport booted to the bootloader:
+{{{#!bash
+mmc dev 0 # use 'mmc list' to show which device to use for eMMC vs microSD
+tftpboot ${loadaddr} firmware-newport.img && mmc write ${loadaddr} 0 8000 # update first 16MB
+mmc rescan # re-scan the mmc devices in case the partition table changed
+}}}
+
+Incorrect or out of date Boot Firmware may result in the analogue to digital conversion or registers being misinterpreted, in example:
+{{{#!bash
+GSC     : v51 0x859f WDT:disabled board temp:3276C
+RTC     : 0
+Model   : GW6300-B
+MFGDate : 12-13-2017
+Serial  : 757565
+DTB     : gw6300.dtb
+SoC     : CN8020-850BG676-SCP-P12-G 1024KB 850/500MHz 0xa2 Pass 1.2 
+MMC0    : eMMC
+MMC1    : not detected
+Boot    : eMMC non-trusted 
+DRAM    : 1024 MB, 1333 MT/s, DDR4 UDIMM
+J9      : PCI
+J10     : PCI
+J11     : PCI
+QLM0    : PCIE_1X1@5000MHz
+QLM1    : SGMII_1X1@1250MHz
+QLM2    : PCIE_1X1@5000MHz
+QLM3    : PCIE_1X1@5000MHz
+Serial  : 2x RS232 without flow control
+PEM0    : QLM0 Link Timeout
+PEM1    : QLM2 Link Timeout
+PEM2    : QLM3 Link Timeout
+temp    : 32765 - Failed High: 9000
+vin     : 7798784 - Failed High: 60000
+3p3     : 137088 - Failed High: 3630
+5p0     : 84481 - Failed High: 5500
+0p9     : 107521 - Failed High: 990
+core    : 8782184 - Failed High: 946
+1p2     : invalid
+2p5     : invalid
+1p0     : invalid
+1p5     : invalid
+1p8     : invalid
+anl     : invalid
+}}} 
+
+
+
+[=#serial-ethernet-linux]
+=== Update Firmware via Serial Console and Ethernet from Linux ===
+If booted to Linux on a board you can also update the kernel and bootscript fairly easily by mounting the FAT12 filesystem and copying the file(s):
+{{{#!bash
+mount /dev/mmcblk0p1 /mnt
+cp kernel.itb /mnt
+cp newport.scr /mnt
+}}}
+
+You can also easily update the [wiki:newport/boot 'Boot Firmware']. First prepare a boot image that contains your desired partition table, boot firmware, kernel, bootscript and U-Boot environment (see example above). Then on a booted Newport:
+{{{#!bash
+cd /tmp
+wget http://dev.gateworks.com/newport/boot_firmware/firmware-newport.img
+dd if=firmware-newport.img of=/dev/mmcblk0
+}}}
+ * Note above we are writing to {{{/dev/mmcblk0}}} and not a partition
+ * Use {{{/dev/mmcblk1}}} for the secondary MMC device (ie microSD)
+ * Note that Newport boards only supports MMC based boot devices
+ *  **Note that this overwrites the partition-table, the U-Boot environment, and the FAT12 filesystem which are things you might have customizations in.**
+
+Note that if you want to update the root filesystem itself from within Linux you can only do this by either:
+ a) updating portions of the live filesystem that are not in use (ie package updates)
+ b) booting to a kernel+ramdisk (ie [wiki:buildroot buildroot) and imaging the disk
+
+= 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://svn.gateworks.com/jtag/linux/x86/jtag_usbv4 here] and execute as follows:
+{{{#!bash
+./jtag_usbv4 -m gsc_630x_v49.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 BDK components
+The BDK is the 'secondary program loader' that the CN80xx BOOT ROM loads/validates/executes. It consists of several components or stages:
+- '''bootstub''': The first 192KB at the fixed FLASH offset of 0x20000 (non-trusted) and 0x50000 (trusted) is the contents of the 'boot.bin' bootstub (bdk/apps/boot/boot.bin). The bootstub is responsible for very early init including identifying the board, loading the board.dtb from the FAT12 filesystem and loading/verify/executing the 'init app' (bdk/apps/init/init.bin). Updating the bootstub can be done in Linux using {{{dd}}} or in U-Boot using {{{mmc write}}} but you will also need to update the CVM_CLIB flash headers at 0x10000. For example:
+ * extract extract the CVM_CLIB headers, the non-trusted bootstub and the trusted bootstub from firmware-newport.img:
+{{{#!bash
+dd if=firmware-newport.img of=bootstub.bin bs=64K skip=1 count=7 # extract 0x10000 to 0x80000
+}}}
+ * write it in Linux:
+{{{#!bash
+dd if=bootstub.bin of=/dev/mmcblk0 bs=64K seek=1 count=7 # program 0x10000 to 0x80000
+}}}
+ - If you need to update one bootstub without the other you will need to modify the CVM_CLIB headers using the details specified in the CN80XX HRM and performed by the {{{newport/make-bootfs.py}}} script.
+- '''board.dtb''': The 'board.dtb' file (ie gw6300.dtb*, gw6304.dtb*, etc) is loaded/verified by the bootstub and contains very low level board-specific CN80XX configuration details that are outside of the scope of the Linux kernel device-tree bindings such as QLM configuration and DRAM configuration. Updating the board.dtb can be done by mounting the FAT12 filesystem in Linux (/dev/mmcblk0p1) and replacing the file.
+- '''init.bin''': The 'init app' (bdk/apps/init) is responsible for the majority of the low-level board configuration such as configuring the CN80XX DDR controller, QLM's, BGX's, phy's, and various board-specific GPIO's. When complete it will load/validate the Linux device tree from the FAT12 filesystem, then load/validate/execute the ATF from its fixed offset in FLASH at 0xe00000 (14MiB). Updating the init app can be done by mounting the FAT12 filesystem in Linux (/dev/mmcblk0p1) and replacing the init.bin file.
+
+
+= Updating Linux device-tree
+The board specific Linux device-tree (ie gw*-linux.dtb*) is loaded by the BDK 'init app' from the embedded FAT12 fs therefor can be updated by mounting the filesystem in Linux (/dev/mmcblk0p1) and replacing the file.
+
+
+= Updating ARM Trusted Firmware (ATF)
+The ARM Trusted Firmware exists from '0x0e00000 - 0x0f00000' (1Mib at 14MiB offset) specified by the 'boot firmware' flash map. It will load/verify/execute U-Boot from its FIP image. The ATF can be updated individually from Linux using {{{dd}}} or U-Boot using {{{mmc write}}} but there is a header around it so you must obtain it from the firmware-newport.img.
+
+For example:
+ * extract ATF from firmware-newport.img:
+{{{#!bash
+dd if=firmware-newport.img of=atf.bin bs=1M skip=14 count=1 # extract 1MiB@14MiB)
+}}}
+ * write it in Linux:
+{{{#!bash
+dd if=atf.bin of=/dev/mmcblk0 bs=1M seek=14 count=1 # program 1MiB@14MiB
+}}}
+
+
+= Updating U-Boot bootloader
+The U-Boot bootloader is wrapped in a ATF FIP package placed at '0x0f00000 - 0x0ff00000' (960KiB at 15MiB offset) and is loaded/verified/executed by the ATF. You can update this taking the 'fip.img' created by the Newport BSP Makefile uboot target and using Linux {{{dd}}} or U-Boot {{{mmc-write}}}.
+
+For example:
+ * write fip.img in Linux:
+{{{#!bash
+dd if=fip.bin of=/dev/mmcblk0 bs=1M seek=15 # program at 15MiB offset
+}}}
+
+
+= Updating Linux kernel
+The Linux kernel exists in the embedded FAT12 filesystem and is loaded by the bootloader boot scripts. It can be updated by mounting {{{/dev/mmcblk0p1}}} in Linux and replacing the file. How and from where the kernel is loaded can be changed to your liking in the U-Boot env however the Gateworks U-Boot env uses a bootscript which is scanned for by the U-Boot scripts (look over the U-Boot env to follow the 'distro config' bootscript setup). The Ubuntu bootscript in the Newport BSP (newport/ubuntu.scr) uses a compressed kernel in a FIT image (kernel.itb). If wanted your bootscripts can be altered to provide a redundant/alternate kernel based on some U-Boot env var flags and counters that could be modified in Linux with the fw_setenv/fw_printenv tools from the U-Boot package. These are packaged in the u-boot-tools Ubuntu package and you can see example usages in the Newport BSP newport/Makefile.
+
+
+= Updating root filesystem
+Updates on the root filesystem are very use specific. You can use a package manager, or use multiple rootfs partitions on the FLASH selected by U-Boot when setting up the bootargs passed to the kernel. A common way to to this would be to use U-Boot variables as flags and counters that are altered within Linux via the fw_setenv/fw_printenv tools from the U-Boot {{{u-boot-tools}}} package. You can see example usages in the Newport BSP newport/Makefile.
+