Ettus Knowledge Base - User contributions [en]

Running UHD and GNU Radio on NI USRP-RIO

2018-04-17T15:08:02Z

NicolasCuervo: /* Flashing FPGA Image */

==Application Note Number==
'''AN-638'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-05-01
|style="text-align:center;"| Neel Pandeya Nate Temple
|style="text-align:center;"| Initial creation
|}

==Abstract==
This AN explains the process to updating your USRP-Rio to run UHD and GNU Radio.

==Overview==
This application note will cover the details of converting your NI-USRP RIO into an equivalent X300/X310 USRP. Once it is converted into a X300/X310, you will be able to use the UHD API, GNU Radio and RFNoC as you would a Ettus Research USRP.

==Warning==
Opening the chassis and changing the daughterboards will void your NI warranty. NI will not be able to provide support for UHD, GNU Radio, or RFNoC. Support questions should be directed to the [[Mailing Lists|usrp-users]] and [[Mailing Lists|discuss-gnuradio]] mailing lists or to [mailto:support@ettus.com support@ettus.com].

==Prerequisites==
This guide assumes that your USRP-Rio already has a valid IP address, and that you can ping the device.

==Installing UHD==
You will need to install UHD 3.9.4 on to your host system. For more information on installing UHD, please see the Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux|Linux]], [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on OS X|OS X]] and [[Building and Installing the USRP Open Source Toolchain (UHD and GNU Radio) on Windows|Windows]] Application Notes.

==Downloading FPGA Images==
After UHD is installed, run the following command to download the corresponding FPGA images.

sudo uhd_images_downloader

==Flashing FPGA Image==
Once the FPGA images are downloaded, you are ready to flash the FPGA image with the following command. Note, you will need to update the IP address of the USRP-Rio and the path to the FPGA image in the following command. Ensure power to the USRP-Rio and host computer is not interrupted during the flashing process. You will need to update the IP Address and FPGA Path in the following command.

If you are loading it via Ethernet:
Automatic FPGA path, detect image type:
uhd_image_loader --args="type=x300,addr=<IP address>"

If you are using PCI Express, then:
Automatic FPGA path, detect image type:
uhd_image_loader --args="type=x300,resource=<NI-RIO resource>"

Further information regarding the way to load FPGA images into the X3X0 device can be found in our [https://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_flash manual page]

Once the FPGA burner utility is completed, power cycle the USRP-Rio.

==Testing==
After you power cycle the USRP-Rio, test it with the following command.

uhd_usrp_probe

==Installing GNU Radio==
For details instructions on installing GNU Radio, please reference the GNU Radio section of the Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux|Linux]] and [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on OS X|OS X]] Application Notes.

==Testing GNU Radio==
Once GNU Radio is installed, you can test the operation of the USRP-Rio with the following utility.

uhd_fft

For a more detailed and through testing procedure, please see the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] Application Note.

==RFNoC==
For detailed instructions on setting up RFNoC, please see the [[RFNoC Getting Started Guides]] page.

[[Category:Application Notes]]

Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux

2018-04-13T16:07:29Z

NicolasCuervo: /* Building and installing GNU Radio from source code */

==Application Note Number==
'''AN-445'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-05-01
|style="text-align:center;"| Neel Pandeya
|style="text-align:center;"| Initial creation
|}

==Abstract==
This Application Note provides a comprehensive guide for building, installing, and maintaining the open-source toolchain for the USRP (UHD and GNU Radio) from source code on the Linux platform. The Ubuntu and Fedora distributions are specifically discussed. Several other alternate installation methods are also discussed.

http://files.ettus.com/manual/page_build_guide.html#build_instructions_unix

==UHD on Linux==

UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

==Devices==
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, N210 devices. The E310 and E312 devices are embedded devices, and are fundamentally different from the other non-embedded USRP devices, and are not addressed by this document.

==Using a Virtual Machine (VM)==
UHD may be installed and run within a Virtual Machine (VM), such as VMware and VirtualBox. There are some special issues to address when running UHD within a VM, and these are discussed in a separate Application Note. If you are using VirtualBox, we recommend using version 5.x.

==Install Linux==

If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a fresh new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 14.04, Ubuntu 16.04, Ubuntu 17.04, Fedora 21, Fedora 22, Fedora 23, Fedora 24, Fedora 25 and that you use a 64-bit architecture, not a 32-bit architecture. There are several re-spins of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should also work. For the purposes of this document, these re-spins can be considered equivalent. Other recent versions of Ubuntu such as 14.10, 15.04, 15.10 should also work. Both Ubuntu and Fedora are known to work well with UHD and GNU Radio.

Download and install Ubuntu, Xubuntu, Linux Mint, or Fedora from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.

* [http://www.ubuntu.com/download/desktop Ubuntu download page]
* [http://www.xubuntu.org/getxubuntu/ Xubuntu download page]
* [https://www.linuxmint.com/download.php Linux Mint download page]
* [https://getfedora.org/en/workstation/download/ Fedora download page]

You can learn more about Ubuntu, Xubuntu, Linux Mint, and Fedora at the links below.

* [https://en.wikipedia.org/wiki/Ubuntu_%28operating_system%29 Wikipedia article on Ubuntu]
* [https://en.wikipedia.org/wiki/Xubuntu Wikipedia article on Xubuntu]
* [https://en.wikipedia.org/wiki/Linux_Mint Wikipedia article on Linux Mint]
* [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Wikipedia article on Fedora]

There are many tools for writing an ISO image to a USB flash drive. In Linux, you can use the "dd" utility, or the UNetbootin utility. On Ubuntu systems, there is also the Startup Disk Creator utility as well.

* [http://unetbootin.sourceforge.net/ UNetbootin homepage]
* [http://en.wikipedia.org/wiki/UNetbootin Wikipedia article on UNetbootin]

* [https://launchpad.net/usb-creator Startup Disk Creator homepage]
* [https://en.wikipedia.org/wiki/Startup_Disk_Creator Wikipedia article on Startup Disk Creator]
* [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-ubuntu Article about Startup Disk Creator]

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

==Update and Install dependencies==

Before building UHD and GNU Radio, you need to make sure that all the dependencies are first installed.

However, before installing any dependencies, you should first make sure that all the packages that are already installed on your system are up-to-date. You can do this from a GUI, or from the command-line, as shown below.

On Ubuntu systems, run:

sudo apt-get update

On Fedora 21 systems, run:

sudo yum update

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf update

Once the system has been updated, then install the required dependencies for UHD and GNU Radio.

On Ubuntu 17.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq

On Ubuntu 16.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq

On Ubuntu 15.04 and 15.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-1.13-0v5 libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq

On Ubuntu 14.04 and 14.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq1 libzmq-dev python-requests python-sphinx libcomedi-dev

On Fedora 21 systems, run:

sudo yum -y groupinstall "Engineering and Scientific" "Development Tools" "Software Development Tools" "C Development Tools and Libraries"

sudo yum -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel qt qt4 qt4-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake git wget python-docutils cppzmq-devel PyQwt PyQwt-devel qwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc orc-devel python-sphinx SDL-devel swig zeromq2-devel python-zmq comedilib comedilib-devel thrift-devel python-thrift scipy zeromq zeromq-devel

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf -y groupinstall "Engineering and Scientific" "Development Tools" "C Development Tools and Libraries"

sudo dnf -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake python-docutils PyQwt PyQwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc-devel python-sphinx SDL-devel swig perl-ZMQ-LibZMQ2 perl-ZMQ-LibZMQ2 zeromq zeromq-devel python-requests gcc-c++ doxygen zeromq-ada-devel cppzmq-devel perl-ZeroMQ amavisd-new-zeromq amavisd-new-snmp-zeromq php-zmq python-zmq czmq uwsgi-logger-zeromq comedilib comedilib-devel pygtk2 ncurses-"*" thrift-devel python-thrift scipy

After installing the dependencies, you should reboot the system.

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

==Building and installing UHD from source code==

UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.10.1.0, which is the the latest release at the time of this writing.

* [https://github.com/EttusResearch/uhd/tree/release_003_010_001_000 UHD repository on GitHub]

There are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple UHD versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

To build UHD from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea-uhd
cd workarea-uhd

Next, clone the repository and change into the cloned directory.

git clone https://github.com/EttusResearch/uhd
cd uhd

Next, checkout the desired UHD version. You can get a full listing of tagged releases by running the command:

git tag -l

''Example truncated output of <code>git tag -l</code>:''

<pre>
$ git tag -l
...
release_003_009_004
release_003_009_005
release_003_010_000_000
</pre>

'''Note''': As of UHD Version 3.10.0.0, the versioning scheme has changed to be a quadruplet format. Each element and version will follow the format of: '''Major.API.ABI.Patch'''. Additional details on this versioning change can be found [https://files.ettus.com/manual/page_semver.html here].

After identifying the version and corresponding release tag you need, check it out:

# Example: For UHD 3.9.5:
git checkout release_003_009_005

# Example: For UHD 3.10.1.0:
git checkout release_003_010_001_000

Next, create a build folder within the repository.

cd host
mkdir build
cd build

Next, invoke CMake to create the Makefiles.

cmake ../

Next, run Make to build UHD.

make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Next, update the system's shared library cache.

sudo ldconfig

Finally, make sure that the <code>LD_LIBRARY_PATH</code> environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your <code>$HOME/.bashrc</code> file:

export LD_LIBRARY_PATH=/usr/local/lib

On Fedora 22/23/24/25 you will need to set the <code>LD_LIBRARY_PATH</code> to <code>/usr/local/lib64</code>.

export LD_LIBRARY_PATH=/usr/local/lib64

If the <code>LD_LIBRARY_PATH</code> environment variable is already defined with other folders in your <code>$HOME/.bashrc</code> file, then add the line below to the end of your <code>$HOME/.bashrc</code> file to preserve the current settings.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For Fedora 21/22/23/24/25

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib64

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running <code>uhd_find_devices</code>. You should see something similar to the following.

<pre>
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

No UHD Devices Found
</pre>

==Building and installing GNU Radio from source code==

As with UHD, GNU Radio is open-source and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.7.10.1, which is the the latest release at the time of this writing.

* [https://github.com/gnuradio/gnuradio/tree/v3.7.10.1 GNU Radio repository on GitHub]

As with UHD, there are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple GNU Radio versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

Similar to the process for UHD, to build GNU Radio from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea-gnuradio
cd workarea-gnuradio

Next, clone the repository.

git clone --recursive https://github.com/gnuradio/gnuradio

Next, go into the repository and check out the desired GNU Radio version.

cd gnuradio
git checkout v3.7.10.1
git submodule update --init --recursive

Next, create a build folder within the repository.

mkdir build
cd build

Next, invoke CMake to create the Makefiles.

cmake ../

Next, run Make to build GNU Radio.

make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install GNU Radio, using the default install prefix, which will install GNU Radio under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Finally, update the system's shared library cache.

sudo ldconfig

At this point, GNU Radio should be installed and ready to use. You can quickly test this, with no USRP device attached, by running the following quick tests.

gnuradio-config-info --version
gnuradio-config-info --prefix
gnuradio-config-info --enabled-components

There is a simple flowgraph that you can run that does not require any USRP hardware. It's called the dialtone test, and it produces a PSTN dial tone on the computer's speakers. Running it verifies that all the libraries can be found, and that the GNU Radio run-time is working.

python $HOME/workarea-gnuradio/gnuradio/gr-audio/examples/python/dial_tone.py

You can try launching the GNU Radio Companion (GRC) tool, a visual tool for building and running GNU Radio flowgraphs.

gnuradio-companion

If "gnuradio-companion" does not start and complains about the <code>PYTHONPATH</code> environment variable, then you may have to set this in your <code>$HOME/.bashrc</code> file, as shown below.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

On Fedora 21/22/23/24, the <code>PYTHONPATH</code> environment variable will need to be set to:

export PYTHONPATH=/usr/lib/python2.7/site-packages:/usr/local/lib64/python2.7/site-packages/

==Configuring USB==

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. This step is only necessary for devices that use USB to connect to the host computer, such as the B200, B210, and B200mini. This setting should take effect immediately and does not require a reboot or logout/login. Be sure that no USRP device is connected via USB when running these commands.

cd $HOME/workarea-uhd/uhd/host/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Configuring Ethernet==

For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with <code>ifconfig</code>, Network Manager will probably overwrite these settings.

==Connect the USRP==

The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run "<code>lsusb</code>". You should see the USRP listed on the USB bus with a VID of <code>2500</code> and PID of <code>0020</code>, <code>0021</code>, <code>0022</code>, for B200, B210, B200mini, respectively.

Also try running "<code>uhd_find_devices</code>" and "<code>uhd_usrp_probe</code>".

==Thread priority scheduling==

When UHD spawns a new thread, it may try to boost the thread's scheduling priority. If setting the new priority fails, the UHD software prints a warning to the console, as shown below. This warning is harmless; it simply means that the thread will retain a normal or default scheduling priority.

<pre>
UHD Warning:
Unable to set the thread priority. Performance may be negatively affected.
Please see the general application notes in the manual for instructions.
EnvironmentError: OSError: error in pthread_setschedparam
</pre>

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. To enable this, add the line below to the file <code>/etc/security/limits.conf</code>.

@GROUP - rtprio 99

Replace <code>GROUP</code> with a group in which your user is a member. You may need to log out and log back into the account for the settings to take effect. In most Linux distributions, a list of groups and group members can be found in the <code>/etc/group</code> file.

There is further documentation about this in the User Manual at the link below.

* [http://files.ettus.com/manual/page_general.html#general_threading_prio Threading Notes section of the User Manual]

[[Category:Application Notes]]

Debugging FPGA images

2017-12-29T17:40:21Z

NicolasCuervo: /* Overview */

= Application Note Number =
'''AN-121'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo Sugandha Gupta
|style="text-align:center;"| Initial creation
|}

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some FPGA code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench. In addition, there is plenty of online resources (such as [8]) that provide enough information to get you started with your simulation.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

* '''UHD, GNURadio and gr-ettus: ''' At the end of the debugging process we will be running the application on a physical device, and for that we need the core code downloaded and installed. UHD will serve as our device driver, GNURadio the frame on which our app will run, and gr-ettus is needed for our ''signal generator'' block. If you need guidance on this, please refer to the [https://kb.ettus.com/Getting_Started_with_RFNoC_Development#Creating_a_development_environment Creating a development environment] section of our ''Getting started guide''. If you are debugging your own RFNoC OOT module, this will have to be installed as well.

* '''RFNoC supported device: ''' The whole point of chipscoping is having the ability of probing signals from a hardware design at runtime. Hence, a device where the application is going to run is needed. In this tutorial we will be using an X310 device.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./uhd_image_builder.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">uhd_image_builder.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">uhd_image_builder.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =
After the bitstream generation is completed successfully, it is time for us to move on and put our design into the device. On the left pannel, right below we generated our bitstream, is the "Hardware Manager". At this point, we have our X310 connected via JTAG for programming purposes, and via Ethernet (1G in this specific use case) for later usage. Now, click on 'Open Target'. If you have only one device connected, the option "auto-connect" should work just fine. Otherwise, select your device by clicking on "Open new target" and following the options in order to find the device you want. After doing so, two options should appear at the top of your Vivado window:

[[File:cs_6.png|center|Hardware options|link=https://kb.ettus.com/images/9/9e/cs_6.png]]

As a first step, click on "Program device". Usually, again, Vivado picks up the bitstream that you just generated. However, if you have been running multiple bitstream builds and/or have multiple Vivado projects, it is possible that you would have to look for the right bitstream. It should be under the project that you have been working during the generation of your debug bitstream.

After programing, you have to run an initialization routine on your device. A way to do this is to run a usrp probe, which will also tell us several interesting information. In a terminal, run:

$ uhd_usrp_probe

This will tell you information about the device. In our case, the last portion of the output should look like this:

| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * SigGen_0
| | | * DUC_0
| | | * DDC_0

which tells us that the blocks '''Signal Generator, DUC and DDC''' were correctly added into the device. Keep in mind that the DmA FIFO and two instances of the radio are added by default into an X310 device. Now, go back to the Vivado GUI and click on "Refresh device" right on the top of the Vivado Window. After that, your debugging signals should appear and you are ready to start chipscoping.

== Selecting Triggers ==
While probing your design, you probably want to know the state of a given signal right at the moment at which it or other signal changed. In some cases you can have a short simulation and you can ''eye-ball'' your signals and see if the results are as expected. However, sometimes signals change very fast or have a really short duration, making a qualitative procedure a little bit more complicated. For that case, you can set up '''triggers''', which means that the chipscope tool will start capturing when a desired signal changes. We are going to use this feature here and is recommended to do so to have more control over the signal capturing.

[[File:cs_7.png|center|Trigger Setup|link=https://kb.ettus.com/images/e/e1/cs_7.png]]

Here we are going to choose two signals as triggers, which are '''s_axis_data_tvalid''' and '''s_axis_data_tready'''. The names are almost self explanatory: they state when the device has valid data and when it is ready (see [4] for further information). After choosing this signals, now we have to put our device to work. Even, you can click on "run trigger for this ILA core", which will let the device on idle state waiting for the trigger.

[[File:cs_9.png|center|Trigger Setup. You can also see the black panel where all the debug lines are listed.|link=https://kb.ettus.com/images/7/74/cs_9.png]]

== Debugging at run time ==
This is what we came for. The block is to be put in a normal use case where it will run and, simultaneously, we will probe signals from it. For the '''RFNoC: Signal Generator''', we are going to use GNURadio to set up the application. Actually, we are going to use the siggen example that is shipped within ''gr-ettus''. We open to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}{path_to_gr-ettus}/examples/rfnoc/rfnoc_siggen.grc</syntaxhighlight>, where a simple setup is ready to show the siggen working.

[[File:cs_8.png|center|GNURadio example for the RFNoC: Signal Generator block|link=https://kb.ettus.com/images/d/d1/cs_8.png]]

You can see that there is a number of options which can be modified. As we choose to check how signal such as "Wave type" and "gain", we are going to focus on this for now. They can be modified on runtime, but every time that they are set to a different value the trigger has to be run again on the Vivado chipscope. Following are some of the expected results:

'''Signal type: Constant || Gain: 1: ''' In this case the signal "wave type" is set to 0, as it being the first option available in the block. The Gain is set to 7FFF, which is the maximum hexadecimal value that the register is able to receive in this case and which means the maximum absolute gain.
[[File:cs_10.png|center|Signal type: Constant || Gain: 1|link=https://kb.ettus.com/images/7/72/cs_10.png]]

'''Signal type: Sinusoid || Gain: 1: ''' Now the wave type is set to 1, being the next option available. The gain is unchanged to show how it holds the same value in the readback register.
[[File:cs_12.png|center|Signal type: Sinusoid || Gain: 1|link=https://kb.ettus.com/images/5/56/cs_12.png]]

'''Signal type: Noise || Gain: 0.5: ''' Wave type and gain are both changed, showing results somewhat expected: wave type is set to 2, being sequentially the next option available, and the gain is set to half of the maximum value, which is shown to be true also in its hexadecimal representation read from the readback register.
[[File:cs_14.png|center|Signal type: Noise || Gain: 0.5|link=https://kb.ettus.com/images/9/9a/cs_14.png]]

If you have come successfully until this point, then you can play around with the signals and checking the result in the debugging panel or, even better, apply this technique to debug your own RFNoC design!

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

[8] [https://www.xilinx.com/support/documentation/application_notes/xapp199.pdf Xilinx AN - Writing efficient Testbenches]

UBX

2017-12-29T17:36:47Z

NicolasCuervo: /* UBX-160 */

== Device Overview ==
The UBX daughterboard is a full-duplex wideband transceiver that covers frequencies from 10 MHz to 6 GHz. Coherent and phase-aligned operation across multiple UBX daughterboards on USRP X Series motherboards enables users to explore MIMO and direction finding applications. The UBX daughterboard works interchangeably with other USRP daughterboards and is supported by the USRP Hardware Driver™ (UHD) software API for seamless integration into existing applications.

The UBX is capable of phase coherent operation, and therefore is suitable for MIMO and Phased Array applications, on the X Series. Additionally this capability is only available on the X Series devices.

== Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 10 MHz - 6 GHz
* Versions: 40MHz / 160MHz
*RF shielding
*Full duplex operation with independent TX and RX frequencies
*Synthesizer synchronization for applications requiring coherent or phase-aligned operation, supported on USRP X Series motherboards only
|[[File:Product ubx 40.png|250px|center]]
|[[File:Product ubx 160.png|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using a UBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* UBX: 40 MHz, RX & TX
* UBX-160: 160 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* '''LOCK''': Synthesizer Lock Detect
* '''TX/RX TXD''': Transmitting on TX/RX antenna port
* '''TX/RX RXD''': Receiving on TX/RX antenna port
* '''RX2 RXD''': Receiving on RX2 antenna port

==RF Specifications==
===Freq Range===
* 10MHz - 6GHz

===Noise Figure===
* 10 MHz - 500 MHz: 3 - 4 dB
* 500 MHz - 1.5 GHz: 2 - 3 dB
* 1.5GHz - 6GHz: 4 - 10 dB

===RX IIP3 (Max)===
* 10 MHz - 6 GHz: 8 - 9 dBm

===RX IQ Imbalance===
* 10 MHz - 6 GHz: < -30dBc

===TX Power (Max)===
* 10 MHz - 3 GHz: 20 dBm
* 3 - 6 GHz: 8 - 20 dBm

===TX OIP3===
* 10 - 500 MHz: 41 dBm
* 0.5 - 3 GHz: 36 dBm
* 3 - 6 GHz: 26 dBm - 36 dBm

===TX IQ Imbalance===
* 10 MHz - 6 GHz: < -30 dBc

Note: The UBX 160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

===Input/Output Impedance===
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

===Input Power Levels===
* The maximum input power for the UBX is -15 dBm.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===UBX-40===
* Current Hardware Revision: 2
* Minimum version of UHD required for UBX rev-1: 3.8.2
* Minimum version of UHD required for UBX rev-2: 3.9.5

===UBX-160===
* Current Hardware Revision: 2
* Minimum version of UHD required for UBX rev-1: 3.8.2
* Minimum version of UHD required for UBX rev-2: 3.9.5

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===UBX-40===
* N or X Series

===UBX-160===
* X Series only

==Phase Synchronization==
The UBX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. The SBX and TwinRX daughterboards are also recommended for phase-coherent applications.

If you are operating the UBX at frequencies below 1 GHz and need phase synchronization, then it is necessary to select a 20 MHz daughterboard clock rate, instead of using the default 50 MHz rate. Note that this is only required for phase synchronization below 1 GHz. The UBX can still operate below 1 GHz without setting this lower daughterboard clock rate, but it will operate without any phase synchronization capability.

If you're using a UHD program, then you can specify the lower daughterboard clock rate on the command line of the program, with <code>--args="dboard_clock_rate=20e6"</code>.

If you're using the UHD API from a C++ program, then you can include <code>"dboard_clock_rate=20e6"</code> in the device arguments parameter when first invoking <code>multi_usrp::make()</code>.

If you're using GNU Radio, then you can add <code>"dboard_clock_rate=20e6"</code> to the <code>"Device Arguments"</code> field of the properties for the UHD Sink and UHD Source blocks.

==Schematics==
===UBX===
[http://files.ettus.com/schematics/ubx/ubx.pdf UBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[https://datasheets.maximintegrated.com/en/ds/MAX2871.pdf MAX2871]
|Fractional/Integer-N Synthesizer/VCO
|U3 (3); U9 (5); U19 (7); U23 (9)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://www.minicircuits.com/pdfs/LFCN-2250.pdf LFCN-2250+]
|Low Pass Filter
|F1 (3); F24 (7); F34, F35 (10)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-490.pdf LFCN-490+]
|Low Pass Filter
|F12 (5); F15 (6); F26 (7); F31 (9); F33, F36 (10)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U16 (6)
|-

|[http://www.rfmd.com/store/downloads/dl/file/id/29224/nbb_400_data_sheet.pdf NBB-400]
|Amplifier
|U13 (6); U30 (11)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U31 (11)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.avagotech.com/docs/AV02-1237EN MGA-62563]
|Low Noise Amplifier
|U36 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1700.pdf LFCN-1700+]
|Low Pass Filter
|F41 (11)
|-

|[http://www.avagotech.com/docs/AV02-2919EN VMMK-3603]
|Low Noise Amplifier
|U34 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (6)
|-

|[http://www.triquint.com/products/d/doc-a-00000518 855916]
|SAW Filter
|F16 (6)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6); U28 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (10)
|-

|[http://www.minicircuits.com/pdfs/TCM1-63AX+.pdf TCM1-63AX+]
|RF Transformer
|T1 (3); T2, T3 (4); T7 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591]
|Operational Amplifiers
|U7 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q1 (6)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/hmc624a.pdf HMC624ALP4E]
|ATTENUATOR
|U16 (6); U29 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-800.pdf LFCN-800+]
|Low Pass Filter
|F2 (3); F25 (7)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-3.3]
|CMOS LDO
|U4, U5 (3); U10, U11 (5); U20, U21 (7); U24, U25 (9); U48 (13)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U28 (10)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U38, U39 (12)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-5.0]
|CMOS LDO
|U41, U42, U43, U44, U45, U46, U47 (13)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q2, Q3, Q4, Q5 (13)
|-
|}

==Mechanical Information==
===Drawings===
* [[Media:cu ettus UBX cca.pdf| PDF Format]]

==RF Connectors==
* The UBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===UBX-40/UBX-160===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==Important Notes==
*A larger 24W (6V, 4A) power supply is required when using a UBX-40 daughterboard and integrated GPS Disciplined Oscillator accessory together in a USRP2, USRP N200, or USRP N210 device.
*The UBX-160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

==RF Performance Data==
* [http://files.ettus.com/performance_data/ubx/UBX-without-UHD-corrections.pdf UBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

UBX

2017-12-29T17:36:15Z

NicolasCuervo: /* UBX-40 */

== Device Overview ==
The UBX daughterboard is a full-duplex wideband transceiver that covers frequencies from 10 MHz to 6 GHz. Coherent and phase-aligned operation across multiple UBX daughterboards on USRP X Series motherboards enables users to explore MIMO and direction finding applications. The UBX daughterboard works interchangeably with other USRP daughterboards and is supported by the USRP Hardware Driver™ (UHD) software API for seamless integration into existing applications.

The UBX is capable of phase coherent operation, and therefore is suitable for MIMO and Phased Array applications, on the X Series. Additionally this capability is only available on the X Series devices.

== Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 10 MHz - 6 GHz
* Versions: 40MHz / 160MHz
*RF shielding
*Full duplex operation with independent TX and RX frequencies
*Synthesizer synchronization for applications requiring coherent or phase-aligned operation, supported on USRP X Series motherboards only
|[[File:Product ubx 40.png|250px|center]]
|[[File:Product ubx 160.png|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using a UBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* UBX: 40 MHz, RX & TX
* UBX-160: 160 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* '''LOCK''': Synthesizer Lock Detect
* '''TX/RX TXD''': Transmitting on TX/RX antenna port
* '''TX/RX RXD''': Receiving on TX/RX antenna port
* '''RX2 RXD''': Receiving on RX2 antenna port

==RF Specifications==
===Freq Range===
* 10MHz - 6GHz

===Noise Figure===
* 10 MHz - 500 MHz: 3 - 4 dB
* 500 MHz - 1.5 GHz: 2 - 3 dB
* 1.5GHz - 6GHz: 4 - 10 dB

===RX IIP3 (Max)===
* 10 MHz - 6 GHz: 8 - 9 dBm

===RX IQ Imbalance===
* 10 MHz - 6 GHz: < -30dBc

===TX Power (Max)===
* 10 MHz - 3 GHz: 20 dBm
* 3 - 6 GHz: 8 - 20 dBm

===TX OIP3===
* 10 - 500 MHz: 41 dBm
* 0.5 - 3 GHz: 36 dBm
* 3 - 6 GHz: 26 dBm - 36 dBm

===TX IQ Imbalance===
* 10 MHz - 6 GHz: < -30 dBc

Note: The UBX 160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

===Input/Output Impedance===
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

===Input Power Levels===
* The maximum input power for the UBX is -15 dBm.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===UBX-40===
* Current Hardware Revision: 2
* Minimum version of UHD required for UBX rev-1: 3.8.2
* Minimum version of UHD required for UBX rev-2: 3.9.5

===UBX-160===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.2

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===UBX-40===
* N or X Series

===UBX-160===
* X Series only

==Phase Synchronization==
The UBX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. The SBX and TwinRX daughterboards are also recommended for phase-coherent applications.

If you are operating the UBX at frequencies below 1 GHz and need phase synchronization, then it is necessary to select a 20 MHz daughterboard clock rate, instead of using the default 50 MHz rate. Note that this is only required for phase synchronization below 1 GHz. The UBX can still operate below 1 GHz without setting this lower daughterboard clock rate, but it will operate without any phase synchronization capability.

If you're using a UHD program, then you can specify the lower daughterboard clock rate on the command line of the program, with <code>--args="dboard_clock_rate=20e6"</code>.

If you're using the UHD API from a C++ program, then you can include <code>"dboard_clock_rate=20e6"</code> in the device arguments parameter when first invoking <code>multi_usrp::make()</code>.

If you're using GNU Radio, then you can add <code>"dboard_clock_rate=20e6"</code> to the <code>"Device Arguments"</code> field of the properties for the UHD Sink and UHD Source blocks.

==Schematics==
===UBX===
[http://files.ettus.com/schematics/ubx/ubx.pdf UBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[https://datasheets.maximintegrated.com/en/ds/MAX2871.pdf MAX2871]
|Fractional/Integer-N Synthesizer/VCO
|U3 (3); U9 (5); U19 (7); U23 (9)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://www.minicircuits.com/pdfs/LFCN-2250.pdf LFCN-2250+]
|Low Pass Filter
|F1 (3); F24 (7); F34, F35 (10)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-490.pdf LFCN-490+]
|Low Pass Filter
|F12 (5); F15 (6); F26 (7); F31 (9); F33, F36 (10)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U16 (6)
|-

|[http://www.rfmd.com/store/downloads/dl/file/id/29224/nbb_400_data_sheet.pdf NBB-400]
|Amplifier
|U13 (6); U30 (11)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U31 (11)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.avagotech.com/docs/AV02-1237EN MGA-62563]
|Low Noise Amplifier
|U36 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1700.pdf LFCN-1700+]
|Low Pass Filter
|F41 (11)
|-

|[http://www.avagotech.com/docs/AV02-2919EN VMMK-3603]
|Low Noise Amplifier
|U34 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (6)
|-

|[http://www.triquint.com/products/d/doc-a-00000518 855916]
|SAW Filter
|F16 (6)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6); U28 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (10)
|-

|[http://www.minicircuits.com/pdfs/TCM1-63AX+.pdf TCM1-63AX+]
|RF Transformer
|T1 (3); T2, T3 (4); T7 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591]
|Operational Amplifiers
|U7 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q1 (6)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/hmc624a.pdf HMC624ALP4E]
|ATTENUATOR
|U16 (6); U29 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-800.pdf LFCN-800+]
|Low Pass Filter
|F2 (3); F25 (7)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-3.3]
|CMOS LDO
|U4, U5 (3); U10, U11 (5); U20, U21 (7); U24, U25 (9); U48 (13)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U28 (10)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U38, U39 (12)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-5.0]
|CMOS LDO
|U41, U42, U43, U44, U45, U46, U47 (13)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q2, Q3, Q4, Q5 (13)
|-
|}

==Mechanical Information==
===Drawings===
* [[Media:cu ettus UBX cca.pdf| PDF Format]]

==RF Connectors==
* The UBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===UBX-40/UBX-160===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==Important Notes==
*A larger 24W (6V, 4A) power supply is required when using a UBX-40 daughterboard and integrated GPS Disciplined Oscillator accessory together in a USRP2, USRP N200, or USRP N210 device.
*The UBX-160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

==RF Performance Data==
* [http://files.ettus.com/performance_data/ubx/UBX-without-UHD-corrections.pdf UBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

Ettus USRP E300 Embedded Family Hardware Resources

2017-12-29T17:28:00Z

NicolasCuervo: /* FPGA */

== Device Overview ==
The USRP E31x offers a portable stand-alone SDR platform designed for field deployment. The flexible 2x2 MIMO AD9361 transceiver from Analog Devices provides up to 56 MHz of instantaneous bandwidth and spans frequencies from 70 MHz – 6 GHz to cover multiple bands of interest.

== Key Features==
===E310===
{|
|style="vertical-align:top"|
*Xilinx Zynq 7020 SoC: 7 Series FPGA with ARM Cortex A9 667 MHz (SG1) or 866 MHz (SG3) dual-core processor
*Analog Devices AD9361 RFIC direct-conversion transceiver
*Frequency range: 70 MHz - 6 GHz
*Up to 56 MHz of instantaneous bandwidth
*2x2 MIMO transceiver
*Up to 10 MS/s sample data transfer rate to ARM processor
*RX, TX filter banks
*Integrated GPS receiver
*9-axis inertial measurement unit
*RF Network on Chip (RFNoC™) FPGA development framework support
|[[File:Product e310.png|250px|center]]
|}

===E312===
{|
|style="vertical-align:top"|
*Battery Operated
*Xilinx Zynq 7020 SoC: 7 Series FPGA with ARM Cortex A9 866 MHz dual-core processor
|[[File:Product e312.png|250px|center]]
|}

===E313===
{|
|style="vertical-align:top"|
* Rugged and weatherproof for outdoor deployment
* Fully assembled IP67-rated enclosure with USRP E310 inside
* Extensive environmental testing
* Power over Ethernet (PoE) with surge and lightning protection
* Xilinx Zynq 7020 SoC: 7 Series FPGA with ARM Cortex A9 866 MHz dual-core processor
|[[File:E313.png|250px|center]]
|}

== Daughterboard Specifications==
===E31x MIMO XCVR board===
The USRP E31x MIMO XCVR daughterboard features an integrated MIMO capable RF frontend.

===Tuning===
The RF frontend has individually tunable receive and transmit chains. Both transmit and receive can be used in a MIMO configuration. For the MIMO case, both receive frontends share the RX LO, and both transmit frontends share the TX LO. Each LO is tunable between 50 MHz and 6 GHz.

===Gains===
All frontends have individual analog gain controls. The receive frontends have 76 dB of available gain; and the transmit frontends have 89.8 dB of available gain. Gain settings are application specific, but it is recommended that users consider using at least half of the available gain to get reasonable dynamic range.

===LO lock status===
The frontends provide a lo-locked sensor that can be queried through the UHD API.

<syntaxhighlight lang="c++">
// assumes 'usrp' is a valid uhd::usrp::multi_usrp::sptr instance
// get status for rx frontend
usrp->get_rx_sensor("lo-locked");
// get status for tx frontend
usrp->get_tx_sensor("lo-locked");
</syntaxhighlight>

===Filter and Antenna Switches===
The transmit and receive filter banks uses switches to select between the available filters. These paths are also dependent on the antenna switch settings. Incorrectly setting the switches generally results in attenuated input / output power. Receive filters are band pass (series high & low pass filters), transmit filters are low pass.

Source code related to controlling the filter band and antenna switches resides in <code>e300_impl.c</code>. Specifically, refer to methods <code>e300_impl::_update_bandsel</code>, <code>e300_impl::_update_atrs</code>, <code>e300_impl::_update_gpio</code>, and <code>e300_impl::_update_enables</code>. Generally, these methods set the switches depending on the state of transmit and receive streams.

The following sections provide switch setting tables for antenna and filter selection for frontends A & B receive and transmit paths. For futher details refer to the schematics.

===Side A Filter and Antenna Switches===
''Note: X = don't care, T = If full duplex, set bits according to transmit table, otherwise don't care. Filter range A – B will be selected if A <= freq < B.''

'''Receive'''

{| class="wikitable"
!RX Port
!RX Filter (MHz)
!VCTXRX2_V1,V2
!VCRX2_V1,V2
!RX2_BANDSEL[2:0]
!RX2B_BANDSEL[1:0]
!RX2C_BANDSEL[1:0]
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | < 450
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 101
| style="text-align: center" | XX
| style="text-align: center" | 01
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 450 – 700
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 011
| style="text-align: center" | XX
| style="text-align: center" | 11
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 700 – 1200
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 001
| style="text-align: center" | XX
| style="text-align: center" | 10
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 1200 – 1800
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 000
| style="text-align: center" | 01
| style="text-align: center" | XX
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 1800 – 2350
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 010
| style="text-align: center" | 11
| style="text-align: center" | XX
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 2350 – 2600
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 100
| style="text-align: center" | 10
| style="text-align: center" | XX
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 2600 – 6000
| style="text-align: center" | 01
| style="text-align: center" | 01
| style="text-align: center" | XXX
| style="text-align: center" | XX
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 70 – 450
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 101
| style="text-align: center" | XX
| style="text-align: center" | 01
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 450 – 700
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 011
| style="text-align: center" | XX
| style="text-align: center" | 11
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 700 – 1200
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 001
| style="text-align: center" | XX
| style="text-align: center" | 10
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 1200 – 1800
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 000
| style="text-align: center" | 01
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 1800 – 2350
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 010
| style="text-align: center" | 11
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 2350 – 2600
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 100
| style="text-align: center" | 10
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | >= 2600
| style="text-align: center" | TT
| style="text-align: center" | 10
| style="text-align: center" | XXX
| style="text-align: center" | XX
| style="text-align: center" | XX
|-
|}

'''Transmit'''
{| class="wikitable"

! TX Port
! TX Filter (MHz)
! VCTXRX2_V1,V2
! TX_ENABLE2A,2B
! TX_BANDSEL[2:0]
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | < 117.7
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 111
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 117.7 – 178.2
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 110
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 178.2 – 284.3
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 101
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 284.3 – 453.7
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 100
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 453.7 – 723.8
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 011
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 723.8 – 1154.9
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 010
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 1154.9 – 1842.6
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 001
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 1842.6 – 2940.0
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 000
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | >= 2940.0
| style="text-align:center;" | 11
| style="text-align:center;" | 10
| style="text-align:center;" | XXX
|-

|}

''Note: Although the transmit filters are low pass, this table describes UHD's tuning range for selecting each filter path. The table also includes the required transmit enable state.''

===Side B Filter and Antenna Switches===
''Note: X = don't care, T = If full duplex, set bits according to transmit table, otherwise don't care. Filter range A – B will be selected if A <= freq < B.''

'''Receive'''
{| class="wikitable"
! RX Port
! RX Filter (MHz)
! VCTXRX1_V1,V2
! VCRX1_V1,V2
! RX1_BANDSEL[2:0]
! RX1B_BANDSEL[1:0]
! RX1C_BANDSEL[1:0]
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | < 450
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 100
| style="text-align:center;" | XX
| style="text-align:center;" | 10
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 450 – 700
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 010
| style="text-align:center;" | XX
| style="text-align:center;" | 11
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 700 – 1200
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 000
| style="text-align:center;" | XX
| style="text-align:center;" | 01
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1200 – 1800
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 001
| style="text-align:center;" | 10
| style="text-align:center;" | XX
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1800 – 2350
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 011
| style="text-align:center;" | 11
| style="text-align:center;" | XX
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 2350 – 2600
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 101
| style="text-align:center;" | 01
| style="text-align:center;" | XX
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 2600 – 6000
| style="text-align:center;" | 10
| style="text-align:center;" | 10
| style="text-align:center;" | XXX
| style="text-align:center;" | XX
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 70 – 450
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 100
| style="text-align:center;" | XX
| style="text-align:center;" | 10
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 450 – 700
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 010
| style="text-align:center;" | XX
| style="text-align:center;" | 11
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 700 – 1200
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 000
| style="text-align:center;" | XX
| style="text-align:center;" | 01
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 1200 – 1800
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 001
| style="text-align:center;" | 10
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 1800 – 2350
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 011
| style="text-align:center;" | 11
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 2350 – 2600
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 101
| style="text-align:center;" | 01
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | >= 2600
| style="text-align:center;" | TT
| style="text-align:center;" | 01
| style="text-align:center;" | XXX
| style="text-align:center;" | XX
| style="text-align:center;" | XX
|-

|}

'''Transmit'''
{| class="wikitable"

! TX Port
! TX Filter (MHz)
! VCTXRX1_V1,V2
! TX_ENABLE1A,1B
! TX1_BANDSEL[2:0]
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | < 117.7
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 111
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 117.7 – 178.2
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 110
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 178.2 – 284.3
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 101
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 284.3 – 453.7
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 100
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 453.7 – 723.8
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 011
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 723.8 – 1154.9
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 010
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1154.9 – 1842.6
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 001
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1842.6 – 2940.0
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 000
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | >= 2940.0
| style="text-align:center;" | 11
| style="text-align:center;" | 10
| style="text-align:center;" | XXX
|-

|}

''Note: Although the transmit filters are low pass, the following table describes UHD's tuning range for selecting each filter path. The table also includes the required transmit enable states.''

==RF Specifications==
===RF Performance===
* SSB/LO Suppression -35/50 dBc
* Phase Noise 3.5 GHz 1.0 deg RMS
* Phase Noise 6 GHz 1.5 deg RMS
* Power Output >10dBm
* IIP3 (@ typ NF) -20dBm
* Typical Noise Figure <8dB

===Input Power Levels===
* The maximum input power for the E310/E312/E313 is 0 dBm.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===E310===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0
* Required version on the host computer must match what is running on the E310

===E312===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.5
* Required version on the host computer must match what is running on the E312

===E313===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0
* Required version on the host computer must match what is running on the E313

==Physical Specifications==

===Dimensions===
====E310====
* 133 x 68 x 26.4 mm

====E312====
* 133 x 68.2 x 31.8 mm

====E313====
* 186 x 280 x 106 mm

==Environmental Specifications==
===Operating Temperature Range===
* E310 0-40 °C
* E312 0-40 °C
* E313 -40-71 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==Schematics==
===E310===
[http://files.ettus.com/schematics/e310/e310.pdf E310 Schematics]

[http://files.ettus.com/schematics/e310/e310_db.pdf E310 DB]

[[Media: E310_System_Diagram.png|E310 Architecture]]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-
! colspan="3" | Motherboard
|-
|[http://www.ti.com.cn/cn/lit/ds/symlink/txs02612.pdf TXS02612RTWR]
|SDIO PORT EXPANDER
|U23 (2)
|-
|[http://www.xilinx.com/support/documentation/data_sheets/ds187-XC7Z010-XC7Z020-Data-Sheet.pdf XC7Z020-1CLG484CES9919]
|FPGA
|U11 (2,3,4,8,11,13)
|-

|[http://www.xilinx.com/products/silicon-devices/soc/zynq-7000.html Xilinx Zynq Product Page ]
|FPGA
| -
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/00001678A.pdf USB3340-EZK-TR]
|ULPI Transceiver
|U33 (5)
|-
|[http://www.akm.com/akm/en/file/datasheet/AK4571VQ.pdf AK4571VQP]
|Audio CODEC
|U30 (6)
|-
|[http://www.ftdichip.com/Support/Documents/DataSheets/ICs/DS_FT230X.pdf FT230XQ-R]
|UART Interface
|U32 (6)
|-
|[http://www.marvell.com/transceivers/assets/Alaska_88E1512-001_product_brief.pdf 88E1512]
|Gigabit Ethernet Transceiver
|U13 (7)
|-
|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210N.pdf 24LC024/SN]
|EEPROM
|U5 (9)
|-
|[http://datasheets.maximintegrated.com/en/ds/DS1339-DS1339U.pdf DS1339,SM]
|Real-Time Clock
|U6 (9)
|-
|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADT7408.pdf ADT7408]
|Temperature Sensor
|U8 (9)
|-
|[https://www.invensense.com/wp-content/uploads/2015/02/MPU-9150-Datasheet.pdf MPU-9150]
|Motion Processing Unit
|U3 (9)
|-

|[http://www.invensense.com/products/motion-tracking/9-axis/mpu-9150/ InvenSense MPU-9150 Product Page]
| Motion Processing Unit
|U3 (9)
|-

|[https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP180-DS000-121.pdf BMP180]
|Digital pressure sensor
|U4 (9)
|-
|[http://www.ti.com/lit/ds/symlink/bq24192.pdf BQ24192]
|Adapter Charger
|U1 (10)
|-
|[http://www.ti.com/lit/ds/symlink/tps54478.pdf TPS54478]
|Step-Down Switcher
|U20 (10)
|-
|[https://datasheets.maximintegrated.com/en/ds/MAX6509-MAX6510.pdf MAX6510HAUT-T]
|Temperature Switches
|U35 (10)
|-
|[http://www.atmel.com/images/doc8008.pdf ATTINY88-MU]
|Microcontroller
|U18 (10)
|-
|[http://www.ti.com/lit/ds/symlink/tps61253.pdf TPS61253YFF]
|Step-Up Converter
|U19 (10)
|-

|[https://www.u-blox.com/sites/default/files/products/documents/AMY-6_ProductSummary_%28GPS.G6-HW-10039%29.pdf AMY-6M]
|GPS Module
|U12 (6)
|-

|[https://www.ctscorp.com/wp-content/uploads/2015/11/008-0334-0.pdf 525L20DA40M0000]
|VCTCXO
| -
|-

! colspan="3" | Daughterboard
|-
!Part Number
!Description
!Schematic ID (Page)
|-

|[http://www.analog.com/en/products/rf-microwave/integrated-transceivers-transmitters-receivers/wideband-transceivers-ic/ad9361.html#product-overview AD9361 Product Page]
|2 x 2 RF Agile Transceiver
| U8 (3)
|-

|[http://ww1.microchip.com/downloads/en/devicedoc/21203m.pdf 24AA256]
|EEPROM
|U15 (2)
|-

|[https://www.minicircuits.com/pdfs/TC1-1-43A+.pdf TC-1-43A+]
|RF Transformer
|T6 (3); T5 (3); T4 (3)
|-

|[https://www.minicircuits.com/pdfs/TC1-1-13M+.pdf TC1-1-13M+]
|RF Transformer
|T7 (3); T10 (3); T1 (3)
|-

|[http://www.ti.com/lit/ds/symlink/tps62140.pdf TPS62140]
|Step-Down Converter
|U19 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP1752_1753.pdf ADP1753ACPZ-R7]
|Linear Regulator
|U17 (4); U18 (4)
|-

|[http://www.rfmd.com/store/downloads/dl/file/id/28671/sga4563z_data_sheet.pdf SGA-4563Z]
|MMIC AMPLIFIER
|U12 (5); U4 (5)
|-

|[http://www.skyworksinc.com/uploads/documents/SKY13418_485LF_201712D.pdf SKY13418-485LF]
|Antenna Switch
|U13 (5); U3 (5); U16 (5); U2 (5); U10 (6); U5 (6)
|-

|[http://www.skyworksinc.com/uploads/documents/SKY13373_460LF_201264N.pdf SKY13373-460LF]
|SP3T Switch
|U11 (6); U9 (6); U6 (6); U7 (6); SW4 (7); SW1 (7)
|-

|[http://www.avagotech.com/docs/AV02-0966EN MGA-81563]
|Amplifier
|U14 (5); U1 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-5850+.pdf LFCN-5850+]
|Low Pass Filter
|FL32 (5); FL1 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2750.pdf LFCN-2750+]
|Low Pass Filter
|FL37 (5); FL4 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2250.pdf LFCN-2250+]
|Low Pass Filter
|FL23 (6); FL20 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1700.pdf LFCN-1700+]
|Low Pass Filter
|FL40 (5); FL2 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1575.pdf LFCN-1575+]
|Low Pass Filter
|FL25 (6); FL17 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1000.pdf LFCN-1000+]
|Low Pass Filter
|FL33 (5); FL9 (5); FL27 (6); FL15 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-575.pdf LFCN-575+]
|Low Pass Filter
|FL36 (5); FL5 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-530.pdf LFCN-530+]
|Low Pass Filter
|FL29 (6); FL13 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-400.pdf LFCN-400+]
|Low Pass Filter
|FL38 (5); FL3 (5); FL30 (6); FL11 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-225.pdf LFCN-225]
|Low Pass Filter
|FL39 (5); FL6 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-160+.pdf LFCN-160+]
|Low Pass Filter
|FL34 (5); FL8 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-80.pdf LFCN-80+]
|Low Pass Filter
|FL35 (5); FL7 (5)
|-

|[https://www.minicircuits.com/pdfs/HFCN-1600.pdf HFCN-1600+]
|High Pass Filter
|FL22 (6); FL19 (6)
|-

|[https://www.minicircuits.com/pdfs/HFCN-1100+.pdf HFCN-1100+]
|High Pass Filter
|FL24 (6); FL16 (6)
|-

|[https://www.minicircuits.com/pdfs/HFCN-650.pdf HFCN-650+]
|High Pass Filter
|FL26 (6); FL14 (6)
|-

|[https://www.minicircuits.com/pdfs/HFCN-440+.pdf HFCN-440+]
|High Pass Filter
|FL28 (6); FL12 (6)
|-

|[https://www.minicircuits.com/pdfs/BFCN-2435+.pdf BFCN-2435+]
|Bandpass Filter
|FL21 (6); FL18 (6)
|-

|[https://www.fairchildsemi.com/datasheets/FD/FDG6301N.pdf FDG6301N]
|Dual N-Channel, Digital FET
|Q8 (7); Q5 (7)
|-

|[http://www.farnell.com/datasheets/461118.pdf HSMS-8202]
|Mixer Diodes
|CR1 (7); CR2 (7); CR3 (7); CR4 (7)
|-

|[http://www.ti.com.cn/cn/lit/ds/symlink/lp5900.pdf LP5900TL]
|Linear Regulator
|U25 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP150.pdf ADP150AUJZ-3.0]
|Linear Regulator
|U22 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD5662.pdf AD5662RBJ]
|16-Bit nanoDAC
|U21 (8)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t57.pdf SN74AUP1T57]
|Voltage Translator
|U27 (8); U28 (8); U29 (8)
|-

|}

Request a detailed whitepaper covering features and components from [mailto:info@ettus.com info@ettus.com]

==Mechanical Information==

===Weight===
====E310====
* 375 g

====E312====
* 446 g

====E313====
* 1.8 kg

===Drawings===
====E310====
* [[File:E310_Dimensional_Sketches.pdf]]
* [[File:cu e310 motherboard cca.pdf]]
* [[File:cu E310 daughtercard cca.pdf]]
* [[File:cu usrp-e310.pdf]]

====E312====
* [[File:cu e312 motherboard cca.pdf]]
* [[File:cu e312 daughtercard cca.pdf]]
* [[File:cu ettus-e312.pdf]]

====E313====
* [[File:USRP E313 Dimension Pole Mount.pdf]]
* [[File:USRP E313 Dimension Surface Mount.pdf]]
* [[File:USRP_E313_Mounting_Accessory_Assembly_Guide.pdf]]
* [[Media:USRP E313 USB conduit interface.png]]

==FPGA==
* Utilization statistics are subject to change between UHD releases. This information is current as of UHD 3.9.4 and was taken directly from Xilinx Vivado 2014.4. However, keep in mind that Vivado 2015.4 is recommended for FPGA design involving this device.

===E310/E312/E313===
<pre>
1. Slice Logic
--------------

+----------------------------+-------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------------------+-------+-----------+-------+
| Slice LUTs | 36203 | 53200 | 68.05 |
| LUT as Logic | 28108 | 53200 | 52.83 |
| LUT as Memory | 8095 | 17400 | 46.52 |
| LUT as Distributed RAM | 870 | | |
| LUT as Shift Register | 7225 | | |
| Slice Registers | 36562 | 106400 | 34.36 |
| Register as Flip Flop | 36562 | 106400 | 34.36 |
| Register as Latch | 0 | 106400 | 0.00 |
| F7 Muxes | 376 | 26600 | 1.41 |
| F8 Muxes | 125 | 13300 | 0.93 |
+----------------------------+-------+-----------+-------+

3. Memory
---------

+-------------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+-------------------+------+-----------+-------+
| Block RAM Tile | 97 | 140 | 69.28 |
| RAMB36/FIFO* | 90 | 140 | 64.28 |
| RAMB36E1 only | 90 | | |
| RAMB18 | 14 | 280 | 5.00 |
| RAMB18E1 only | 14 | | |
+-------------------+------+-----------+-------+
* Note: Each Block RAM Tile only has one FIFO logic available and therefore can accommodate only one FIFO36E1 or one FIFO18E1. However, if a FIFO18E1 occupies a Block RAM Tile, that tile can still accommodate a RAMB18E1

4. DSP
------

+----------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------+------+-----------+-------+
| DSPs | 120 | 220 | 54.54 |
| DSP48E1 only | 120 | | |
+----------------+------+-----------+-------+

</pre>

==Interfaces and Connectivity==
*10/100/1000 BASE-T Ethernet
*Stereo audio out, mono mic in
*Integrated GPS receiver
*Host USB support
*9-axis IMU

===Front Panel===
{|
| style="width:50%" |
*'''RF A Group'''
**'''TX/RX LED:''' Indicates that data is streaming on the TX/RX channel on frontend side A
**'''RX2 LED:''' Indicates that data is streaming on the RX2 channel on frontend side A
*'''RF B Group'''
**'''TX/RX LED:''' Indicates that data is streaming on the TX/RX channel on frontend B
**'''RX2 LED:''' Indicates that data is streaming on the RX2 channel on frontend B
*'''PWR:''' Power switch with integrated status LED, for status description see below.
*'''SYNC:''' Input port for external PPS signal
*'''GPS:''' Connection for the GPS antenna
*'''AUDIO:''' Audio input / output

The status LED in the power switch indicates the power and charge status. It's behavior is firmware version dependent.

*'''Version 1''' (original E310)
**'''Off:''' Indicates device is off and not charging
**'''Solid Red:''' Indicates device is charging
**'''Solid Green:''' Indicates device is on
**'''Fast Blinking Red:''' Indicates an error code
***1 - Low voltage error
***2 - Regulator low voltage error
***3 - FPGA power error
***4 - DRAM power error
***5 - 1.8V rail power error
***6 - 3.3V rail power error
***7 - Daughterboard / TX power error
***9 - Temperature error

*'''Version 2''' (E312 and upgraded E310)
**'''Off:''' Indicates device is off and not charging
**'''Slow Blinking Green:''' Indicates device is off and charging
**'''Fast Blinking Green:''' Indicates device is on and charging
**'''Solid Green:''' Indicates device is on (and not charging, if E312)
**'''Solid Orange:''' Indicates device is on and discharging
**'''Fast Blinking Orange:''' Indicates device is on, discharging, and charge is below 10% charge
**'''Fast Blinking Red:''' Indicates an error code
***1 - Low voltage error
***2 - Regulator low voltage error
***3 - FPGA power error
***4 - DRAM power error
***5 - 1.8V rail power error
***6 - 3.3V rail power error
***7 - Daughterboard / TX power error
***8 - Charger error
***9 - Charger temperature error
***10 - Battery low error
***11 - Fuel Gauge temperature error
***12 - Global (case) temperature error

| style="vertical-align:top" | [[File:e3x0 fp overlay.png]]
|}

===Rear Panel===
{|
| style="width:50%" |
*'''PWR:''' Locking connector (Kycon KLDHCX-0202-A-LT) for the USRP-E Series power supply
*'''1G ETH:''' RJ45 port for Ethernet interfaces
*'''USB:''' USB 2.0 Port
*'''SERIAL:''' Micro USB connection for serial uart console

| style="vertical-align:top" | [[File:e3x0 rp overlay.png]]

|}

===GPIO===
{|

| style="width:60%" |
'''Pin Mapping'''
* Pin 1: +3.3V
* Pin 2: Reserved
* Pin 3: Data[5]
* Pin 4: Reserved
* Pin 5: Data[4]
* Pin 6: Data[0]
* Pin 7: Data[3]
* Pin 8: Data[1]
* Pin 9: 0V
* Pin 10: Data[2]
|[[File:e3x0 gpio conn.png]]
|}

====Power on state====
The hardware power on state and UHD initial state for the front-panel GPIOs is high-Z. For the E3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: E3xx: pull-down.

* Please see the [http://files.ettus.com/manual/page_gpio_api.html E3x0/X3x0 GPIO API] for information on configuring and using the GPIO bus.

===Audio===
{|
| style="width:60%" |
* The E3x0 2.5 mm Audio Jack TRRS pins are assigned as follows: Tip=Mic, Ring1=Right, Ring2=Left, Sleeve=GND.
* The Left/Right audio outputs are compatible with typical low-impedance headphones (16 to 32 Ohms). The Microphone pin provides approximately 2 mA bias at 2.2 V when not suspended. A variety of pin configurations can be found on commonly available headsets, so an adapter may be required.

|[[File:TRRS.png]]

|}

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===E310===
* [[Media:volatility USRP E310 r1.pdf]]

===E312===
* [[Media:USRP E31x CoV.pdf]]

==SD Card Images==

* [http://files.ettus.com/e3xx_images/ http://files.ettus.com/e3xx_images/]

This folder linked above contains SD card images and the SDK (OE cross-compiler build environment) for the USRP E31x. There is a manifest file that shows which packages, and which versions, are included in the OE build within each folder.

The "<code>alpha</code>", "<code>beta</code>", "<code>e3xx-release-001</code>", "<code>e310-release-002</code>", "<code>e3xx-release-3</code>" folders contain older versions which are currently obsolete. We do not suggest that customers use these files. These versions are no longer supported. They are provided here for archival purposes only.

The current version is Release 4, which located in the "<code>e3xx-release-4</code>" folder. We recommend the customers use this version. It is fine if you are already successfully using an older version, but at some point it is recommended that you upgrade to this current version so that you benefit from the latest bug fixes, new features, stability improvements, and other enhancements.

The Release 4 image includes UHD 3.9.2 and GNU Radio 3.7.9, and also includes the corresponding FPGA image file.

'''Note:''' An 8 GB SD card is required for the Release 4 image.

The SD card image contains both the FPGA image and the OS for the E31x. The FPGA images are located in the file system of the E31x in the <code>/usr/local/share/uhd/images</code> folder.

There are two SD card image files for each version of the image, which include the text "<code>-dev</code>" and "<code>-demo</code>" in the filename. The "<code>-dev</code>" flavor lacks some graphical packages, such as X Windows and QT, which the "<code>-demo</code>" flavor includes. The two flavors are otherwise functionally equivalent, although the "<code>-demo</code>" flavor takes some additional space on the SD card and some additional memory to run.

The Release 4 image comes in two varieties. The variety that you will need depends on the product number of your E31x, which is printed on the bottom of the device.

For the E310, the product number will be <code>156333X-01L</code>, where X is a letter from A to Z. For devices where X is A, B, C, D, the images under the "<code>ettus-e3xx-sg1</code>" folder should be used. For devices where X is E or later, the images under the "<code>ettus-e3xx-sg3</code>" folder should be used. You must use the appropriate image for your specific device. The incorrect image will not work, and will only boot as far as the U-Boot boot loader before stopping.

For the E312, the product number will be <code>140605X-01L</code>, where X is a letter from A to Z. The images under the "<code>ettus-e3xx-sg3</code>" folder should be used for all E312 devices.

You can burn the image to an SD card using either the "<code>dd</code>" or the "<code>bmaptool</code>" tool. Instructions on how to use these tools are at the links below.

* http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_upgrade_sd_card

* https://gnuradio.org/redmine/projects/gnuradio/wiki/Copy_an_image_file_to_the_SD_card

The SD image files have an *.xz extension, as they are compressed using the LZMA/LZMA2 compression algorithms. You can uncompress these files with tools such as 7-Zip and the XZ Utils. Please see the links below for further information.

'''7-Zip'''
* http://www.7-zip.org/
* https://en.wikipedia.org/wiki/7-Zip

'''XZ Utils'''
* http://tukaani.org/xz/
* https://en.wikipedia.org/wiki/XZ_Utils

The folder structure is listed below.
<pre>
.
|-- alpha
| |-- dizzy-test
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| | |-- sdimage-gnuradio-demo.direct.xz
| | `-- sdimage-gnuradio-dev.direct.xz
| |-- fido-rfnoc-test
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| | |-- sdimage-gnuradio-demo.direct.xz
| | |-- sdimage-gnuradio-demo.direct.xz.md5
| | |-- sdimage-gnuradio-dev.direct.xz
| | `-- sdimage-gnuradio-dev.direct.xz.md5
| |-- fido-test
| | |-- ettus-e3xx-sg1
| | | |-- sdimage-gnuradio-demo.direct.xz
| | | |-- sdimage-gnuradio-demo.direct.xz.md5
| | | |-- sdimage-gnuradio-dev.direct.xz
| | | `-- sdimage-gnuradio-dev.direct.xz.md5
| | |-- ettus-e3xx-sg3
| | | |-- sdimage-gnuradio-demo.direct.xz
| | | |-- sdimage-gnuradio-demo.direct.xz.md5
| | | |-- sdimage-gnuradio-dev.direct.xz
| | | `-- sdimage-gnuradio-dev.direct.xz.md5
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | `-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| `-- fosphor-testing
| |-- fosphor.direct.xz
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.host.manifest
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.target.manifest
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5
|-- beta
| |-- dizzy-test
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| | |-- sdimage-gnuradio-demo.direct.xz
| | `-- sdimage-gnuradio-dev.direct.xz
| `-- dizzy-test-wifi
| `-- sdimage-gnuradio-dev.direct.xz
|-- e310-release-002
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5sum
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5sum
|-- e3xx-release-001
| |-- e300-gnuradio-dev-image-release1.bz
| `-- nodistro-eglibc-x86_64-gnuradio-dev-image-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
|-- e3xx-release-3
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| |-- sdimage-gnuradio-demo.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz
`-- e3xx-release-4
|-- ettus-e3xx-sg1
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5
|-- ettus-e3xx-sg3
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5
|-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
`-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
</pre>

==WiFi Network Connectivity==
Below are instructions on setting up a USB WiFi adapter with the E3xx. We have tested the "Edimax EW-7811Un", however many USB based WiFi adapters should be supported.

First verify the USB WiFI adapter is found by running <code>lsusb</code>.

Example output from <code>lsusb</code> for the "Edimax EW-7811Un" WiFi adapter:

<pre>Bus 001 Device 003: ID 7392:7811 Edimax Technology Co., Ltd EW-7811Un 802.11n Wireless Adapter [Realtek RTL8188CUS]</pre>

If the USB adapter is found, proceed with installation and configuration procedure:

1. Run the command below. Enter the passphrase and hit <code><Enter></code>.

wpa_passphrase <SSID> >> /etc/wpa_supplicant.conf`

2. In the file <code>/etc/wpa_supplicant.conf</code>, edit the entry created above to look like the text below (just add what is missing).

<pre>
network={
ssid="YOUR_SSID"
psk=HASH_VALUE
key_mgmt=WPA-PSK
proto=RSN WPA
pairwise=CCMP TKIP
group=CCMP TKIP
}
</pre>

3. Run the command:
wpa_supplicant -B -D nl80211 -i wlan0 -c /etc/wpa_supplicant.conf

4. Run the command:
udhcpc -i wlan0

===Compiling Wireless Drivers===
At this time, Ettus Research does not support compiling drivers on the E3xx device. In the Release-4 image there is the drivers for several wifi adapters built-in. Most wireless adapters labeled for the Raspberry-Pi should work with the included drivers.

==Additional Resources==
===Application Notes===
* [[Software Development on the E310 and E312]]
* [[Resolving Audio Codec Enumeration Issues On The E31x]]
===Third-party Resources===
* [http://www51.honeywell.com/aero/common/documents/myaerospacecatalog-documents/Defense_Brochures-documents/Magnetic__Literature_Application_notes-documents/AN203_Compass_Heading_Using_Magnetometers.pdf Compass Heading Using Magnetometers (Honeywell Application Note)]

==Downloads==

[http://files.ettus.com/e3xx_images/ FPGA Images]

[http://files.ettus.com/e3xx_images/README FPGA Images Read Me]

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

==USRP Embedded Series FAQ==

===General USRP E31x Questions===
'''Q: What data rate is supported for continuous sample streaming to a desktop or laptop host-PC?'''
A: Unlike host-based SDRs such as the USRP B, N, and X Series devices, the USRP E Series devices are not intended for continuous streaming of high bandwidth data to a desktop or laptop host-PC. The SDR application runs on an embedded CPU with limited processing capability. Users should leverage the FPGA using tools such as RFNoC to offload compute intensive algorithms that process high bandwidth samples.

'''Q: What data rate is supported between FPGA to the ARM processor?'''
A: Due to the limited performance of the embedded processor, the maximum data rate from the FPGA to ARM cores is approximately 10 MS/s, and will vary with the processing load on the CPU. The AD9631 RFIC is capable of capturing 56 MHz of bandwidth. Processing signals at full bandwidth requires implementing algorithms on the FPGA.

'''Q: What is the purpose of the 1 GbE port?'''
A: The E Series can run a DHCP client on the 1 GigE interface to enable connection to a larger network for remote access by another computer. Power over Ethernet is also supported on the E313.

===USRP E313 Questions===
'''Q: Which environmental tests were performed?'''
A: The USRP E313 is tested against multiple environmental standards to ensure operation in outdoor conditions. These test include ingress protection, temperature, humidity, mechanical shock, random vibration, and altitude. Detailed specifications are provided in the [link data sheet].

'''Q: How do I protect external devices connected to the host USB port?'''  
{|
|style="vertical-align:top"|
A: A circular conduit interface is provided in the kit. This component has large and small threaded ends. The small end connects to the USB port on the USRP E313. The user will need to connect their own waterproof structure to the large end to protect the USB device. Since requirements for external devices vary greatly, the conduit interface serves as a flexible starting point for users to build their own solution. See the [[Media:USRP E313 Dimension Pole Mount.pdf]] of the conduit interface for details.
|[[File:USRP E313 USB conduit interface.png|250px|center]]
|}

'''Q: How do I protect unused ports?'''
A: All ports come with protective end caps that should be left in place on unused ports.

'''Q: Why is a DC power supply not included?'''
A: The RJ45 port supports Power over Ethernet and is intended as the primary power supply option. However, users can still use a DC power supply. Since requirements for supplying DC power in outdoor scenarios can vary greatly, a waterproof sleeve for the DC port is provided as a starting point for users to design their own solution. A waterproof sleeve for the RJ45 port is also provided.

'''Q: Do the RF inputs have lightning protection?'''
A: The DC and PoE power inputs have surge and lightning protection, but the N-type RX/TX inputs and SMA GPS input do not. Users should design antenna lightning protection based on their application requirements.

[[Category:Hardware Resources]]
[[Category:E310]]
[[Category:E312]]
[[Category:E313]]

Getting Started with RFNoC Development

2017-10-03T20:42:19Z

NicolasCuervo: /* Image building using the command line */

==Application Note Number==
'''AN-823'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-07-12
|style="text-align:center;"| Martin Braun Nicolas Cuervo
|style="text-align:center;"| Initial creation

|-
|style="text-align:center;"| 2017-01-10
|style="text-align:center;"| Team
|style="text-align:center;"| Added “Digital Gain” example
|-

|-
|style="text-align:center;"| 2017-05-08
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Updated example code. Update to Testbench section.
|-

|-
|style="text-align:center;"| 2017-08-26
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Updated following sections: '''Abstract'''(This AN is specific to USRP X300/X310), '''Using a graphical interface'''(updated GUI image with newest version and the explanation section), '''Testing out the custom block'''(Updated GRC image that has correct Sampling Rate for RFNoC:Radio block).
|-

|-
|style="text-align:center;"| 2017-09-07
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added link to Video that follows this App Note in the Resources section. Also [https://youtube.com/watch?v=j-EfyPVpaJ8 here]
|-

|}

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example. RFNoC is currently supported on the USRP X300/X310 and USRP E310/E312 hardware. '''However''', this document only covers using RFNoC for the USRP X300/X310. Using RFNoC with the E310/E312 will be covered in another document.

==Overview==
First sections deal with installing tools and validating correct tool installation in order to do RFNoC development. Later sections deal with creating a custom RFNoC block, using the built-in testbench architecture, building an FPGA image with the custom block and finally testing out the new block within GNU Radio.

==Licensing==
The RFNoC code base is open source, including code that executes on the host, as well as code targeted to the USRP hardware (FPGA and microcontroller firmware). As dual-licensed software, RFNoC is available under the open-source GNU Public License version 3 (GPLv3), as well as an alternative, less-restrictive license offered only by Ettus Research. For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Prerequisites==
RFNoC is only supported on the USRP E310/E312 and the USRP X300/X310.

In order to build custom USRP FPGA images and RFNoC blocks the following hardware and software are needed.

* '''Ubuntu 14.04.5 or 16.04.1 (preferred):''' Currently PyBOMBS (which can be used to install the ''Software build tools''), works most reliably in Ubuntu, and thus, we recommend using this distribution. Also, a majority of the scripts used during the build process are Linux (Ubuntu) specific. A PC with multiple cores and 8GB+ of RAM is recommended.

* '''Xilinx Vivado tools (version 2015.4):''' The specific version depends on the branch and state of the FPGA code. The default install location is <code>/opt/Xilinx/Vivado</code>. Once all of the Software build tools are installed the specific version for the downloaded code can be found in the <code>setupenv.sh</code> file located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{DEVICE}</code> directory. Further information can be found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here].

* '''Software build tools:''' If UHD can be or has been compiled from source on the development PC then all the necessary software build components are present (PyBOMBS can be used to set all this up and instructions on how to do so are given in a following step).

* X3xx series or E3xx series device or any future USRP

'''NOTE:'''
* The edition of Xilinx Vivado that is required will depend on which USRP device is being used.
** X3xx series devices: Design Edition or System Edition.
** E3xx series devices: Design Edition, System Edition, or the free WebPack Edition.
* Other operating systems can be used, but the exact steps on how to proceed are not given in this Application Note.
* In some Linux distributions (e.g. Ubuntu) <code>dash</code> is set as default shell, which may cause some issues. It is recommended to set the shell to <code>bash</code> by running the following commands in the terminal. Choose <code><No></code> when prompted by the first command and the second command will validate the that bash will be used.

$ sudo dpkg-reconfigure dash
$ ll /bin/sh

==Creating a development environment==
While this Application Note goes through the process of integrating GNU Radio into the RFNoC development flow, it is by no means required to use or develop within the RFNoC framework, but it makes it a great deal easier to use a framework on top of RFNoC for aspects such as visualization and other features. GNU Radio is freely available and more information about it can be found [http://gnuradio.org/ here].

The following software packages are required in order to setup a development environment/sandbox:

* UHD
* GNU Radio
* gr-ettus

===Create development environment using PyBOMBS===
The cleanest way to set this up is to install everything into a dedicated directory. [https://github.com/gnuradio/pybombs PyBOMBS] is the simplest way to do this. If not already installed, PyBOMBS can be setup with the following commands:

$ sudo apt-get install git
$ sudo apt-get install python-setuptools python-dev python-pip build-essential

$ sudo pip install git+https://github.com/gnuradio/pybombs.git
$ pybombs recipes add gr-recipes git+https://github.com/gnuradio/gr-recipes.git
$ pybombs recipes add ettus git+https://github.com/EttusResearch/ettus-pybombs.git

These commands will do the following:
* Install <code>Git</code>
* Install <code>pip</code> and other Python dependencies
* Install the latest <code>PyBOMBS</code> from its Git repository
* Add the <code>gr-recipes</code> recipes which are used to install GNU Radio specific software
* Add the <code>ettus</code> recipes which are used to install Ettus Research specific software

From here, PyBOMBS can be used to setup and install the development environment/sandbox by running the following command:

$ pybombs prefix init ~/rfnoc -R rfnoc -a rfnoc

This will do the following:

* Create a directory in the user’s home directory called <code>rfnoc</code> (any valid directory name will work)

* Give the prefix an alias of <code>rfnoc</code> ( <code>[-a alias]</code>, e.g. <code>–a rfnoc</code> ), which would be the name given to this path. This name will be used in further steps that use PyBOMBS. When creating the first prefix and omitting the alias, the prefix will be setup as the default.

* Use the <code>rfnoc</code> prefix recipe ( as opposed to a package recipe like <code>gqrx</code> ) to clone UHD, FPGA, GNU Radio, and gr-ettus sources into the <code>~/rfnoc</code> directory as well as compile and install all the software

'''NOTE:''' A user can specify how many cores are used by builds when using PyBOMBS. The default is set to 4. For example, this will set the number of cores used to 3:

$ pybombs config makewidth 3

The value will be written into a configuration file and then applied to subsequent PyBOMBS commands. This value can temporarily be overridden for a specific build by specifying the <code>--config makewidth=X</code> argument, where “<code>X</code>” is an integer number. If the user only has 4 cores it is recommend to use this argument in the pybombs command to limit the number of cores to <4 (e.g. 3) so that the computer stays responsive. Following are 2 examples, one using less cores and the other using more cores:

$ pybombs --config makewidth=3 prefix init ~/rfnoc -R rfnoc -a rfnoc
$ pybombs --config makewidth=7 prefix init ~/rfnoc -R rfnoc -a rfnoc

Then, it is necessary to setup the PyBOMBS environment, so that the system/terminal session will have the environmental variables pointing to this newly created prefix, which is done with the following commands:

$ cd ~/rfnoc
$ source ./setup_env.sh

Once the previous command is run, this terminal session will have access to the environmental variables that allow the complete use of the set of software that was just installed with PyBOMBS. If access to the software is needed in other terminals the same command must be run within them.

'''NOTE:''' Throughout the rest of this document the term <code>{USER_PREFIX}</code> will used at the beginning of different directories. For example, <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts</code> is a directory that contains useful scripts for compiling. The term <code>{USER_PREFIX}</code> is used to denote the folders that precede the <code>/src</code> directory. Examples of what <code>{USER_PREFIX}</code> could be: <code>/home/user/rfnoc</code> or <code>/home/user/myDevfolder/</code>. On many Linux environments using <code>~/</code> at the beginning of the target directory path is equivalent to the user’s home directory.( i.e <code>~/</code> is equal to <code>/home/user/</code>). So <code>{USER_PREFIX}</code> could also look like <code>~/rfnoc</code> or <code>~/myDevfolder/</code>.

===Create the development environment manually===
As an alternative to using PyBOMBS, manually installing and configuring the software is done by following the individual install notes for [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio], [https://files.ettus.com/manual/page_build_guide.html UHD] and [https://github.com/EttusResearch/gr-ettus gr-ettus] and by making sure they are reachable by linkers and compilers.

'''NOTE:''' The Application Note found [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux here] goes through the process of manually installing UHD and GNU Radio on Linux platforms.

To manually download the software, use these <code>git clone</code> commands, which will select the correct branches:

$ git clone --recursive -b rfnoc-devel https://github.com/EttusResearch/uhd.git
$ git clone --recursive -b maint https://github.com/gnuradio/gnuradio.git # master branch is also fine instead of maint
$ git clone -b master https://github.com/EttusResearch/gr-ettus.git
$ git clone -b rfnoc-devel https://github.com/EttusResearch/fpga.git

If UHD, GNU Radio and/or gr-ettus are already installed, it would be sufficient to checkout the branches mentioned and update them them (<code>git pull</code>). Thereafter, rebuild each of the repositories (rebuild order: UHD, GNU Radio, gr-ettus).

===Verify Environment===
Running the command “<code>uhd_config_info</code>” with the “<code>--version</code>” flag will verify that the installation has been completed successfully.

'''NOTE:''' The version string output from this command may differ, however it should be similar to the output below.

$ uhd_config_info --version
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-161- g83150fdd

4.0.0.rfnoc-devel-161-g83150fdd

===Testing the default FPGA image and building from existing blocks===

It is recommended to spend a moment looking at the Ettus Research default image, which is pre-built with a set of RFNoC blocks, as well as building a custom image with a unique set of pre-built RFNoC blocks. To get the default image(s), run the following command:

$ uhd_images_downloader

Ettus Research will be updating the default image(s) occasionally, and <code>uhd_images_downloader</code> can be run anytime after running <code>git pull</code> and re-installing to pull the most current images. Images are stored in the <code>{USER_PREFIX}/share/uhd/images</code> directory.

The following images have the corresponding RFNoC blocks (Computation Engines):

{| class="wikitable"
!Image Name
!Included Blocks
|-

|<code>usrp_x300_fpga_HG.bit</code>
<code>usrp_x300_fpga_XG.bit</code>

<code>usrp_x310_fpga_HG.bit</code>

<code>usrp_x310_fpga_XG.bit</code>
|<code>2x DDC, 2x DUC</code>
|-

|<code>usrp_x300_fpga_RFNOC_HG.bit</code>
<code>usrp_x300_fpga_RFNOC_XG.bit</code>
|<code>DUC, DDC (one channel), fosphor, window, fft, 2x AXI FIFOs</code>
|-

|<code>usrp_x310_fpga_RFNOC_HG.bit</code>
<code>usrp_x310_fpga_RFNOC_XG.bit</code>
|<code>DUC, DDC (one channel), fosphor, window, fft, 2x AXI FIFOs, Keep One in N, FIR, Siggen</code>
|-

|<code>usrp_e310_fpga.bit</code>
<code>usrp_e310_fpga_sg3.bit</code>
|<code>1x DDC, 1x DUC</code>
|-

|<code>usrp_e310_fpga_RFNOC.bit (sg1 version)</code>
<code>usrp_e310_fpga_RFNOC_sg3.bit</code>
|<code>fosphor, window, fft, 2x AXI FIFOs, FIR</code>
|-

|}

Instructions on flashing the image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

'''NOTE:''' FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device.

By following the steps above the following should now be available:
* UHD/RFNoC code downloaded and installed
* FPGA code available
* A valid RFNoC image on your X3xx or E3xx series device

====Inspect default images====
Run the following command, with a USRP connected to your PC, to verify current image on the USRP.

$ uhd_usrp_probe

If an RFNoC image was successfully loaded onto the USRP, there will be a lot of output text (RFNoC code is currently very verbose). The final lines of the output should be similar to the following for an USRP X310 ( e.g. <code>usrp_x310_fpga_HG</code> ):

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1

Final output for <code>usrp_x310_fpga_RFNOC_HG.bit</code> image:

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DUC_0
| | | * FFT_0
| | | * Window_0
| | | * FIR_0
| | | * SigGen_0
| | | * KeepOneInN_0
| | | * fosphor_0
| | | * FIFO_0
| | | * FIFO_1

'''NOTE:''' The actual names and number of blocks can differ. The list of blocks should start with the <code>DmaFIFO_x</code> and <code>Radio_x</code>, and then a couple more lines of block IDs should follow.

====Build custom image with pre-built RFNoC blocks====
Because of the growing number of RFNoC blocks, the user has the option to build an FPGA image with a set of pre-built RFNoC blocks of their choosing. The following steps describe the process for doing this and by so doing will also validate proper tool installation. Because compilation can take a couple of hours, it is recommended the user begin this process while continuing the rest of this guide.

'''NOTE:''' FPGA compilations can run in the background, however they are very resource intensive. If the user intents to use the same computer that is compiling to walk through the rest of this Application Note, it is recommended that the computer has plenty of resources.

The script to initiate a compile is called <code>uhd_image_builder.py</code>, and is located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts</code> directory. Run the help menu by typing:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py --help

A more detailed discussion of this script is given in an upcoming section. For now, compiling an FPGA image that has 2 RFNoC blocks (<code>window</code> and <code>fft</code>) and some <code>FIFOs</code>, is done by running the script with the following arguments.

Example for an X310 USRP:

$ ./uhd_image_builder.py window fft -d x310 -t X310_RFNOC_HG -m 5 --fill-with-fifos

Example for an E310 USRP with Speed Grade 3 (sg3) FPGA:

$ ./uhd_image_builder.py window fft -d e310 -t E310_RFNOC_sg3 -m 5 --fill-with-fifos

At the end of a successful compilation process, write the new image to a USRP. If the image was compiled for a USRP X310, the following command will load the new image. Update the <code>{IP_Address}</code> of the USRP and <code>{USER_PREFIX}</code> to the appropriate values for your configuration before running the command.

$ uhd_image_loader --args "type=x300,addr={IP_ADDRESS}" --fpga-path {USER_PREFIX}/src/uhd-fpga/usrp3/top/x300/build/usrp_x310_fpga_RFNOC_HG.bit

'''NOTE:''' FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device. Additional instructions on flashing a custom image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

After the image has been successfully written to the USRP, power-cycle it and run the “<code>uhd_usrp_probe</code>” utility to view the newly compiled blocks.

$ uhd_usrp_probe

The final lines of output for the image built for the X310 is as follows:

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * Window_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

===Getting started with UHD + RFNoC===
The following new examples included within the <code>rfnoc-devel</code> branch of UHD, are a good reference on how to use RFNoC from UHD.

The following example is based off of <code>rx_samples_to_file.cpp</code>. The example can be configured to place an RFNoC block in between the radio and host.

rfnoc_rx_to_file.cpp

This next example chains a null source to another block and streams the data to the host.

rfnoc_nullsource_ce_rx.cpp

These examples demonstrate the core features and flexibility of RFNoC.

For more information on UHD and UHD development please refer to the [https://kb.ettus.com/UHD UHD Software Resource page], [https://kb.ettus.com/Getting_Started_with_UHD_and_C%2B%2B Getting Started with UHD and C++ Application Note] or directly to the [http://files.ettus.com/manual/ UHD user manual].

===Getting started with GNU Radio + RFNoC===
A good way of getting started with RFNoC in a more visual way is to use GNU Radio. The <code>gr-ettus</code> out-of-tree module (OOT) allows a user to use RFNoC blocks in their local GNU Radio / GNU Radio Companion (GRC) installation. This GNU Radio OOT contains blocks that allow you to configure your FPGA through GRC.

'''NOTE:''' As blocks in the <code>gr-ettus</code> OOT mature, they will be upstreamed to <code>gr-uhd</code>. Also, <code>gr-ettus</code> is a container used by Ettus Research to disseminate experimental or under-development features for <code>gr-uhd</code>. It is not a replacement for <code>gr-uhd</code> (in fact, the latter is a requirement for <code>gr-ettus</code>).

Examples can be run from <code>gr-ettus/examples/rfnoc</code>, provided that the appropriate RFNoC blocks are compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs with RFNoC blocks:

* You always need a <code>Device3</code> object in your flow graph (it does not get connected, see screenshot below).
* You should have at least two RFNoC blocks connected together. Going <code>GNU Radio Block</code> -> <code>RFNoC Block</code> -> <code>GNU Radio Block</code> is not recommended (it will work, but with suboptimal performance).

The GNU Radio flowgraph <code>rfnoc_ddc.grc</code> is an example that can be run using the default RFNoC image. Below are screenshots of the flowgraph and what it produces.

[[File:rfnoc gsg an 1.png|center|800px|]]

'''NOTE:''' Copy Block: In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The “copy” block depicted in the screenshot above serves the function as a stream splitter. Its main purpose, when “enabled”, is to copy the samples it is getting at its input and put them into the output, but here it is also serving as a boundary between a RFNoC-domain and a GNURadio-domain. In the flowgraph above, after this boundary is passed, the data stream can easily be split into the two sinks to have them run simultaneously (standard GNU Radio functionality). It is possible to connect the GNU Radio blocks directly to RFNoC blocks without a “copy” block, but only one would work at a time (the other ones would have to be disabled). Another way to split data streams from the RFNoC-domain is to use the ”RFNoC: split stream” block, which would split the streams in the RFNoC domain, but this is not very useful here as we are, in any case, moving into the GNURadio-domain.

[[File:rfnoc gsg an 2.png|center|800px|]]

For more information on GNURadio development please refer to the [http://gnuradio.org/doc/doxygen/ GNURadio user's manual and API].

==Starting a custom RFNoC block using RFNoC Modtool==
The figure below shows the basic structure of the RFNoC Stack. Corresponding code is needed in each of the three sections in order to build a custom RFNoC block with GNU Radio integration. A tool called RFNoC Modtool was created in order to minimize the effort needed to implement a new RFNoC block. RFNoC Modtool creates a custom GNU Radio OOT module with the basic structure and the necessary files for each of these sections. RFNoC Modtool is currently a part of the GNU Radio OOT module <code>gr-ettus</code>.

[[File:rfnoc gsg an 3.png|center|800px|]]

===RFNoC Modtool Utilization===
'''NOTE:''' Console outputs may vary depending on the version of UHD the user is running. However, functionality should be the same or similar.

Because the RFNoC Modtool has similar functionality to the <code>gr_modtool</code> [ [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules gr_modtool] ] provided by GNU Radio, those that have worked with <code>gr_modtool</code> in the past will find the RFNoC Modtool familiar.

To check the usage of the tool, run the following:

$ rfnocmodtool help
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

Usage:
rfnocmodtool <command> [options] -- Run <command> with the given options.
rfnocmodtool help -- Show a list of commands.
rfnocmodtool help <command> -- Shows the help for a given command.

List of possible commands:

Name Aliases Description
=====================================================================
disable dis Disable block (comments out CMake entries for files)
info getinfo,inf Return information about a given module
remove rm,del Remove block (delete files and remove Makefile entries)
makexml mx Make XML file for GRC block bindings
add insert Add block to the out-of-tree module.
newmod nm,create Create a new out-of-tree module
rename mv Rename a block in the out-of-tree module.

===Creating an RFNoC OOT Module===

To start generating an RFNoC OOT module navigate to the source location ( i.e. <code>cd ~/{USER_PREFIX}/src</code> ) and type:
$ rfnocmodtool newmod [NAME OF THE MODULE]

Where <code>[NAME OF THE MODULE]</code> is a name the user gives the new module. In the following, a module is created with the name “<code>tutorial</code>”. If the user does not write the name of the module following the <code>newmod</code> command the tool will ask for it interactively. Running this command will create a folder containing the basic folders that you may need for a functional module.

$ rfnocmodtool newmod tutorial
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

Creating out-of-tree module in ./rfnoc-tutorial... Done.
Use 'rfnocmodtool add' to add a new block to this currently empty module.

To see what files and directories were created run:

$ ls rfnoc-tutorial/
apps cmake CMakeLists.txt docs examples grc include lib MANIFEST.md python README.md rfnoc swig

In contrast with <code>gr_modtool</code>, this includes a folder called <code>rfnoc</code>, which is where the UHD/FPGA files are located.

===Adding custom blocks to OOT Module===
In order to add blocks to a module, navigate to the folder just created and use the <code>add</code> command of <code>rfnocmodtool</code>. Continuing with the example above, run the following:

$ cd rfnoc-tutorial
$ rfnocmodtool add [NAME OF THE BLOCK]

For demonstrative purposes, a block named <code>gain</code> will be created. The <code>gain</code> block will multiply samples that pass through it by a constant. As before, if the name is not given, the tool will ask the user for the name. There are several arguments that can be passed to the tool, but running the tool without any of these arguments will give the following interactive parsing output:

$ rfnocmodtool add gain
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

RFNoC module name identified: tutorial
Block/code identifier: gain
Enter valid argument list, including default arguments:
Block NoC ID (Hexadecimal): 1111222233334444
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] N
Skip Block interface files Generation? [GRC block ctrl files] [y/N] N

Hitting <code>enter</code> on each one of the options will take the default values.

The following is a description of the valid argument list items:

* '''NoC ID:''' This ID is a Hexadecimal number which serves as identification between the hardware part and the software part of the design. It can be as long as 16 0-9 A-F digits. If a NoC ID is not provided, it will be set to a random number.

* '''Block Controllers Generation:''' The block controllers are the C++ control that the user can apply to the UHD-part of the design. In these files, the user can add more control over this layer of the design. Depending on the complexity of the block it may be possible to add all necessary control using NoCScript (more details on NoCScript can be found in the section labeled UHD Integration). In this case the cpp/hpp block control files generation are not needed. Default is to generate as their existence will be ignored if not edited.

* '''Block Interface:''' Add more design specific functionality to the design at the GNU Radio interface by generating these block-interface files and adding necessary logic. Depending on the complexity of the block it may be possible to add all necessary control using NoC-Script. In this case the block-interface files are not needed. Default is to generate as their existence will be ignored if not edited.

'''NOTE:''' If the user does not intend to use the block controllers or is not sure if they are needed, the presence of them in the design will do no harm. It is recommended to add them. This leaves the possibility to add more functions inside them in a future stage of development.

After finishing the parsing, the following files will be generated/edited:

Adding file 'lib/gain_impl.h'...
Adding file 'lib/gain_impl.cc'...
Adding file 'include/tutorial/gain.h'...
Adding file 'include/tutorial/gain_block_ctrl.hpp'...
Adding file 'lib/gain_block_ctrl_impl.cpp'...
Editing swig/tutorial_swig.i...
Adding file 'python/qa_gain.py'...
Editing python/CMakeLists.txt...
Adding file 'grc/tutorial_gain.xml'...
Adding file 'rfnoc/blocks/gain.xml'...
Adding file 'rfnoc/fpga-src/noc_block_gain.v'...
rfnoc/testbenches/noc_block_gain_tb folder created
Adding file 'rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/CMakeLists.txt'...

==Creating FPGA portion of custom RFNoC Block==
===RFNoC FPGA User Interface (API)===
RFNoC blocks or Computation Engines (CEs) in the FPGA use a NoC Shell instance to interface with the rest of RFNoC. NoC Shell implements RFNoC's core functionality: packet muxing and demuxing, flow control, and the settings register bus (i.e. write/read control/status registers). The NoC Shell has an interface to the RFNoC AXI stream crossbar and a user interface. NoC Shell AXI stream interfaces expect CHDR packets with a proper header. See the manual for information on [https://files.ettus.com/manual/page_rtp.html CHDR and SID].

'''NOTE:''' AXI Stream is an ARM AMBA standard interface. Xilinx has an [http://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf AXI Reference Guide] with more details on this standard.

[[File:rfnoc gsg an 4.png|center|800px|]]

Many designs will want to use an AXI Stream interface with only sample data. However, as stated earlier, the NoC Shell block expects CHDR packets. To ease interfacing user code, the AXI Wrapper block provides the necessary logic to strip and insert the CHDR header, effectively converting packetized sample data into streaming sample data and vice versa. The example RFNoC blocks <code>noc_block_fft.v</code> and <code>noc_block_fir.v</code> show how AXI Wrapper is used to implement existing Xilinx AXI Stream based IP within a computation engine.

'''NOTE:''' AXI Wrapper also supports AXI Stream buses for configuration. These buses are driven via the setting register bus and do not have back pressure. They also consume two user register addresses per bus.

The primary user interface consists of four AXI stream interfaces ( <code>tready, tvalid, tlast, tdata</code> ) and a settings register bus ( 8-bit, valid user register addresses: <code>128-255</code> ).

{|
|
AXI Stream signals:
* '''m_axis_data_tdata:''' Input sample data packets
** Data coming from host or another CE
* '''s_axis_data_tdata:''' Output sample data packets
** Data going to another CE or host
* '''m_axis_data_tready:''' Input signal to CE
** Used to notify CE that downstream CE is ready for data
* '''s_axis_data_tready:''' Output signal to CE
** Used to notify upstream CE that CE is ready for data
* '''m_axis_data_tvalid:''' Input signal to CE
** Used to indicate upstream CE has valid data
* '''s_axis_data_tvalid:''' Output signal to CE
** Used to indicate to downstream CE that CE has valid data
* '''m_axis_data_tlast:''' Input signal to CE
** Used to delimit packets from upstream CE
* '''s_axis_data_tlast:''' Output signal to CE
** Used to delimit packets to downstream CE
| style="vertical-align:top" |[[File:rfnoc gsg an 5.png|right|500px|]]
|-
|}

[[File:rfnoc gsg an 6.png|center|800px|]]

{|
|
Settings Bus signals:
* '''set_stb:''' Assert to write '''set_data''' to register at '''set_addr'''ess
* '''set_addr:''' Register address to set
* '''set_data:''' Data to set
* '''rb_data:''' Data to read back
* '''rb_strobe:''' Assert to read '''rb_data''' from register at '''set_addr'''ess

| style="vertical-align:top" |[[File:rfnoc gsg an 7.png|right|500px|]]
|-
|}
For the <code>gain</code> example block the following architecture is desired:

[[File:rfnoc gsg an 8.png|center|800px|]]

Open the file <code>rfnoc-tutorial/rfnoc/fpga-src/noc_block_gain.v</code> that contains the RFNoC block skeleton code that was created when the <code>$ rfnocmodtool add gain</code> command was run and modify the following ('''BOLD''' indicates changes to the skeleton code).

'''localparam [7:0] SR_GAIN = SR_USER_REG_BASE;'''
localparam [7:0] SR_TEST_REG_1 = SR_USER_REG_BASE + 8'd1;

'''wire [15:0] gain;'''
'''setting_reg #('''
'''.my_addr(SR_GAIN), .awidth(8), .width(16))'''
'''sr_gain ('''
'''.clk(ce_clk), .rst(ce_rst),'''
'''.strobe(set_stb), .addr(set_addr), .in(set_data), .out(gain), .changed());'''

always @(posedge ce_clk) begin
case(rb_addr)
'''8'd0 : rb_data <= {48'd0, gain};'''
8'd1 : rb_data <= {32'd0, test_reg_1};
default : rb_data <= 64'h0BADC0DE0BADC0DE;
endcase
end

'''wire [31:0] pipe_in_tdata;'''
'''wire pipe_in_tvalid, pipe_in_tlast;'''
'''wire pipe_in_tready;'''

'''wire [31:0] pipe_out_tdata;'''
'''wire pipe_out_tvalid, pipe_out_tlast;'''
'''wire pipe_out_tready;'''

'''// Adding FIFO to ensure Pipeline'''
'''axi_fifo_flop #(.WIDTH(32+1))'''
'''pipeline0_axi_fifo_flop ('''
'''.clk(ce_clk),'''
'''.reset(ce_rst),'''
'''.clear(clear_tx_seqnum),'''
'''.i_tdata({m_axis_data_tlast,m_axis_data_tdata}),'''
'''.i_tvalid(m_axis_data_tvalid),'''
'''.i_tready(m_axis_data_tready),'''
'''.o_tdata({pipe_in_tlast,pipe_in_tdata}),'''
'''.o_tvalid(pipe_in_tvalid),'''
'''.o_tready(pipe_in_tready));'''

'''wire [15:0] i = pipe_in_tdata[31:16];'''
'''wire [15:0] q = pipe_in_tdata[15:0];'''

'''wire [31:0] i_mult_gain = i*gain;'''
'''wire [31:0] q_mult_gain = q*gain;'''

'''wire [31:0] mult_gain = {i_mult_gain[15:0], q_mult_gain[15:0]};'''
'''axi_fifo_flop #(.WIDTH(32+1))'''
'''pipeline1_axi_fifo_flop ('''
'''.clk(ce_clk),'''
'''.reset(ce_rst),'''
'''.clear(clear_tx_seqnum),'''
'''.i_tdata({pipe_in_tlast,mult_gain}),'''
'''.i_tvalid(pipe_in_tvalid),'''
'''.i_tready(pipe_in_tready),'''
'''.o_tdata({pipe_out_tlast,pipe_out_tdata}),'''
'''.o_tvalid(pipe_out_tvalid),'''
'''.o_tready(pipe_out_tready));'''

'''/* Output Signals */'''
'''assign pipe_out_tready = s_axis_data_tready;'''
'''assign s_axis_data_tvalid = pipe_out_tvalid;'''
'''assign s_axis_data_tlast = pipe_out_tlast;'''
'''assign s_axis_data_tdata = pipe_out_tdata;'''

The following is a block diagram of the code created by the above Verilog:

[[File:gain_block_diagram_v01.png|center|800px|]]

'''NOTE:''' In order to meet timing, FIFO blocks were added to either side of the Multiplication process.

===Creating and running HDL testbenches===
In order to make the coding iteration process more efficient, it is recommended to create testbenches for all RFNoC blocks before compiling them into the FPGA image. This allows for flaw and/or bug detection early in the design. RFNoC Modtool provides the structure and files ( e.g. noc_block_{USER_BLOCK_NAME}_tb ) for the testbenches of each of the OOT blocks that are added with the <code>$ rfnocmodtool add</code> command.

Below is a figure that shows the general testbench architecture that is created by the RFNoC Modtool. This architecture allows a user to test their custom block in the exact same environment it will be placed in when it is built into the RFNoC architecture. Other benefits of the testbench architecture include:
* Testing through multiple blocks (e.g. FILTER -> FFT -> AVE)
* Testing with multiple streams (e.g. RFNoC block ADD/SUB takes 2 streams, one that will have a constant added to it and one that will have a constant subtracted from it)
* Data transfer abstraction (e.g. RFNoC Sim Lib API calls to <code>tb_streamer.send</code> and <code>tb_streamer.recv</code> which take care of all the AXI stream signaling)

[[File:rfnoc gsg an 9.png|center|800px|]]

'''NOTE:''' The <code>noc_block_tb</code> block is an instantiation of the <code>noc_block_export_io</code> that is used in testbenches to communicate to the RFNoC architecture. This makes it possible to talk “RFNoC” to the user’s custom block and as such the custom block has a complete RFNoC experience (signaling, flowcontrol, addressing, etc)

From the [[Getting Started with RFNoC Development#Adding_custom_blocks_to_OOT_Module|Adding custom blocks to OOT Module section]] where the <code>gain</code> block was initially created, the last files generated were:

rfnoc/testbenches/noc_block_gain_tb folder created
Adding file 'rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/CMakeLists.txt'...

The <code>noc_block_gain_tb</code> is a folder generated to contain all the files related to the test bench of the <code>gain</code> block. Each time a new OOT block is created, a new folder will be generated as well.

Inside of this folder are the following three files:

* <code>CMakeLists.txt:</code> this is an empty file used, so far, only to increase the scope of the compilers.
* <code>noc_block_gain_tb.sv:</code> this is a ''System Verilog'' file, in which user custom tests are to be located. This is the '''only''' file that needs to be modified.
* <code>Makefile:</code> This file determines the directives that run the simulation.

The <code>noc_block_gain_tb.sv</code> testbench skeleton code creates the following architecture:

[[File:testbench_arch_gain_v01.png|center|800px|]]

Open the file <code>rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv</code> and modify the following lines:

Right under the “Verification” section:

initial begin : tb_main
string s;
logic [31:0] random_word;
logic [63:0] readback;
'''logic [15:0] gain;'''

In the “Test 4 -- Write / readback user registers” section:

`TEST_CASE_START("Write / readback user registers");
random_word = $random();
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, random_word[15:0]);'''
'''tb_streamer.read_user_reg(sid_noc_block_gain, 0, readback);'''
'''$sformat(s, "User register 0 incorrect readback! Expected: %0d, Actual %0d", readback[15:0], random_word[15:0]);'''
'''`ASSERT_ERROR(readback[15:0] == random_word[15:0], s);'''

In the “Test 5 -- Test sequence” section:

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin
cvita_payload_t send_payload;
for (int i = 0; i < SPP/2; i++) begin
send_payload.push_back(64'(i));
end
tb_streamer.send(send_payload);
end
begin
cvita_payload_t recv_payload;
cvita_metadata_t md;
logic [63:0] expected_value;
tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Test #4 verifies that we can write and readback the <code>gain</code> value. Test #5 writes to the <code>gain</code> register, sends a sample set in the form of a ramp (1, 2, 3, 4, etc) to the RFNoC gain block and finally reads the values from the <code>gain</code> block and compares them to expected values. The followings steps will allow the user to run this testbench.

From within the <code>rfnoc-tutorial</code> directory, create a <code>build</code> directory and enter it by running:

$ mkdir build && cd build/

The next step is to run <code>cmake</code>. If PyBOMBS was used to create the development sandbox, <code>cmake</code> will automatically detect the location of the <code>fpga</code> repository. If PyBOMBS was not used, the user must provide the location of where the <code>fpga</code> repository is installed.

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

$ cmake [-DUHD_FPGA_DIR=/PATH/TO/FPGA/REPOSITORY] ../

Final output from the <code>$ cmake ../</code> command:

-- Configuring done
-- Generating done
-- Build files have been written to: /home/widow/rfnoc/src/rfnoc-tutorial/build

The following command will modify the necessary files and set the correct path to the simulation tools. From now on, every time a new block is added, this command will be run automatically. Remember, only run the following command once for each OOT module (not RFNoC block, but OOT module) created:

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

The gain block testbench can be run by running the following command:

$ make noc_block_gain_tb

The simulation will start. Final output should look like this:

========================================================
TESTBENCH STARTED: noc_block_gain
========================================================
[TEST CASE 1] (t=000000000) BEGIN: Wait for Reset...
[TEST CASE 1] (t=000001002) DONE... Passed
[TEST CASE 2] (t=000001002) BEGIN: Check NoC ID...
Read GAIN NOC ID: 1111222233334444
[TEST CASE 2] (t=000001238) DONE... Passed
[TEST CASE 3] (t=000001238) BEGIN: Connect RFNoC blocks...
Connecting noc_block_tb (SID: 1:0) to noc_block_gain (SID: 0:0)
Connecting noc_block_gain (SID: 0:0) to noc_block_tb (SID: 1:0)
[TEST CASE 3] (t=000005457) DONE... Passed
[TEST CASE 4] (t=000005457) BEGIN: Write / readback user registers...
[TEST CASE 4] (t=000006888) DONE... Passed
[TEST CASE 5] (t=000006888) BEGIN: Test sequence...
[TEST CASE 5] (t=000007633) DONE... Passed
========================================================
'''TESTBENCH FINISHED: noc_block_gain'''
''' - Time elapsed: 7700 ns'''
''' - Tests Expected: 5'''
''' - Tests Run: 5'''
''' - Tests Passed: 5'''
'''Result: PASSED'''
========================================================
$finish called at time : 7700 ns : File "/home/widow/rfnoc/src/rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv" Line 10
INFO: [USF-XSim-96] XSim completed. Design snapshot 'noc_block_gain_tb_behav' loaded.
INFO: [USF-XSim-97] XSim simulation ran for 1000000000us
launch_simulation: Time (s): cpu = 00:00:10 ; elapsed = 00:00:12 . Memory (MB): peak = 966.387 ; gain = 54.848 ; free physical = 3080 ; free virtual = 29888
# if [string equal $vivado_mode "batch"] {
# puts "BUILDER: Closing project"
# close_project
# } else {
# puts "BUILDER: In GUI mode. Leaving project open."
# }
BUILDER: Closing project
****** Webtalk v2015.4 (64-bit)
**** SW Build 1412921 on Wed Nov 18 09:44:32 MST 2015
**** IP Build 1412160 on Tue Nov 17 13:47:24 MST 2015
** Copyright 1986-2015 Xilinx, Inc. All Rights Reserved.

source /home/widow/rfnoc/src/rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/xsim_proj/xsim_proj.hw/webtalk/labtool_webtalk.tcl -notrace
INFO: [Common 17-206] Exiting Webtalk at Tue Jan 10 23:26:20 2017...
INFO: [Common 17-206] Exiting Vivado at Tue Jan 10 23:26:22 2017...
Built target noc_block_gain_tb

With every custom block created, a <code>make</code> directive will be available to run the simulation from the <code>build</code> directory.

===Building the FPGA image with a custom user block===
In this section steps are given on how to initiate an FPGA build while incorporating the user’s custom RFNoC block. The first sections give general information on building RFNoC images. The remaining two sections show how to initiate FPGA builds using a command line interface and using a graphical interface (coming out soon), respectively.

====Discussion on number of blocks in an FPGA image====
There is a maximum number of blocks that can be added for each device. The maximum amount of computation engines (CEs/RFNoC blocks) that each device can use is 16, but the amount of custom blocks that can be added depends on the device.

If using a device from the X3xx series, from the 16 CEs, there are 6 that will be always added and are not subject to direct customization: 1 CE for the AXI bus, 1 CE for the Ethernet Interface, 2 Radios and 2 Dma FIFOS. Because of this, the application will only allow a number of 10 custom blocks on the X3xx series.

If using a device from the E3xx series, 2 CE engines are always added and are not subject to direct customization: 1 CE for the AXI bus and 1 Radio. This would virtually allow 14 slots for custom blocks. However, given the size of the FPGA on the E3xx series of devices, the application only allows a number of 6 custom blocks.

'''NOTE:''' Blocks with higher resource utilization may fill up the FPGA and force the user to include less blocks.

Verify the current maximum values by running the <code>uhd_images_builder.py</code> utility from the scripts directory.

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ uhd_image_builder.py --help

====Discussion on FPGA image targets====
RFNoC target names follow the pattern <code>{DEVICE}_RFNOC_{BUILD_TYPE}</code> with the following build types:

* <code>HG:</code> 1GigE on SFP+ Port0, 10Gig on SFP+ Port
* <code>XG:</code> 10GigE on both SFP+ ports
* <code>HLS:</code> Vivado High Level Synthesis enabled
* <code>sgX:</code> Speed grade for E300 devices (1 or 3)

Some examples are:
* <code>X310_RFNOC_HG</code>
* <code>X300_RFNOC_HG</code>
* <code>X310_RFNOC_XG</code>
* <code>X300_RFNOC_XG</code>
* <code>X310_RFNOC_HLS_HG</code>
* <code>X300_RFNOC_HLS_HG</code>
* <code>E310_RFNOC</code> (this is for the speed grade 1 FPGA version of E310, append <code>_sg3</code> for speed grade 3)

'''NOTE:''' E310, E312 and E313 all have the same FPGA hardware and therefore will use the <code>E310_RFNOC_{BUILD_TYPE}</code> target. USRP E3xx devices have either <code>sg1</code> or <code>sg3</code> hardware, please visit [http://files.ettus.com/e3xx_images/README here] to find out how to differentiate.

Additional information about the build targets can be found at the build instructions for USRP3, found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here].

====Image building using the command line====
The script <code>uhd_image_builder.py</code> is used to generate the NoC block instantiation file and build the FPGA image. Run the help menu by typing:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py --help

usage: uhd_image_builder.py [-h] [-I INCLUDE_DIR [INCLUDE_DIR ...]]
[-m MAX_NUM_BLOCKS] [--fill-with-fifos]
[-o OUTFILE] [-d DEVICE] [-t TARGET] [-g] [-c]
[blocks [blocks ...]]

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

optional arguments:
-h, --help show this help message and exit
-I INCLUDE_DIR [INCLUDE_DIR ...], --include-dir INCLUDE_DIR [INCLUDE_DIR ...]
Path directory of the RFNoC Out-of-Tree module
-m MAX_NUM_BLOCKS, --max-num-blocks MAX_NUM_BLOCKS
Maximum number of blocks (Max. Allowed for x310|x300:
10, for e300: 6)
--fill-with-fifos If the number of blocks provided was smaller than the
max number, fill the rest with FIFOs
-o OUTFILE, --outfile OUTFILE
Output /path/filename - By running this directive, you
won't build your IP
-d DEVICE, --device DEVICE
Device to be programmed [x300, x310, e310]
-t TARGET, --target TARGET
Build target - image type [X3X0_RFNOC_HG,
X3X0_RFNOC_XG, E310_RFNOC_sg3...]
-g, --GUI Open Vivado GUI during the FPGA building process
-c, --clean-all Cleans the IP before a new build

Here are details on the usage of the script which is followed by an example:

'''Blocks:''' The first arguments are the names of RFNoC blocks that the user wants to have compiled into the new image which are separated by a space. They can be custom blocks from the user’s OOT module or from the ones that are provided from Ettus, or a combination. Blocks provided by Ettus Research are listed (among other sources necessary for the FPGA build) in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/lib/rfnoc/Makefile.srcs</code> file.

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

However, as all the RFNoC blocks have the same <code>noc_block_</code> prefix, for simplicity this prefix is omitted when listing the blocks in the <code>uhd_image_builder.py</code> utility. As an example of the incorrect and correct way of adding blocks, consider the following examples when adding the <code>noc_block_null_source_sink</code> and <code>noc_block_siggen</code> blocks:

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

'''NOTE:''' Blocks generated by the RFNoC Modtool follow the same naming convention.

There is an increasing list of pre-built blocks. Here is a sample:

* <code>axi_fifo_loopback</code>
* <code>axi_dma_fifo</code>
* <code>fir_filter</code>
* <code>fft</code>
* <code>null_source_sink</code>
* <code>schmidl_cox</code>
* <code>packet_resizer</code>
* <code>split_stream</code>
* <code>vector_iir</code>
* <code>addsub</code>
* <code>window</code>
* <code>keep_one_in_n</code>
* <code>pfb</code>
* <code>export_io</code>
* <code>conv_encoder_qpsk</code>
* <code>siggen</code>
* <code>logpwr</code>
* <code>fosphor</code>
* <code>moving_avg</code>
* <code>ddc</code>
* <code>duc</code>

RFNoC related blocks generally reside in <code>fpga/usrp3/lib/rfnoc/</code>.

{| class="wikitable" style="margin:auto;"

!Block
!Filename
!Description
|-

|FIFO
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_axi_fifo_loopback.v noc_block_axi_fifo_loopback.v]
|Simple FIFO loopback / passthrough block.
|-

|FFT
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_fft.v noc_block_fft.v]
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_fir_filter.v noc_block_fir_filter.v]
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_window.v noc_block_window.v]
|Windowing block for use with FFT block.
|-

|Vector IIR
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_vector_iir.v noc_block_vector_iir.v]
|Single pole IIR with configurable coefficients that filters data along vectors (i.e. parallel streams of samples). Useful with FFT output.
|-

|Keep One in N
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_keep_one_in_n.v noc_block_keep_one_in_n.v]
|Keeps one packet every N packets.
|-

|AddSub
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_addsub.v noc_block_addsub.v]
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_null_source_sink.v noc_block_null_source_sink.v]
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_packet_resizer.v noc_block_packet_resizer.v]
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_split_stream.v noc_block_split_stream.v]
|Replicates an input stream to a configurable number of output streams.
|-

|}

'''NOTE:''' There is a restriction on the amount of blocks that can added into the FPGA image, see the section in this Application Note labeled [[Getting_Started_with_RFNoC_Development#Discussion_on_number_of_blocks_in_an_FPGA_image|Discussion on number of blocks in an FPGA image]] for more information.

<code>-I INCLUDE_DIR:</code> The <code>-I</code> directive provides the path to top OOT directory, which contains the users <code>rfnoc/fpga-src</code> directory which contains the custom blocks. This path is needed by the Xilinx Vivado tool. Inside the <code>fpga-src</code> directory there is a file called <code>Makefile.srcs</code> that contains the path of the OOT module and a list of all the custom OOT blocks. This is an auto generated file, which is amended every time a new block is added to the OOT module. Manually modifying this file is not recommended. If there are multiple OOT modules with various custom blocks that reside in different directories the way to include them all is by separating the different paths by a space (e.g. <code>-I /first/OOT/path/ /second/OOT/path/</code>).

'''IMPORTANT:''' Please be sure to terminate the path of your OOT with the "/" character. Otherwise the path might not be recognized.

<code>-d DEVICE:</code> The <code>-d</code> directive directs the script on which USRP device the build is for. If no <code>–d</code> is included the default is <code>–d x310</code>. Generation-3 USRPs and above all support RFNoC.

<code>-t TARGET:</code> The <code>–t</code> directive directs the script on which type of image to build for the chosen device. With each USRP device there are several build options to choose from. Detailed information about the build targets can be found at the build instructions for USRP3, found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here]. If <code>-t</code> is not included, a default target will be chosen for the given device. For example, the default <code>X310_RFNOC_HG</code> target builds for the <code>–d x310</code> device. More details on targets can be found in the section of this Application Note labeled [[Getting Started with RFNoC Development#Discussion_on_FPGA_image_targets|Discussion on FPGA image targets]].

<code>-m MAX_NUM_BLOCKS:</code> The <code>–m</code> directive specifies the max number of RFNoC blocks to build on the FPGA image. An RFNoC image does not need to fill all available slots with RFNoC blocks.

<code>--fill-with-fifos:</code> The <code>--fill-with-fifos</code> directive will fill the empty RFNoC block slots with FIFOS. As an example, if a user indicates three RFNoC blocks by name and also specifies <code>–m 5</code> then the other two slots will be filed with FIFOs.

<code>-o OUTFILE:</code> With the <code>-o</code> directive, the RFNoC blocks instantiation file is generated and saved at the desired path with the given name for the user to inspect. The FPGA image will NOT build if this directive is provided. The purpose of the <code>uhd_image_builder.py</code> script is to auto generate an instantiation file and populate the source files needed for the Xilinx Vivado tool to build the FPGA image, however, it may be desirable to only see the effect of adding a custom OOT module in the <code>fpga/</code> directory, or for inspecting the instantiation file. When the directive is not provided the <code>rfnoc_ce_auto_inst_x3x0.v</code> file is overwritten and the FPGA image build process will start automatically (standard use).

<code>-g, --GUI:</code> Open Vivado GUI during the FPGA building process

<code>-c, --clean-all:</code> Cleans the IP before a new build

Here is how to create an X310 FPGA image incorporating the <code>gain</code> block that was created earlier in this Application Note:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py gain ddc fft -I {USER_PREFIX}/src/rfnoc-tutorial/ -d x310 -t X310_RFNOC_HG -m 6 --fill-with-fifos

At the end of a successful compilation process, write the new image to a USRP. The following command will load the new image. Update the <code>{IP_Address}</code> of the USRP and <code>{USER_PREFIX}</code> to the appropriate values for your configuration before running the command.

$ uhd_image_loader --args "type=x300,addr={IP_ADDRESS}" --fpga-path {USER_PREFIX}/src/uhd-fpga/usrp3/top/x300/build/usrp_x310_fpga_RFNOC_HG.bit

'''NOTE:'''
* The FPGA image building process may take over an hour.

* FPGA images are specific to the USRP device NOT the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device. Additional instructions on flashing a custom image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

* [Environment setup] - The <code>uhd_image_builder.py</code> script will also set up the Xilinx Vivado environment by automatically running the <code>setupenv.sh</code> script located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{device}</code> directory. The <code>setupenv.sh</code> script assumes that Xilinx Vivado is installed in the default location of <code>/opt/Xilinx/Vivado</code>. If the installation is in a different directory the <code>setupenv_base.sh</code> script will need to be modified. The script is located at: <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts/setupenv_base.sh</code>

Besides the custom <code>gain</code> block, a <code>DDC</code> and <code>FFT</code> block are also being added along with three <code>FIFOs</code>. The <code>DDC</code>, <code>FFT</code> and <code>FIFO</code> blocks are already in the script's path and therefore do not need their path specified (they ship with the Ettus Research FPGA code). The reason three FIFOs are added is because the max number of blocks was specified to be 6 ( <code>-m 6</code> ) and since only 3 blocks were specifically named the other three slots are filled with FIFOs.

[[File:rfnoc gsg an 10.png|center|800px|]]

'''NOTE:''' Instructions on flashing the image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series. FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device.

Once the newly compiled image is loaded onto a USRP X3xx running the following command will show what RFNoC blocks are available on the FPGA:

$ uhd_usrp_probe

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * '''Block_0'''
| | | * DDC_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

'''NOTE:''' The reason the custom block is called <code>Block_0</code> and not <code>gain_0</code> is because there is still host side software/files that need updated in order for this block to populate it’s proper name. A following section (UHD Integration) will step through the process of updating those host side files.

====Using a graphical interface====
A graphical user interface for FPGA generation and building is shipped along with the <code>uhd_image_builder.py</code> script. This intuitive application aids in setting up a custom FPGA build.

This utility is located in the same <code>scripts</code> directory as <code>uhd_image_builder.py</code>.

To run it, enter the following commands:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts/
$ ./uhd_image_builder_gui

The application will then be launched:

[[File:rfnoc gsg an 11.png|center|800px|]]

'''1. Select build target:''' In this panel the available build targets are listed. This list may vary depending on which branch of the FPGA repository this user is using. Only RFNoC targets are listed. The build type descriptions are:

* <code>HG:</code> 1GigE on SFP+ Port0, 10Gig on SFP+ Port1
* <code>XG:</code> 10GigE on both SFP+ ports
* <code>HLS:</code> Vivado High Level Synthesis enabled
* <code>sgX:</code> Speed grade for E300 devices (1 or 3)

'''2. List of blocks available:''' In this panel the available blocks are listed that can be included into a custom design. This list separates the RFNoC blocks provided by Ettus Research and the OOT modules and corresponding blocks that the user adds. Given the hardware differences between the X3xx and E3xx devices, this list will dynamically change when a different device is selected from the panel on the left. This implies that it is necessary to add the OOT modules for each device independently. This is accomplished by using the <code>Add OOT Blocks</code> feature of the application, details of which are explained at #7 (<code>Add OOT Blocks</code>).

'''3. Blocks in current design:''' This section gives information on the MAX number of blocks for a given USRP (based on the target selection). There is a maximum number of blocks that can be added for each device. See the section in this App Note labeled "Discussion on number of blocks in an FPGA image" for more information.

'''4. Blocks in current design:''' This panel will be populated by adding elements from the available blocks. All the blocks listed in here will be compiled into the FPGA custom image. There is a maximum number of blocks that can be added for each device. See the section in this App Note labeled "Discussion on number of blocks in an FPGA image" for more information.

'''5. Add button (>>):''' Manually add the blocks from the central panel into your design.

'''6. Remove button (<<):''' Remove blocks from the current design (far-left panel)

'''7. Fill with FIFOs:''' By checking this box, the design will fill any available/unspecified block slots with FIFOs. The number of FIFO blocks that will be instantiated is based on the rules of amount of blocks explained at #3. When less than the max amount of blocks are needed for certain implementation, many users choose to fill their design with FIFO blocks.

'''8. Open Vivado GUI:''' Open Vivado GUI during the FPGA building process. This allows the user to save a Vivado project with all IP and work within the Vivado GUI for development.

'''9. Clean IP:''' Cleans the IP before a new build (recompiles all IP).

'''10. Add OOT blocks:''' Manually add RFNoC Modtool-generated OOT modules by pointing the application to the <code>Makefile.srcs</code> file, which is located in the <code>{USER_PREFIX}/src/{USER-OOT-moddir}/rfnoc/fpga-srcs/</code> directory. After adding this file, blocks will appear under “<code>OOT blocks for XXXX devices</code>”

'''11. Show Instantiation File:''' The application auto-generates the instantiation file that is going to be used by Vivado to build the FPGA image. This instantiation file can be viewed and edited before starting the build by clicking this button.

'''12. Import from GRC:''' If the user has a GNU Radio flowgraph with RFNoC blocks already in it, this application can read what RFNoC blocks are in the flowgraph and populate the <code>Blocks in current design</code> section of the application with the necessary RFNoC blocks. '''NOTE:''' All RFNoC blocks pulled from a <code>.grc</code> file must be in the of <code>List of blocks available</code> before beginning the build.

'''13. Generate .bit file:''' Start the build by clicking this button.

'''14. uhd_image_builder command:''' The command line command with arguments is dynamically build here as the user selects different options. The user could save this command to use next time they build/compile an FPGA image to avoid having to select all options again.

'''NOTE:''' See the latter end of the previous section for additional information on what to expect once the compile has started as well as final output.

==Creating Software/Host portion of custom RFNoC Block==
Now that the FPGA portion is complete the next step is to add software integration to UHD and GNU Radio as depicted in the RFNoC Stack below.

[[File:rfnoc gsg an 12.png|center|800px|]]

===UHD integration===
Despite the data processing happening on the FPGA, the host software still has a lot of responsibilities in order for an RFNoC application to function. For example, it needs to know which settings registers are available within an RFNoC block, or what kind of input and output a block has. All of this information goes into the <code>Block Declaration</code>, which is an XML file that is readable by UHD. Often, some simple logic needs to be embedded in the XML file, which we can do by using a simple scripting language called Noc-Script. Changes to the block declaration file are immediately imported into UHD every time an application is executed, and therefore, no software development toolchain needs to be set up.

The list of things declared by the block declaration file includes:

* Block name and Noc-ID
* Registers
* Inputs and outputs (including types)

In some cases, additional C++ code is required to properly control a block from software. In this case, a <code>Block Controller</code> file is required as well as the declaration file. In most cases, the default block controller provided by UHD is sufficient, so no C++ code needs to be written. Writing custom block controllers requires more effort, and means having to set up a programming toolchain. A common reason to write custom C++ block controllers is if setting a register requires a lot of computation, which is not feasible to do within a block declaration file (e.g., using Noc-Script).

Skeleton code for both the block declaration and the block controller (if required) can be generated through RFNoC Modtool.

Because the <code>gain</code> block does not require anything other than simply reading and writing to a single register the default block controller will suffice for this example. However, we will need to add information about the register.

Open the <code>gain.xml</code> file located in the <code>/rfnoc-tutorial/rfnoc/blocks</code> directory and add the following:

<?xml version="1.0"?>
<nowiki></nowiki>
<nocblock>
<name>gain</name>
<blockname>gain</blockname>
<ids>
<id revision="0">1111222233334444</id>
</ids>
'''<nowiki></nowiki>'''
'''<registers>'''
'''<setreg>'''
'''<name>GAIN</name>'''
'''<address>128</address>'''
'''</setreg>'''
'''</registers>'''
'''<nowiki></nowiki>'''
'''<args>'''
'''<arg>'''
'''<name>gain</name>'''
'''<type>double</type>'''
'''<value>1.0</value>'''
'''<check>GE($gain, 0.0) AND LE($gain, 32767.0)</check>'''
'''<check_message>Invalid gain.</check_message>'''
'''<action>'''
'''SR_WRITE("GAIN", IROUND($gain))'''
'''</action>'''
'''</arg>'''
'''</args>'''
<nowiki></nowiki>
<ports>
<sink>
'''<name>in0</name>'''
'''<type>sc16</type>'''
</sink>
<nowiki><source></nowiki>
'''<name>out0</name>'''
'''<type>sc16</type>'''
<nowiki></source></nowiki>
</ports>
</nocblock>

===GNU Radio Integration===
GNU Radio is built around the concept of blocks, similarly to RFNoC. When mapping RFNoC into an application, the simple constraint is made that every RFNoC block maps to a single GNU Radio block. Thus, when creating mixed GNU Radio/RFNoC applications, there is a very clear 1:1 mapping between what’s happening in RFNoC and GNU Radio.

Since most RFNoC blocks behave very similar to one another from GNU Radio’s perspective, it is generally not required to write C++ code for another block. Rather, a default block provided by RFNoC can be used with appropriate configuration. However, in some cases it may be desirable or even necessary to write a custom GNU Radio block for more specific controlling of the underlying RFNoC block. GNU Radio allows writing blocks in either C++ or Python, but since UHD and RFNoC do not have a Python API, a custom wrapper for an RFNoC block needs to be written in C++. RFNoC Modtool will create skeleton files for this purpose.

The most popular and effective way to use GNU Radio is through the graphical interface, the GNU Radio Companion (GRC). GRC requires a separate description of every GNU Radio block in order to become available in the graphical UI, and the same is true for an RFNoC block that is wrapped in a GNU Radio block (even if the generic RFNoC block wrapper is used). For GNU Radio 3.7 and earlier, GRC bindings for blocks are written as XML files with interspersed Cheetah or Python statements. For a more detailed tutorial on how to write these files, refer to the [http://gnuradio.org/redmine/projects/gnuradio/wiki GNU Radio Documentation] and associated [http://gnuradio.org/redmine/projects/gnuradio/wiki/Guided_Tutorials tutorials].

====GNU Radio Block Code====

* C++ or Python, although RFNoC blocks need to be written in C++ (if at all)
* How does GNU Radio interface to RFNoC?
** via C++ infrastructure code in <code>gr-ettus</code>
** <code>gr-ettus</code> provides a base RFNoC block class
** Users extend base class for their RFNoC blocks
** Many blocks can use base class “as is”
** No C++ or Python code!
* <code>rfnoc-tutorial/lib/gain_impl.cc</code>
** The gain block does not need anything additional

====GNU Radio Companion Bindings====
* XML
* Describes GNU Radio blocks to GRC
* No recompilation
* Requirement of GNU Radio Companion
* Not strictly necessary for GNU Radio
* Tutorial on how to write them:
** [http://gnuradio.org/redmine/projects/gnuradio/wiki/GNURadioCompanion http://gnuradio.org/redmine/projects/gnuradio/wiki/GNURadioCompanion ]
* Skeleton file generated by RFNoC Modtool

Open the <code>tutorial-gain.xml</code> file located in the <code>rfnoc-tutorial/grc</code> directory and edit as follows:

<nowiki><?xml version="1.0"?></nowiki>
<block>
<name>RFNoC: gain</name>
<key>tutorial_gain</key>
<category>tutorial</category>
<import>import tutorial</import>
<make>tutorial.gain(
self.device3,
uhd.stream_args( \# TX Stream Args
cpu_format="'''fc32'''",
otw_format="'''sc16'''",
args="gr_vlen={0},{1}".format(${grvlen}, "" if $grvlen == 1 else "spp={0}".format($grvlen)),
),
uhd.stream_args( \# RX Stream Args
cpu_format="'''fc32'''",
otw_format="'''sc16'''",
args="gr_vlen={0},{1}".format(${grvlen}, "" if $grvlen == 1 else "spp={0}".format($grvlen)),
),
$block_index, $device_index,
)
'''self.$(id).set_arg("gain", $gain)'''
'''</make>'''
'''<callback>set_arg("gain", $gain)</callback>'''
<nowiki></nowiki>

.
.
.

<option>
<name>Byte</name>
<key>u8</key>
</option>
</param>
<param>
<name>'''Gain'''</name>
<key>'''gain'''</key>
'''<value>1.0</value>'''
<type>'''real'''</type>
</param>

<nowiki></nowiki>
<sink>
<name>in</name>
<type>'''complex'''</type>
<vlen>$grvlen</vlen>
<domain>rfnoc</domain>
</sink>

<nowiki></nowiki>
<nowiki><source></nowiki>
<name>out</name>
<type>'''complex'''</type>
<vlen>$grvlen</vlen>
<domain>rfnoc</domain>
<nowiki></source></nowiki>
</block>

'''NOTE:''' Indentation spacing is important in the <code><make></code> section.

===Compile, Install and Verify===

$ cd {USER_PREFIX}/src/rfnoc-tutorial/build
$ make install

$ uhd_usrp_probe

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * '''gain_0'''
| | | * DDC_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

'''NOTE:''' In the case where the <code>gain_0</code> does not appear but <code>Block_0</code> does: Most likely, the XML block declaration file (see [[Getting_Started_with_RFNoC_Development#UHD_integration|UHD Integration]] section) for the block contains a NoC-ID that does not match with any NoC-ID defined in the hardware part of the design. The user has to be certain that the description files are up-to-date and that the NoC-ID matches in the SW and HW side. See the [[Getting_Started_with_RFNoC_Development#UHD_integration|UHD Integration]] section to update those host side files.

==Testing out the custom block==
At this point the custom <code>gain</code> RFNoc Block (Computation Engine) can be used within a GNU Radio flowgraph. Below is an example GRC flowgraph using our new block as well as the output application it produces.

[[File:rfnoc gsg an 13.png|center|800px|]]

'''NOTE:''' Copy Block: In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The “copy” block depicted in the screenshot above serves the function as a stream splitter . It’s main purpose, when “enabled”, is to copy the samples it is getting at its input and putting then into the output, but here it is also serving as a boundary between a RFNoC-domain and a GNURadio-domain. In the flowgraph above. after this boundary is passed, the data stream can easily be split into the two sinks to have them run simultaneously (standard GNU Radio functionality). It is possible to connect the GNU Radio blocks directly to RFNoC blocks without a “copy” block, but only one would work at a time (the other ones would have to be disabled). Another way to split data streams from the RFNoC-domain is to use the ”RFNoC: split stream” block, which would split the streams in the RFNoC domain, but this is not very useful here as we are, in any case, moving into the GNURadio-domain.

[[File:rfnoc gsg an 14.png|center|800px|]]

==Troubleshooting==
===Xilinx Vivado===
====Compile issues====
=====Synthesis is failing=====
Verify all the correct Xilinx [[Getting Started with RFNoC Development#Prerequisites|prerequisite software]] is installed.

Additional helpful information can be found in the following Xilinx forum posts:
* https://forums.xilinx.com/t5/Synthesis/Synthesis-failed-without-reporting-any-error/td-p/686000
* https://forums.xilinx.com/t5/Installation-and-Licensing/Vivado-on-Linux-synthesis-fails-with-no-error-message/td-p/732143

====Environment Setup====
The <code>uhd_image_builder.py</code> script will also set up the Xilinx Vivado environment by automatically running the <code>setupenv.sh</code> located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{device}</code> directory. The <code>setupenv.sh</code> script assumes that Xilinx Vivado is installed in the default location of <code>/opt/Xilinx/Vivado</code>. If the installation is in a different directory, then the <code>setupenv_base.sh</code> script will need to be modified. The script is located at: <code>{USER_PREFIX}/src/uhd-fpga/usrp3_rfnoc/tools/scripts/setupenv_base.sh</code>.

==Reference Files==
The following reference files are included within the gain_src.tar.gz archive linked below:

* gain.xml
* noc_block_gain.v
* noc_block_gain_tb.sv
* tutorial_gain.xml
* rfnoc_gain.grc

[[Media:gain src.tar.gz]]

==Links and Additional Resources==
===RFNoC additional resources===
* [https://youtube.com/watch?v=j-EfyPVpaJ8 Video: RFNoC Getting Started Video Tutorial]
* [http://lists.ettus.com/mailman/listinfo/usrp-users_lists.ettus.com USRP Mailing List]
* [https://kb.ettus.com/RFNoC RFNoC Software Resources Page]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf RFNoC Introduction]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]
* [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015 ]
** Explaining the slides of Intro, FPGA and Host presentations above (in that order).
* [https://www.youtube.com/watch?v=51rpjJ2W0Qs Video: It's the RFNoC Life for Us by Martin Braun at GRCon16, 2016]

===GNU Radio resources===
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNU Radio OutOfTree Modules tutorial]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio Installation]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/Tutorials GNU Radio Tutorials]

===UHD resources===
* [http://lists.ettus.com/mailman/listinfo/usrp-users_lists.ettus.com USRP Mailing List]
* [https://kb.ettus.com/UHD UHD Software Resources Page]
* [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]
* [http://files.ettus.com/manual/ UHD Manual]

===Other resources===
* [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]
* [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD + GNU Radio Application Note (Linux)]
* [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS]

[[Category:Application Notes]]

Debugging FPGA images

2017-07-11T20:44:38Z

NicolasCuervo: /* Save the project and finish Synthesis */

= Application Note Number =
'''AN-121'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo Sugandha Gupta
|style="text-align:center;"| Initial creation
|}

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench. In addition, there is plenty of online resources (such as [8]) that provide enough information to get you started with your simulation.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

* '''UHD, GNURadio and gr-ettus: ''' At the end of the debugging process we will be running the application on a physical device, and for that we need the core code downloaded and installed. UHD will serve as our device driver, GNURadio the frame on which our app will run, and gr-ettus is needed for our ''signal generator'' block. If you need guidance on this, please refer to the [https://kb.ettus.com/Getting_Started_with_RFNoC_Development#Creating_a_development_environment Creating a development environment] section of our ''Getting started guide''. If you are debugging your own RFNoC OOT module, this will have to be installed as well.

* '''RFNoC supported device: ''' The whole point of chipscoping is having the ability of probing signals from a hardware design at runtime. Hence, a device where the application is going to run is needed. In this tutorial we will be using an X310 device.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./uhd_image_builder.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">uhd_image_builder.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">uhd_image_builder.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =
After the bitstream generation is completed successfully, it is time for us to move on and put our design into the device. On the left pannel, right below we generated our bitstream, is the "Hardware Manager". At this point, we have our X310 connected via JTAG for programming purposes, and via Ethernet (1G in this specific use case) for later usage. Now, click on 'Open Target'. If you have only one device connected, the option "auto-connect" should work just fine. Otherwise, select your device by clicking on "Open new target" and following the options in order to find the device you want. After doing so, two options should appear at the top of your Vivado window:

[[File:cs_6.png|center|Hardware options|link=https://kb.ettus.com/images/9/9e/cs_6.png]]

As a first step, click on "Program device". Usually, again, Vivado picks up the bitstream that you just generated. However, if you have been running multiple bitstream builds and/or have multiple Vivado projects, it is possible that you would have to look for the right bitstream. It should be under the project that you have been working during the generation of your debug bitstream.

After programing, you have to run an initialization routine on your device. A way to do this is to run a usrp probe, which will also tell us several interesting information. In a terminal, run:

$ uhd_usrp_probe

This will tell you information about the device. In our case, the last portion of the output should look like this:

| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * SigGen_0
| | | * DUC_0
| | | * DDC_0

which tells us that the blocks '''Signal Generator, DUC and DDC''' were correctly added into the device. Keep in mind that the DmA FIFO and two instances of the radio are added by default into an X310 device. Now, go back to the Vivado GUI and click on "Refresh device" right on the top of the Vivado Window. After that, your debugging signals should appear and you are ready to start chipscoping.

== Selecting Triggers ==
While probing your design, you probably want to know the state of a given signal right at the moment at which it or other signal changed. In some cases you can have a short simulation and you can ''eye-ball'' your signals and see if the results are as expected. However, sometimes signals change very fast or have a really short duration, making a qualitative procedure a little bit more complicated. For that case, you can set up '''triggers''', which means that the chipscope tool will start capturing when a desired signal changes. We are going to use this feature here and is recommended to do so to have more control over the signal capturing.

[[File:cs_7.png|center|Trigger Setup|link=https://kb.ettus.com/images/e/e1/cs_7.png]]

Here we are going to choose two signals as triggers, which are '''s_axis_data_tvalid''' and '''s_axis_data_tready'''. The names are almost self explanatory: they state when the device has valid data and when it is ready (see [4] for further information). After choosing this signals, now we have to put our device to work. Even, you can click on "run trigger for this ILA core", which will let the device on idle state waiting for the trigger.

[[File:cs_9.png|center|Trigger Setup. You can also see the black panel where all the debug lines are listed.|link=https://kb.ettus.com/images/7/74/cs_9.png]]

== Debugging at run time ==
This is what we came for. The block is to be put in a normal use case where it will run and, simultaneously, we will probe signals from it. For the '''RFNoC: Signal Generator''', we are going to use GNURadio to set up the application. Actually, we are going to use the siggen example that is shipped within ''gr-ettus''. We open to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}{path_to_gr-ettus}/examples/rfnoc/rfnoc_siggen.grc</syntaxhighlight>, where a simple setup is ready to show the siggen working.

[[File:cs_8.png|center|GNURadio example for the RFNoC: Signal Generator block|link=https://kb.ettus.com/images/d/d1/cs_8.png]]

You can see that there is a number of options which can be modified. As we choose to check how signal such as "Wave type" and "gain", we are going to focus on this for now. They can be modified on runtime, but every time that they are set to a different value the trigger has to be run again on the Vivado chipscope. Following are some of the expected results:

'''Signal type: Constant || Gain: 1: ''' In this case the signal "wave type" is set to 0, as it being the first option available in the block. The Gain is set to 7FFF, which is the maximum hexadecimal value that the register is able to receive in this case and which means the maximum absolute gain.
[[File:cs_10.png|center|Signal type: Constant || Gain: 1|link=https://kb.ettus.com/images/7/72/cs_10.png]]

'''Signal type: Sinusoid || Gain: 1: ''' Now the wave type is set to 1, being the next option available. The gain is unchanged to show how it holds the same value in the readback register.
[[File:cs_12.png|center|Signal type: Sinusoid || Gain: 1|link=https://kb.ettus.com/images/5/56/cs_12.png]]

'''Signal type: Noise || Gain: 0.5: ''' Wave type and gain are both changed, showing results somewhat expected: wave type is set to 2, being sequentially the next option available, and the gain is set to half of the maximum value, which is shown to be true also in its hexadecimal representation read from the readback register.
[[File:cs_14.png|center|Signal type: Noise || Gain: 0.5|link=https://kb.ettus.com/images/9/9a/cs_14.png]]

If you have come successfully until this point, then you can play around with the signals and checking the result in the debugging panel or, even better, apply this technique to debug your own RFNoC design!

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

[8] [https://www.xilinx.com/support/documentation/application_notes/xapp199.pdf Xilinx AN - Writing efficient Testbenches]

Synchronization and MIMO Capability with USRP Devices

2017-06-01T13:38:19Z

NicolasCuervo: /* Additional Resources */

==Application Note Number==
'''AN-882'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-05-01
|style="text-align:center;"| Neel Pandeya Nate Temple
|style="text-align:center;"| Initial creation
|}

==Abstract==
This AN provides insight into the topics of USRP architecture, system bandwidth, host interface throughput, and available sampling rates.
Discusses the requirements for Multiple-In-Multiple-Out (MIMO) and phased-array systems. Summarizes the MIMO capability of each USRP device and daughterboard, and shows how to build MIMO systems with the USRP product family.

==Overview==
Some applications require synchronization across multiple USRPTM (Universal Software Radio Peripheral) devices. Ettus ResearchTM provides several convenient solutions for synchronization. For example, two USRP N210s can be synchronized using a MIMO cable. It is also possible to synchronize more than two units using the Ettus Research OctoClock. Optional GPS-disciplined oscillators provide the capability to synchronize devices to the GPS standard over a large geographic area. This document will introduce and explain the synchronization features of the USRPTM product family and how to meet the requirements of multi-channel applications.

==MIMO System Requirements – Time and Frequency Synchronization==
For a transceiver to be considered MIMO-capable, each channel in the system must meet two basic requirements:

#The sample clocks must be synchronized and aligned.
#DSP operations must be performed on samples aligned in time – from the same sample clock edge.

The Ettus Research USRP N200/N210 is recommended for MIMO applications. Two USRP N200/N210s can be synchronized with the USRP MIMO cable. It is also possible to build larger MIMO systems (up to 16x16) by distributing an external reference.

==Beamforming and Direction Finding Requirements==
Some applications, such as beamforming and direction finding, place additional requirements on the system. In addition to sample time and sample clock alignment, the system must maintain a known phase relationship between each RF input or output. Due to phase ambiguities caused by phased- locked loops which are used for up and down-conversion, some calibration may be required to determine this phase relationship.

It is possible to calibrate a multi-channel system by producing a tone that is distributed to the inputs of each USRP device with match-length RF cables. An illustration of a system that uses this methodology is shown in Figure 1. User-developed software running on the host PC is used to measure the phase and amplitude differences of each channel and apply a correction.

[[File:Mimo figure 1.png|700px|center]]

==Other Variables That Effect Phase Alignment==
As mentioned, other components aside from local oscillators contribute to phase error. Filters, mixers, amplifiers and other components produce phase offsets that vary with time, temperature, mechanical conditions, etc. These types of errors can generally be calibrated out with intermittent, low-rate routines that detect the channel-to-channel phase with a calibration tone. These errors will not change with each PLL retune but may change with time and temperature variation. Thus, applications that require RF phase alignment may require periodic calibration.

==USRP B100 and E100 – Not Recommended for MIMO==
Like the USRP N200/N210, the USRP B100 and E100/110 can be synchronized with an external reference and PPS source. However, this does not imply the USRP B100 and E100/E110 are MIMO capable. The flexible frequency clocking architecture used in these devices produces phase ambiguity in ADC/DAC sample clocks. Therefore, sample edges will not be aligned.

Despite the sample edge misalignment, it is still possible to produce samples with relatively accurate time stamps. This is useful for time-difference-of-arrival or similar algorithms.

One exception to these statements is when you make use of a daughterboard containing more than one channel in a single slot. For example, LFRX/TX, BasicRX/TX, and TVRX2 can all be used to achieve MIMO capability with a USRP B100 or E100/110.

==Synchronization with GPS Disciplined Oscillator==
It is possible to provide time-synchronization over a wider geographic area with a GPS disciplined oscillator (GPSDO). A GPSDO derives 10 MHz/PPS signals from the GPS system. The GPSDO is accurate to approximately +/-50 ns across the globe. Ettus Research provides an optional GPSDO module with the USRP N200/N210. There is also an upgraded version of the OctoClock, which includes an internal GPSDO.

[[File:Mimo figure 2.png|300px|center]]

==MIMO Capability of Ettus Research USRP Devices==
Table 1 provides an overview of the synchronization and MIMO capabilities of the USRP product line.

{| class="wikitable" style="margin: auto;"
!USRP Model
!BW Capability (MSPS w/ 16-bit)
!MIMO Capable
!Ext Ref. Input
!1 PPS Input
!Internal GPS Disiplined Oscillator (Optional)
!Plug and Play MIMO
|-
|N200
|25
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|-
|N210
|25
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|-

|X300
|200
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|-

|X310
|200
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|-

|B200
|61.44
|style="text-align:center;" |
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |
|-

|B210
|61.44
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|-

|B200mini
|61.44
|style="text-align:center;" |
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |
|style="text-align:center;" |
|-

|B205mini
|61.44
|style="text-align:center;" |
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |
|style="text-align:center;" |
|-

|E310
|61.44
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |
|style="text-align:center;" |X
|-

|E312
|61.44
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |X
|style="text-align:center;" |
|style="text-align:center;" |X
|-
|}

<center>Table 1- USRP Synchronization Capabilities</center>

The RF daughterboard selection also impacts the synchronization experience. Most daughterboards use a fractional-N synthesizer to generate the local-oscillator signals. Generally, these fractional- N synthesizers introduce a random phase offset after each retune. If phase alignment between all RF channels is required, this random phase offset will need to be measured and compensated for in software. The SBX PLL includes a resync feature that resets to a fixed phase after each retune. Thus, it may not need to be calibrated after each retune, but may require periodic calibration. This makes the SBX daughterboard the most ideal option for phased-array applications that fall within its frequency range. Also, the BasicRX/TX and LFRX/TX boards do not contain local oscillators that introduce phase errors.

{| class="wikitable" style="margin: auto;"
!
!MIMO Capable
!Phase Sync Feature?
|-
|CBX
|Yes
|No
|-
|SBX
|Yes
|Yes
|-

|UBX
|Yes
|Yes *
|-

|WBX
|Yes
|Yes, +/- 180 deg
|-
|XCVR2450
|Yes
|No
|-
|DBSRX2
|Yes
|No
|-
|TVRX2
|Yes
|No
|-
|BasicRX/BasicTX
|Yes
|No
|-
|LFRX/LFTX
|Yes
|No
|}
<center>Table 2 - Synchronization Capability vs. Daughterboard and USRP</center>
<center>''* UBX Phase Sync only supported on X300/X310''</center>

==USRP N200/N210 – Plug and Play 2x2 MIMO System==
The easiest method to implement a high-performance 2x2 MIMO system is to utilize two N200/N210s synchronized with an Ettus Research MIMO cable. In this configuration, a single Gigabit Ethernet(GigE) interface can be used to communicate with both USRP devices. The USRP connected to the GigE acts as a switch and routes data to/from both USRP devices. It will also handle time synchronization of the data so the sample alignment process is transparent to the user. The total sample rate for USRP devices connected to a single GigE port on the host computer cannot exceed 25 MS/s in 16-bit mode, or 50 MS/s in 8-bit mode.

==Application Example – Visual Phase Alignment with N210 2X2 MIMO System==
The UHD API allows you to select synchronization settings for each USRP device. These settings are also exposed through GNU Radio blocks. This allows for a quick, illustrative example of how to use the N200/N210 to build a MIMO system. GNU Radio Companion (GRC) is used for this basic illustration.

Figure 3 shows a flowgraph that receives two streams from two unsynchronized USRP devices. A 400.01 MHz tone is injected into both USRP devices, which are tuned to 400.00 MHz. The flow graph separates the real component of each complex baseband signal and plots them together on a WX GUI Scope. When the two USRP devices are synchronized, the scope sill show two, 10 kHz tones with constant relative phase. In this test case, the USRP devices are unsynchronized. Notice in Figure 4 that there are obvious phase and frequency differences between the two signals. This is a result of variations in the two unsynchronized reference clocks. Heat is applied to one of the USRP device’s internal reference crystals to amplify the frequency variation between the two units.

[[File:Mimo figure 3.png|700px|center]]

[[File:Mimo figure 4.png|700px|center]]

Next, plug-and-play 2X2 system is illustrated in Figure 5. Notice the relative simplicity of the system. A MIMO system is created by connecting two N200/N210s with a MIMO cable, which shares Ethernet connectivity and common 10 MHz/PPS signals. Like the unsynchronized setup that produce the scope view in Figure 4, a signal generator drives the receiver inputs of both inputs. A block diagram of the synchronized system is shown in Figure 5. The flowgraph is shown in Figure 6.

[[File:Mimo figure 5.png|700px|center]]

[[File:Mimo figure 6.png|700px|center]]

A single UHD block is used in the GRC flowgraph. The block parameters are configured to set up a 2x2 MIMO system. The settings of interest are:

Device addr: addr0=192.168.10.2,addr1=192.168.10.3 Sync = don't sync
Num Mboards = 2
Mb0 Clk Src = Default
Mb0 Time Src = Default
...
Mb1 Clk Src = MIMO Cable Mb1 Time Src = MIMO Cable

These settings configure the first USRP device, Mb0, which corresponds to the first entry in the address string, to use its default reference for clocking and timing. The second USRP(Mb1) is configured to accept its frequency and timing reference from the MIMO cable. The signals are provided by Mb0. All other standard settings such as center frequency and gain assignments apply as well.

Like the first flowgraph shown, the real part of each USRP stream is displayed on a scope. A phase correction block is included to compensate for the random, but constant, phase offset discussed earlier in this paper. Figure 7 includes a screenshot of the resultant display both before phase adjustment. Note the phase is constant and the tones are the same frequency.

[[File:Mimo figure 7.png|700px|center]]

Figure 8 shows the signals with phase correction applied. In this plot, it is clear the MIMO connection has enabled the frequency and time references to be synchronized. The random phase offset is corrected with a complex phase shift in the flowgraph. In real applications, this phase correction would be implicitly generated with algorithms such as maximum-ratio combining (MRC), or periodic calibration.

[[File:Mimo figure 8.png|700px|center]]

This is a simple illustration of the MIMO capability provided by the USRP N200/N210. In most applications the phase compensation is implemented with some automated process. However, calibrating the devices with this type of manual correction is certainly an option.

All principles illustrated in this example are applicable to operations in the transmit direction.

==Synchronization with 10 MHz and 1 PPS Signals==
While the USRP N200 and N210 provide plug-and-play MIMO capability with the Ettus Research MIMO cable, it is also possible to synchronize multiple devices using external 10 MHz and 1 PPS distribution. This is useful if the developer would like to use a high-accuracy external reference such as a Rubidium source. It is also helpful if the developer must build a MIMO system with more than two channels.

If common PPS and 10 MHz signals are distributed to USRP N-Series devices, it is theoretically possible to build arbitrarily large MIMO systems. In practice, developers have built systems with up to 16 synchronized USRP devices.

The Ettus Research OctoClock and OctoClock-G make it easy to distribute 10 MHz and 1 PPS signals for multi-channel operation. The OctoClock serves as an 8-way PPS and 10 MHz reference splitter. The user must provide a single 10 MHz and 1 PPS signal. The upgraded OctoClock-G includes a high-accuracy, internal GPS-disciplined oscillator and does not require external signals to be supplied. Figure 9 illustrates the use of an OctoClock-G to create an 8x8 MIMO system.

[[File:Mimo figure 9.png|700px|center]]

All timing signals from the OctoClock should be connected to the USRP devices with matched length cable of the same type and connectorization. This ensures that there is low skew between all of the channels.

==Synchronization Signals – Input Levels==
To achieve optimum performance and prevent damage to the USRP devices, the designer must assure that the input levels fall with specified limits. Guidance for input voltage levels and power levels for the 1 PPS and 10 MHz inputs are shown in Table 3.

{| class="wikitable" style="margin: auto;"
!USRP Model
!1 PPS Specification
!External Ref. Specification*
|-
|N200
|3.3-5V
|0 to 18 dBm
|-
|N210
|3.3-5V
|0 to 18 dBm
|-
|}

*50 ohm Terminated

==Additional Resources==
UHD API For Synchronization https://files.ettus.com/manual/page_sync.html

OctoClock-G Product Page https://www.ettus.com/product/details/OctoClock-G

GPSDO Module for USRP N200/N210 https://www.ettus.com/product/details/GPSDO-KIT

[[Category:Application Notes]]

TwinRX

2017-05-12T11:34:20Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The TwinRX daughterboard for the USRP X Series SDR platform is a two-channel superheterodyne receiver designed for high performance spectrum monitoring and direction finding applications. The receiver is tunable from 10 MHz - 6 GHz and has 80 MHz of instantaneous bandwidth per channel, providing the versatility necessary to analyze a variety of signals in multiple bands of interest. Each channel has an independent RF signal chain with preampilifiers, preselectors, and two mixer stages for superior selectivity. Users can tune the two channels independently to simultaneously monitor uplink and downlink communication with a combined bandwidth of 160 MHz. The ability to share the LO between channels across multiple daughterboards enables the phase-aligned operation required to implement scalable multi-channel phased-arrays. The receiver is capable of fast frequency hopping to detect frequency agile emitters. Configurable RF attenuation and preamplication allow users to optimize dynamic range in favor of noise figure for faint signals, or IP3 for stronger signals. UHD automatically configures the RF signal path for optimized performance in the pre-defined use cases, and provides the flexibility to adjust settings manually. Support for RFNoC on the X Series motherboard enables deterministic FPGA-accelerated computations for real-time spectrum analysis.

[[File:TwinRX BlockDiagram.png|1000px|center]]

== Key Features==
{|
|style="vertical-align:top"|
* Two-Channel Superheterodyne Receiver
* Frequency Range: 10 MHz - 6 GHz
* Bandwidth: 80 MHz per channel ( 160 MHz total )
* RF shielding
* Independent RF signal channels with optional LO sharing
|[[File:TwinRX large.png|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 superheterodyne frontends (2 receive)
* 80 MHz per channel
* Independent tuning
* LO Sharing Capability
* Coherent and phase-aligned operation
* Preselection Filters
* RF Shielding

===Antennas===
Receive: '''RX1''' or '''RX2'''

===Gains===
* Receive Gains Range: 0-95dB

===Bandwidths===
* TwinRX: 80 MHz per channel ( 160 MHz total )

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===Ports===
The TwinRX has six MMCX RF connectors on it.

{|class="wikitable"
!Connector
!Description
!Damage Threshold/Max Output
|-

| J1
| LO2 Export
| 0 dBm output
|-

| J2
| LO2 Input
| +20dBm input
|-

| J3
| LO1 Export
| +5 dBm output
|-

| J4
| LO1 Input
| +10dBm input
|-

| J5
| Antenna 1 connector (RX1)
| +10 dBm input
|-

| J6
| Antenna 2 connector (RX2)
| +10 dBm input
|-
|}

===Preselector Filters===
{|
|style="vertical-align:top"|

{|class="wikitable"
!Band
!Range
|-

|LB1
|10 - 500 MHz
|-

|LB2
|500 - 800 MHz
|-

|LB3
|800 - 1.2 GHz
|-

|LB4
|1.2 - 1.8 GHz
|-

|HB1
|1.8 - 3.0 GHz
|-

|HB2
|3.0 - 4.1 GHz
|-

|HB3
|4.1 - 5.1 GHz
|-

|HB4
|5.1 - 6.0 GHz
|-

|}

|style="vertical-align:top"|[[File:TwinRX Normalized Preselector Response.png|650px|center]]
|}
* Each preselector filter has a ±40 MHz band overlap.

==RF Specifications==
'''Freq Range'''
* 10MHz - 6GHz

'''Noise Figure'''
{| class="wikitable" style="width:60%"
!Frequency
!Preamp Enabled
|-

| 10 MHz - 3 GHz
| < 5
|-

| 3 GHz - 5 GHz
| < 4
|-

| 5 GHz - 6 GHz
| < 8
|-

|}

'''RX Third Order Intercept (dBm)'''
{| class="wikitable" style="width:60%"

!Frequency
!Full Scale = -45 dBm
!Full Scale = -30 dBm
!Full Scale = -20 dBm
|-

| 10 MHz - 1.8 GHz
| -8
| -2
| 16
|-

| 1.8 GHz - 3 GHz
| -10
| -1
| 14
|-

| 3 GHz - 6 GHz
| -13
| -1
| 12
|-

|}

'''Phase Noise (dBc/Hz)'''
{| class="wikitable" style="width:60%"
!Frequency Offset
! 0.9 GHz
! 2.4 GHz
! 5.8 GHz
|-

| 10 kHz
| -88
| -86
| -82
|-

| 100 kHz
| -105
| -107
| -103
|-

| 1 MHz
| -124
| -127
| -127
|-

|}

===Input/Output Impedance===
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD. Minimum UHD version is 3.10.0.0

===TwinRX===
* Current Hardware Revision: 2
* Minimum version of UHD required: 3.10.0.0
* Minimum version of GNU Radio required: 3.7.10

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
* X Series only

==Phase Synchronization==
The TwinRX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. Please note that the TwinRX is receive-only. The SBX and UBX daughterboards are also recommended for phase-coherent applications, and are capable of both transmit and receive operations.

==Schematics==
The TwinRX daughterboard is composed of two PCBs, the Intermediate Frequency (IF) board and the RF board. There are two functionally identical revisions of TwinRX at the moment. Please check the back of your TwinRX to see which you have. The schematics for TwinRX revision B should answer most possible questions. If you have any further questions please email [mailto:support@ettus.com support@ettus.com].

TwinRX Revision A - (159685A-01)
* IF Board Revision B - (158671B-01L)
* RF Board Revision C - (156263C-01L)

TwinRX Revision B - (159685B-01)
* IF Board Revision C - (158671C-01L)
* RF Board Revision D - (156263D-01L)

[[File:TwinRX IF Board Rev C.pdf]]

[[File:TwinRX RF Board Rev D.pdf]]

==RF Connectors==
{|
|style="vertical-align:top"|
The antenna ports are MMCX connectors with 50 ohm input impedance. By default Antenna 1 (RX1) is routed to Channel 1 and Antenna 2 (RX2) to Channel 2. This routing can be changed to swap the antennas or to share a single antenna to both channels. The damage threshold for the antenna inputs is 10 dBm. In practice the available gain makes much lower input powers recommended for achieving the best dynamic range and noise figure.
|[[File:TwinRX 80 Inputs.jpg|250px|center]]
|}

==Local Oscillator Connectors==
Note: LO sharing cables are not required for a single TwinRX setup. LO sharing cables are only required with two TwinRX daughterboards in a single USRP X300/X310.

{|
|style="vertical-align:top"|

{|class="wikitable"

! Connector
! Description
! Min
! Nominal
! Damage
|-

| J1
| LO2 Export
| 0 dBm
| 3 dBm
| NA (Output)
|-

| J2
| LO2 Input
| 0 dBm
| 2 dBm
| 20dBm
|-

| J3
| LO1 Export
| -12 dBm
| 5 dBm
| NA (Output)
|-

| J4
| LO1 Input
| -10 dBm
| -5 dBm
| 10dBm
|-

| Antenna 1 connector
| RX 1
|
|
| 10 dBm
|-

| Antenna 2 connector
| RX 2
|
|
| 10 dBm
|-

|}

| style="padding-left: 30px" | [[File:TwinRX 80 LOs.jpg|250px|center]]
|}

===LO Sharing with Neighbour TwinRXs===
{|class="wikitable"
!TwinRX (A Slot)
!TwinRX (B Slot)
|-
|J1 LO2 Export
|J2 LO2 Input
|-
|J2 LO2 Input
|J1 LO2 Export
|-
|J3 LO1 Export
|J4 LO1 Input
|-
|J4 LO1 Input
|J3 LO1 Export
|-

|}

==Software API==

===New Multi USRP Functions===
The advanced functionalities of the TwinRX will be exposed through new functions implemented in [http://files.ettus.com/manual/classuhd_1_1usrp_1_1multi__usrp.html Multi-USRP].

===Antenna Mapping===
The two channels of the TwinRX can be independently configured to use either of the two antenna ports, '''RX1''' and '''RX2''' using the standard antenna selection function in <code>multi_usrp</code>.

virtual void set_rx_antenna(const std::string &ant, size_t chan = 0) = 0;

Select the RX antenna on the frontend.
* '''ant''' the antenna name
* '''chan''' the channel index 0 to N-1

===Local Oscillator Control and Routing===
The TwinRX has two channels, '''CH1''' and '''CH2''' and each channel has two local oscillators, '''LO1''' and '''LO2'''. The local oscillators for a channel can be sourced from that channel's '''internal''' synthesizers, the '''companion''' channel's synthesizers, or '''external''' inputs. The value <code>multi_usrp::ALL_LOS</code> can be used to specify that the command be run on both synthesizers for a channel. The defaults are to operate on

virtual std::vector<std::string> get_rx_lo_names(size_t chan = 0) = 0;

Get a list of possible LO stage names
* '''chan''' the channel index 0 to N-1
* Returns a vector of strings for possible LO names

virtual void set_rx_lo_source(const std::string &src, const std::string &name = ALL_LOS, size_t chan = 0) = 0;

Set the LO source for the usrp device. For USRPs that support selectable LOs, this function allows switching between them. Supported options for source: internal, external, companion.
* '''src''' a string representing the LO source
* '''name''' the name of the LO stage to update
* '''chan''' the channel index 0 to N-1

virtual const std::string get_rx_lo_source(const std::string &name = ALL_LOS, size_t chan = 0) = 0;

Get the currently set LO source.
* '''name''' the name of the LO stage to query
* '''chan''' the channel index 0 to N-1
* Returns the configured LO source

virtual std::vector<std::string> get_rx_lo_sources(const std::string &name = ALL_LOS, size_t chan = 0) = 0;

Get a list of possible LO sources.
* '''name''' the name of the LO stage to query
* '''chan''' the channel index 0 to N-1
* Returns a vector of strings for possible settings

virtual double set_rx_lo_freq(double freq, const std::string &name, size_t chan = 0) = 0;

Set the RX LO frequency.
* '''freq''' the frequency to set the LO to
* '''name''' the name of the LO stage to update
* '''chan''' the channel index 0 to N-1
* Returns a coerced LO frequency

virtual double get_rx_lo_freq(const std::string &name, size_t chan = 0) = 0;

Get the current RX LO frequency.
* '''name''' the name of the LO stage to query
* '''chan''' the channel index 0 to N-1
* Returns the configured LO frequency

virtual freq_range_t get_rx_lo_freq_range(const std::string &name, size_t chan = 0) = 0;

Get the LO frequency range of the RX LO.
* '''name''' the name of the LO stage to query
* '''chan''' the channel index 0 to N-1
* Returns a frequency range object

===Exporting Local Oscillators===

virtual void set_rx_lo_export_enabled(bool enabled, const std::string &name = ALL_LOS, size_t chan = 0) = 0;

Set whether the LO used by the usrp device is exported For USRPs that support exportable LOs, this function configures if the LO used by chan is exported or not.
* '''enabled''' if true then export the LO
* '''name''' the name of the LO stage to update
* '''chan''' the channel index 0 to N-1 for the source channel

virtual bool get_rx_lo_export_enabled(const std::string &name = ALL_LOS, size_t chan = 0) = 0;

Returns true if the currently selected LO is being exported.
* '''name''' the name of the LO stage to query
* '''chan''' the channel index 0 to N-1

==Drawings==
* [[File:cu usrp twinrx cca.pdf]]

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

CBX

2017-05-12T11:33:55Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The CBX is a full-duplex, wideband transceiver that covers a frequency band from 1.2 GHz to 6 GHz with a instantaneous bandwidth of 40 MHz or 120 MHz. The CBX can serve a wide variety of application areas, including WiFi research, cellular base stations, cognitive radio research, and RADAR.

The CBX does not provided phase coherent operation, and therefore is not recommended for MIMO and Phased Array applications.

== Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 1.2GHz - 6GHz
* Versions: 40MHz / 120MHz
|[[File:Product cbx 40.jpg|250px|center]]
|[[File:Product cbx 120.jpg|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using a CBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* CBX: 40 MHz, RX & TX
* CBX-120: 120 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* All LEDs flash when daughterboard control is initialized
* '''TX LD''': Transmit Synthesizer Lock Detect
* '''TX/RX''': Receiver on TX/RX antenna port (No TX)
* '''RX LD''': Receive Synthesizer Lock Detect
* '''RX1/RX2''': Receiver on RX2 antenna port

==RF Specifications==
'''Freq Range'''
* 1.2GHz - 6GHz

'''Noise Figure'''
* 5 - 7.5 dB @ (1.2GHz ~ 5GHz)
* 7.5dB - 10 dB (5GHz ~ 6GHz)

'''RX IIP3 (Max)'''
* 8 - 10 dBm

'''RX IQ Imbalance'''
* -20 dBc

'''TX Power (Max)'''
* 22 dBm @ (1.2GHz ~ 3GHz)
* 12 ~ 22 dBm @ (3GHz ~ 6GHz)

'''TX OIP3'''
* 30 - 32 dBm @ (1.2GHz ~ 5GHz)
* 26 ~ 30 dBm @ (5GHz ~ 6GHz)

'''TX IQ Imbalance'''
* -20 dBc

'''Input/Output Impedance'''
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===CBX===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===CBX-40===
* N or X Series

===CBX-120===
* X Series only

==Phase Synchronization==
The CBX daughterboard is not capable of phase-synchronous operation. The SBX, UBX, TwinRX daughterboards are recommended for phase-coherent applications.

==Schematics==
===CBX===
[http://files.ettus.com/schematics/cbx/CBX.pdf CBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-
|[http://www.avagotech.com/docs/AV02-2919EN VMMK-3603]
|Low Noise Amplifier
|U1, U5 (1)
|-

|[http://www.skyworksinc.com/uploads/documents/AS225_313LF_200148E.pdf AS225-313LF]
|SPDT Switch
|U3, U6 (1)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U7, U2 (1)
|-

|[http://www.avagotech.com/docs/AV02-1985EN MGA82563]
|Amplifier
|U4 (1)
|-

|[https://www.minicircuits.com/pdfs/GVA-84+.pdf GVA-84+]
|Amplifier
|U9 (1)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U8 (1)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380ACPZ]
|Quadrature Demodulator
|U11 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2YCPZ]
|Differential ADC Driver
|U10 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591ARTZ-REEL]
|Amplifiers
|U31 (2)
|-

|[https://www.fairchildsemi.com/datasheets/NC/NC7WZ04.pdf NC7WZ04P6X]
|Dual Inverter
|U26 (3); U15, U16 (4); U21 (5); U27 (6)
|-

|[https://datasheets.maximintegrated.com/en/ds/MAX2870.pdf MAX2870ETJ+]
|Fractional/Integer-N Synthesizer
|U23 (3); U24 (6)
|-

|[http://www.skyworksinc.com/uploads/documents/200027E.pdf SKY13267-321]
|Diversity Switch
|U12 (3); U25 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2000.pdf LFCN-2000+]
|Low Pass Filter
|FL13 (3); FL12 (6)
|-

|[http://www.ti.com/lit/ds/symlink/lp3878-adj.pdf LP3878MR-ADJ]
|Voltage Regulator
|U13, U14 (4); U19, U20 (5)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U17 (4); U22 (5)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U18 (5)
|-
|}

==Drawings==
* [[File:cu ettus-cca-cbx.pdf]]

==RF Connectors==
* The CBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===CBX-40/CBX-120===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==RF Performance Data==
* [http://files.ettus.com/performance_data/cbx/CBX-without-UHD-corrections.pdf CBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

E310/E312

2017-05-12T11:33:35Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The USRP E310 offers a portable stand-alone SDR platform designed for field deployment. The flexible 2x2 MIMO AD9361 transceiver from Analog Devices provides up to 56 MHz of instantaneous bandwidth and spans frequencies from 70 MHz – 6 GHz to cover multiple bands of interest.

== Key Features==
===E310===
{|
|style="vertical-align:top"|
*Xilinx Zynq 7020 SoC: 7 Series FPGA with ARM Cortex A9 667 MHz dual-core processor
*Analog Devices AD9361 RFIC direct-conversion transceiver
*Frequency range: 70 MHz - 6 GHz
*Up to 56 MHz of instantaneous bandwidth
*2x2 MIMO transceiver
*Up to 10 MS/s sample data transfer rate to ARM processor
*RX, TX filter banks
*Integrated GPS receiver
*9-axis inertial measurement unit
*RF Network on Chip (RFNoC™) FPGA development framework support
|[[File:Product e310.png|250px|center]]
|}

===E312===
{|
|style="vertical-align:top"|
*Battery Operated
*Xilinx Zynq 7020 SoC: 7 Series FPGA with ARM Cortex A9 866 MHz dual-core processor
*Analog Devices AD9361 RFIC direct-conversion transceiver
*Frequency range: 70 MHz - 6 GHz
*Up to 56 MHz of instantaneous bandwidth
*2x2 MIMO transceiver
*Up to 10 MS/s sample data transfer rate to ARM processor
*RX, TX filter banks
*Integrated GPS receiver
*9-axis inertial measurement unit
*RF Network on Chip (RFNoC™) FPGA development framework support
|[[File:Product e312.png|250px|center]]
|}

== Daughterboard Specifications==
===E310 MIMO XCVR board===
The USRP E310 MIMO XCVR daughterboard features an integrated MIMO capable RF frontend.

===Tuning===
The RF frontend has individually tunable receive and transmit chains. Both transmit and receive can be used in a MIMO configuration. For the MIMO case, both receive frontends share the RX LO, and both transmit frontends share the TX LO. Each LO is tunable between 50 MHz and 6 GHz.

===Gains===
All frontends have individual analog gain controls. The receive frontends have 76 dB of available gain; and the transmit frontends have 89.5 dB of available gain. Gain settings are application specific, but it is recommended that users consider using at least half of the available gain to get reasonable dynamic range.

===LO lock status===
The frontends provide a lo-locked sensor that can be queried through the UHD API.

<syntaxhighlight lang="c++">
// assumes 'usrp' is a valid uhd::usrp::multi_usrp::sptr instance
// get status for rx frontend
usrp->get_rx_sensor("lo-locked");
// get status for tx frontend
usrp->get_tx_sensor("lo-locked");
</syntaxhighlight>

===Filter and Antenna Switches===
The transmit and receive filter banks uses switches to select between the available filters. These paths are also dependent on the antenna switch settings. Incorrectly setting the switches generally results in attenuated input / output power. Receive filters are band pass (series high & low pass filters), transmit filters are low pass.

Source code related to controlling the filter band and antenna switches resides in <code>e300_impl.c</code>. Specifically, refer to methods <code>e300_impl::_update_bandsel</code>, <code>e300_impl::_update_atrs</code>, <code>e300_impl::_update_gpio</code>, and <code>e300_impl::_update_enables</code>. Generally, these methods set the switches depending on the state of transmit and receive streams.

The following sections provide switch setting tables for antenna and filter selection for frontends A & B receive and transmit paths. For futher details refer to the schematics.

===Side A Filter and Antenna Switches===
''Note: X = don't care, T = If full duplex, set bits according to transmit table, otherwise don't care. Filter range A – B will be selected if A <= freq < B.''

'''Receive'''

{| class="wikitable"
!RX Port
!RX Filter (MHz)
!VCTXRX2_V1,V2
!VCRX2_V1,V2
!RX2_BANDSEL[2:0]
!RX2B_BANDSEL[1:0]
!RX2C_BANDSEL[1:0]
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | < 450
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 101
| style="text-align: center" | XX
| style="text-align: center" | 01
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 450 – 700
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 011
| style="text-align: center" | XX
| style="text-align: center" | 11
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 700 – 1200
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 001
| style="text-align: center" | XX
| style="text-align: center" | 10
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 1200 – 1800
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 000
| style="text-align: center" | 01
| style="text-align: center" | XX
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 1800 – 2350
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 010
| style="text-align: center" | 11
| style="text-align: center" | XX
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 2350 – 2600
| style="text-align: center" | 01
| style="text-align: center" | 10
| style="text-align: center" | 100
| style="text-align: center" | 10
| style="text-align: center" | XX
|-

| style="text-align: center" | TRX-A
| style="text-align: center" | 2600 – 6000
| style="text-align: center" | 01
| style="text-align: center" | 01
| style="text-align: center" | XXX
| style="text-align: center" | XX
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 70 – 450
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 101
| style="text-align: center" | XX
| style="text-align: center" | 01
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 450 – 700
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 011
| style="text-align: center" | XX
| style="text-align: center" | 11
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 700 – 1200
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 001
| style="text-align: center" | XX
| style="text-align: center" | 10
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 1200 – 1800
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 000
| style="text-align: center" | 01
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 1800 – 2350
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 010
| style="text-align: center" | 11
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | 2350 – 2600
| style="text-align: center" | TT
| style="text-align: center" | 01
| style="text-align: center" | 100
| style="text-align: center" | 10
| style="text-align: center" | XX
|-

| style="text-align: center" | RX2-A
| style="text-align: center" | >= 2600
| style="text-align: center" | TT
| style="text-align: center" | 10
| style="text-align: center" | XXX
| style="text-align: center" | XX
| style="text-align: center" | XX
|-
|}

'''Transmit'''
{| class="wikitable"

! TX Port
! TX Filter (MHz)
! VCTXRX2_V1,V2
! TX_ENABLE2A,2B
! TX_BANDSEL[2:0]
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | < 117.7
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 111
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 117.7 – 178.2
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 110
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 178.2 – 284.3
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 101
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 284.3 – 453.7
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 100
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 453.7 – 723.8
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 011
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 723.8 – 1154.9
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 010
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 1154.9 – 1842.6
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 001
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | 1842.6 – 2940.0
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 000
|-

| style="text-align:center;" | TRX-A
| style="text-align:center;" | >= 2940.0
| style="text-align:center;" | 11
| style="text-align:center;" | 10
| style="text-align:center;" | XXX
|-

|}

''Note: Although the transmit filters are low pass, this table describes UHD's tuning range for selecting each filter path. The table also includes the required transmit enable state.''

===Side B Filter and Antenna Switches===
''Note: X = don't care, T = If full duplex, set bits according to transmit table, otherwise don't care. Filter range A – B will be selected if A <= freq < B.''

'''Receive'''
{| class="wikitable"
! RX Port
! RX Filter (MHz)
! VCTXRX1_V1,V2
! VCRX1_V1,V2
! RX1_BANDSEL[2:0]
! RX1B_BANDSEL[1:0]
! RX1C_BANDSEL[1:0]
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | < 450
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 100
| style="text-align:center;" | XX
| style="text-align:center;" | 10
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 450 – 700
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 010
| style="text-align:center;" | XX
| style="text-align:center;" | 11
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 700 – 1200
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 000
| style="text-align:center;" | XX
| style="text-align:center;" | 01
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1200 – 1800
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 001
| style="text-align:center;" | 10
| style="text-align:center;" | XX
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1800 – 2350
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 011
| style="text-align:center;" | 11
| style="text-align:center;" | XX
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 2350 – 2600
| style="text-align:center;" | 10
| style="text-align:center;" | 01
| style="text-align:center;" | 101
| style="text-align:center;" | 01
| style="text-align:center;" | XX
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 2600 – 6000
| style="text-align:center;" | 10
| style="text-align:center;" | 10
| style="text-align:center;" | XXX
| style="text-align:center;" | XX
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 70 – 450
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 100
| style="text-align:center;" | XX
| style="text-align:center;" | 10
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 450 – 700
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 010
| style="text-align:center;" | XX
| style="text-align:center;" | 11
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 700 – 1200
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 000
| style="text-align:center;" | XX
| style="text-align:center;" | 01
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 1200 – 1800
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 001
| style="text-align:center;" | 10
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 1800 – 2350
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 011
| style="text-align:center;" | 11
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | 2350 – 2600
| style="text-align:center;" | TT
| style="text-align:center;" | 10
| style="text-align:center;" | 101
| style="text-align:center;" | 01
| style="text-align:center;" | XX
|-

| style="text-align:center;" | RX2-B
| style="text-align:center;" | >= 2600
| style="text-align:center;" | TT
| style="text-align:center;" | 01
| style="text-align:center;" | XXX
| style="text-align:center;" | XX
| style="text-align:center;" | XX
|-

|}

'''Transmit'''
{| class="wikitable"

! TX Port
! TX Filter (MHz)
! VCTXRX1_V1,V2
! TX_ENABLE1A,1B
! TX1_BANDSEL[2:0]
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | < 117.7
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 111
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 117.7 – 178.2
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 110
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 178.2 – 284.3
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 101
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 284.3 – 453.7
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 100
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 453.7 – 723.8
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 011
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 723.8 – 1154.9
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 010
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1154.9 – 1842.6
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 001
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | 1842.6 – 2940.0
| style="text-align:center;" | 00
| style="text-align:center;" | 01
| style="text-align:center;" | 000
|-

| style="text-align:center;" | TRX-B
| style="text-align:center;" | >= 2940.0
| style="text-align:center;" | 11
| style="text-align:center;" | 10
| style="text-align:center;" | XXX
|-

|}

''Note: Although the transmit filters are low pass, the following table describes UHD's tuning range for selecting each filter path. The table also includes the required transmit enable states.''

==RF Specifications==
===RF Performance===
* SSB/LO Suppression -35/50 dBc
* Phase Noise 3.5 GHz 1.0 deg RMS
* Phase Noise 6 GHz 1.5 deg RMS
* Power Output >10dBm
* IIP3 (@ typ NF) -20dBm
* Typical Noise Figure <8dB

===Input/Output Impedance===
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===E310===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0
* Required version on the host computer must match what is running on the E310

===E312===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.5
* Required version on the host computer must match what is running on the E312

==Physical Specifications==

===Dimensions===
* 133 x 68 x 26.4 mm

==Environmental Specifications==
===Operating Temperature Range===
* E310 0-40 °C
* E312 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==Schematics==
===E310===
[http://files.ettus.com/schematics/e310/e310.pdf E310 Schematics]

[http://files.ettus.com/schematics/e310/e310_db.pdf E310 DB]

[[Media: E310_System_Diagram.png|E310 Architecture]]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-
! colspan="3" | Motherboard
|-
|[http://www.ti.com.cn/cn/lit/ds/symlink/txs02612.pdf TXS02612RTWR]
|SDIO PORT EXPANDER
|U23 (2)
|-
|[http://www.xilinx.com/support/documentation/data_sheets/ds187-XC7Z010-XC7Z020-Data-Sheet.pdf XC7Z020-1CLG484CES9919]
|FPGA
|U11 (2,3,4,8,11,13)
|-

|[http://www.xilinx.com/products/silicon-devices/soc/zynq-7000.html Xilinx Zynq Product Page ]
|FPGA
| -
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/00001678A.pdf USB3340-EZK-TR]
|ULPI Transceiver
|U33 (5)
|-
|[http://www.akm.com/akm/en/file/datasheet/AK4571VQ.pdf AK4571VQP]
|Audio CODEC
|U30 (6)
|-
|[http://www.ftdichip.com/Support/Documents/DataSheets/ICs/DS_FT230X.pdf FT230XQ-R]
|UART Interface
|U32 (6)
|-
|[http://www.marvell.com/transceivers/assets/Alaska_88E1512-001_product_brief.pdf 88E1512]
|Gigabit Ethernet Transceiver
|U13 (7)
|-
|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210N.pdf 24LC024/SN]
|EEPROM
|U5 (9)
|-
|[http://datasheets.maximintegrated.com/en/ds/DS1339-DS1339U.pdf DS1339,SM]
|Real-Time Clock
|U6 (9)
|-
|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADT7408.pdf ADT7408]
|Temperature Sensor
|U8 (9)
|-
|[https://www.invensense.com/wp-content/uploads/2015/02/MPU-9150-Datasheet.pdf MPU-9150]
|Motion Processing Unit
|U3 (9)
|-

|[http://www.invensense.com/products/motion-tracking/9-axis/mpu-9150/ InvenSense MPU-9150 Product Page]
| Motion Processing Unit
|U3 (9)
|-

|[https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP180-DS000-121.pdf BMP180]
|Digital pressure sensor
|U4 (9)
|-
|[http://www.ti.com/lit/ds/symlink/bq24192.pdf BQ24192]
|Adapter Charger
|U1 (10)
|-
|[http://www.ti.com/lit/ds/symlink/tps54478.pdf TPS54478]
|Step-Down Switcher
|U20 (10)
|-
|[https://datasheets.maximintegrated.com/en/ds/MAX6509-MAX6510.pdf MAX6510HAUT-T]
|Temperature Switches
|U35 (10)
|-
|[http://www.atmel.com/images/doc8008.pdf ATTINY88-MU]
|Microcontroller
|U18 (10)
|-
|[http://www.ti.com/lit/ds/symlink/tps61253.pdf TPS61253YFF]
|Step-Up Converter
|U19 (10)
|-

|[https://www.u-blox.com/sites/default/files/products/documents/AMY-6_ProductSummary_%28GPS.G6-HW-10039%29.pdf AMY-6M]
|GPS Module
|U12 (6)
|-

! colspan="3" | Daughterboard
|-
!Part Number
!Description
!Schematic ID (Page)
|-

|[http://www.analog.com/en/products/rf-microwave/integrated-transceivers-transmitters-receivers/wideband-transceivers-ic/ad9361.html#product-overview AD9361 Product Page]
|2 x 2 RF Agile Transceiver
| U8 (3)
|-

|[http://ww1.microchip.com/downloads/en/devicedoc/21203m.pdf 24AA256]
|EEPROM
|U15 (2)
|-

|[https://www.minicircuits.com/pdfs/TC1-1-43A+.pdf TC-1-43A+]
|RF Transformer
|T6 (3); T5 (3); T4 (3)
|-

|[https://www.minicircuits.com/pdfs/TC1-1-13M+.pdf TC1-1-13M+]
|RF Transformer
|T7 (3); T10 (3); T1 (3)
|-

|[http://www.ti.com/lit/ds/symlink/tps62140.pdf TPS62140]
|Step-Down Converter
|U19 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP1752_1753.pdf ADP1753ACPZ-R7]
|Linear Regulator
|U17 (4); U18 (4)
|-

|[http://www.rfmd.com/store/downloads/dl/file/id/28671/sga4563z_data_sheet.pdf SGA-4563Z]
|MMIC AMPLIFIER
|U12 (5); U4 (5)
|-

|[http://www.skyworksinc.com/uploads/documents/SKY13418_485LF_201712D.pdf SKY13418-485LF]
|Antenna Switch
|U13 (5); U3 (5); U16 (5); U2 (5); U10 (6); U5 (6)
|-

|[http://www.skyworksinc.com/uploads/documents/SKY13373_460LF_201264N.pdf SKY13373-460LF]
|SP3T Switch
|U11 (6); U9 (6); U6 (6); U7 (6); SW4 (7); SW1 (7)
|-

|[http://www.avagotech.com/docs/AV02-0966EN MGA-81563]
|Amplifier
|U14 (5); U1 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-5850+.pdf LFCN-5850+]
|Low Pass Filter
|FL32 (5); FL1 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2750.pdf LFCN-2750+]
|Low Pass Filter
|FL37 (5); FL4 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2250.pdf LFCN-2250+]
|Low Pass Filter
|FL23 (6); FL20 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1700.pdf LFCN-1700+]
|Low Pass Filter
|FL40 (5); FL2 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1575.pdf LFCN-1575+]
|Low Pass Filter
|FL25 (6); FL17 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1000.pdf LFCN-1000+]
|Low Pass Filter
|FL33 (5); FL9 (5); FL27 (6); FL15 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-575.pdf LFCN-575+]
|Low Pass Filter
|FL36 (5); FL5 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-530.pdf LFCN-530+]
|Low Pass Filter
|FL29 (6); FL13 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-400.pdf LFCN-400+]
|Low Pass Filter
|FL38 (5); FL3 (5); FL30 (6); FL11 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-225.pdf LFCN-225]
|Low Pass Filter
|FL39 (5); FL6 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-160+.pdf LFCN-160+]
|Low Pass Filter
|FL34 (5); FL8 (5)
|-

|[https://www.minicircuits.com/pdfs/LFCN-80.pdf LFCN-80+]
|Low Pass Filter
|FL35 (5); FL7 (5)
|-

|[https://www.minicircuits.com/pdfs/HFCN-1600.pdf HFCN-1600+]
|High Pass Filter
|FL22 (6); FL19 (6)
|-

|[https://www.minicircuits.com/pdfs/HFCN-1100+.pdf HFCN-1100+]
|High Pass Filter
|FL24 (6); FL16 (6)
|-

|[https://www.minicircuits.com/pdfs/HFCN-650.pdf HFCN-650+]
|High Pass Filter
|FL26 (6); FL14 (6)
|-

|[https://www.minicircuits.com/pdfs/HFCN-440+.pdf HFCN-440+]
|High Pass Filter
|FL28 (6); FL12 (6)
|-

|[https://www.minicircuits.com/pdfs/BFCN-2435+.pdf BFCN-2435+]
|Bandpass Filter
|FL21 (6); FL18 (6)
|-

|[https://www.fairchildsemi.com/datasheets/FD/FDG6301N.pdf FDG6301N]
|Dual N-Channel, Digital FET
|Q8 (7); Q5 (7)
|-

|[http://www.farnell.com/datasheets/461118.pdf HSMS-8202]
|Mixer Diodes
|CR1 (7); CR2 (7); CR3 (7); CR4 (7)
|-

|[http://www.ti.com.cn/cn/lit/ds/symlink/lp5900.pdf LP5900TL]
|Linear Regulator
|U25 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP150.pdf ADP150AUJZ-3.0]
|Linear Regulator
|U22 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD5662.pdf AD5662RBJ]
|16-Bit nanoDAC
|U21 (8)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t57.pdf SN74AUP1T57]
|Voltage Translator
|U27 (8); U28 (8); U29 (8)
|-

|}

Request a detailed whitepaper covering features and components from [mailto:info@ettus.com info@ettus.com]

==Mechanical Information==

===Weight===
* Partial Enclosure 225 g
* Full Enclosure 375 g

===Drawings===
====E310====
* [[File:E310_Dimensional_Sketches.pdf]]
* [[File:cu e310 motherboard cca.pdf]]
* [[File:cu E310 daughtercard cca.pdf]]
* [[File:cu usrp-e310.pdf]]
====E312====
* [[File:cu e312 motherboard cca.pdf]]
* [[File:cu e312 daughtercard cca.pdf]]
* [[File:cu ettus-e312.pdf]]

==FPGA==
* Utilization statistics are subject to change between UHD releases. This information is current as of UHD 3.9.4 and was taken directly from Xilinx Vivado 2014.4.

===E310/E312===
<pre>
1. Slice Logic
--------------

+----------------------------+-------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------------------+-------+-----------+-------+
| Slice LUTs | 36203 | 53200 | 68.05 |
| LUT as Logic | 28108 | 53200 | 52.83 |
| LUT as Memory | 8095 | 17400 | 46.52 |
| LUT as Distributed RAM | 870 | | |
| LUT as Shift Register | 7225 | | |
| Slice Registers | 36562 | 106400 | 34.36 |
| Register as Flip Flop | 36562 | 106400 | 34.36 |
| Register as Latch | 0 | 106400 | 0.00 |
| F7 Muxes | 376 | 26600 | 1.41 |
| F8 Muxes | 125 | 13300 | 0.93 |
+----------------------------+-------+-----------+-------+

3. Memory
---------

+-------------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+-------------------+------+-----------+-------+
| Block RAM Tile | 97 | 140 | 69.28 |
| RAMB36/FIFO* | 90 | 140 | 64.28 |
| RAMB36E1 only | 90 | | |
| RAMB18 | 14 | 280 | 5.00 |
| RAMB18E1 only | 14 | | |
+-------------------+------+-----------+-------+
* Note: Each Block RAM Tile only has one FIFO logic available and therefore can accommodate only one FIFO36E1 or one FIFO18E1. However, if a FIFO18E1 occupies a Block RAM Tile, that tile can still accommodate a RAMB18E1

4. DSP
------

+----------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------+------+-----------+-------+
| DSPs | 120 | 220 | 54.54 |
| DSP48E1 only | 120 | | |
+----------------+------+-----------+-------+

</pre>

==Interfaces and Connectivity==
*10/100/1000 BASE-T Ethernet
*Stereo audio out, mono mic in
*Integrated GPS receiver
*Host USB support
*9-axis IMU

===Front Panel===
{|
| style="width:50%" |
*'''RF A Group'''
**'''TX/RX LED:''' Indicates that data is streaming on the TX/RX channel on frontend side A
**'''RX2 LED:''' Indicates that data is streaming on the RX2 channel on frontend side A
*'''RF B Group'''
**'''TX/RX LED:''' Indicates that data is streaming on the TX/RX channel on frontend B
**'''RX2 LED:''' Indicates that data is streaming on the RX2 channel on frontend B
*'''PWR:''' Power switch with integrated status LED, for status description see below.
*'''SYNC:''' Input port for external PPS signal
*'''GPS:''' Connection for the GPS antenna
*'''AUDIO:''' Audio input / output

The status LED in the power switch indicates the power and charge status. It's behavior is firmware version dependent.

*'''Version 1''' (original E310)
**'''Off:''' Indicates device is off and not charging
**'''Solid Red:''' Indicates device is charging
**'''Solid Green:''' Indicates device is on
**'''Fast Blinking Red:''' Indicates an error code
***1 - Low voltage error
***2 - Regulator low voltage error
***3 - FPGA power error
***4 - DRAM power error
***5 - 1.8V rail power error
***6 - 3.3V rail power error
***7 - Daughterboard / TX power error
***9 - Temperature error

*'''Version 2''' (E312 and upgraded E310)
**'''Off:''' Indicates device is off and not charging
**'''Slow Blinking Green:''' Indicates device is off and charging
**'''Fast Blinking Green:''' Indicates device is on and charging
**'''Solid Green:''' Indicates device is on (and not charging, if E312)
**'''Solid Orange:''' Indicates device is on and discharging
**'''Fast Blinking Orange:''' Indicates device is on, discharging, and charge is below 10% charge
**'''Fast Blinking Red:''' Indicates an error code
***1 - Low voltage error
***2 - Regulator low voltage error
***3 - FPGA power error
***4 - DRAM power error
***5 - 1.8V rail power error
***6 - 3.3V rail power error
***7 - Daughterboard / TX power error
***8 - Charger error
***9 - Charger temperature error
***10 - Battery low error
***11 - Fuel Gauge temperature error
***12 - Global (case) temperature error

| style="vertical-align:top" | [[File:e3x0 fp overlay.png]]
|}

===Rear Panel===
{|
| style="width:50%" |
*'''PWR:''' Locking connector (Kycon KLDHCX-0202-A-LT) for the USRP-E Series power supply
*'''1G ETH:''' RJ45 port for Ethernet interfaces
*'''USB:''' USB 2.0 Port
*'''SERIAL:''' Micro USB connection for serial uart console

| style="vertical-align:top" | [[File:e3x0 rp overlay.png]]

|}

===GPIO===
{|

| style="width:60%" |
'''Pin Mapping'''
* Pin 1: +3.3V
* Pin 2: Reserved
* Pin 3: Data[5]
* Pin 4: Reserved
* Pin 5: Data[4]
* Pin 6: Data[0]
* Pin 7: Data[3]
* Pin 8: Data[1]
* Pin 9: 0V
* Pin 10: Data[2]
|[[File:e3x0 gpio conn.png]]
|}
* Please see the [http://files.ettus.com/manual/page_gpio_api.html E3x0/X3x0 GPIO API] for information on configuring and using the GPIO bus.

===Audio===
{|
| style="width:60%" |
* The E3x0 2.5 mm Audio Jack TRRS pins are assigned as follows: Tip=Mic, Ring1=Right, Ring2=Left, Sleeve=GND.
* The Left/Right audio outputs are compatible with typical low-impedance headphones (16 to 32 Ohms). The Microphone pin provides approximately 2 mA bias at 2.2 V when not suspended. A variety of pin configurations can be found on commonly available headsets, so an adapter may be required.

|[[File:TRRS.png]]

|}

==E312 Battery==
The USRP E312 is equipped with an integrated 3.7V, 3200mAh lithiumion battery cell. After unboxing the USRP E312 , plug in the power adapter to an AC power source and fully charge the battery. This process with take approximately 2 hours. Do not leave the USRP E312 unit plugged in for more than 24 hours.

The status LED in the power button indicates the power and charge status of the battery:

Off: Indicates device is off and not charging.
*Slow Blinking Green: Indicates device is off and charging.
*Fast Blinking Green: Indicates device is on and charging.
*Solid Green: Indicates device is on and not charging (Battery is finished charging).
*Solid Orange: Indicates device is on and discharging.
*Fast Blinking Orange: Indicates device is on, discharging, and charge is below 10% charge.
*Fast Blinking Red: Indicates an error code:

#Low Voltage Error
#Regulator Low Voltage Error
#FPGA Power Error
#DRAM Power Error
#1.8V Power Rail Error
#3.3V Power Rail Error
#Daughterboard / TX Power Error
#Charger Error
#Charger Temperature Error
#Battery Low Error
#Fuel Gauge Temperature Error
#Global (Enclosure) Temperature Error

The battery life of the USRP E312 in idle mode is approximately 5 1/2 hours. The battery will enable the USRP E312 to operate for approximately 2 hours 20 minutes, when transmitting and receiving on both channels (2x2 MIMO), with maximum gain settings, at 5 GHz center frequency, and 1 MS/s sample rate. When the power button status LED is in the “Fast Blinking Orange” mode, plug the USRP E312 into an AC power source as soon as possible to recharge the battery.

If the power button status LED indicates a “Low Voltage Error” (codes 1, 2, 3, 4, 5, 6, 7) or a “Battery Low Error” (code 10), plug the USRP E312 into an AC power source as soon as possible to recharge the battery.

When the power button status LED indicates at “Temperature Error” or “Charger Error” (codes 8, 9, 11, or 12), power off the USRP E312 unit and allow it to cool down to room temperature. Then, plug in the USRP E312 to and AC power source and fully charge the battery.

If error codes persist after cooling down and/or recharging the USRP E312, please contact [mailto:support@ettus.com support@ettus.com].

You can purchase a replacement battery for the E312 at [https://www.ettus.com/product/details/E312-battery https://www.ettus.com/product/details/E312-battery].

An Application Note covering the replacement of the E312 battery can be found at [[USRP E312 Battery Replacement Instructions]].

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

==Certificate of Volatility==
===E310===
* [[Media:volatility USRP E310 r1.pdf]]

===E312===
* [[Media:USRP E31x CoV.pdf]]

==SD Card Images==

* [http://files.ettus.com/e3xx_images/ http://files.ettus.com/e3xx_images/]

This folder linked above contains SD card images and the SDK (OE cross-compiler build environment) for the USRP E310 and E312. There is a manifest file that shows which packages, and which versions, are included in the OE build within each folder.

The "<code>alpha</code>", "<code>beta</code>", "<code>e3xx-release-001</code>", "<code>e310-release-002</code>", "<code>e3xx-release-3</code>" folders contain older versions which are currently obsolete. We do not suggest that customers use these files. These versions are no longer supported. They are provided here for archival purposes only.

The current version is Release 4, which located in the "<code>e3xx-release-4</code>" folder. We recommend the customers use this version. It is fine if you are already successfully using an older version, but at some point it is recommended that you upgrade to this current version so that you benefit from the latest bug fixes, new features, stability improvements, and other enhancements.

The Release 4 image includes UHD 3.9.2 and GNU Radio 3.7.9, and also includes the corresponding FPGA image file.

'''Note:''' An 8 GB SD card is required for the Release 4 image.

The SD card image contains both the FPGA image and the OS for the E310/E312. The FPGA images are located in the file system of the E310/E312 in the <code>/usr/local/share/uhd/images</code> folder.

There are two SD card image files for each version of the image, which include the text "<code>-dev</code>" and "<code>-demo</code>" in the filename. The "<code>-dev</code>" flavor lacks some graphical packages, such as X Windows and QT, which the "<code>-demo</code>" flavor includes. The two flavors are otherwise functionally equivalent, although the "<code>-demo</code>" flavor takes some additional space on the SD card and some additional memory to run.

The Release 4 image comes in two varieties. The variety that you will need depends on the product number of your E310 or E312, which is printed on the bottom of the device.

For the E310, the product number will be <code>156333X-01L</code>, where X is a letter from A to Z. For devices where X is A, B, C, D, the images under the "<code>ettus-e3xx-sg1</code>" folder should be used. For devices where X is E or later, the images under the "<code>ettus-e3xx-sg3</code>" folder should be used. You must use the appropriate image for your specific device. The incorrect image will not work, and will only boot as far as the U-Boot boot loader before stopping.

For the E312, the product number will be <code>140605X-01L</code>, where X is a letter from A to Z. The images under the "<code>ettus-e3xx-sg3</code>" folder should be used for all E312 devices.

You can burn the image to an SD card using either the "<code>dd</code>" or the "<code>bmaptool</code>" tool. Instructions on how to use these tools are at the links below.

* http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_upgrade_sd_card

* https://gnuradio.org/redmine/projects/gnuradio/wiki/Copy_an_image_file_to_the_SD_card

The SD image files have an *.xz extension, as they are compressed using the LZMA/LZMA2 compression algorithms. You can uncompress these files with tools such as 7-Zip and the XZ Utils. Please see the links below for further information.

'''7-Zip'''
* http://www.7-zip.org/
* https://en.wikipedia.org/wiki/7-Zip

'''XZ Utils'''
* http://tukaani.org/xz/
* https://en.wikipedia.org/wiki/XZ_Utils

The folder structure is listed below.
<pre>
.
|-- alpha
| |-- dizzy-test
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| | |-- sdimage-gnuradio-demo.direct.xz
| | `-- sdimage-gnuradio-dev.direct.xz
| |-- fido-rfnoc-test
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| | |-- sdimage-gnuradio-demo.direct.xz
| | |-- sdimage-gnuradio-demo.direct.xz.md5
| | |-- sdimage-gnuradio-dev.direct.xz
| | `-- sdimage-gnuradio-dev.direct.xz.md5
| |-- fido-test
| | |-- ettus-e3xx-sg1
| | | |-- sdimage-gnuradio-demo.direct.xz
| | | |-- sdimage-gnuradio-demo.direct.xz.md5
| | | |-- sdimage-gnuradio-dev.direct.xz
| | | `-- sdimage-gnuradio-dev.direct.xz.md5
| | |-- ettus-e3xx-sg3
| | | |-- sdimage-gnuradio-demo.direct.xz
| | | |-- sdimage-gnuradio-demo.direct.xz.md5
| | | |-- sdimage-gnuradio-dev.direct.xz
| | | `-- sdimage-gnuradio-dev.direct.xz.md5
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | `-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| `-- fosphor-testing
| |-- fosphor.direct.xz
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.host.manifest
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.target.manifest
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5
|-- beta
| |-- dizzy-test
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| | |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| | |-- sdimage-gnuradio-demo.direct.xz
| | `-- sdimage-gnuradio-dev.direct.xz
| `-- dizzy-test-wifi
| `-- sdimage-gnuradio-dev.direct.xz
|-- e310-release-002
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5sum
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5sum
|-- e3xx-release-001
| |-- e300-gnuradio-dev-image-release1.bz
| `-- nodistro-eglibc-x86_64-gnuradio-dev-image-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
|-- e3xx-release-3
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
| |-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
| |-- sdimage-gnuradio-demo.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz
`-- e3xx-release-4
|-- ettus-e3xx-sg1
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5
|-- ettus-e3xx-sg3
| |-- sdimage-gnuradio-demo.direct.xz
| |-- sdimage-gnuradio-demo.direct.xz.md5
| |-- sdimage-gnuradio-dev.direct.xz
| `-- sdimage-gnuradio-dev.direct.xz.md5
|-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.manifest
`-- oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh
</pre>

==Additional Resources==
* [http://www51.honeywell.com/aero/common/documents/myaerospacecatalog-documents/Defense_Brochures-documents/Magnetic__Literature_Application_notes-documents/AN203_Compass_Heading_Using_Magnetometers.pdf COMPASS HEADING USING MAGNETOMETERS]

==Downloads==

[http://files.ettus.com/e3xx_images/ FPGA Images]

[http://files.ettus.com/e3xx_images/README FPGA Images Read Me]

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

E310/E312

2017-05-12T11:33:17Z

NicolasCuervo: /* RF Specifications */

LFTX/LFRX

2017-05-12T11:32:53Z

NicolasCuervo: /* Daughterboard Specifications */

== Device Overview ==
The LFTX daughterboard utilizes two high-speed operational amplifiers to allow transmission from 0-30 MHz. The LFTX is ideal for applications in the HF band, or for applications using an external front end to up-convert and amplify the intermediate signal. The outputs of the LFTX can be processed independently, or as a single I/Q pair. Example applications include HF communications, radios with external front ends and direct signal generation below 30 MHz.

== Key Features==
{|
|style="vertical-align:top"|
* DC-30Mhz coverage
|[[File:Product basic lfrx.jpg|250px|center]]
|[[File:Product basic lftx.jpg|250px|center]]
|}

==Daughterboard Specifications==
===Frontends===
''' LFRX'''

The LFRX has 4 frontends:

* '''Frontend A''': real signal on antenna RXA
* '''Frontend B''': real signal on antenna RXB
* '''Frontend AB''': quadrature frontend using both antennas (IQ)
* '''Frontend BA''': quadrature frontend using both antennas (QI)

'''LFTX'''

The LFTX has 4 frontends:

* '''Frontend A''': real signal on antenna TXA
* '''Frontend B''': real signal on antenna TXB
* '''Frontend AB''': quadrature frontend using both antennas (IQ)
* '''Frontend BA''': quadrature frontend using both antennas (QI)

===Gains===
'''LFRX'''
* The LFRX has no tunable elements or programmable gains. Through the magic of aliasing, you can down-convert signals greater than the Nyquist rate of the ADC.

'''LFTX'''
* The LFTX has no tunable elements or programmable gains. Through the magic of aliasing, you can up-convert signals greater than the Nyquist rate of the DAC.

===Bandwidths===
'''LFRX'''
* '''For Real-Mode (A or B frontend)''': 33 MHz
* '''For Complex (AB or BA frontend)''': 66 MHz

'''LFTX'''
* '''For Real-Mode (A or B frontend)''': 33 MHz
* '''For Complex (AB or BA frontend)''': 66 MHz

===Input/Output Impedance===
All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===LFRX===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

===LFTX===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===LFRX===
* N or X Series

===LFTX===
* N or X Series

==Schematics==
===LFRX===
[http://files.ettus.com/schematics/lfrx/lfrx.pdf LFRX Schematics]

===LFTX===
[http://files.ettus.com/schematics/lftx/lftx.pdf LFTX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-
|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8138.pdf AD813x]
|Differential ADC Driver
|U2, U3 (1)
|-
|[http://cds.linear.com/docs/en/datasheet/3462af.pdf LT3462]
|DC/DC Converter
|U3 (1)
|-
|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210N.pdf 24LC025B]
|EEPROM
|U1 (1)
|-
|}

==RF Connectors==
* The LFTX / LFRX daughterboard features female SMA connectors for both the TX and RX connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

SBX

2017-05-12T11:32:28Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The SBX is a wide bandwidth transceiver that provides up to 100 mW of output power, and a typical noise figure of 5 dB. The local oscillators for the receive and transmit chains operate independently, which allows dual-band operation. The SBX is MIMO capable, and provides 40 MHz or 120 MHz of bandwidth. The SBX is ideal for applications requiring access to a variety of bands in the 400 MHz-4400 MHz range. Example application areas include WiFi, WiMax, S-band transceivers and 2.4 GHz ISM band transceivers.

The SBX is capable of phase coherent operation, and therefore is suitable for MIMO and Phased Array applications.

==Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 400MHz - 4.4GHz
* Versions: 40MHz / 120MHz
* Power Output: 100mW
|[[File:Product sbx 40.jpg|250px|center]]
|[[File:Product sbx 120.jpg|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using an SBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* SBX: 40 MHz, RX & TX
* SBX-120: 120 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* All LEDs flash when daughterboard control is initialized
* '''TX LD''': Transmit Synthesizer Lock Detect
* '''TX/RX''': Receiver on TX/RX antenna port (No TX)
* '''RX LD''': Receive Synthesizer Lock Detect
* '''RX1/RX2''': Receiver on RX2 antenna port

==RF Specifications==
'''Freq Range'''
* 400MHz - 4.4GHz

'''Noise Figure'''
* 4 - 5 dB @ (400MHz ~ 1.5GHz)
* 5 - 7 dB @ (1.5GHz ~ 3GHz)
* 7 - 12dB @ (3GHz ~ 4.4GHz)

'''RX IIP3 (Max)'''
* 16 ~ 22 dBm

'''RX IQ Imbalance'''
* -20 dBc @ (400MHz ~ 600MHz)
* -30dBc @ (600MHz ~ 4.4GHz)

'''TX Power (Max)'''
* 20 dBm @ (400MHz ~ 3.5GHz)
* 18 - 20dBm @ (3.5GHz ~ 4.4GHz)

'''TX OIP3'''
* 26 - 30dBm @ (400MHz ~ 1.5GHz)
* 30 dBm @ (1.5GHz ~ 4.4GHz)

'''TX IQ Imbalance'''
* -20 dBc @ (400MHz ~ 600MHz)
* -30dBc @ (600MHz ~ 4.4GHz)

'''Input/Output Impedance'''
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===SBX===
* Current Hardware Revision: 5.1
* Minimum version of UHD required: 3.8.0

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===SBX-40===
* N or X Series

===SBX-120===
* X Series only

==Phase Synchronization==
The SBX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. The UBX and TwinRX daughterboards are also recommended for phase-coherent applications.

==Schematics==
===SBX===
[http://files.ettus.com/schematics/sbx/SBX.pdf SBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[http://www.avagotech.com/docs/AV02-1985EN MGA82563]
|Amplifier
|U1, U5, U4 (1)
|-

|[http://www.skyworksinc.com/uploads/documents/AS225_313LF_200148E.pdf AS225-313LF]
|SPDT Switch
|U3, U6 (1)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U2, U7 (1)
|-

|[http://www.minicircuits.com/pdfs/LFCN-5850+.pdf LFCN-5850+]
|Low Pass Filter
|FL1 (1)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U8 (1)
|-

|[https://www.minicircuits.com/pdfs/GVA-84+.pdf GVA-84+]
|Amplifier
|U9 (1)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380ACPZ]
|Quadrature Demodulator
|U11 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2YCPZ]
|Differential ADC Driver
|U10 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591ARTZ-REEL]
|Amplifiers
|U31 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADF4350.pdf ADF4350BCPZ]
|Synthesizer with Integrated VCO
|U23 (3); U24 (6)
|-

|[http://www.skyworksinc.com/uploads/documents/200027E.pdf SKY13267]
|Diversity Switch
|U12 (3); U25 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1200.pdf LFCN-1200+]
|Low Pass Filter
|FL13 (3); FL12 (6)
|-

|[http://www.minicircuits.com/pdfs/TC1-1-43A+.pdf TC1-1-43A+]
|RF Transformer
|T3 (2); T2, T5 (3); T4, T6 (6)
|-

|[http://www.ti.com/lit/ds/symlink/lp3878-adj.pdf LP3878MR-ADJ]
|Voltage Regulator
|U13, U14 (4); U19, U20 (5)
|-

|[https://www.fairchildsemi.com/datasheets/NC/NC7WZ04.pdf NC7WZ04P6X]
|Dual Inverter
|U15, U16 (4); U21 (5); U27 (6); U26 (3)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U17 (4); U22 (5)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375]
|Quadrature Modulator
|U18 (5)
|-

|}

==Drawings==
* [[File:cu ettus-cca-sbx.pdf]]

==RF Connectors==
* The SBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===SBX-40/SBX-120===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==RF Performance Data==
* [http://files.ettus.com/performance_data/sbx/SBX-without-UHD-corrections.pdf SBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

SBX

2017-05-12T11:32:15Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The SBX is a wide bandwidth transceiver that provides up to 100 mW of output power, and a typical noise figure of 5 dB. The local oscillators for the receive and transmit chains operate independently, which allows dual-band operation. The SBX is MIMO capable, and provides 40 MHz or 120 MHz of bandwidth. The SBX is ideal for applications requiring access to a variety of bands in the 400 MHz-4400 MHz range. Example application areas include WiFi, WiMax, S-band transceivers and 2.4 GHz ISM band transceivers.

The SBX is capable of phase coherent operation, and therefore is suitable for MIMO and Phased Array applications.

==Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 400MHz - 4.4GHz
* Versions: 40MHz / 120MHz
* Power Output: 100mW
|[[File:Product sbx 40.jpg|250px|center]]
|[[File:Product sbx 120.jpg|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using an SBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* SBX: 40 MHz, RX & TX
* SBX-120: 120 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* All LEDs flash when daughterboard control is initialized
* '''TX LD''': Transmit Synthesizer Lock Detect
* '''TX/RX''': Receiver on TX/RX antenna port (No TX)
* '''RX LD''': Receive Synthesizer Lock Detect
* '''RX1/RX2''': Receiver on RX2 antenna port

==RF Specifications==
'''Freq Range'''
* 400MHz - 4.4GHz

'''Noise Figure'''
* 4 - 5 dB @ (400MHz ~ 1.5GHz)
* 5 - 7 dB @ (1.5GHz ~ 3GHz)
* 7 - 12dB @ (3GHz ~ 4.4GHz)

'''RX IIP3 (Max)'''
* 16 ~ 22 dBm

'''RX IQ Imbalance'''
* -20 dBc @ (400MHz ~ 600MHz)
* -30dBc @ (600MHz ~ 4.4GHz)

'''TX Power (Max)'''
* 20 dBm @ (400MHz ~ 3.5GHz)
* 18 - 20dBm @ (3.5GHz ~ 4.4GHz)

'''TX OIP3'''
* 26 - 30dBm @ (400MHz ~ 1.5GHz)
* 30 dBm @ (1.5GHz ~ 4.4GHz)

'''TX IQ Imbalance'''
* -20 dBc @ (400MHz ~ 600MHz)
* -30dBc @ (600MHz ~ 4.4GHz)

'''Input/Output Impedance'''
All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===SBX===
* Current Hardware Revision: 5.1
* Minimum version of UHD required: 3.8.0

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===SBX-40===
* N or X Series

===SBX-120===
* X Series only

==Phase Synchronization==
The SBX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. The UBX and TwinRX daughterboards are also recommended for phase-coherent applications.

==Schematics==
===SBX===
[http://files.ettus.com/schematics/sbx/SBX.pdf SBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[http://www.avagotech.com/docs/AV02-1985EN MGA82563]
|Amplifier
|U1, U5, U4 (1)
|-

|[http://www.skyworksinc.com/uploads/documents/AS225_313LF_200148E.pdf AS225-313LF]
|SPDT Switch
|U3, U6 (1)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U2, U7 (1)
|-

|[http://www.minicircuits.com/pdfs/LFCN-5850+.pdf LFCN-5850+]
|Low Pass Filter
|FL1 (1)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U8 (1)
|-

|[https://www.minicircuits.com/pdfs/GVA-84+.pdf GVA-84+]
|Amplifier
|U9 (1)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380ACPZ]
|Quadrature Demodulator
|U11 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2YCPZ]
|Differential ADC Driver
|U10 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591ARTZ-REEL]
|Amplifiers
|U31 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADF4350.pdf ADF4350BCPZ]
|Synthesizer with Integrated VCO
|U23 (3); U24 (6)
|-

|[http://www.skyworksinc.com/uploads/documents/200027E.pdf SKY13267]
|Diversity Switch
|U12 (3); U25 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1200.pdf LFCN-1200+]
|Low Pass Filter
|FL13 (3); FL12 (6)
|-

|[http://www.minicircuits.com/pdfs/TC1-1-43A+.pdf TC1-1-43A+]
|RF Transformer
|T3 (2); T2, T5 (3); T4, T6 (6)
|-

|[http://www.ti.com/lit/ds/symlink/lp3878-adj.pdf LP3878MR-ADJ]
|Voltage Regulator
|U13, U14 (4); U19, U20 (5)
|-

|[https://www.fairchildsemi.com/datasheets/NC/NC7WZ04.pdf NC7WZ04P6X]
|Dual Inverter
|U15, U16 (4); U21 (5); U27 (6); U26 (3)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U17 (4); U22 (5)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375]
|Quadrature Modulator
|U18 (5)
|-

|}

==Drawings==
* [[File:cu ettus-cca-sbx.pdf]]

==RF Connectors==
* The SBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===SBX-40/SBX-120===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==RF Performance Data==
* [http://files.ettus.com/performance_data/sbx/SBX-without-UHD-corrections.pdf SBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

BasicTX/BasicRX

2017-05-12T11:31:47Z

NicolasCuervo: /* Daughterboard Specifications */

== Device Overview ==
The BasicRX/BasicTX daughterboards are low-cost daughterboards that provides direct access to the ADC inputs. The boards can accept real-mode signals from 1 to 250 MHz. The BasicRX/BasicTX is ideal for applications using an external front end providing relatively clean signals within operable bandwidth. Wideband transformers couple each RF input to a single channel of the USRP device's ADC. The signals sampled by the ADC are manipulated in the FPGA, and can be processed as two real-mode signals, or a single I-Q pair.

== Key Features==
{|
|style="vertical-align:top"|
* 1-250 MHz coverage
* Real or Complex sampling
|[[File:Product basic rx.jpg|250px|center]]
|[[File:Product basic tx.jpg|250px|center]]
|}

==Daughterboard Specifications==
===Frontends===
''' BasicRX'''

The BasicRX has 4 frontends:

* '''Frontend A''': real signal on antenna RXA
* '''Frontend B''': real signal on antenna RXB
* '''Frontend AB''': quadrature frontend using both antennas (IQ)
* '''Frontend BA''': quadrature frontend using both antennas (QI)

'''BasicTX'''

The BasicTX has 4 frontends:

* '''Frontend A''': real signal on antenna TXA
* '''Frontend B''': real signal on antenna TXB
* '''Frontend AB''': quadrature frontend using both antennas (IQ)
* '''Frontend BA''': quadrature frontend using both antennas (QI)

===Gains===
'''BasicRX'''
* The BasicRX has no tunable elements or programmable gains. Through the magic of aliasing, you can down-convert signals greater than the Nyquist rate of the ADC.

'''BasicTX'''
* The BasicTX has no tunable elements or programmable gains. Through the magic of aliasing, you can up-convert signals greater than the Nyquist rate of the DAC.

===Bandwidths===
'''BasicRX'''
* '''For Real-Mode (A or B frontend)''': 250 MHz
* '''For Complex (AB or BA frontend)''': 500 MHz

'''BasicTX'''
* '''For Real-Mode (A or B frontend)''': 250 MHz
* '''For Complex (AB or BA frontend)''': 500 MHz

===Input/Output Impedance===
All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===BasicRX===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

===BasicTX===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===BasicRX===
* N or X Series

===BasicTX===
* N or X Series

==Schematics==
===Basic RX===
[http://files.ettus.com/schematics/basic_dbs/BasicRX.pdf Basic RX Schematics]

===Basic TX===
[http://files.ettus.com/schematics/basic_dbs/BasicTX.pdf Basic TX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210N.pdf 24LC025B]
|EEPROM
|U1 (1); U52 (1)
|-

|[https://www.minicircuits.com/pdfs/ADT1-1WT.pdf ADT1−1WT]
|RF Transformer
|T1 (1); T2 (1); T50 (1); T51 (1)

|}

==Mechanical Information==
===Drawings===
* BasicRX - [[File:cu ettus-cca-basic-rx.pdf]]

==RF Connectors==
* The BasicTX/RX daughterboard features female SMA connectors for both the RX and TX connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

WBX

2017-05-12T11:31:17Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The WBX is a wide bandwidth transceiver that provides up to 100 mW of output power and a noise figure of 5 dB. The LO's for the receive and transmit chains operate independently.

The WBX provides phase coherent operation, although with a 180-degree ambiguity, which must be calibrated out in the application. For phase-coherent applications, Ettus Research recommends the SBX with the N200/N210 or the SBX or UBX with the X300/X310.

== Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 50MHz - 2.2GHz
* Versions: 40MHz / 120MHz
* Power Output: 100mW
* Noise Figure: 5dB
|[[File:Product wbx 40.jpg|250px|center]]
|[[File:Product wbx 120.jpg|250px|center]]
|}
==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using a WBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-25dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* WBX: 40 MHz, RX & TX
* WBX-120: 120 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

==RF Specifications==
'''Freq Range'''
* 50MHz - 2.2GHz

'''Noise Figure'''
* 2 - 4 dB @ (50MHz ~ 1.2GHz)
* 4 - 8 dB @ (1.2GHz ~ 2.2GHz)

'''RX IIP3 (Max)'''
* 10 - 18 dBm

'''RX IQ Imbalance'''
* -30 dBc

'''TX Power (Max)'''
* 18 - 20 dBm @ (50MHz ~ 1.4 GHz)
* 12 - 18dBm @ (1.4GHz ~ 2.2 GHz)

'''TX OIP3'''
* 30 - 32 dBm @ (50MHz ~ 800MHz)
* 25 - 30 dBm @ (800MHz ~ 2.2GHz)

'''TX IQ Imbalance'''
* -30 dBc @ (50MHz ~ 1.9GHz)
*- 24 dBc @ (1.9GHz ~ 2.2GHz)

'''Input/Output Impedance'''
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===WBX-40===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

===WBX-120===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.0

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===WBX-40===
* N or X Series

===WBX-120===
* X Series only

==Phase Synchronization==
The WBX daughterboard is capable of phase-synchronous operation, but with a with a 180-degree ambiguity, which must be calibrated out in the user application. The SBX, UBX, TwinRX daughterboards are recommended for phase-coherent applications.

==Schematics==
===WBX===
[http://files.ettus.com/schematics/wbx/WBX.pdf WBX Schematics]

[http://files.ettus.com/schematics/wbx/wbx_fe.pdf WBX FE Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4937-1_4937-2.pdf ADA4937]
|Ultralow Distortion Differential ADC Driver
|U304 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP3336.pdf ADP3336]
|High Accuracy Ultralow IQ, 500 mA anyCAP® Adjustable Low Dropout Regulator
|U306, U308 (2); U503, U505 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5387.pdf ADL5387]
|50 MHz to 2 GHz Quadrature Demodulator
|U307 (2)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5385.pdf ADL5385]
|50 MHz to 2200 MHz Quadrature Modulator
|U501 (4,5)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADF4350.pdf ADF4350] / [http://www.analog.com/media/en/technical-documentation/data-sheets/ADF4351.pdf ADF4351]
|Wideband Synthesizer with Integrated VCO
|U201 (3); U401 (5)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC472LP4.pdf HMC472LP4]
|Attenuator
|U302 (2); U504 (4,5)
|-

|[http://www.avagotech.com/docs/AV02-1985EN MGA82563]
|Amplifier
|U313 (2)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U202 (3); U403 (5)
|-

|[https://www.minicircuits.com/pdfs/GVA-84+.pdf GVA−84+]
|Amplifier
|U502 (4)
|-
|}

==Mechanical Information==
===Drawings===
* [[Media:cu ettus-wbx-cca.pdf]]

==RF Connectors==
* The WBX daughterboard features female MCX connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===WBX-40/WBX-120===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==RF Performance Data==
* [http://files.ettus.com/performance_data/wbx/WBX-without-UHD-corrections.pdf WBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

UBX

2017-05-12T11:29:58Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The UBX daughterboard is a full-duplex wideband transceiver that covers frequencies from 10 MHz to 6 GHz. Coherent and phase-aligned operation across multiple UBX daughterboards on USRP X Series motherboards enables users to explore MIMO and direction finding applications. The UBX daughterboard works interchangeably with other USRP daughterboards and is supported by the USRP Hardware Driver™ (UHD) software API for seamless integration into existing applications.

The UBX is capable of phase coherent operation, and therefore is suitable for MIMO and Phased Array applications, on the X Series. Additionally this capability is only available on the X Series devices.

== Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 10 MHz - 6 GHz
* Versions: 40MHz / 160MHz
*RF shielding
*Full duplex operation with independent TX and RX frequencies
*Synthesizer synchronization for applications requiring coherent or phase-aligned operation, supported on USRP X Series motherboards only
|[[File:Product ubx 40.png|250px|center]]
|[[File:Product ubx 160.png|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using a UBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* UBX: 40 MHz, RX & TX
* UBX-160: 160 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* '''LOCK''': Synthesizer Lock Detect
* '''TX/RX TXD''': Transmitting on TX/RX antenna port
* '''TX/RX RXD''': Receiving on TX/RX antenna port
* '''RX2 RXD''': Receiving on RX2 antenna port

==RF Specifications==
'''Freq Range'''
* 10MHz - 6GHz

'''Noise Figure'''
* 10 MHz - 500 MHz: 3 - 4 dB
* 500 MHz - 1.5 GHz: 2 - 3 dB
* 1.5GHz - 6GHz: 4 - 10 dB

'''RX IIP3 (Max)'''
* 10 MHz - 6 GHz: 8 - 9 dBm

'''RX IQ Imbalance'''
* 10 MHz - 6 GHz: < -30dBc

'''TX Power (Max)'''
* 10 MHz - 3 GHz: 20 dBm
* 3 - 6 GHz: 8 - 20 dBm

'''TX OIP3'''
* 10 - 500 MHz: 41 dBm
* 0.5 - 3 GHz: 36 dBm
* 3 - 6 GHz: 26 dBm - 36 dBm

'''TX IQ Imbalance'''
* 10 MHz - 6 GHz: < -30 dBc

Note: The UBX 160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

'''Input/Output Impedance'''
* All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===UBX-40===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.2

===UBX-160===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.2

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===UBX-40===
* N or X Series

===UBX-160===
* X Series only

==Phase Synchronization==
The UBX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. The SBX and TwinRX daughterboards are also recommended for phase-coherent applications.

==Schematics==
===UBX===
[http://files.ettus.com/schematics/ubx/ubx.pdf UBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[https://datasheets.maximintegrated.com/en/ds/MAX2871.pdf MAX2871]
|Fractional/Integer-N Synthesizer/VCO
|U3 (3); U9 (5); U19 (7); U23 (9)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://www.minicircuits.com/pdfs/LFCN-2250.pdf LFCN-2250+]
|Low Pass Filter
|F1 (3); F24 (7); F34, F35 (10)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-490.pdf LFCN-490+]
|Low Pass Filter
|F12 (5); F15 (6); F26 (7); F31 (9); F33, F36 (10)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U16 (6)
|-

|[http://www.rfmd.com/store/downloads/dl/file/id/29224/nbb_400_data_sheet.pdf NBB-400]
|Amplifier
|U13 (6); U30 (11)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U31 (11)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.avagotech.com/docs/AV02-1237EN MGA-62563]
|Low Noise Amplifier
|U36 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1700.pdf LFCN-1700+]
|Low Pass Filter
|F41 (11)
|-

|[http://www.avagotech.com/docs/AV02-2919EN VMMK-3603]
|Low Noise Amplifier
|U34 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (6)
|-

|[http://www.triquint.com/products/d/doc-a-00000518 855916]
|SAW Filter
|F16 (6)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6); U28 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (10)
|-

|[http://www.minicircuits.com/pdfs/TCM1-63AX+.pdf TCM1-63AX+]
|RF Transformer
|T1 (3); T2, T3 (4); T7 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591]
|Operational Amplifiers
|U7 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q1 (6)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/hmc624a.pdf HMC624ALP4E]
|ATTENUATOR
|U16 (6); U29 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-800.pdf LFCN-800+]
|Low Pass Filter
|F2 (3); F25 (7)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-3.3]
|CMOS LDO
|U4, U5 (3); U10, U11 (5); U20, U21 (7); U24, U25 (9); U48 (13)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U28 (10)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U38, U39 (12)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-5.0]
|CMOS LDO
|U41, U42, U43, U44, U45, U46, U47 (13)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q2, Q3, Q4, Q5 (13)
|-
|}

==Mechanical Information==
===Drawings===
* [[Media:cu ettus UBX cca.pdf| PDF Format]]

==RF Connectors==
* The UBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===UBX-40/UBX-160===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==Important Notes==
*A larger 24W (6V, 4A) power supply is required when using a UBX-40 daughterboard and integrated GPS Disciplined Oscillator accessory together in a USRP2, USRP N200, or USRP N210 device.
*The UBX-160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

==RF Performance Data==
* [http://files.ettus.com/performance_data/ubx/UBX-without-UHD-corrections.pdf UBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

UBX

2017-05-12T11:29:33Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The UBX daughterboard is a full-duplex wideband transceiver that covers frequencies from 10 MHz to 6 GHz. Coherent and phase-aligned operation across multiple UBX daughterboards on USRP X Series motherboards enables users to explore MIMO and direction finding applications. The UBX daughterboard works interchangeably with other USRP daughterboards and is supported by the USRP Hardware Driver™ (UHD) software API for seamless integration into existing applications.

The UBX is capable of phase coherent operation, and therefore is suitable for MIMO and Phased Array applications, on the X Series. Additionally this capability is only available on the X Series devices.

== Key Features==
{|
|style="vertical-align:top"|
* Frequency Range: 10 MHz - 6 GHz
* Versions: 40MHz / 160MHz
*RF shielding
*Full duplex operation with independent TX and RX frequencies
*Synthesizer synchronization for applications requiring coherent or phase-aligned operation, supported on USRP X Series motherboards only
|[[File:Product ubx 40.png|250px|center]]
|[[File:Product ubx 160.png|250px|center]]
|}

==Daughterboard Specifications==
===Features===
* 2 quadrature frontends (1 transmit, 1 receive)
** Defaults to direct conversion
** Can be used in low IF mode through lo_offset with uhd::tune_request_t
* Independent receive and transmit LO's and synthesizers
** Allows for full-duplex operation on different transmit and receive frequencies
** Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t

===Antennas===
Transmit: '''TX/RX'''

Receive: '''TX/RX''' or '''RX2'''
* '''Frontend 0:''' Complex baseband signal for selected antenna
* '''Note:''' The user may set the receive antenna to be TX/RX or RX2. However, when using a UBX board in full-duplex mode, the receive antenna will always be set to RX2, regardless of the settings.

===Gains===
* Transmit Gains: '''PGA0''', Range: 0-31.5dB
* Receive Gains: '''PGA0''', Range: 0-31.5dB

===Bandwidths===
* UBX: 40 MHz, RX & TX
* UBX-160: 160 MHz, RX & TX

===Sensors===
* '''lo_locked:''' boolean for LO lock state

===LEDs===
* '''LOCK''': Synthesizer Lock Detect
* '''TX/RX TXD''': Transmitting on TX/RX antenna port
* '''TX/RX RXD''': Receiving on TX/RX antenna port
* '''RX2 RXD''': Receiving on RX2 antenna port

==RF Specifications==
'''Freq Range'''
* 10MHz - 6GHz

'''Noise Figure'''
* 10 MHz - 500 MHz: 3 - 4 dB
* 500 MHz - 1.5 GHz: 2 - 3 dB
* 1.5GHz - 6GHz: 4 - 10 dB

'''RX IIP3 (Max)'''
* 10 MHz - 6 GHz: 8 - 9 dBm

'''RX IQ Imbalance'''
* 10 MHz - 6 GHz: < -30dBc

'''TX Power (Max)'''
* 10 MHz - 3 GHz: 20 dBm
* 3 - 6 GHz: 8 - 20 dBm

'''TX OIP3'''
* 10 - 500 MHz: 41 dBm
* 0.5 - 3 GHz: 36 dBm
* 3 - 6 GHz: 26 dBm - 36 dBm

'''TX IQ Imbalance'''
* 10 MHz - 6 GHz: < -30 dBc

Note: The UBX 160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

'''Input/Output Impedance'''
All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

===UBX-40===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.2

===UBX-160===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.8.2

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==USRP Compatibility==
===UBX-40===
* N or X Series

===UBX-160===
* X Series only

==Phase Synchronization==
The UBX daughterboard is capable of phase-synchronous operation, and is recommended for phase-coherent applications. The SBX and TwinRX daughterboards are also recommended for phase-coherent applications.

==Schematics==
===UBX===
[http://files.ettus.com/schematics/ubx/ubx.pdf UBX Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-

|[https://datasheets.maximintegrated.com/en/ds/MAX2871.pdf MAX2871]
|Fractional/Integer-N Synthesizer/VCO
|U3 (3); U9 (5); U19 (7); U23 (9)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://www.minicircuits.com/pdfs/LFCN-2250.pdf LFCN-2250+]
|Low Pass Filter
|F1 (3); F24 (7); F34, F35 (10)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6)
|-

|[https://www.minicircuits.com/pdfs/LFCN-490.pdf LFCN-490+]
|Low Pass Filter
|F12 (5); F15 (6); F26 (7); F31 (9); F33, F36 (10)
|-

|[http://media.digikey.com/pdf/Data%20Sheets/Analog%20Devices%20PDFs/HMC624LP4E.pdf HMC624LP4E]
|ATTENUATOR
|U16 (6)
|-

|[http://www.rfmd.com/store/downloads/dl/file/id/29224/nbb_400_data_sheet.pdf NBB-400]
|Amplifier
|U13 (6); U30 (11)
|-

|[https://www.minicircuits.com/pdfs/PHA-1+.pdf PHA-1+]
|Amplifier
|U31 (11)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.avagotech.com/docs/AV02-1237EN MGA-62563]
|Low Noise Amplifier
|U36 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-1700.pdf LFCN-1700+]
|Low Pass Filter
|F41 (11)
|-

|[http://www.avagotech.com/docs/AV02-2919EN VMMK-3603]
|Low Noise Amplifier
|U34 (11)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (6)
|-

|[http://www.triquint.com/products/d/doc-a-00000518 855916]
|SAW Filter
|F16 (6)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U15 (6); U28 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-2600.pdf LFCN-2600+]
|Low Pass Filter
|F14, F17 (10)
|-

|[http://www.minicircuits.com/pdfs/TCM1-63AX+.pdf TCM1-63AX+]
|RF Transformer
|T1 (3); T2, T3 (4); T7 (8)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADA4927-1_ADA4927-2.pdf ADA4927-2]
|Differential ADC Driver
|U6 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD8591_8592_8594.pdf AD8591]
|Operational Amplifiers
|U7 (4)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADL5380.pdf ADL5380]
|Quadrature Demodulator
|U8 (4)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q1 (6)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/hmc624a.pdf HMC624ALP4E]
|ATTENUATOR
|U16 (6); U29 (10)
|-

|[https://www.minicircuits.com/pdfs/LFCN-800.pdf LFCN-800+]
|Low Pass Filter
|F2 (3); F25 (7)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-3.3]
|CMOS LDO
|U4, U5 (3); U10, U11 (5); U20, U21 (7); U24, U25 (9); U48 (13)
|-

|[http://www.analog.com/media/en/technical-documentation/evaluation-documentation/ADL5375.pdf ADL5375-05]
|Quadrature Modulator
|U22 (8)
|-

|[http://cds.linear.com/docs/en/datasheet/5510fa.pdf LTC5510]
|Active Mixer
|U28 (10)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/21210G.pdf 24LC024]
|EEPROM
|U38, U39 (12)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADP7104.pdf ADP7104-5.0]
|CMOS LDO
|U41, U42, U43, U44, U45, U46, U47 (13)
|-

|[http://www.diodes.com/_files/datasheets/ZXTC2062E6.pdf ZXTC2062E6]
|TRANSISTORS
|Q2, Q3, Q4, Q5 (13)
|-
|}

==Mechanical Information==
===Drawings===
* [[Media:cu ettus UBX cca.pdf| PDF Format]]

==RF Connectors==
* The UBX daughterboard features female SMA connectors for both the TX/RX and RX2 connectors.

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===UBX-40/UBX-160===
* [[Media:volatility UBX CBX WBX SBX r1 1.pdf]]

==Important Notes==
*A larger 24W (6V, 4A) power supply is required when using a UBX-40 daughterboard and integrated GPS Disciplined Oscillator accessory together in a USRP2, USRP N200, or USRP N210 device.
*The UBX-160 transmitter path has 160 MHz of bandwidth throughout the full frequency range of the device; the receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to 500 MHz.

==RF Performance Data==
* [http://files.ettus.com/performance_data/ubx/UBX-without-UHD-corrections.pdf UBX without UHD Corrections]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

[[Category:Hardware Resources]]

OctoClock CDA-2990

2017-05-12T11:29:08Z

NicolasCuervo:

== Device Overview ==
The OctoClock CDA-2990 is an affordable solution for high-accuracy time and frequency reference distribution. The OctoClock accepts 10 MHz and PPS signals from an external source, and distributed each signal 8 ways. This is a useful accessory for users that would like to build multi-channel systems that are synchronized to a common timing source.

'''Note:''' The OctoClock CDA-2990 is functionally identical to the previous generation OctoClock, which contained an Ettus Research logo.

== Key Features==
{|
|style="vertical-align:top"|
*8-Way Time and Frequency Distribution (1 PPS and 10 MHz)
*Convenient Solution for Multi-Channel Synchronization
*Use with MIMO Capable N-Series Devices for Coherent System
*External 10 MHz/1 PPS Source Required
*19" Rackmount – 1U
|[[File:Product octoclock.jpg|450px|center]]
|[[File:octoclock2.png|450px|center]]

|}

==Signal Levels==
{|
|style="vertical-align:top"|
; 10 MHz output : 1.25 Vpp at 50 ohms, 3.3Vpp at 1M ohms
; 1 PPS output: 20% duty cycle square wave with amplitude 5 V

; 10 MHz input : 0-20 dBm
; 1 PPS input: 2.5-5 V
|[[File:octoclock1.png|450px|center]]
|[[File:octoclock3.png|450px|center]]

|}

==Physical Specifications==
===Dimension (1U Rackmount)===
4 x 17.187x 1.75 inches

==Environmental Specifications==
===Operating Temperature Range===
* 0-40 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==Input/Output Impedance==
All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

==Schematics==
===OctoClock===
[http://files.ettus.com/schematics/octoclock/octoclock.pdf OctoClock Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-
|[http://ww1.microchip.com/downloads/en/DeviceDoc/39662e.pdf ENC28J60−DIG]
|Ethernet Controller
|U103 (1)
|-

|[http://www.atmel.com/images/doc2467.pdf ATmega128]
|Microcontroller
|U102 (1)
|-

|[http://www.mymectronic.com/datasheet/13059_4168782_m9107.pdf M9107]
|SMT OCXO-Based GPSDO
|U206 (2)
|-

|[http://www.ti.com.cn/cn/lit/ds/symlink/sn74aup1t57.pdf SN74AUP1T57]
|VOLTAGE-LEVEL TRANSLATOR
|U204, U203 (2)
|-

|[http://www.ti.com/lit/ds/symlink/cdce18005.pdf CDCE18005−PWR]
|Output Clock Programmable Buffer
|U205 (2)
|-

|[http://www.nxp.com/documents/data_sheet/74HC_HCT4020.pdf 74HC4020]
|Binary Ripple Counter
|U207 (2)
|-

|[http://www.ti.com/lit/ds/symlink/lmz12001.pdf LMZ12001]
|Power Module
|U101 (1)
|-
|}

==Mechanical Info==
===Weight===
2.6 lbs

===Drawings===
* [[File:cu ettus octoclock cca.pdf]]
* [[File:cu ettus-octoclock.pdf]]

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===OctoClock===
* [[Media:OctoClock CoV.pdf]]

==Firmware==
The OctoClock's firmware is divided into two image files: octoclock_bootloader.hex and octoclock_r4_fw.hex. All image files can be found [http://files.ettus.com/binaries/images/ here], in version-specific ZIP files. Download the version corresponding to the version of UHD that you're running. You must use at least version 3.9.2.

* Full instructions on updating the OctoClock's firmware is located here: http://files.ettus.com/manual/page_octoclock.html#upgrading_device
* Source of the firmware for the OctoClock is located at: https://github.com/EttusResearch/uhd/tree/master/firmware/octoclock

==Downloads==
[https://www.ettus.com/content/files/OctoClock_Spec_Sheet.pdf OctoClock Spec Sheet]

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

==FAQ==
*'''What is the OctoClock'''

The OctoClock is a USRP-compatible accessory that allows you to easily synchronize up to 8 USRP radios. Multiple OctoClock devices can be combined for synchronization of larger numbers of USRP radios.

*'''When would I used the OctoClock'''

The OctoClock is useful for synchronizing multiple USRP devices for high channel count systems.

The following applications can benefit from OctoClock clock distribution:

*Direction Finding
*Beamforming
*Adaptive Beamforming
*Multiple-In-Multiple-Out (MIMO) Prototyping
*Geolocation Systems that Use Time-Difference-of-Arrival (TDOA)
*Multi-Channel, Multi-Static, and Passive RADAR
*Multi-Band GPS Record and Playback
*Multi-Band Cellular Monitoring

Essentially, anything that requires from synchronization or the distribution of timing information would benefit from the use of the OctoClock.

*'''Are there example applications that could benefit from the OctoClock'''

32-Channel Phased-Array Receiver Built with QR210 - OctoClock a Component in the System

Afford 8x8 MIMO Testbed

Share your applications with us and we will add them to the list.

*'''How does the OctoClock work'''

The OctoClock accepts 10 MHz and PPS signals from an external source. Active circuits are used to amplify and split the signals 8-ways. Matched-length traces minimize phase differences between all 10 MHz and 1 PPS outputs

The OctoClock-G includes an internal GPSDO (GPS Disciplined Oscillator) which provides an internal source for 10 MHz and PPS from an OCXO high precision oscillator. Add a GPS antenna (optional) with a clear view of the sky for GPS Disciplining of the OCXO that futher enhances frequency accuracy of the OCXO and global time synchronization.

*'''Where can I find user manuals for the OctoClock and USRP'''

Here is helpful document. Sync. and MIMO w/ the USRP

Also, here is some documentation on how to use UHD™ to interact with multi-USRP systems.

*'''What USRP model do you recommend for MIMO systems'''

The USRP N200 or N210 and USRP X300 or X310 are recommended for building high channel count and MIMO systems. These models provide external PPS and 10 MHz reference inputs. The USRP N200 and N210 support the USRP MIMO cable.

The USRP B100, B200, B210, E100, E110, and E310 can be synchronized with 10 MHz/PPS but are not phase coherent MIMO capable devices. The USRP1 cannot be synchronized with 10 MHz/PPS.

*'''How does the automatic switchover functionality work'''

When using the OctoClock-G, the Internal/External switch on the front panel allows the user to choose between the internal GPSDO and external source 10 MHz/PPS source. If the selected sournce is not availble, the device will automatically switch over to the backup frequency source. When switchover is active the corresponding LED indicator will illuminate.

If neither source is present, the internal, external and status LEDs will not be illuminated and the user will not received valid 10 MHz/PPS outputs.

*'''What do the LED indications mean'''

The following list describes the behavior when each of the 6 LED status indicators is illuminated:

*Internal - internal GPSDO is selected and present.
*External - external source is selected and present
*Status - Either the internal GPSDO or external source is selected. If neither source is present this LED will turn off (no signals are output).
*PPS - selected PPS pulse high.
*GPS Locked - GPS is receiving signals and has valid time/position lock.
*Power - Power is applied - smoke is still inside.

*'''What are the input and output specifications'''

*10 MHz Input – 0-10 dBm
*10 MHz Outputs - ~1.4 Vpp Square Wave, Impedance 50 ohm nominal
*1 PPS Input - Logic-level pulse, 2.5V - 5V
*1 PPS Outputs - Logic-level pulse, 2.5V - 5V

*'''What is the function of the Ethernet port'''

Currently, the Ethernet port is non-functional. In the future the Ethernet port may be used to provide a method for reading GPS time and NMEA sentences.

*'''What is the input voltage rating'''

The OctoClock can be powered at any voltage between 6 and 15Vdc.

*'''Are the design files open source'''

As with all of our products, the driver code is free & open source, and can be found in our UHD repository. The schematics are also available.

[[Category:Hardware Resources]]

B200/B210/B200mini/B205mini/B206mini

2017-05-12T11:27:53Z

NicolasCuervo: /* RF Specifications */

== Device Overview ==
The USRP Bus Series provides a fully integrated, single board, Universal Software Radio Peripheral platform with continuous frequency coverage from 70 MHz – 6 GHz. Designed for low-cost experimentation, it combines a fully integrated direct conversion transceiver providing up to 56MHz of real-time bandwidth, an open and reprogrammable Spartan6 FPGA, and fast and convenient bus-powered SuperSpeed USB 3.0 connectivity.

== Key Features==
=== B200===
{|
|style="vertical-align:top"|
* Xilinx Spartan 6 XC6SLX75 FPGA
* Analog Devices AD9364 RFIC direct-conversion transceiver
* Frequency range: 70 MHz - 6 GHz
* Up to 56 MHz of instantaneous bandwidth
* Full duplex, SISO (1 Tx & 1 Rx)
* Fast and convenient bus-powered USB 3.0 connectivity
* Optional Board Mounted GPSDO
|[[File:Product b200.png|250px|center]]
|}

=== B210===
{|
|style="vertical-align:top"|
* Xilinx Spartan 6 XC6SLX150 FPGA
* Analog Devices AD9361 RFIC direct-conversion transceiver
* Frequency range: 70 MHz - 6 GHz
* Up to 56 MHz of instantaneous bandwidth (61.44MS/s quadrature)
* Full duplex, MIMO (2 Tx & 2 Rx)
* Fast and convenient bus-powered USB 3.0 connectivity
* Optional Board Mounted GPSDO
|[[File:Product b210.png|250px|center]]
|}

=== B200mini===
{|
|style="vertical-align:top"|
* Xilinx Spartan-6 XC6SLX75 FPGA
* Analog Devices AD9364 RFIC direct-conversion transceiver
* Frequency range: 70 MHz - 6 GHz
* Up to 56 MHz of instantaneous bandwidth
* Full duplex, SISO (1 Tx & 1 Rx)
* Fast and convenient bus-powered USB 3.0 connectivity
|[[File:Product b200 mini.png|250px|center]]
|}

=== B200mini-i===
{|
|style="vertical-align:top"|
* Industrial-grade Xilinx Spartan-6 XC6SLX75 FPGA
* Analog Devices AD9364 RFIC direct-conversion transceiver
* Frequency range: 70 MHz - 6 GHz
* Up to 56 MHz of instantaneous bandwidth
* Full duplex, SISO (1 Tx & 1 Rx)
* Fast and convenient bus-powered USB 3.0 connectivity
|[[File:Product b200 mini i.png|250px|center]]
|}

=== B205mini-i===
{|
|style="vertical-align:top"|
* Industrial-grade Xilinx Spartan-6 XC6SLX150 FPGA
* Analog Devices AD9364 RFIC direct-conversion transceiver
* Frequency range: 70 MHz - 6 GHz
* Up to 56 MHz of instantaneous bandwidth
* Full duplex, SISO (1 Tx & 1 Rx)
* Fast and convenient bus-powered USB 3.0 connectivity
|[[File:Product b200 mini i.png|250px|center]]
|}

==Frontend Specifications==
===Tuning===
The RF frontend has individually tunable receive and transmit chains. On the B200 and B200 mini, there is one transmit and one receive RF frontend. On the B210, both transmit and receive can be used in a MIMO configuration. For the MIMO case, both receive frontends share the RX LO, and both transmit frontends share the TX LO. Each LO is tunable between 50 MHz and 6 GHz.

===Gains===
All frontends have individual analog gain controls. The receive frontends have 76 dB of available gain; and the transmit frontends have 89.8 dB of available gain. Gain settings are application specific, but it is recommended that users consider using at least half of the available gain to get reasonable dynamic range.

===Bandwidths===
The analog frontend has a seamlessly adjustable bandwidth of 200 kHz to 56 MHz.

Generally, when requesting any possible master clock rate, UHD will automatically configure the analog filters to avoid any aliasing (RX) or out-of-band emissions whilst letting through the cleanest possible signal.

If you, however, happen to have a very strong interferer within half the master clock rate of your RX LO frequency, you might want to reduce this analog bandwidth. You can do so by calling uhd::usrp::multi_usrp::set_rx_bandwidth(bw).

The property to control the analog RX bandwidth is bandwidth/value.

UHD will not allow you to set bandwidths larger than your current master clock rate.

==RF Specifications==
The USRP B200/B210/B200mini/B205mini are derived from the Analog devices AD936x integrated transceiver chip, the overall RF performance of the device is largely governed by the transceiver chip itself.

===RF Performance===
* SSB/LO Suppression -35/50 dBc
* Phase Noise 3.5 GHz 1.0 deg RMS
* Phase Noise 6 GHz 1.5 deg RMS
* Power Output >10dBm
* IIP3 (@ typ NF) -20dBm
* Typical Noise Figure <8dB
* Maximum Input Power: 0 dBm

===Input/Output Impedance===
All RF Ports are matched to 50 Ohm with -10dB or better return loss generally. Detailed test is pending.

===RF Performance Data===
====B200mini / B205mini====
* [[Media:B200mini B205 RF Performance Data 20160119.pdf]]

====B200 / B210====
* [[Media:B200 RF Performance.pdf]]

==Hardware Specifications==
* Ettus Research recommends to always use the latest stable version of UHD

=== B200===
* Current Hardware Revision: 6
* Minimum version of UHD required: 3.8.4
* B200 Rev 5 (AD9364-based board) requires minimum UHD 3.8.4

=== B210===
* Current Hardware Revision: 5
* Minimum version of UHD required: 3.6.0

=== B200mini===
* Current Hardware Revision: 2
* Minimum version of UHD required: 3.9.0

=== B200mini-i===
* Current Hardware Revision: 2
* Minimum version of UHD required: 3.9.0

=== B205mini-i===
* Current Hardware Revision: 1
* Minimum version of UHD required: 3.9.2

==Physical Specifications==
===Dimensions===
* B200mini/B205mini 5.0 x 8.4 cm
* B200/B210 9.7 x 15.5 x 1.5 cm

==Environmental Specifications==
===Operating Temperature Range===
* B200mini / B200 / B210 0-40 °C
* B200mini-i / B205mini-i 0-45 °C

===Operating Humidity Range===
* 10% to 90% non-condensing

==Schematics==
===B200mini/B200mini-i/B205mini-i===
[http://files.ettus.com/schematics/b200mini/b200mini.pdf B200mini/B200mini-i/B205mini-i Schematics]

===B200/B210===
[http://files.ettus.com/schematics/b200/b210.pdf B200/B210 Schematics]

==Key Component Datasheets==
{| class="wikitable" style="width:80%"
!Part Number
!Description
!Schematic ID (Page)
|-
|[http://www.analog.com/en/products/rf-microwave/integrated-transceivers-transmitters-receivers/wideband-transceivers-ic/ad9364.html#product-overview Analog Devices AD9364]
|RF Transceiver
|U1 (2)
|-
|[http://www.analog.com/en/products/rf-microwave/integrated-transceivers-transmitters-receivers/wideband-transceivers-ic/ad9361.html#product-overview Analog Devices AD9361]
|RF Transceiver
|U2 (2,8)
|-

|[http://www.analog.com/en/design-center/landing-pages/001/ad9361-ad9364-integ-rf-agile-transceiver-design-res.html AD9361/AD9364 Product Page]
|RF Transceiver
| -
|-
|[http://www.xilinx.com/products/silicon-devices/fpga/spartan-6.html Xilinx Spartan-6 Product Page]
|FPGA
|rowspan="2"|U1 (2,3,4,6); PG1 (6); U18B, U18C (7); U18D (8); U18E, U18F (9); U18G, U18H (10)
|-
|[http://www.xilinx.com/support/documentation/data_sheets/ds160.pdf XC6SLX75 / XC6SLX150]
|FPGA
|-
|[http://www.analog.com/media/en/technical-documentation/data-sheets/ADF4001.pdf ADF4001]
|Frequency Synthesizer
|U101 (1)
|-

|[http://www.cypress.com/file/140296/download CYUSB3014]
|rowspan="2"|FX3: SuperSpeed USB Controller
|rowspan="2"|U3 (5,6); U13 (5)
|-

|[http://www.cypress.com/applications/ez-usb-fx3-superspeed-usb-30-peripheral-controller-collateral-guide EZ-USB FX3™ Product Page]
|-

|[http://www.skyworksinc.com/uploads/documents/SKY13317_373LF_200914K.pdf SKY13317]
|Antenna Switch
|U801, U810 (8)
|-
|[http://www.anaren.com/sites/default/files/BD3150L50100A00%20Data%20sheet%20Rev%20C.pdf BD3150L50100A00]
|Balun
|U802, U808, U809, U815 (8)
|-
|[https://www.minicircuits.com/pdfs/PGA-102+.pdf PGA−102+]
|Amplifier
|U804, U817 (8)
|-
|[http://www.ctscorp.com/wp-content/uploads/2015/11/008-0371-0.pdf B200mini VXTCXO]
|VXTCXO (B200mini only)
| -
|-
|[http://www.mymectronic.com/datasheet/13059_4168782_m9107.pdf M9107]
|Optional GPSDO (B200/B210 only)
|U100 (1)
|-
|}

==Mechanical Information==
===Weight===
* B200mini 24.0 g
* B200/B210 350 g

===Drawings===
====B200mini====
* [[{{ns:media}}:B200mini_drawing.png]]

====B200====
* [[Media:cu ettus b200 cca.pdf| PDF Format]]

====B210====
* [[Media:cu ettus b210 cca.pdf| PDF Format]]

==Enclosures==
[https://www.ettus.com/product/details/USRP-B200-Enclosure USRP B200/B210 Enclosure]
* Full Steel Enclosure
* Compatible with green USRP B200 and B210 devices (revision 6 or later)
* Front and rear K-Slots for anti-theft protection

==FPGA==
* Utilization statistics are subject to change between UHD releases. This information is current as of UHD 3.9.4 and was taken directly from Xilinx Vivado 2014.4.

===B200===
<pre>
Device utilization summary:
---------------------------

Selected Device : 6slx75fgg484-3

Slice Logic Utilization:
Number of Slice Registers: 15781 out of 93296 16%
Number of Slice LUTs: 19987 out of 46648 42%
Number used as Logic: 15983 out of 46648 34%
Number used as Memory: 4004 out of 11072 36%
Number used as RAM: 972
Number used as SRL: 3032

Slice Logic Distribution:
Number of LUT Flip Flop pairs used: 24062
Number with an unused Flip Flop: 8281 out of 24062 34%
Number with an unused LUT: 4075 out of 24062 16%
Number of fully used LUT-FF pairs: 11706 out of 24062 48%
Number of unique control sets: 434

IO Utilization:
Number of IOs: 172
Number of bonded IOBs: 155 out of 280 55%
IOB Flip Flops/Latches: 124

Specific Feature Utilization:
Number of Block RAM/FIFO: 144 out of 172 83%
Number using Block RAM only: 144
Number of BUFG/BUFGCTRLs: 4 out of 16 25%
Number of DSP48A1s: 76 out of 132 57%
</pre>

===B210===
<pre>
Device utilization summary:
---------------------------

Selected Device : 6slx150fgg484-3

Slice Logic Utilization:
Number of Slice Registers: 29310 out of 184304 15%
Number of Slice LUTs: 36486 out of 92152 39%
Number used as Logic: 29279 out of 92152 31%
Number used as Memory: 7207 out of 21680 33%
Number used as RAM: 1752
Number used as SRL: 5455

Slice Logic Distribution:
Number of LUT Flip Flop pairs used: 43635
Number with an unused Flip Flop: 14325 out of 43635 32%
Number with an unused LUT: 7149 out of 43635 16%
Number of fully used LUT-FF pairs: 22161 out of 43635 50%
Number of unique control sets: 723

IO Utilization:
Number of IOs: 180
Number of bonded IOBs: 163 out of 338 48%
IOB Flip Flops/Latches: 148

Specific Feature Utilization:
Number of Block RAM/FIFO: 186 out of 268 69%
Number using Block RAM only: 186
Number of BUFG/BUFGCTRLs: 4 out of 16 25%
Number of DSP48A1s: 152 out of 180 84%
</pre>

===B200mini===
<pre>
Device utilization summary:
---------------------------

Selected Device : 6slx75csg484-3

Slice Logic Utilization:
Number of Slice Registers: 15949 out of 93296 17%
Number of Slice LUTs: 19963 out of 46648 42%
Number used as Logic: 16140 out of 46648 34%
Number used as Memory: 3823 out of 11072 34%
Number used as RAM: 972
Number used as SRL: 2851

Slice Logic Distribution:
Number of LUT Flip Flop pairs used: 23859
Number with an unused Flip Flop: 7910 out of 23859 33%
Number with an unused LUT: 3896 out of 23859 16%
Number of fully used LUT-FF pairs: 12053 out of 23859 50%
Number of unique control sets: 429

IO Utilization:
Number of IOs: 123
Number of bonded IOBs: 114 out of 328 34%
IOB Flip Flops/Latches: 147

Specific Feature Utilization:
Number of Block RAM/FIFO: 110 out of 172 63%
Number using Block RAM only: 110
Number of BUFG/BUFGCTRLs: 6 out of 16 37%
Number of DSP48A1s: 76 out of 132 57%
Number of PLL_ADVs: 1 out of 6 16%
</pre>

===B205mini===
<pre>
Device utilization summary:
---------------------------

Selected Device : 6slx150csg484-3

Slice Logic Utilization:
Number of Slice Registers: 15949 out of 184304 8%
Number of Slice LUTs: 19963 out of 92152 21%
Number used as Logic: 16140 out of 92152 17%
Number used as Memory: 3823 out of 21680 17%
Number used as RAM: 972
Number used as SRL: 2851

Slice Logic Distribution:
Number of LUT Flip Flop pairs used: 23859
Number with an unused Flip Flop: 7910 out of 23859 33%
Number with an unused LUT: 3896 out of 23859 16%
Number of fully used LUT-FF pairs: 12053 out of 23859 50%
Number of unique control sets: 429

IO Utilization:
Number of IOs: 123
Number of bonded IOBs: 114 out of 338 33%
IOB Flip Flops/Latches: 147

Specific Feature Utilization:
Number of Block RAM/FIFO: 110 out of 268 41%
Number using Block RAM only: 110
Number of BUFG/BUFGCTRLs: 6 out of 16 37%
Number of DSP48A1s: 76 out of 180 42%
Number of PLL_ADVs: 1 out of 6 16%
</pre>

==Interfaces and Connectivity==
B200/B210/B200mini - USB 3.0

===GPIO===
====Power on state====
The hardware power on state and UHD initial state for the front-panel GPIOs is high-Z. For the B2xx, B2xxmini there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: B2xx: pull-up, B2xxmini: pull-up.

====Output Current====
The GPIOs are configured as LVCMOS33 outputs with pull-ups on the B2xx. The strength for LVCMOS and LVTTL on Spartan 6 is 12 mA if not otherwise specified.

===Timing Reference Input===
====B200mini/B200mini-i/B205mini-i====
* 1-PPS or 10 MHz input

=====1-PPS=====
* Maximum: -5V / +5V
* Minimum: 0V / +2.5V

=====10 MHz=====
* Maximum: 0V / +5V
* Minimum: 0V / +1.8V
'''OR'''
* +10dBm ~ +27dBm

====B200/B210====
=====1-PPS=====
* Maximum: 5V
=====10 MHz=====
* Maximum: 15dBm (3.5V into 50 ohms)

==Certifications==
===RoHS===
As of December 1st, 2010 all Ettus Research products are RoHS compliant unless otherwise noted. More information can be found at [http://ettus.com/legal/rohs-information http://ettus.com/legal/rohs-information]

===China RoHS===
'''Management Methods for Controlling Pollution Caused by Electronic Information Products Regulation'''

'''Chinese Customers'''

National Instruments is in compliance with the Chinese policy on the Restriction of Hazardous Substances (RoHS) used in Electronic Information Products. For more information about the National Instruments China RoHS compliance, visit [http://www.ni.com/environment/rohs_china ni.com/environment/rohs_china].

==Certificate of Volatility==
===B200/B210===
* [[Media:volatility USRP B200 B210 r1.pdf]]

==Downloads==

[http://files.ettus.com/manual/md_fpga.html FPGA Resources]

[http://files.ettus.com/binaries/uhd_stable/ UHD Stable Binaries]

[https://github.com/EttusResearch/uhd UHD Source Code on Github]

==FAQ==
This is a list of frequently asked questions on the USRP [https://www.ettus.com/product/details/UB200-KIT B200]/[https://www.ettus.com/product/details/UB210-KIT B210]/[https://www.ettus.com/product/details/USRP-B200mini B200mini]. If you have questions that are not answered in this document, please contact us - [mailto:info@ettus.com info@ettus.com].

'''Will the USRP [https://www.ettus.com/product/details/UB200-KIT B200]/[https://www.ettus.com/product/details/UB210-KIT B210] work with USB 2.0?'''

Yes, both the USRP B200 and USRP B210 will fall back to the USB 2.0 standard if a USB 3.0 port is not available. There are several things to consider. First, the USB 2.0 data rates are slower. Depending on the USB controller, operating system, and other factors, you may achieve a sample rate up to 8 MS/s with USB 2.0. Also, you may not be able to bus-power the USRP B200/B210 in USB 2.0 mode.

'''What samples rates should I expect with USB 3.0? USB 2.0?'''

The performance and throughput of USB 3.0 can vary between host controllers. Ettus Research recommends using the Intel Series 7, 8, and 9 USB controllers. In Linux, the command <code>lspci</code> will show the USB controller on the system.

'''When can I power the USRP B200/B210/B200mini off the USB bus?'''

The experience may vary across various controllers. Generally speaking, bus-power is ideal for SISO operation. If you are using both channels of a USRP B210 we recommend an external power supply. We provide a power supply with the USRP B210.

MIMO operation with the USRP B210 is not recommended when using the USRP B210 on bus-power.

You should not attempt to run the device on bus-power if a GPS-disciplined oscillator is installed.

'''How much power does the USRP consume?'''

The table below shows power consumption (Watts) of a USRP B210 run with a 6V power supply. Figures on a 5V supply (USB power), or with a USRP B200 will be moderately lower. The sample rates shown are aggregate sample rates on the USB 3.0 interface.

{| class="wikitable"
!
!5 Msps
!15.36 Msps
!30.72 Msps
!56 Msps
!61.44 Msps
|-
|1 RX
|1.92
|2.112
|2.184
|2.508
|
|-
|2 RX
|2.148
|2.436
|2.508
|2.64
|
|-
|1 TX
|2.184
|2.34
|2.352
|2.22
|
|-
|2 TX
|2.76
|2.88
|2.904
|2.64
|
|-
|Full Duplex (1x1)
|2.508
|2.736
|2.796
|3.168
|
|-
|2x2 MIMO
|3.252
|3.588
|3.672
|4.11
|4.092
|-
|}

'''Can I build a multi-unit system with the USRP B200/B210?'''

It is possible to synchronize multiple USRP B200/B210 devices using the 10 MHz/1 PPS inputs and an external distribution system like to the OctoClock-G. However, [http://www.ettus.com/kb/detail/usrp-b200-and-b210-usb-30-streaming-rate-benchmarks USB 3.0/2.0 performance] varies dramatically when multiple devices are streaming through the same controller. Generally, we recommend using the USRP N200/N210 if you need to build a high-channel count system.

'''Can I access the source code for the USRP B200/B210?'''

Yes. The USRP B200/B210 is supported by the USRP Hardware DriverTM software. You can find the driver and FPGA source code for the USRP B200/B210, and all other USRP models, in the UHD git repository:

http://files.ettus.com/manual/page_build_guide.html

'''What operating systems does the USRP B200/B210 work on?'''

The USRP B200/B210 is supported on [http://files.ettus.com/manual/page_install.html Linux, MAC and Windows].

'''Does the USRP B200/B210 work with GNU Radio?'''

Yes. The USRP B200/B210 work with our GNU Radio plugin - gr-uhd.

'''Does the USRP B200/B210 work with MATLAB and Simulink?'''

Yes. You need to install the [http://www.mathworks.com/hardware-support/usrp.html Communications System Toolbox Support Package for USRP Radio].

'''Does the USRP B200/B210 work with OpenBTS?'''

Yes. This is a third-party application and you can find instructions here: [http://wush.net/trac/rangepublic/wiki/BuildInstallRun OpenBTS - Build, Install, Run.]

For support, please sign up and contact the [https://lists.sourceforge.net/lists/listinfo/openbts-discuss OpenBTS mailing list].

'''What tools do I need to program the FPGA?'''

The USRP [https://www.ettus.com/product/details/UB200-KIT B200] and USRP [https://www.ettus.com/product/details/UB210-KIT B210] include a Spartan 6 XC6SLX75 and XC6S150, respectively. The USRP B200 can be programmed with the free version of Xilinx tools, while the larger FPGA on the USRP B210 requires a licensed seat.

'''Can I use a GPSDO with the USRP B200/B210?'''

Ettus Research offers a [https://www.ettus.com/product/details/GPSDO-MINI Board-Mounted GPS-Disciplined OCXO] and a [https://www.ettus.com/product/details/GPSDO-TCXO-MODULE Board-Mounted GPS-Disciplined TCXO], which are compatible with the USRP B200/B210. These provide a high-accuracy XO, which can be disciplined to the global GPS standard. Please note: When the GPSDO OCXO model is integrated on the USRP B200/B210, the device should be powered with an external supply instead of USB bus power. The TCXO version can be USB bus powered.

[[Category:Hardware Resources]]

Getting Started with RFNoC Development

2017-02-22T11:57:13Z

NicolasCuervo: /* Image building using the command line */

==Application Note Number==
'''AN-823'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-07-12
|style="text-align:center;"| Martin Braun Nicolas Cuervo
|style="text-align:center;"| Initial creation

|-
|style="text-align:center;"| 2017-01-10
|style="text-align:center;"| Team
|style="text-align:center;"| Added “Digital Gain” example
|-
|}

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

==Overview==
First sections deal with installing tools and validating correct tool installation in order to do RFNoC development. Later sections deal with creating a custom RFNoC block, using the built-in testbench architecture, building an FPGA image with the custom block and finally testing out the new block within GNU Radio.

==Licensing==
The RFNoC code base is open source, including code that executes on the host, as well as code targeted to the USRP hardware (FPGA and microcontroller firmware). As dual-licensed software, RFNoC is available under the open-source GNU Public License version 3 (GPLv3), as well as an alternative, less-restrictive license offered only by Ettus Research. For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Prerequisites==
RFNoC is only supported on the USRP E310/E312 and the USRP X300/X310.

In order to build custom USRP FPGA images and RFNoC blocks the following hardware and software are needed.

* '''Ubuntu 14.04.5 or 16.04.1 (preferred):''' Currently PyBOMBS (which can be used to install the ''Software build tools''), works most reliably in Ubuntu, and thus, we recommend using this distribution. Also, a majority of the scripts used during the build process are Linux (Ubuntu) specific. A PC with multiple cores and 8GB+ of RAM is recommended.

* '''Xilinx Vivado tools (version 2015.4):''' The specific version depends on the branch and state of the FPGA code. The default install location is <code>/opt/Xilinx/Vivado</code>. Once all of the Software build tools are installed the specific version for the downloaded code can be found in the <code>setupenv.sh</code> file located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{DEVICE}</code> directory. Further information can be found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here].

* '''Software build tools:''' If UHD can be or has been compiled from source on the development PC then all the necessary software build components are present (PyBOMBS can be used to set all this up and instructions on how to do so are given in a following step).

* X3xx series or E3xx series device or any future USRP

'''NOTE:'''
* The edition of Xilinx Vivado that is required will depend on which USRP device is being used.
** X3xx series devices: Design Edition or System Edition.
** E3xx series devices: Design Edition, System Edition, or the free WebPack Edition.
* Other operating systems can be used, but the exact steps on how to proceed are not given in this Application Note.
* In some Linux distributions (e.g. Ubuntu) <code>dash</code> is set as default shell, which may cause some issues. It is recommended to set the shell to <code>bash</code> by running the following commands in the terminal. Choose <code><No></code> when prompted by the first command and the second command will validate the that bash will be used.

$ sudo dpkg-reconfigure dash
$ ll /bin/sh

==Creating a development environment==
While this Application Note goes through the process of integrating GNU Radio into the RFNoC development flow, it is by no means required to use or develop within the RFNoC framework, but it makes it a great deal easier to use a framework on top of RFNoC for aspects such as visualization and other features. GNU Radio is freely available and more information about it can be found [http://gnuradio.org/ here].

The following software packages are required in order to setup a development environment/sandbox:

* UHD
* GNU Radio
* gr-ettus

===Create development environment using PyBOMBS===
The cleanest way to set this up is to install everything into a dedicated directory. [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS] is the simplest way to do this. If not already installed, PyBOMBS can be setup with the following commands:

$ sudo apt-get install git
$ sudo apt-get install python-setuptools python-dev python-pip build-essential

$ sudo pip install git+https://github.com/gnuradio/pybombs.git
$ pybombs recipes add gr-recipes git+https://github.com/gnuradio/gr-recipes.git
$ pybombs recipes add ettus git+https://github.com/EttusResearch/ettus-pybombs.git

These commands will do the following:
* Install <code>Git</code>
* Install <code>pip</code> and other Python dependencies
* Install the latest <code>PyBOMBS</code> from its Git repository
* Add the <code>gr-recipes</code> recipes which are used to install GNU Radio specific software
* Add the <code>ettus</code> recipes which are used to install Ettus Research specific software

From here, PyBOMBS can be used to setup and install the development environment/sandbox by running the following command:

$ pybombs prefix init ~/rfnoc -R rfnoc -a rfnoc

This will do the following:

* Create a directory in the user’s home directory called <code>rfnoc</code> (any valid directory name will work)

* Give the prefix an alias of <code>rfnoc</code> ( <code>[-a alias]</code>, e.g. <code>–a rfnoc</code> ), which would be the name given to this path. This name will be used in further steps that use PyBOMBS. When creating the first prefix and omitting the alias, the prefix will be setup as the default.

* Use the <code>rfnoc</code> prefix recipe ( as opposed to a package recipe like <code>gqrx</code> ) to clone UHD, FPGA, GNU Radio, and gr-ettus sources into the <code>~/rfnoc</code> directory as well as compile and install all the software

'''NOTE:''' A user can specify how many cores are used by builds when using PyBOMBS. The default is set to 4. For example, this will set the number of cores used to 3:

$ pybombs config makewidth 3

The value will be written into a configuration file and then applied to subsequent PyBOMBS commands. This value can temporarily be overridden for a specific build by specifying the <code>--config makewidth=X</code> argument, where “<code>X</code>” is an integer number. If the user only has 4 cores it is recommend to use this argument in the pybombs command to limit the number of cores to <4 (e.g. 3) so that the computer stays responsive. Following are 2 examples, one using less cores and the other using more cores:

$ pybombs --config makewidth=3 prefix init ~/rfnoc -R rfnoc -a rfnoc
$ pybombs --config makewidth=7 prefix init ~/rfnoc -R rfnoc -a rfnoc

Then, it is necessary to setup the PyBOMBS environment, so that the system/terminal session will have the environmental variables pointing to this newly created prefix, which is done with the following commands:

$ cd ~/rfnoc
$ source ./setup_env.sh

Once the previous command is run, this terminal session will have access to the environmental variables that allow the complete use of the set of software that was just installed with PyBOMBS. If access to the software is needed in other terminals the same command must be run within them.

'''NOTE:''' Throughout the rest of this document the term <code>{USER_PREFIX}</code> will used at the beginning of different directories. For example, <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts</code> is a directory that contains useful scripts for compiling. The term <code>{USER_PREFIX}</code> is used to denote the folders that precede the <code>/src</code> directory. Examples of what <code>{USER_PREFIX}</code> could be: <code>/home/user/rfnoc</code> or <code>/home/user/myDevfolder/</code>. On many Linux environments using <code>~/</code> at the beginning of the target directory path is equivalent to the user’s home directory.( i.e <code>~/</code> is equal to <code>/home/user/</code>). So <code>{USER_PREFIX}</code> could also look like <code>~/rfnoc</code> or <code>~/myDevfolder/</code>.

===Create the development environment manually===
As an alternative to using PyBOMBS, manually installing and configuring the software is done by following the individual install notes for [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio], [https://files.ettus.com/manual/page_build_guide.html UHD] and [https://github.com/EttusResearch/gr-ettus gr-ettus] and by making sure they are reachable by linkers and compilers.

'''NOTE:''' The Application Note found [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux here] goes through the process of manually installing UHD and GNU Radio on Linux platforms.

To manually download the software, use these <code>git clone</code> commands, which will select the correct branches:

$ git clone --recursive -b rfnoc-devel https://github.com/EttusResearch/uhd.git
$ git clone --recursive -b maint https://github.com/gnuradio/gnuradio.git # master branch is also fine instead of maint
$ git clone -b master https://github.com/EttusResearch/gr-ettus.git
$ git clone -b rfnoc-devel https://github.com/EttusResearch/fpga.git

If UHD, GNU Radio and/or gr-ettus are already installed, it would be sufficient to checkout the branches mentioned and update them them (<code>git pull</code>). Thereafter, rebuild each of the repositories (rebuild order: UHD, GNU Radio, gr-ettus).

===Verify Environment===
Running the command “<code>uhd_config_info</code>” with the “<code>--version</code>” flag will verify that the installation has been completed successfully.

'''NOTE:''' The version string output from this command may differ, however it should be similar to the output below.

$ uhd_config_info --version
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-161- g83150fdd

4.0.0.rfnoc-devel-161-g83150fdd

===Testing the default FPGA image and building from existing blocks===

It is recommended to spend a moment looking at the Ettus Research default image, which is pre-built with a set of RFNoC blocks, as well as building a custom image with a unique set of pre-built RFNoC blocks. To get the default image(s), run the following command:

$ uhd_images_downloader

Ettus Research will be updating the default image(s) occasionally, and <code>uhd_images_downloader</code> can be run anytime after running <code>git pull</code> and re-installing to pull the most current images. Images are stored in the <code>{USER_PREFIX}/share/uhd/images</code> directory.

The following images have the corresponding RFNoC blocks (Computation Engines):

{| class="wikitable"
!Image Name
!Included Blocks
|-

|<code>usrp_x300_fpga_HG.bit</code>
<code>usrp_x300_fpga_XG.bit</code>

<code>usrp_x310_fpga_HG.bit</code>

<code>usrp_x310_fpga_XG.bit</code>
|<code>2x DDC, 2x DUC</code>
|-

|<code>usrp_x300_fpga_RFNOC_HG.bit</code>
<code>usrp_x300_fpga_RFNOC_XG.bit</code>
|<code>DUC, DDC (one channel), fosphor, window, fft, 2x AXI FIFOs</code>
|-

|<code>usrp_x310_fpga_RFNOC_HG.bit</code>
<code>usrp_x310_fpga_RFNOC_XG.bit</code>
|<code>DUC, DDC (one channel), fosphor, window, fft, 2x AXI FIFOs, Keep One in N, FIR, Siggen</code>
|-

|<code>usrp_e310_fpga.bit</code>
<code>usrp_e310_fpga_sg3.bit</code>
|<code>1x DDC, 1x DUC</code>
|-

|<code>usrp_e310_fpga_RFNOC.bit (sg1 version)</code>
<code>usrp_e310_fpga_RFNOC_sg3.bit</code>
|<code>fosphor, window, fft, 2x AXI FIFOs, FIR</code>
|-

|}

Instructions on flashing the image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

'''NOTE:''' FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device.

By following the steps above the following should now be available:
* UHD/RFNoC code downloaded and installed
* FPGA code available
* A valid RFNoC image on your X3xx or E3xx series device

====Inspect default images====
Run the following command, with a USRP connected to your PC, to verify current image on the USRP.

$ uhd_usrp_probe

If an RFNoC image was successfully loaded onto the USRP, there will be a lot of output text (RFNoC code is currently very verbose). The final lines of the output should be similar to the following for an USRP X310 ( e.g. <code>usrp_x310_fpga_HG</code> ):

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1

Final output for <code>usrp_x310_fpga_RFNOC_HG.bit</code> image:

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DUC_0
| | | * FFT_0
| | | * Window_0
| | | * FIR_0
| | | * SigGen_0
| | | * KeepOneInN_0
| | | * fosphor_0
| | | * FIFO_0
| | | * FIFO_1

'''NOTE:''' The actual names and number of blocks can differ. The list of blocks should start with the <code>DmaFIFO_x</code> and <code>Radio_x</code>, and then a couple more lines of block IDs should follow.

====Build custom image with pre-built RFNoC blocks====
Because of the growing number of RFNoC blocks, the user has the option to build an FPGA image with a set of pre-built RFNoC blocks of their choosing. The following steps describe the process for doing this and by so doing will also validate proper tool installation. Because compilation can take a couple of hours, it is recommended the user begin this process while continuing the rest of this guide.

'''NOTE:''' FPGA compilations can run in the background, however they are very resource intensive. If the user intents to use the same computer that is compiling to walk through the rest of this Application Note, it is recommended that the computer has plenty of resources.

The script to initiate a compile is called <code>uhd_image_builder.py</code>, and is located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts</code> directory. Run the help menu by typing:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py --help

A more detailed discussion of this script is given in an upcoming section. For now, compiling an FPGA image that has 2 RFNoC blocks (<code>window</code> and <code>fft</code>) and some <code>FIFOs</code>, is done by running the script with the following arguments.

Example for an X310 USRP:

$ ./uhd_image_builder.py window fft -d x310 -t X310_RFNOC_HG -m 5 --fill-with-fifos

Example for an E310 USRP with Speed Grade 3 (sg3) FPGA:

$ ./uhd_image_builder.py window fft -d e310 -t E310_RFNOC_sg3 -m 5 --fill-with-fifos

At the end of a successful compilation process, write the new image to a USRP. If the image was compiled for a USRP X310, the following command will load the new image. Update the <code>{IP_Address}</code> of the USRP and <code>{USER_PREFIX}</code> to the appropriate values for your configuration before running the command.

$ uhd_image_loader --args “type=x300,addr={IP_ADDRESS}” --fpga-path {USER_PREFIX}/src/uhd-fpga/usrp3/top/x300/build/usrp_x310_fpga_RFNOC_HG.bit

'''NOTE:''' FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device. Additional instructions on flashing a custom image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

After the image has been successfully written to the USRP, power-cycle it and run the “<code>uhd_usrp_probe</code>” utility to view the newly compiled blocks.

$ uhd_usrp_probe

The final lines of output for the image built for the X310 is as follows:

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * Window_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

===Getting started with UHD + RFNoC===
The following new examples included within the <code>rfnoc-devel</code> branch of UHD, are a good reference on how to use RFNoC from UHD.

The following example is based off of <code>rx_samples_to_file.cpp</code>. The example can be configured to place an RFNoC block in between the radio and host.

rfnoc_rx_to_file.cpp

This next example chains a null source to another block and streams the data to the host.

rfnoc_nullsource_ce_rx.cpp

These examples demonstrate the core features and flexibility of RFNoC.

For more information on UHD and UHD development please refer to the [https://kb.ettus.com/UHD UHD Software Resource page], [https://kb.ettus.com/Getting_Started_with_UHD_and_C%2B%2B Getting Started with UHD and C++ Application Note] or directly to the [http://files.ettus.com/manual/ UHD user manual].

===Getting started with GNU Radio + RFNoC===
A good way of getting started with RFNoC in a more visual way is to use GNU Radio. The <code>gr-ettus</code> out-of-tree module (OOT) allows a user to use RFNoC blocks in their local GNU Radio / GNU Radio Companion (GRC) installation. This GNU Radio OOT contains blocks that allow you to configure your FPGA through GRC.

'''NOTE:''' As blocks in the <code>gr-ettus</code> OOT mature, they will be upstreamed to <code>gr-uhd</code>. Also, <code>gr-ettus</code> is a container used by Ettus Research to disseminate experimental or under-development features for <code>gr-uhd</code>. It is not a replacement for <code>gr-uhd</code> (in fact, the latter is a requirement for <code>gr-ettus</code>).

Examples can be run from <code>gr-ettus/examples/rfnoc</code>, provided that the appropriate RFNoC blocks are compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs with RFNoC blocks:

* You always need a <code>Device3</code> object in your flow graph (it does not get connected, see screenshot below).
* You should have at least two RFNoC blocks connected together, going <code>GNU Radio Block</code> -> <code>RFNoC Block</code> -> <code>GNU Radio Block</code> is not recommended (it will work, but with suboptimal performance).

The GNU Radio flowgraph <code>rfnoc_ddc.grc</code> is an example that can be run using the default RFNoC image. Below are screenshots of the flowgraph and what it produces.

[[File:rfnoc gsg an 1.png|center|800px|]]

'''NOTE:''' Copy Block: In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The “copy” block depicted in the screenshot above serves the function as a stream splitter . It’s main purpose, when “enabled”, is to copy the samples it is getting at its input and putting then into the output, but here it is also serving as a boundary between a RFNoC-domain and a GNURadio-domain. In the flowgraph above. after this boundary is passed, the data stream can easily be split into the two sinks to have them run simultaneously (standard GNU Radio functionality). It is possible to connect the GNU Radio blocks directly to RFNoC blocks without a “copy” block, but only one would work at a time (the other ones would have to be disabled). Another way to split data streams from the RFNoC- domain is to use the ”RFNoC: split stream” block, which would split the streams in the RFNoC domain, but this is not very useful here as we are, in any case, moving into the GNURadio-domain.

[[File:rfnoc gsg an 2.png|center|800px|]]

For more information on GNURadio development please refer to the [http://gnuradio.org/doc/doxygen/ GNURadio user's manual and API].

==Starting a custom RFNoC block using RFNoC Modtool==
The figure below shows the basic structure of the RFNoC Stack. Corresponding code is needed in each of the three sections in order to build a custom RFNoC block with GNU Radio integration. A tool called RFNoC Modtool was created in order to minimize the effort needed to implement a new RFNoC block. RFNoC Modtool creates a custom GNU Radio OOT module with the basic structure and the necessary files for each of these sections. RFNoC Modtool is currently a part of the GNU Radio OOT module <code>gr-ettus</code>.

[[File:rfnoc gsg an 3.png|center|800px|]]

===RFNoC Modtool Utilization===
'''NOTE:''' Console outputs may vary depending on the version of UHD the user is running. However, functionality should be the same or similar.

Because the RFNoC Modtool has similar functionality to the <code>gr_modtool</code> [ [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules gr_modtool] ] provided by GNU Radio, those that have worked with <code>gr_modtool</code> in the past will find the RFNoC Modtool familiar.

To check the usage of the tool, run the following:

$ rfnocmodtool help
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

Usage:
rfnocmodtool <command> [options] -- Run <command> with the given options.
rfnocmodtool help -- Show a list of commands.
rfnocmodtool help <command> -- Shows the help for a given command.

List of possible commands:

Name Aliases Description
=====================================================================
disable dis Disable block (comments out CMake entries for files)
info getinfo,inf Return information about a given module
remove rm,del Remove block (delete files and remove Makefile entries)
makexml mx Make XML file for GRC block bindings
add insert Add block to the out-of-tree module.
newmod nm,create Create a new out-of-tree module
rename mv Rename a block in the out-of-tree module.

===Creating an RFNoC OOT Module===

To start generating an RFNoC OOT module navigate to the source location ( i.e. <code>cd ~/{USER_PREFIX}/src</code> ) and type:
$ rfnocmodtool newmod [NAME OF THE MODULE]

Where <code>[NAME OF THE MODULE]</code> is a name the user gives the new module. In the following, a module is created with the name “<code>tutorial</code>”. If the user does not write the name of the module following the <code>newmod</code> command the tool will ask for it interactively. Running this command will create a folder containing the basic folders that you may need for a functional module.

$ rfnocmodtool newmod tutorial
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

Creating out-of-tree module in ./rfnoc-tutorial... Done.
Use 'rfnocmodtool add' to add a new block to this currently empty module.

To see what files and directories were created run:

$ ls rfnoc-tutorial/
apps cmake CMakeLists.txt docs examples grc include lib MANIFEST.md python README.md rfnoc swig

In contrast with <code>gr_modtool</code>, this includes a folder called <code>rfnoc</code>, which is where the UHD/FPGA files are located.

===Adding custom blocks to OOT Module===
In order to add blocks to a module, navigate to the folder just created and use the <code>add</code> command of <code>rfnocmodtool</code>. Continuing with the example above, run the following:

$ cd rfnoc-tutorial
$ rfnocmodtool add [NAME OF THE BLOCK]

For demonstrative purposes, a block named <code>gain</code> will be created. The <code>gain</code> block will multiply samples that pass through it by a constant. As before, if the name is not given, the tool will ask the user for the name. There are several arguments that can be passed to the tool, but running the tool without any of these arguments will give the following interactive parsing output:

$ rfnocmodtool add gain
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

RFNoC module name identified: tutorial
Block/code identifier: gain
Enter valid argument list, including default arguments:
Add Python QA code? [Y/n] N
Add C++ QA code? [y/N] N
Block NoC ID (Hexadecimal): 1111222233334444
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] N
Skip Block interface files Generation? [GRC block ctrl files] [y/N] N

Hitting <code>enter</code> on each one of the options will take the default values.

The following is a description of the valid argument list items:

* '''Add Python QA code:''' Not used.

* '''Add C++ QA code:''' Not used.

* '''NoC ID:''' This ID is a Hexadecimal number which serves as identification between the hardware part and the software part of the design. It can be as long as 16 0-9 A-F digits. If a NoC ID is not provided, it will be set to a random number.

* '''Block Controllers Generation:''' The block controllers are the C++ control that the user can apply to the UHD-part of the design. In these files, the user can add more control over this layer of the design. Depending on the complexity of the block it may be possible to add all necessary control using NoCScript (more details on NoCScript can be found in the section labeled UHD Integration). In this case the cpp/hpp block control files generation are not needed. Default is to generate as their existence will be ignored if not edited.

* '''Block Interface:''' Add more design specific functionality to the design at the GNU Radio interface by generating these block-interface files and adding necessary logic. Depending on the complexity of the block it may be possible to add all necessary control using NoC-Script. In this case the block-interface files are not needed. Default is to generate as their existence will be ignored if not edited.

'''NOTE:''' If the user does not intend to use the block controllers or is not sure if they are needed, the presence of them in the design will do no harm. It is recommended to add them. This leaves the possibility to add more functions inside them in a future stage of development.

After finishing the parsing, the following files will be generated/edited:

Adding file 'lib/gain_impl.h'...
Adding file 'lib/gain_impl.cc'...
Adding file 'include/tutorial/gain.h'...
Adding file 'include/tutorial/gain_block_ctrl.hpp'...
Adding file 'lib/gain_block_ctrl_impl.cpp'...
Editing swig/tutorial_swig.i...
Adding file 'python/qa_gain.py'...
Editing python/CMakeLists.txt...
Adding file 'grc/tutorial_gain.xml'...
Adding file 'rfnoc/blocks/gain.xml'...
Adding file 'rfnoc/fpga-src/noc_block_gain.v'...
rfnoc/testbenches/noc_block_gain_tb folder created
Adding file 'rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/CMakeLists.txt'...

==Creating FPGA portion of custom RFNoC Block==
===RFNoC FPGA User Interface (API)===
RFNoC blocks or Computation Engines (CEs) in the FPGA use a NoC Shell instance to interface with the rest of RFNoC. NoC Shell implements RFNoC's core functionality: packet muxing and demuxing, flow control, and the settings register bus (i.e. write/read control/status registers). The NoC Shell has an interface to the RFNoC AXI stream crossbar and a user interface. NoC Shell AXI stream interfaces expect CHDR packets with a proper header. See the manual for information on [https://files.ettus.com/manual/page_rtp.html CHDR and SID].

'''NOTE:''' AXI Stream is an ARM AMBA standard interface. Xilinx has an [http://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf AXI Reference Guide] with more details on this standard.

[[File:rfnoc gsg an 4.png|center|800px|]]

Many designs will want to use an AXI Stream interface with only sample data. However, as stated earlier, the NoC Shell block expects CHDR packets. To ease interfacing user code, the AXI Wrapper block provides the necessary logic to strip and insert the CHDR header, effectively converting packetized sample data into streaming sample data and vice versa. The example RFNoC blocks <code>noc_block_fft.v</code> and <code>noc_block_fir.v</code> show how AXI Wrapper is used to implement existing Xilinx AXI Stream based IP within a computation engine.

'''NOTE:''' AXI Wrapper also supports AXI Stream buses for configuration. These buses are driven via the setting register bus and do not have back pressure. They also consume two user register addresses per bus.

The primary user interface consists of four AXI stream interfaces ( <code>tready, tvalid, tlast, tdata</code> ) and a settings register bus ( 8-bit, valid user register addresses: <code>128-255</code> ).

{|
|
AXI Stream signals:
* '''m_axis_data_tdata:''' Input sample data packets
** Data coming from host or another CE
* '''s_axis_data_tdata:''' Output sample data packets
** Data going to another CE or host
* '''m_axis_data_tready:''' Input signal to CE
** Used to notify CE that downstream CE is ready for data
* '''s_axis_data_tready:''' Output signal to CE
** Used to notify upstream CE that CE is ready for data
* '''m_axis_data_tvalid:''' Input signal to CE
** Used to indicate upstream CE has valid data
* '''s_axis_data_tvalid:''' Output signal to CE
** Used to indicate to downstream CE that CE has valid data
* '''m_axis_data_tlast:''' Input signal to CE
** Used to delimit packets from upstream CE
* '''s_axis_data_tlast:''' Output signal to CE
** Used to delimit packets to downstream CE
| style="vertical-align:top" |[[File:rfnoc gsg an 5.png|right|500px|]]
|-
|}

[[File:rfnoc gsg an 6.png|center|800px|]]

{|
|
Settings Bus signals:
* '''set_stb:''' Assert to write '''set_data''' to register at '''set_addr'''ess
* '''set_addr:''' Register address to set
* '''set_data:''' Data to set
* '''rb_data:''' Data to read back
* '''rb_strobe:''' Assert to read '''rb_data''' from register at '''set_addr'''ess

| style="vertical-align:top" |[[File:rfnoc gsg an 7.png|right|500px|]]
|-
|}
For the <code>gain</code> example block the following architecture is desired:

[[File:rfnoc gsg an 8.png|center|800px|]]

Open the file <code>rfnoc-tutorial/rfnoc/fpga-src/noc_block_gain.v</code> that contains the RFNoC block skeleton code that was created when the <code>$ rfnocmodtool add gain</code> command was run and modify the following sections.

For the setting register that will hold the constant value as well as the read back register:

'''localparam [7:0] SR_GAIN = SR_USER_REG_BASE;'''
localparam [7:0] SR_TEST_REG_1 = SR_USER_REG_BASE + 8'd1;

'''wire [15:0] gain;'''
'''setting_reg #('''
'''.my_addr(SR_GAIN), .awidth(8), .width(16))'''
'''sr_gain ('''
'''.clk(ce_clk), .rst(ce_rst),'''
'''.strobe(set_stb), .addr(set_addr), .in(set_data), .out(gain), .changed());'''

always @(posedge ce_clk) begin
case(rb_addr)
'''8'd0 : rb_data <= {48'd0, gain};'''
8'd1 : rb_data <= {32'd0, test_reg_1};
default : rb_data <= 64'h0BADC0DE0BADC0DE;
endcase
end

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

'''wire [15:0] i = m_axis_data_tdata[31:16];'''
'''wire [15:0] q = m_axis_data_tdata[15:0];'''

'''wire [31:0] i_mult_gain = i*gain;'''
'''wire [31:0] q_mult_gain = q*gain;'''

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

===Creating and running HDL testbenches===
In order to make the coding iteration process more efficient, it is recommended to create testbenches for all RFNoC blocks before compiling them into the FPGA image. This allows for flaw and/or bug detection early in the design. RFNoC Modtool provides the structure and files ( e.g. <code>noc_block_{USER_BLOCK_NAME}_tb</code> ) for the testbenches of each of the OOT blocks that are added with the <code>$ rfnocmodtool add</code> command.

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

[[File:rfnoc gsg an 9.png|center|800px|]]

From the [[Getting Started with RFNoC Development#Adding_custom_blocks_to_OOT_Module|Adding custom blocks to OOT Module section]] where the <code>gain</code> block was initially created, the last files generated were:

rfnoc/testbenches/noc_block_gain_tb folder created
Adding file 'rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/CMakeLists.txt'...

The <code>noc_block_gain_tb</code> is a folder generated to contain all the files related to the test bench of the <code>gain</code> block. Each time a new OOT block is created, a new folder will be generated as well.

Inside of this folder are the following three files:

* <code>CMakeLists.txt:</code> this is an empty file used, so far, only to increase the scope of the compilers.
* <code>noc_block_gain_tb.sv:</code> this is a ''System Verilog'' file, in which user custom tests are to be located. This is the '''only''' file that needs to be modified.
* <code>Makefile:</code> This file determines the directives that run the simulation.

Open the file <code>rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv</code> and modify the following lines:

initial begin : tb_main
string s;
logic [31:0] random_word;
logic [63:0] readback;
'''logic [15:0] gain;'''

`TEST_CASE_START("Write / readback user registers");
random_word = $random();
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, random_word[15:0]);
tb_streamer.read_user_reg(sid_noc_block_gain, 0, readback);
$sformat(s, "User register 0 incorrect readback! Expected: %0d, Actual %0d", readback[15:0], random_word[15:0]);
`ASSERT_ERROR(readback[15:0] == random_word[15:0], s);'''

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

The next step is to run <code>cmake</code>. If PyBOMBS was used to create the development sandbox, <code>cmake</code> will automatically detect the location of the <code>fpga</code> repository. If PyBOMBS was not used, the user must provide the location of where the <code>fpga</code> repository is installed.

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

$ cmake [-DUHD_FPGA_DIR=/PATH/TO/FPGA/REPOSITORY] ../

Final output from the <code>$ cmake ../</code> command:

-- Configuring done
-- Generating done
-- Build files have been written to: /home/widow/rfnoc/src/rfnoc-tutorial/build

The following command will modify the necessary files and set the correct path to the simulation tools. From now on, every time a new block is added, this command will be run automatically. Remember, only run the following command once for each OOT module (not RFNoC block, but OOT module) created:

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

The gain block testbench can be run by running the following command:

$ make noc_block_gain_tb

The simulation will start. Final output should look like this:

========================================================
TESTBENCH STARTED: noc_block_gain
========================================================
[TEST CASE 1] (t=000000000) BEGIN: Wait for Reset...
[TEST CASE 1] (t=000001002) DONE... Passed
[TEST CASE 2] (t=000001002) BEGIN: Check NoC ID...
Read GAIN NOC ID: 1111222233334444
[TEST CASE 2] (t=000001238) DONE... Passed
[TEST CASE 3] (t=000001238) BEGIN: Connect RFNoC blocks...
Connecting noc_block_tb (SID: 1:0) to noc_block_gain (SID: 0:0)
Connecting noc_block_gain (SID: 0:0) to noc_block_tb (SID: 1:0)
[TEST CASE 3] (t=000005457) DONE... Passed
[TEST CASE 4] (t=000005457) BEGIN: Write / readback user registers...
[TEST CASE 4] (t=000006888) DONE... Passed
[TEST CASE 5] (t=000006888) BEGIN: Test sequence...
[TEST CASE 5] (t=000007633) DONE... Passed
========================================================
'''TESTBENCH FINISHED: noc_block_gain'''
''' - Time elapsed: 7700 ns'''
''' - Tests Expected: 5'''
''' - Tests Run: 5'''
''' - Tests Passed: 5'''
'''Result: PASSED'''
========================================================
$finish called at time : 7700 ns : File "/home/widow/rfnoc/src/rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv" Line 10
INFO: [USF-XSim-96] XSim completed. Design snapshot 'noc_block_gain_tb_behav' loaded.
INFO: [USF-XSim-97] XSim simulation ran for 1000000000us
launch_simulation: Time (s): cpu = 00:00:10 ; elapsed = 00:00:12 . Memory (MB): peak = 966.387 ; gain = 54.848 ; free physical = 3080 ; free virtual = 29888
# if [string equal $vivado_mode "batch"] {
# puts "BUILDER: Closing project"
# close_project
# } else {
# puts "BUILDER: In GUI mode. Leaving project open."
# }
BUILDER: Closing project
****** Webtalk v2015.4 (64-bit)
**** SW Build 1412921 on Wed Nov 18 09:44:32 MST 2015
**** IP Build 1412160 on Tue Nov 17 13:47:24 MST 2015
** Copyright 1986-2015 Xilinx, Inc. All Rights Reserved.

source /home/widow/rfnoc/src/rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/xsim_proj/xsim_proj.hw/webtalk/labtool_webtalk.tcl -notrace
INFO: [Common 17-206] Exiting Webtalk at Tue Jan 10 23:26:20 2017...
INFO: [Common 17-206] Exiting Vivado at Tue Jan 10 23:26:22 2017...
Built target noc_block_gain_tb

With every custom block created, a <code>make</code> directive will be available to run the simulation from the <code>build</code> directory.

===Building the FPGA image with a custom user block===
In this section steps are given on how to initiate an FPGA build while incorporating the user’s custom RFNoC block. The first sections give general information on building RFNoC images. The remaining two sections show how to initiate FPGA builds using a command line interface and using a graphical interface (coming out soon), respectively.

====Discussion on number of blocks in an FPGA image====
There is a maximum number of blocks that can be added for each device. The maximum amount of computation engines (CEs/RFNoC blocks) that each device can use is 16, but the amount of custom blocks that can be added depends on the device.

If using a device from the X3xx series, from the 16 CEs, there are 6 that will be always added and are not subject to direct customization: 1 CE for the AXI bus, 1 CE for the Ethernet Interface, 2 Radios and 2 Dma FIFOS. Because of this, the application will only allow a number of 10 custom blocks on the X3xx series.

If using a device from the E3xx series, 2 CE engines are always added and are not subject to direct customization: 1 CE for the AXI bus and 1 Radio. This would virtually allow 14 slots for custom blocks. However, given the size of the FPGA on the E3xx series of devices, the application only allows a number of 6 custom blocks.

'''NOTE:''' Blocks with higher resource utilization may fill up the FPGA and force the user to include less blocks.

Verify the current maximum values by running the <code>uhd_images_builder.py</code> utility from the scripts directory.

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ uhd_image_builder.py --help

====Discussion on FPGA image targets====
RFNoC target names follow the pattern <code>{DEVICE}_RFNOC_{BUILD_TYPE}</code> with the following build types:

* <code>HG:</code> 1GigE on SFP+ Port0, 10Gig on SFP+ Port
* <code>XG:</code> 10GigE on both SFP+ ports
* <code>HLS:</code> Vivado High Level Synthesis enabled
* <code>sgX:</code> Speed grade for E300 devices (1 or 3)

Some examples are:
* <code>X310_RFNOC_HG</code>
* <code>X300_RFNOC_HG</code>
* <code>X310_RFNOC_XG</code>
* <code>X300_RFNOC_XG</code>
* <code>X310_RFNOC_HLS_HG</code>
* <code>X300_RFNOC_HLS_HG</code>
* <code>E310_RFNOC</code> (this is for the speed grade 1 FPGA version of E310, append <code>_sg3</code> for speed grade 3)

'''NOTE:''' E310, E312 and E313 all have the same FPGA hardware and therefore will use the <code>E310_RFNOC_{BUILD_TYPE}</code> target. USRP E3xx devices have either <code>sg1</code> or <code>sg3</code> hardware, please visit [http://files.ettus.com/e3xx_images/README here] to find out how to differentiate.

Additional information about the build targets can be found at the build instructions for USRP3, found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here].

====Image building using the command line====
The script <code>uhd_image_builder.py</code> is used to generate the NoC block instantiation file and build the FPGA image. Run the help menu by typing:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py --help

usage: uhd_image_builder.py [-h] [-I INCLUDE_DIR [INCLUDE_DIR ...]]
[-m MAX_NUM_BLOCKS] [--fill-with-fifos]
[-o OUTFILE] [-d DEVICE] [-t TARGET] [-g] [-c]
[blocks [blocks ...]]

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

optional arguments:
-h, --help show this help message and exit
-I INCLUDE_DIR [INCLUDE_DIR ...], --include-dir INCLUDE_DIR [INCLUDE_DIR ...]
Path directory of the RFNoC Out-of-Tree module
-m MAX_NUM_BLOCKS, --max-num-blocks MAX_NUM_BLOCKS
Maximum number of blocks (Max. Allowed for x310|x300:
10, for e300: 6)
--fill-with-fifos If the number of blocks provided was smaller than the
max number, fill the rest with FIFOs
-o OUTFILE, --outfile OUTFILE
Output /path/filename - By running this directive, you
won't build your IP
-d DEVICE, --device DEVICE
Device to be programmed [x300, x310, e310]
-t TARGET, --target TARGET
Build target - image type [X3X0_RFNOC_HG,
X3X0_RFNOC_XG, E310_RFNOC_sg3...]
-g, --GUI Open Vivado GUI during the FPGA building process
-c, --clean-all Cleans the IP before a new build

Here are details on the usage of the script which is followed by an example:

'''Blocks:''' The first arguments are the names of RFNoC blocks that the user wants to have compiled into the new image which are separated by a space. They can be custom blocks from the user’s OOT module or from the ones that are provided from Ettus, or a combination. Blocks provided by Ettus Research are listed (among other sources necessary for the FPGA build) in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/lib/rfnoc/Makefile.srcs</code> file.

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

However, as all the RFNoC blocks have the same <code>noc_block_</code> prefix, for simplicity this prefix is omitted when listing the blocks in the <code>uhd_image_builder.py</code> utility. As an example of the incorrect and correct way of adding blocks, consider the following examples when adding the <code>noc_block_null_source_sink</code> and <code>noc_block_siggen</code> blocks:

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

'''NOTE:''' Blocks generated by the RFNoC Modtool follow the same naming convention.

There is an increasing list of pre-built blocks. Here is a sample:

* <code>axi_fifo_loopback</code>
* <code>axi_dma_fifo</code>
* <code>fir_filter</code>
* <code>fft</code>
* <code>null_source_sink</code>
* <code>schmidl_cox</code>
* <code>packet_resizer</code>
* <code>split_stream</code>
* <code>vector_iir</code>
* <code>addsub</code>
* <code>window</code>
* <code>keep_one_in_n</code>
* <code>pfb</code>
* <code>export_io</code>
* <code>conv_encoder_qpsk</code>
* <code>siggen</code>
* <code>logpwr</code>
* <code>fosphor</code>
* <code>moving_avg</code>
* <code>ddc</code>
* <code>duc</code>

RFNoC related blocks generally reside in <code>fpga/usrp3/lib/rfnoc/</code>.

{| class="wikitable" style="margin:auto;"

!Block
!Filename
!Description
|-

|FIFO
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_axi_fifo_loopback.v noc_block_axi_fifo_loopback.v]
|Simple FIFO loopback / passthrough block.
|-

|FFT
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_fft.v noc_block_fft.v]
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_fir_filter.v noc_block_fir_filter.v]
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_window.v noc_block_window.v]
|Windowing block for use with FFT block.
|-

|Vector IIR
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_vector_iir.v noc_block_vector_iir.v]
|Single pole IIR with configurable coefficients that filters data along vectors (i.e. parallel streams of samples). Useful with FFT output.
|-

|Keep One in N
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_keep_one_in_n.v noc_block_keep_one_in_n.v]
|Keeps one packet every N packets.
|-

|AddSub
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_addsub.v noc_block_addsub.v]
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_null_source_sink.v noc_block_null_source_sink.v]
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_packet_resizer.v noc_block_packet_resizer.v]
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_split_stream.v noc_block_split_stream.v]
|Replicates an input stream to a configurable number of output streams.
|-

|}

'''NOTE:''' There is a restriction on the amount of blocks that can added into the FPGA image, see the section in this Application Note labeled [[Getting_Started_with_RFNoC_Development#Discussion_on_number_of_blocks_in_an_FPGA_image|Discussion on number of blocks in an FPGA image]] for more information.

<code>-I INCLUDE_DIR:</code> The <code>-I</code> directive provides the path to the users <code>rfnoc/fpga-src</code> directory which contains the custom blocks. This path is needed by the Xilinx Vivado tool. Inside the <code>fpga-src</code> directory there is a file called <code>Makefile.srcs</code> that contains the path of the OOT module and a list of all the custom OOT blocks. This is an auto generated file, which is amended every time a new block is added to the OOT module. Manually modifying this file is not recommended. If there are multiple OOT modules with various custom blocks that reside in different directories the way to include them all is by separating the different paths by a space (e.g. <code>-I /first/OOT/path/ /second/OOT/path/</code>).

'''IMPORTANT:''' Please be sure to terminate the path of your OOT with the "/" character. Otherwise the path might not be recognized.

<code>-d DEVICE:</code> The <code>-d</code> directive directs the script on which USRP device the build is for. If no <code>–d</code> is included the default is <code>–d x310</code>. Generation-3 USRPs and above all support RFNoC.

<code>-t TARGET:</code> The <code>–t</code> directive directs the script on which type of image to build for the chosen device. With each USRP device there are several build options to choose from. Detailed information about the build targets can be found at the build instructions for USRP3, found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here]. If <code>-t</code> is not included, a default target will be chosen for the given device. For example, the default <code>X310_RFNOC_HG</code> target builds for the <code>–d x310</code> device. More details on targets can be found in the section of this Application Note labeled [[Getting Started with RFNoC Development#Discussion_on_FPGA_image_targets|Discussion on FPGA image targets]].

<code>-m MAX_NUM_BLOCKS:</code> The <code>–m</code> directive specifies the max number of RFNoC blocks to build on the FPGA image. An RFNoC image does not need to fill all available slots with RFNoC blocks.

<code>--fill-with-fifos:</code> The <code>--fill-with-fifos</code> directive will fill the empty RFNoC block slots with FIFOS. As an example, if a user indicates three RFNoC blocks by name and also specifies <code>–m 5</code> then the other two slots will be filed with FIFOs.

<code>-o OUTFILE:</code> With the <code>-o</code> directive, the RFNoC blocks instantiation file is generated and saved at the desired path with the given name for the user to inspect. The FPGA image will NOT build if this directive is provided. The purpose of the <code>uhd_image_builder.py</code> script is to auto generate an instantiation file and populate the source files needed for the Xilinx Vivado tool to build the FPGA image, however, it may be desirable to only see the effect of adding a custom OOT module in the <code>fpga/</code> directory, or for inspecting the instantiation file. When the directive is not provided the <code>rfnoc_ce_auto_inst_x3x0.v</code> file is overwritten and the FPGA image build process will start automatically (standard use).

<code>-g, --GUI:</code> Open Vivado GUI during the FPGA building process

<code>-c, --clean-all:</code> Cleans the IP before a new build

Here is how to create an X310 FPGA image incorporating the <code>gain</code> block that was created earlier in this Application Note:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py gain ddc fft -I {USER_PREFIX}/src/rfnoc-tutorial/rfnoc/fpga-src/ -d x310 -t X310_RFNOC_HG -m 6 --fill-with-fifos

At the end of a successful compilation process, write the new image to a USRP. The following command will load the new image. Update the <code>{IP_Address}</code> of the USRP and <code>{USER_PREFIX}</code> to the appropriate values for your configuration before running the command.

$ uhd_image_loader --args “type=x300,addr={IP_ADDRESS}” --fpga-path {USER_PREFIX}/src/uhd-fpga/usrp3/top/x300/build/usrp_x310_fpga_RFNOC_HG.bit

'''NOTE:'''
* The FPGA image building process may take over an hour.

* FPGA images are specific to the USRP device NOT the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device. Additional instructions on flashing a custom image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

* [Environment setup] - The <code>uhd_image_builder.py</code> script will also set up the Xilinx Vivado environment by automatically running the <code>setupenv.sh</code> script located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{device}</code> directory. The <code>setupenv.sh</code> script assumes that Xilinx Vivado is installed in the default location of <code>/opt/Xilinx/Vivado</code>. If the installation is in a different directory the <code>setupenv_base.sh</code> script will need to be modified. The script is located at: <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts/setupenv_base.sh</code>

Besides the custom <code>gain</code> block, a <code>DDC</code> and <code>FFT</code> block are also being added along with three <code>FIFOs</code>. The <code>DDC</code>, <code>FFT</code> and <code>FIFO</code> blocks are already in the script's path and therefore do not need their path specified (they ship with the Ettus Research FPGA code). The reason three FIFOs are added is because the max number of blocks was specified to be 6 ( <code>-m 6</code> ) and since only 3 blocks were specifically named the other three slots are filled with FIFOs.

[[File:rfnoc gsg an 10.png|center|800px|]]

'''NOTE:''' Instructions on flashing the image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series. FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device.

Once the newly compiled image is loaded onto a USRP X3xx running the following command will show what RFNoC blocks are available on the FPGA:

$ uhd_usrp_probe

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * '''Block_0'''
| | | * DDC_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

'''NOTE:''' The reason the custom block is called <code>Block_0</code> and not <code>gain_0</code> is because there is still host side software/files that need updated in order for this block to populate it’s proper name. A following section (UHD Integration) will step through the process of updating those host side files.

====Using a graphical interface====
A graphical user interface for FPGA generation and building is shipped along with the <code>uhd_image_builder.py</code> script. This intuitive application aids in setting up a custom FPGA build.

This utility is located in the same <code>scripts</code> directory as <code>uhd_image_builder.py</code>.

To run it, enter the following commands:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts/
$ ./uhd_image_builder_gui

The application will then be launched:

[[File:rfnoc gsg an 11.png|center|800px|]]

'''1. Select build target:''' In this panel the available build targets are listed. This list may vary depending on which branch of the FPGA repository this user is using. Only RFNoC targets are listed. The build type descriptions are:

* <code>HG:</code> 1GigE on SFP+ Port0, 10Gig on SFP+ Port1
* <code>XG:</code> 10GigE on both SFP+ ports
* <code>HLS:</code> Vivado High Level Synthesis enabled
* <code>sgX:</code> Speed grade for E300 devices (1 or 3)

'''2. List of blocks available:''' In this panel the available blocks are listed that can be included into a custom design. This list separates the RFNoC blocks provided by Ettus Research and the OOT modules and corresponding blocks that the user adds. Given the hardware differences between the X3xx and E3xx devices, this list will dynamically change when a different device is selected from the panel on the left. This implies that it is necessary to add the OOT modules for each device independently. This is accomplished by using the <code>Add OOT Blocks</code> feature of the application, details of which are explained at #7 (<code>Add OOT Blocks</code>).

'''3. Blocks in current design:''' This panel will be populated by adding elements from the available blocks. All the blocks listed in here will be compiled into the FPGA custom image. There is a maximum number of blocks that can be added for each device. See the section in this App Note labeled Discussion on number of blocks in an FPGA image for more information.

'''4. Add button (>>):''' Manually add the blocks from the central panel into your design.

'''5. Remove button (<<):''' Remove blocks from the current design (far-left panel)

'''6. Fill with FIFOs:''' By checking this box, the design will fill any available/unspecified block slots with FIFOs. The number of FIFO blocks that will be instantiated is based on the rules of amount of blocks explained at #3. When less than the max amount of blocks are needed for certain implementation, many users choose to fill their design with FIFO blocks.

'''7. Open Vivado GUI:''' Open Vivado GUI during the FPGA building process. This allows the user to save a Vivado project with all IP and work within the Vivado GUI for development.

'''8. Clean IP:''' Cleans the IP before a new build (recompiles all IP).

'''9. Add OOT blocks:''' Manually add RFNoC Modtool-generated OOT modules by pointing the application to the <code>Makefile.srcs</code> file, which is located in the <code>{USER_PREFIX}/src/{USER-OOT-moddir}/rfnoc/fpga-srcs/</code> directory. After adding this file, blocks will appear under “<code>OOT blocks for XXXX devices</code>”

'''10. Import from GRC:''' If the user has a GNU Radio flowgraph with RFNoC blocks already in it, this application can read what RFNoC blocks are in the flowgraph and populate the <code>Blocks in current design</code> section of the application with the necessary RFNoC blocks. '''NOTE:''' All RFNoC blocks pulled from a <code>.grc</code> file must be in the of <code>List of blocks available</code> before beginning the build.

'''11. Show Instantiation File:''' The application auto-generates the instantiation file that is going to be used by Vivado to build the FPGA image. This instantiation file can be viewed and edited before starting the build by clicking this button.

'''12. Generate .bit file:''' Start the build by clicking this button.

'''NOTE:''' See the latter end of the previous section for additional information on what to expect once the compile has started as well as final output.

==Creating Software/Host portion of custom RFNoC Block==
Now that the FPGA portion is complete the next step is to add software integration to UHD and GNU Radio as depicted in the RFNoC Stack below.

[[File:rfnoc gsg an 12.png|center|800px|]]

===UHD integration===
Despite the data processing happening on the FPGA, the host software still has a lot of responsibilities in order for an RFNoC application to function. For example, it needs to know which settings registers are available within an RFNoC block, or what kind of input and output a block has. All of this information goes into the <code>Block Declaration</code>, which is an XML file that is readable by UHD. Often, some simple logic needs to be embedded in the XML file, which we can do by using a simple scripting language called Noc-Script. Changes to the block declaration file are immediately imported into UHD every time an application is executed, and therefore, no software development toolchain needs to be set up.

The list of things declared by the block declaration file includes:

* Block name and Noc-ID
* Registers
* Inputs and outputs (including types)

In some cases, additional C++ code is required to properly control a block from software. In this case, a <code>Block Controller</code> file is required as well as the declaration file. In most cases, the default block controller provided by UHD is sufficient, so no C++ code needs to be written. Writing custom block controllers requires more effort, and means having to set up a programming toolchain. A common reason to write custom C++ block controllers is if setting a register requires a lot of computation, which is not feasible to do within a block declaration file (e.g., using Noc-Script).

Skeleton code for both the block declaration and the block controller (if required) can be generated through RFNoC Modtool.

Because the <code>gain</code> block does not require anything other than simply reading and writing to a single register the default block controller will suffice for this example. However, we will need to add information about the register.

Open the <code>gain.xml</code> file located in the <code>/rfnoc-tutorial/rfnoc/blocks</code> directory and add the following:

<?xml version="1.0"?>
<nowiki></nowiki>
<nocblock>
<name>gain</name>
<blockname>gain</blockname>
<ids>
<id revision="0">1111222233334444</id>
</ids>
'''<nowiki></nowiki>'''
'''<registers>'''
'''<setreg>'''
'''<name>GAIN</name>'''
'''<address>128</address>'''
'''</setreg>'''
'''</registers>'''
'''<nowiki></nowiki>'''
'''<args>'''
'''<arg>'''
'''<name>gain</name>'''
'''<type>double</type>'''
'''<value>1.0</value>'''
'''<check>GE($gain, 0.0) AND LE($gain, 32767.0)</check>'''
'''<check_message>Invalid gain.</check_message>'''
'''<action>'''
'''SR_WRITE("GAIN", IROUND($gain))'''
'''</action>'''
'''</arg>'''
'''</args>'''
<nowiki></nowiki>
<ports>
<sink>
'''<name>in0</name>'''
'''<type>sc16</type>'''
</sink>
<nowiki><source></nowiki>
'''<name>out0</name>'''
'''<type>sc16</type>'''
<nowiki></source></nowiki>
</ports>
</nocblock>

===GNU Radio Integration===
GNU Radio is built around the concept of blocks, similarly to RFNoC. When mapping RFNoC into an application, the simple constraint is made that every RFNoC block maps to a single GNU Radio block. Thus, when creating mixed GNU Radio/RFNoC applications, there is a very clear 1:1 mapping between what’s happening in RFNoC and GNU Radio.

Since most RFNoC blocks behave very similar to one another from GNU Radio’s perspective, it is generally not required to write C++ code for another block. Rather, a default block provided by RFNoC can be used with appropriate configuration. However, in some cases it may be desirable or even necessary to write a custom GNU Radio block for more specific controlling of the underlying RFNoC block. GNU Radio allows writing blocks in either C++ or Python, but since UHD and RFNoC do not have a Python API, a custom wrapper for an RFNoC block needs to be written in C++. RFNoC Modtool will create skeleton files for this purpose.

The most popular and effective way to use GNU Radio is through the graphical interface, the GNU Radio Companion (GRC). GRC requires a separate description of every GNU Radio block in order to become available in the graphical UI, and the same is true for an RFNoC block that is wrapped in a GNU Radio block (even if the generic RFNoC block wrapper is used). For GNU Radio 3.7 and earlier, GRC bindings for blocks are written as XML files with interspersed Cheetah or Python statements. For a more detailed tutorial on how to write these files, refer to the [http://gnuradio.org/redmine/projects/gnuradio/wiki GNU Radio Documentation] and associated [http://gnuradio.org/redmine/projects/gnuradio/wiki/Guided_Tutorials tutorials].

====GNU Radio Block Code====

* C++ or Python, although RFNoC blocks need to be written in C++ (if at all)
* How does GNU Radio interface to RFNoC?
** via C++ infrastructure code in <code>gr-ettus</code>
** <code>gr-ettus</code> provides a base RFNoC block class
** Users extend base class for their RFNoC blocks
** Many blocks can use base class “as is”
** No C++ or Python code!
* <code>rfnoc-tutorial/lib/gain_impl.cc</code>
** The gain block does not need anything additional

====GNU Radio Companion Bindings====
* XML
* Describes GNU Radio blocks to GRC
* No recompilation
* Requirement of GNU Radio Companion
* Not strictly necessary for GNU Radio
* Tutorial on how to write them:
** [http://gnuradio.org/redmine/projects/gnuradio/wiki/GNURadioCompanion http://gnuradio.org/redmine/projects/gnuradio/wiki/GNURadioCompanion ]
* Skeleton file generated by RFNoC Modtool

Open the <code>tutorial-gain.xml</code> file located in the <code>rfnoc-tutorial/grc</code> directory and edit as follows:

<nowiki><?xml version="1.0"?></nowiki>
<block>
<name>RFNoC: gain</name>
<key>tutorial_gain</key>
<category>tutorial</category>
<import>import tutorial</import>
<make>tutorial.gain(
self.device3,
uhd.stream_args( \# TX Stream Args
cpu_format="'''fc32'''",
otw_format="'''sc16'''",
args="gr_vlen={0},{1}".format(${grvlen}, "" if $grvlen == 1 else "spp={0}".format($grvlen)),
),
uhd.stream_args( \# RX Stream Args
cpu_format="'''fc32'''",
otw_format="'''sc16'''",
args="gr_vlen={0},{1}".format(${grvlen}, "" if $grvlen == 1 else "spp={0}".format($grvlen)),
),
$block_index, $device_index,
)
'''self.$(id).set_arg("gain", $gain)'''
'''</make>'''
'''<callback>set_arg("gain", $gain)</callback>'''
<nowiki></nowiki>

.
.
.

<option>
<name>Byte</name>
<key>u8</key>
</option>
</param>
<param>
<name>'''Gain'''</name>
<key>'''gain'''</key>
'''<value>1.0</value>'''
<type>'''real'''</type>
</param>

<nowiki></nowiki>
<sink>
<name>in</name>
<type>'''complex'''</type>
<vlen>$grvlen</vlen>
<domain>rfnoc</domain>
</sink>

<nowiki></nowiki>
<nowiki><source></nowiki>
<name>out</name>
<type>'''complex'''</type>
<vlen>$grvlen</vlen>
<domain>rfnoc</domain>
<nowiki></source></nowiki>
</block>

'''NOTE:''' Indentation spacing is important in the <code><make></code> section.

===Compile, Install and Verify===

$ cd {USER_PREFIX}/src/rfnoc-tutorial/build
$ make install

$ uhd_usrp_probe

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * '''gain_0'''
| | | * DDC_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

'''NOTE:''' In the case where the <code>gain_0</code> does not appear but <code>Block_0</code> does: Most likely, the XML block declaration file (see [[Getting_Started_with_RFNoC_Development#UHD_integration|UHD Integration]] section) for the block contains a NoC-ID that does not match with any NoC-ID defined in the hardware part of the design. The user has to be certain that the description files are up-to-date and that the NoC-ID matches in the SW and HW side. See the [[Getting_Started_with_RFNoC_Development#UHD_integration|UHD Integration]] section to update those host side files.

==Testing out the custom block==
At this point the custom <code>gain</code> RFNoc Block (Computation Engine) can be used within a GNU Radio flowgraph. Below is an example GRC flowgraph using our new block as well as the output application it produces.

[[File:rfnoc gsg an 13.png|center|800px|]]

'''NOTE:''' Copy Block: In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The “copy” block depicted in the screenshot above serves the function as a stream splitter . It’s main purpose, when “enabled”, is to copy the samples it is getting at its input and putting then into the output, but here it is also serving as a boundary between a RFNoC-domain and a GNURadio-domain. In the flowgraph above. after this boundary is passed, the data stream can easily be split into the two sinks to have them run simultaneously (standard GNU Radio functionality). It is possible to connect the GNU Radio blocks directly to RFNoC blocks without a “copy” block, but only one would work at a time (the other ones would have to be disabled). Another way to split data streams from the RFNoC-domain is to use the ”RFNoC: split stream” block, which would split the streams in the RFNoC domain, but this is not very useful here as we are, in any case, moving into the GNURadio-domain.

[[File:rfnoc gsg an 14.png|center|800px|]]

==Troubleshooting==
===Xilinx Vivado===
====Compile issues====
=====Synthesis is failing=====
Verify all the correct Xilinx [[Getting Started with RFNoC Development#Prerequisites|prerequisite software]] is installed.

Additional helpful information can be found in the following Xilinx forum posts:
* https://forums.xilinx.com/t5/Synthesis/Synthesis-failed-without-reporting-any-error/td-p/686000
* https://forums.xilinx.com/t5/Installation-and-Licensing/Vivado-on-Linux-synthesis-fails-with-no-error-message/td-p/732143

====Environment Setup====
The <code>uhd_image_builder.py</code> script will also set up the Xilinx Vivado environment by automatically running the <code>setupenv.sh</code> located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{device}</code> directory. The <code>setupenv.sh</code> script assumes that Xilinx Vivado is installed in the default location of <code>/opt/Xilinx/Vivado</code>. If the installation is in a different directory, then the <code>setupenv_base.sh</code> script will need to be modified. The script is located at: <code>{USER_PREFIX}/src/uhd-fpga/usrp3_rfnoc/tools/scripts/setupenv_base.sh</code>.

==Reference Files==
The following reference files are included within the gain_src.tar.gz archive linked below:

* gain.xml
* noc_block_gain.v
* noc_block_gain_tb.sv
* tutorial_gain.xml
* rfnoc_gain.grc

[[Media:gain src.tar.gz]]

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Software Resources Page]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf RFNoC Introduction]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]
* [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015 ]
** Explaining the slides of Intro, FPGA and Host presentations above (in that order).
* [https://www.youtube.com/watch?v=51rpjJ2W0Qs Video: It's the RFNoC Life for Us by Martin Braun at GRCon16, 2016]

===GNU Radio resources===
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNU Radio OutOfTree Modules tutorial]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio Installation]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/Tutorials GNU Radio Tutorials]

===UHD resources===
* [https://kb.ettus.com/UHD UHD Software Resources Page]
* [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]
* [http://files.ettus.com/manual/ UHD Manual]

===Other resources===
* [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]
* [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD + GNU Radio Application Note (Linux)]
* [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS]

[[Category:Application Notes]]

Getting Started with RFNoC Development

2017-02-22T11:54:57Z

NicolasCuervo: /* Image building using the command line */

==Application Note Number==
'''AN-823'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-07-12
|style="text-align:center;"| Martin Braun Nicolas Cuervo
|style="text-align:center;"| Initial creation

|-
|style="text-align:center;"| 2017-01-10
|style="text-align:center;"| Team
|style="text-align:center;"| Added “Digital Gain” example
|-
|}

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

==Overview==
First sections deal with installing tools and validating correct tool installation in order to do RFNoC development. Later sections deal with creating a custom RFNoC block, using the built-in testbench architecture, building an FPGA image with the custom block and finally testing out the new block within GNU Radio.

==Licensing==
The RFNoC code base is open source, including code that executes on the host, as well as code targeted to the USRP hardware (FPGA and microcontroller firmware). As dual-licensed software, RFNoC is available under the open-source GNU Public License version 3 (GPLv3), as well as an alternative, less-restrictive license offered only by Ettus Research. For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Prerequisites==
RFNoC is only supported on the USRP E310/E312 and the USRP X300/X310.

In order to build custom USRP FPGA images and RFNoC blocks the following hardware and software are needed.

* '''Ubuntu 14.04.5 or 16.04.1 (preferred):''' Currently PyBOMBS (which can be used to install the ''Software build tools''), works most reliably in Ubuntu, and thus, we recommend using this distribution. Also, a majority of the scripts used during the build process are Linux (Ubuntu) specific. A PC with multiple cores and 8GB+ of RAM is recommended.

* '''Xilinx Vivado tools (version 2015.4):''' The specific version depends on the branch and state of the FPGA code. The default install location is <code>/opt/Xilinx/Vivado</code>. Once all of the Software build tools are installed the specific version for the downloaded code can be found in the <code>setupenv.sh</code> file located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{DEVICE}</code> directory. Further information can be found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here].

* '''Software build tools:''' If UHD can be or has been compiled from source on the development PC then all the necessary software build components are present (PyBOMBS can be used to set all this up and instructions on how to do so are given in a following step).

* X3xx series or E3xx series device or any future USRP

'''NOTE:'''
* The edition of Xilinx Vivado that is required will depend on which USRP device is being used.
** X3xx series devices: Design Edition or System Edition.
** E3xx series devices: Design Edition, System Edition, or the free WebPack Edition.
* Other operating systems can be used, but the exact steps on how to proceed are not given in this Application Note.
* In some Linux distributions (e.g. Ubuntu) <code>dash</code> is set as default shell, which may cause some issues. It is recommended to set the shell to <code>bash</code> by running the following commands in the terminal. Choose <code><No></code> when prompted by the first command and the second command will validate the that bash will be used.

$ sudo dpkg-reconfigure dash
$ ll /bin/sh

==Creating a development environment==
While this Application Note goes through the process of integrating GNU Radio into the RFNoC development flow, it is by no means required to use or develop within the RFNoC framework, but it makes it a great deal easier to use a framework on top of RFNoC for aspects such as visualization and other features. GNU Radio is freely available and more information about it can be found [http://gnuradio.org/ here].

The following software packages are required in order to setup a development environment/sandbox:

* UHD
* GNU Radio
* gr-ettus

===Create development environment using PyBOMBS===
The cleanest way to set this up is to install everything into a dedicated directory. [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS] is the simplest way to do this. If not already installed, PyBOMBS can be setup with the following commands:

$ sudo apt-get install git
$ sudo apt-get install python-setuptools python-dev python-pip build-essential

$ sudo pip install git+https://github.com/gnuradio/pybombs.git
$ pybombs recipes add gr-recipes git+https://github.com/gnuradio/gr-recipes.git
$ pybombs recipes add ettus git+https://github.com/EttusResearch/ettus-pybombs.git

These commands will do the following:
* Install <code>Git</code>
* Install <code>pip</code> and other Python dependencies
* Install the latest <code>PyBOMBS</code> from its Git repository
* Add the <code>gr-recipes</code> recipes which are used to install GNU Radio specific software
* Add the <code>ettus</code> recipes which are used to install Ettus Research specific software

From here, PyBOMBS can be used to setup and install the development environment/sandbox by running the following command:

$ pybombs prefix init ~/rfnoc -R rfnoc -a rfnoc

This will do the following:

* Create a directory in the user’s home directory called <code>rfnoc</code> (any valid directory name will work)

* Give the prefix an alias of <code>rfnoc</code> ( <code>[-a alias]</code>, e.g. <code>–a rfnoc</code> ), which would be the name given to this path. This name will be used in further steps that use PyBOMBS. When creating the first prefix and omitting the alias, the prefix will be setup as the default.

* Use the <code>rfnoc</code> prefix recipe ( as opposed to a package recipe like <code>gqrx</code> ) to clone UHD, FPGA, GNU Radio, and gr-ettus sources into the <code>~/rfnoc</code> directory as well as compile and install all the software

'''NOTE:''' A user can specify how many cores are used by builds when using PyBOMBS. The default is set to 4. For example, this will set the number of cores used to 3:

$ pybombs config makewidth 3

The value will be written into a configuration file and then applied to subsequent PyBOMBS commands. This value can temporarily be overridden for a specific build by specifying the <code>--config makewidth=X</code> argument, where “<code>X</code>” is an integer number. If the user only has 4 cores it is recommend to use this argument in the pybombs command to limit the number of cores to <4 (e.g. 3) so that the computer stays responsive. Following are 2 examples, one using less cores and the other using more cores:

$ pybombs --config makewidth=3 prefix init ~/rfnoc -R rfnoc -a rfnoc
$ pybombs --config makewidth=7 prefix init ~/rfnoc -R rfnoc -a rfnoc

Then, it is necessary to setup the PyBOMBS environment, so that the system/terminal session will have the environmental variables pointing to this newly created prefix, which is done with the following commands:

$ cd ~/rfnoc
$ source ./setup_env.sh

Once the previous command is run, this terminal session will have access to the environmental variables that allow the complete use of the set of software that was just installed with PyBOMBS. If access to the software is needed in other terminals the same command must be run within them.

'''NOTE:''' Throughout the rest of this document the term <code>{USER_PREFIX}</code> will used at the beginning of different directories. For example, <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts</code> is a directory that contains useful scripts for compiling. The term <code>{USER_PREFIX}</code> is used to denote the folders that precede the <code>/src</code> directory. Examples of what <code>{USER_PREFIX}</code> could be: <code>/home/user/rfnoc</code> or <code>/home/user/myDevfolder/</code>. On many Linux environments using <code>~/</code> at the beginning of the target directory path is equivalent to the user’s home directory.( i.e <code>~/</code> is equal to <code>/home/user/</code>). So <code>{USER_PREFIX}</code> could also look like <code>~/rfnoc</code> or <code>~/myDevfolder/</code>.

===Create the development environment manually===
As an alternative to using PyBOMBS, manually installing and configuring the software is done by following the individual install notes for [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio], [https://files.ettus.com/manual/page_build_guide.html UHD] and [https://github.com/EttusResearch/gr-ettus gr-ettus] and by making sure they are reachable by linkers and compilers.

'''NOTE:''' The Application Note found [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux here] goes through the process of manually installing UHD and GNU Radio on Linux platforms.

To manually download the software, use these <code>git clone</code> commands, which will select the correct branches:

$ git clone --recursive -b rfnoc-devel https://github.com/EttusResearch/uhd.git
$ git clone --recursive -b maint https://github.com/gnuradio/gnuradio.git # master branch is also fine instead of maint
$ git clone -b master https://github.com/EttusResearch/gr-ettus.git
$ git clone -b rfnoc-devel https://github.com/EttusResearch/fpga.git

If UHD, GNU Radio and/or gr-ettus are already installed, it would be sufficient to checkout the branches mentioned and update them them (<code>git pull</code>). Thereafter, rebuild each of the repositories (rebuild order: UHD, GNU Radio, gr-ettus).

===Verify Environment===
Running the command “<code>uhd_config_info</code>” with the “<code>--version</code>” flag will verify that the installation has been completed successfully.

'''NOTE:''' The version string output from this command may differ, however it should be similar to the output below.

$ uhd_config_info --version
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-161- g83150fdd

4.0.0.rfnoc-devel-161-g83150fdd

===Testing the default FPGA image and building from existing blocks===

It is recommended to spend a moment looking at the Ettus Research default image, which is pre-built with a set of RFNoC blocks, as well as building a custom image with a unique set of pre-built RFNoC blocks. To get the default image(s), run the following command:

$ uhd_images_downloader

Ettus Research will be updating the default image(s) occasionally, and <code>uhd_images_downloader</code> can be run anytime after running <code>git pull</code> and re-installing to pull the most current images. Images are stored in the <code>{USER_PREFIX}/share/uhd/images</code> directory.

The following images have the corresponding RFNoC blocks (Computation Engines):

{| class="wikitable"
!Image Name
!Included Blocks
|-

|<code>usrp_x300_fpga_HG.bit</code>
<code>usrp_x300_fpga_XG.bit</code>

<code>usrp_x310_fpga_HG.bit</code>

<code>usrp_x310_fpga_XG.bit</code>
|<code>2x DDC, 2x DUC</code>
|-

|<code>usrp_x300_fpga_RFNOC_HG.bit</code>
<code>usrp_x300_fpga_RFNOC_XG.bit</code>
|<code>DUC, DDC (one channel), fosphor, window, fft, 2x AXI FIFOs</code>
|-

|<code>usrp_x310_fpga_RFNOC_HG.bit</code>
<code>usrp_x310_fpga_RFNOC_XG.bit</code>
|<code>DUC, DDC (one channel), fosphor, window, fft, 2x AXI FIFOs, Keep One in N, FIR, Siggen</code>
|-

|<code>usrp_e310_fpga.bit</code>
<code>usrp_e310_fpga_sg3.bit</code>
|<code>1x DDC, 1x DUC</code>
|-

|<code>usrp_e310_fpga_RFNOC.bit (sg1 version)</code>
<code>usrp_e310_fpga_RFNOC_sg3.bit</code>
|<code>fosphor, window, fft, 2x AXI FIFOs, FIR</code>
|-

|}

Instructions on flashing the image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

'''NOTE:''' FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device.

By following the steps above the following should now be available:
* UHD/RFNoC code downloaded and installed
* FPGA code available
* A valid RFNoC image on your X3xx or E3xx series device

====Inspect default images====
Run the following command, with a USRP connected to your PC, to verify current image on the USRP.

$ uhd_usrp_probe

If an RFNoC image was successfully loaded onto the USRP, there will be a lot of output text (RFNoC code is currently very verbose). The final lines of the output should be similar to the following for an USRP X310 ( e.g. <code>usrp_x310_fpga_HG</code> ):

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1

Final output for <code>usrp_x310_fpga_RFNOC_HG.bit</code> image:

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DUC_0
| | | * FFT_0
| | | * Window_0
| | | * FIR_0
| | | * SigGen_0
| | | * KeepOneInN_0
| | | * fosphor_0
| | | * FIFO_0
| | | * FIFO_1

'''NOTE:''' The actual names and number of blocks can differ. The list of blocks should start with the <code>DmaFIFO_x</code> and <code>Radio_x</code>, and then a couple more lines of block IDs should follow.

====Build custom image with pre-built RFNoC blocks====
Because of the growing number of RFNoC blocks, the user has the option to build an FPGA image with a set of pre-built RFNoC blocks of their choosing. The following steps describe the process for doing this and by so doing will also validate proper tool installation. Because compilation can take a couple of hours, it is recommended the user begin this process while continuing the rest of this guide.

'''NOTE:''' FPGA compilations can run in the background, however they are very resource intensive. If the user intents to use the same computer that is compiling to walk through the rest of this Application Note, it is recommended that the computer has plenty of resources.

The script to initiate a compile is called <code>uhd_image_builder.py</code>, and is located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts</code> directory. Run the help menu by typing:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py --help

A more detailed discussion of this script is given in an upcoming section. For now, compiling an FPGA image that has 2 RFNoC blocks (<code>window</code> and <code>fft</code>) and some <code>FIFOs</code>, is done by running the script with the following arguments.

Example for an X310 USRP:

$ ./uhd_image_builder.py window fft -d x310 -t X310_RFNOC_HG -m 5 --fill-with-fifos

Example for an E310 USRP with Speed Grade 3 (sg3) FPGA:

$ ./uhd_image_builder.py window fft -d e310 -t E310_RFNOC_sg3 -m 5 --fill-with-fifos

At the end of a successful compilation process, write the new image to a USRP. If the image was compiled for a USRP X310, the following command will load the new image. Update the <code>{IP_Address}</code> of the USRP and <code>{USER_PREFIX}</code> to the appropriate values for your configuration before running the command.

$ uhd_image_loader --args “type=x300,addr={IP_ADDRESS}” --fpga-path {USER_PREFIX}/src/uhd-fpga/usrp3/top/x300/build/usrp_x310_fpga_RFNOC_HG.bit

'''NOTE:''' FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device. Additional instructions on flashing a custom image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

After the image has been successfully written to the USRP, power-cycle it and run the “<code>uhd_usrp_probe</code>” utility to view the newly compiled blocks.

$ uhd_usrp_probe

The final lines of output for the image built for the X310 is as follows:

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * Window_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

===Getting started with UHD + RFNoC===
The following new examples included within the <code>rfnoc-devel</code> branch of UHD, are a good reference on how to use RFNoC from UHD.

The following example is based off of <code>rx_samples_to_file.cpp</code>. The example can be configured to place an RFNoC block in between the radio and host.

rfnoc_rx_to_file.cpp

This next example chains a null source to another block and streams the data to the host.

rfnoc_nullsource_ce_rx.cpp

These examples demonstrate the core features and flexibility of RFNoC.

For more information on UHD and UHD development please refer to the [https://kb.ettus.com/UHD UHD Software Resource page], [https://kb.ettus.com/Getting_Started_with_UHD_and_C%2B%2B Getting Started with UHD and C++ Application Note] or directly to the [http://files.ettus.com/manual/ UHD user manual].

===Getting started with GNU Radio + RFNoC===
A good way of getting started with RFNoC in a more visual way is to use GNU Radio. The <code>gr-ettus</code> out-of-tree module (OOT) allows a user to use RFNoC blocks in their local GNU Radio / GNU Radio Companion (GRC) installation. This GNU Radio OOT contains blocks that allow you to configure your FPGA through GRC.

'''NOTE:''' As blocks in the <code>gr-ettus</code> OOT mature, they will be upstreamed to <code>gr-uhd</code>. Also, <code>gr-ettus</code> is a container used by Ettus Research to disseminate experimental or under-development features for <code>gr-uhd</code>. It is not a replacement for <code>gr-uhd</code> (in fact, the latter is a requirement for <code>gr-ettus</code>).

Examples can be run from <code>gr-ettus/examples/rfnoc</code>, provided that the appropriate RFNoC blocks are compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs with RFNoC blocks:

* You always need a <code>Device3</code> object in your flow graph (it does not get connected, see screenshot below).
* You should have at least two RFNoC blocks connected together, going <code>GNU Radio Block</code> -> <code>RFNoC Block</code> -> <code>GNU Radio Block</code> is not recommended (it will work, but with suboptimal performance).

The GNU Radio flowgraph <code>rfnoc_ddc.grc</code> is an example that can be run using the default RFNoC image. Below are screenshots of the flowgraph and what it produces.

[[File:rfnoc gsg an 1.png|center|800px|]]

'''NOTE:''' Copy Block: In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The “copy” block depicted in the screenshot above serves the function as a stream splitter . It’s main purpose, when “enabled”, is to copy the samples it is getting at its input and putting then into the output, but here it is also serving as a boundary between a RFNoC-domain and a GNURadio-domain. In the flowgraph above. after this boundary is passed, the data stream can easily be split into the two sinks to have them run simultaneously (standard GNU Radio functionality). It is possible to connect the GNU Radio blocks directly to RFNoC blocks without a “copy” block, but only one would work at a time (the other ones would have to be disabled). Another way to split data streams from the RFNoC- domain is to use the ”RFNoC: split stream” block, which would split the streams in the RFNoC domain, but this is not very useful here as we are, in any case, moving into the GNURadio-domain.

[[File:rfnoc gsg an 2.png|center|800px|]]

For more information on GNURadio development please refer to the [http://gnuradio.org/doc/doxygen/ GNURadio user's manual and API].

==Starting a custom RFNoC block using RFNoC Modtool==
The figure below shows the basic structure of the RFNoC Stack. Corresponding code is needed in each of the three sections in order to build a custom RFNoC block with GNU Radio integration. A tool called RFNoC Modtool was created in order to minimize the effort needed to implement a new RFNoC block. RFNoC Modtool creates a custom GNU Radio OOT module with the basic structure and the necessary files for each of these sections. RFNoC Modtool is currently a part of the GNU Radio OOT module <code>gr-ettus</code>.

[[File:rfnoc gsg an 3.png|center|800px|]]

===RFNoC Modtool Utilization===
'''NOTE:''' Console outputs may vary depending on the version of UHD the user is running. However, functionality should be the same or similar.

Because the RFNoC Modtool has similar functionality to the <code>gr_modtool</code> [ [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules gr_modtool] ] provided by GNU Radio, those that have worked with <code>gr_modtool</code> in the past will find the RFNoC Modtool familiar.

To check the usage of the tool, run the following:

$ rfnocmodtool help
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

Usage:
rfnocmodtool <command> [options] -- Run <command> with the given options.
rfnocmodtool help -- Show a list of commands.
rfnocmodtool help <command> -- Shows the help for a given command.

List of possible commands:

Name Aliases Description
=====================================================================
disable dis Disable block (comments out CMake entries for files)
info getinfo,inf Return information about a given module
remove rm,del Remove block (delete files and remove Makefile entries)
makexml mx Make XML file for GRC block bindings
add insert Add block to the out-of-tree module.
newmod nm,create Create a new out-of-tree module
rename mv Rename a block in the out-of-tree module.

===Creating an RFNoC OOT Module===

To start generating an RFNoC OOT module navigate to the source location ( i.e. <code>cd ~/{USER_PREFIX}/src</code> ) and type:
$ rfnocmodtool newmod [NAME OF THE MODULE]

Where <code>[NAME OF THE MODULE]</code> is a name the user gives the new module. In the following, a module is created with the name “<code>tutorial</code>”. If the user does not write the name of the module following the <code>newmod</code> command the tool will ask for it interactively. Running this command will create a folder containing the basic folders that you may need for a functional module.

$ rfnocmodtool newmod tutorial
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

Creating out-of-tree module in ./rfnoc-tutorial... Done.
Use 'rfnocmodtool add' to add a new block to this currently empty module.

To see what files and directories were created run:

$ ls rfnoc-tutorial/
apps cmake CMakeLists.txt docs examples grc include lib MANIFEST.md python README.md rfnoc swig

In contrast with <code>gr_modtool</code>, this includes a folder called <code>rfnoc</code>, which is where the UHD/FPGA files are located.

===Adding custom blocks to OOT Module===
In order to add blocks to a module, navigate to the folder just created and use the <code>add</code> command of <code>rfnocmodtool</code>. Continuing with the example above, run the following:

$ cd rfnoc-tutorial
$ rfnocmodtool add [NAME OF THE BLOCK]

For demonstrative purposes, a block named <code>gain</code> will be created. The <code>gain</code> block will multiply samples that pass through it by a constant. As before, if the name is not given, the tool will ask the user for the name. There are several arguments that can be passed to the tool, but running the tool without any of these arguments will give the following interactive parsing output:

$ rfnocmodtool add gain
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_4.0.0.rfnoc-devel-162-g335a1317

RFNoC module name identified: tutorial
Block/code identifier: gain
Enter valid argument list, including default arguments:
Add Python QA code? [Y/n] N
Add C++ QA code? [y/N] N
Block NoC ID (Hexadecimal): 1111222233334444
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] N
Skip Block interface files Generation? [GRC block ctrl files] [y/N] N

Hitting <code>enter</code> on each one of the options will take the default values.

The following is a description of the valid argument list items:

* '''Add Python QA code:''' Not used.

* '''Add C++ QA code:''' Not used.

* '''NoC ID:''' This ID is a Hexadecimal number which serves as identification between the hardware part and the software part of the design. It can be as long as 16 0-9 A-F digits. If a NoC ID is not provided, it will be set to a random number.

* '''Block Controllers Generation:''' The block controllers are the C++ control that the user can apply to the UHD-part of the design. In these files, the user can add more control over this layer of the design. Depending on the complexity of the block it may be possible to add all necessary control using NoCScript (more details on NoCScript can be found in the section labeled UHD Integration). In this case the cpp/hpp block control files generation are not needed. Default is to generate as their existence will be ignored if not edited.

* '''Block Interface:''' Add more design specific functionality to the design at the GNU Radio interface by generating these block-interface files and adding necessary logic. Depending on the complexity of the block it may be possible to add all necessary control using NoC-Script. In this case the block-interface files are not needed. Default is to generate as their existence will be ignored if not edited.

'''NOTE:''' If the user does not intend to use the block controllers or is not sure if they are needed, the presence of them in the design will do no harm. It is recommended to add them. This leaves the possibility to add more functions inside them in a future stage of development.

After finishing the parsing, the following files will be generated/edited:

Adding file 'lib/gain_impl.h'...
Adding file 'lib/gain_impl.cc'...
Adding file 'include/tutorial/gain.h'...
Adding file 'include/tutorial/gain_block_ctrl.hpp'...
Adding file 'lib/gain_block_ctrl_impl.cpp'...
Editing swig/tutorial_swig.i...
Adding file 'python/qa_gain.py'...
Editing python/CMakeLists.txt...
Adding file 'grc/tutorial_gain.xml'...
Adding file 'rfnoc/blocks/gain.xml'...
Adding file 'rfnoc/fpga-src/noc_block_gain.v'...
rfnoc/testbenches/noc_block_gain_tb folder created
Adding file 'rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/CMakeLists.txt'...

==Creating FPGA portion of custom RFNoC Block==
===RFNoC FPGA User Interface (API)===
RFNoC blocks or Computation Engines (CEs) in the FPGA use a NoC Shell instance to interface with the rest of RFNoC. NoC Shell implements RFNoC's core functionality: packet muxing and demuxing, flow control, and the settings register bus (i.e. write/read control/status registers). The NoC Shell has an interface to the RFNoC AXI stream crossbar and a user interface. NoC Shell AXI stream interfaces expect CHDR packets with a proper header. See the manual for information on [https://files.ettus.com/manual/page_rtp.html CHDR and SID].

'''NOTE:''' AXI Stream is an ARM AMBA standard interface. Xilinx has an [http://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf AXI Reference Guide] with more details on this standard.

[[File:rfnoc gsg an 4.png|center|800px|]]

Many designs will want to use an AXI Stream interface with only sample data. However, as stated earlier, the NoC Shell block expects CHDR packets. To ease interfacing user code, the AXI Wrapper block provides the necessary logic to strip and insert the CHDR header, effectively converting packetized sample data into streaming sample data and vice versa. The example RFNoC blocks <code>noc_block_fft.v</code> and <code>noc_block_fir.v</code> show how AXI Wrapper is used to implement existing Xilinx AXI Stream based IP within a computation engine.

'''NOTE:''' AXI Wrapper also supports AXI Stream buses for configuration. These buses are driven via the setting register bus and do not have back pressure. They also consume two user register addresses per bus.

The primary user interface consists of four AXI stream interfaces ( <code>tready, tvalid, tlast, tdata</code> ) and a settings register bus ( 8-bit, valid user register addresses: <code>128-255</code> ).

{|
|
AXI Stream signals:
* '''m_axis_data_tdata:''' Input sample data packets
** Data coming from host or another CE
* '''s_axis_data_tdata:''' Output sample data packets
** Data going to another CE or host
* '''m_axis_data_tready:''' Input signal to CE
** Used to notify CE that downstream CE is ready for data
* '''s_axis_data_tready:''' Output signal to CE
** Used to notify upstream CE that CE is ready for data
* '''m_axis_data_tvalid:''' Input signal to CE
** Used to indicate upstream CE has valid data
* '''s_axis_data_tvalid:''' Output signal to CE
** Used to indicate to downstream CE that CE has valid data
* '''m_axis_data_tlast:''' Input signal to CE
** Used to delimit packets from upstream CE
* '''s_axis_data_tlast:''' Output signal to CE
** Used to delimit packets to downstream CE
| style="vertical-align:top" |[[File:rfnoc gsg an 5.png|right|500px|]]
|-
|}

[[File:rfnoc gsg an 6.png|center|800px|]]

{|
|
Settings Bus signals:
* '''set_stb:''' Assert to write '''set_data''' to register at '''set_addr'''ess
* '''set_addr:''' Register address to set
* '''set_data:''' Data to set
* '''rb_data:''' Data to read back
* '''rb_strobe:''' Assert to read '''rb_data''' from register at '''set_addr'''ess

| style="vertical-align:top" |[[File:rfnoc gsg an 7.png|right|500px|]]
|-
|}
For the <code>gain</code> example block the following architecture is desired:

[[File:rfnoc gsg an 8.png|center|800px|]]

Open the file <code>rfnoc-tutorial/rfnoc/fpga-src/noc_block_gain.v</code> that contains the RFNoC block skeleton code that was created when the <code>$ rfnocmodtool add gain</code> command was run and modify the following sections.

For the setting register that will hold the constant value as well as the read back register:

'''localparam [7:0] SR_GAIN = SR_USER_REG_BASE;'''
localparam [7:0] SR_TEST_REG_1 = SR_USER_REG_BASE + 8'd1;

'''wire [15:0] gain;'''
'''setting_reg #('''
'''.my_addr(SR_GAIN), .awidth(8), .width(16))'''
'''sr_gain ('''
'''.clk(ce_clk), .rst(ce_rst),'''
'''.strobe(set_stb), .addr(set_addr), .in(set_data), .out(gain), .changed());'''

always @(posedge ce_clk) begin
case(rb_addr)
'''8'd0 : rb_data <= {48'd0, gain};'''
8'd1 : rb_data <= {32'd0, test_reg_1};
default : rb_data <= 64'h0BADC0DE0BADC0DE;
endcase
end

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

'''wire [15:0] i = m_axis_data_tdata[31:16];'''
'''wire [15:0] q = m_axis_data_tdata[15:0];'''

'''wire [31:0] i_mult_gain = i*gain;'''
'''wire [31:0] q_mult_gain = q*gain;'''

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

===Creating and running HDL testbenches===
In order to make the coding iteration process more efficient, it is recommended to create testbenches for all RFNoC blocks before compiling them into the FPGA image. This allows for flaw and/or bug detection early in the design. RFNoC Modtool provides the structure and files ( e.g. <code>noc_block_{USER_BLOCK_NAME}_tb</code> ) for the testbenches of each of the OOT blocks that are added with the <code>$ rfnocmodtool add</code> command.

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

[[File:rfnoc gsg an 9.png|center|800px|]]

From the [[Getting Started with RFNoC Development#Adding_custom_blocks_to_OOT_Module|Adding custom blocks to OOT Module section]] where the <code>gain</code> block was initially created, the last files generated were:

rfnoc/testbenches/noc_block_gain_tb folder created
Adding file 'rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_gain_tb/CMakeLists.txt'...

The <code>noc_block_gain_tb</code> is a folder generated to contain all the files related to the test bench of the <code>gain</code> block. Each time a new OOT block is created, a new folder will be generated as well.

Inside of this folder are the following three files:

* <code>CMakeLists.txt:</code> this is an empty file used, so far, only to increase the scope of the compilers.
* <code>noc_block_gain_tb.sv:</code> this is a ''System Verilog'' file, in which user custom tests are to be located. This is the '''only''' file that needs to be modified.
* <code>Makefile:</code> This file determines the directives that run the simulation.

Open the file <code>rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv</code> and modify the following lines:

initial begin : tb_main
string s;
logic [31:0] random_word;
logic [63:0] readback;
'''logic [15:0] gain;'''

`TEST_CASE_START("Write / readback user registers");
random_word = $random();
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, random_word[15:0]);
tb_streamer.read_user_reg(sid_noc_block_gain, 0, readback);
$sformat(s, "User register 0 incorrect readback! Expected: %0d, Actual %0d", readback[15:0], random_word[15:0]);
`ASSERT_ERROR(readback[15:0] == random_word[15:0], s);'''

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

The next step is to run <code>cmake</code>. If PyBOMBS was used to create the development sandbox, <code>cmake</code> will automatically detect the location of the <code>fpga</code> repository. If PyBOMBS was not used, the user must provide the location of where the <code>fpga</code> repository is installed.

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

$ cmake [-DUHD_FPGA_DIR=/PATH/TO/FPGA/REPOSITORY] ../

Final output from the <code>$ cmake ../</code> command:

-- Configuring done
-- Generating done
-- Build files have been written to: /home/widow/rfnoc/src/rfnoc-tutorial/build

The following command will modify the necessary files and set the correct path to the simulation tools. From now on, every time a new block is added, this command will be run automatically. Remember, only run the following command once for each OOT module (not RFNoC block, but OOT module) created:

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

The gain block testbench can be run by running the following command:

$ make noc_block_gain_tb

The simulation will start. Final output should look like this:

========================================================
TESTBENCH STARTED: noc_block_gain
========================================================
[TEST CASE 1] (t=000000000) BEGIN: Wait for Reset...
[TEST CASE 1] (t=000001002) DONE... Passed
[TEST CASE 2] (t=000001002) BEGIN: Check NoC ID...
Read GAIN NOC ID: 1111222233334444
[TEST CASE 2] (t=000001238) DONE... Passed
[TEST CASE 3] (t=000001238) BEGIN: Connect RFNoC blocks...
Connecting noc_block_tb (SID: 1:0) to noc_block_gain (SID: 0:0)
Connecting noc_block_gain (SID: 0:0) to noc_block_tb (SID: 1:0)
[TEST CASE 3] (t=000005457) DONE... Passed
[TEST CASE 4] (t=000005457) BEGIN: Write / readback user registers...
[TEST CASE 4] (t=000006888) DONE... Passed
[TEST CASE 5] (t=000006888) BEGIN: Test sequence...
[TEST CASE 5] (t=000007633) DONE... Passed
========================================================
'''TESTBENCH FINISHED: noc_block_gain'''
''' - Time elapsed: 7700 ns'''
''' - Tests Expected: 5'''
''' - Tests Run: 5'''
''' - Tests Passed: 5'''
'''Result: PASSED'''
========================================================
$finish called at time : 7700 ns : File "/home/widow/rfnoc/src/rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/noc_block_gain_tb.sv" Line 10
INFO: [USF-XSim-96] XSim completed. Design snapshot 'noc_block_gain_tb_behav' loaded.
INFO: [USF-XSim-97] XSim simulation ran for 1000000000us
launch_simulation: Time (s): cpu = 00:00:10 ; elapsed = 00:00:12 . Memory (MB): peak = 966.387 ; gain = 54.848 ; free physical = 3080 ; free virtual = 29888
# if [string equal $vivado_mode "batch"] {
# puts "BUILDER: Closing project"
# close_project
# } else {
# puts "BUILDER: In GUI mode. Leaving project open."
# }
BUILDER: Closing project
****** Webtalk v2015.4 (64-bit)
**** SW Build 1412921 on Wed Nov 18 09:44:32 MST 2015
**** IP Build 1412160 on Tue Nov 17 13:47:24 MST 2015
** Copyright 1986-2015 Xilinx, Inc. All Rights Reserved.

source /home/widow/rfnoc/src/rfnoc-tutorial/rfnoc/testbenches/noc_block_gain_tb/xsim_proj/xsim_proj.hw/webtalk/labtool_webtalk.tcl -notrace
INFO: [Common 17-206] Exiting Webtalk at Tue Jan 10 23:26:20 2017...
INFO: [Common 17-206] Exiting Vivado at Tue Jan 10 23:26:22 2017...
Built target noc_block_gain_tb

With every custom block created, a <code>make</code> directive will be available to run the simulation from the <code>build</code> directory.

===Building the FPGA image with a custom user block===
In this section steps are given on how to initiate an FPGA build while incorporating the user’s custom RFNoC block. The first sections give general information on building RFNoC images. The remaining two sections show how to initiate FPGA builds using a command line interface and using a graphical interface (coming out soon), respectively.

====Discussion on number of blocks in an FPGA image====
There is a maximum number of blocks that can be added for each device. The maximum amount of computation engines (CEs/RFNoC blocks) that each device can use is 16, but the amount of custom blocks that can be added depends on the device.

If using a device from the X3xx series, from the 16 CEs, there are 6 that will be always added and are not subject to direct customization: 1 CE for the AXI bus, 1 CE for the Ethernet Interface, 2 Radios and 2 Dma FIFOS. Because of this, the application will only allow a number of 10 custom blocks on the X3xx series.

If using a device from the E3xx series, 2 CE engines are always added and are not subject to direct customization: 1 CE for the AXI bus and 1 Radio. This would virtually allow 14 slots for custom blocks. However, given the size of the FPGA on the E3xx series of devices, the application only allows a number of 6 custom blocks.

'''NOTE:''' Blocks with higher resource utilization may fill up the FPGA and force the user to include less blocks.

Verify the current maximum values by running the <code>uhd_images_builder.py</code> utility from the scripts directory.

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ uhd_image_builder.py --help

====Discussion on FPGA image targets====
RFNoC target names follow the pattern <code>{DEVICE}_RFNOC_{BUILD_TYPE}</code> with the following build types:

* <code>HG:</code> 1GigE on SFP+ Port0, 10Gig on SFP+ Port
* <code>XG:</code> 10GigE on both SFP+ ports
* <code>HLS:</code> Vivado High Level Synthesis enabled
* <code>sgX:</code> Speed grade for E300 devices (1 or 3)

Some examples are:
* <code>X310_RFNOC_HG</code>
* <code>X300_RFNOC_HG</code>
* <code>X310_RFNOC_XG</code>
* <code>X300_RFNOC_XG</code>
* <code>X310_RFNOC_HLS_HG</code>
* <code>X300_RFNOC_HLS_HG</code>
* <code>E310_RFNOC</code> (this is for the speed grade 1 FPGA version of E310, append <code>_sg3</code> for speed grade 3)

'''NOTE:''' E310, E312 and E313 all have the same FPGA hardware and therefore will use the <code>E310_RFNOC_{BUILD_TYPE}</code> target. USRP E3xx devices have either <code>sg1</code> or <code>sg3</code> hardware, please visit [http://files.ettus.com/e3xx_images/README here] to find out how to differentiate.

Additional information about the build targets can be found at the build instructions for USRP3, found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here].

====Image building using the command line====
The script <code>uhd_image_builder.py</code> is used to generate the NoC block instantiation file and build the FPGA image. Run the help menu by typing:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py --help

usage: uhd_image_builder.py [-h] [-I INCLUDE_DIR [INCLUDE_DIR ...]]
[-m MAX_NUM_BLOCKS] [--fill-with-fifos]
[-o OUTFILE] [-d DEVICE] [-t TARGET] [-g] [-c]
[blocks [blocks ...]]

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

optional arguments:
-h, --help show this help message and exit
-I INCLUDE_DIR [INCLUDE_DIR ...], --include-dir INCLUDE_DIR [INCLUDE_DIR ...]
Path directory of the RFNoC Out-of-Tree module
-m MAX_NUM_BLOCKS, --max-num-blocks MAX_NUM_BLOCKS
Maximum number of blocks (Max. Allowed for x310|x300:
10, for e300: 6)
--fill-with-fifos If the number of blocks provided was smaller than the
max number, fill the rest with FIFOs
-o OUTFILE, --outfile OUTFILE
Output /path/filename - By running this directive, you
won't build your IP
-d DEVICE, --device DEVICE
Device to be programmed [x300, x310, e310]
-t TARGET, --target TARGET
Build target - image type [X3X0_RFNOC_HG,
X3X0_RFNOC_XG, E310_RFNOC_sg3...]
-g, --GUI Open Vivado GUI during the FPGA building process
-c, --clean-all Cleans the IP before a new build

Here are details on the usage of the script which is followed by an example:

'''Blocks:''' The first arguments are the names of RFNoC blocks that the user wants to have compiled into the new image which are separated by a space. They can be custom blocks from the user’s OOT module or from the ones that are provided from Ettus, or a combination. Blocks provided by Ettus Research are listed (among other sources necessary for the FPGA build) in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/lib/rfnoc/Makefile.srcs</code> file.

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

However, as all the RFNoC blocks have the same <code>noc_block_</code> prefix, for simplicity this prefix is omitted when listing the blocks in the <code>uhd_image_builder.py</code> utility. As an example of the incorrect and correct way of adding blocks, consider the following examples when adding the <code>noc_block_null_source_sink</code> and <code>noc_block_siggen</code> blocks:

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

'''NOTE:''' Blocks generated by the RFNoC Modtool follow the same naming convention.

There is an increasing list of pre-built blocks. Here is a sample:

* <code>axi_fifo_loopback</code>
* <code>axi_dma_fifo</code>
* <code>fir_filter</code>
* <code>fft</code>
* <code>null_source_sink</code>
* <code>schmidl_cox</code>
* <code>packet_resizer</code>
* <code>split_stream</code>
* <code>vector_iir</code>
* <code>addsub</code>
* <code>window</code>
* <code>keep_one_in_n</code>
* <code>pfb</code>
* <code>export_io</code>
* <code>conv_encoder_qpsk</code>
* <code>siggen</code>
* <code>logpwr</code>
* <code>fosphor</code>
* <code>moving_avg</code>
* <code>ddc</code>
* <code>duc</code>

RFNoC related blocks generally reside in <code>fpga/usrp3/lib/rfnoc/</code>.

{| class="wikitable" style="margin:auto;"

!Block
!Filename
!Description
|-

|FIFO
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_axi_fifo_loopback.v noc_block_axi_fifo_loopback.v]
|Simple FIFO loopback / passthrough block.
|-

|FFT
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_fft.v noc_block_fft.v]
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_fir_filter.v noc_block_fir_filter.v]
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_window.v noc_block_window.v]
|Windowing block for use with FFT block.
|-

|Vector IIR
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_vector_iir.v noc_block_vector_iir.v]
|Single pole IIR with configurable coefficients that filters data along vectors (i.e. parallel streams of samples). Useful with FFT output.
|-

|Keep One in N
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_keep_one_in_n.v noc_block_keep_one_in_n.v]
|Keeps one packet every N packets.
|-

|AddSub
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_addsub.v noc_block_addsub.v]
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_null_source_sink.v noc_block_null_source_sink.v]
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_packet_resizer.v noc_block_packet_resizer.v]
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|[https://github.com/EttusResearch/fpga/blob/maint/usrp3/lib/rfnoc/noc_block_split_stream.v noc_block_split_stream.v]
|Replicates an input stream to a configurable number of output streams.
|-

|}

'''NOTE:''' There is a restriction on the amount of blocks that can added into the FPGA image, see the section in this Application Note labeled [[Getting_Started_with_RFNoC_Development#Discussion_on_number_of_blocks_in_an_FPGA_image|Discussion on number of blocks in an FPGA image]] for more information.

<code>-I INCLUDE_DIR:</code> The <code>-I</code> directive provides the path to the users <code>rfnoc/fpga-src</code> directory which contains the custom blocks. This path is needed by the Xilinx Vivado tool. Inside the <code>fpga-src</code> directory there is a file called <code>Makefile.srcs</code> that contains the path of the OOT module and a list of all the custom OOT blocks. This is an auto generated file, which is amended every time a new block is added to the OOT module. Manually modifying this file is not recommended. If there are multiple OOT modules with various custom blocks that reside in different directories the way to include them all is by separating the different paths by a space (e.g. <code>-I /first/OOT/path/ /second/OOT/path/</code>) '''IMPORTANT:''' Please be sure to terminate the path of your OOT with the "/" character. Otherwise the path might not be recognized.

<code>-d DEVICE:</code> The <code>-d</code> directive directs the script on which USRP device the build is for. If no <code>–d</code> is included the default is <code>–d x310</code>. Generation-3 USRPs and above all support RFNoC.

<code>-t TARGET:</code> The <code>–t</code> directive directs the script on which type of image to build for the chosen device. With each USRP device there are several build options to choose from. Detailed information about the build targets can be found at the build instructions for USRP3, found [http://files.ettus.com/manual/md_usrp3_build_instructions.html here]. If <code>-t</code> is not included, a default target will be chosen for the given device. For example, the default <code>X310_RFNOC_HG</code> target builds for the <code>–d x310</code> device. More details on targets can be found in the section of this Application Note labeled [[Getting Started with RFNoC Development#Discussion_on_FPGA_image_targets|Discussion on FPGA image targets]].

<code>-m MAX_NUM_BLOCKS:</code> The <code>–m</code> directive specifies the max number of RFNoC blocks to build on the FPGA image. An RFNoC image does not need to fill all available slots with RFNoC blocks.

<code>--fill-with-fifos:</code> The <code>--fill-with-fifos</code> directive will fill the empty RFNoC block slots with FIFOS. As an example, if a user indicates three RFNoC blocks by name and also specifies <code>–m 5</code> then the other two slots will be filed with FIFOs.

<code>-o OUTFILE:</code> With the <code>-o</code> directive, the RFNoC blocks instantiation file is generated and saved at the desired path with the given name for the user to inspect. The FPGA image will NOT build if this directive is provided. The purpose of the <code>uhd_image_builder.py</code> script is to auto generate an instantiation file and populate the source files needed for the Xilinx Vivado tool to build the FPGA image, however, it may be desirable to only see the effect of adding a custom OOT module in the <code>fpga/</code> directory, or for inspecting the instantiation file. When the directive is not provided the <code>rfnoc_ce_auto_inst_x3x0.v</code> file is overwritten and the FPGA image build process will start automatically (standard use).

<code>-g, --GUI:</code> Open Vivado GUI during the FPGA building process

<code>-c, --clean-all:</code> Cleans the IP before a new build

Here is how to create an X310 FPGA image incorporating the <code>gain</code> block that was created earlier in this Application Note:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts
$ ./uhd_image_builder.py gain ddc fft -I {USER_PREFIX}/src/rfnoc-tutorial/rfnoc/fpga-src/ -d x310 -t X310_RFNOC_HG -m 6 --fill-with-fifos

At the end of a successful compilation process, write the new image to a USRP. The following command will load the new image. Update the <code>{IP_Address}</code> of the USRP and <code>{USER_PREFIX}</code> to the appropriate values for your configuration before running the command.

$ uhd_image_loader --args “type=x300,addr={IP_ADDRESS}” --fpga-path {USER_PREFIX}/src/uhd-fpga/usrp3/top/x300/build/usrp_x310_fpga_RFNOC_HG.bit

'''NOTE:'''
* The FPGA image building process may take over an hour.

* FPGA images are specific to the USRP device NOT the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device. Additional instructions on flashing a custom image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series.

* [Environment setup] - The <code>uhd_image_builder.py</code> script will also set up the Xilinx Vivado environment by automatically running the <code>setupenv.sh</code> script located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{device}</code> directory. The <code>setupenv.sh</code> script assumes that Xilinx Vivado is installed in the default location of <code>/opt/Xilinx/Vivado</code>. If the installation is in a different directory the <code>setupenv_base.sh</code> script will need to be modified. The script is located at: <code>{USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts/setupenv_base.sh</code>

Besides the custom <code>gain</code> block, a <code>DDC</code> and <code>FFT</code> block are also being added along with three <code>FIFOs</code>. The <code>DDC</code>, <code>FFT</code> and <code>FIFO</code> blocks are already in the script's path and therefore do not need their path specified (they ship with the Ettus Research FPGA code). The reason three FIFOs are added is because the max number of blocks was specified to be 6 ( <code>-m 6</code> ) and since only 3 blocks were specifically named the other three slots are filled with FIFOs.

[[File:rfnoc gsg an 10.png|center|800px|]]

'''NOTE:''' Instructions on flashing the image to a device can be found [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs here] for X3xx series and [http://files.ettus.com/manual/page_usrp_e3x0.html#e3x0_load_fpga_imgs here] for E3xx series. FPGA images are specific to the USRP device '''NOT''' the USRP series. For example, a USRP X300 FPGA image will '''NOT''' work on a USRP X310 and vice versa. Loading an image that does not correspond to a USRP device will likely brick the device.

Once the newly compiled image is loaded onto a USRP X3xx running the following command will show what RFNoC blocks are available on the FPGA:

$ uhd_usrp_probe

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * '''Block_0'''
| | | * DDC_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

'''NOTE:''' The reason the custom block is called <code>Block_0</code> and not <code>gain_0</code> is because there is still host side software/files that need updated in order for this block to populate it’s proper name. A following section (UHD Integration) will step through the process of updating those host side files.

====Using a graphical interface====
A graphical user interface for FPGA generation and building is shipped along with the <code>uhd_image_builder.py</code> script. This intuitive application aids in setting up a custom FPGA build.

This utility is located in the same <code>scripts</code> directory as <code>uhd_image_builder.py</code>.

To run it, enter the following commands:

$ cd {USER_PREFIX}/src/uhd-fpga/usrp3/tools/scripts/
$ ./uhd_image_builder_gui

The application will then be launched:

[[File:rfnoc gsg an 11.png|center|800px|]]

'''1. Select build target:''' In this panel the available build targets are listed. This list may vary depending on which branch of the FPGA repository this user is using. Only RFNoC targets are listed. The build type descriptions are:

* <code>HG:</code> 1GigE on SFP+ Port0, 10Gig on SFP+ Port1
* <code>XG:</code> 10GigE on both SFP+ ports
* <code>HLS:</code> Vivado High Level Synthesis enabled
* <code>sgX:</code> Speed grade for E300 devices (1 or 3)

'''2. List of blocks available:''' In this panel the available blocks are listed that can be included into a custom design. This list separates the RFNoC blocks provided by Ettus Research and the OOT modules and corresponding blocks that the user adds. Given the hardware differences between the X3xx and E3xx devices, this list will dynamically change when a different device is selected from the panel on the left. This implies that it is necessary to add the OOT modules for each device independently. This is accomplished by using the <code>Add OOT Blocks</code> feature of the application, details of which are explained at #7 (<code>Add OOT Blocks</code>).

'''3. Blocks in current design:''' This panel will be populated by adding elements from the available blocks. All the blocks listed in here will be compiled into the FPGA custom image. There is a maximum number of blocks that can be added for each device. See the section in this App Note labeled Discussion on number of blocks in an FPGA image for more information.

'''4. Add button (>>):''' Manually add the blocks from the central panel into your design.

'''5. Remove button (<<):''' Remove blocks from the current design (far-left panel)

'''6. Fill with FIFOs:''' By checking this box, the design will fill any available/unspecified block slots with FIFOs. The number of FIFO blocks that will be instantiated is based on the rules of amount of blocks explained at #3. When less than the max amount of blocks are needed for certain implementation, many users choose to fill their design with FIFO blocks.

'''7. Open Vivado GUI:''' Open Vivado GUI during the FPGA building process. This allows the user to save a Vivado project with all IP and work within the Vivado GUI for development.

'''8. Clean IP:''' Cleans the IP before a new build (recompiles all IP).

'''9. Add OOT blocks:''' Manually add RFNoC Modtool-generated OOT modules by pointing the application to the <code>Makefile.srcs</code> file, which is located in the <code>{USER_PREFIX}/src/{USER-OOT-moddir}/rfnoc/fpga-srcs/</code> directory. After adding this file, blocks will appear under “<code>OOT blocks for XXXX devices</code>”

'''10. Import from GRC:''' If the user has a GNU Radio flowgraph with RFNoC blocks already in it, this application can read what RFNoC blocks are in the flowgraph and populate the <code>Blocks in current design</code> section of the application with the necessary RFNoC blocks. '''NOTE:''' All RFNoC blocks pulled from a <code>.grc</code> file must be in the of <code>List of blocks available</code> before beginning the build.

'''11. Show Instantiation File:''' The application auto-generates the instantiation file that is going to be used by Vivado to build the FPGA image. This instantiation file can be viewed and edited before starting the build by clicking this button.

'''12. Generate .bit file:''' Start the build by clicking this button.

'''NOTE:''' See the latter end of the previous section for additional information on what to expect once the compile has started as well as final output.

==Creating Software/Host portion of custom RFNoC Block==
Now that the FPGA portion is complete the next step is to add software integration to UHD and GNU Radio as depicted in the RFNoC Stack below.

[[File:rfnoc gsg an 12.png|center|800px|]]

===UHD integration===
Despite the data processing happening on the FPGA, the host software still has a lot of responsibilities in order for an RFNoC application to function. For example, it needs to know which settings registers are available within an RFNoC block, or what kind of input and output a block has. All of this information goes into the <code>Block Declaration</code>, which is an XML file that is readable by UHD. Often, some simple logic needs to be embedded in the XML file, which we can do by using a simple scripting language called Noc-Script. Changes to the block declaration file are immediately imported into UHD every time an application is executed, and therefore, no software development toolchain needs to be set up.

The list of things declared by the block declaration file includes:

* Block name and Noc-ID
* Registers
* Inputs and outputs (including types)

In some cases, additional C++ code is required to properly control a block from software. In this case, a <code>Block Controller</code> file is required as well as the declaration file. In most cases, the default block controller provided by UHD is sufficient, so no C++ code needs to be written. Writing custom block controllers requires more effort, and means having to set up a programming toolchain. A common reason to write custom C++ block controllers is if setting a register requires a lot of computation, which is not feasible to do within a block declaration file (e.g., using Noc-Script).

Skeleton code for both the block declaration and the block controller (if required) can be generated through RFNoC Modtool.

Because the <code>gain</code> block does not require anything other than simply reading and writing to a single register the default block controller will suffice for this example. However, we will need to add information about the register.

Open the <code>gain.xml</code> file located in the <code>/rfnoc-tutorial/rfnoc/blocks</code> directory and add the following:

<?xml version="1.0"?>
<nowiki></nowiki>
<nocblock>
<name>gain</name>
<blockname>gain</blockname>
<ids>
<id revision="0">1111222233334444</id>
</ids>
'''<nowiki></nowiki>'''
'''<registers>'''
'''<setreg>'''
'''<name>GAIN</name>'''
'''<address>128</address>'''
'''</setreg>'''
'''</registers>'''
'''<nowiki></nowiki>'''
'''<args>'''
'''<arg>'''
'''<name>gain</name>'''
'''<type>double</type>'''
'''<value>1.0</value>'''
'''<check>GE($gain, 0.0) AND LE($gain, 32767.0)</check>'''
'''<check_message>Invalid gain.</check_message>'''
'''<action>'''
'''SR_WRITE("GAIN", IROUND($gain))'''
'''</action>'''
'''</arg>'''
'''</args>'''
<nowiki></nowiki>
<ports>
<sink>
'''<name>in0</name>'''
'''<type>sc16</type>'''
</sink>
<nowiki><source></nowiki>
'''<name>out0</name>'''
'''<type>sc16</type>'''
<nowiki></source></nowiki>
</ports>
</nocblock>

===GNU Radio Integration===
GNU Radio is built around the concept of blocks, similarly to RFNoC. When mapping RFNoC into an application, the simple constraint is made that every RFNoC block maps to a single GNU Radio block. Thus, when creating mixed GNU Radio/RFNoC applications, there is a very clear 1:1 mapping between what’s happening in RFNoC and GNU Radio.

Since most RFNoC blocks behave very similar to one another from GNU Radio’s perspective, it is generally not required to write C++ code for another block. Rather, a default block provided by RFNoC can be used with appropriate configuration. However, in some cases it may be desirable or even necessary to write a custom GNU Radio block for more specific controlling of the underlying RFNoC block. GNU Radio allows writing blocks in either C++ or Python, but since UHD and RFNoC do not have a Python API, a custom wrapper for an RFNoC block needs to be written in C++. RFNoC Modtool will create skeleton files for this purpose.

The most popular and effective way to use GNU Radio is through the graphical interface, the GNU Radio Companion (GRC). GRC requires a separate description of every GNU Radio block in order to become available in the graphical UI, and the same is true for an RFNoC block that is wrapped in a GNU Radio block (even if the generic RFNoC block wrapper is used). For GNU Radio 3.7 and earlier, GRC bindings for blocks are written as XML files with interspersed Cheetah or Python statements. For a more detailed tutorial on how to write these files, refer to the [http://gnuradio.org/redmine/projects/gnuradio/wiki GNU Radio Documentation] and associated [http://gnuradio.org/redmine/projects/gnuradio/wiki/Guided_Tutorials tutorials].

====GNU Radio Block Code====

* C++ or Python, although RFNoC blocks need to be written in C++ (if at all)
* How does GNU Radio interface to RFNoC?
** via C++ infrastructure code in <code>gr-ettus</code>
** <code>gr-ettus</code> provides a base RFNoC block class
** Users extend base class for their RFNoC blocks
** Many blocks can use base class “as is”
** No C++ or Python code!
* <code>rfnoc-tutorial/lib/gain_impl.cc</code>
** The gain block does not need anything additional

====GNU Radio Companion Bindings====
* XML
* Describes GNU Radio blocks to GRC
* No recompilation
* Requirement of GNU Radio Companion
* Not strictly necessary for GNU Radio
* Tutorial on how to write them:
** [http://gnuradio.org/redmine/projects/gnuradio/wiki/GNURadioCompanion http://gnuradio.org/redmine/projects/gnuradio/wiki/GNURadioCompanion ]
* Skeleton file generated by RFNoC Modtool

Open the <code>tutorial-gain.xml</code> file located in the <code>rfnoc-tutorial/grc</code> directory and edit as follows:

<nowiki><?xml version="1.0"?></nowiki>
<block>
<name>RFNoC: gain</name>
<key>tutorial_gain</key>
<category>tutorial</category>
<import>import tutorial</import>
<make>tutorial.gain(
self.device3,
uhd.stream_args( \# TX Stream Args
cpu_format="'''fc32'''",
otw_format="'''sc16'''",
args="gr_vlen={0},{1}".format(${grvlen}, "" if $grvlen == 1 else "spp={0}".format($grvlen)),
),
uhd.stream_args( \# RX Stream Args
cpu_format="'''fc32'''",
otw_format="'''sc16'''",
args="gr_vlen={0},{1}".format(${grvlen}, "" if $grvlen == 1 else "spp={0}".format($grvlen)),
),
$block_index, $device_index,
)
'''self.$(id).set_arg("gain", $gain)'''
'''</make>'''
'''<callback>set_arg("gain", $gain)</callback>'''
<nowiki></nowiki>

.
.
.

<option>
<name>Byte</name>
<key>u8</key>
</option>
</param>
<param>
<name>'''Gain'''</name>
<key>'''gain'''</key>
'''<value>1.0</value>'''
<type>'''real'''</type>
</param>

<nowiki></nowiki>
<sink>
<name>in</name>
<type>'''complex'''</type>
<vlen>$grvlen</vlen>
<domain>rfnoc</domain>
</sink>

<nowiki></nowiki>
<nowiki><source></nowiki>
<name>out</name>
<type>'''complex'''</type>
<vlen>$grvlen</vlen>
<domain>rfnoc</domain>
<nowiki></source></nowiki>
</block>

'''NOTE:''' Indentation spacing is important in the <code><make></code> section.

===Compile, Install and Verify===

$ cd {USER_PREFIX}/src/rfnoc-tutorial/build
$ make install

$ uhd_usrp_probe

| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * '''gain_0'''
| | | * DDC_0
| | | * FFT_0
| | | * FIFO_0
| | | * FIFO_1
| | | * FIFO_2

'''NOTE:''' In the case where the <code>gain_0</code> does not appear but <code>Block_0</code> does: Most likely, the XML block declaration file (see [[Getting_Started_with_RFNoC_Development#UHD_integration|UHD Integration]] section) for the block contains a NoC-ID that does not match with any NoC-ID defined in the hardware part of the design. The user has to be certain that the description files are up-to-date and that the NoC-ID matches in the SW and HW side. See the [[Getting_Started_with_RFNoC_Development#UHD_integration|UHD Integration]] section to update those host side files.

==Testing out the custom block==
At this point the custom <code>gain</code> RFNoc Block (Computation Engine) can be used within a GNU Radio flowgraph. Below is an example GRC flowgraph using our new block as well as the output application it produces.

[[File:rfnoc gsg an 13.png|center|800px|]]

'''NOTE:''' Copy Block: In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The “copy” block depicted in the screenshot above serves the function as a stream splitter . It’s main purpose, when “enabled”, is to copy the samples it is getting at its input and putting then into the output, but here it is also serving as a boundary between a RFNoC-domain and a GNURadio-domain. In the flowgraph above. after this boundary is passed, the data stream can easily be split into the two sinks to have them run simultaneously (standard GNU Radio functionality). It is possible to connect the GNU Radio blocks directly to RFNoC blocks without a “copy” block, but only one would work at a time (the other ones would have to be disabled). Another way to split data streams from the RFNoC-domain is to use the ”RFNoC: split stream” block, which would split the streams in the RFNoC domain, but this is not very useful here as we are, in any case, moving into the GNURadio-domain.

[[File:rfnoc gsg an 14.png|center|800px|]]

==Troubleshooting==
===Xilinx Vivado===
====Compile issues====
=====Synthesis is failing=====
Verify all the correct Xilinx [[Getting Started with RFNoC Development#Prerequisites|prerequisite software]] is installed.

Additional helpful information can be found in the following Xilinx forum posts:
* https://forums.xilinx.com/t5/Synthesis/Synthesis-failed-without-reporting-any-error/td-p/686000
* https://forums.xilinx.com/t5/Installation-and-Licensing/Vivado-on-Linux-synthesis-fails-with-no-error-message/td-p/732143

====Environment Setup====
The <code>uhd_image_builder.py</code> script will also set up the Xilinx Vivado environment by automatically running the <code>setupenv.sh</code> located in the <code>{USER_PREFIX}/src/uhd-fpga/usrp3/top/{device}</code> directory. The <code>setupenv.sh</code> script assumes that Xilinx Vivado is installed in the default location of <code>/opt/Xilinx/Vivado</code>. If the installation is in a different directory, then the <code>setupenv_base.sh</code> script will need to be modified. The script is located at: <code>{USER_PREFIX}/src/uhd-fpga/usrp3_rfnoc/tools/scripts/setupenv_base.sh</code>.

==Reference Files==
The following reference files are included within the gain_src.tar.gz archive linked below:

* gain.xml
* noc_block_gain.v
* noc_block_gain_tb.sv
* tutorial_gain.xml
* rfnoc_gain.grc

[[Media:gain src.tar.gz]]

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Software Resources Page]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf RFNoC Introduction]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]
* [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015 ]
** Explaining the slides of Intro, FPGA and Host presentations above (in that order).
* [https://www.youtube.com/watch?v=51rpjJ2W0Qs Video: It's the RFNoC Life for Us by Martin Braun at GRCon16, 2016]

===GNU Radio resources===
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNU Radio OutOfTree Modules tutorial]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio Installation]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/Tutorials GNU Radio Tutorials]

===UHD resources===
* [https://kb.ettus.com/UHD UHD Software Resources Page]
* [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]
* [http://files.ettus.com/manual/ UHD Manual]

===Other resources===
* [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]
* [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD + GNU Radio Application Note (Linux)]
* [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS]

[[Category:Application Notes]]

Debugging FPGA images

2016-12-16T11:18:45Z

NicolasCuervo:

= Application Note Number =
'''AN-121'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo Sugandha Gupta
|style="text-align:center;"| Initial creation
|}

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench. In addition, there is plenty of online resources (such as [8]) that provide enough information to get you started with your simulation.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

* '''UHD, GNURadio and gr-ettus: ''' At the end of the debugging process we will be running the application on a physical device, and for that we need the core code downloaded and installed. UHD will serve as our device driver, GNURadio the frame on which our app will run, and gr-ettus is needed for our ''signal generator'' block. If you need guidance on this, please refer to the [https://kb.ettus.com/Getting_Started_with_RFNoC_Development#Creating_a_development_environment Creating a development environment] section of our ''Getting started guide''. If you are debugging your own RFNoC OOT module, this will have to be installed as well.

* '''RFNoC supported device: ''' The whole point of chipscoping is having the ability of probing signals from a hardware design at runtime. Hence, a device where the application is going to run is needed. In this tutorial we will be using an X310 device.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =
After the bitstream generation is completed successfully, it is time for us to move on and put our design into the device. On the left pannel, right below we generated our bitstream, is the "Hardware Manager". At this point, we have our X310 connected via JTAG for programming purposes, and via Ethernet (1G in this specific use case) for later usage. Now, click on 'Open Target'. If you have only one device connected, the option "auto-connect" should work just fine. Otherwise, select your device by clicking on "Open new target" and following the options in order to find the device you want. After doing so, two options should appear at the top of your Vivado window:

[[File:cs_6.png|center|Hardware options|link=https://kb.ettus.com/images/9/9e/cs_6.png]]

As a first step, click on "Program device". Usually, again, Vivado picks up the bitstream that you just generated. However, if you have been running multiple bitstream builds and/or have multiple Vivado projects, it is possible that you would have to look for the right bitstream. It should be under the project that you have been working during the generation of your debug bitstream.

After programing, you have to run an initialization routine on your device. A way to do this is to run a usrp probe, which will also tell us several interesting information. In a terminal, run:

$ uhd_usrp_probe

This will tell you information about the device. In our case, the last portion of the output should look like this:

| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * SigGen_0
| | | * DUC_0
| | | * DDC_0

which tells us that the blocks '''Signal Generator, DUC and DDC''' were correctly added into the device. Keep in mind that the DmA FIFO and two instances of the radio are added by default into an X310 device. Now, go back to the Vivado GUI and click on "Refresh device" right on the top of the Vivado Window. After that, your debugging signals should appear and you are ready to start chipscoping.

== Selecting Triggers ==
While probing your design, you probably want to know the state of a given signal right at the moment at which it or other signal changed. In some cases you can have a short simulation and you can ''eye-ball'' your signals and see if the results are as expected. However, sometimes signals change very fast or have a really short duration, making a qualitative procedure a little bit more complicated. For that case, you can set up '''triggers''', which means that the chipscope tool will start capturing when a desired signal changes. We are going to use this feature here and is recommended to do so to have more control over the signal capturing.

[[File:cs_7.png|center|Trigger Setup|link=https://kb.ettus.com/images/e/e1/cs_7.png]]

Here we are going to choose two signals as triggers, which are '''s_axis_data_tvalid''' and '''s_axis_data_tready'''. The names are almost self explanatory: they state when the device has valid data and when it is ready (see [4] for further information). After choosing this signals, now we have to put our device to work. Even, you can click on "run trigger for this ILA core", which will let the device on idle state waiting for the trigger.

[[File:cs_9.png|center|Trigger Setup. You can also see the black panel where all the debug lines are listed.|link=https://kb.ettus.com/images/7/74/cs_9.png]]

== Debugging at run time ==
This is what we came for. The block is to be put in a normal use case where it will run and, simultaneously, we will probe signals from it. For the '''RFNoC: Signal Generator''', we are going to use GNURadio to set up the application. Actually, we are going to use the siggen example that is shipped within ''gr-ettus''. We open to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}{path_to_gr-ettus}/examples/rfnoc/rfnoc_siggen.grc</syntaxhighlight>, where a simple setup is ready to show the siggen working.

[[File:cs_8.png|center|GNURadio example for the RFNoC: Signal Generator block|link=https://kb.ettus.com/images/d/d1/cs_8.png]]

You can see that there is a number of options which can be modified. As we choose to check how signal such as "Wave type" and "gain", we are going to focus on this for now. They can be modified on runtime, but every time that they are set to a different value the trigger has to be run again on the Vivado chipscope. Following are some of the expected results:

'''Signal type: Constant || Gain: 1: ''' In this case the signal "wave type" is set to 0, as it being the first option available in the block. The Gain is set to 7FFF, which is the maximum hexadecimal value that the register is able to receive in this case and which means the maximum absolute gain.
[[File:cs_10.png|center|Signal type: Constant || Gain: 1|link=https://kb.ettus.com/images/7/72/cs_10.png]]

'''Signal type: Sinusoid || Gain: 1: ''' Now the wave type is set to 1, being the next option available. The gain is unchanged to show how it holds the same value in the readback register.
[[File:cs_12.png|center|Signal type: Sinusoid || Gain: 1|link=https://kb.ettus.com/images/5/56/cs_12.png]]

'''Signal type: Noise || Gain: 0.5: ''' Wave type and gain are both changed, showing results somewhat expected: wave type is set to 2, being sequentially the next option available, and the gain is set to half of the maximum value, which is shown to be true also in its hexadecimal representation read from the readback register.
[[File:cs_14.png|center|Signal type: Noise || Gain: 0.5|link=https://kb.ettus.com/images/9/9a/cs_14.png]]

If you have come successfully until this point, then you can play around with the signals and checking the result in the debugging panel or, even better, apply this technique to debug your own RFNoC design!

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

[8] [https://www.xilinx.com/support/documentation/application_notes/xapp199.pdf Xilinx AN - Writing efficient Testbenches]

File:cs 14.png

2016-12-16T11:11:03Z

NicolasCuervo: NicolasCuervo uploaded a new version of File:cs 14.png

File:cs 12.png

2016-12-16T11:10:21Z

NicolasCuervo: NicolasCuervo uploaded a new version of File:cs 12.png

File:cs 10.png

2016-12-16T11:09:29Z

NicolasCuervo: NicolasCuervo uploaded a new version of File:cs 10.png

File:cs 14.png

2016-12-16T10:58:32Z

NicolasCuervo:

File:cs 13.png

2016-12-16T10:50:37Z

NicolasCuervo:

File:cs 12.png

2016-12-16T10:50:11Z

NicolasCuervo:

File:cxs 11.png

2016-12-16T10:48:14Z

NicolasCuervo:

File:cs 10.png

2016-12-16T10:47:48Z

NicolasCuervo:

File:cs 9.png

2016-12-16T10:40:15Z

NicolasCuervo:

File:cs 8.png

2016-12-16T10:35:50Z

NicolasCuervo:

File:cs 7.png

2016-12-16T10:17:52Z

NicolasCuervo:

Debugging FPGA images

2016-12-03T15:16:20Z

NicolasCuervo:

= Application Note Number =
'''AN-XXX'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo Sugandha Gupta
|style="text-align:center;"| Initial creation
|}

= UNDER CONSTRUCTION: THE CONTENTS OF THIS PAGE HAVE TO GO THROUGH REVIEW AND EDITION. AT THIS MOMENT, PLEASE DO NOT USE THIS PAGE AS A REFERENCE! =

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench. In addition, there is plenty of online resources (such as [8]) that provide enough information to get you started with your simulation.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

* '''UHD, GNURadio and gr-ettus: ''' At the end of the debugging process we will be running the application on a physical device, and for that we need the core code downloaded and installed. UHD will serve as our device driver, GNURadio the frame on which our app will run, and gr-ettus is needed for our ''signal generator'' block. If you need guidance on this, please refer to the [https://kb.ettus.com/Getting_Started_with_RFNoC_Development#Creating_a_development_environment Creating a development environment] section of our ''Getting started guide''. If you are debugging your own RFNoC OOT module, this will have to be installed as well.

* '''RFNoC supported device: ''' The whole point of chipscoping is having the ability of probing signals from a hardware design at runtime. Hence, a device where the application is going to run is needed. In this tutorial we will be using an X310 device.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =
After the bitstream generation is completed successfully, it is time for us to move on and put our design into the device. On the left pannel, right below we generated our bitstream, is the "Hardware Manager". At this point, we have our X310 connected via JTAG for programming purposes, and via Ethernet (1G in this specific use case) for later usage. Now, click on 'Open Target'. If you have only one device connected, the option "auto-connect" should work just fine. Otherwise, select your device by clicking on "Open new target" and following the options in order to find the device you want. After doing so, two options should appear at the top of your Vivado window:

[[File:cs_6.png|center|Hardware options|link=https://kb.ettus.com/images/9/9e/cs_6.png]]

As a first step, click on "Program device". Usually, again, Vivado picks up the bitstream that you just generated. However, if you have been running multiple bitstream builds and/or have multiple Vivado projects, it is possible that you would have to look for the right bitstream. It should be under the project that you have been working during the generation of your debug bitstream.

After programing, you have to run an initialization routine on your device. A way to do this is to run a usrp probe, which will also tell us several interesting information. In a terminal, run:

$ uhd_usrp_probe

This will tell you information about the device. In our case, the last portion of the output should look like this:

| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * SigGen_0
| | | * DUC_0
| | | * DDC_0

which tells us that the blocks '''Signal Generator, DUC and DDC''' were correctly added into the device. Keep in mind that the DmA FIFO and two instances of the radio are added by default into an X310 device. Now, go back to the Vivado GUI and click on "Refres

#WIP

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

[8] [https://www.xilinx.com/support/documentation/application_notes/xapp199.pdf Xilinx AN - Writing efficient Testbenches]

File:cs 6.png

2016-12-02T13:24:25Z

NicolasCuervo:

Debugging FPGA images

2016-12-02T09:28:24Z

NicolasCuervo: /* External references */

= Application Note Number =
'''AN-XXX'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo
|style="text-align:center;"| Initial creation
|}

= UNDER CONSTRUCTION: THE CONTENTS OF THIS PAGE HAVE TO GO THROUGH REVIEW AND EDITION. AT THIS MOMENT, PLEASE DO NOT USE THIS PAGE AS A REFERENCE! =

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench. In addition, there is plenty of online resources (such as [8]) that provide enough information to get you started with your simulation.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =

#TODO

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

[8] [https://www.xilinx.com/support/documentation/application_notes/xapp199.pdf Xilinx AN - Writing efficient Testbenches]

Debugging FPGA images

2016-12-02T09:27:27Z

NicolasCuervo: /* Overview */

= Application Note Number =
'''AN-XXX'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo
|style="text-align:center;"| Initial creation
|}

= UNDER CONSTRUCTION: THE CONTENTS OF THIS PAGE HAVE TO GO THROUGH REVIEW AND EDITION. AT THIS MOMENT, PLEASE DO NOT USE THIS PAGE AS A REFERENCE! =

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench. In addition, there is plenty of online resources (such as [8]) that provide enough information to get you started with your simulation.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =

#TODO

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

Debugging FPGA images

2016-12-02T09:23:47Z

NicolasCuervo: /* Overview */

= Application Note Number =
'''AN-XXX'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo
|style="text-align:center;"| Initial creation
|}

= UNDER CONSTRUCTION: THE CONTENTS OF THIS PAGE HAVE TO GO THROUGH REVIEW AND EDITION. AT THIS MOMENT, PLEASE DO NOT USE THIS PAGE AS A REFERENCE! =

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://files.ettus.com/manual/md_usrp3_sim_writing_testbenches.html - Writing Testbenches] section of our reference manual to have insights on how to write your own testbench.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =

#TODO

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

Debugging FPGA images

2016-11-30T19:57:24Z

NicolasCuervo: /* Revision History */

= Application Note Number =
'''AN-XXX'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo
|style="text-align:center;"| Initial creation
|}

= UNDER CONSTRUCTION: THE CONTENTS OF THIS PAGE HAVE TO GO THROUGH REVIEW AND EDITION. AT THIS MOMENT, PLEASE DO NOT USE THIS PAGE AS A REFERENCE! =

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://kb.ettus.com/index.php?title=Writing_Testbenches_for_RFNoC - Writing Testbenches for RFNoC] application note to have insights on how to write your own testbench.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =

#TODO

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

Debugging FPGA images

2016-11-30T19:56:21Z

NicolasCuervo:

= Application Note Number =
'''AN-XXX'''

= Revision History =
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-11-28
|style="text-align:center;"| Nicolas Cuervo Sugandha Gupta
|style="text-align:center;"| Initial creation
|}

= UNDER CONSTRUCTION: THE CONTENTS OF THIS PAGE HAVE TO GO THROUGH REVIEW AND EDITION. AT THIS MOMENT, PLEASE DO NOT USE THIS PAGE AS A REFERENCE! =

= Abstract =
This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator. The contents of this AN could suit most of your needs while setting your debug bitstream for a RFNoC design. However, keep in mind that the topics described here are strictly related to Xilinx framework. For further information please refer to Xilinx documentation [1][2].

= Overview =
When you are developing your own application, you might come to the point on which you would like to build an FPGA image for your USRP. You might want to modify part of the cores, add some custom functionality, or even add your custom RFNoC block! For that you might follow tutorials such as the [[Getting_Started_with_RFNoC_Development#Building the FPGA image|Building the FPGA image]] section of one our "getting started" guides.

But how about debugging your HDL code? This comes really handy when you want to follow closely the behavior of your signals within your hardware design. This Application Note will follow the basic steps needed to create a "chipscope image", which allow you to use the Vivado GUI visual tools to debug your design.

Before we start, this App note assumes that you have been working already with some fpga code and you want to debug it. Being this the case, we assume that you have UHD installed, the FPGA repository cloned, the right version of Xilinx Vivado installed (by the moment this is being written we use Vivado 2015.4) and its environment initialized. If not, we assume you are familiar on how to do the previously noted procedures.

For illustration purposes, here we are going to check the status of some of the output signals of one of the RFNoC blocks we currently provide. However, the same procedure can be used to check the status of any signal within your hardware code, being input, output, or intermediate signal, and being the code a core description, a module for your library or your custom RFNoC block.

''' Note: ''' Keep in mind that this procedure intends to probe the signals in a fully designed block, which has been also built into a FPGA .bit file and is running in a supported device. This is *not* intended to be a way to test directly your designed code, as building an FPGA image may take several minutes (even hours). For small functionality checks, we strongly recommend you to write a testbench for your code, which will allow you to have more iterations without the need of building and synthesizing your hardware description. You can follow the [https://kb.ettus.com/index.php?title=Writing_Testbenches_for_RFNoC - Writing Testbenches for RFNoC] application note to have insights on how to write your own testbench.

= Prerequisites =

* '''Vivado (version 2015.4): ''' As stated in the overview, you'll be working directly with HDL code that you need to build and synthesize. Depending on your target device, you may even need a non-free license (which is the case for the X3XX devices). In the case of Ettus' embedded devices, you can proceed with your design using the Vivado Webpack.

= Choosing your signals =
At this point we assume that you have a verilog code that has been properly tested by the means of simulation/testbench, but that you want to inspect into its functionality deeper by probing its signals while it is running on a device. This could be helpful for many reasons, such as getting a deeper understanding on the state of your signal during a given transaction, which could give you an insight on how it is working (or even, can give you a lead on why it isn't!)

For this AN, we will use out block '''RFNoC: Signal Generator''' as our Unit Under Test (UUT). However, all procedures to be done can be easily transfered to your own design. In addition, as most of our block and FPGA code is written in Verilog, we will use it also in this document. So let's get started.

The Signal generator's code can be found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3/lib/rfnoc/</syntaxhighlight>. In some of our latest code releases (such as 3.10.0.0), this code is found under <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/usrp3_rfnoc/lib/rfnoc/</syntaxhighlight>. In this directory you can find the RFNoC related code that is used in the RFNoC framework. Consequently, all the HDL for the NoC blocks the we provide is located here. Now, open the file <syntaxhighlight lang="bash" enclose="none">noc_block_siggen.v</syntaxhighlight> in your IDE or text editor of preference and give it a quick look.

As you can see, the code is not too extensive and is the comments divide it properly based on functionality. If your design is RFNoCModtool-generated, you'll get a similar preliminary structure in the verilog files for your block. For information on how to use RFNoCModtool please refer to [https://kb.ettus.com/index.php?title=Getting_Started_with_RFNoC_Development RFNoC Development - Getting Started Guide]. Normally for rather simple designs you won't have to deal with the RFNoC Shell or the AXI Wrapper configuration. However, for illustration purposes, we are going to take some of the signals from this part of the code and probe them in our debugging process. A total of 11 signals will be selected, each from a different internal stage.

Lets take a look at how this boundaries look like in the FPGA Internals. Each full RFNoC design can include several different blocks, which are also called "computation engines". The picture on the right [3] portraits the computation engine internals in a quite self explanatory fashion, although a slightly more detailed explanation about each of the internals from a Computation Engine can be found at the [https://kb.ettus.com/RFNoC_Getting_Started_Guides RFNoC Software Page]:

[[File:CE_internals.png|Anatomy of a computation engine.|600px|right|Anatomy of a computation engine|link=https://kb.ettus.com/images/8/83/CE_internals.png]]

'''From NoC Shell: '''At the top of the figure you can see the AXI Crossbar, were all the computation engines are wired up together. This is not part of our UUT in particular. However, the connection between the crossbar and our UUT - NoC Shell can be tested within our code. From here we are taking the set_data/addr/stb, which are readback registers and provide information from this interface.
* set_data
* set_addr
* set_stb

'''From the AXI Wrapper: '''our next stage from where we are taking signals is the AXI Wrapper. This can be understood as a translating stage in which the data that goes from and to the user's design is correctly encapsulated into a CHDR packet [5]. By probing this signals we expect to find out that the data that is being transported is correct, and that the transaction also takes places at the right moment.
* s_axis_data_tdata
* s_axis_data_tuser
* s_axis_data_tlast
* s_axis_data_tvalid
* s_axis_data_tready

'''From the signal generator design: ''' Last but not least, we are probing signals from the UUT IP, which means that we are checking directly the value that certain lines inside the FPGA have the correct value at a certain time. In this case, we'll be checking if the wave type is according with the one selected from the host, that the gain value is propagated correctly and, clearly, if the block is generating signals when it is enable and when it isn't.
* gain
* wave_type
* enable

= Setting up the code for ChipScoping =

To let know Vivado that we want to probe signals, we have to go directly into the code and mark this signals for debugging. This can be done by using reserved words that describe the synthesizing attributes for a given signal. There is a variety of different attributes that you can give to any signal of your design [2], but here we are going to discuss the ones that serve most of the debugging needs:

* '''KEEP: ''' This attribute prevents the signal to be optimized or absorbed into logic blocks, which would mean that the signal, even though it would be operational after synthesis, may not be accessible for probing. An example of the syntax for this attribute is as follows:
VERILOG:
(* keep = "true" *) wire signal_name;
assign signal_name = in1 & in2;

VHDL:
signal signal_name : std_logic;
attribute keep : string;
attribute keep of signal_name : signal is "true";
signal_name <= in1 and in2;

* '''KEEP_HIERARCHY: ''' As well as KEEP, this attribute prevents the optimization. However, this attribute can be applied to a module or instance. By using this attribute, the synthesis tools keep the boundary on this signal static. Example:
VERILOG
On Module:
(* keep_hierarchy = "yes" *) module example (in1, in2, out1, out2);
On Instance:
(* keep_hierarchy = "yes" *) example e0 (.in1(in1), .in2(in2), .out1(out1));

VHDL
On Module:
attribute keep_hierarchy : string;
attribute keep_hierarchy of example : architecture is "yes";
On Instance:
attribute keep_hierarchy : string;
attribute keep_hierarchy of e0 : label is "yes";

* '''DONT_TOUCH: ''' this attribute works just as KEEP and KEEP_HIERARCHY, with the difference that this one is forward-annotated to place and route to prevent logic optimization. In case where other attributes get into conflict with DONT_TOUCH, DONT_TOUCH takes precedence and will be applied. It also can take values yes/no and true/false. Example:

VERILOG WIRE
(* dont_touch = "yes" *) wire signal1;
assign signal1 = in1 & in2;

VERILOG MODULE
(* DONT_TOUCH = "yes" *)
module example (clk, in1, in2, out1);

VHDL EXAMPLE
signal sig1 : std_logic;
attribute dont_touch : string;
attribute dont_touch of sig1 : signal is "true"

* '''MARK_DEBUG: ''' This is arguably the most important attribute for our current use case, because it is the one that tells Vivado which nets are going to be debugged. This also prevents optimization over the signal, and in addition prepares it to be probed during operation. Virtually this attribute could be applied to any net within the design, but there are some nets with specific properties could have protection against visibility, and can not be probed. The values for MARK_DEBUG are TRUE/FALSE. Example:
VERILOG
(* MARK_DEBUG = "TRUE" *) wire debug_wire;
VHDL
attribute MARK_DEBUG : string;
attribute MARK_DEBUG of signal_name : signal is "TRUE";

For other attributes and options, please refer to Xilinx's documentation [1][2]. We are going to use the given almost in every case, if not always. Now, the syntax is rather simple and so is the applications to the attributes to the code. The resulting file should look as the picture on the right. When you have modified the code, you are ready to build your debug bitstream.

[[File:chipscope_diff_siggen.png|thumb|Adding attributes to signals to probe.|900px|center|Adding attributes to signals to probe.|link=https://kb.ettus.com/images/a/a7/chipscope_diff_siggen.png]]

= Building the debug bitstream =
== Save the project and finish Synthesis ==
For this test in particular you are going to need to have a DDC (Digital down converter) in addition to the UUT for visualization purposes on a host. To add this blocks into the bitstream, go to <syntaxhighlight lang="bash" enclose="none">{fpga-repository}/[usrp3|usrp3_rfnoc/tools/scripts/</syntaxhighlight> and inside that directory run the following command:

$ ./make.py siggen ddc -g

This will set up your Vivado environment and start the build of an FPGA image with the signal generator and the DDC blocks. The option '-g' is telling the script that at some point during the build process the Vivado User Interface should be opened, as it is where we are going to set up our debug image. For <syntaxhighlight lang="bash" enclose="none">make.py</syntaxhighlight> usage and options please refer to the [[Getting_Started_with_RFNoC_Development#Wiring_up_computation_engines_and_building_the_FPGA image|Wiring up computation engines and building the FPGA image]] section of our getting started guide, or simply run <syntaxhighlight lang="bash" enclose="none">make.py --help in your terminal</syntaxhighlight>

'''Note: ''' ''The FPGA image building process may take over an hour.''

The Vivado GUI is going to come up at some point of the synthesis. Right after the Vivado GUI has opened, you can go ahead and cancel the process that is running, which is usually the last part of the synthesis (when it shows 90% done is a safe moment to cancel. See "Saving the project" figure). This is because we first have to set up the parameters for debugging and the synthesis has to be re-run. After canceling, save the project and give it a name of your choice; we are giving here the name ''AN_chipscope'', but you can name the project whatever you like. Right after saving the project, click on 'Run Synthesis', which can be found on the left panel under '''Project Manager->Synthesis->Run Synthesis'''.

[[File:cs1.png|thumb|200px|left|Saving the Vivado Project|link=https://kb.ettus.com/images/7/74/cs1.png]]

'''Note: ''' Most of the time Vivado will auto-detect your highest hierarchy module, but it may happen that it just slips to it and then it will ask you which it. If this happens, you can select the verilog file according to the target device that you are chipscoping as the top module (e.g. x300.v or e300.v)

Now wait until the synthesis is finished. This won't take long, and after it finishes a window will prompted saying that the synthesis is done, and asking if you want to run the implementation. Click on cancel, as we need to setup the debugging parameters first.

== Setup debug ==

Go to '''Project Manager -> Synthesis -> Open Synthesized Design -> Set Up debug''', and the wizard will start. Click on next until you see a window listing the nets to debug. Here, two scenarios are expected. See the figure below:

[[File:cs_2.png|center|1200px|Clock Domain|link=https://kb.ettus.com/images/5/52/cs_2.png]]

Sometimes Vivado will pick up the clock domain automatically (which is the case depicted on the right side), but there are occasions where the nets to debug aren't clearly defined under a clock domain and this cases require a little bit more of work, depending on your knowledge of your design. In this case, we know that the nets are under the same clock domain as the other signals, but in case of doubt, you'll have to go and find it out through the code. The case on the left can be solved easily by clicking on 'more info', which is just at the end of the red warning. Right after clickling, further, clearly, information will appear. In the prompted dialog, let us click on 'Assign All Clock Domains'

[[File:cs_3.png|center|Assigning all clock domains|link=https://kb.ettus.com/images/e/e4/cs_3.png]]

A window will appear where you can choose the common clock domain on which you want to have the signals. Here, in our case, we select <syntaxhighlight lang="bash" enclose="none">radio_clk_gen/inst/CLK_OUT1</syntaxhighlight>, and that would be sufficient to continue. Accept and click next.

Right after, we have to choose the ''Integrated Logic Analizer - ILA'' Core Options [6][7]. Here we will only focus on "Sample of data depth" and "Input pipe stages"

[[File:cs_4.png|550px|center|ILA core options|link=https://kb.ettus.com/images/2/29/cs_4.png]]

The "Sample of data depth" is the maximum number of data sample words that the ILA core can store at run time for each of the probe lines. The input pipe stages is the number of flops or registers that are added to each probe line. This basically determines how big the debug setup will be, and the amount of data that is going to be analyzed per run. Here we select 4096 for the data depth and 1 input pipe line. For further information about the ILA and its configuration, please refer to the ILA documentation [6][7]. With this, the set up is done, and you can proceed to click "next" and then "finish" to complete the wizard operation.

[[File:cs_5.png|center|ILA core options|link=https://kb.ettus.com/images/a/a3/cs_5.png]]

After the setup is finished, go to the left panel and click '''Project Manager->Program and Debug->Generate Bitstream'''. This will ask you if you want to run the implementation first, to what we answer 'Yes'. This will prepare the bitstream with which we are going to program our device and debug our design.

= Running the debug bitstream in the target device =

#TODO

= External references =
[1] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug936-vivado-tutorial-programming-debugging.pdf Vivado Tutorial: Programming and debugging]

[2] [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_4/ug901-vivado-synthesis.pdf Vivado Synthesis]

[3] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]

[4] [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]

[5] [https://files.ettus.com/manual/page_rtp.html Radio Transport Protocols]

[6] [https://www.xilinx.com/support/documentation/ip_documentation/chipscope_ila/v1_04_a/chipscope_ila.pdf LogiCORE IP ChipScope Pro Integrated Logic Analyzer]

[7] [https://www.xilinx.com/support/documentation/ip_documentation/ila/v3_0/pg172-ila.pdf LogiCORE IP Integrated Logic Analyzer v3.0]

File:cs 5.png

2016-11-30T19:13:33Z

NicolasCuervo:

File:cs 4.png

2016-11-30T19:02:02Z

NicolasCuervo:

File:cs 3.png

2016-11-30T18:47:10Z

NicolasCuervo: NicolasCuervo uploaded a new version of File:cs 3.png

File:cs 3.png

2016-11-30T18:45:08Z

NicolasCuervo:

File:cs 2.png

2016-11-30T18:35:55Z

NicolasCuervo:

File:cs1.png

2016-11-30T18:15:53Z

NicolasCuervo:

File:chipscope diff siggen.png

2016-11-30T10:26:50Z

NicolasCuervo: