Ettus Knowledge Base - User contributions [en]

USRP X Series Quick Start (Daughterboard Installation)

2020-04-28T19:51:49Z

JoseLoera: /* Revision History */

==Application Note Number==
'''AN-904'''

==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
|
|-
|style="text-align:center;"| 2020-Apr-27
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added section "UBX Daughterboard Installation Video" and link. Link also provided [https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing here] as well
|}

==Abstract==
This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.

==Overview==
This Quick Start is meant to show you how to put together your new X300/310. We will start at the point when you have yet to unpack the boxes and go all the way to being able to ping the device, performing a quick software probe to verify hardware components and finally running a simple FFT demo. This Quick Start does not cover the installation of software on the host computer. If you have not installed UHD/Gnuradio on your system, please reference 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. You may also use the [[Live SDR Environment]] to perform the verification steps for your USRP. Detailed information on the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==Tools Required==
* Philips Screwdriver
* 5/16” wrench

==Pre-installed Software==
* UHD Latest
* GNU Radio

==Box Contents==
===USRP Box===
* 1 x USRP X300/X310
* 1 x SFP Adapter for 1 GigE
* 1 x Power Supply and US Cord
* 1 x USB 2.0 JTAG Debug Cable
* 1 x Gigabit Ethernet Cable
* 4 x SMA-Bulkhead Cables
* 16 x Daughterboard Screws
===Daughterboard Boxes===
* 2 x SBX Daughterboards
===Antenna Boxes===
* One or more Antennas

[[File:Xseries quickstart figure 1.png|700px|center]]

[[File:Xseries quickstart figure 2.png|700px|center]]

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Ettus Research recommends you perform the installation with no power to the USRP and using ESD equipment. Listed below are some examples of actions which can prevent damage to the unit:

*Never allow metal objects to touch the circuit board while powered.
*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the board with proper anti-static methods.
*Never allow the board to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the boards.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Installation Process==
===Step 1===
Unscrew the 2 screws on the top of the USRP and remove cover. (Lift up about 15 degrees and wiggle back as there
is a flange on the front part of the cover)

[[File:Xseries quickstart figure 3.png|700px|center]]

[[File:Xseries quickstart figure 4.png|700px|center]]

[[File:Xseries quickstart figure 5.png|700px|center]]

===Step 2===
Line up the 8 screw holes on the Daughterboard with the USRP Motherboard standoffs (they only go one way).

[[File:Xseries quickstart figure 6.png|700px|center]]

[[File:Xseries quickstart figure 7.png|700px|center]]

===Step 3===
After you have aligned the Daughterboard correctly you can press the Daughterboard on to the connectors below them (you will feel them snap into place).

[[File:Xseries quickstart figure 8.png|700px|center]]

[[File:Xseries quickstart figure 9.png|700px|center]]

===Step 4===
Put 8 of the screws provided in the daughterboard

[[File:Xseries quickstart figure 10.png|700px|center]]

===Step 5===
Repeat steps 2- 4 for the second Daughterboard

===Step 6===
It is recommended to connect the bulkhead cables one at a time to avoid confusion. The Daughterboards and front
panel of the X300/310 are clearly labeled as to which cable goes where.

[[File:Xseries quickstart figure 11.png|700px|center]]

[[File:Xseries quickstart figure 12.png|700px|center]]

[[File:Xseries quickstart figure 13.png|700px|center]]

[[File:Xseries quickstart figure 14.png|700px|center]]

[[File:Xseries quickstart figure 15.png|700px|center]]

[[File:Xseries quickstart figure 16.png|700px|center]]

===Step 7===
Repeat step 6 for the other bulkhead cables

[[File:Xseries quickstart figure 17.png|700px|center]]

[[File:Xseries quickstart figure 18.png|700px|center]]

===Step 8===
Install USRP cover with screws

[[File:Xseries quickstart figure 19.png|700px|center]]

===Step 9===
Connect the SFP 1 GigE adapter into USRP SFP port 0

[[File:Xseries quickstart figure 20.png|700px|center]]

[[File:Xseries quickstart figure 21.png|700px|center]]

===Step 10===
Connect the Gigabit Ethernet cable and power cord provided

[[File:Xseries quickstart figure 22.png|700px|center]]

===Step 11===
Attach any Antennas you may have purchased

[[File:Xseries quickstart figure 23.png|700px|center]]

===Step 12===
On the computer(host) you plan to use to connect to the USRP set the Ethernet adapter to have an IP address of 192.168.10.1 with a subnet mask of 255.255.255.0. Connect the other end of the Gigabit Ethernet cable to your computer.

[[File:Xseries quickstart figure 24.png|700px|center]]

===Step 13===
Power on the USRP (button on the front right of the USRP)

===Step 14===
Ping the device from host computer:

$ ping 192.168.10.2

[[File:Xseries quickstart figure 25.png|700px|center]]

===Step 15===
Assuming you have properly installed the UHD driver you can now run this command in a terminal/command window:

$ uhd_usrp_probe

This will tell you about the hardware inside of your USRP. The output will look like the following:

$ uhd_usrp_probe
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- Detecting internal GPSDO.... No GPSDO found
-- Initialize Radio0 control...
-- Performing register loopback test... pass
-- Initialize Radio1 control...
-- Performing register loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X300
| | revision: 7
| | revision_compat: 7
| | product: 30518
| | mac-addr0: ff:ff:ff:ff:ff:ff
| | mac-addr1: ff:ff:ff:ff:ff:ff
| | gateway: 255.255.255.255
| | ip-addr0: 255.255.255.255
| | subnet0: 255.255.255.255
| | ip-addr1: 255.255.255.255
| | subnet1: 255.255.255.255
| | ip-addr2: 255.255.255.255
| | subnet2: 255.255.255.255
| | ip-addr3: 255.255.255.255
| | subnet3: 255.255.255.255
| | serial: FFFFFFF
| | FW Version: 4.0
| | FPGA Version: 20.0
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None

==UBX daughterboard Installation Video==
The following link is a video of the steps to install the UBX daughterboard. The procedure is similar to what is outlined above.

*[https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing Video: UBX Installation into a USRP X-series device.]

==UHD FFT==
Try the UHD_FFT demo that comes with GNU Radio

1. Connect one antenna to RX2 on the left Daughterboard (Daughterboard A)

[[File:Xseries quickstart figure 26.png|700px|center]]

2.From the terminal/command window:

$ uhd_fft --ant RX2

[[File:Xseries quickstart figure 27.png|700px|center]]

[[File:Xseries quickstart figure 28.png|700px|center]]

==Success==
Congratulations! You have successfully setup and verified your new USRP X300/X310. A more detailed verification guide is at the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] application note. For additional step-by-step guides to using your USRP X300/X310, see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

USRP X Series Quick Start (Daughterboard Installation)

2020-04-28T19:50:26Z

JoseLoera: /* Additional Resources */

==Application Note Number==
'''AN-904'''

==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
|
|-
|style="text-align:center;"| 2020-Apr-27
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added link to video on installing UBX board in a USRP X Series device to the Additional Resources section. Link [https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing here] as well
|}

==Abstract==
This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.

==Overview==
This Quick Start is meant to show you how to put together your new X300/310. We will start at the point when you have yet to unpack the boxes and go all the way to being able to ping the device, performing a quick software probe to verify hardware components and finally running a simple FFT demo. This Quick Start does not cover the installation of software on the host computer. If you have not installed UHD/Gnuradio on your system, please reference 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. You may also use the [[Live SDR Environment]] to perform the verification steps for your USRP. Detailed information on the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==Tools Required==
* Philips Screwdriver
* 5/16” wrench

==Pre-installed Software==
* UHD Latest
* GNU Radio

==Box Contents==
===USRP Box===
* 1 x USRP X300/X310
* 1 x SFP Adapter for 1 GigE
* 1 x Power Supply and US Cord
* 1 x USB 2.0 JTAG Debug Cable
* 1 x Gigabit Ethernet Cable
* 4 x SMA-Bulkhead Cables
* 16 x Daughterboard Screws
===Daughterboard Boxes===
* 2 x SBX Daughterboards
===Antenna Boxes===
* One or more Antennas

[[File:Xseries quickstart figure 1.png|700px|center]]

[[File:Xseries quickstart figure 2.png|700px|center]]

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Ettus Research recommends you perform the installation with no power to the USRP and using ESD equipment. Listed below are some examples of actions which can prevent damage to the unit:

*Never allow metal objects to touch the circuit board while powered.
*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the board with proper anti-static methods.
*Never allow the board to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the boards.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Installation Process==
===Step 1===
Unscrew the 2 screws on the top of the USRP and remove cover. (Lift up about 15 degrees and wiggle back as there
is a flange on the front part of the cover)

[[File:Xseries quickstart figure 3.png|700px|center]]

[[File:Xseries quickstart figure 4.png|700px|center]]

[[File:Xseries quickstart figure 5.png|700px|center]]

===Step 2===
Line up the 8 screw holes on the Daughterboard with the USRP Motherboard standoffs (they only go one way).

[[File:Xseries quickstart figure 6.png|700px|center]]

[[File:Xseries quickstart figure 7.png|700px|center]]

===Step 3===
After you have aligned the Daughterboard correctly you can press the Daughterboard on to the connectors below them (you will feel them snap into place).

[[File:Xseries quickstart figure 8.png|700px|center]]

[[File:Xseries quickstart figure 9.png|700px|center]]

===Step 4===
Put 8 of the screws provided in the daughterboard

[[File:Xseries quickstart figure 10.png|700px|center]]

===Step 5===
Repeat steps 2- 4 for the second Daughterboard

===Step 6===
It is recommended to connect the bulkhead cables one at a time to avoid confusion. The Daughterboards and front
panel of the X300/310 are clearly labeled as to which cable goes where.

[[File:Xseries quickstart figure 11.png|700px|center]]

[[File:Xseries quickstart figure 12.png|700px|center]]

[[File:Xseries quickstart figure 13.png|700px|center]]

[[File:Xseries quickstart figure 14.png|700px|center]]

[[File:Xseries quickstart figure 15.png|700px|center]]

[[File:Xseries quickstart figure 16.png|700px|center]]

===Step 7===
Repeat step 6 for the other bulkhead cables

[[File:Xseries quickstart figure 17.png|700px|center]]

[[File:Xseries quickstart figure 18.png|700px|center]]

===Step 8===
Install USRP cover with screws

[[File:Xseries quickstart figure 19.png|700px|center]]

===Step 9===
Connect the SFP 1 GigE adapter into USRP SFP port 0

[[File:Xseries quickstart figure 20.png|700px|center]]

[[File:Xseries quickstart figure 21.png|700px|center]]

===Step 10===
Connect the Gigabit Ethernet cable and power cord provided

[[File:Xseries quickstart figure 22.png|700px|center]]

===Step 11===
Attach any Antennas you may have purchased

[[File:Xseries quickstart figure 23.png|700px|center]]

===Step 12===
On the computer(host) you plan to use to connect to the USRP set the Ethernet adapter to have an IP address of 192.168.10.1 with a subnet mask of 255.255.255.0. Connect the other end of the Gigabit Ethernet cable to your computer.

[[File:Xseries quickstart figure 24.png|700px|center]]

===Step 13===
Power on the USRP (button on the front right of the USRP)

===Step 14===
Ping the device from host computer:

$ ping 192.168.10.2

[[File:Xseries quickstart figure 25.png|700px|center]]

===Step 15===
Assuming you have properly installed the UHD driver you can now run this command in a terminal/command window:

$ uhd_usrp_probe

This will tell you about the hardware inside of your USRP. The output will look like the following:

$ uhd_usrp_probe
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- Detecting internal GPSDO.... No GPSDO found
-- Initialize Radio0 control...
-- Performing register loopback test... pass
-- Initialize Radio1 control...
-- Performing register loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X300
| | revision: 7
| | revision_compat: 7
| | product: 30518
| | mac-addr0: ff:ff:ff:ff:ff:ff
| | mac-addr1: ff:ff:ff:ff:ff:ff
| | gateway: 255.255.255.255
| | ip-addr0: 255.255.255.255
| | subnet0: 255.255.255.255
| | ip-addr1: 255.255.255.255
| | subnet1: 255.255.255.255
| | ip-addr2: 255.255.255.255
| | subnet2: 255.255.255.255
| | ip-addr3: 255.255.255.255
| | subnet3: 255.255.255.255
| | serial: FFFFFFF
| | FW Version: 4.0
| | FPGA Version: 20.0
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None

==UBX daughterboard Installation Video==
The following link is a video of the steps to install the UBX daughterboard. The procedure is similar to what is outlined above.

*[https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing Video: UBX Installation into a USRP X-series device.]

==UHD FFT==
Try the UHD_FFT demo that comes with GNU Radio

1. Connect one antenna to RX2 on the left Daughterboard (Daughterboard A)

[[File:Xseries quickstart figure 26.png|700px|center]]

2.From the terminal/command window:

$ uhd_fft --ant RX2

[[File:Xseries quickstart figure 27.png|700px|center]]

[[File:Xseries quickstart figure 28.png|700px|center]]

==Success==
Congratulations! You have successfully setup and verified your new USRP X300/X310. A more detailed verification guide is at the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] application note. For additional step-by-step guides to using your USRP X300/X310, see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

USRP X Series Quick Start (Daughterboard Installation)

2020-04-28T19:50:12Z

JoseLoera: /* UBX daughterboard Installation Video */

==Application Note Number==
'''AN-904'''

==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
|
|-
|style="text-align:center;"| 2020-Apr-27
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added link to video on installing UBX board in a USRP X Series device to the Additional Resources section. Link [https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing here] as well
|}

==Abstract==
This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.

==Overview==
This Quick Start is meant to show you how to put together your new X300/310. We will start at the point when you have yet to unpack the boxes and go all the way to being able to ping the device, performing a quick software probe to verify hardware components and finally running a simple FFT demo. This Quick Start does not cover the installation of software on the host computer. If you have not installed UHD/Gnuradio on your system, please reference 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. You may also use the [[Live SDR Environment]] to perform the verification steps for your USRP. Detailed information on the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==Tools Required==
* Philips Screwdriver
* 5/16” wrench

==Pre-installed Software==
* UHD Latest
* GNU Radio

==Box Contents==
===USRP Box===
* 1 x USRP X300/X310
* 1 x SFP Adapter for 1 GigE
* 1 x Power Supply and US Cord
* 1 x USB 2.0 JTAG Debug Cable
* 1 x Gigabit Ethernet Cable
* 4 x SMA-Bulkhead Cables
* 16 x Daughterboard Screws
===Daughterboard Boxes===
* 2 x SBX Daughterboards
===Antenna Boxes===
* One or more Antennas

