AirStack FPGA Firmware¶

The AIR-T's FPGA is configured with a firmware image stored in flash memory that the FPGA loads automatically on startup. Flash memory can be programmed with a new image to upgrade or modify the FPGA's behavior. This document describes the procedure for loading a new image into flash memory. This document also describes how to load a recovery image directly into the FPGA in the event that a faulty image is loaded into memory that could prevent normal programming of new images.

Firmware Installation¶

Prerequisites¶

To flash the firmware on the AIR-T you will need:

• An AIR-T
• AirStack OS image or Debian packages downloaded from the Developer Portal at www.deepwavedigital.com

Firmware Flash Procedure¶

NOTE: AirStack 0.5 introduced a recovery image to the FPGA firmware. This is achieved by partitioning the FPGA flash memory with a recovery firmware and the operational firmware. You may use the -i 0 flag of load_flash to address the recovery partition and -i 1 flag to address the operational partition.

1. If you have not already, follow the AirStack Upgrade Procedure or the AirStack Imaging Procedure to install AirStack Debian (.deb) packages or operating system images, respectively. This will place the firmware .bit files into /lib/firmware.

2. You may skip this step if you are already using AirStack 0.5.0+. If upgrading from an AirStack version older than 0.5.0 (e.g., upgrading from AirStack 0.4.2 AirStack to 0.5.0) first load the recovery firmware image introduced in AirStack 0.5.0: Use the load_flash utility with the -i 0 argument to load the AIR-T_Recovery .bit file installed into /lib/firmware. Use a command from the table below that corresponds to your AIR-T model.

   AIR-T Model(s)	FPGA Model	Flash Command
   AIR7101	XC7A75T	load_flash -i 0 /lib/firmware/AIR-T_Recovery_Firmware_xc7a75t_v0.5.0.bit
   AIR7201	XC7A200T	load_flash -i 0 /lib/firmware/AIR-T_Recovery_Firmware_xc7a200t_v0.5.0.bit
   AIR8201	XC7A200T	load_flash -i 0 /lib/firmware/AIR-T_Recovery_Firmware_xc7a200t_v0.5.0.bit

   • If the load_flash utility fails, you will need to use steps from the Recovery Method section below to return to a state where load_flash is functional.

3. Use the load_flash utility with the -i 1 argument to load the new AirStack .bit file installed into /lib/firmware. Use a command like one from the table below that corresponds to your AIR-T model.

   AIR-T Model(s)	FPGA Model	Flash Command
   AIR7101	XC7A75T	load_flash -i 1 /lib/firmware/AirStack_Firmware_7000_xc7a75t_vX.X.X.bit
   AIR7201	XC7A200T	load_flash -i 1 /lib/firmware/AirStack_Firmware_7000_xc7a200t_vX.X.X.bit
   AIR8201	XC7A200T	load_flash -i 1 /lib/firmware/AirStack_Firmware_8000_xc7a200t_vX.X.X.bit

   • If the load_flash utility fails, you will need to use steps from the Recovery Method section below to return to a state where load_flash is functional.

4. At this point new firmware has been loaded into the FPGA's flash memory but the FPGA is still using a prior configuration. In order to reload the FPGA you must do one of the following:

   • Shutdown, unplug the power supply to the AIR-T, and plug it back in.
   • Run the fpga_reload command which will safely take the FPGA off the PCIe bus, reload the flash memory into the FPGA, then place the FPGA back on the PCIe bus. Note that 7000 series AIR-T models will require the placement of a jumper wire on the AIR-T to allow for the FPGA to reload safely prior to running this command. See the procedure here: Remote Firmware Upgrades.

5. After reboot run the following to verify the upgrade:

   $ SoapySDRUtil --find

   which should return a found AIR-T device:

   Found device 0
     driver = SoapyAIRT
     driver_version = X.X.X-X
     firmware_version = AirStack X.X.X
     fpga_driver_version = X.X.X-X
     hardware = AIRXXXX
     rf_api_version = X.X.X-X
     url = https://www.deepwavedigital.com
     vendor = Deepwave Digital, Inc.
   

Firmware Recovery Method - Xilinx Vivado and USB/JTAG¶

Programming the AIR-T's flash memory with a faulty FPGA image could prevent the use of the load_flash utility for reprogramming the flash device. The following method will restore memory with an image that allows the use of the load_flash utility for normal reprogramming. Note that, once this procedure is complete, the FPGA's flash memory will ONLY contain a recovery image. It will NOT contain any firmware for normal SDR operation. Additional programming with load_flash will be necessary to install an image that allows SDR operation.

Prerequisites¶

To flash the firmware on the AIR-T you will need:

• A host machine running Linux*
• An AIR-T
• firmware_recovery.tar.gz downloaded from the Developer Portal at www.deepwavedigital.com

• A Micro USB cable

• It is possible to flash the AIR-T firmware with Vivado on any operating system supported by Vivado, however this bash script only runs on Linux.*

Linux Host Machine Requirements¶

We recommend running Ubuntu 16.04+ with the software outlined below installed.

Vivado for Linux¶

To flash the FPGA on the AIR-T, Vivado is currently required to be installed on the host. You may install full Vivado if you will be developing FPGA code. If you are just using Vivado to flash the FPGA, we recommend installing the lighter version, Vivado Lab Edition:

• Vivado 2017.4: Lab Edition Download

The flash_firmware install script will look for the Vivado Lab executable in:

/opt/Xilinx/Vivado_Lab/2017.4/bin/vivado_lab

which is the default installation location. If you choose to install Vivado in a different location, you must let the script know by passing the -v parameter.

Digilent JTAG Drivers for Linux¶

This is the driver for Linux to communicate with the USB JTAG module on the AIR-T. To set this up, install the following drivers on the host:

• Digilent Plugin for Xilinx Tools
• Adept 2 JTAG driver

AIR-T Hardware Connections¶

USB to USB Micro Cable¶

The FPGA on the AIR-T requires a USB connection to the host from the JTAG module (U23). If the AIR-T is in its enclosure, you will need to remove the cover to get access to the JTAG module. If you are having trouble plugging in the USB micro cable to U23, you may either remove the board from the enclosure or use an angled USB micro cable, shown as the StarTech 90 degree Micro USB Cable - A to Down Angle Micro B.

Figure 1: Image of the AIR-T and the relevant interfaces highlighted.

Firmware Flashing Utility¶

The flash_firmware script has a help menu that defines the input commands:

$ ./flash_firmware -h
This script will flash the firmware on the AIR-T.
Author: Deepwave Digital, Inc.

Usage: sudo ./flash_firmware [options]
Program Options:
  -h              Display this help message
  -a [path]       Path to AirStack files
  -v [file]       Vivado / Vivado Lab executable

Note: if you have installed Vivado in a non-default location, you must pass the location to the script using the -v option.

Firmware Flashing Procedure¶

1. Install Required software on the host computer

2. On the host computer extract the firmware_recovery.tar.gz archive containing the flash_firmware script:

   $ tar xvf firmware_recovery.tar.gz
   

3. Set the FPGA Programming DIP Switch to 001 as shown in the image

4. Connect a USB cable between the host and the FPGA Programming JTAG Module - U23 as shown in Figure 1.
5. Boot the AIR-T so that power is provided to the FPGA.

6. Run the flash_firmware script on the host machine:

   $ sudo ./flash_firmware -a <HARDWARE_VERSION>
   

   where the HARDWARE_VERSION is the subfolder that is relevant to your AIR-T hardware.

7. You should now be able to run the load_flash based steps from the "Firmware Installation" procedure above.