Skip to content

FPGA Autoloading

Jump to bottom
Jon Szymaniak edited this page Jul 22, 2015 · 35 revisions

Table of Contents

Overview

There are currently two ways to have the FPGA automatically loaded when you begin using the bladeRF: a host-software based mechanism, and a firmware-based mechanism.

These "autoload" mechanisms alleviate the need to manually load the FPGA via the bladeRF-cli or using the bladerf_load_fpga() function.

Host software-based

As of version 0.16.0, libbladeRF provides a mechanism to load an FPGA when a device handle is opened, if the FPGA is detected to not already be in a configured state.

This approach is generally recommended over the firmware-based mechanism for users who will always be using the bladeRF device with a host machine.

Upon opening a device handle, libbladeRF checks the device's FPGA size. It then searchs for the corresponding FPGA bitfile (hostedx40.rbf or hostedx115.rbf) in one of the following locations. The order in which these locations are searched is from top to bottom.

Simply place (or symlink, for *nix users) the FPGA bitfile in one of these directories and it will be loaded when you first open the device handle.

Linux or OSX

  • The directory specified by the BLADERF_SEARCH_DIR environment variable (As of 2014-12-10)
  • The current working directory (As of 2014-12-10)
  • The directory containing the program being executed. (As of 2014-12-10)
  • your_home_directory/.config/Nuand/bladeRF/ (libbladeRF v0.16.0 +)
  • your_home_directory/.Nuand/bladeRF/ (libbladeRF v0.16.0 +)
  • ${CMAKE_INSTALL_PREFIX}/share/Nuand/bladeRF/ (libbladeRF v1.4.2 +)
  • ${CMAKE_INSTALL_PREFIX}/etc/Nuand/bladeRF/ (libbladeRF v1.4.2 +)
  • /usr/share/Nuand/bladeRF/ (libbladeRF v0.16.0 +)
  • /etc/Nuand/bladeRF/ (libbladeRF v0.16.0 +)

The user's home directory is determined via $HOME, and then /etc/passwd (via getpwuid()) if $HOME is not valid.

Note that the last two entries in the list may be duplicates of the two that precede them. This is intentional, and is intended to provide reverse compatibility and avoid breaking packaging scripts that were forced to install files in to /usr/share/Nuand/bladeRF, even if a different ${CMAKE_INSTALL_PREFIX} was used.

Windows

  • The directory specified by the BLADERF_SEARCH_DIR environment variable (As of 2014-12-10)
  • The current working directory (As of 2014-12-10)
  • The directory containing the program being executed. (As of 2014-12-10)
  • C:\Users\<user name>\AppData\Roaming\Nuand\bladeRF (via FOLDERID_RoamingAppData) (libbladeRF v0.16.0 +)
  • The installation directory, via the HKEY_LOCAL_MACHINE\Software\Nuand LLC\Path registry key (libbladeRF v0.17.0 +)

Firmware-based

Another option is to write an FPGA-bitstream to the device's SPI flash. When the firmware boots, it checks for the presence of FPGA metadata, and will begin to load the FPGA if a bitstream is present.

This process is slower than the host-based mechanism mentioned above. However, this mechanism allows for "headless" (without a host PC) operation. It takes approximately 4 seconds to load an x40 image, and ~12 seconds to load an x115 image.

IMPORTANT: Be sure that the firmware autoload has completed before attempting to use the device (i.e., open a device handle)! When the FPGA is fully configured, LEDs 1-3 will be lit. As of FX3 firmware v1.8.0 and libbladeRF v1.0.0, bladerf_open() will block and wait until the device reports that its initialization (including autoloading) have completed. Therefore, using the aforementioned versions or later alleviates this concern.

The FPGA may be written to the bladeRF's SPI flash via the CLI: 

bladeRF-cli -L path/to/hostedx(size).rbf

To disable this autoload mechanism, erase the FPGA image and metadata. This can also be done via the CLI: 

bladeRF-cli -L X

IMPORTANT: It is highly recommended that you disable FPGA autoload prior to upgrading device firmware in order to avoid any potential conflicts.

Clone this wiki locally