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.

NOTE: IF YOU ARE HAVING ISSUES FLASHING YOUR AIR-T, PLEASE TAKE A LOOK AT OUR AIRSTACK INSTALLATION FAQ.

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
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.
If you are upgrading from a version of AirStack older than 0.5.0, you will need to follow the steps in the Creating the Recovery Partition section below.

Firmware Flash Procedure¶

Locate the new AirStack firmware image .bit file to install. Your AirStack firmware file name may be found by executing the following command on a terminal:
```
$ ls /lib/firmware/AirStack_Firmware*
```
which should produce an output similar to the following:
```
/lib/firmware/AirStack_Firmware_8000_xc7a200t_v0.5.6-1.bit
```
In this example, the firmware to install is AirStack_Firmware_8000_xc7a200t_v0.5.6-1.bit, but the file may have a different name on your system. If you have multiple firmware .bit files, then you will need to choose the one that corresponds to the version of AirStack you are installing and the corresponding FPGA part number, e.g., 75T (AIR7101) vs 200T (AIR7201, AIR8201). The FPGA part may also be found in the sensors Hardware Product Guide in the AIR-T section of the navigation menu.
Install the new firmware found in the previous step onto partition 1 of the FPGA. You will use the load_flash utility with the -i 1 argument to load the AirStack Firmware .bit file. Use the following command:
```
load_flash -i 1 /lib/firmware/AirStack_Firmware_8000_xc7a200t_v0.5.6-1.bit
```
where you will replace the file name with the one found on your hardware.

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.
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. For AIR7000 series models, please read Reference [1] below.

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.

Creating the Recovery Partition¶

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.

NOTE: All version of AirStack 0.5+ have the recovery partition created at the factory, so you may skip this step if your version of AirStack is > 0.5.0.

If you are upgrading from AirStack < 0.5.0, then you will need to create a recovery partition. Having this partition in your FPGA firmware memory significantly reduces the likelihood of bricking your AIR-T.

Locate the recovery firmware image. Your recovery firmware file name may be found by executing the following command:
```
ls /lib/firmware/AIR-T_Recovery_Firmware*
```
which should produce an output similar to the following:
```
/lib/firmware/AIR-T_Recovery_Firmware_xc7a200t_v0.5.0-1.bit
```
In this example, the firmware to install is AIR-T_Recovery_Firmware_xc7a200t_v0.5.0-1.bit, but the file may have a different name on your system. If you have multiple firmware recovery .bit files, then you will need to choose the one that corresponds to FPGA part number, e.g., 75T (AIR7101) vs 200T (AIR7201, AIR8201). The FPGA part may also be found in the sensors Hardware Product Guide in the AIR-T section of the navigation menu.
Install the recovery firmware found in the previous step onto partition 0 of the FPGA. You will use the load_flash utility with the -i 0 argument to load the AIR-T_Recovery .bit file. Use the following command:
```
load_flash -i 0 /lib/firmware/AIR-T_Recovery_Firmware_xc7a200t_v0.5.0-1.bit
```
where you will replace the file name with the one found on your hardware.

If the load_flash utility fails, you will need to use steps from the Firmware Recovery page to return to a state where load_flash is functional.

References¶

The usage of the fpga_reload command on all 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 Remote Firmware Upgrades procedure.

Last update: August 3, 2023