[[File:Xseries quickstart figure 1.png|700px|center]]

[[File:Xseries quickstart figure 2.png|700px|center]]

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Ettus Research recommends you perform the installation with no power to the USRP and using ESD equipment. Listed below are some examples of actions which can prevent damage to the unit:

*Never allow metal objects to touch the circuit board while powered.
*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the board with proper anti-static methods.
*Never allow the board to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the boards.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Installation Process==
===Step 1===
Unscrew the 2 screws on the top of the USRP and remove cover. (Lift up about 15 degrees and wiggle back as there
is a flange on the front part of the cover)

[[File:Xseries quickstart figure 3.png|700px|center]]

[[File:Xseries quickstart figure 4.png|700px|center]]

[[File:Xseries quickstart figure 5.png|700px|center]]

===Step 2===
Line up the 8 screw holes on the Daughterboard with the USRP Motherboard standoffs (they only go one way).

[[File:Xseries quickstart figure 6.png|700px|center]]

[[File:Xseries quickstart figure 7.png|700px|center]]

===Step 3===
After you have aligned the Daughterboard correctly you can press the Daughterboard on to the connectors below them (you will feel them snap into place).

[[File:Xseries quickstart figure 8.png|700px|center]]

[[File:Xseries quickstart figure 9.png|700px|center]]

===Step 4===
Put 8 of the screws provided in the daughterboard

[[File:Xseries quickstart figure 10.png|700px|center]]

===Step 5===
Repeat steps 2- 4 for the second Daughterboard

===Step 6===
It is recommended to connect the bulkhead cables one at a time to avoid confusion. The Daughterboards and front
panel of the X300/310 are clearly labeled as to which cable goes where.

[[File:Xseries quickstart figure 11.png|700px|center]]

[[File:Xseries quickstart figure 12.png|700px|center]]

[[File:Xseries quickstart figure 13.png|700px|center]]

[[File:Xseries quickstart figure 14.png|700px|center]]

[[File:Xseries quickstart figure 15.png|700px|center]]

[[File:Xseries quickstart figure 16.png|700px|center]]

===Step 7===
Repeat step 6 for the other bulkhead cables

[[File:Xseries quickstart figure 17.png|700px|center]]

[[File:Xseries quickstart figure 18.png|700px|center]]

===Step 8===
Install USRP cover with screws

[[File:Xseries quickstart figure 19.png|700px|center]]

===Step 9===
Connect the SFP 1 GigE adapter into USRP SFP port 0

[[File:Xseries quickstart figure 20.png|700px|center]]

[[File:Xseries quickstart figure 21.png|700px|center]]

===Step 10===
Connect the Gigabit Ethernet cable and power cord provided

[[File:Xseries quickstart figure 22.png|700px|center]]

===Step 11===
Attach any Antennas you may have purchased

[[File:Xseries quickstart figure 23.png|700px|center]]

===Step 12===
On the computer(host) you plan to use to connect to the USRP set the Ethernet adapter to have an IP address of 192.168.10.1 with a subnet mask of 255.255.255.0. Connect the other end of the Gigabit Ethernet cable to your computer.

[[File:Xseries quickstart figure 24.png|700px|center]]

===Step 13===
Power on the USRP (button on the front right of the USRP)

===Step 14===
Ping the device from host computer:

$ ping 192.168.10.2

[[File:Xseries quickstart figure 25.png|700px|center]]

===Step 15===
Assuming you have properly installed the UHD driver you can now run this command in a terminal/command window:

$ uhd_usrp_probe

This will tell you about the hardware inside of your USRP. The output will look like the following:

$ uhd_usrp_probe
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- Detecting internal GPSDO.... No GPSDO found
-- Initialize Radio0 control...
-- Performing register loopback test... pass
-- Initialize Radio1 control...
-- Performing register loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X300
| | revision: 7
| | revision_compat: 7
| | product: 30518
| | mac-addr0: ff:ff:ff:ff:ff:ff
| | mac-addr1: ff:ff:ff:ff:ff:ff
| | gateway: 255.255.255.255
| | ip-addr0: 255.255.255.255
| | subnet0: 255.255.255.255
| | ip-addr1: 255.255.255.255
| | subnet1: 255.255.255.255
| | ip-addr2: 255.255.255.255
| | subnet2: 255.255.255.255
| | ip-addr3: 255.255.255.255
| | subnet3: 255.255.255.255
| | serial: FFFFFFF
| | FW Version: 4.0
| | FPGA Version: 20.0
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None

==UBX daughterboard Installation Video==
The following link is a video of the steps to install the UBX daughterboard. The procedure is similar to what is outlined above.

*[https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing Video: UBX Installation into a USRP X-series device.]

==UHD FFT==
Try the UHD_FFT demo that comes with GNU Radio

1. Connect one antenna to RX2 on the left Daughterboard (Daughterboard A)

[[File:Xseries quickstart figure 26.png|700px|center]]

2.From the terminal/command window:

$ uhd_fft --ant RX2

[[File:Xseries quickstart figure 27.png|700px|center]]

[[File:Xseries quickstart figure 28.png|700px|center]]

==Success==
Congratulations! You have successfully setup and verified your new USRP X300/X310. A more detailed verification guide is at the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] application note. For additional step-by-step guides to using your USRP X300/X310, see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

==Additional Resources==
*[https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing Video link on installing UBX board in a USRP X Series device]

[[Category:Application Notes]]

USRP X Series Quick Start (Daughterboard Installation)

2020-04-28T19:48:50Z

JoseLoera: /* UHD FFT */

==Application Note Number==
'''AN-904'''

==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
|
|-
|style="text-align:center;"| 2020-Apr-27
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added link to video on installing UBX board in a USRP X Series device to the Additional Resources section. Link [https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing here] as well
|}

==Abstract==
This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.

==Overview==
This Quick Start is meant to show you how to put together your new X300/310. We will start at the point when you have yet to unpack the boxes and go all the way to being able to ping the device, performing a quick software probe to verify hardware components and finally running a simple FFT demo. This Quick Start does not cover the installation of software on the host computer. If you have not installed UHD/Gnuradio on your system, please reference 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. You may also use the [[Live SDR Environment]] to perform the verification steps for your USRP. Detailed information on the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==Tools Required==
* Philips Screwdriver
* 5/16” wrench

==Pre-installed Software==
* UHD Latest
* GNU Radio

==Box Contents==
===USRP Box===
* 1 x USRP X300/X310
* 1 x SFP Adapter for 1 GigE
* 1 x Power Supply and US Cord
* 1 x USB 2.0 JTAG Debug Cable
* 1 x Gigabit Ethernet Cable
* 4 x SMA-Bulkhead Cables
* 16 x Daughterboard Screws
===Daughterboard Boxes===
* 2 x SBX Daughterboards
===Antenna Boxes===
* One or more Antennas

[[File:Xseries quickstart figure 1.png|700px|center]]

[[File:Xseries quickstart figure 2.png|700px|center]]

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Ettus Research recommends you perform the installation with no power to the USRP and using ESD equipment. Listed below are some examples of actions which can prevent damage to the unit:

*Never allow metal objects to touch the circuit board while powered.
*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the board with proper anti-static methods.
*Never allow the board to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the boards.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Installation Process==
===Step 1===
Unscrew the 2 screws on the top of the USRP and remove cover. (Lift up about 15 degrees and wiggle back as there
is a flange on the front part of the cover)

[[File:Xseries quickstart figure 3.png|700px|center]]

[[File:Xseries quickstart figure 4.png|700px|center]]

[[File:Xseries quickstart figure 5.png|700px|center]]

===Step 2===
Line up the 8 screw holes on the Daughterboard with the USRP Motherboard standoffs (they only go one way).

[[File:Xseries quickstart figure 6.png|700px|center]]

[[File:Xseries quickstart figure 7.png|700px|center]]

===Step 3===
After you have aligned the Daughterboard correctly you can press the Daughterboard on to the connectors below them (you will feel them snap into place).

[[File:Xseries quickstart figure 8.png|700px|center]]

[[File:Xseries quickstart figure 9.png|700px|center]]

===Step 4===
Put 8 of the screws provided in the daughterboard

[[File:Xseries quickstart figure 10.png|700px|center]]

===Step 5===
Repeat steps 2- 4 for the second Daughterboard

===Step 6===
It is recommended to connect the bulkhead cables one at a time to avoid confusion. The Daughterboards and front
panel of the X300/310 are clearly labeled as to which cable goes where.

[[File:Xseries quickstart figure 11.png|700px|center]]

[[File:Xseries quickstart figure 12.png|700px|center]]

[[File:Xseries quickstart figure 13.png|700px|center]]

[[File:Xseries quickstart figure 14.png|700px|center]]

[[File:Xseries quickstart figure 15.png|700px|center]]

[[File:Xseries quickstart figure 16.png|700px|center]]

===Step 7===
Repeat step 6 for the other bulkhead cables

[[File:Xseries quickstart figure 17.png|700px|center]]

[[File:Xseries quickstart figure 18.png|700px|center]]

===Step 8===
Install USRP cover with screws

[[File:Xseries quickstart figure 19.png|700px|center]]

===Step 9===
Connect the SFP 1 GigE adapter into USRP SFP port 0

[[File:Xseries quickstart figure 20.png|700px|center]]

[[File:Xseries quickstart figure 21.png|700px|center]]

===Step 10===
Connect the Gigabit Ethernet cable and power cord provided

[[File:Xseries quickstart figure 22.png|700px|center]]

===Step 11===
Attach any Antennas you may have purchased

[[File:Xseries quickstart figure 23.png|700px|center]]

===Step 12===
On the computer(host) you plan to use to connect to the USRP set the Ethernet adapter to have an IP address of 192.168.10.1 with a subnet mask of 255.255.255.0. Connect the other end of the Gigabit Ethernet cable to your computer.

[[File:Xseries quickstart figure 24.png|700px|center]]

===Step 13===
Power on the USRP (button on the front right of the USRP)

===Step 14===
Ping the device from host computer:

$ ping 192.168.10.2

[[File:Xseries quickstart figure 25.png|700px|center]]

===Step 15===
Assuming you have properly installed the UHD driver you can now run this command in a terminal/command window:

$ uhd_usrp_probe

This will tell you about the hardware inside of your USRP. The output will look like the following:

$ uhd_usrp_probe
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- Detecting internal GPSDO.... No GPSDO found
-- Initialize Radio0 control...
-- Performing register loopback test... pass
-- Initialize Radio1 control...
-- Performing register loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X300
| | revision: 7
| | revision_compat: 7
| | product: 30518
| | mac-addr0: ff:ff:ff:ff:ff:ff
| | mac-addr1: ff:ff:ff:ff:ff:ff
| | gateway: 255.255.255.255
| | ip-addr0: 255.255.255.255
| | subnet0: 255.255.255.255
| | ip-addr1: 255.255.255.255
| | subnet1: 255.255.255.255
| | ip-addr2: 255.255.255.255
| | subnet2: 255.255.255.255
| | ip-addr3: 255.255.255.255
| | subnet3: 255.255.255.255
| | serial: FFFFFFF
| | FW Version: 4.0
| | FPGA Version: 20.0
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None

==UBX daughterboard Installation Video==
The following link is a video of the steps to install the UBX daughterboard. The procedure is similar to what is outlined above.

UBX Installation into a USRP X-series device.

==UHD FFT==
Try the UHD_FFT demo that comes with GNU Radio

1. Connect one antenna to RX2 on the left Daughterboard (Daughterboard A)

[[File:Xseries quickstart figure 26.png|700px|center]]

2.From the terminal/command window:

$ uhd_fft --ant RX2

[[File:Xseries quickstart figure 27.png|700px|center]]

[[File:Xseries quickstart figure 28.png|700px|center]]

==Success==
Congratulations! You have successfully setup and verified your new USRP X300/X310. A more detailed verification guide is at the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] application note. For additional step-by-step guides to using your USRP X300/X310, see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

==Additional Resources==
*[https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing Video link on installing UBX board in a USRP X Series device]

[[Category:Application Notes]]

USRP X Series Quick Start (Daughterboard Installation)

2020-04-27T23:02:35Z

JoseLoera: /* Success */

==Application Note Number==
'''AN-904'''

==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
|
|-
|style="text-align:center;"| 2020-Apr-27
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added link to video on installing UBX board in a USRP X Series device to the Additional Resources section. Link [https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing here] as well
|}

==Abstract==
This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.

==Overview==
This Quick Start is meant to show you how to put together your new X300/310. We will start at the point when you have yet to unpack the boxes and go all the way to being able to ping the device, performing a quick software probe to verify hardware components and finally running a simple FFT demo. This Quick Start does not cover the installation of software on the host computer. If you have not installed UHD/Gnuradio on your system, please reference 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. You may also use the [[Live SDR Environment]] to perform the verification steps for your USRP. Detailed information on the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==Tools Required==
* Philips Screwdriver
* 5/16” wrench

==Pre-installed Software==
* UHD Latest
* GNU Radio

==Box Contents==
===USRP Box===
* 1 x USRP X300/X310
* 1 x SFP Adapter for 1 GigE
* 1 x Power Supply and US Cord
* 1 x USB 2.0 JTAG Debug Cable
* 1 x Gigabit Ethernet Cable
* 4 x SMA-Bulkhead Cables
* 16 x Daughterboard Screws
===Daughterboard Boxes===
* 2 x SBX Daughterboards
===Antenna Boxes===
* One or more Antennas

[[File:Xseries quickstart figure 1.png|700px|center]]

[[File:Xseries quickstart figure 2.png|700px|center]]

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Ettus Research recommends you perform the installation with no power to the USRP and using ESD equipment. Listed below are some examples of actions which can prevent damage to the unit:

*Never allow metal objects to touch the circuit board while powered.
*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the board with proper anti-static methods.
*Never allow the board to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the boards.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Installation Process==
===Step 1===
Unscrew the 2 screws on the top of the USRP and remove cover. (Lift up about 15 degrees and wiggle back as there
is a flange on the front part of the cover)

[[File:Xseries quickstart figure 3.png|700px|center]]

[[File:Xseries quickstart figure 4.png|700px|center]]

[[File:Xseries quickstart figure 5.png|700px|center]]

===Step 2===
Line up the 8 screw holes on the Daughterboard with the USRP Motherboard standoffs (they only go one way).

