bladeRF/hdl
Rey Tucker 455b5bcb79 hdl: update with fixes from public-facing repo
This includes everything but AGC-related stuff.

Squashed commit of the following:

commit ab00f2a68353024c5faf14dedbb5fd05a8438f26
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Wed Aug 9 10:58:08 2017 -0400

    libbladeRF: add compilation hint to boilerplate.c

    h/t owen on IRC

commit 3cbeaf72dbe22525a5c907dfb9643db81c7aca85
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Mon Aug 7 12:27:21 2017 -0400

    host/CMakeLists: dequote variables in ifs (CMP0054) #511

    Per CMake Policy CMP0054, the meaning of constructs like

    if("${FOOBAR}" STREQUAL "quux")

    is ambigious, and the old meaning is deprecated.

    https://cmake.org/cmake/help/git-stage/policy/CMP0054.html

commit 73376b7aac65d945c5399a5130aca33265080653
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Fri Aug 4 13:40:37 2017 -0400

    host/README.md: add pthreads-win32 build instructions (#447)

    On recent versions of Windows / Visual Studio, struct timespec is
    already defined, and the definition is subtly different than what
    pthreads-win32 is built with.

    It may be possible to handle this in a more automatic fashion via CMake,
    but this is TBD.

commit b90ff648e5cf754a29264f2a2c2c19d924c5c070
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Mon Aug 7 18:09:30 2017 -0400

    host/cmake/CyAPI: define Windows 10 support

    This requires that the user get special additional drivers in addition
    to the ones provided by the usual SDK; a URL will point in the right
    direction.

    Note that this does not remove the requirement for driver signing.  Some
    work will be needed to document how to do this.

commit 888254b975f3b64ec787c741b937a561a08ccc44
Author: Jon Szymaniak <jon.szymaniak@nuand.com>
Date:   Thu Jun 9 17:47:21 2016 -0400

    libbladeRF: Treat incompatible OS version as "not found" in FindCyAPI.cmake

commit a9e97b2de6c22539266447f755e5a42cdf9a4f70
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Mon Aug 7 11:35:16 2017 -0400

    host/libbladeRF/cyapi: ReleaseMutex before CloseHandle

    When working on mutexes for the libusb backend, I noticed that I needed
    to ReleaseMutex() when closing the device, or else that device would not
    be usable again until all of the mutexes were released.

    I have not tested this with CyAPI as yet, but I believe the same problem
    will occur, and I also believe this may fix it.

commit b897475aa1a5b80358fcf2c8902089740d04582f
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Fri Aug 4 18:00:34 2017 -0400

    host/libusb.c: properly release/close handles

commit f9b99ee7715af1ccb64d41d3363a3cc8e66aa063
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Fri Aug 4 17:17:29 2017 -0400

    host/libusb.c: fix create_device_mutex errors (#484)

    This builds and correctly enforces exclusive access under Windows 10.

commit 6e9c048ff2e8321052c3e72e14f51eb2aa66b5dc
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Thu Aug 3 13:14:51 2017 -0400

    host/backend/libusb: enforce exclusive access (#484)

    Windows seems to allow multiple instances of libbladeRF to open the same
    device, which is problematic in many ways.  This borrows the mutex
    approach from cyapi.c to enforce exclusivity.

commit 519f26b6b88d1cbdfec7138fe9a0fc13715c7f93
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Fri Aug 4 16:07:49 2017 -0400

    host/cmake: search for pthreadVC2.dll more vigorously (#517)

    With the pre-built binary pack, pthreadVC2.dll lives in a
    dll/${ARCHITECTURE}/ directory.  However, when compiling from scratch,
    it just lives in the source code's root directory.  Look in both places
    and set a LIBPTHREADSWIN32_DLL variable accordingly.

commit b7617cda8e87396da19101f10de02619d0fd8e1d
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Wed Aug 2 18:05:33 2017 -0400

    CONTRIBUTORS: self-updating

commit 3a4e57b3c2f2b9ac27db832de0bbc945c3217dd7
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Tue Jul 25 15:07:54 2017 -0400

    debian: chmod 0444 downloaded fpga/fw images

    The mktemp/wget workflow creates the data files chmod 0600, which breaks
    loading of firmware for non-root users.  Explicitly chmod 0444 to allow
    all users to read.

commit 24594d3e34eca05c2fc738dc2fa5d1fcc9ab0bda
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Wed Aug 2 17:34:11 2017 -0400

    host: add note about Fedora and /usr/local (#490)

commit 6219e15a38c8dfe957e12ce38fbd76e0bf40a177
Author: Rey Tucker <rey.tucker@nuand.com>
Date:   Wed Aug 2 15:35:27 2017 -0400

    nios: fix si5338_write typo (#491)

    Unnecessary bit is being set when writing address.

commit 0d14e6ec0a3d438c206f4d02a95aa4b250ec3674
Author: Oliver Jowett <oliver@mutability.co.uk>
Date:   Thu Apr 27 21:03:12 2017 +0100

    Document why postinst should succeed if the FPGA download fails

commit 84042b6aa5bcc761c631a06687dc690343f4d952
Author: Oliver Jowett <oliver@mutability.co.uk>
Date:   Thu Apr 27 13:20:25 2017 +0100

    Don't make postinst fail entirely (producing half-configured packages and
    making the overall install operation fail) if the FPGA download fails.

    (cherry picked from commit 13befc071b3cddb913ce961c3cd7b08216bba2e5)

commit b203fbca8c789d8a99bbef34e20feda9d1a6e940
Author: ifrasch <fraschi17@gmail.com>
Date:   Sat Feb 18 17:28:59 2017 -0500

    hdl: Fixed simulation files

    -Added missing ports to nios_system.vhd
    -Added missing files to nuand.do
    -Compile.do will now compile successfully in Modelsim
2017-12-21 12:55:07 -05:00
..
fpga hdl: update with fixes from public-facing repo 2017-12-21 12:55:07 -05:00
quartus bladerf-micro: build: Add hosted message suppression file 2017-12-21 12:55:01 -05:00
CHANGELOG hdl: bump the FPGA version to 0.7.1 2017-12-07 21:07:08 -08:00
README.md hdl: missed one Web Edition reference on the README 2017-08-02 15:55:32 -04:00

bladeRF HDL Source

The Cyclone IV FPGA is at the heart of the bladeRF. It interfaces to the Cypress FX3, Lime Micro LMS6002D RF transceiver, Si5338 clock generator chip, and VCTCXO trim DAC. It has an input to read NMEA from a GPS as well as a 1pps input for time synchronization of signals and has a reference input for a reference clock to tame the VCTCXO. Lastly, it connects directly to the expansion header for controlling GPIO or any other interfaces that may reside on the expansion board.

The HDL is separated out into two different sections:

Directory Description
fpga Source HDL in the form of IP blocks or platform specific top levels
quartus Specific files for Quartus Prime project creation and building

IP, as it is added to the repository, falls under the category of who created the IP. Some IP is created by Altera tools and remains in an Altera directory. Some has been written by nuand or has been downloaded from OpenCores. These blocks should be seen as independent from the platform and, essentially, building blocks for the entire platform.

Currently, the only platform we have is bladeRF. As more platforms come out, more top levels will be created but the same IP should be able to be used with any of those platforms.

Pre-compiled FPGA Binaries

Some FPGA binaries are available for download. Please note the md5 hash as well as the git commit hash.

Required Software

We use an Altera Cyclone IV E FPGA. The size of the FPGA is the only difference between the x40 and x115 models. Altera provides their Quartus Prime software for synthesizing designs for their FPGAs. The Lite Edition is free of charge, but not open source, and may require registering on their site to download the software.

Important Note: Be sure to download Quartus Prime version 17.0, which the bladeRF project files are based upon. The updates to Quartus Prime 17.0 are not reverse-compatible with earlier Quartus versions, nor will future versions necessarily be reverse-compatible with 17.0.

HDL Structure

Since the FPGA is connected and soldered down to the board, it makes sense to have a single top level which defines where the pins go, their IO levels and their genera directionality. We use a single bladerf.vhd top level to define a VHDL entity called bladerf that defines these pins.

We realize people will want to change the internal guts of the FPGA for their own programmable logic reasons. Because of this, we decided to differentiate the implementations using a feature of the Quartus Prime project file called Revisions. Revisions can take a base design (top level entity, a part and pins) and duplicate that project, recording any source level changes you wish to make to the project. This way, a user must only create their own architecture that is the new implementation of the bladerf top level.

This technique can be seen with the currently supported architectures:

Architecture Description
hosted Listens for commands from the USB connection to perform operations or send/receive RF.
atsc_tx ATSC transmittter - Reads 4-bit ATSC symbols via USB and performs pilot insertion, filtering, and baseband shift.

Building the Project

The Quartus Prime build tools supports TCL as a scripting language which we utilize to not only create the project file, but build the system without requiring the need of the GUI. Currently, the build_bladerf.sh performs some environment checks, builds the NIOS BSP and software, and then kicks off TCL scripts to build the FPGA image.

To support multiple versions of Quartus Prime on the same machine and to ensure the environment is appropriately setup, please use the nios2_command_shell.sh script to get into an appropriate Quartus Prime environment. Note that this shell script is usually located in the nios2eds directory of your Quartus Prime install directory. Also note that this is the preferred method regardless of using Windows or Linux to build. If you're using pybombs, make sure you haven't run setup_env.sh, as it prevents nios2_command_shell.sh from working properly.

  1. Take note of which Altera Cyclone IV you have. (The EP4CE40 is 40 kLE, and the EP4CE115 is 115 kLE.) You'll need this size below...
  2. Enter the quartus directory
  3. Execute, from inside an appropriate NIOS II command shell, ./build_bladerf.sh -h to view the usage for the build script. Note the size and revision options. Also note any items you'll need to add to your PATH before continuing.
  4. Execute, from inside an appropriate NIOS II command shell, ./build_bladerf.sh -s <size> -r <revision>, with the relevant size for your bladeRF, and the desired revision. This will create the NIOS system and software associated with the FPGA build needed by the internal RAM for execution.
  5. The output of the build will be stored in a directory named in the form, <revision>x<size>-<build time>. This directory will contain the bitstream, summaries, and reports.

Note that there will be a lot of information displayed from notes to critical warnings. Some of these are benign and others are, in fact, critical.

Adding Signal Tap

For advanced users who want to use Signal Tap internal logic analyzer in their design, the build.tcl file can be passed a -stp flag which will add the Signal Tap file to the project before building it:

quartus_sh -t ../build.tcl -rev hosted -size 115 -stp ../signaltap/debug_rx.stp

Note that to use Signal Tap with the Quartus Prime Lite Edition software, Altera requires that the TalkBack feature be enabled. The build script tries to 'fake' this out by setting the TalkBack feature to be on, compiling the project, then turning it off immediately. If this behavior is not desired, don't try to add a Signal Tap file to the project.