Gateworks Newport Family Support

Getting Started	Newport Software	Peripherals	User Manuals
Wireless / WiFi Radios	Cellular Modems	GPS	3D Model

The Gateworks Newport product family utilizes the Cavium ARM ThunderX CN80xx / CN81xx SoC (System On Chip) offering a large variety of peripherals with a focus on Networking, and Security. See ​here for a product comparison matrix.

Links

Please note: This is a subset of information for Newport, however, please visit our Main Wiki for all other information

Software

• Firmware (up to and including the Bootloader)
• U-Boot Bootloader
• Newport Board Support Packages and Operating Systems
• Linux kernel support
• Booting Third Party Linux Distro's on Newport
• Newport JTAG Programming

Peripheral Support

• Gateworks Expansion Modules - GW16081, GW16082, GW16083
• SPI Support
• I2C Support
• GPIO Control
• LED Control
• Connector and Cable Information
• mSATA Information
• GPS Support
• CAN Bus Support
• PCI/PCIe information
• PCIe Accessory Cards
• MultiMediaCard (microSD/eMMC) Information
• Gateworks System Controller (GSC) - Temperature, voltage, RTC, GPIO, Digital IO, I/O, pushbutton, etc
• Gateworks Enclosures

Performance / Processor / Memory / Power / Thermal

• Multi Core Processing
• Increasing Boot Speeds

Other Info

• ​Product Info
• ​Where to Buy
• Newport Board Errata
• Linux Kernel Device-Tree info

JTAG Programming

The Gateworks JTAG dongle (GW16099) is available in the Newport Dev Kit as well as on the Gateworks web store ​here

All Newport boards have a 10-pin JTAG header which provides:

• JTAG Programming for embedded FLASH - see 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

User Manual

• ​All Gateworks User Manuals

Processor Reference Manual / Datasheet / Errata

The ​​Cavium Website contains details about the OCTEON TX Dual and Quad core 64bit ARM based SoC's.

Additional references:

• ​​OCTEON TX CN80XX-CN81XX Product Brief

Firmware (Up to and including the Bootloader)

The 'firmware-image' for Newport is defined as the combination of the First level 'boot stub' and the additional firmware stages through the bootloader. This can be broken down into the following stages:

• Boot ROM (internal on CN80XX/CN81XX SoC): fetch first level boot stub (192KB limit) from boot device (MMC or SPI FLASH)
• SPL (Secondary Program Loader)
• Bootloader (U-Boot)

For a Secondary Program Loader, or SPL, Gateworks currently uses the Cavium Board Development Kit (BDK) provided by their OCTEON-TX Software Development Kit (SDK). In this current implementation the Boot ROM loads and executes the BDK, the BDK loads and executes the ARM Trusted Firmware (ATF) and the ATF loads and executes the U-Boot bootloader in multiple stages as such:

• First level: Bootstub (firmware/bdk)
• Second level: ATF (firmware/atf)
• Third level: U-Boot (bootloader/u-boot)

Gateworks provides a pre-built firmware-image ready to flash onto boot devices as well as source for building and/or modifying the firmware yourself.

Boot ROM

The OCTEON-TX Boot ROM code loads an image from the primary boot device which can be either MMC or SPI FLASH. For a description of available boot devices see below.

Boot Device

Some boards have multiple boot device and may allow selection of which one is the 'primary boot device':

board	Primary Boot Device	Alternate Boot Device
GW630x	on board eMMC	microSD

To boot from the alternate boot device manually you can press-and-release the user pushbutton 5 times in a row and the board will power cycle primary power (the 3.3V LED will go off, then on again) and the board will boot from the alternate boot device.

Boards with an Alternate boot device also have a boot watchdog such that if the current boot device fails to boot within 30 seconds, the board will power cycle primary power and attempt boot from the other boot device.

U-Boot Bootloader