[[File:Xseries quickstart figure 6.png|700px|center]]

[[File:Xseries quickstart figure 7.png|700px|center]]

===Step 3===
After you have aligned the Daughterboard correctly you can press the Daughterboard on to the connectors below them (you will feel them snap into place).

[[File:Xseries quickstart figure 8.png|700px|center]]

[[File:Xseries quickstart figure 9.png|700px|center]]

===Step 4===
Put 8 of the screws provided in the daughterboard

[[File:Xseries quickstart figure 10.png|700px|center]]

===Step 5===
Repeat steps 2- 4 for the second Daughterboard

===Step 6===
It is recommended to connect the bulkhead cables one at a time to avoid confusion. The Daughterboards and front
panel of the X300/310 are clearly labeled as to which cable goes where.

[[File:Xseries quickstart figure 11.png|700px|center]]

[[File:Xseries quickstart figure 12.png|700px|center]]

[[File:Xseries quickstart figure 13.png|700px|center]]

[[File:Xseries quickstart figure 14.png|700px|center]]

[[File:Xseries quickstart figure 15.png|700px|center]]

[[File:Xseries quickstart figure 16.png|700px|center]]

===Step 7===
Repeat step 6 for the other bulkhead cables

[[File:Xseries quickstart figure 17.png|700px|center]]

[[File:Xseries quickstart figure 18.png|700px|center]]

===Step 8===
Install USRP cover with screws

[[File:Xseries quickstart figure 19.png|700px|center]]

===Step 9===
Connect the SFP 1 GigE adapter into USRP SFP port 0

[[File:Xseries quickstart figure 20.png|700px|center]]

[[File:Xseries quickstart figure 21.png|700px|center]]

===Step 10===
Connect the Gigabit Ethernet cable and power cord provided

[[File:Xseries quickstart figure 22.png|700px|center]]

===Step 11===
Attach any Antennas you may have purchased

[[File:Xseries quickstart figure 23.png|700px|center]]

===Step 12===
On the computer(host) you plan to use to connect to the USRP set the Ethernet adapter to have an IP address of 192.168.10.1 with a subnet mask of 255.255.255.0. Connect the other end of the Gigabit Ethernet cable to your computer.

[[File:Xseries quickstart figure 24.png|700px|center]]

===Step 13===
Power on the USRP (button on the front right of the USRP)

===Step 14===
Ping the device from host computer:

$ ping 192.168.10.2

[[File:Xseries quickstart figure 25.png|700px|center]]

===Step 15===
Assuming you have properly installed the UHD driver you can now run this command in a terminal/command window:

$ uhd_usrp_probe

This will tell you about the hardware inside of your USRP. The output will look like the following:

$ uhd_usrp_probe
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- Detecting internal GPSDO.... No GPSDO found
-- Initialize Radio0 control...
-- Performing register loopback test... pass
-- Initialize Radio1 control...
-- Performing register loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X300
| | revision: 7
| | revision_compat: 7
| | product: 30518
| | mac-addr0: ff:ff:ff:ff:ff:ff
| | mac-addr1: ff:ff:ff:ff:ff:ff
| | gateway: 255.255.255.255
| | ip-addr0: 255.255.255.255
| | subnet0: 255.255.255.255
| | ip-addr1: 255.255.255.255
| | subnet1: 255.255.255.255
| | ip-addr2: 255.255.255.255
| | subnet2: 255.255.255.255
| | ip-addr3: 255.255.255.255
| | subnet3: 255.255.255.255
| | serial: FFFFFFF
| | FW Version: 4.0
| | FPGA Version: 20.0
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None

==UHD FFT==
Try the UHD_FFT demo that comes with GNU Radio

1. Connect one antenna to RX2 on the left Daughterboard (Daughterboard A)

[[File:Xseries quickstart figure 26.png|700px|center]]

2.From the terminal/command window:

$ uhd_fft --ant RX2

[[File:Xseries quickstart figure 27.png|700px|center]]

[[File:Xseries quickstart figure 28.png|700px|center]]

==Success==
Congratulations! You have successfully setup and verified your new USRP X300/X310. A more detailed verification guide is at the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] application note. For additional step-by-step guides to using your USRP X300/X310, see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

==Additional Resources==
*[https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing Video link on installing UBX board in a USRP X Series device]

[[Category:Application Notes]]

USRP X Series Quick Start (Daughterboard Installation)

2020-04-27T22:58:55Z

JoseLoera: /* Revision History */

==Application Note Number==
'''AN-904'''

==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
|
|-
|style="text-align:center;"| 2020-Apr-27
|style="text-align:center;"| Jose Loera
|style="text-align:center;"| Added link to video on installing UBX board in a USRP X Series device to the Additional Resources section. Link [https://drive.google.com/file/d/1cMMxuV_KZVrc5r-NOwNLI9JoaGM8aUIu/view?usp=sharing here] as well
|}

==Abstract==
This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.

==Overview==
This Quick Start is meant to show you how to put together your new X300/310. We will start at the point when you have yet to unpack the boxes and go all the way to being able to ping the device, performing a quick software probe to verify hardware components and finally running a simple FFT demo. This Quick Start does not cover the installation of software on the host computer. If you have not installed UHD/Gnuradio on your system, please reference 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. You may also use the [[Live SDR Environment]] to perform the verification steps for your USRP. Detailed information on the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==Tools Required==
* Philips Screwdriver
* 5/16” wrench

==Pre-installed Software==
* UHD Latest
* GNU Radio

==Box Contents==
===USRP Box===
* 1 x USRP X300/X310
* 1 x SFP Adapter for 1 GigE
* 1 x Power Supply and US Cord
* 1 x USB 2.0 JTAG Debug Cable
* 1 x Gigabit Ethernet Cable
* 4 x SMA-Bulkhead Cables
* 16 x Daughterboard Screws
===Daughterboard Boxes===
* 2 x SBX Daughterboards
===Antenna Boxes===
* One or more Antennas

[[File:Xseries quickstart figure 1.png|700px|center]]

[[File:Xseries quickstart figure 2.png|700px|center]]

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Ettus Research recommends you perform the installation with no power to the USRP and using ESD equipment. Listed below are some examples of actions which can prevent damage to the unit:

*Never allow metal objects to touch the circuit board while powered.
*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the board with proper anti-static methods.
*Never allow the board to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the boards.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Installation Process==
===Step 1===
Unscrew the 2 screws on the top of the USRP and remove cover. (Lift up about 15 degrees and wiggle back as there
is a flange on the front part of the cover)

[[File:Xseries quickstart figure 3.png|700px|center]]

[[File:Xseries quickstart figure 4.png|700px|center]]

[[File:Xseries quickstart figure 5.png|700px|center]]

===Step 2===
Line up the 8 screw holes on the Daughterboard with the USRP Motherboard standoffs (they only go one way).

[[File:Xseries quickstart figure 6.png|700px|center]]

[[File:Xseries quickstart figure 7.png|700px|center]]

===Step 3===
After you have aligned the Daughterboard correctly you can press the Daughterboard on to the connectors below them (you will feel them snap into place).

[[File:Xseries quickstart figure 8.png|700px|center]]

[[File:Xseries quickstart figure 9.png|700px|center]]

===Step 4===
Put 8 of the screws provided in the daughterboard

[[File:Xseries quickstart figure 10.png|700px|center]]

===Step 5===
Repeat steps 2- 4 for the second Daughterboard

===Step 6===
It is recommended to connect the bulkhead cables one at a time to avoid confusion. The Daughterboards and front
panel of the X300/310 are clearly labeled as to which cable goes where.

[[File:Xseries quickstart figure 11.png|700px|center]]

[[File:Xseries quickstart figure 12.png|700px|center]]

[[File:Xseries quickstart figure 13.png|700px|center]]

[[File:Xseries quickstart figure 14.png|700px|center]]

[[File:Xseries quickstart figure 15.png|700px|center]]

[[File:Xseries quickstart figure 16.png|700px|center]]

===Step 7===
Repeat step 6 for the other bulkhead cables

[[File:Xseries quickstart figure 17.png|700px|center]]

[[File:Xseries quickstart figure 18.png|700px|center]]

===Step 8===
Install USRP cover with screws

[[File:Xseries quickstart figure 19.png|700px|center]]

===Step 9===
Connect the SFP 1 GigE adapter into USRP SFP port 0

[[File:Xseries quickstart figure 20.png|700px|center]]

[[File:Xseries quickstart figure 21.png|700px|center]]

===Step 10===
Connect the Gigabit Ethernet cable and power cord provided

[[File:Xseries quickstart figure 22.png|700px|center]]

===Step 11===
Attach any Antennas you may have purchased

[[File:Xseries quickstart figure 23.png|700px|center]]

===Step 12===
On the computer(host) you plan to use to connect to the USRP set the Ethernet adapter to have an IP address of 192.168.10.1 with a subnet mask of 255.255.255.0. Connect the other end of the Gigabit Ethernet cable to your computer.

[[File:Xseries quickstart figure 24.png|700px|center]]

===Step 13===
Power on the USRP (button on the front right of the USRP)

===Step 14===
Ping the device from host computer:

$ ping 192.168.10.2

[[File:Xseries quickstart figure 25.png|700px|center]]

===Step 15===
Assuming you have properly installed the UHD driver you can now run this command in a terminal/command window:

$ uhd_usrp_probe

This will tell you about the hardware inside of your USRP. The output will look like the following:

$ uhd_usrp_probe
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- Detecting internal GPSDO.... No GPSDO found
-- Initialize Radio0 control...
-- Performing register loopback test... pass
-- Initialize Radio1 control...
-- Performing register loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X300
| | revision: 7
| | revision_compat: 7
| | product: 30518
| | mac-addr0: ff:ff:ff:ff:ff:ff
| | mac-addr1: ff:ff:ff:ff:ff:ff
| | gateway: 255.255.255.255
| | ip-addr0: 255.255.255.255
| | subnet0: 255.255.255.255
| | ip-addr1: 255.255.255.255
| | subnet1: 255.255.255.255
| | ip-addr2: 255.255.255.255
| | subnet2: 255.255.255.255
| | ip-addr3: 255.255.255.255
| | subnet3: 255.255.255.255
| | serial: FFFFFFF
| | FW Version: 4.0
| | FPGA Version: 20.0
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: SBX (0x0054)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: SBXv3 RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX DSP: 1
| | | Freq range: -100.000 to 100.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: SBX (0x0055)
| | | Serial: FFFFFF
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: SBXv3 TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 400.000 to 4400.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None

==UHD FFT==
Try the UHD_FFT demo that comes with GNU Radio

1. Connect one antenna to RX2 on the left Daughterboard (Daughterboard A)

[[File:Xseries quickstart figure 26.png|700px|center]]

2.From the terminal/command window:

$ uhd_fft --ant RX2

[[File:Xseries quickstart figure 27.png|700px|center]]

[[File:Xseries quickstart figure 28.png|700px|center]]

==Success==
Congratulations! You have successfully setup and verified your new USRP X300/X310. A more detailed verification guide is at the [[Verifying the Operation of the USRP Using UHD and GNU Radio]] application note. For additional step-by-step guides to using your USRP X300/X310, see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

[[Category:Application Notes]]

USRP-2974

2020-02-25T03:26:41Z

JoseLoera: /* System Block Diagrams */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [[UBX | UBX hardware resource]] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.14.1.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagrams===
[[file:2974_blk_dia_hiLevel_v01.png | 800px]]
<center>High Level Block Diagram of the USRP 2974</center>