Gateworks supports the U-Boot Bootloader for the Newport product family. We provide pre-built firmware images (see [#firmware above) as well as source for building and/or modifying it yourself.

One of the primary features of the Bootloader is to provide access to the hwconfig environment variable that the firmware uses for initial board configuration on power-up.

hwconfig

The U-Boot Bootloader by convention provides a hwconfig environment variable which is used by the firmware (before U-Boot is loaded and executed) to configure board options at power-up. These options can include things such as:

• miniPCIe socket functions (ie PCIe vs mSATA vs USB3.0)
• serial configuration (ie RS232 vs RS485)

hwconfig: miniPCIe Socket Configuration

Newport board model socket options:

• GW630x:
  • J9: PCIe
  • J10: PCIe or SATA
  • J11: PCIe or USB3.0

Note that USB2.0 is routed to all three miniPCIe sockets always but as USB3.0 shares signals with PCIe you must choose between PCIe and USB3 on sockets that support USB3.

You can get/set the hwconfig variable within the U-Boot bootloader but you must reboot the board for it to take effect as the variable is acted upon in the Secondary Program Loader (SPL).

Examples:

• GW630x:
  • J10 PCIe, J11 PCIe (default)

    setenv hwconfig 'j10:pcie;j11:pcie'; saveenv
    

  • J10 mSATA, J11 USB3.0

    setenv hwconfig 'j10:sata;j11:usb3'; saveenv
    

  • J9/J10 disabled, J11 PCIe

    setenv hwconfig 'j9:disabled;j10:disabled;j11:pcie'; saveenv
    

Note that hwconfig is also used for serial configuration so care should be taken to preserve that configuration if used

hwconfig: serial Configuration

Many boards in the Newport product family provide a 5-pin off-board serial connector that provides the following options:

• 1x RS485 FD (UART2)
• 1x RS485 HD (UART2)
• 1x RS232 w/ hardware flow control (UART2)
• 2x RS232 w/o hardware flow control (UART2/UART3)

By default 2x RS232 with no flow control is enabled. To configure a different option use the hwconfig U-Boot env variable. The mode property of the serial option defines the initial configuration of the serial port(s). If RS485 is selected by the mode property the term property will select whether or not on-board termination is enabled.

The mode property can have the following values:

• rs232 - 2x RS232 (UART2/UART3) without hardware flow control (default if not specified)
• rs232_dtr - RS232 (UART2) with hardware flow control
• rs485_hd - RS485 half-duplex
• rs485_fd - RS485 full-duplex

Examples:

• enable RS485 half duplex no on-board termination

  setenv hwconfig "serial:mode=rs485_hd,term=no"; saveenv
  

• enable RS485 full duplex with on-board termination

  setenv hwconfig "serial:mode=rs485_fd,term=yes"; saveenv
  

• enable RS232 with hardware flow-control:

  setenv hwconfig "serial:mode=rs232_dtr"; saveenv
  

Note that hwconfig is also used for serial configuration so care should be taken to preserve that configuration if used

Board Support Packages (BSP) Software

Choosing a BSP

Gateworks offers several Board Support Packages for the Newport Product family. Which one we recommend depends a bit upon what your goal is and what your experience level is.

• Ubuntu
  • Recommended for developers trying to heavily leverage opensource software packages or libraries that are not supported by the other BSP's. This is the most user-friendly for developers new to Embedded Linux but will not produce a very trimmed down filesystem image.
  • Uses mainline kernel.
  • Supports all Newport features.
  • Documentation provided to use Ubuntu pre-built packages and debootstrap to create a root filesystem in minutes
  • Native compilation: no SDK or cross-toolchain needed

• OpenWrt - Coming Soon for Newport - intended for wireless routers and access points (low flash and memory footprint)
  • Recommended for networking users wanting to create a headless router, VPN, basestation, wireless access point and more. Produces by far the smallest storage and memory footprint but users new to Embedded Linux will have a bit of a learning curve
  • Fairly up-to-date and/or vanilla kernel support
  • Latest wireless drivers (via linux-backports)
  • Custom application config and init system (nice for small footprint, but can make adding support for additional packages more work)
  • Wide variety of packages (including a fairly nice web-admin)
  • Console-based build system (expect 60mins to build BSP for a specific board family)
  • Downloadable SDK and Toolchain available to build apps on a development host without building the entire BSP
  • Pre-built images available

The following table may also help in choosing what BSP is right for you:

Feature	OpenWrt	Ubuntu	Notes
Pre-built images	Yes	Yes
Storage Needed	<256MB	2GB or larger
Build-System	Yes	No	1
Toolchain	SDK	Native	2
Web-Admin	Yes	No	3

1. The OpenWrt BSP contain an integrated build-system. Ubuntu has step-by-step instructions on how to build an bootable system in 10 or so steps.
2. The OpenWrt BSP provides a downloadable SDK for cross-compiling applications on a development hosts. For Ubuntu native development and compilation is supported.
3. The OpenWrt BSP is designed to be a wireless router and has an integrated web-admin for configuration and control.

Ubuntu

Gateworks offers a pre-built Ubuntu distribution using the latest Gateworks kernel as well as instructions on how to build your own Ubuntu based distribution.

• Ubuntu Wiki and Software

OpenWrt Board Support Package (BSP)

Coming Soon

Newport OpenWrt BSP:

• Pre-Built Binaries
• Building/Installing OpenWrt w/ Gateworks Patches for the Newport Family
• Main OpenWrt Wiki Page
• OpenWrt SDK Toolchain
• join the ​maillist to follow activity
• GPIO and LED Configuration

The Newport OpenWrt BSP provides the following:

• Linux 4.x kernel (fairly vanilla)
• latest wireless drivers (compat-wireless)
• tuned for minimal FLASH/memory footprint (entire distro fits on embedded 16MB FLASH)

Third Party Linux Distros

While Gateworks cannot fully support all Linux distros, it is relatively simple to overlay a Gateworks Newport kernel onto any non-Gateworks third party Linux distro rootfs image.

The following links will describe what is needed:

1. Linux kernel supporting Newport: linux/kernel
2. Root Filesystem: see below
3. Bootable media: linux/blockdev

Root filesystem Sources

There are several sources of pre-built root filesystems that are compatible with Newport. As Newport uses an ARM 64bit based SoC, you need to use something that is compatible with an ARMv8 instruction set. Many pre-built distributions will reference 'arm64' which means 'ARM 64-bit' which is appropriate for the CN80XX / CN81XX SoC.

Some popular third-party sources:

• ​Ubuntu Core - this is a minimal filesystem that you can build off of at runtime by adding packages from various repositories.
• ​Linaro - Linaro has several root filesystems including server, nano, developer, core, and ALIP. Each root filesystem will have different things installed for different purposes. Choose carefully which will work for you.

Notes:

• some root filesystems may require you to manually add a user before booting (ie Ubuntu Core)
• the default Newport bootloader expects to find the Image in the /boot directory on the 2nd partition of type ext2/3/4

Mainline Linux Kernel support

Gateworks actively participates in the development of the Linux kernel.

Cavium licenses CPU core IP from ARM and the name they give the CPU core within the OCTEON-TX CN80XX / CN81XX is the Cavium 'ThunderX'. Therefore many of the peripheral drivers within the Linux kernel have 'thunderx' in their name and more often then not the 'OCTEON' name refers to the older OCTEON MIP64 core.

The following table shows what OCTEON-TX CN80XX / CN81XX peripherals support is available in the mainline kernel starting from 4.13:

Feature	Support	Notes
SMP	Yes	ARCH_THUNDER
serial UART (SBSA)	Yes	SERIAL_AMBA_PL011 drivers/tty/serial/amba-pl011.c
watchdog Watchdog (SBSA)	Yes	ARM_SBSA_WATCHDOG drivers/watchdog/sbsa_gwdt.c
I2C	Yes (4.9+)	I2C_THUNDERX drivers/i2c/busses/i2c-{octeon-core,thunderx-pcidrv}.c
Networking BGX (SGMII)	Yes (4.2+)	THUNDER_NIC_BGX drivers/net/ethernet/cavium/thunder/thunder_bgx.c
Networking RGX (RGMII)	Yes (4.9+)	THUNDER_NIC_RGX drivers/net/ethernet/cavium/thunder/thunder_xcv.c
PCI	Yes (4.6+)	PCI drivers/pci/host/pci-thunder-{ecam,pem}.c
SPI	Yes (4.9+)	SPI_THUNDERX drivers/spi/spi-thunderx.c
MMC eMMC / microSD	Yes (4.12+)	MMC_CAVIUM_THUNDERX drivers/mmc/host/thunderx-mmc.c
HW RNG (Hardware Random Number Generator)	Yes (4.9+)	HW_RANDOM_CAVIUM drivers/char/hw_random/cavium-rng*.c
HW Compressions offload	Yes (4.12+)	DEV_CAVIUM_ZIP drivers/crypto/cavium/zip.c
Crypto	Yes (4.11+)	DEV_CAVIUM_CPT drivers/crypto/cavium
RTC	Yes	RTC_DRV_DS1672 drivers/rtc/rtc-ds1672.c
LED/GPIO	Yes (4.14+)	GPIO_THUNDERX drivers/gpio/gpio-thunderx.c
USB 3.0	Yes	USB_XHCI_PCI
mSATA	Yes	SATA_AHCI

The following kernel configs should be enabled for the OCTEON-TX CN80XX / CN81XX:

• SERIAL_AMBA_PL011 - ARM SBSA UART
• MMC_CAVIUM_THUNDERX - MMC
• EDAC_THUNDERX - Error Detection and Correction (works with 'edac-util' app from 'edac-utils' package)
• GPIO_THUNDERX - General Purpose I/O
• SPI_THUNDERX - SPI Controller
• I2C_THUNDERX - I2C Controller
• THUNDERX_NIC_VF - NIC virtual function
• THUNDERX_NIC_PF - NIC physical function
• THUNDERX_NIC_BGX - Network Controller (selects MDIO_CAVIUM/MDIO_THUNDERX)
• THUNDERX_NIC_RGX - RGMII Network Controller (selects MDIO_CAVIUM/MDIO_THUNDERX)
• PCI_HOST_THUNDER_PEM - PCI host controller
• PCI_HOST_THUNDER_ECAM - Enhanced Configuration Access Mechanism for PCIe memory mapped I/O
• ARM_SBSA_WATCHDOG - ARMv8 Watchdog
• CRYPTO_DEV_CAVIUM_ZIP - Hardware Compression / Decompression off-load
• HW_RANDOM_CAVIUM - Hardware accelerated random number generator

Note that there are many kernel drivers using the name 'Octeon' but they typically refer to a different chipset and the CN80XX / CN81XX have more in common with the Cavium 'ThunderX' architecture as that is the SoC core.

For details on building a Linux kernel see here