[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ Detailed System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 25 ppb
± 25 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed for a specific application.

[[Category:Hardware Resources]]

File:2974 blk dia hiLevel v01.png

2020-02-25T03:24:16Z

JoseLoera: USRP-2974 High Level Block Diagram

USRP-2974 High Level Block Diagram

USRP-2974

2020-02-25T03:22:56Z

JoseLoera: /* System Block Diagram */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [[UBX | UBX hardware resource]] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.14.1.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagrams===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ Detailed System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 25 ppb
± 25 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed for a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T18:43:05Z

JoseLoera: /* FAQ */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [[UBX | UBX hardware resource]] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ Detailed System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed for a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T18:39:22Z

JoseLoera: /* System Block Diagram */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [[UBX | UBX hardware resource]] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ Detailed System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T18:37:57Z

JoseLoera: /* RF Specifications */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [[UBX | UBX hardware resource]] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974 Getting Started Guide

2019-06-01T15:16:29Z

JoseLoera: /* Kit Contents */

==Kit Contents==
* NI USRP-2974
* 30 dB SMA Attenuator
* SMA-male to SMA-male Cable
* Power Supply
* Getting Started Guide
{|
||[[File:USRP_2974_frt_dia.jpg|300px|center]]
|}

 
 
 

==Verify the Contents of Your Kit==
Make sure that your kit contains all the items listed above. If any items are missing, please contact your sales agent.

==Unpacking the Kit==
1. To prevent electrostatic discharge (ESD) from damaging the device, ground yourself using a grounding strap or by holding a grounded object, such as your computer chassis.

2. Remove the device from the package and inspect the device for loose components or any
other sign of damage.

3. Never touch the exposed pins of connectors.

4. Unpack any other items and documentation from the kit.

'''NOTE:''' Do not install a device if it appears damaged in any way. Store the device in the antistatic package when the device is not in use.

==Proper Care and Handling==
All NI products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Listed below are some examples of actions which can prevent damage to the unit:

*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the USRP with proper anti-static methods.
*Never allow the USRP to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the USRP.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+10 dBm''' of power into RF ports RF0 and RF1.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+15 dBm''' of power into the REF IN input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''-15 dBm''' of power into the GPS ANT input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Install and Setup the Software Tools on the onboard computer (SoM-System on Module)==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on the SoM. A step-by-step guide for doing this is available at the [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on the Linux] Application Note. '''Release 3.15.0''' or later of the USRP Hardware Driver, UHD, is needed.

==Basic Connectivity==
This USRP-2974 host supports multiple, high-speed, low-latency interface options to the FPGA. To setup the device, follow these basic instructions:
* Configure the host ethernet adapter (enp1s0f0) to use an IP address of 192.168.40.1 and a subnet mask of 255.255.255.0
* Configure the host ethernet adapter (enp1s0f1) to use an IP address of 192.168.30.1 and a subnet mask of 255.255.255.0 (loopback with SFP+ cable needed)
* To test communications, ping the USRP FPGA at address "192.168.40.2" or “192.168.30.2”

For more details on network setup, including PCIe connectivity, please see the section [[USRP-2974#Interfaces_and_Connectivity|Interfaces and Connectivity]] of the NI USRP-2974 Hardware Resources page.

==Test and Verify the Operation of the USRP==
Once the software tools are installed on the onboard computer, verify the correct operation of the USRP by running the utility programs on the onboard computer. More information is available at the [https://kb.ettus.com/Verifying_the_Operation_of_the_USRP_Using_UHD_and_GNU_Radio Verifying the Operation of the USRP Using UHD and GNU Radio] Application Note.

==Enabling PXE Boot==

===Legacy PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with Legacy option, restart the system
* Go into the BIOS’ Boot tab and set IBA CL Slot 00FE v0105 as first boot option, restart the system

===UEFI PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with UEFI option, restart the system
* Go into the BIOS’ Boot tab and set IPv4 as first boot option, restart the system

==NI USRP RIO PCIe Support==

If you are connecting the USRP-2974 through the PCIe interface, then complete this section.

If you are connecting the USRP-2974 through the 1G or 10G Ethernet connection then do '''NOT''' complete this section.

# Installer and commands taken from [https://files.ettus.com/manual/page_ni_rio_kernel.html https://files.ettus.com/manual/page_ni_rio_kernel.html]
# Extract the installer and install as described (note the _ instead of – in the folder name)
# Enable or disable the PCIe link
##<code>$ sudo /usr/local/bin/niusrprio_pcie start</code>
##<code>$ sudo /usr/local/bin/niusrprio_pcie stop </code>
# Check the status
##<code>$ sudo /usr/local/bin/niusrprio_pcie status</code>
# see the connection over PCIe with
##<code>$ uhd_find_devices</code>

==Note on USRP-2974 Rev A Hardware==
To find out if you have a '''"Rev A"''' hardware version of the USRP-2974 check the last character of the part number on the USRP-2974. E.g. "146873'''A'''"

To fully support Rev A with UHD software, install UHD as explained and run the following command:

$ /usr/local/lib/uhd/utils/usrp_burn_mb_eeprom --args=”addr=192.168.40.2” --value=”product=31131”

After a reboot run:

$ uhd_find_devices</code>

Under the product category section you will see the following:
“NI-2974”.

==Technical Support and Community Knowledge Base==

Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==

If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com]. Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

==Additional Resources==

* [[USRP-2974 | USRP-2974 Hardware Resource]]
* http://www.ni.com/pdf/manuals/377416c.pdf

[[Category:Getting Started Guides]]

USRP-2974 Getting Started Guide

2019-06-01T15:15:44Z

JoseLoera: /* Kit Contents */

==Kit Contents==
* NI USRP-2974
* 30 dB SMA Attenuator
* SMA-male to SMA-male Cable
* Power Supply
* Getting Started Guide
{|
||[[File:USRP_2974_frt_dia.jpg|250px|center]]
|}

 
 
 

==Verify the Contents of Your Kit==
Make sure that your kit contains all the items listed above. If any items are missing, please contact your sales agent.

==Unpacking the Kit==
1. To prevent electrostatic discharge (ESD) from damaging the device, ground yourself using a grounding strap or by holding a grounded object, such as your computer chassis.

2. Remove the device from the package and inspect the device for loose components or any
other sign of damage.

3. Never touch the exposed pins of connectors.

4. Unpack any other items and documentation from the kit.

'''NOTE:''' Do not install a device if it appears damaged in any way. Store the device in the antistatic package when the device is not in use.

==Proper Care and Handling==
All NI products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Listed below are some examples of actions which can prevent damage to the unit:

*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the USRP with proper anti-static methods.
*Never allow the USRP to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the USRP.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+10 dBm''' of power into RF ports RF0 and RF1.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+15 dBm''' of power into the REF IN input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''-15 dBm''' of power into the GPS ANT input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Install and Setup the Software Tools on the onboard computer (SoM-System on Module)==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on the SoM. A step-by-step guide for doing this is available at the [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on the Linux] Application Note. '''Release 3.15.0''' or later of the USRP Hardware Driver, UHD, is needed.

==Basic Connectivity==
This USRP-2974 host supports multiple, high-speed, low-latency interface options to the FPGA. To setup the device, follow these basic instructions:
* Configure the host ethernet adapter (enp1s0f0) to use an IP address of 192.168.40.1 and a subnet mask of 255.255.255.0
* Configure the host ethernet adapter (enp1s0f1) to use an IP address of 192.168.30.1 and a subnet mask of 255.255.255.0 (loopback with SFP+ cable needed)
* To test communications, ping the USRP FPGA at address "192.168.40.2" or “192.168.30.2”

For more details on network setup, including PCIe connectivity, please see the section [[USRP-2974#Interfaces_and_Connectivity|Interfaces and Connectivity]] of the NI USRP-2974 Hardware Resources page.

==Test and Verify the Operation of the USRP==
Once the software tools are installed on the onboard computer, verify the correct operation of the USRP by running the utility programs on the onboard computer. More information is available at the [https://kb.ettus.com/Verifying_the_Operation_of_the_USRP_Using_UHD_and_GNU_Radio Verifying the Operation of the USRP Using UHD and GNU Radio] Application Note.

==Enabling PXE Boot==

===Legacy PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with Legacy option, restart the system
* Go into the BIOS’ Boot tab and set IBA CL Slot 00FE v0105 as first boot option, restart the system

===UEFI PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with UEFI option, restart the system
* Go into the BIOS’ Boot tab and set IPv4 as first boot option, restart the system

==NI USRP RIO PCIe Support==

If you are connecting the USRP-2974 through the PCIe interface, then complete this section.

If you are connecting the USRP-2974 through the 1G or 10G Ethernet connection then do '''NOT''' complete this section.

# Installer and commands taken from [https://files.ettus.com/manual/page_ni_rio_kernel.html https://files.ettus.com/manual/page_ni_rio_kernel.html]
# Extract the installer and install as described (note the _ instead of – in the folder name)
# Enable or disable the PCIe link
##<code>$ sudo /usr/local/bin/niusrprio_pcie start</code>
##<code>$ sudo /usr/local/bin/niusrprio_pcie stop </code>
# Check the status
##<code>$ sudo /usr/local/bin/niusrprio_pcie status</code>
# see the connection over PCIe with
##<code>$ uhd_find_devices</code>

==Note on USRP-2974 Rev A Hardware==
To find out if you have a '''"Rev A"''' hardware version of the USRP-2974 check the last character of the part number on the USRP-2974. E.g. "146873'''A'''"

To fully support Rev A with UHD software, install UHD as explained and run the following command:

$ /usr/local/lib/uhd/utils/usrp_burn_mb_eeprom --args=”addr=192.168.40.2” --value=”product=31131”

After a reboot run:

$ uhd_find_devices</code>

Under the product category section you will see the following:
“NI-2974”.

==Technical Support and Community Knowledge Base==

Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==

If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com]. Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

==Additional Resources==

* [[USRP-2974 | USRP-2974 Hardware Resource]]
* http://www.ni.com/pdf/manuals/377416c.pdf

[[Category:Getting Started Guides]]

USRP-2974

2019-06-01T15:14:58Z

JoseLoera: /* Controller - Onboard computer */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T15:14:36Z

JoseLoera: /* Controller - Onboard computer */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 


==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T15:14:18Z

JoseLoera: /* Controller - Onboard computer */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974 Getting Started Guide

2019-06-01T15:11:18Z

JoseLoera: /* Additional Resources */

==Kit Contents==
* NI USRP-2974
* 30 dB SMA Attenuator
* SMA-male to SMA-male Cable
* Power Supply
* Getting Started Guide
{|
||[[File:USRP_2974_frt_dia.jpg|250px|center]]
|}

==Verify the Contents of Your Kit==
Make sure that your kit contains all the items listed above. If any items are missing, please contact your sales agent.

==Unpacking the Kit==
1. To prevent electrostatic discharge (ESD) from damaging the device, ground yourself using a grounding strap or by holding a grounded object, such as your computer chassis.

2. Remove the device from the package and inspect the device for loose components or any
other sign of damage.

3. Never touch the exposed pins of connectors.

4. Unpack any other items and documentation from the kit.

'''NOTE:''' Do not install a device if it appears damaged in any way. Store the device in the antistatic package when the device is not in use.

==Proper Care and Handling==
All NI products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Listed below are some examples of actions which can prevent damage to the unit:

*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the USRP with proper anti-static methods.
*Never allow the USRP to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the USRP.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+10 dBm''' of power into RF ports RF0 and RF1.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+15 dBm''' of power into the REF IN input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''-15 dBm''' of power into the GPS ANT input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Install and Setup the Software Tools on the onboard computer (SoM-System on Module)==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on the SoM. A step-by-step guide for doing this is available at the [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on the Linux] Application Note. '''Release 3.15.0''' or later of the USRP Hardware Driver, UHD, is needed.

==Basic Connectivity==
This USRP-2974 host supports multiple, high-speed, low-latency interface options to the FPGA. To setup the device, follow these basic instructions:
* Configure the host ethernet adapter (enp1s0f0) to use an IP address of 192.168.40.1 and a subnet mask of 255.255.255.0
* Configure the host ethernet adapter (enp1s0f1) to use an IP address of 192.168.30.1 and a subnet mask of 255.255.255.0 (loopback with SFP+ cable needed)
* To test communications, ping the USRP FPGA at address "192.168.40.2" or “192.168.30.2”

For more details on network setup, including PCIe connectivity, please see the section [[USRP-2974#Interfaces_and_Connectivity|Interfaces and Connectivity]] of the NI USRP-2974 Hardware Resources page.

==Test and Verify the Operation of the USRP==
Once the software tools are installed on the onboard computer, verify the correct operation of the USRP by running the utility programs on the onboard computer. More information is available at the [https://kb.ettus.com/Verifying_the_Operation_of_the_USRP_Using_UHD_and_GNU_Radio Verifying the Operation of the USRP Using UHD and GNU Radio] Application Note.

==Enabling PXE Boot==

===Legacy PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with Legacy option, restart the system
* Go into the BIOS’ Boot tab and set IBA CL Slot 00FE v0105 as first boot option, restart the system

===UEFI PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with UEFI option, restart the system
* Go into the BIOS’ Boot tab and set IPv4 as first boot option, restart the system

==NI USRP RIO PCIe Support==

If you are connecting the USRP-2974 through the PCIe interface, then complete this section.

If you are connecting the USRP-2974 through the 1G or 10G Ethernet connection then do '''NOT''' complete this section.

# Installer and commands taken from [https://files.ettus.com/manual/page_ni_rio_kernel.html https://files.ettus.com/manual/page_ni_rio_kernel.html]
# Extract the installer and install as described (note the _ instead of – in the folder name)
# Enable or disable the PCIe link
##<code>$ sudo /usr/local/bin/niusrprio_pcie start</code>
##<code>$ sudo /usr/local/bin/niusrprio_pcie stop </code>
# Check the status
##<code>$ sudo /usr/local/bin/niusrprio_pcie status</code>
# see the connection over PCIe with
##<code>$ uhd_find_devices</code>

==Note on USRP-2974 Rev A Hardware==
To find out if you have a '''"Rev A"''' hardware version of the USRP-2974 check the last character of the part number on the USRP-2974. E.g. "146873'''A'''"

To fully support Rev A with UHD software, install UHD as explained and run the following command:

$ /usr/local/lib/uhd/utils/usrp_burn_mb_eeprom --args=”addr=192.168.40.2” --value=”product=31131”

After a reboot run:

$ uhd_find_devices</code>

Under the product category section you will see the following:
“NI-2974”.

==Technical Support and Community Knowledge Base==

Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==

If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com]. Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

==Additional Resources==

* [[USRP-2974 | USRP-2974 Hardware Resource]]
* http://www.ni.com/pdf/manuals/377416c.pdf

[[Category:Getting Started Guides]]

USRP-2974 Getting Started Guide

2019-06-01T15:10:32Z

JoseLoera: /* Basic Connectivity */

==Kit Contents==
* NI USRP-2974
* 30 dB SMA Attenuator
* SMA-male to SMA-male Cable
* Power Supply
* Getting Started Guide
{|
||[[File:USRP_2974_frt_dia.jpg|250px|center]]
|}

==Verify the Contents of Your Kit==
Make sure that your kit contains all the items listed above. If any items are missing, please contact your sales agent.

==Unpacking the Kit==
1. To prevent electrostatic discharge (ESD) from damaging the device, ground yourself using a grounding strap or by holding a grounded object, such as your computer chassis.

2. Remove the device from the package and inspect the device for loose components or any
other sign of damage.

3. Never touch the exposed pins of connectors.

4. Unpack any other items and documentation from the kit.

'''NOTE:''' Do not install a device if it appears damaged in any way. Store the device in the antistatic package when the device is not in use.

==Proper Care and Handling==
All NI products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Listed below are some examples of actions which can prevent damage to the unit:

*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the USRP with proper anti-static methods.
*Never allow the USRP to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the USRP.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+10 dBm''' of power into RF ports RF0 and RF1.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+15 dBm''' of power into the REF IN input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''-15 dBm''' of power into the GPS ANT input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Install and Setup the Software Tools on the onboard computer (SoM-System on Module)==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on the SoM. A step-by-step guide for doing this is available at the [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on the Linux] Application Note. '''Release 3.15.0''' or later of the USRP Hardware Driver, UHD, is needed.

==Basic Connectivity==
This USRP-2974 host supports multiple, high-speed, low-latency interface options to the FPGA. To setup the device, follow these basic instructions:
* Configure the host ethernet adapter (enp1s0f0) to use an IP address of 192.168.40.1 and a subnet mask of 255.255.255.0
* Configure the host ethernet adapter (enp1s0f1) to use an IP address of 192.168.30.1 and a subnet mask of 255.255.255.0 (loopback with SFP+ cable needed)
* To test communications, ping the USRP FPGA at address "192.168.40.2" or “192.168.30.2”

For more details on network setup, including PCIe connectivity, please see the section [[USRP-2974#Interfaces_and_Connectivity|Interfaces and Connectivity]] of the NI USRP-2974 Hardware Resources page.

==Test and Verify the Operation of the USRP==
Once the software tools are installed on the onboard computer, verify the correct operation of the USRP by running the utility programs on the onboard computer. More information is available at the [https://kb.ettus.com/Verifying_the_Operation_of_the_USRP_Using_UHD_and_GNU_Radio Verifying the Operation of the USRP Using UHD and GNU Radio] Application Note.

==Enabling PXE Boot==

===Legacy PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with Legacy option, restart the system
* Go into the BIOS’ Boot tab and set IBA CL Slot 00FE v0105 as first boot option, restart the system

===UEFI PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with UEFI option, restart the system
* Go into the BIOS’ Boot tab and set IPv4 as first boot option, restart the system

==NI USRP RIO PCIe Support==

If you are connecting the USRP-2974 through the PCIe interface, then complete this section.

If you are connecting the USRP-2974 through the 1G or 10G Ethernet connection then do '''NOT''' complete this section.

# Installer and commands taken from [https://files.ettus.com/manual/page_ni_rio_kernel.html https://files.ettus.com/manual/page_ni_rio_kernel.html]
# Extract the installer and install as described (note the _ instead of – in the folder name)
# Enable or disable the PCIe link
##<code>$ sudo /usr/local/bin/niusrprio_pcie start</code>
##<code>$ sudo /usr/local/bin/niusrprio_pcie stop </code>
# Check the status
##<code>$ sudo /usr/local/bin/niusrprio_pcie status</code>
# see the connection over PCIe with
##<code>$ uhd_find_devices</code>

==Note on USRP-2974 Rev A Hardware==
To find out if you have a '''"Rev A"''' hardware version of the USRP-2974 check the last character of the part number on the USRP-2974. E.g. "146873'''A'''"

To fully support Rev A with UHD software, install UHD as explained and run the following command:

$ /usr/local/lib/uhd/utils/usrp_burn_mb_eeprom --args=”addr=192.168.40.2” --value=”product=31131”

After a reboot run:

$ uhd_find_devices</code>

Under the product category section you will see the following:
“NI-2974”.

==Technical Support and Community Knowledge Base==

Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==

If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com]. Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

==Additional Resources==

* [[NI_USRP-2974_Hardware_Resource_00 | USRP-2974 Hardware Resource]]
* http://www.ni.com/pdf/manuals/377416c.pdf

[[Category:Getting Started Guides]]

USRP-2974

2019-06-01T15:08:56Z

JoseLoera: /* Front Panel */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 


==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T15:07:25Z

JoseLoera: /* Front Panel */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 


==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T15:04:10Z

JoseLoera: /* Option: Using the GPIO Expansion Kit */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 


==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Product_x3x0_gpio.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T15:02:45Z

JoseLoera: /* Controller - Onboard computer */

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 


==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Gpio_expan.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

USRP-2974

2019-06-01T15:02:12Z

JoseLoera: Created page with "== Device Overview == The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communi..."

== Device Overview ==
The NI USRP-2974 is a high-performance, USRP software defined radio (SDR) stand-alone device for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering 10 MHz – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE), an onboard Intel Core i7 processor, and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 2U form factor.

The USRP-2974 is the equivalent to a USRP X310 with two UBX-160 boards, a GPSDO and an onboard Intel i7 computer. The USRP-2974 comes with NI Linux RTOS pre-installed, but in order to use it with open-source tool-chain, a user will need to install Linux (preferably Fedora or Ubuntu) and then the USRP Hardware driver (UHD). After these have been installed, any other open-source tools can be installed, such as GNU Radio.

== Key Features of the USRP-2974==
{|
|style="vertical-align:top"|
* Intel Core i7 6822EQ 2GHz Quad CoreProcessor
* 16GB DDR4 Memory
* 512GB SSD
* USB-to-UART to the CPU
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: 10 MHz - 6 GHz
* Up 160MHz* bandwidth per channel
* 2 Transmit ports
* 2 Receive ports
* GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, 1G)
|[[File:USRP_2974_frt_dia.jpg|350px|center]]
|}

== Controller - Onboard computer ==
{| class="wikitable"

|System on module (SoM)
|Congatec COM Express conga-TS170
|-

|CPU
|Intel Core i7 6822EQ (2 GHz Quad Core)
|-

|Memory
|SO-DIMM DDR4 16 GB
|-

|SFP+1
|10G ETH connection to the SoM
|-

|Cabled PCIe
|PCIe Gen 2 x4
|-

|MicroUSB2
|USB-to-UART to the SoM
|-

|RJ45
|1G ETH host connection
|-

|}

1 Can be bypassed to the FPGA.

2 Device port for external host.

 
 
 
 
 

==RF Specifications==

{| class="wikitable"
|-
!colspan="2"|Transmitter
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Maximum output power
|5mW to 100mW (7dBm to 20dBm)
|-
|Gain range1
|0dB to 31.5dB
|-
|Gain step
|0.5dB
|-
|Maximum instantaneous real-time bandwidth
|160MHz
|-
|}

{| class="wikitable"
|-
!colspan="2"|Receiver
|-
|Number of channels
|2
|-
|Frequency range
|10MHz to 6GHz
|-
|Frequency step
|<1kHz
|-
|Gain range2
|0dB to 37.5dB
|-
|Gain step
|0.5dB
|-
|Maximum input power
|10dBm
|-
|Noise Figure
|5dB to 7dB
|-
|Maximum instantaneous real-time bandwidth3
|160MHz                                        
|-
|}
1 The output power resulting from the gain setting varies over the frequency band and among
devices.

2The received signal amplitude resulting from the gain setting varies over the frequency band and
among devices.

3The USRP-2974 receiver path has 84 MHz of bandwidth for center frequencies from 10 MHz to
500 MHz

'''NOTE:''' As mentioned earlier, the USRP-2974 incorporates 2 UBX-160 daughterboards. Therefore, for more information on RF performance, please see the [https://kb.ettus.com/UBX UBX hardware resource] page

==Hardware Specifications==
===USRP Hardware Driver (UHD) version===
* Minimum version of UHD required: '''3.15.0'''

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the USRP-2974 like on the X310: 200.0 MHz and 184.32 MHz.

The sampling rate must be an integer decimation rate of the MCR. Ideally, this decimation factor should be an even number. An odd decimation factor will result in additional unwanted attenuation (roll-off from the CIC filter in the DUC and DDC blocks in the FPGA). The valid decimation rates are between 1 and 1024.

For the MCR of 200.0 MHz, the achievable sampling rates using an even decimation factor are 200.0, 100.0, 50.0, 33.33, 25.0, 20.0, 16.67, 14.286 Msps, ... 195.31 Ksps.

For the MCR of 184.32 MHz, the achievable sampling rates using an even decimation factor are 184.32, 92.16, 46.08, 30.72, 23.04, 18.432, 15.36, 13.166 Msps, ... 180.0 Ksps.

If the desired sampling rate is not directly supported by the hardware, then it will be necessary to re-sample in software. This can be done in C++ using libraries such as Liquid DSP [https://github.com/jgaeddert/liquid-dsp], or can be done in GNU Radio, in which there are three blocks that perform sampling rate conversion.

==Physical Specifications==

===Dimensions===
(L × W × H) 29.08 cm × 21.84 cm × 7.98 cm (11.45 in. × 8.60 in. × 3.14 in. )

===Weight===
3.34 kg (7.35 lb)

==Power==
{| class="wikitable"

|Voltage range
|14.25 V to 15.75 V DC
|-

|Current
|10 A, maximum
|-

|Power
|150 W, maximum
|-

|}

==Environmental Specifications==

'''NOTE:''' Indoor use only

===Operating Temperature Range===
* 0 °C to 50 °C

===Maximum altitude===
* 2,000 m (800 mbar) (at 25 °C ambient temperature)

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

===Pollution Degree===
* 2

==System Diagram and Schematics==

===System Block Diagram===
[[file:2974_blk_dia.png |800px]]

<center>[http://www.ni.com/documentation/en/usrp-software-defined-radio-stand-alone-device/latest/usrp-2974/block-diagram/ System Block Diagram]</center>

===Schematics===
Because the USRP-2974 is a combination of an Intel i7 SOM and an X310 USRP, a user can reference the X310 Schematics.

[http://files.ettus.com/schematics/x300/x3xx.pdf X310 Schematics]

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

|[https://www.congatec.com/fileadmin/user_upload/Documents/Datasheets/conga-TS170.pdf conga-TS170]
|System on Module (SoM)
|
|-

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K410T]
|FPGA
|U23 (3,5,8,9,10,18)
|-

|[http://www.analog.com/media/en/technical-documentation/data-sheets/AD9146.PDF AD9146]
|Dual Channel, 16-Bit, 1230 MSPS DAC
|U12, U36 (7)
|-

|[http://www.ti.com/lit/ds/slas635b/slas635b.pdf ADS62P48]
|Dual Channel, 14-Bit 210 MSPS ADC
|U11, U35 (6)
|-

|[https://www.onsemi.com/pub/Collateral/FIN1002-D.pdf FIN1002]
|High Speed Differential Receiver
|U3, U5, U31, U32 (4)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/20001203U.pdf 24LC256T]
|EEPROM
|U530 (11)
|-

|[http://www.ti.com/lit/ds/symlink/lmk04816.pdf LMK04816BISQ/NOPB_1/3]
|Jitter Cleaner With Dual Loop PLLs
|U531 (11)
|-

|[http://ww1.microchip.com/downloads/en/DeviceDoc/sy89547l.pdf SY89547LMGTR]
|Multiplexer
|U506 (12)
|-

|[http://www.ti.com/lit/ds/symlink/sn74aup1t17.pdf SN74AUP1T17]
|Single Schmitt-Trigger Buffer Gate
|U6, U519 (12)
|-

|[http://www.ti.com/lit/ds/symlink/tps54620.pdf TPS54620RGYT]
|Synchronous Step Down SWIFT™ Converter
|U515 (21); U516 (26)
|-

|[http://cds.linear.com/docs/en/datasheet/1764fb.pdf LT1764EQ-3.3]
|Voltage Regulator
|U27 (21); U516 (26)
|-

|[http://www.ti.com/lit/ds/symlink/tps7a47.pdf TPS7A47]
|Voltage Regulator
|U28, U532 (21)
|-

|[http://cds.linear.com/docs/en/datasheet/3603fc.pdf LTC3603EUF_TRPBF]
|Monolithic Synchronous Step-Down Regulator
|U517 (23); U500 (25); U514, U513 (27)
|-

|[http://www.ti.com/product/TPS77625-EP?keyMatch=TPS77625&tisearch=Search-EN-Everything TPS77625]
|Low-Dropout Voltage Regulators
|U30 (23)
|-

|[http://www.ti.com/lit/ds/symlink/tps79318-ep.pdf TPS79318_SM]
|Low-Dropout Voltage Regulators
|U510 (27)
|-

|[[Media:agile9598503.pdf|OSC-96MHZ-724821-01]]
|Voltage Controlled Crystal Oscillator
|U25 (11)
|-

|}

==FPGA and Baseband==

{| class="wikitable"

|FPGA
|Kintex-7 XC7K410T
|-

|DRAM
|1 GB
|-

|Baseband analog-to-digital converter
(ADC) resolution
|14 bit
|-

|Baseband digital-to-analog converter
(DAC) resolution
|16 bit
|-

|ADC spurious-free dynamic range (sFDR)
|88 dB
|-

|DAC sFDR
|80 dB
|-

|Maximum I/Q sample rate
|200 MS/s
|-

|SFP+1
|High speed serial link to one of the FPGA
GTX transceivers
|-

|}

1Can be bypassed to the SoM if using the 10 GbE as protocol.

===FPGA User Modifications===

The Verilog code for the FPGA in the NI USRP-2974 is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Specifically, changing the I/O interface of the FPGA in any way (do not remove any of the I/O for the PCIe interface, such as <code>x300_pcie_int</code> and <code>LvFpga_Chinch_Interface</code>), or modifying the pin and timing constraint files, could result in physical damage to other components on the motherboard, external to the FPGA, and doing this will void the warranty. Also, even if the PCIe interface is not being used, you cannot remove or reassign these pins in the constraint file. The constraint files should not be modified. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP-2974.

*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_10gige Dual 10 Gigabit Ethernet] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_pcie PCIe Express (Desktop)] - 200 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===

[[File:USRP-2974 Front Panel.jpg|800px]]
[[File:2974_frt_wireframe.png|800px]]

{| class="wikitable"
!Connector
!colspan="2" | '''Use'''
|-
|rowspan="2" | RF 0
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | AUX I/O
|General-purpose I/O (GPIO) port. AUX I/O is controlled by the FPGA.
|-

|rowspan="2" | RF 1
|TX1RX1
|Input and output terminal for the RF signal. TX1 RX1 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input or output channel.
|-
|RX2
|Input terminal for the RF signal. RX2 is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel.
|-

|colspan="2" | DP
|DisplayPort connector to connect one monitor for your controller.
|-

|colspan="2" | USB2.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | USB3.0
|USB ports that support common USB peripheral devices such as flash drives, hard drives, keyboards, and mice.
|-

|colspan="2" | 1G ETH
|RJ45 port used for 1G ETH connectivity to other ethernet devices.
|-

|colspan="2" | μUSB
|USB port used for UART connectivity to the controller.
|-

|colspan="2" | 1G/10G ETH 0
|SFP+ port used for 10G ETH connectivity to other ethernet devices. Connects to the embedded Linux computer for communication with LabVIEW RT.
|-

|colspan="2" | 1G/10G ETH 1
|SFP+ port used for 1G/10G ETH connectivity to other ethernet devices. Connects to the FPGA. Not currently supported in LabVIEW Communications System Design Suite.
|-

|}

{| class="wikitable"
!colspan="2" | '''LED'''
!'''Description'''
!'''Color'''
!'''State'''
!'''Indication'''
|-
|rowspan="5" | RF 0
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="3" colspan="2"| REF
|rowspan="3" | Indicates the status of the reference signal.
|OFF
| —
|There is no reference signal, or the device is not locked to the reference signal.
|-
|rowspan="2" |Green
|Blinking
|The device is not locked to the reference signal.
|-
|Solid
|The device is locked to the reference signal.
|-

|rowspan="2" colspan="2"| PPS
|rowspan="2" | Indicates the pulse per second (PPS).
|OFF
| —
|There is no PPS timing reference signal, or the device is not locked to the reference signal.
|-
|Green
|Blinking
|The device is locked to the PPS timing reference signal.
|-

|rowspan="2" colspan="2"| GPS
|rowspan="2" | Indicates whether the GPSDO is locked.
|OFF
| —
|There is no GPSDO or the GPSDO is not locked.
|-
|Green
|Solid
|The GPSDO is locked.
|-

|rowspan="5" | RF 1
|rowspan="3" | TX1RX1
|rowspan="3" | Indicates thetransmit status of the device
|OFF
| —
|The device is not active.
|-
|Red
|Solid
|The device is transmitting data.
|-
|Green
|Solid
|The device is receiving data.
|-
|rowspan="2" | RX2
|rowspan="2" | Indicates the receive status of the device.
|OFF
| —
|The device is not receiving data.
|-
|Green
|Solid
|The device is receiving data.
|-

|rowspan="2" colspan="2"| Status
|rowspan="2" | Indicates the status of the device
|OFF
| —
|The device initialized successfully and is ready for use.
|-
|Red
|Blinking
|Hardware error. An internal power supply has failed. Check front-panel I/O connections for shorts. Remove any shorts and cycle power to the USRP-2974. Contact NI if the problem persists.
|-

|rowspan="2" colspan="2"| PWR
|rowspan="2" | Indicates the power status of the device
|OFF
| —
|The device is powered off.
|-
|Green
|Solid
|The devices is powered on.
|-

| rowspan="3" colspan="2" | 10/100/1000
| rowspan="3"| Indicates the speed of the Gigabit Ethernet link.
|OFF
| —
|No link, or 10 Mbps link.
|-
|Green
|Solid
|100 Mbps link.
|-
|Amber
|Solid
|1,000 Mbps link.
|-

| rowspan="3" colspan="2"| ACT/LINK
| rowspan="3" | Indicates the Gigabit Ethernet link activity or status.
|OFF
| —
|No link has been established.
|-
| rowspan="2" | Green
|Solid
|A link has been negotiated.
|-
|Blinking
|Activity on the link.
|-

| rowspan="5" | 1G/10G ETH 0
| rowspan="3" | ACT/LINK
| rowspan="3" | Indicates the status of the SFP+ port.
|OFF
| —
|The link is down.
|-
| rowspan="2" |Green
|Solid
|The link is up.
|-
|Blinking
|The link is active (transmitting and receiving).
|-
| rowspan="2" |10GbE
| rowspan="2" |Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

| rowspan="2" colspan="2" | 1G/10G ETH 1 10GbE
| rowspan="2" | Indicates the status of the 10G ETH link.
|OFF
| —
|The 10G ETH link is down.
|-
|Green
|Solid
|The 10G ETH link is up.
|-

|}

===Rear Panel===
[[File:USRP-2974 Rear Panel.jpg|800px]]
[[File:2974_back_wireframe.png|800px]]

{| class="wikitable"
!Connector
!Use
|-
|REF OUT
|Output terminal for an external reference signal for the LO on the device. REF OUT is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference output. The output signal at this connector is 10 MHz at 3.3 V.
|-

|REF IN
|Input terminal for an external reference signal for the LO on the device. REF IN is an SMA (f) connector with an impedance of 50 Ω, and it is a single-ended reference input. REF IN accepts a 10 MHz signal with a minimum input power of 0 dBm (0.632 Vpk-pk) and a maximum input power of 15 dBm (3.56 Vpk-pk) for a square wave or sine wave.
|-

|PPS TRIG OUT
|Output terminal for the PPS timing reference. PPS TRIG OUT is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input. The output signal is 0 V to 3.3 V TTL. You can also use this port as a triggered output (TRIG OUT) that you program with the PPS Trig Out I/O signal.
|-

|PPS TRIG IN
|Input terminal for PPS timing reference. PPS TRIG IN is an SMA (f) connector with an impedance of 50 Ω and is a single-ended input channel. PPS TRIG IN accepts 0 V to 3.3 V TTL and 0 V to 5 V TTL signals. You can also use this port as a triggered input (TRIG IN) that you control using NI-USRP software.
|-

|GPS ANT
|Input terminal for the GPS antenna signal. GPS ANT is an SMA (f) connector with a maximum input power of -15 dBm and an output of DC 5 V to power an active antenna. '''Notice:''' Do not terminate the GPS ANT port if you do not use it.
|-

|PCIe x4
|Port for a PCI Express Generation 2, x4 bus connection through an MXI Express four-lane cable. Can be used to connect an external USRP device or external chassis.
|-

|SYSTEM POWER IN
|Input that accepts a 15 V ± 5%, 10 A external DC power connector.
|-

|}

===Ref Clock - 10 MHz===
Using an external 10 MHz reference clock, a square wave will offer the best phase noise performance, but a sinusoid is acceptable. The power level of the reference clock cannot exceed +15 dBm.

===PPS - Pulse Per Second===
Using a PPS signal for timestamp synchronization requires a square wave signal with the following a 5Vpp amplitude.

To test the PPS input, you can use the following tool from the UHD examples:

* <code><args></code> are device address arguments (optional if only one USRP device is on your machine)

cd <install-path>/lib/uhd/examples ./test_pps_input –args=<args>

===Front Panel GPIO===
{|
| style="width:50%" |
The GPIO port is not meant to drive big loads. You should not try to source more than 5mA per pin.

The +3.3V is for ESD clamping purposes only and not designed to deliver high currents.

| style="vertical-align:top" | [[File:x3x0 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 X3xx, there are no external pull-ups/pull-downs for the GPIO pins, but the FPGAs do have them and they are configured as follows: X3xx: pull-down.

====Pin Mapping====
* Pin 1: +3.3V
* Pin 2: Data[0]
* Pin 3: Data[1]
* Pin 4: Data[2]
* Pin 5: Data[3]
* Pin 6: Data[4]
* Pin 7: Data[5]
* Pin 8: Data[6]
* Pin 9: Data[7]
* Pin 10: Data[8]
* Pin 11: Data[9]
* Pin 12: Data[10]
* Pin 13: Data[11]
* Pin 14: 0V
* Pin 15: 0V

'''Note''': 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.

==Certifications==
===RoHS===
As of December 1st, 2010 all NI/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]

==Choosing an Interface==

The USRP-2974 provides three interface options – 1 Gigabit Ethernet (1 GigE), 10 Gigabit Ethernet (10 GigE), and PCI-Express (PCIe). The PCIe interface is always available regardless of what FPGA image is loaded. Ettus ships two FPGA image variants, the HG or HGS image which has one 1 GigE interfaces and one 10 GigE interfaces, and the XG image which has two 10 GigE interfaces. Generally, Ettus Research recommends using 10 GigE to achieve the maximum throughput available from the USRP-2974. PCIe is recommended for applications that require the lowest possible latency, which is a desirable characteristic for PHY/MAC research. If your application does not require the full bandwidth of the USRP-2974, the 1 GigE interface serves as a cost-effective fall-back option. Ettus Research provides a complete interface kit for each of these options, which is also shown in the following table.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|[https://www.ettus.com/product/details/1GIGE-KIT SFP Adapter + GigE Cable]
|-
|10 Gigabit
|200 MS/s
|Desktop
|[https://www.ettus.com/product/details/10GIGE-KIT 10 GigE Interface Kit]
|-
|PCI-Express
(PCIe, 4 lane)
|200 MS/S
|Desktop
|[https://www.ettus.com/product/details/PCIE-KIT PCI-Express Desktop Kit]
|-

|}

===10 Gigabit Ethernet===
In order to utilize the dual 10 Gigabit Ethernet interfaces, ensure the XG image is installed ([http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs_fpga_flavours see FPGA Image Flavors]). In addition to burning the prerequisite FPGA image, it may also be necessary to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). This is done by increasing the number of RX descriptors ([http://files.ettus.com/manual/page_transport.html#transport_udp_linux see Linux specific notes]).

The <code>benchmark_rate</code> tool can be used to test this capability. Run the following commands to test the X-series USRP over both 10 Gigabit Ethernet interfaces with the maximum rate of 200 Msps per channel:

cd <install-path>/lib/uhd/examples
./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6

The second interface is specified by the extra argument '''second_addr'''.

'''Recommended 10 Gigabit Ethernet Cards'''
* Intel X520-DA2
** [http://ark.intel.com/products/39776/Intel-Ethernet-Converged-Network-Adapter-X520-DA2 Intel® Ethernet Converged Network Adapter X520-DA2]
* Intel X520-DA1
** [http://ark.intel.com/products/68669/Intel-Ethernet-Converged-Network-Adapter-X520-DA1 Intel® Ethernet Converged Network Adapter X520-DA1 ]
* Intel X710-DA2
** [http://ark.intel.com/products/83964/Intel-Ethernet-Converged-Network-Adapter-X710-DA2 Intel® Ethernet Converged Network Adapter X710-DA2 ]
* Intel X710-DA4
** [http://ark.intel.com/products/83965/Intel-Ethernet-Converged-Network-Adapter-X710-DA4 Intel® Ethernet Converged Network Adapter X710-DA4 ]
* Mellanox MCX4121A-ACAT
** [https://store.mellanox.com/products/mellanox-mcx4121a-acat-connectx-4-lx-en-network-interface-card-25gbe-dual-port-sfp28-pcie3-0-x8-rohs-r6.html Mellanox MCX4121A-ACAT ]

==GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP-2794 has a high-accuracy GPS-disciplined oscillator (GPSDO). The GPSDO improves the accuracy of the internal frequency reference to 20 ppb, or 0.1 ppb if the GPS is synchronized to the GPS constellation. When synchronized to the GPS constellation, all USRP™ devices will also be synchronized in time within 50 ns.

* Support GPSDO NMEA Strings
* [http://www.jackson-labs.com/assets/uploads/main/LC_XO_specsheet.pdf JacksonLabs LC_XO]

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy
|± 2.5ppm
± 2,500 Hz @ 1 GHz
|± 20 ppb
± 20 Hz @ 1 GHz
|-
|Frequency Accuracy
|
|± 0.01ppb
|-
|(GPS-Disciplined)
|
|~ ± 0.01 Hz @ 1 GHz
|-
|GPS Time Sync Accuracy
|
|±50ns to UTC Time**
|-
|10 MHz Reference Phase Drift with GPS Sync
|
|<±20ns After 1 Hour**
|-
|}

===Sensors===
You can query the lock status with the <code>gps_locked</code> sensor, as well as obtain raw NMEA sentences using the <code>gps_gprmc</code>, and <code>gps_gpgga</code> sensors. Location information can be parsed out of the <code>gps_gpgga</code> sensor by using <code>gpsd</code> or another NMEA parser.

==Option: Using the GPIO Expansion Kit==
{|
|style="vertical-align:top; width:60%"|This General Purpose Input/output (GPIO) breakout kit provides access to general purpose digital I/O signals with simple terminal blocks, and a prototyping area where wires and components can be soldered. Each GPIO pin is connected to an FPGA digital line allowing it to be configured as an input, or an output, using the various software frameworks that support the USRP™ GPIO.

These GPIO signals can serve the following functions:

* Control of external devices, such as power amplifiers and RF switches
* Provide output signals that can help with debugging
* Provide observables to be analyzed by oscilloscopes or other external equipment
* Accept input from external devices for local, software-based triggering
* Implement a protocol line such as SPI or I2C
||[[File:Gpio_expan.jpg|250px]]
|}
===GPIO Expansion Kit Contents===

*1 GPIO Breakout Board
*1 DB-15, 1-meter cable
*GPIO Quick Reference

===Circuit Protection===
The GPIO signals exposed with this breakout kit are routed directly to the USRP device's FPGA with limited protection circuitry. However, the user must take precautionary measures to ensure input/output signals meet the specifications shown in this document. Over voltage, excess current draw, and other conditions can damage the USRP device and void the warranty. Special care should be taken when the USRP is powered off.

===Mounting the GPIO Breakout Board===
The GPIO breakout board can be mounted directly to the DB15 connector of a USRP ™ device, or mounted remotely with the cable provided in this kit. The screws on the DB15 connector of the breakout board must be removed to mount the board directly. For remote mounting, the breakout board is supplied with rubber standoffs to avoid scratching surfaces, and several through-holes for hard mounting with screws or other hardware (not provided).

===Using GPIO with UHD, GNU Radio, and other Third-Party Frameworks===
When used with UHD, or other third party frameworks that leverage UHD, the GPIO expansion can be controlled with simple API calls. For more information, on the C++ API, and examples of how to use the GPIO in frameworks such as GNU Radio, please see the [[Application Notes]] section of the [https://kb.ettus.com Ettus Research Knowledge Base].

===GPIO Specifications (3.3V Bank, LVCMOS)===

{| class="wikitable"
!Parameter
!Typical
|-
!colspan="2"|Configured as Input
|-
|Default Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Threshold
|2.0V
|-
|Voltage Low Threshold
|0.8V
|-
|Voltage Input Limits (no damage)
| -0.3V/3.45V
|-
!colspan="2"|Configured as Output
|-
|Voltage Standard
|3.3V LVCMOS
|-
|Voltage High Output
|2.8V
|-
|Voltage Low Output
|0.4V
|-
|Current Source Capability
|12 mA
|-
|Output Source Impedance
|>33 ohms typical
|-
|}

==Option: Antenna Kit for GPSDO==
The GPSDO Mini Kit will improve the accuracy of the USRP reference clock, even if it does not receive signals from the GPS Constellation. However, to achieve the best accuracy possible, and to achieve global timing alignment across multiple USRPs, Ettus Research recommends the GPSDO Mini Antenna Kit.

==Option: Cables for MIMO Expansion==
Multiple USRP-2974s can be synchronized for coherent operation by sharing a common 10 MHz and 1 PPS signal. We recommend using a star-distribution topology with an OctoClock or OctoClock-G, as seen in Figure 4. This requires matched length cables to be used for both 10 MHz and 1 PPS.

For more information about MIMO operation, please see the MIMO and Synchronization Application Note.
[[File:8mimo.png|700px|center]]
<center>Figure 4 - Star-Distribution of 10 MHz/PPS Signals with OctoClock</center>

==FAQ==

* '''What is the bandwidth of the USRP-2974'''

The ADC rate on each analog RX channel is 200 MS/s quadrature, which provides a theoretical analog bandwidth of approximately 80% of the Nyquist bandwidth of +/- 100 MHz (+/- 80 MHz around the center frequency). The resulting maximum theoretical analog bandwidth is 160 MHz.

FPGA Processing Bandwidth: Up to 200 MS/s quadrature.

Host Bandwidth: Up to 200 MS/s quadrature, dependent on selected interface

For more information about achieving the maximum bandwidth with a USRP-2974, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP-2974'''

Like all other USRP models, the USRP-2974 is compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on the onboard or host computer. UHD provides a direct C++ API to control and stream to/from the USRP-2974. It also provides compatibility with a variety of third-party software frameworks including GNU Radio, LabVIEW, and MATLAB. You may also customize the FPGA image provided with UHD to integrate your own signal processing. For more information about UHD, and supported software frameworks, please see:

http://files.ettus.com/manual/

* '''How do I update the FPGA images and firmware with the latest from UHD'''

You can find more information about updating the FPGA image through PCIe, 1/10 GigE, and JTAG [https://kb.ettus.com/X300/X310_Device_Recovery here].

* '''How can I modify the FPGA of the USRP-2974'''

The source code (Verilog) for the USRP-2794 is available in the UHD repository. The build process leverages the existing CMAKE build system used to compile the host-side driver. A Linux-based setup will provide the best results.

Which FPGA toolchain required to build the FPGA images will depend upon your version of UHD. For more details please see the [https://kb.ettus.com/UHD UHD] Software Resource page.

* '''How much free space is available in the USRP-2974 FPGA'''

Please see the [[#Utilization statistics]] section of this resources page for more information.

* '''What frequency range does the USRP-2974 cover'''

10MHz to 6GHz.

* '''What components do I need to purchase for a complete USRP-2974 system'''

The USRP-2974 is a complete stand alone SDR. Additional components might include RF filters, antennas, RF power amplifiers or other RF components needed of a specific application.

[[Category:Hardware Resources]]

File:2974 back wireframe.png

2019-06-01T14:56:07Z

JoseLoera:

File:USRP-2974 Rear Panel.jpg

2019-06-01T14:55:53Z

JoseLoera:

File:2974 frt wireframe.png

2019-06-01T14:54:03Z

JoseLoera: JoseLoera uploaded a new version of File:2974 frt wireframe.png

File:2974 frt wireframe.png

2019-06-01T14:52:17Z

JoseLoera:

File:USRP-2974 Front Panel.jpg

2019-06-01T14:48:31Z

JoseLoera:

File:2974 blk dia.png

2019-06-01T14:45:48Z

JoseLoera:

Knowledge Base

2019-06-01T14:44:08Z

JoseLoera: /* Hardware Resources */ Adding USRP-2974

Welcome to the Ettus Research Knowledge Base (KB). The KB is continuously being updated and expanded. If you have any suggestions, or do not find what you are looking for, then please [http://www.ettus.com/contact Contact Us].
__NOTOC__
<div class="row">
<div class="col-1-3">
== [[Getting Started Guides| Getting Started Guides]] ==

'''Motherboards'''
* [[B200/B210/B200mini/B205mini Getting Started Guides|B200/B210/B200mini/B205mini]]
* [[Ettus USRP E300 Embedded Family Getting Started Guides|E310/E312/E313]]
* [[E320 Getting Started Guide|E320]]
* [[N200/N210 Getting Started Guides|N200/N210]]
* [[USRP N300/N310/N320/N321 Getting Started Guide|N300/N310/N320/N321]]
* [[X300/X310 Getting Started Guides|X300/X310]]
* [[USRP-2974 Getting Started Guide|USRP-2974]]

'''Daughterboards'''
* [[BasicTX/BasicRX Getting Started Guides|BasicTX/BasicRX]]
* [[CBX Getting Started Guides|CBX]]
* [[LFTX/LFRX Getting Started Guides|LFTX/LFRX]]
* [[SBX Getting Started Guides|SBX]]
* [[TwinRX Getting Started Guides|TwinRX]]
* [[UBX Getting Started Guides|UBX]]
* [[WBX Getting Started Guides|WBX]]

'''Other'''
* [[Getting_Started_with_RFNoC_Development|RFNoC Development]]
* [[Live SDR Environment Getting Started Guides|Live SDR Environment]]
* [[OctoClock CDA-2990 Getting Started Guides|OctoClock CDA-2990]]
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices|White Rabbit]]

</div>
<div class="col-1-3">

== [[Hardware Resources| Hardware Resources]] ==
'''Motherboards'''
* [[B200/B210/B200mini/B205mini]]
* [[Ettus USRP E300 Embedded Family Hardware Resources|E310/E312/E313]]
* [[E320|E320]]
* [[N200/N210]]
* [[N300/N310]]
* [[N320/N321]]
* [[X300/X310]]
* [[USRP-2974]]

'''Daughterboards'''
* [[BasicTX/BasicRX]]
* [[CBX]]
* [[LFTX/LFRX]]
* [[SBX]]
* [[TwinRX]]
* [[UBX]]
* [[WBX]]

'''Other'''
* [[OctoClock CDA-2990]]
* [[GPSDO]]
* [[Antennas]]

</div>
<div class="col-1-3">

== [[Software Resources| Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[RFNoC]]
* [[Live SDR Environment]]

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual| UHD and USRP User Manual]] ==
'''Software'''
* [http://files.ettus.com/manual/ UHD Manual]

'''Motherboards'''
* [http://files.ettus.com/manual/page_usrp_b200.html B200/B210/B200mini/B205mini]
* [http://files.ettus.com/manual/page_usrp_x3x0.html X300/X310]
* [http://files.ettus.com/manual/page_usrp2.html N200/N210]
* [http://files.ettus.com/manual/page_usrp_e3x0.html E310/E312]

'''Daughterboards'''
* [http://files.ettus.com/manual/page_dboards.html#dboards_basictx BasicRX/LFRX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_basicrx BasicTX/LFTX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_cbx CBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_sbx SBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_wbx WBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_ubx UBX]

'''Other'''
* [http://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes| Application Notes]] ==
Application Notes (AN) and technical articles written by engineers, for engineers. These articles offer experienced analysis, design ideas, reference designs, and tutorials—to make you productive and successful using USRP devices.
</div>
<div class="col-1-3">

== [[Additional Resources| Additional Resources]] ==
* [[Suggested Reading|Suggested Reading]]
* [[Suggested Videos|Suggested Videos]]
* [[SDR Events]]
* [[CGRAN]]
</div>
</div>

<div class="row">
<div class="col-1-3">

== [[Technical Support| Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Internet Relay Chat (IRC)|Internet Relay Chat (IRC)]]
* [[StackExchange|StackExchange]]
* [[Ordering and Fulfillment Help | Ordering and Fulfillment Help]]

</div>
<div class="col-1-3">

== [[Faq| FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]

</div>
<div class="col-1-3">

== [[Legacy Products| Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

USRP-2974 Getting Started Guide

2019-06-01T14:42:16Z

JoseLoera: Created page with "==Kit Contents== * NI USRP-2974 * 30 dB SMA Attenuator * SMA-male to SMA-male Cable * Power Supply * Getting Started Guide {| ||center |..."

==Kit Contents==
* NI USRP-2974
* 30 dB SMA Attenuator
* SMA-male to SMA-male Cable
* Power Supply
* Getting Started Guide
{|
||[[File:USRP_2974_frt_dia.jpg|250px|center]]
|}

==Verify the Contents of Your Kit==
Make sure that your kit contains all the items listed above. If any items are missing, please contact your sales agent.

==Unpacking the Kit==
1. To prevent electrostatic discharge (ESD) from damaging the device, ground yourself using a grounding strap or by holding a grounded object, such as your computer chassis.

2. Remove the device from the package and inspect the device for loose components or any
other sign of damage.

3. Never touch the exposed pins of connectors.

4. Unpack any other items and documentation from the kit.

'''NOTE:''' Do not install a device if it appears damaged in any way. Store the device in the antistatic package when the device is not in use.

==Proper Care and Handling==
All NI products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Listed below are some examples of actions which can prevent damage to the unit:

*Always properly terminate the transmit port with an antenna or 50Ω load.
*Always handle the USRP with proper anti-static methods.
*Never allow the USRP to directly or indirectly come into contact with any voltage spikes.
*Never allow any water, or condensing moisture, to come into contact with the USRP.
*Always use caution with FPGA, firmware, or software modifications.
{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+10 dBm''' of power into RF ports RF0 and RF1.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''+15 dBm''' of power into the REF IN input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than '''-15 dBm''' of power into the GPS ANT input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Install and Setup the Software Tools on the onboard computer (SoM-System on Module)==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on the SoM. A step-by-step guide for doing this is available at the [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on the Linux] Application Note. '''Release 3.15.0''' or later of the USRP Hardware Driver, UHD, is needed.

==Basic Connectivity==
This USRP-2974 host supports multiple, high-speed, low-latency interface options to the FPGA. To setup the device, follow these basic instructions:
* Configure the host ethernet adapter (enp1s0f0) to use an IP address of 192.168.40.1 and a subnet mask of 255.255.255.0
* Configure the host ethernet adapter (enp1s0f1) to use an IP address of 192.168.30.1 and a subnet mask of 255.255.255.0 (loopback with SFP+ cable needed)
* To test communications, ping the USRP FPGA at address "192.168.40.2" or “192.168.30.2”

For more details on network setup, including PCIe connectivity, please see the section [[NI_USRP-2974_Hardware_Resource_0#Interfaces_and_Connectivity|Interfaces and Connectivity]] of the NI USRP-2974 Hardware Resources page.

==Test and Verify the Operation of the USRP==
Once the software tools are installed on the onboard computer, verify the correct operation of the USRP by running the utility programs on the onboard computer. More information is available at the [https://kb.ettus.com/Verifying_the_Operation_of_the_USRP_Using_UHD_and_GNU_Radio Verifying the Operation of the USRP Using UHD and GNU Radio] Application Note.

==Enabling PXE Boot==

===Legacy PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with Legacy option, restart the system
* Go into the BIOS’ Boot tab and set IBA CL Slot 00FE v0105 as first boot option, restart the system

===UEFI PXE Boot===
* When rebooting the USRP-2974 open BIOS with DEL and go to Boot tab
* Enable PXE Network Boot with UEFI option, restart the system
* Go into the BIOS’ Boot tab and set IPv4 as first boot option, restart the system

==NI USRP RIO PCIe Support==

If you are connecting the USRP-2974 through the PCIe interface, then complete this section.

If you are connecting the USRP-2974 through the 1G or 10G Ethernet connection then do '''NOT''' complete this section.

# Installer and commands taken from [https://files.ettus.com/manual/page_ni_rio_kernel.html https://files.ettus.com/manual/page_ni_rio_kernel.html]
# Extract the installer and install as described (note the _ instead of – in the folder name)
# Enable or disable the PCIe link
##<code>$ sudo /usr/local/bin/niusrprio_pcie start</code>
##<code>$ sudo /usr/local/bin/niusrprio_pcie stop </code>
# Check the status
##<code>$ sudo /usr/local/bin/niusrprio_pcie status</code>
# see the connection over PCIe with
##<code>$ uhd_find_devices</code>

==Note on USRP-2974 Rev A Hardware==
To find out if you have a '''"Rev A"''' hardware version of the USRP-2974 check the last character of the part number on the USRP-2974. E.g. "146873'''A'''"

To fully support Rev A with UHD software, install UHD as explained and run the following command:

$ /usr/local/lib/uhd/utils/usrp_burn_mb_eeprom --args=”addr=192.168.40.2” --value=”product=31131”

After a reboot run:

$ uhd_find_devices</code>

Under the product category section you will see the following:
“NI-2974”.

==Technical Support and Community Knowledge Base==

Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==

If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com]. Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

==Additional Resources==

* [[NI_USRP-2974_Hardware_Resource_00 | USRP-2974 Hardware Resource]]
* http://www.ni.com/pdf/manuals/377416c.pdf

[[Category:Getting Started Guides]]

File:USRP 2974 frt dia.jpg

2019-06-01T14:41:37Z

JoseLoera:

Knowledge Base

2019-06-01T14:37:48Z

JoseLoera: /* Getting Started Guides */ added USRP-2974 link

Welcome to the Ettus Research Knowledge Base (KB). The KB is continuously being updated and expanded. If you have any suggestions, or do not find what you are looking for, then please [http://www.ettus.com/contact Contact Us].
__NOTOC__
<div class="row">
<div class="col-1-3">
== [[Getting Started Guides| Getting Started Guides]] ==

'''Motherboards'''
* [[B200/B210/B200mini/B205mini Getting Started Guides|B200/B210/B200mini/B205mini]]
* [[Ettus USRP E300 Embedded Family Getting Started Guides|E310/E312/E313]]
* [[E320 Getting Started Guide|E320]]
* [[N200/N210 Getting Started Guides|N200/N210]]
* [[USRP N300/N310/N320/N321 Getting Started Guide|N300/N310/N320/N321]]
* [[X300/X310 Getting Started Guides|X300/X310]]
* [[USRP-2974 Getting Started Guide|USRP-2974]]

'''Daughterboards'''
* [[BasicTX/BasicRX Getting Started Guides|BasicTX/BasicRX]]
* [[CBX Getting Started Guides|CBX]]
* [[LFTX/LFRX Getting Started Guides|LFTX/LFRX]]
* [[SBX Getting Started Guides|SBX]]
* [[TwinRX Getting Started Guides|TwinRX]]
* [[UBX Getting Started Guides|UBX]]
* [[WBX Getting Started Guides|WBX]]

'''Other'''
* [[Getting_Started_with_RFNoC_Development|RFNoC Development]]
* [[Live SDR Environment Getting Started Guides|Live SDR Environment]]
* [[OctoClock CDA-2990 Getting Started Guides|OctoClock CDA-2990]]
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices|White Rabbit]]

</div>
<div class="col-1-3">

== [[Hardware Resources| Hardware Resources]] ==
'''Motherboards'''
* [[B200/B210/B200mini/B205mini]]
* [[Ettus USRP E300 Embedded Family Hardware Resources|E310/E312/E313]]
* [[E320|E320]]
* [[N200/N210]]
* [[N300/N310]]
* [[N320/N321]]
* [[X300/X310]]

'''Daughterboards'''
* [[BasicTX/BasicRX]]
* [[CBX]]
* [[LFTX/LFRX]]
* [[SBX]]
* [[TwinRX]]
* [[UBX]]
* [[WBX]]

'''Other'''
* [[OctoClock CDA-2990]]
* [[GPSDO]]
* [[Antennas]]

</div>
<div class="col-1-3">

== [[Software Resources| Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[RFNoC]]
* [[Live SDR Environment]]

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual| UHD and USRP User Manual]] ==
'''Software'''
* [http://files.ettus.com/manual/ UHD Manual]

'''Motherboards'''
* [http://files.ettus.com/manual/page_usrp_b200.html B200/B210/B200mini/B205mini]
* [http://files.ettus.com/manual/page_usrp_x3x0.html X300/X310]
* [http://files.ettus.com/manual/page_usrp2.html N200/N210]
* [http://files.ettus.com/manual/page_usrp_e3x0.html E310/E312]

'''Daughterboards'''
* [http://files.ettus.com/manual/page_dboards.html#dboards_basictx BasicRX/LFRX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_basicrx BasicTX/LFTX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_cbx CBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_sbx SBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_wbx WBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_ubx UBX]

'''Other'''
* [http://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes| Application Notes]] ==
Application Notes (AN) and technical articles written by engineers, for engineers. These articles offer experienced analysis, design ideas, reference designs, and tutorials—to make you productive and successful using USRP devices.
</div>
<div class="col-1-3">

== [[Additional Resources| Additional Resources]] ==
* [[Suggested Reading|Suggested Reading]]
* [[Suggested Videos|Suggested Videos]]
* [[SDR Events]]
* [[CGRAN]]
</div>
</div>

<div class="row">
<div class="col-1-3">

== [[Technical Support| Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Internet Relay Chat (IRC)|Internet Relay Chat (IRC)]]
* [[StackExchange|StackExchange]]
* [[Ordering and Fulfillment Help | Ordering and Fulfillment Help]]

</div>
<div class="col-1-3">

== [[Faq| FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]

</div>
<div class="col-1-3">

== [[Legacy Products| Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

X300/X310 Device Recovery

2019-02-25T18:15:45Z

JoseLoera: /* Starting Xilinx Vivado Lab Edition */

==Application Note Number==
'''AN-305'''

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

==Abstract==
This application note covers the details of recovering the USRP X300/X310 via JTAG.

==Overview==
This application note covers the process of recovering the USRP X300/X310 by flashing the FPGA image via the JTAG interface.

Note: Linux only.

==Manual==
For reference, the user manual page for the X300/X310 is at the link below.

http://files.ettus.com/manual/page_usrp_x3x0.html

==Required Tools==
* Computer with USB2/3 and 1 GbE or 10GbE Interface
* Ubuntu 14.x or 16.x Installation
* UHD Installation
* USB2 Cable
* SFP+ / RJ45 Adapter
* Ethernet Cable

==Prerequisites==
This application note assumes you have a Ubuntu 14.x or 16.x Linux installation. You should also have a working UHD installation. If you do not have UHD installed, please reference the [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux]] Application Note.

You will need to have the matching FPGA images downloaded before proceeding for your UHD installation. If you do not have the FPGA images downloaded, run the command:

sudo uhd_images_downloader

Verify you have the FPGA images downloaded by running the command:

ls -alh /usr/local/share/uhd/images/usrp_x3*

[[File:x300_recovery_19.png|700px|center]]

==Installing Xilinx Vivado Lab 2015.4==
You will need to download and install Xilinx Vivado Lab Edition 2015.4 in order to flash the USRP X300/X310 via JTAG. Xilinx Vivado Lab Edition 2015.4 can be downloaded at the following link:

'''Note:''' Xilinx Vivado 2015.4 must be used. If you already have Xilinx Vivado Design or System Edition (2015.4) installed, they will work in place of the Lab Edition. If Design or System Edition is used, the paths may differ from described within this application note, however the process is the same.

https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive.html

[[File:x300_recovery_1.png|700px|center]]

After the download is complete, verify the MD5 sum of the file:

cd ~/Downloads
md5sum Xilinx_Vivado_Lab_Lin_2015.4_1118_2.tar.gz

'''Note:''' The filename and MD5 hash may differ from the screen capture shown. Verify the MD5 sum against the hash listed on the Xilinx download page.

[[File:x300_recovery_2.png|700px|center]]

Next, decompress the downloaded tarball:

tar -zxvf Xilinx_Vivado_Lab_Lin_2015.4_1118_2.tar.gz

Next, go into the new directory and run the <code>xsetup</code> installer (It requires <code>sudo</code> permissions to install):

cd Xilinx_Vivado_Lab_Lin_2015.4_1118_2
sudo ./xsetup

[[File:x300_recovery_3.png|700px|center]]

[[File:x300_recovery_4.png|700px|center]]

This will launch the Xilinx Vivado Lab installer.

[[File:x300_recovery_5.png|700px|center]]

You will be prompted that a newer version is available, ignore this popup and click <code>Continue</code> to install Xilinx Vivado Lab 2015.4.

[[File:x300_recovery_7.png|700px|center]]

The installer will then be at a Welcome screen, click <code>Next</code>.

[[File:x300_recovery_8.png|700px|center]]

You will then be prompted to accept the various License Agreements, click <code>Next</code>.

[[File:x300_recovery_9.png|700px|center]]

You will then be prompted to select the install options. It is suggested to leave the default values, click <code>Next</code>.

[[File:x300_recovery_10.png|700px|center]]

You will then be prompted with the installation locations. It is suggested to leave the default values, click <code>Next</code>.

[[File:x300_recovery_11.png|700px|center]]

You will then be prompted to create the directory <code>/opt/Xilinx</code>. Click <code>Yes</code>.

[[File:x300_recovery_12.png|700px|center]]

Finally, you will be at the Installation Summary prompt. Click <code>Install</code>.

[[File:x300_recovery_13.png|700px|center]]

The installation process should only take a minute or two.

[[File:x300_recovery_14.png|700px|center]]

You will then be prompted that the installation was successful. Click <code>Ok</code>, and the installer will close.

[[File:x300_recovery_15.png|700px|center]]

==Installing the Digilent Cable Driver==
In order to use the JTAG interface built into the USRP X300/X310 front panel, you will need to install the Digilent Cable Driver. It is included with the Xilinx Vivado Lab Edition package.

Navigate to the folder <code>/opt/Xilinx/Vivado_Lab/2015.4/data/xicom/cable_drivers/lin64/install_script/install_drivers</code>, and run the installer script.

cd /opt/Xilinx/Vivado_Lab/2015.4/data/xicom/cable_drivers/lin64/install_script/install_drivers
sudo ./install_digilent.sh

[[File:x300_recovery_16.png|700px|center]]

Next, reload the UDEV rules

sudo udevadm control --reload

==Configuring Network Interface==
You will need to set your ethernet interface that will be connected to the USRP X300/X310 to a static IP address of <code>192.168.10.1</code> along with setting a MTU of <code>1500</code>.

[[File:x300_recovery_36.png|300px|center]]

[[File:x300_recovery_33.png|500px|center]]

==Connect the X300/X310==
Connect the USRP X300/X310 with the USB2 cable via the JTAG port on the front face plate. You can also attach the SFP+/RJ45 adapter to Port 0 and connect your computer via ethernet.

Power on the USRP X300/X310.

==Starting Xilinx Vivado Lab Edition==
Start by navigating back to your home directory:

cd ~/

Next, start Xilinx Vivado Lab

/opt/Xilinx/Vivado_Lab/2015.4/bin/vivado_lab

[[File:x300_recovery_18.png|700px|center]]

[[File:x300_recovery_20.png|700px|center]]

Open the Hardware Manager

[[File:x300_recovery_21.png|700px|center]]

[[File:x300_recovery_22.png|700px|center]]

Next, within the menu the of the Hardware Manager select <code>Tools</code> -> <code>Auto Connect</code>.

[[File:x300_recovery_23.png|700px|center]]

The details of the FPGA should populate the window on the left side of the Hardware Manager.

[[File:x300_recovery_24.png|700px|center]]

Right click on the FPGA listed, and select <code>Program Device</code>.

[[File:x300_recovery_25.png|700px|center]]

This will popup a new window. Click on the file selection button and navigate to the location of the UHD FPGA images, and select the correct FPGA image for your device. (<code>/usr/local/share/uhd/images</code>)

'''Note:''' Select the correct FPGA image that matches your USRP (either <code>_x300</code> or <code>_x310</code>) with the <code>.bit</code> file extension. It is recommended to select the <code>_HG</code> FPGA image, which will initialize Port 0 as 1 GbE and Port 1 as 10 GbE. Advanced users operating with dual 10 GbE may select the <code>_XG</code> image, however you will need to adjust the instructions listed within this document to match the dual 10GbE configuration (IP Addresses, MTU settings, etc).

[[File:x300_recovery_26.png|700px|center]]

[[File:x300_recovery_27.png|700px|center]]

[[File:x300_recovery_28.png|700px|center]]

[[File:x300_recovery_29.png|700px|center]]

Next, click <code>Program</code>.

[[File:x300_recovery_30.png|700px|center]]

A progress bar will popup as the FPGA is programmed.

[[File:x300_recovery_31.png|700px|center]]

Once the programming is completed, close Vivado Lab.

[[File:x300_recovery_32.png|700px|center]]

Return to a terminal and attempt to ping the USRP X300/X310.

ping 192.168.10.2

[[File:x300_recovery_34.png|700px|center]]

Stop the ping with <code>CTRL-C</code>.

At this point, if you're able to ping the USRP X300/X310, attempt to run the UHD utility <code>uhd_usrp_probe</code>.

uhd_usrp_probe

Example output from <code>uhd_usrp_probe</code>:

<pre>
user@host:~$ uhd_usrp_probe
linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_003.010.001.HEAD-0-gc705922a

-- X300 initialization sequence...
-- Determining maximum frame size... 1472 bytes.
-- Setup basic communication...
-- Loading values from EEPROM...
-- Setup RF frontend clocking...
-- Radio 1x clock:200
-- [DMA FIFO] Running BIST for FIFO 0... pass (Throughput: 1304.3MB/s)
-- [DMA FIFO] Running BIST for FIFO 1... pass (Throughput: 1300.5MB/s)
-- [RFNoC Radio] Performing register loopback test... pass
-- [RFNoC Radio] Performing register loopback test... pass
-- [RFNoC Radio] Performing register loopback test... pass
-- [RFNoC Radio] Performing register loopback test... pass
-- Performing timer loopback test... pass
-- Performing timer loopback test... pass
_____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X310
| | revision: 8
| | revision_compat: 7
| | product: 30818
| | mac-addr0: 00:00:00:00:00:00
| | mac-addr1: 00:00:00:00:00:00
| | gateway: 192.168.10.1
| | ip-addr0: 192.168.10.2
| | subnet0: 255.255.255.0
| | ip-addr1: 192.168.20.2
| | subnet1: 255.255.255.0
| | ip-addr2: 192.168.30.2
| | subnet2: 255.255.255.0
| | ip-addr3: 192.168.40.2
| | subnet3: 255.255.255.0
| | serial: xxxxxxxx
| | FW Version: 5.1
| | FPGA Version: 33.0
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: UBX-160 v1 (0x007a)
| | | Serial: xxxxxxxx
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: UBX RX
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 10.000 to 6000.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 160000000.0 to 160000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Unknown (0xffff) - 0
| | | | Antennas:
| | | | Sensors:
| | | | Freq range: 0.000 to 0.000 MHz
| | | | Gain Elements: None
| | | | Bandwidth range: 0.0 to 0.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ads62p48
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: UBX-160 v1 (0x0079)
| | | Serial: xxxxxxxx
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: UBX TX
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 10.000 to 6000.000 MHz
| | | | Gain range PGA0: 0.0 to 31.5 step 0.5 dB
| | | | Bandwidth range: 160000000.0 to 160000000.0 step 0.0 Hz
| | | | Connection Type: QI
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Unknown (0xffff) - 0
| | | | Antennas:
| | | | Sensors:
| | | | Freq range: 0.000 to 0.000 MHz
| | | | Gain Elements: None
| | | | Bandwidth range: 0.0 to 0.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: ad9146
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1

</pre>

If running <code>uhd_usrp_probe</code> is successful, proceed with flashing the FPGA image with the UHD utility <code>uhd_image_loader</code>.

'''Note:''' Flashing the FPGA image via JTAG only does not write the FPGA image to EEPROM, you must run the <code>uhd_image_loader</code> to write the FPGA image to the internal EEPROM.

uhd_image_loader --args "type=x300,addr=192.168.10.2,fpga=HG"

[[File:x300_recovery_37.png|700px|center]]

When <code>uhd_image_loader</code> has completed the flashing process, it will recommend to power cycle the USRP X300/X310.

[[File:x300_recovery_38.png|700px|center]]

Power off the USRP X300/X310, remove the JTAG USB cable, and then power on the USRP X300/X310.

The USRP X300/X310 is now recovered. You should be able to <code>ping</code>, run <code>uhd_usrp_probe</code> and any other UHD utility/application as normal.

[[Category:Application Notes]]

Getting Started with RFNoC Development

2017-09-08T03:44:45Z

JoseLoera: /* Revision History */

==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 . 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:
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 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 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]]

Getting Started with RFNoC Development

2017-09-08T03:41:24Z

JoseLoera: /* RFNoC additional resources */

==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).
|-
|}

==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 . 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:
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 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 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]]

Getting Started with RFNoC Development

2017-08-26T20:28:17Z

JoseLoera: /* Links and Additional Resources */

==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).
|-
|}

==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 . 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:
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 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 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===
* [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]]

Getting Started with RFNoC Development

2017-08-26T17:24:09Z

JoseLoera: /* Revision History */

==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).
|-
|}

==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 . 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:
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 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 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://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-08-26T17:16:00Z

JoseLoera: /* Using a graphical interface */

==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.
|-
|}

==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 . 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:
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 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 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://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-08-26T17:13:38Z

JoseLoera: /* Using a graphical interface */

==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.
|-
|}

==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 . 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:
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 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 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. 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.

'''12. 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.

'''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://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]]

File:rfnoc gsg an 11.png

2017-08-26T17:09:27Z

JoseLoera: JoseLoera uploaded a new version of File:rfnoc gsg an 11.png

Getting Started with RFNoC Development

2017-08-26T17:08:01Z

JoseLoera: /* Using a graphical interface */

==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.
|-
|}

==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 . 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:
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 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 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. 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.

'''12. 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.

'''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 and 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://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]]

File:rfnoc gsg an 13.png

2017-08-26T16:14:04Z

JoseLoera: JoseLoera uploaded a new version of File:rfnoc gsg an 13.png

Getting Started with RFNoC Development

2017-08-26T15:54:23Z

JoseLoera: /* Abstract */

==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.
|-
|}

==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 . 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:
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 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-06-09T19:58:12Z

JoseLoera: /* 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.
|-
|}

==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. [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 . 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:
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 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-06-09T19:57:10Z

JoseLoera: /* Build custom image with pre-built RFNoC blocks */

==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.
|-
|}

==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. [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 . 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:
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 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-06-09T19:55:15Z

JoseLoera: /* Adding custom blocks to OOT Module */

==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.
|-
|}

==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. [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 . 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:
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 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-06-09T19:52:21Z

JoseLoera: /* Creating and running HDL testbenches */

==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.
|-
|}

==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. [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 . 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 ('''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 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-06-09T18:16:33Z

JoseLoera: /* GNU Radio Companion Bindings */

==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.
|-
|}

==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. [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 . 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 ('''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 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]]