Ettus Knowledge Base - User contributions [en]

About the Motherboard and Daughtercard EEPROM on USRP Devices

2025-07-15T07:10:05Z

MartinBraun: /* USB VID/PID */

==Application Note Number and Authors ==
'''AN-309''' by Trip Humphries and Michael Dickens


=USRP EEPROM Settings & Recovery Guide=

Some USRP products contain an EEPROM on the motherboard which is used to store information about the USRP. Currently, the N200/210, X300/310, B200/210, and E100 contain an on-board EEPROM. The EEPROM contains information about each USRP such as product code, revision number, USRP name, and IP address. The specific information stores on each USRP EEPROM is dependent on the USRP model.

Daughter boards also contain an EEPROM that contains identification information about the daughter board. UHD reads the daughter board ID to determine the model and revision (if applicable) of the daughter board. This information is used to properly configure the USRP and daughter board for proper function.

==EEPROM Burn Utility==

'''Disclaimer: Ettus Research accepts no liability for misuse of this utility. It can very easily cause irreversible damage if used incorrectly! Please contact Ettus support at [mailto:support@ettus.com support@ettus.com] if you are unsure how to proceed.'''

A utility, usrp_burn_mb_eeprom, is included with UHD to read/write values on the various motherboards that contain an EEPROM. The utility is located in the UHD install directory. The default folder is:

/usr/local/lib/uhd/utils/

The utility can be used with the USRP X300/310, N200/210, B200/210, and E100. In some cases, it is necessary to use the utility to write custom user settings to the USRP, such as USRP name or IP address. In other cases, some EEPROM settings set by the factory may become corrupted and need to be restored. This section will cover basic usage of the usrp_burn_mb_eeprom utility, with USRP specific instructions covered in the sections below.

EEPROM settings can be read using the usrp_burn_mb_eeprom utility. All the EEPROM settings can be read at once using the 'read all' option:

./usrp_burn_mb_eeprom --args=<optional device args> --read-all

This will return the current contents in the EEPROM for the specified USRP. For example, if you want to read all the EEPROM contents for a USRP B210, the command would look like:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

The EEPROM settings vary based on the specific USRP in use. The following sections document the EEPROM settings available for each USRP. Examples for each USRP with an EEPROM are also given.

=X300/310 EEPROM=
The EEPROM on the X300/310 stores useful information about the USRP so that UHD can set the proper settings based on model and revision. Some of these settings are user customizable. The table below outlines the values stored in the X300/310 EEPROM. Any entry that is designated "User Customizable?=No" can cause irreversible damage to the USRP and should only be altered by proper guidance from Ettus Support. For example, certain settings in the EEPROM could become corrupted and can be restored with the proper commands.

{| class="wikitable"
|'''X300/310 EEPROM Setting:'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Hardware Number
|-
|revision_compat
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique USRP Serial Number
|-
|mac-addr0
|No
|MAC Address (Port 0)
|-
|mac-addr1
|No
|MAC Address (Port 1)
|-
|gateway
|Yes
|Network Gateway
|-
|subnet0
|Yes
|Subnet Mask
|-
|subnet1
|Yes
|Subnet Mask
|-
|subnet2
|Yes
|Subnet Mask
|-
|subnet3
|Yes
|Subnet Mask
|-
|ip-addr0
|Yes
|IP Address
|-
|ip-addr1
|Yes
|IP Address
|-
|ip-addr2
|Yes
|IP Address
|-
|ip-addr3
|Yes
|IP Address
|-
|name
|Yes
|Custom USRP Name
|}

As an example, the EEPROM settings of an X310 with IP address 192.168.10.2 could be read-back with the following command:

./usrp_burn_mb_eeprom --args="addr=192.168.10.2,type=x300" --read-all

and the output would look like:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["revision_compat"] is "2"
EEPROM ["product"] is "30AD2D4"
EEPROM ["mac-addr0"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["mac-addr1"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["gateway"] is "192.168.10.1"
EEPROM ["ip-addr0"] is "192.168.10.2"
EEPROM ["subnet0"] is "255.255.255.0"
EEPROM ["ip-addr1"] is "192.168.20.2"
EEPROM ["subnet1"] is "255.255.255.0"
EEPROM ["ip-addr2"] is "192.168.10.3"
EEPROM ["subnet2"] is "255.255.255.0"
EEPROM ["ip-addr3"] is "192.168.40.2"
EEPROM ["subnet3"] is "255.255.255.0"
EEPROM ["serial"] is "30AF217"
EEPROM ["name"] is ""
</pre>

==Determining X300/X310 Revision Number==
It is useful in many cases to determine the revision number of your X300/X310. A part number sticker is located on the X300/310 motherboard. This sticker is located near the AUX-I/O connector and has the format 123456\<R>-\<XXX> where \<R> is a letter code that corresponds to the revision number. The photograph below highlights the location of the sticker:

<center>
<div><ul>
<li style="display: inline-block;"> [[File:an-309-x3x0-rev-id.png|thumb|500px|center|The USRP X300/310 motherboard has a sticker that identifies the product and revision. The sticker is outlined in red.]] </li>
</ul></div>
</center>

Once the letter code has been determined use the table below to map the letter code to a revision number:

{| class="wikitable"
|'''Letter'''
|'''Revision #'''
|-
|C
|3
|-
|D
|4
|-
|E
|5
|-
|F
|6
|-
|G
|7
|-
|H
|8
|-
|I
|N/A
|-
|J
|8
|-
|K
|8
|-
|}

==Restore X300/310 EEPROM Revision Code==

A corrupted or missing revision code in the X300/310 EEPROM will be indicated by a UHD runtime error:

Error: RuntimeError: No revision compat detected. MB EEPROM must be reprogrammed!

If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to restore the X300/310 revision code in the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number for your X300/310 is known, the usrp_burn_mb_eeprom utility can be used to restore the revision code to the EEPROM. The syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="revision=<#>"

where <#> is the revision number of your X300/310 to be written to the EEPROM. For example, to restore the revision number in EEPROM for a Rev. 6 X300 with an IP address of 192.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="revision=6"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==Restore X300/310 EEPROM Product Code==

A corrupted product code in the X300/310 EEPROM will be indicated by a UHD warning:

UHD Warning: X300/X310 unknown product code in EEPROM: <###>

where <###> is some numbered code that is unknown by UHD. If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to write a new product code to the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number has been determined, refer to the table below to find the product code for the X300/310:

{| class="wikitable"
|'''USRP'''
|'''Rev. 0-6'''
|'''Rev. 7-8'''
|-
|X300
|30518 (0x7736)
|30817 (0x7861)
|-
|X310
|30410 (0x76CA)
|30818 (0x7862)
|}

Once the correct product code has been determined base on the X3x0 model and revision, the usrp_burn_mb_eeprom utility can be used to write the correct product code to the EEPROM. They syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="product=<###>"

where <###> is the product code to be written to the EEPROM. For example, on a Rev. 7 X300 with an IP address of 191.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="product=30817"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==National Instruments USRP RIO==

The National Instruments branded X300/310 have unique product codes to identify the motherboard revision as well as the daughter-cards in the USRP. The product codes are listed below:

{| class="wikitable"
|'''Model (DB, BW, Rev.)'''
|'''Hex ID'''
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 0-6)
|0x772B
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 7+)
|0x7853
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 0-6)
|0x77FB
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 7+)
|0x785B
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 0-6)
|0x772C
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 7+)
|0x7854
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 0-6)
|0x77FC
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 7+)
|0x785C
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 0-6)
|0x772D
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 7+)
|0x7855
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 0-6)
|0x77FD
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 7+)
|0x785D
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 0-6)
|0x772E
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 7+)
|0x7856
|-
|USRP-2945R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78EF
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 0-6)
|0x772F
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 7+)
|0x7857
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 0-6)
|0x77FE
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 7+
|0x785E
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 0-6)
|0x7730
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 7+)
|0x7858
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 0-6)
|0x77FF
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 7+
|0x785F
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 0-6)
|0x7731
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 7+)
|0x7859
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 0-6)
|0x7800
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 7+)
|0x7860
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 0-6)
|0x7732
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 7+)
|0x785A
|-
|USRP-2955R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78F0
|-
|}

=N200/210 EEPROM=

{| class="wikitable"
|'''N200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|hardware
|No
|Hardware Number
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|mac-addr
|No
|MAC Address
|-
|ip-addr
|Yes
|IP Address
|-
|subnet
|Yes
|Subnetwork
|-
|gateway
|Yes
|Network Gateway
|-
|}

The N200/210 do not store the product codes in the motherboard EEPROM. The "hardware" field is programmed at the factory but is not referenced by UHD. Instead, the revision field is used to determine the N200/210 hardware in use.

{| class="wikitable"
|'''USRP'''
|'''Motherboard Product ID'''
|-
|N200
|0x0A00
|-
|N210
|0x0A01
|-
|N200 - R4
|0x0A10
|-
|N210 - R4
|0x0A11
|-
|}

=B200/210 and B200mini EEPROM=

The USRP B200 and B210 EEPROM is used to store certain information about each board. The USB PID (Product ID) and VID (Vendor ID) are stored in the EEPROM as well as serial number, product code, hardware revision, and USRP name for each B200/210. A table of these settings and whether or not the setting is user customizable is given below:

{| class="wikitable"
|'''B200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique Serial Number
|-
|name
|Yes
|Custom USRP Name
|-
|}

To read the current EEPROM values from the USRP, use the usrp_burn_mb_eeprom utility:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

This will read the settings and print them to the terminal. A sample output is shown below for a USRP B210:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "MyB210"
</pre>

If desired, a B200/210 could be given a custom name with the following command:

./usrp_burn_mb_eeprom --args="type=b200" --values="name=Lab_B210"

After the command has been run, the device must be power-cycled for the new EEPROM setting to take effect. Reading the updated EEPROM values yields:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "Lab_B210"
</pre>

==EEPROM Product ID==

The product code and the product revision stored in the EEPROM of the USRP
B200/B210 devices are used to identify the specific model and revision of the
device. The product code is a unique identifier that corresponds to the
specific hardware design, while the product revision indicates the version of
that design.

In case of EEPROM corruption, the following table can help identify the correct
revision and product code that is written into the EEPROM during the manufacturing
process, by comparing to the USRP Type and NI Part Number, which can be found
on the blue sticker on the PCB. The "Letter Revision" is the last letter of
the NI Part Number.

{| class="wikitable"
|'''USRP Type'''
|'''NI PN'''
|'''Letter Revision'''
|'''EEPROM Product Code (Ettus Branding)'''
|'''EEPROM Product Code (NI Branding)'''
|'''EEPROM Revision No'''
|'''Comments'''
|-
|B210
|156229A-01L, 156229B-01L
|A, B
|2
|0x7738, 0x7814
|4
|
|-
|B200
|156229A-02L, 156229B-02L
|A, B
|1
|0x7737, 0x7813
|4
|
|-
|B200
|156229C-02L, 156229D-02L
|C, D
|1
|0x7737, 0x7813
|5
|This revision switched from AD9361 to AD9634, and thus had to switch the RF side.
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034A-01L, 159034A-02L, 159034A-03L
|A
|0x0003, 0x0004
|0x7739, 0x773a
|1
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034B-01L, 159034B-02L, 159034B-03L
|B
|0x0003, 0x0004
|0x7739, 0x773a
|2
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034C-01L, 159034C-02L, 159034C-03L
|C
|0x0003, 0x0004
|0x7739, 0x773a
|3
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034D-01L, 159034D-02L, 159034D-03L
|D
|0x0003, 0x0004
|0x7739, 0x773a
|4
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034E-01L, 159034E-02L, 159034E-03L
|E
|0x0003, 0x0004
|0x7739, 0x773a
|5
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034{F,G}-01L, 159034{F,G}-02L, 159034{F,G}-03L
|{F,G}
|0x0003, 0x0004
|0x7739, 0x773a
|6
|
|-
|B206mini
|117434A-01L
|A
|0x0005
|0x773b
|1
|
|-
|B206mini
|117434B-01L
|B
|0x0005
|0x773b
|2
|
|-
|}

==USB VID/PID==

The USB vendor identification (VID) and product identification (PID) numbers can be written to the USRP B200/210 using the "b2xx_fx3_utils" utility that is included with UHD. To reset the VID and PID, the command would be:

./b2xx_fx3_utils --init-device --write-vid 0x2500 --write-pid -0x0020 --write-serial $SERIAL

{| class="wikitable"
|'''USRP'''
|'''USB PID'''
|-
|B200
|0x0020
|-
|B210
|0x0020
|-
|B200 (NI)
|0x7813
|-
|B210 (NI)
|0x7814
|-
|B200mini
|0x0021
|-
|B205mini
|0x0022
|-
|B206mini
|0x0023
|-
|}

The VID is the same for all B2x0 variants, 0x2500.

=Daughtercard IDs=

Below is a comprehensive list of the daughtercard hex ID's.

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|Basic Tx
| 0x0000
|-
|Basic Rx
| 0x0001
|-
|DBS Rx
| 0x0002
|-
|TV Rx
| 0x0003
|-
|Flex 400 Rx
| 0x0004
|-
|Flex 900 Rx
| 0x0005
|-
|Flex 1200 Rx
| 0x0006
|-
|Flex 2400 Rx
| 0x0007
|-
|Flex 400 Tx
| 0x0008
|-
|Flex 900 Tx
| 0x0009
|-
|Flex 1200 Tx
| 0x000a
|-
|Flex 2400 Tx
| 0x000b
|-
|TV Rx Rev 2
| 0x000c
|-
|DBS Rx ClkMod
| 0x000d
|-
|LF Tx
| 0x000e
|-
|LF Rx
| 0x000f
|-
|DBSRX2
| 0x012
|-
|Flex 400 Rx MIMO A
| 0x0014
|-
|Flex 900 Rx MIMO A
| 0x0015
|-
|Flex 1200 Rx MIMO A
| 0x0016
|-
|Flex 2400 Rx MIMO A
| 0x0017
|-
|Flex 400 Tx MIMO A
| 0x0018
|-
|Flex 900 Tx MIMO A
| 0x0019
|-
|Flex 1200 Tx MIMO A
| 0x001a
|-
|Flex 2400 Tx MIMO A
| 0x001b
|-
|Flex 400 Rx MIMO B
| 0x0024
|-
|Flex 900 Rx MIMO B
| 0x0025
|-
|Flex 1200 Rx MIMO B
| 0x0026
|-
|Flex 2400 Rx MIMO B
| 0x0027
|-
|Flex 400 Tx MIMO B
| 0x0028
|-
|Flex 900 Tx MIMO B
| 0x0029
|-
|Flex 1200 Tx MIMO B
| 0x002a
|-
|Flex 2400 Tx MIMO B
| 0x002b
|-
|Flex 2200 Rx MIMO B
| 0x002c
|-
|Flex 2200 Tx MIMO B
| 0x002d
|-
|Flex 1800 Rx
| 0x0030
|-
|Flex 1800 Tx
| 0x0031
|-
|Flex 1800 Rx MIMO A
| 0x0032
|-
|Flex 1800 Tx MIMO A
| 0x0033
|-
|Flex 1800 Rx MIMO B
| 0x0034
|-
|Flex 1800 Tx MIMO B
| 0x0035
|-
|TV Rx Rev 3
| 0x0040
|-
|DTT754
| 0x0041
|-
|DTT768
| 0x0042
|-
|TV Rx MIMO
| 0x0043
|-
|TV Rx Rev 2 MIMO
| 0x0044
|-
|TV Rx Rev 3 MIMO
| 0x0045
|-
|TVRX2
| 0x0046
|-
|WCDMA US
| 0x004d
|-
|WCDMA EU
| 0x004e
|-
|SIMPLE GDB
| 0x004f
|-
|WBX LO TX
| 0x0050
|-
|WBX LO RX
| 0x0051
|-
|WBX NG TX
| 0x0052
|-
|WBX NG RX
| 0x0053
|-
|SBX v3 RX
| 0x0054
|-
|SBX v3 TX
| 0x0055
|-
|WBX v3 TX
| 0x0056
|-
|WBX v3 RX
| 0x0057
|-
|XCVR2450 - No Div
| 0x0059
|-
|XCVR2450 TX
| 0x0060
|-
|XCVR2450 RX
| 0x0061
|-
|WBX v4 TX
| 0x0062
|-
|WBX v4 RX
| 0x0063
|-
|SBX v4 TX
| 0x0064
|-
|SBX v4 RX
| 0x0065
|-
|CBX v1 TX
| 0x0066
|-
|CBX v1 RX
| 0x0067
|-
|SBX v5 TX
| 0x0068
|-
|SBX v5 RX
| 0x0069
|-
|UBX-Prototype v3 TX
| 0x0073
|-
|UBX-Prototype v3 RX
| 0x0074
|-
|UBX-Prototype v4 TX
| 0x0075
|-
|UBX-Prototype v4 RX
| 0x0076
|-
|UBX v1 TX
| 0x0077
|-
|UBX v1 RX
| 0x0078
|-
|UBX-160 v1 TX
| 0x0079
|-
|UBX-160 v1 RX
| 0x007a
|-

|UBX-40 v2 TX
| 0x007b
|-
|UBX-40 v2 RX
| 0x007c
|-

|UBX-160 v2 TX
| 0x007d
|-
|UBX-160 v2 RX
| 0x007e
|-

|Bitshark RX
| 0x0070
|-
|B150 v1 TX
| 0x0071
|-
|B150 v1 RX
| 0x0072
|-
|WBX-120 v1 TX
| 0x0080
|-
|WBX-120 v1 RX
| 0x0081
|-
|SBX-120 v1 TX
| 0x0082
|-
|SBX-120 v1 RX
| 0x0083
|-
|CBX-120 v1 TX
| 0x0084
|-
|CBX-120 v1 RX
| 0x0085
|-
|TwinRX Rev A TX
| 0x0090
|-
|TwinRX Rev A RX
| 0x0091
|-
|TwinRX Rev B TX
| 0x0092
|-
|TwinRX Rev B RX
| 0x0093
|-
|TwinRX Rev C TX
| 0x0094
|-
|TwinRX Rev C RX
| 0x0095
|-
|E300 AD3964 DB RevB
| 0x0100
|-
|E310 AD9361 DB RevB
| 0x0110
|-
|E300 AD9364 DB RevC
| 0x0101
|-
|E310 AD9361 DB RevC
| 0x0111
|-
|Unknown Tx
| 0xfff0
|-
|Unknown Rx
| 0xfff1
|-
|}

=Motherboard IDs=

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|B200
|0x7737
|-
|B210
|0x7738
|-
|B200mini
|0x7739
|-
|B205mini
|0x773a
|-
|}

[[Category:Application Notes]]

About the Motherboard and Daughtercard EEPROM on USRP Devices

2025-07-15T07:09:37Z

MartinBraun: /* USB VID/PID */

==Application Note Number and Authors ==
'''AN-309''' by Trip Humphries and Michael Dickens


=USRP EEPROM Settings & Recovery Guide=

Some USRP products contain an EEPROM on the motherboard which is used to store information about the USRP. Currently, the N200/210, X300/310, B200/210, and E100 contain an on-board EEPROM. The EEPROM contains information about each USRP such as product code, revision number, USRP name, and IP address. The specific information stores on each USRP EEPROM is dependent on the USRP model.

Daughter boards also contain an EEPROM that contains identification information about the daughter board. UHD reads the daughter board ID to determine the model and revision (if applicable) of the daughter board. This information is used to properly configure the USRP and daughter board for proper function.

==EEPROM Burn Utility==

'''Disclaimer: Ettus Research accepts no liability for misuse of this utility. It can very easily cause irreversible damage if used incorrectly! Please contact Ettus support at [mailto:support@ettus.com support@ettus.com] if you are unsure how to proceed.'''

A utility, usrp_burn_mb_eeprom, is included with UHD to read/write values on the various motherboards that contain an EEPROM. The utility is located in the UHD install directory. The default folder is:

/usr/local/lib/uhd/utils/

The utility can be used with the USRP X300/310, N200/210, B200/210, and E100. In some cases, it is necessary to use the utility to write custom user settings to the USRP, such as USRP name or IP address. In other cases, some EEPROM settings set by the factory may become corrupted and need to be restored. This section will cover basic usage of the usrp_burn_mb_eeprom utility, with USRP specific instructions covered in the sections below.

EEPROM settings can be read using the usrp_burn_mb_eeprom utility. All the EEPROM settings can be read at once using the 'read all' option:

./usrp_burn_mb_eeprom --args=<optional device args> --read-all

This will return the current contents in the EEPROM for the specified USRP. For example, if you want to read all the EEPROM contents for a USRP B210, the command would look like:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

The EEPROM settings vary based on the specific USRP in use. The following sections document the EEPROM settings available for each USRP. Examples for each USRP with an EEPROM are also given.

=X300/310 EEPROM=
The EEPROM on the X300/310 stores useful information about the USRP so that UHD can set the proper settings based on model and revision. Some of these settings are user customizable. The table below outlines the values stored in the X300/310 EEPROM. Any entry that is designated "User Customizable?=No" can cause irreversible damage to the USRP and should only be altered by proper guidance from Ettus Support. For example, certain settings in the EEPROM could become corrupted and can be restored with the proper commands.

{| class="wikitable"
|'''X300/310 EEPROM Setting:'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Hardware Number
|-
|revision_compat
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique USRP Serial Number
|-
|mac-addr0
|No
|MAC Address (Port 0)
|-
|mac-addr1
|No
|MAC Address (Port 1)
|-
|gateway
|Yes
|Network Gateway
|-
|subnet0
|Yes
|Subnet Mask
|-
|subnet1
|Yes
|Subnet Mask
|-
|subnet2
|Yes
|Subnet Mask
|-
|subnet3
|Yes
|Subnet Mask
|-
|ip-addr0
|Yes
|IP Address
|-
|ip-addr1
|Yes
|IP Address
|-
|ip-addr2
|Yes
|IP Address
|-
|ip-addr3
|Yes
|IP Address
|-
|name
|Yes
|Custom USRP Name
|}

As an example, the EEPROM settings of an X310 with IP address 192.168.10.2 could be read-back with the following command:

./usrp_burn_mb_eeprom --args="addr=192.168.10.2,type=x300" --read-all

and the output would look like:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["revision_compat"] is "2"
EEPROM ["product"] is "30AD2D4"
EEPROM ["mac-addr0"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["mac-addr1"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["gateway"] is "192.168.10.1"
EEPROM ["ip-addr0"] is "192.168.10.2"
EEPROM ["subnet0"] is "255.255.255.0"
EEPROM ["ip-addr1"] is "192.168.20.2"
EEPROM ["subnet1"] is "255.255.255.0"
EEPROM ["ip-addr2"] is "192.168.10.3"
EEPROM ["subnet2"] is "255.255.255.0"
EEPROM ["ip-addr3"] is "192.168.40.2"
EEPROM ["subnet3"] is "255.255.255.0"
EEPROM ["serial"] is "30AF217"
EEPROM ["name"] is ""
</pre>

==Determining X300/X310 Revision Number==
It is useful in many cases to determine the revision number of your X300/X310. A part number sticker is located on the X300/310 motherboard. This sticker is located near the AUX-I/O connector and has the format 123456\<R>-\<XXX> where \<R> is a letter code that corresponds to the revision number. The photograph below highlights the location of the sticker:

<center>
<div><ul>
<li style="display: inline-block;"> [[File:an-309-x3x0-rev-id.png|thumb|500px|center|The USRP X300/310 motherboard has a sticker that identifies the product and revision. The sticker is outlined in red.]] </li>
</ul></div>
</center>

Once the letter code has been determined use the table below to map the letter code to a revision number:

{| class="wikitable"
|'''Letter'''
|'''Revision #'''
|-
|C
|3
|-
|D
|4
|-
|E
|5
|-
|F
|6
|-
|G
|7
|-
|H
|8
|-
|I
|N/A
|-
|J
|8
|-
|K
|8
|-
|}

==Restore X300/310 EEPROM Revision Code==

A corrupted or missing revision code in the X300/310 EEPROM will be indicated by a UHD runtime error:

Error: RuntimeError: No revision compat detected. MB EEPROM must be reprogrammed!

If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to restore the X300/310 revision code in the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number for your X300/310 is known, the usrp_burn_mb_eeprom utility can be used to restore the revision code to the EEPROM. The syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="revision=<#>"

where <#> is the revision number of your X300/310 to be written to the EEPROM. For example, to restore the revision number in EEPROM for a Rev. 6 X300 with an IP address of 192.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="revision=6"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==Restore X300/310 EEPROM Product Code==

A corrupted product code in the X300/310 EEPROM will be indicated by a UHD warning:

UHD Warning: X300/X310 unknown product code in EEPROM: <###>

where <###> is some numbered code that is unknown by UHD. If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to write a new product code to the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number has been determined, refer to the table below to find the product code for the X300/310:

{| class="wikitable"
|'''USRP'''
|'''Rev. 0-6'''
|'''Rev. 7-8'''
|-
|X300
|30518 (0x7736)
|30817 (0x7861)
|-
|X310
|30410 (0x76CA)
|30818 (0x7862)
|}

Once the correct product code has been determined base on the X3x0 model and revision, the usrp_burn_mb_eeprom utility can be used to write the correct product code to the EEPROM. They syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="product=<###>"

where <###> is the product code to be written to the EEPROM. For example, on a Rev. 7 X300 with an IP address of 191.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="product=30817"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==National Instruments USRP RIO==

The National Instruments branded X300/310 have unique product codes to identify the motherboard revision as well as the daughter-cards in the USRP. The product codes are listed below:

{| class="wikitable"
|'''Model (DB, BW, Rev.)'''
|'''Hex ID'''
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 0-6)
|0x772B
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 7+)
|0x7853
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 0-6)
|0x77FB
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 7+)
|0x785B
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 0-6)
|0x772C
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 7+)
|0x7854
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 0-6)
|0x77FC
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 7+)
|0x785C
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 0-6)
|0x772D
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 7+)
|0x7855
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 0-6)
|0x77FD
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 7+)
|0x785D
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 0-6)
|0x772E
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 7+)
|0x7856
|-
|USRP-2945R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78EF
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 0-6)
|0x772F
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 7+)
|0x7857
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 0-6)
|0x77FE
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 7+
|0x785E
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 0-6)
|0x7730
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 7+)
|0x7858
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 0-6)
|0x77FF
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 7+
|0x785F
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 0-6)
|0x7731
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 7+)
|0x7859
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 0-6)
|0x7800
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 7+)
|0x7860
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 0-6)
|0x7732
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 7+)
|0x785A
|-
|USRP-2955R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78F0
|-
|}

=N200/210 EEPROM=

{| class="wikitable"
|'''N200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|hardware
|No
|Hardware Number
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|mac-addr
|No
|MAC Address
|-
|ip-addr
|Yes
|IP Address
|-
|subnet
|Yes
|Subnetwork
|-
|gateway
|Yes
|Network Gateway
|-
|}

The N200/210 do not store the product codes in the motherboard EEPROM. The "hardware" field is programmed at the factory but is not referenced by UHD. Instead, the revision field is used to determine the N200/210 hardware in use.

{| class="wikitable"
|'''USRP'''
|'''Motherboard Product ID'''
|-
|N200
|0x0A00
|-
|N210
|0x0A01
|-
|N200 - R4
|0x0A10
|-
|N210 - R4
|0x0A11
|-
|}

=B200/210 and B200mini EEPROM=

The USRP B200 and B210 EEPROM is used to store certain information about each board. The USB PID (Product ID) and VID (Vendor ID) are stored in the EEPROM as well as serial number, product code, hardware revision, and USRP name for each B200/210. A table of these settings and whether or not the setting is user customizable is given below:

{| class="wikitable"
|'''B200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique Serial Number
|-
|name
|Yes
|Custom USRP Name
|-
|}

To read the current EEPROM values from the USRP, use the usrp_burn_mb_eeprom utility:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

This will read the settings and print them to the terminal. A sample output is shown below for a USRP B210:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "MyB210"
</pre>

If desired, a B200/210 could be given a custom name with the following command:

./usrp_burn_mb_eeprom --args="type=b200" --values="name=Lab_B210"

After the command has been run, the device must be power-cycled for the new EEPROM setting to take effect. Reading the updated EEPROM values yields:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "Lab_B210"
</pre>

==EEPROM Product ID==

The product code and the product revision stored in the EEPROM of the USRP
B200/B210 devices are used to identify the specific model and revision of the
device. The product code is a unique identifier that corresponds to the
specific hardware design, while the product revision indicates the version of
that design.

In case of EEPROM corruption, the following table can help identify the correct
revision and product code that is written into the EEPROM during the manufacturing
process, by comparing to the USRP Type and NI Part Number, which can be found
on the blue sticker on the PCB. The "Letter Revision" is the last letter of
the NI Part Number.

{| class="wikitable"
|'''USRP Type'''
|'''NI PN'''
|'''Letter Revision'''
|'''EEPROM Product Code (Ettus Branding)'''
|'''EEPROM Product Code (NI Branding)'''
|'''EEPROM Revision No'''
|'''Comments'''
|-
|B210
|156229A-01L, 156229B-01L
|A, B
|2
|0x7738, 0x7814
|4
|
|-
|B200
|156229A-02L, 156229B-02L
|A, B
|1
|0x7737, 0x7813
|4
|
|-
|B200
|156229C-02L, 156229D-02L
|C, D
|1
|0x7737, 0x7813
|5
|This revision switched from AD9361 to AD9634, and thus had to switch the RF side.
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034A-01L, 159034A-02L, 159034A-03L
|A
|0x0003, 0x0004
|0x7739, 0x773a
|1
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034B-01L, 159034B-02L, 159034B-03L
|B
|0x0003, 0x0004
|0x7739, 0x773a
|2
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034C-01L, 159034C-02L, 159034C-03L
|C
|0x0003, 0x0004
|0x7739, 0x773a
|3
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034D-01L, 159034D-02L, 159034D-03L
|D
|0x0003, 0x0004
|0x7739, 0x773a
|4
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034E-01L, 159034E-02L, 159034E-03L
|E
|0x0003, 0x0004
|0x7739, 0x773a
|5
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034{F,G}-01L, 159034{F,G}-02L, 159034{F,G}-03L
|{F,G}
|0x0003, 0x0004
|0x7739, 0x773a
|6
|
|-
|B206mini
|117434A-01L
|A
|0x0005
|0x773b
|1
|
|-
|B206mini
|117434B-01L
|B
|0x0005
|0x773b
|2
|
|-
|}

==USB VID/PID==

The USB vendor identification (VID) and product identification (PID) numbers can be written to the USRP B200/210 using the "b2xx_fx3_utils" utility that is included with UHD. To reset the VID and PID, the command would be:

./b2xx_fx3_utils --init-device --write-vid 0x2500 --write-pid -0x0020

{| class="wikitable"
|'''USRP'''
|'''USB PID'''
|-
|B200
|0x0020
|-
|B210
|0x0020
|-
|B200 (NI)
|0x7813
|-
|B210 (NI)
|0x7814
|-
|B200mini
|0x0021
|-
|B205mini
|0x0022
|-
|B206mini
|0x0023
|-
|}

The VID is the same for all B2x0 variants, 0x2500.

=Daughtercard IDs=

Below is a comprehensive list of the daughtercard hex ID's.

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|Basic Tx
| 0x0000
|-
|Basic Rx
| 0x0001
|-
|DBS Rx
| 0x0002
|-
|TV Rx
| 0x0003
|-
|Flex 400 Rx
| 0x0004
|-
|Flex 900 Rx
| 0x0005
|-
|Flex 1200 Rx
| 0x0006
|-
|Flex 2400 Rx
| 0x0007
|-
|Flex 400 Tx
| 0x0008
|-
|Flex 900 Tx
| 0x0009
|-
|Flex 1200 Tx
| 0x000a
|-
|Flex 2400 Tx
| 0x000b
|-
|TV Rx Rev 2
| 0x000c
|-
|DBS Rx ClkMod
| 0x000d
|-
|LF Tx
| 0x000e
|-
|LF Rx
| 0x000f
|-
|DBSRX2
| 0x012
|-
|Flex 400 Rx MIMO A
| 0x0014
|-
|Flex 900 Rx MIMO A
| 0x0015
|-
|Flex 1200 Rx MIMO A
| 0x0016
|-
|Flex 2400 Rx MIMO A
| 0x0017
|-
|Flex 400 Tx MIMO A
| 0x0018
|-
|Flex 900 Tx MIMO A
| 0x0019
|-
|Flex 1200 Tx MIMO A
| 0x001a
|-
|Flex 2400 Tx MIMO A
| 0x001b
|-
|Flex 400 Rx MIMO B
| 0x0024
|-
|Flex 900 Rx MIMO B
| 0x0025
|-
|Flex 1200 Rx MIMO B
| 0x0026
|-
|Flex 2400 Rx MIMO B
| 0x0027
|-
|Flex 400 Tx MIMO B
| 0x0028
|-
|Flex 900 Tx MIMO B
| 0x0029
|-
|Flex 1200 Tx MIMO B
| 0x002a
|-
|Flex 2400 Tx MIMO B
| 0x002b
|-
|Flex 2200 Rx MIMO B
| 0x002c
|-
|Flex 2200 Tx MIMO B
| 0x002d
|-
|Flex 1800 Rx
| 0x0030
|-
|Flex 1800 Tx
| 0x0031
|-
|Flex 1800 Rx MIMO A
| 0x0032
|-
|Flex 1800 Tx MIMO A
| 0x0033
|-
|Flex 1800 Rx MIMO B
| 0x0034
|-
|Flex 1800 Tx MIMO B
| 0x0035
|-
|TV Rx Rev 3
| 0x0040
|-
|DTT754
| 0x0041
|-
|DTT768
| 0x0042
|-
|TV Rx MIMO
| 0x0043
|-
|TV Rx Rev 2 MIMO
| 0x0044
|-
|TV Rx Rev 3 MIMO
| 0x0045
|-
|TVRX2
| 0x0046
|-
|WCDMA US
| 0x004d
|-
|WCDMA EU
| 0x004e
|-
|SIMPLE GDB
| 0x004f
|-
|WBX LO TX
| 0x0050
|-
|WBX LO RX
| 0x0051
|-
|WBX NG TX
| 0x0052
|-
|WBX NG RX
| 0x0053
|-
|SBX v3 RX
| 0x0054
|-
|SBX v3 TX
| 0x0055
|-
|WBX v3 TX
| 0x0056
|-
|WBX v3 RX
| 0x0057
|-
|XCVR2450 - No Div
| 0x0059
|-
|XCVR2450 TX
| 0x0060
|-
|XCVR2450 RX
| 0x0061
|-
|WBX v4 TX
| 0x0062
|-
|WBX v4 RX
| 0x0063
|-
|SBX v4 TX
| 0x0064
|-
|SBX v4 RX
| 0x0065
|-
|CBX v1 TX
| 0x0066
|-
|CBX v1 RX
| 0x0067
|-
|SBX v5 TX
| 0x0068
|-
|SBX v5 RX
| 0x0069
|-
|UBX-Prototype v3 TX
| 0x0073
|-
|UBX-Prototype v3 RX
| 0x0074
|-
|UBX-Prototype v4 TX
| 0x0075
|-
|UBX-Prototype v4 RX
| 0x0076
|-
|UBX v1 TX
| 0x0077
|-
|UBX v1 RX
| 0x0078
|-
|UBX-160 v1 TX
| 0x0079
|-
|UBX-160 v1 RX
| 0x007a
|-

|UBX-40 v2 TX
| 0x007b
|-
|UBX-40 v2 RX
| 0x007c
|-

|UBX-160 v2 TX
| 0x007d
|-
|UBX-160 v2 RX
| 0x007e
|-

|Bitshark RX
| 0x0070
|-
|B150 v1 TX
| 0x0071
|-
|B150 v1 RX
| 0x0072
|-
|WBX-120 v1 TX
| 0x0080
|-
|WBX-120 v1 RX
| 0x0081
|-
|SBX-120 v1 TX
| 0x0082
|-
|SBX-120 v1 RX
| 0x0083
|-
|CBX-120 v1 TX
| 0x0084
|-
|CBX-120 v1 RX
| 0x0085
|-
|TwinRX Rev A TX
| 0x0090
|-
|TwinRX Rev A RX
| 0x0091
|-
|TwinRX Rev B TX
| 0x0092
|-
|TwinRX Rev B RX
| 0x0093
|-
|TwinRX Rev C TX
| 0x0094
|-
|TwinRX Rev C RX
| 0x0095
|-
|E300 AD3964 DB RevB
| 0x0100
|-
|E310 AD9361 DB RevB
| 0x0110
|-
|E300 AD9364 DB RevC
| 0x0101
|-
|E310 AD9361 DB RevC
| 0x0111
|-
|Unknown Tx
| 0xfff0
|-
|Unknown Rx
| 0xfff1
|-
|}

=Motherboard IDs=

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|B200
|0x7737
|-
|B210
|0x7738
|-
|B200mini
|0x7739
|-
|B205mini
|0x773a
|-
|}

[[Category:Application Notes]]

About the Motherboard and Daughtercard EEPROM on USRP Devices

2025-07-14T07:47:50Z

MartinBraun: /* EEPROM Product ID */

==Application Note Number and Authors ==
'''AN-309''' by Trip Humphries and Michael Dickens


=USRP EEPROM Settings & Recovery Guide=

Some USRP products contain an EEPROM on the motherboard which is used to store information about the USRP. Currently, the N200/210, X300/310, B200/210, and E100 contain an on-board EEPROM. The EEPROM contains information about each USRP such as product code, revision number, USRP name, and IP address. The specific information stores on each USRP EEPROM is dependent on the USRP model.

Daughter boards also contain an EEPROM that contains identification information about the daughter board. UHD reads the daughter board ID to determine the model and revision (if applicable) of the daughter board. This information is used to properly configure the USRP and daughter board for proper function.

==EEPROM Burn Utility==

'''Disclaimer: Ettus Research accepts no liability for misuse of this utility. It can very easily cause irreversible damage if used incorrectly! Please contact Ettus support at [mailto:support@ettus.com support@ettus.com] if you are unsure how to proceed.'''

A utility, usrp_burn_mb_eeprom, is included with UHD to read/write values on the various motherboards that contain an EEPROM. The utility is located in the UHD install directory. The default folder is:

/usr/local/lib/uhd/utils/

The utility can be used with the USRP X300/310, N200/210, B200/210, and E100. In some cases, it is necessary to use the utility to write custom user settings to the USRP, such as USRP name or IP address. In other cases, some EEPROM settings set by the factory may become corrupted and need to be restored. This section will cover basic usage of the usrp_burn_mb_eeprom utility, with USRP specific instructions covered in the sections below.

EEPROM settings can be read using the usrp_burn_mb_eeprom utility. All the EEPROM settings can be read at once using the 'read all' option:

./usrp_burn_mb_eeprom --args=<optional device args> --read-all

This will return the current contents in the EEPROM for the specified USRP. For example, if you want to read all the EEPROM contents for a USRP B210, the command would look like:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

The EEPROM settings vary based on the specific USRP in use. The following sections document the EEPROM settings available for each USRP. Examples for each USRP with an EEPROM are also given.

=X300/310 EEPROM=
The EEPROM on the X300/310 stores useful information about the USRP so that UHD can set the proper settings based on model and revision. Some of these settings are user customizable. The table below outlines the values stored in the X300/310 EEPROM. Any entry that is designated "User Customizable?=No" can cause irreversible damage to the USRP and should only be altered by proper guidance from Ettus Support. For example, certain settings in the EEPROM could become corrupted and can be restored with the proper commands.

{| class="wikitable"
|'''X300/310 EEPROM Setting:'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Hardware Number
|-
|revision_compat
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique USRP Serial Number
|-
|mac-addr0
|No
|MAC Address (Port 0)
|-
|mac-addr1
|No
|MAC Address (Port 1)
|-
|gateway
|Yes
|Network Gateway
|-
|subnet0
|Yes
|Subnet Mask
|-
|subnet1
|Yes
|Subnet Mask
|-
|subnet2
|Yes
|Subnet Mask
|-
|subnet3
|Yes
|Subnet Mask
|-
|ip-addr0
|Yes
|IP Address
|-
|ip-addr1
|Yes
|IP Address
|-
|ip-addr2
|Yes
|IP Address
|-
|ip-addr3
|Yes
|IP Address
|-
|name
|Yes
|Custom USRP Name
|}

As an example, the EEPROM settings of an X310 with IP address 192.168.10.2 could be read-back with the following command:

./usrp_burn_mb_eeprom --args="addr=192.168.10.2,type=x300" --read-all

and the output would look like:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["revision_compat"] is "2"
EEPROM ["product"] is "30AD2D4"
EEPROM ["mac-addr0"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["mac-addr1"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["gateway"] is "192.168.10.1"
EEPROM ["ip-addr0"] is "192.168.10.2"
EEPROM ["subnet0"] is "255.255.255.0"
EEPROM ["ip-addr1"] is "192.168.20.2"
EEPROM ["subnet1"] is "255.255.255.0"
EEPROM ["ip-addr2"] is "192.168.10.3"
EEPROM ["subnet2"] is "255.255.255.0"
EEPROM ["ip-addr3"] is "192.168.40.2"
EEPROM ["subnet3"] is "255.255.255.0"
EEPROM ["serial"] is "30AF217"
EEPROM ["name"] is ""
</pre>

==Determining X300/X310 Revision Number==
It is useful in many cases to determine the revision number of your X300/X310. A part number sticker is located on the X300/310 motherboard. This sticker is located near the AUX-I/O connector and has the format 123456\<R>-\<XXX> where \<R> is a letter code that corresponds to the revision number. The photograph below highlights the location of the sticker:

<center>
<div><ul>
<li style="display: inline-block;"> [[File:an-309-x3x0-rev-id.png|thumb|500px|center|The USRP X300/310 motherboard has a sticker that identifies the product and revision. The sticker is outlined in red.]] </li>
</ul></div>
</center>

Once the letter code has been determined use the table below to map the letter code to a revision number:

{| class="wikitable"
|'''Letter'''
|'''Revision #'''
|-
|C
|3
|-
|D
|4
|-
|E
|5
|-
|F
|6
|-
|G
|7
|-
|H
|8
|-
|I
|N/A
|-
|J
|8
|-
|K
|8
|-
|}

==Restore X300/310 EEPROM Revision Code==

A corrupted or missing revision code in the X300/310 EEPROM will be indicated by a UHD runtime error:

Error: RuntimeError: No revision compat detected. MB EEPROM must be reprogrammed!

If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to restore the X300/310 revision code in the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number for your X300/310 is known, the usrp_burn_mb_eeprom utility can be used to restore the revision code to the EEPROM. The syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="revision=<#>"

where <#> is the revision number of your X300/310 to be written to the EEPROM. For example, to restore the revision number in EEPROM for a Rev. 6 X300 with an IP address of 192.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="revision=6"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==Restore X300/310 EEPROM Product Code==

A corrupted product code in the X300/310 EEPROM will be indicated by a UHD warning:

UHD Warning: X300/X310 unknown product code in EEPROM: <###>

where <###> is some numbered code that is unknown by UHD. If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to write a new product code to the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number has been determined, refer to the table below to find the product code for the X300/310:

{| class="wikitable"
|'''USRP'''
|'''Rev. 0-6'''
|'''Rev. 7-8'''
|-
|X300
|30518 (0x7736)
|30817 (0x7861)
|-
|X310
|30410 (0x76CA)
|30818 (0x7862)
|}

Once the correct product code has been determined base on the X3x0 model and revision, the usrp_burn_mb_eeprom utility can be used to write the correct product code to the EEPROM. They syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="product=<###>"

where <###> is the product code to be written to the EEPROM. For example, on a Rev. 7 X300 with an IP address of 191.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="product=30817"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==National Instruments USRP RIO==

The National Instruments branded X300/310 have unique product codes to identify the motherboard revision as well as the daughter-cards in the USRP. The product codes are listed below:

{| class="wikitable"
|'''Model (DB, BW, Rev.)'''
|'''Hex ID'''
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 0-6)
|0x772B
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 7+)
|0x7853
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 0-6)
|0x77FB
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 7+)
|0x785B
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 0-6)
|0x772C
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 7+)
|0x7854
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 0-6)
|0x77FC
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 7+)
|0x785C
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 0-6)
|0x772D
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 7+)
|0x7855
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 0-6)
|0x77FD
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 7+)
|0x785D
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 0-6)
|0x772E
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 7+)
|0x7856
|-
|USRP-2945R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78EF
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 0-6)
|0x772F
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 7+)
|0x7857
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 0-6)
|0x77FE
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 7+
|0x785E
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 0-6)
|0x7730
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 7+)
|0x7858
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 0-6)
|0x77FF
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 7+
|0x785F
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 0-6)
|0x7731
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 7+)
|0x7859
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 0-6)
|0x7800
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 7+)
|0x7860
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 0-6)
|0x7732
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 7+)
|0x785A
|-
|USRP-2955R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78F0
|-
|}

=N200/210 EEPROM=

{| class="wikitable"
|'''N200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|hardware
|No
|Hardware Number
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|mac-addr
|No
|MAC Address
|-
|ip-addr
|Yes
|IP Address
|-
|subnet
|Yes
|Subnetwork
|-
|gateway
|Yes
|Network Gateway
|-
|}

The N200/210 do not store the product codes in the motherboard EEPROM. The "hardware" field is programmed at the factory but is not referenced by UHD. Instead, the revision field is used to determine the N200/210 hardware in use.

{| class="wikitable"
|'''USRP'''
|'''Motherboard Product ID'''
|-
|N200
|0x0A00
|-
|N210
|0x0A01
|-
|N200 - R4
|0x0A10
|-
|N210 - R4
|0x0A11
|-
|}

=B200/210 and B200mini EEPROM=

The USRP B200 and B210 EEPROM is used to store certain information about each board. The USB PID (Product ID) and VID (Vendor ID) are stored in the EEPROM as well as serial number, product code, hardware revision, and USRP name for each B200/210. A table of these settings and whether or not the setting is user customizable is given below:

{| class="wikitable"
|'''B200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique Serial Number
|-
|name
|Yes
|Custom USRP Name
|-
|}

To read the current EEPROM values from the USRP, use the usrp_burn_mb_eeprom utility:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

This will read the settings and print them to the terminal. A sample output is shown below for a USRP B210:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "MyB210"
</pre>

If desired, a B200/210 could be given a custom name with the following command:

./usrp_burn_mb_eeprom --args="type=b200" --values="name=Lab_B210"

After the command has been run, the device must be power-cycled for the new EEPROM setting to take effect. Reading the updated EEPROM values yields:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "Lab_B210"
</pre>

==EEPROM Product ID==

The product code and the product revision stored in the EEPROM of the USRP
B200/B210 devices are used to identify the specific model and revision of the
device. The product code is a unique identifier that corresponds to the
specific hardware design, while the product revision indicates the version of
that design.

In case of EEPROM corruption, the following table can help identify the correct
revision and product code that is written into the EEPROM during the manufacturing
process, by comparing to the USRP Type and NI Part Number, which can be found
on the blue sticker on the PCB. The "Letter Revision" is the last letter of
the NI Part Number.

{| class="wikitable"
|'''USRP Type'''
|'''NI PN'''
|'''Letter Revision'''
|'''EEPROM Product Code (Ettus Branding)'''
|'''EEPROM Product Code (NI Branding)'''
|'''EEPROM Revision No'''
|'''Comments'''
|-
|B210
|156229A-01L, 156229B-01L
|A, B
|2
|0x7738, 0x7814
|4
|
|-
|B200
|156229A-02L, 156229B-02L
|A, B
|1
|0x7737, 0x7813
|4
|
|-
|B200
|156229C-02L, 156229D-02L
|C, D
|1
|0x7737, 0x7813
|5
|This revision switched from AD9361 to AD9634, and thus had to switch the RF side.
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034A-01L, 159034A-02L, 159034A-03L
|A
|0x0003, 0x0004
|0x7739, 0x773a
|1
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034B-01L, 159034B-02L, 159034B-03L
|B
|0x0003, 0x0004
|0x7739, 0x773a
|2
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034C-01L, 159034C-02L, 159034C-03L
|C
|0x0003, 0x0004
|0x7739, 0x773a
|3
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034D-01L, 159034D-02L, 159034D-03L
|D
|0x0003, 0x0004
|0x7739, 0x773a
|4
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034E-01L, 159034E-02L, 159034E-03L
|E
|0x0003, 0x0004
|0x7739, 0x773a
|5
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034{F,G}-01L, 159034{F,G}-02L, 159034{F,G}-03L
|{F,G}
|0x0003, 0x0004
|0x7739, 0x773a
|6
|
|-
|B206mini
|117434A-01L
|A
|0x0005
|0x773b
|1
|
|-
|B206mini
|117434B-01L
|B
|0x0005
|0x773b
|2
|
|-
|}

==USB VID/PID==

The USB vendor identification (VID) and product identification (PID) numbers can be written to the USRP B200/210 using the "b2xx_fx3_utils" utility that is included with UHD. To reset the VID and PID, the command would be:

./b2xx_fx3_utils --init-device --write-vid 0x2500 --write-pid -0x0020

{| class="wikitable"
|'''USRP'''
|'''USB PID'''
|-
|B200
|0x0020
|-
|B210
|0x0020
|-
|B200 (NI)
|0x7813
|-
|B210 (NI)
|0x7814
|-
|B200mini
|0x0021
|-
|B205mini
|0x0022
|-
|}

The VID is the same for all B2x0 variants, 0x2500.

=Daughtercard IDs=

Below is a comprehensive list of the daughtercard hex ID's.

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|Basic Tx
| 0x0000
|-
|Basic Rx
| 0x0001
|-
|DBS Rx
| 0x0002
|-
|TV Rx
| 0x0003
|-
|Flex 400 Rx
| 0x0004
|-
|Flex 900 Rx
| 0x0005
|-
|Flex 1200 Rx
| 0x0006
|-
|Flex 2400 Rx
| 0x0007
|-
|Flex 400 Tx
| 0x0008
|-
|Flex 900 Tx
| 0x0009
|-
|Flex 1200 Tx
| 0x000a
|-
|Flex 2400 Tx
| 0x000b
|-
|TV Rx Rev 2
| 0x000c
|-
|DBS Rx ClkMod
| 0x000d
|-
|LF Tx
| 0x000e
|-
|LF Rx
| 0x000f
|-
|DBSRX2
| 0x012
|-
|Flex 400 Rx MIMO A
| 0x0014
|-
|Flex 900 Rx MIMO A
| 0x0015
|-
|Flex 1200 Rx MIMO A
| 0x0016
|-
|Flex 2400 Rx MIMO A
| 0x0017
|-
|Flex 400 Tx MIMO A
| 0x0018
|-
|Flex 900 Tx MIMO A
| 0x0019
|-
|Flex 1200 Tx MIMO A
| 0x001a
|-
|Flex 2400 Tx MIMO A
| 0x001b
|-
|Flex 400 Rx MIMO B
| 0x0024
|-
|Flex 900 Rx MIMO B
| 0x0025
|-
|Flex 1200 Rx MIMO B
| 0x0026
|-
|Flex 2400 Rx MIMO B
| 0x0027
|-
|Flex 400 Tx MIMO B
| 0x0028
|-
|Flex 900 Tx MIMO B
| 0x0029
|-
|Flex 1200 Tx MIMO B
| 0x002a
|-
|Flex 2400 Tx MIMO B
| 0x002b
|-
|Flex 2200 Rx MIMO B
| 0x002c
|-
|Flex 2200 Tx MIMO B
| 0x002d
|-
|Flex 1800 Rx
| 0x0030
|-
|Flex 1800 Tx
| 0x0031
|-
|Flex 1800 Rx MIMO A
| 0x0032
|-
|Flex 1800 Tx MIMO A
| 0x0033
|-
|Flex 1800 Rx MIMO B
| 0x0034
|-
|Flex 1800 Tx MIMO B
| 0x0035
|-
|TV Rx Rev 3
| 0x0040
|-
|DTT754
| 0x0041
|-
|DTT768
| 0x0042
|-
|TV Rx MIMO
| 0x0043
|-
|TV Rx Rev 2 MIMO
| 0x0044
|-
|TV Rx Rev 3 MIMO
| 0x0045
|-
|TVRX2
| 0x0046
|-
|WCDMA US
| 0x004d
|-
|WCDMA EU
| 0x004e
|-
|SIMPLE GDB
| 0x004f
|-
|WBX LO TX
| 0x0050
|-
|WBX LO RX
| 0x0051
|-
|WBX NG TX
| 0x0052
|-
|WBX NG RX
| 0x0053
|-
|SBX v3 RX
| 0x0054
|-
|SBX v3 TX
| 0x0055
|-
|WBX v3 TX
| 0x0056
|-
|WBX v3 RX
| 0x0057
|-
|XCVR2450 - No Div
| 0x0059
|-
|XCVR2450 TX
| 0x0060
|-
|XCVR2450 RX
| 0x0061
|-
|WBX v4 TX
| 0x0062
|-
|WBX v4 RX
| 0x0063
|-
|SBX v4 TX
| 0x0064
|-
|SBX v4 RX
| 0x0065
|-
|CBX v1 TX
| 0x0066
|-
|CBX v1 RX
| 0x0067
|-
|SBX v5 TX
| 0x0068
|-
|SBX v5 RX
| 0x0069
|-
|UBX-Prototype v3 TX
| 0x0073
|-
|UBX-Prototype v3 RX
| 0x0074
|-
|UBX-Prototype v4 TX
| 0x0075
|-
|UBX-Prototype v4 RX
| 0x0076
|-
|UBX v1 TX
| 0x0077
|-
|UBX v1 RX
| 0x0078
|-
|UBX-160 v1 TX
| 0x0079
|-
|UBX-160 v1 RX
| 0x007a
|-

|UBX-40 v2 TX
| 0x007b
|-
|UBX-40 v2 RX
| 0x007c
|-

|UBX-160 v2 TX
| 0x007d
|-
|UBX-160 v2 RX
| 0x007e
|-

|Bitshark RX
| 0x0070
|-
|B150 v1 TX
| 0x0071
|-
|B150 v1 RX
| 0x0072
|-
|WBX-120 v1 TX
| 0x0080
|-
|WBX-120 v1 RX
| 0x0081
|-
|SBX-120 v1 TX
| 0x0082
|-
|SBX-120 v1 RX
| 0x0083
|-
|CBX-120 v1 TX
| 0x0084
|-
|CBX-120 v1 RX
| 0x0085
|-
|TwinRX Rev A TX
| 0x0090
|-
|TwinRX Rev A RX
| 0x0091
|-
|TwinRX Rev B TX
| 0x0092
|-
|TwinRX Rev B RX
| 0x0093
|-
|TwinRX Rev C TX
| 0x0094
|-
|TwinRX Rev C RX
| 0x0095
|-
|E300 AD3964 DB RevB
| 0x0100
|-
|E310 AD9361 DB RevB
| 0x0110
|-
|E300 AD9364 DB RevC
| 0x0101
|-
|E310 AD9361 DB RevC
| 0x0111
|-
|Unknown Tx
| 0xfff0
|-
|Unknown Rx
| 0xfff1
|-
|}

=Motherboard IDs=

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|B200
|0x7737
|-
|B210
|0x7738
|-
|B200mini
|0x7739
|-
|B205mini
|0x773a
|-
|}

[[Category:Application Notes]]

About the Motherboard and Daughtercard EEPROM on USRP Devices

2025-07-11T13:08:17Z

MartinBraun: /* B200/210 and B200mini EEPROM */

==Application Note Number and Authors ==
'''AN-309''' by Trip Humphries and Michael Dickens


=USRP EEPROM Settings & Recovery Guide=

Some USRP products contain an EEPROM on the motherboard which is used to store information about the USRP. Currently, the N200/210, X300/310, B200/210, and E100 contain an on-board EEPROM. The EEPROM contains information about each USRP such as product code, revision number, USRP name, and IP address. The specific information stores on each USRP EEPROM is dependent on the USRP model.

Daughter boards also contain an EEPROM that contains identification information about the daughter board. UHD reads the daughter board ID to determine the model and revision (if applicable) of the daughter board. This information is used to properly configure the USRP and daughter board for proper function.

==EEPROM Burn Utility==

'''Disclaimer: Ettus Research accepts no liability for misuse of this utility. It can very easily cause irreversible damage if used incorrectly! Please contact Ettus support at [mailto:support@ettus.com support@ettus.com] if you are unsure how to proceed.'''

A utility, usrp_burn_mb_eeprom, is included with UHD to read/write values on the various motherboards that contain an EEPROM. The utility is located in the UHD install directory. The default folder is:

/usr/local/lib/uhd/utils/

The utility can be used with the USRP X300/310, N200/210, B200/210, and E100. In some cases, it is necessary to use the utility to write custom user settings to the USRP, such as USRP name or IP address. In other cases, some EEPROM settings set by the factory may become corrupted and need to be restored. This section will cover basic usage of the usrp_burn_mb_eeprom utility, with USRP specific instructions covered in the sections below.

EEPROM settings can be read using the usrp_burn_mb_eeprom utility. All the EEPROM settings can be read at once using the 'read all' option:

./usrp_burn_mb_eeprom --args=<optional device args> --read-all

This will return the current contents in the EEPROM for the specified USRP. For example, if you want to read all the EEPROM contents for a USRP B210, the command would look like:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

The EEPROM settings vary based on the specific USRP in use. The following sections document the EEPROM settings available for each USRP. Examples for each USRP with an EEPROM are also given.

=X300/310 EEPROM=
The EEPROM on the X300/310 stores useful information about the USRP so that UHD can set the proper settings based on model and revision. Some of these settings are user customizable. The table below outlines the values stored in the X300/310 EEPROM. Any entry that is designated "User Customizable?=No" can cause irreversible damage to the USRP and should only be altered by proper guidance from Ettus Support. For example, certain settings in the EEPROM could become corrupted and can be restored with the proper commands.

{| class="wikitable"
|'''X300/310 EEPROM Setting:'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Hardware Number
|-
|revision_compat
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique USRP Serial Number
|-
|mac-addr0
|No
|MAC Address (Port 0)
|-
|mac-addr1
|No
|MAC Address (Port 1)
|-
|gateway
|Yes
|Network Gateway
|-
|subnet0
|Yes
|Subnet Mask
|-
|subnet1
|Yes
|Subnet Mask
|-
|subnet2
|Yes
|Subnet Mask
|-
|subnet3
|Yes
|Subnet Mask
|-
|ip-addr0
|Yes
|IP Address
|-
|ip-addr1
|Yes
|IP Address
|-
|ip-addr2
|Yes
|IP Address
|-
|ip-addr3
|Yes
|IP Address
|-
|name
|Yes
|Custom USRP Name
|}

As an example, the EEPROM settings of an X310 with IP address 192.168.10.2 could be read-back with the following command:

./usrp_burn_mb_eeprom --args="addr=192.168.10.2,type=x300" --read-all

and the output would look like:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["revision_compat"] is "2"
EEPROM ["product"] is "30AD2D4"
EEPROM ["mac-addr0"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["mac-addr1"] is "xx:xx:xx:xx:xx:xx"
EEPROM ["gateway"] is "192.168.10.1"
EEPROM ["ip-addr0"] is "192.168.10.2"
EEPROM ["subnet0"] is "255.255.255.0"
EEPROM ["ip-addr1"] is "192.168.20.2"
EEPROM ["subnet1"] is "255.255.255.0"
EEPROM ["ip-addr2"] is "192.168.10.3"
EEPROM ["subnet2"] is "255.255.255.0"
EEPROM ["ip-addr3"] is "192.168.40.2"
EEPROM ["subnet3"] is "255.255.255.0"
EEPROM ["serial"] is "30AF217"
EEPROM ["name"] is ""
</pre>

==Determining X300/X310 Revision Number==
It is useful in many cases to determine the revision number of your X300/X310. A part number sticker is located on the X300/310 motherboard. This sticker is located near the AUX-I/O connector and has the format 123456\<R>-\<XXX> where \<R> is a letter code that corresponds to the revision number. The photograph below highlights the location of the sticker:

<center>
<div><ul>
<li style="display: inline-block;"> [[File:an-309-x3x0-rev-id.png|thumb|500px|center|The USRP X300/310 motherboard has a sticker that identifies the product and revision. The sticker is outlined in red.]] </li>
</ul></div>
</center>

Once the letter code has been determined use the table below to map the letter code to a revision number:

{| class="wikitable"
|'''Letter'''
|'''Revision #'''
|-
|C
|3
|-
|D
|4
|-
|E
|5
|-
|F
|6
|-
|G
|7
|-
|H
|8
|-
|I
|N/A
|-
|J
|8
|-
|K
|8
|-
|}

==Restore X300/310 EEPROM Revision Code==

A corrupted or missing revision code in the X300/310 EEPROM will be indicated by a UHD runtime error:

Error: RuntimeError: No revision compat detected. MB EEPROM must be reprogrammed!

If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to restore the X300/310 revision code in the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number for your X300/310 is known, the usrp_burn_mb_eeprom utility can be used to restore the revision code to the EEPROM. The syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="revision=<#>"

where <#> is the revision number of your X300/310 to be written to the EEPROM. For example, to restore the revision number in EEPROM for a Rev. 6 X300 with an IP address of 192.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="revision=6"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==Restore X300/310 EEPROM Product Code==

A corrupted product code in the X300/310 EEPROM will be indicated by a UHD warning:

UHD Warning: X300/X310 unknown product code in EEPROM: <###>

where <###> is some numbered code that is unknown by UHD. If this problem is encountered, the usrp_burn_mb_eeprom utility can be used to write a new product code to the EEPROM. First, the X300/X310 revision number must be determined. Once the revision number has been determined, refer to the table below to find the product code for the X300/310:

{| class="wikitable"
|'''USRP'''
|'''Rev. 0-6'''
|'''Rev. 7-8'''
|-
|X300
|30518 (0x7736)
|30817 (0x7861)
|-
|X310
|30410 (0x76CA)
|30818 (0x7862)
|}

Once the correct product code has been determined base on the X3x0 model and revision, the usrp_burn_mb_eeprom utility can be used to write the correct product code to the EEPROM. They syntax is as follows:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom" --values="product=<###>"

where <###> is the product code to be written to the EEPROM. For example, on a Rev. 7 X300 with an IP address of 191.168.10.2, the command would be:

./usrp_burn_mb_eeprom --args="recover_mb_eeprom,addr=192.168.10.2" --values="product=30817"

After the utility has been run, power cycle the USRP and then run uhd_usrp_probe to ensure that the new revision number has been written to the EEPROM correctly. If you are unsure of how to accomplish these steps, please feel free to contact Ettus Support at [mailto:support@ettus.com support@ettus.com].

==National Instruments USRP RIO==

The National Instruments branded X300/310 have unique product codes to identify the motherboard revision as well as the daughter-cards in the USRP. The product codes are listed below:

{| class="wikitable"
|'''Model (DB, BW, Rev.)'''
|'''Hex ID'''
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 0-6)
|0x772B
|-
|USRP-2940R (WBX, 40 MHz BW, Rev. 7+)
|0x7853
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 0-6)
|0x77FB
|-
|USRP-2940R (WBX, 120 MHz BW, Rev. 7+)
|0x785B
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 0-6)
|0x772C
|-
|USRP-2942R (SBX, 40 MHz BW, Rev. 7+)
|0x7854
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 0-6)
|0x77FC
|-
|USRP-2942R (SBX, 120 MHz BW, Rev. 7+)
|0x785C
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 0-6)
|0x772D
|-
|USRP-2943R (CBX, 40 MHz BW, Rev. 7+)
|0x7855
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 0-6)
|0x77FD
|-
|USRP-2943R (CBX, 120 MHz BW, Rev. 7+)
|0x785D
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 0-6)
|0x772E
|-
|USRP-2944R (UBX, 160 MHz BW, Rev. 7+)
|0x7856
|-
|USRP-2945R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78EF
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 0-6)
|0x772F
|-
|USRP-2950R (GPS, WBX, 40 MHz BW, Rev. 7+)
|0x7857
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 0-6)
|0x77FE
|-
|USRP-2950R (GPS, WBX, 120 MHz BW, Rev. 7+
|0x785E
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 0-6)
|0x7730
|-
|USRP-2952R (GPS, SBX, 40 MHz BW, Rev. 7+)
|0x7858
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 0-6)
|0x77FF
|-
|USRP-2952R (GPS, SBX, 120 MHz BW, Rev. 7+
|0x785F
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 0-6)
|0x7731
|-
|USRP-2953R (GPS, CBX, 40 MHz BW, Rev. 7+)
|0x7859
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 0-6)
|0x7800
|-
|USRP-2953R (GPS, CBX, 120 MHz BW, Rev. 7+)
|0x7860
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 0-6)
|0x7732
|-
|USRP-2954R (GPS, UBX, 160 MHz BW, Rev. 7+)
|0x785A
|-
|USRP-2955R (TwinRX, 80 MHz BW, Rev. 7+)
|0x78F0
|-
|}

=N200/210 EEPROM=

{| class="wikitable"
|'''N200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|hardware
|No
|Hardware Number
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|mac-addr
|No
|MAC Address
|-
|ip-addr
|Yes
|IP Address
|-
|subnet
|Yes
|Subnetwork
|-
|gateway
|Yes
|Network Gateway
|-
|}

The N200/210 do not store the product codes in the motherboard EEPROM. The "hardware" field is programmed at the factory but is not referenced by UHD. Instead, the revision field is used to determine the N200/210 hardware in use.

{| class="wikitable"
|'''USRP'''
|'''Motherboard Product ID'''
|-
|N200
|0x0A00
|-
|N210
|0x0A01
|-
|N200 - R4
|0x0A10
|-
|N210 - R4
|0x0A11
|-
|}

=B200/210 and B200mini EEPROM=

The USRP B200 and B210 EEPROM is used to store certain information about each board. The USB PID (Product ID) and VID (Vendor ID) are stored in the EEPROM as well as serial number, product code, hardware revision, and USRP name for each B200/210. A table of these settings and whether or not the setting is user customizable is given below:

{| class="wikitable"
|'''B200/210 EEPROM Setting'''
|'''User Customizable?'''
|'''Description'''
|-
|revision
|No
|Revision Number
|-
|product
|No
|Product Code
|-
|serial
|No
|Unique Serial Number
|-
|name
|Yes
|Custom USRP Name
|-
|}

To read the current EEPROM values from the USRP, use the usrp_burn_mb_eeprom utility:

./usrp_burn_mb_eeprom --args="type=b200" --read-all

This will read the settings and print them to the terminal. A sample output is shown below for a USRP B210:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "MyB210"
</pre>

If desired, a B200/210 could be given a custom name with the following command:

./usrp_burn_mb_eeprom --args="type=b200" --values="name=Lab_B210"

After the command has been run, the device must be power-cycled for the new EEPROM setting to take effect. Reading the updated EEPROM values yields:

<pre>
Fetching current settings from EEPROM...
EEPROM ["revision"] is "4"
EEPROM ["product"] is "2"
EEPROM ["serial"] is "30AD2D4"
EEPROM ["name"] is "Lab_B210"
</pre>

==EEPROM Product ID==

The product code and the product revision stored in the EEPROM of the USRP
B200/B210 devices are used to identify the specific model and revision of the
device. The product code is a unique identifier that corresponds to the
specific hardware design, while the product revision indicates the version of
that design.

In case of EEPROM corruption, the following table can help identify the correct
revision and product code that is written into the EEPROM during the manufacturing
process, by comparing to the USRP Type and NI Part Number, which can be found
on the blue sticker on the PCB. The "Letter Revision" is the last letter of
the NI Part Number.

{| class="wikitable"
|'''USRP Type'''
|'''NI PN'''
|'''Letter Revision'''
|'''EEPROM Product Code (Ettus Branding)'''
|'''EEPROM Product Code (NI Branding)'''
|'''EEPROM Revision No'''
|'''Comments'''
|-
|B210
|156229A-01L, 156229B-01L
|A, B
|2
|0x7738, 0x7814
|4
|
|-
|B200
|156229A-02L, 156229B-02L
|A, B
|1
|0x7737, 0x7813
|4
|
|-
|B200
|156229C-02L, 156229D-02L
|C, D
|1
|0x7737, 0x7813
|5
|This revision switched from AD9361 to AD9634, and thus had to switch the RF side.
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034A-01L, 159034A-02L, 159034A-03L
|A
|0x0003, 0x0004
|0x7739, 0x773a
|1
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034B-01L, 159034B-02L, 159034B-03L
|B
|0x0003, 0x0004
|0x7739, 0x773a
|2
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034C-01L, 159034C-02L, 159034C-03L
|C
|0x0003, 0x0004
|0x7739, 0x773a
|3
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034D-01L, 159034D-02L, 159034D-03L
|D
|0x0003, 0x0004
|0x7739, 0x773a
|4
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034E-01L, 159034E-02L, 159034E-03L
|E
|0x0003, 0x0004
|0x7739, 0x773a
|5
|
|-
|B200mini (I-grade) & B205mini (I-grade)
|159034{F,G}-01L, 159034{F,G}-02L, 159034{F,G}-03L
|{F,G}
|0x0003, 0x0004
|0x7739, 0x773a
|6
|
|-
|B206mini
|117434A-01L, 117434B-01L
|A, B
|0x0005
|0x773b
|1
|
|-
|}

==USB VID/PID==

The USB vendor identification (VID) and product identification (PID) numbers can be written to the USRP B200/210 using the "b2xx_fx3_utils" utility that is included with UHD. To reset the VID and PID, the command would be:

./b2xx_fx3_utils --init-device --write-vid 0x2500 --write-pid -0x0020

{| class="wikitable"
|'''USRP'''
|'''USB PID'''
|-
|B200
|0x0020
|-
|B210
|0x0020
|-
|B200 (NI)
|0x7813
|-
|B210 (NI)
|0x7814
|-
|B200mini
|0x0021
|-
|B205mini
|0x0022
|-
|}

The VID is the same for all B2x0 variants, 0x2500.

=Daughtercard IDs=

Below is a comprehensive list of the daughtercard hex ID's.

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|Basic Tx
| 0x0000
|-
|Basic Rx
| 0x0001
|-
|DBS Rx
| 0x0002
|-
|TV Rx
| 0x0003
|-
|Flex 400 Rx
| 0x0004
|-
|Flex 900 Rx
| 0x0005
|-
|Flex 1200 Rx
| 0x0006
|-
|Flex 2400 Rx
| 0x0007
|-
|Flex 400 Tx
| 0x0008
|-
|Flex 900 Tx
| 0x0009
|-
|Flex 1200 Tx
| 0x000a
|-
|Flex 2400 Tx
| 0x000b
|-
|TV Rx Rev 2
| 0x000c
|-
|DBS Rx ClkMod
| 0x000d
|-
|LF Tx
| 0x000e
|-
|LF Rx
| 0x000f
|-
|DBSRX2
| 0x012
|-
|Flex 400 Rx MIMO A
| 0x0014
|-
|Flex 900 Rx MIMO A
| 0x0015
|-
|Flex 1200 Rx MIMO A
| 0x0016
|-
|Flex 2400 Rx MIMO A
| 0x0017
|-
|Flex 400 Tx MIMO A
| 0x0018
|-
|Flex 900 Tx MIMO A
| 0x0019
|-
|Flex 1200 Tx MIMO A
| 0x001a
|-
|Flex 2400 Tx MIMO A
| 0x001b
|-
|Flex 400 Rx MIMO B
| 0x0024
|-
|Flex 900 Rx MIMO B
| 0x0025
|-
|Flex 1200 Rx MIMO B
| 0x0026
|-
|Flex 2400 Rx MIMO B
| 0x0027
|-
|Flex 400 Tx MIMO B
| 0x0028
|-
|Flex 900 Tx MIMO B
| 0x0029
|-
|Flex 1200 Tx MIMO B
| 0x002a
|-
|Flex 2400 Tx MIMO B
| 0x002b
|-
|Flex 2200 Rx MIMO B
| 0x002c
|-
|Flex 2200 Tx MIMO B
| 0x002d
|-
|Flex 1800 Rx
| 0x0030
|-
|Flex 1800 Tx
| 0x0031
|-
|Flex 1800 Rx MIMO A
| 0x0032
|-
|Flex 1800 Tx MIMO A
| 0x0033
|-
|Flex 1800 Rx MIMO B
| 0x0034
|-
|Flex 1800 Tx MIMO B
| 0x0035
|-
|TV Rx Rev 3
| 0x0040
|-
|DTT754
| 0x0041
|-
|DTT768
| 0x0042
|-
|TV Rx MIMO
| 0x0043
|-
|TV Rx Rev 2 MIMO
| 0x0044
|-
|TV Rx Rev 3 MIMO
| 0x0045
|-
|TVRX2
| 0x0046
|-
|WCDMA US
| 0x004d
|-
|WCDMA EU
| 0x004e
|-
|SIMPLE GDB
| 0x004f
|-
|WBX LO TX
| 0x0050
|-
|WBX LO RX
| 0x0051
|-
|WBX NG TX
| 0x0052
|-
|WBX NG RX
| 0x0053
|-
|SBX v3 RX
| 0x0054
|-
|SBX v3 TX
| 0x0055
|-
|WBX v3 TX
| 0x0056
|-
|WBX v3 RX
| 0x0057
|-
|XCVR2450 - No Div
| 0x0059
|-
|XCVR2450 TX
| 0x0060
|-
|XCVR2450 RX
| 0x0061
|-
|WBX v4 TX
| 0x0062
|-
|WBX v4 RX
| 0x0063
|-
|SBX v4 TX
| 0x0064
|-
|SBX v4 RX
| 0x0065
|-
|CBX v1 TX
| 0x0066
|-
|CBX v1 RX
| 0x0067
|-
|SBX v5 TX
| 0x0068
|-
|SBX v5 RX
| 0x0069
|-
|UBX-Prototype v3 TX
| 0x0073
|-
|UBX-Prototype v3 RX
| 0x0074
|-
|UBX-Prototype v4 TX
| 0x0075
|-
|UBX-Prototype v4 RX
| 0x0076
|-
|UBX v1 TX
| 0x0077
|-
|UBX v1 RX
| 0x0078
|-
|UBX-160 v1 TX
| 0x0079
|-
|UBX-160 v1 RX
| 0x007a
|-

|UBX-40 v2 TX
| 0x007b
|-
|UBX-40 v2 RX
| 0x007c
|-

|UBX-160 v2 TX
| 0x007d
|-
|UBX-160 v2 RX
| 0x007e
|-

|Bitshark RX
| 0x0070
|-
|B150 v1 TX
| 0x0071
|-
|B150 v1 RX
| 0x0072
|-
|WBX-120 v1 TX
| 0x0080
|-
|WBX-120 v1 RX
| 0x0081
|-
|SBX-120 v1 TX
| 0x0082
|-
|SBX-120 v1 RX
| 0x0083
|-
|CBX-120 v1 TX
| 0x0084
|-
|CBX-120 v1 RX
| 0x0085
|-
|TwinRX Rev A TX
| 0x0090
|-
|TwinRX Rev A RX
| 0x0091
|-
|TwinRX Rev B TX
| 0x0092
|-
|TwinRX Rev B RX
| 0x0093
|-
|TwinRX Rev C TX
| 0x0094
|-
|TwinRX Rev C RX
| 0x0095
|-
|E300 AD3964 DB RevB
| 0x0100
|-
|E310 AD9361 DB RevB
| 0x0110
|-
|E300 AD9364 DB RevC
| 0x0101
|-
|E310 AD9361 DB RevC
| 0x0111
|-
|Unknown Tx
| 0xfff0
|-
|Unknown Rx
| 0xfff1
|-
|}

=Motherboard IDs=

{| class="wikitable"
|'''Name'''
|'''Hex ID'''
|-
|B200
|0x7737
|-
|B210
|0x7738
|-
|B200mini
|0x7739
|-
|B205mini
|0x773a
|-
|}

[[Category:Application Notes]]

Getting Started with RFNoC in UHD 4.0

2025-06-23T08:00:09Z

MartinBraun:

==Application Note Number and Authors==
'''AN-400''' by Sugandha Gupta, Brent Stapleton, Wade Fife, and Michael Dickens


==WARNING==

'''Parts of this AN are outdated! We are currently working on updating this article.'''

==Abstract==
This guide describes how to get started with FPGA and Software development for RF Network-on-Chip (RFNoC™). It gives a brief introduction to RFNoC and explains the steps needed to generate, build, and use custom RFNoC images and introduces the process for creating and integrating new RFNoC IP blocks.


==Intended Audience==
This guide is written for hardware and software engineers who want to use the RF Network-on-Chip (RFNoC™) architecture or want to develop intellectual property (IP) using the RFNoC architecture. For more details on the architecture please refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

This guide assumes that you have some basic familiarity with USRPs, such as connecting them, configuring your network interfaces, etc., so that your USRP is ready for use. See the [https://kb.ettus.com/Getting_Started_Guides Getting Started Guide] for your USRP if you are just getting started with USRPs.

==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). RFNoC is available under the open-source GNU Lesser General Public License (LGPL). For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Prerequisites==
RFNoC is currently supported on the USRP X410 series, and all the Generation-3 USRPs in the X series (X3xx), E series (E3xx) and N series (N3xx). For details on the hardware, software, and process required to build custom USRP FPGA images that include RFNoC blocks, see the [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP Build Documentation] in the UHD and USRP Manual.

It is recommended that you learn how to build an FPGA image for your USRP and download it to the device before starting this guide if you have never done so before. This will ensure you have all the necessary software installed.

==Introduction to RFNoC==

===What is RFNoC?===

RFNoC™ is a heterogeneous processing framework used to implement high-throughput DSP in the FPGA for Software Defined Radio (SDR) systems in an easy-to-use and flexible way. It provides all the infrastructure required to insert signal-processing IP into the FPGA logic and communicate with it through software. It also provides highly-optimized software and FPGA code to enable high-performance streaming to and from IP blocks on the USRP device.

The IP blocks in RFNoC are called ''RFNoC blocks''. The RFNoC blocks wrap the IP and provide a custom interface to the RFNoC infrastructure through a tool-generated interface called the ''NoC Shell''. Many standard blocks are included in UHD 4.0. These blocks enable typical operation of the USRP and allow RFNoC to connect to the different hardware components of the USRP. Several of the included blocks are described in the section [[#Available RFNoC Blocks|Available RFNoC Blocks]]. You can mix the available blocks for your application, or develop your own custom RFNoC blocks with your own IP to open up new applications. The NoC Shell hides the complexity of RFNoC from your block, making it easy to plug your IP into the USRP.

RFNoC is used on all Generation-3 USRPs and is installed with UHD 4.0. USRPs ship with a default RFNoC image that can be used as is, or can be modified and/or customized to suite your application. So if you're using a modern USRP, it's running RFNoC under the hood even if you haven't customized anything.

===Example RFNoC Image===

The diagram below shows a simplified view of an RFNoC FPGA image that is similar to the default images available on USRPs.

<br>
[[File:simplified_rfnoc_image_uhd_4.png|center]]
<br>

Notice that an RFNoC FPGA is made up of several components. A description of each one is provided below.

* '''RFNoC Image Core'''<br>This is the main block of the RFNoC framework and instantiates the components that make up RFNoC. The contents of the image core are described by an RFNoC image core YAML file, and the Verilog code that represents this block is automatically generated by the RFNoC Image Builder tool based on the YAML description. In other words, you provide a description of what you want to be included in RFNoC and the tools generate the code to implement that description.
* '''Transport Adapter'''<br>The transport adapter is a component of the USRP that allows communication with an outside interface. These vary depending on the USRP model in use. For example, this could be a 10 Gbps Ethernet link for SFP+ port of the USRP, or a cabled PCIe interface. As of UHD 4.7, the USRP X4xx series puts the transport adapters inside the image core for higher flexibility.
* '''CHDR Crossbar'''<br>The CHDR crossbar is a dynamic router for RFNoC traffic. This is a high-throughput crossbar designed for RF streaming applications. It is reconfigurable at run time via software and can be used to configure routes between stream endpoints and transport adapters. The number of ports available is configurable by changing the RFNoC image core YAML file. CHDR (Condensed Hierarchical Datagram for RFNoC) refers to the network protocol that is used for RFNoC.
* '''Stream Endpoint (SEP)'''<br>The stream endpoint (SEP) provides the high-level flow control for traffic over the network. It also separates control traffic from data traffic to create a separate AXIS-Ctrl network for control traffic. Control traffic refers to things like register reads and writes for configuring and monitoring RFNoC blocks.
* '''Control Crossbar'''<br>The control crossbar is similar to the CHDR Crossbar, but is only for control traffic. It has a much lower throughput and has been optimized for control-traffic, making it much less resource intensive than the CHDR crossbar.
* '''Other Blocks'''<br>The DDC (digital down converter), DUC (digital up converter), and Radio in this example are RFNoC blocks that are included with UHD. These are standard components included the default USRP images and enable typical RF applications. Most blocks only communicate with the RFNoC network, but some blocks require access to external hardware interfaces, such as the radio or DRAM. In this example, the radio blocks connect to the radio hardware on the USRP.

===Static vs. Dynamic Routing===

The routes between blocks that go through the crossbar are ''dynamic''. That is, the routes can be changed at run time and are controlled by software. The CHDR crossbar is very powerful in that it allows any of its ports to communicate with each other. It allows for streaming between blocks on the same FPGA, between RFNoC blocks and a host computer, or between blocks on different USRPs. New signal processing chains can be added to this crossbar, as needed, for the application.

Similarly, the control crossbar supports dynamic routing, allowing any RFNoC block to send control traffic to any other RFNoC block, even to blocks on a different USRP. Control traffic can also be sent from the host computer to the RFNoC blocks, for example to read/write registers. Additionally, RFNoC blocks can send control to the host computer. In this example, the Radio block sends control traffic to the computer to report specific events, such as overflow or underflow in the radio.

The block connections that don't go through a crossbar (e.g., the connection from the radio to the DDC, and the DDC to the stream endpoint, etc.) are ''static'' connections. That is, they cannot be changed at run time. Making a connection static has the advantage that it does not require additional ports on the crossbar and that the connection can be made much simpler because the high-level network flow-control protocol used by CHDR is not required. This reduces latency between blocks and leads to FPGA resource savings, allowing more logic be included in a single FPGA image. The static connections are described by the RFNoC image core YAML file. In order to change the static connections, the YAML description needs to be updated and the FPGA image needs to be rebuilt.

===RFNoC Customization===

The RFNoC framework makes it easy to customize the RFNoC image and add your own IP blocks. Later on in this guide, we'll explore how you can customize the RFNoC image to add or remove blocks, as well as create your own RFNoC blocks and include them in your FPGA builds. This allows you to create highly-customized and high-performance FPGA images for your USRP.

==Setting Up==
To use RFNoC in UHD 4.0 you need to perform the following:

* Clone the UHD repository
* Install UHD
* Update your device's filesystem and FPGA image

Building custom RFNoC images requires the FPGA source code and build system. These are included in the UHD repository, located in <code><repo>/fpga/usrp3/</code>, where <code><repo></code> refers to the location where you cloned the UHD repository.

Please see the [http://files.ettus.com/manual/page_install.html Binary Installation] for UHD installation documentation or [https://files.ettus.com/manual/page_build_guide.html Building and Installing] instructions to build and install UHD from source. Additionally, [[Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux|AN-445]] provides step-by step instructions for cloning the repository and installing UHD from source.

Starting with UHD 3.15, RFNoC is enabled by default, and starting with UHD 4.0, it can no longer be disabled, so no additional instructions are necessary to install support for RFNoC in UHD.

Many of the UHD utilities we will use in this guide are based on Python. Please ensure that your <code>PYTHONPATH</code> is set correctly. If not set correctly, you will see errors indicating that Python could not find the <code>uhd</code> or <code>image_builder</code> libraries. The correct setting may depend on where you installed UHD and which Linux distribution you are using. If you installed UHD from source to the default location on Ubuntu, you may need to add <code>/usr/local/lib/python3/dist-packages</code> to your <code>PYTHONPATH</code> variable. For example:

$ export PYTHONPATH=/usr/local/lib/python3/dist-packages

Instructions for updating your device's filesystem (applicable to E3xx and N3xx) and FPGA image can be found in that device's [https://kb.ettus.com/Getting_Started_Guides Getting Started Guide]. If your filesystem is already up to date, or your device does not use a filesystem (e.g., X3xx), then instructions on flashing an FPGA image to a device can be found in the following locations:

* [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs X3xx series]
* [http://files.ettus.com/manual/page_usrp_e3xx.html#e3xx_getting_started_fpga_update E3xx series]
* [http://files.ettus.com/manual/page_usrp_n3xx.html#n3xx_getting_started_fpga_update N3xx 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 your USRP device will likely lead to an error message but can brick the device under some circumstances.

===Configure the Default Shell===

Make sure you are using the <code>Bash</code> shell. Many of the build scripts used by RFNoC are written for <code>Bash</code>. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

==Testing the Default FPGA Image==

Before continuing, please verify that you have downloaded and flashed the latest FPGA image for your version of UHD. All FPGA images for Generation-3 and above devices are RFNoC images, so there is no requirement to download a special image for RFNoC.

===Inspect the Default Image===

Before we start customizing our FPGA, let's get familiar with the default FPGA image, which is pre-built with a set of RFNoC blocks.

Run the following command, with your USRP connected to your PC, to see what is available on the device.

$ uhd_usrp_probe --args type=x300

Note that your <code>args</code> may be different, depending on the USRP device you're using. The example here works for X300/X310. Refer to the manual page on [https://files.ettus.com/manual/page_identification.html Identifying USRP Devices] for more details. If an RFNoC image was successfully loaded onto the USRP, the output will show something like the following:

<nowiki> _____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X310
| | revision: 11
| | revision_compat: 7
| | product: 30818
| | mac-addr0: 00:80:2f:17:40:6d
| | mac-addr1: 00:80:2f:17:40:6e
| | 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: 311EF81
| | FW Version: 6.0
| | FPGA Version: 38.0
| | FPGA git hash: be53058
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
...</nowiki>

More than this will likely be shown. The specifics of the output depend on the UHD version and which device you're running on. However, we're interested in the following sections:

* '''Device description'''. At the top, there is a section with basic information about your device, such as serial number, revision, etc. You can use this information to verify that you are indeed communicating with the correct device, and that the device has been updated. The FPGA git hash identifies the commit from which the FPGA image was built.
* '''RFNoC blocks on this device'''. This section lists all the RFNoC blocks in the loaded FPGA image. The blocks are listed by their block IDs. For example, <code>0/Radio#0</code> means that we're on device zero (<code>0/</code>), and we're talking about the first radio (with index <code>#0</code>). Unless you probe multiple devices at once by specifying multiple addresses in the <code>--args</code> argument, the device number will always be zero, but the block index will change depending on the number of blocks of that type. For example, on X310, <code>Radio#0</code> corresponds to RF A and <code>Radio#1</code> corresponds to RF B.
* '''Static connections on this device'''. This section lists how the blocks are pre-connected in the FPGA image. For example, the line <code>0/Radio#0:0==>0/DDC#0:0</code> means that radio zero, port zero (<code>:0</code>), is connected statically to DDC zero, port zero. Static connections can only be changed at compile time when building the FPGA image.

The connection endpoints labeled <code>SEP</code> are not RFNoC blocks. They are Stream Endpoints (SEPs). SEPs can send data packets to one another, or to streamers in software, using the CHDR crossbar, which is a dynamic router on the FPGA.

===Available RFNoC Blocks===

Many RFNoC blocks come with UHD. The HDL source code for these blocks resides in <code><repo>/fpga/usrp3/lib/rfnoc/blocks/</code>. Several of the blocks are described below.

{| class="wikitable"
!Block Name
!HDL Name
!Description
|-
|AddSub
|<code>rfnoc_block_addsub</code>
|Add/Subtract Verilog/VHDL/HLS Example
|-
|DmaFIFO
|<code>rfnoc_block_axi_ram_fifo</code>
|FIFO that uses an AXI4 memory-mapped interface for storage. For use with external DRAM or on-chip SRAM.
|-
|DDC
|<code>rfnoc_block_ddc</code>
|Digital Down Converter
|-
|DUC
|<code>rfnoc_block_duc</code>
|Digital Up Converter
|-
|FFT
|<code>rfnoc_block_fft</code>
|Fast Fourier Transform
|-
|FIR
|<code>rfnoc_block_fir_filter</code>
|Finite Impulse Response Filter
|-
|Fosphor
|<code>rfnoc_block_fosphor</code>
|FFT and waterfall display tool
|-
|KeepOneInN
|<code>rfnoc_block_keep_one_in_n</code>
|Keep one sample/packet in N
|-
|LogPwr
|<code>rfnoc_block_logpwr</code>
|Computes an estimate of log2(i^2+q^2)
|-
|MovingAverage
|<code>rfnoc_block_moving_avg</code>
|Outputs the running average of the N most recent inputs of data stream
|-
|NullSrcSink
|<code>rfnoc_block_null_src_sink</code>
|Data source generator, sink, and loopback for testing
|-
|Radio
|<code>rfnoc_block_radio</code>
|Radio Interface
|-
|Replay
|<code>rfnoc_block_replay</code>
|Record/Playblack using AXI4 memory-mapped interface. For use with external DRAM or on-chip SRAM.
|-
|SigGen
|<code>rfnoc_block_siggen</code>
|Signal Generator. Supports sinusoidal, constant, and random outputs, with configurable gain.
|-
|SplitStream
|<code>rfnoc_block_split_stream</code>
|Splits a single data stream into two
|-
|Switchboard
|<code>rfnoc_block_switchboard</code>
|A configurable RFNoC datapath switch for testing
|-
|VectorIIR
|<code>rfnoc_block_vector_iir</code>
|Implements an IIR filter with variable length delay line
|-
|Window
|<code>rfnoc_block_window</code>
|Windowing module for use with FFT block
|}

===Streaming Example===

In the UHD installation directory, you'll find example applications (e.g., in <code>/usr/lib/uhd/examples/</code> or <code>/usr/local/lib/uhd/examples/</code>). We'll look at <code>rfnoc_rx_to_file</code> to familiarize ourselves with the RFNoC API.

If we look at the source code for this example (located at <code><repo>/host/examples/rfnoc_rx_to_file.cpp</code>), we can see the components necessary in an RFNoC application. In the <code>UHD_SAFE_MAIN</code> function, we create a few crucial objects, such as an RFNoC graph, a radio block controller, a DDC block controller, and an RX streamer.

auto graph = uhd::rfnoc::rfnoc_graph::make(args);
// ...
auto radio_ctrl = graph->get_block<uhd::rfnoc::radio_control>(radio_ctrl_id);
// ...
uhd::rfnoc::ddc_block_control::sptr ddc_ctrl;
// ...
auto rx_stream = graph->create_rx_streamer(1, stream_args);

We also make connections in our graph and configure our blocks.

// Connect blocks and commit the graph
for (auto& edge : chain) {
if (uhd::rfnoc::block_id_t(edge.dst_blockid).match(uhd::rfnoc::NODE_ID_SEP)) {
graph->connect(edge.src_blockid, edge.src_port, rx_stream, 0);
} else {
graph->connect(
edge.src_blockid, edge.src_port, edge.dst_blockid, edge.dst_port);
}
}
...
rate = radio_ctrl->set_rate(rate);
...
radio_ctrl->set_rx_frequency(freq, radio_chan);

Once our graph and blocks are configured, we use the <code>recv_to_file</code> function to receive data from our device and write it to a file on our host computer. Running this example with the <code>--help</code> argument shows the available options. For example, to receive 3 seconds of data at a specific frequency and sample rate, we can run:

rfnoc_rx_to_file --args type=x300 --freq 2.4e9 --rate 10e6 --duration 3

Now you are ready to move to the next step and build your own blocks and FPGA images.

==RFNoC Image Builder==

UHD provides tooling to help develop custom RFNoC images. In this guide we will demonstrate how to use the RFNoC Image Builder, which will allow you to change which blocks are included and the connections between blocks. Let's go over common decisions you'll have to make with this tool.

* '''Blocks Included'''<br>The particular blocks to be included in the image is the most impactful decision you'll make in the image building process, both in terms of image functionality and FPGA resource utilization. Adding more blocks means more processing in the image, but it also means longer FPGA build times and less space in the FPGA.
* '''Static Connections'''<br>Recall that blocks can be statically connected, as opposed to connecting every block to the CHDR crossbar (dynamically connected). The number of dynamic connections has a large impact on the size of the CHDR crossbar, so static connections are used to lower resource utilization. However, once a block is statically connected in a chain of blocks, data cannot be sent between arbitrary blocks; it must traverse and be processed by each block in the order defined by the static connections.
* '''Hardware Connections'''<br>All blocks share some connections defined by the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification]. These connections are made automatically and cannot be changed. Many blocks require additional connections, such as clocks for the internal DSP or external DRAM interfaces. These connections must also be specified.

Now that we've gone over some of the considerations, let's look at how to actually build a custom RFNoC image. This begins with the RFNoC image core YAML description.

===Understanding the RFNoC Image YAML File===

The image YAML file defines RFNoC blocks in the FPGA image. It is designed to be both human-readable and machine-parseable, which allows us to make edits quickly and easily. Each device type has a default YAML image file, which is named <code><DEVICE>_rfnoc_image_core.yml</code> (e.g., <code>x310_rfnoc_image_core.yml</code>). Take a look at the RFNoC image core YAML file for the X310 by opening <code><repo>/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml</code>. Notice that it has the following sections.

* '''General Parameters'''<br>Here we define the device, the bit width of our CHDR connections, as well as some versioning and licensing.
* '''Stream Endpoints'''<br>In the <code>stream_endpoints</code> section we list each stream endpoint (SEP) that we wish to instantiate. These will be directly connected to the CHDR crossbar and will allow us to make dynamic connections within the CHDR crossbar. Typically you will have one SEP that forms the start and end of a single DSP chain of RFNoC blocks.<br>You can also add some per-stream-endpoint configuration here, such as the ingress buffer size, which affects streaming performance from your computer to that SEP. For example, if we know that one SEP will be receiving data transferred from your computer to the USRP then a data buffer is needed to accept those incoming packets, in which case we specify the buffer size by setting the <code>buff_size</code> option on that SEP. Alternatively, if we know that a particular SEP only sends data from the USRP to the computer, then we won't need the ingress data buffer and we can set <code>buff-size</code> to 0, thus saving FPGA resources.<br>Each SEP can have an AXIS-Ctrl and an AXIS-CHDR port, as indicated by the <code>ctrl</code> and <code>data</code> options. At least one AXIS-Ctrl port is required to communicate with the RFNoC blocks, so <code>ctrl</code> typically enabled on just the first SEP. Every SEP will usually have AXIS-CHDR connections to one or more RFNoC blocks, so <code>data</code> is usually enabled on all SEPs.
* '''NoC Blocks'''<br>In the <code>noc_blocks</code> section we specify all the RFNoC blocks to include in the FPGA image. We'll need to give each block a unique name and reference a block definition YAML file (which we'll discuss in a later section). The blocks chosen have the greatest impact on the functionality of the image, as well as providing very coarse control over the FPGA resource utilization. We'll look at how to change the blocks included in the image as part of our example below.
*'''Static Connections'''<br>The <code>connections</code> section defines static connections between blocks, stream endpoints, and various hardware interfaces on the USRP. Statically connected chains of blocks will usually start and end at a stream endpoint (SEP). SEPs are automatically connected to the CHDR crossbar by the RFNoC infrastructure. Remember that data must be passed through the entire statically connected chain; dynamic connections cannot be made to the statically connected blocks in the middle of the chain. Other hardware connections, such as to the external DRAM, would also be specified here. We'll take a closer look at making connections as part of our example below.
* '''Clock Domains'''<br>The <code>clk_domains</code> section defines which clocks to connect to each block's clock inputs. Some blocks do not need any clock connections beyond the base clocks required by RFNoC. These required connections are not listed here, since they are always the same for each block. Other blocks may require additional clocks. For example, the radio blocks should be connected to the <code>radio</code> clock. Many other blocks require a <code>ce</code> (Compute Engine) clock, which is used for the block's internal DSP.

===Running the Image Builder===

Before we look at editing the image core YAML file, let's go over how to use the RFNoC image builder to generate a bitstream from that YAML file. Additional details on how to run the image builder can be found with the <code>--help</code> option:

$ rfnoc_image_builder --help

Here are some of the options provided:
* '''<code>-y</code>''': Path to the RFNoC image core YAML file
* '''<code>-t</code>''': The image target you would like to build. These are the same targets that are used in the FPGA <code>make</code> process. More details on these can be found in the [https://files.ettus.com/manual/md_usrp3_build_instructions.html Generation 3 USRP Build Documentation] of the UHD and USRP Manual. If not specified, the default specified in the image core YAML file will be used.
* '''<code>-l debug</code>''': Use the <code>debug</code> log level. This prints more information about the FPGA connections and available port names, which can be useful for debugging connection errors in the YAML file.
* '''<code>--generate-only</code>''': Generate the HDL files required, but do not build the FPGA. Users can then build the FPGA later using <code>make <target></code>.
* '''<code>-I</code>''': Path to the directory containing out-of-tree block YAML descriptions (the YAML files installed with UHD are included by default). This option is only needed if using an out-of-tree RFNoC block.
* '''<code>-F</code>''': Path to the FPGA source code (e.g., <code><repo>/fpga</code>). This path is only required if the current working directory is not within the UHD repository.

For example, to build the default RFNoC image for X310, you might use the following command:

$ cd <repo>/fpga/usrp3/top/x300/
$ rfnoc_image_builder -y ./x310_rfnoc_image_core.yml -t X310_XG

In this example <code><repo></code> refers to the location where you cloned the UHD repository and should be replaced by the location you used. <code>x310_rfnoc_image_core.yml</code> is the default RFNoC image core YAML file for the X310, which is in the x300 project directory. <code>X310_XG</code> is the make target to use for the build. <code>XG</code> in this case refers to dual 10 Gbps Ethernet. As of UHD 4.9, <code>rfnoc_image_builder -h</code> will list valid targets.

For an out-of-tree RFNoC block, you will also need to specify the location of the block information. For example:

$ rfnoc_image_builder -F <repo>/fpga -I <repo>/host/examples/rfnoc-example -y <repo>/host/examples/rfnoc-example/icores/x310_rfnoc_image_core.yml -t X310_XG

This example shows how to build an FPGA with the Gain example out-of-tree RFNoC block, which is located in <code><repo>/host/examples/rfnoc-example/</code>. The <code>-F</code> option is added to specify the location of the FPGA source, and <code>-I</code> specifies the location of the out-of-tree block YAML.

The image builder performs several steps in order to build the FPGA image from the image coure YAML:

# It generates the <code><device>_rfnoc_image_core.v</code> file. This file includes the Verilog code described by the YAML image core file. A <code><device>_static_router.hex</code> file is also generated. This file describes the static connections that should be made by the Verilog code. In the case of the X310 examples above, the output files would be named <code>x310_rfnoc_image_core.v</code> and <code>x310_static_router.hex</code>, and would be placed in the project directory for the X310 (<code><repo>/fpga/usrp3/top/x300/</code>).
# The image builder will configure the environment for building the FPGA. This is equivalent to sourcing the <code>setupenv.sh</code> script for the device type being built. For example, in our example above, it would run <code>source <repo>/fpga/usrp3/top/x300/setupenv.sh</code>.
# The image builder runs <code>make <target></code> to build the IP and the FPGA bitstream for the indicated target. The generated Verilog files are automatically pulled into this build.

===Example: Adding an FFT Block===

As an example, let's run through how to modify the YAML file to modify the RFNoC image. Suppose we have an application that we'd like to run on a USRP X310 and we would like to offload the FFT processing to the FPGA. UHD provides an FFT RFNoC block, and the default X310 image has some extra space in it, so we should be able to add this block. First, we copy the default X310 image core file, named <code>x310_rfnoc_image_core.yml</code>.

$ cd <repo>/fpga/usrp3/top/x300/
$ cp x310_rfnoc_image_core.yml x310_with_fft.yml

Now open <code>x310_with_fft.yml</code> in your favorite text editor. We'll start by making some room for our new block. The default images use very large ingress FIFO buffers for the main SEPs to maximize streaming performance. But we want to make sure we have enough memory buffer space for our new blocks. So Start by reducing the <code>buf_size</code> parameters for <code>ep0</code> and <code>ep2</code> from 65536 to 32768. If using a device other than X310, the numbers may be different, but you can similarly reduce the <code>buff_size</code> parameter by half. On smaller devices, it may be necessary to remove the Replay block to make room for the FFT blocks. After making the changes on X310, the result should look like the following:

stream_endpoints:
ep0: # Stream endpoint name
ctrl: True # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 32768 # Ingress buffer size for data
...
ep2: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 32768 # Ingress buffer size for data

Now we can add our FFT block. We'll put it on its own stream endpoint, so we first need to add a new stream endpoint. Add the following to the <code>stream_endpoints</code> section:

stream_endpoints:
...
ep_fft: # The name can be incremented from previous SEP
ctrl: False # Only the first SEP needs control traffic
data: True # We do want to pass data through this SEP
buff_size: 32768 # Ingress buffer size for data

In this example, we've named the SEP <code>ep_fft</code>. Other names could be given, as long as the name is unique (it does not have to be numbered). Now that we've allocated an SEP for our block, we need to instantiate the actual block. In the next section, add the following:

Now let's add the FFT block. Note that the .yml file name and the parameters differ depending on the UHD version.

Starting from UHD 4.8:

* In this example, we're setting <code>MAX_FFT_SIZE_LOG2</code> parameter to 10, which sets the max FFT-size to 1024.

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
MAX_FFT_SIZE_LOG2: 10

From UHD 4.0 until UHD 4.7:

* In this example, we're setting <code>EN_FFT_SHIFT</code> parameter to 1, which causes the FFT block to center the zero frequency bin.

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft_1x64.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
EN_FFT_SHIFT: 1

Again, the name <code>fft0</code> is arbitrary, but the name must be unique. In some cases, there will also be block parameters you'll want to pass, such as the data format of the FFT output data.

Now that we've added our FFT block, we need to connect it to the stream endpoint. In the next section of the YAML file, we add the static connections:

connections:
...
- { srcblk: ep_fft, srcport: out0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep_fft, dstport: in0 }

This connects the output of SEP <code>ep_fft</code> to the input of block <code>fft0</code>, and the output of <code>fft0</code> to the input of <code>ep_fft</code>. Since we're placing the FFT block on its own SEP, the only connections we need to make are between the SEP and the FFT. All SEPs are automatically connected to the CHDR crossbar, so this effectively connects the FFT block to the crossbar, allowing it to communicate with anything on the RFNoC network.

The names of block ports are defined in the YAML descriptions for the blocks. Blocks can use any names for their ports, and they don't have to be numbered (unless the number of ports is parameterized). Generally, the block ports are named <code>in_N</code> for inputs to the block and <code>out_N</code> for outputs. SEP ports are named <code>in0</code> for the input <code>out0</code> for the output.

If you are having trouble connecting a block due to an unresolved connection, running <code>rfnoc_image_builder</code> with the <code>-l debug</code> option will list all available block ports.

Finally, the FFT block has an additional clock input port named <code>ce</code> that is used for the FFT signal processing. We need to connect it to a clock domain. Any clock that's at least as fast as the incoming data rate should be sufficient. For example, X3xx devices have a <code>ce</code> clock (214.286 MHz) that is usually a good choice, but <code>rfnoc_chdr</code> clock (200 MHz) should also work for this example. For N31x and E3xx devices, <code>rfnoc_chdr</code> clock is a good choice (200 MHz on N31x and 100 MHz on E3xx). For N32x, <code>radio</code> clock (250 MHz) is a good choice. For example, this is how you would connect the X310's <code>ce</code> clock to the <code>ce</code> port of the FFT block:

clk_domains:
...
- { srcblk: _device_, srcport: ce, dstblk: fft0, dstport: ce }

And this is how you would connect <code>rfnoc_chdr</code> clock to the <code>ce</code> port:

clk_domains:
...
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

And finally, this is how you would connect <code>radio</code> clock:

clk_domains:
...
- { srcblk: _device_, srcport: radio, dstblk: fft0, dstport: ce }

The source block name <code>_device_</code> is special and refers to the USRP device itself. Choose a clock that's apprpriate for your device and connect it as shown above.

And that's it! The next step will be to run the image builder on our modified YAML file. Once that's done, and the bitstream has been created, you can load it onto your USRP X310 device, and verify the blocks, as we did in the [[#Inspect_the_Default_Image|Inspect the Default Image]] section.

For example, from the X300 directory, you would run the following command to run the image builder:

$ rfnoc_image_builder -y x310_with_fft.yml -t X310_XG

To download the FPGA bitstream to the X310, run the following:

$ uhd_image_loader --args "type=x300,addr=192.168.30.2" --fpga-path ./build/usrp_x310_fpga_XG.bin

You may need to change the IP address to match your device, depending on your configuration. After completing the flash update and power-cycling the USRP, run <code>uhd_usrp_probe</code> to confirm that the FFT block was recognized.

$ uhd_usrp_probe --args "type=x300,addr=192.168.30.2"

Take a look at the RFNoC blocks and the static connections on the device. You should see the following new blocks and connections:

| _____________________________________________________
| /
| | RFNoC blocks on this device:
...
| | * 0/FFT#0
...
| _____________________________________________________
| /
| | Static connections on this device:
...
| | * 0/SEP#6:0==>0/FFT#0:0
| | * 0/FFT#0:0==>0/SEP#6:0
...


===Example: Adding an FFT Block to the Receive Chain===

Now that we've added the FFT block and verified that it is operating as expected, let's see if we can modify it a little. Let's say that we're sure that we always want to receive the FFT bins from our device, and we don't want to see the raw samples. In order to save some FPGA resources, we can move our FFT block to be between the DDC and the SEP, on the RX data path. Instead of the previous modifications to our YAML file, we want the following:

Starting from UHD 4.8:

stream_endpoints:
...
# Unchanged from the default image core (no need for ep_fft).

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
MAX_FFT_SIZE_LOG2: 10

connections:
...
# Change this line:
# - { srcblk: ddc0, srcport: out_0, dstblk: ep0, dstport: in0 }
# Change it to the following to add fft0 between ddc0 and ep0:
- { srcblk: ddc0, srcport: out_0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep0, dstport: in0 }

clk_domains:
...
# As before, we still connect our FFT block to the clock domain
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

From UHD 4.0 until UHD 4.7:

stream_endpoints:
...
# Unchanged from the default image core (no need for ep_fft).

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft_1x64.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
EN_FFT_SHIFT: 1

connections:
...
# Change this line:
# - { srcblk: ddc0, srcport: out_0, dstblk: ep0, dstport: in0 }
# Change it to the following to add fft0 between ddc0 and ep0:
- { srcblk: ddc0, srcport: out_0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep0, dstport: in0 }

clk_domains:
...
# As before, we still connect our FFT block to the clock domain
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

This last line is valid for E310/E320; for X300/X310/N300/N310/N320/N321 use the following:

- { srcblk: _device_, srcport: ce, dstblk: fft0, dstport: ce }

And as simply as that, we have added the FFT block to our RX block chain. Remember that this is a static connection, so when the resulting FPGA image is loaded onto your device, you will no longer be able to receive samples from the DDC directly; all samples on that chain will be processed by the FFT block, and you will only receive FFT bins from this radio chain.

==Out-of-tree Modules==

===OOT Overview===

Now that we've gone over what is provided by UHD, let's start to look at custom RFNoC development. It's recommended that custom RFNoC development be kept separate from the in-tree UHD RFNoC infrastructure and examples, in order to simplify version control and licensing. Modules located outside of the repository are called ''out-of-tree'' (OOT).

In order to understand how OOT modules for RFNoC are created, let's take a look at the example that's provided with UHD. You can find the example located in <code><repo>/host/examples/rfnoc-example/</code>. This example includes a simple Gain RFNoC block that we can use as a reference for creating our own OOT blocks.

===OOT Subdirectories===

Take a look at the <code>rfnoc-example</code> directory structure. An OOT module is a collection of block implementations, the software controllers for those blocks, and sometimes applications to demonstrate their functionality. These different components within the OOT module are organized into the directories described below.

* HDL and Image Resources
** <code>fpga/</code>: Contains the HDL (e.g., Verilog) required for the module. Each RFNoC block should have its own subdirectory here, such as <code>rfnoc_block_gain</code>, for the Gain block.
** <code>rfnoc/blocks/</code>: Contains the YAML RFNoC block definition files. These describe the block's interfaces and are used by the image builder. We'll go into more detail with regards to what goes into these YAML files in the [[#Creating_Your_Own_RFNoC_Block|Creating Your Own RFNoC Block]] section.
** <code>icores/</code>: Contains example FPGA image core YAML files, to demonstrate how to create an FPGA image using your custom blocks. These image core files may demonstrate important parameters or show recommended configurations for chains of blocks.
* Block Controller and Example Software
** <code>include/</code>: Contains the headers for the block controller software. Once installed, these headers will be used by UHD and other applications to interface with and control your custom RFNoC blocks.
** <code>lib/</code>: Contains the block controller implementations. The files here should implement the features outlined in the headers located in the <code>include/</code> directory. All unit test code should also be located here.
** <code>apps/</code>: Contains example applications for your custom blocks. These applications may demonstrate how to use the block controllers, common configurations, or how to process data from your blocks.
* Infrastructure
** <code>cmake/</code>: Contains any custom CMake commands the module may need. In general, simple modules will not need to modify this directory at all. More complicated modules with additional external dependencies may need to modify this.

Take some time to explore the files in the <code>rfnoc-gain</code>. Note the following files and directories related to the Gain example:

* <code>rfnoc-gain/fpga/rfnoc_block_gain/</code><br>This is the HDL for the Gain RFNoC block.
** <code>rfnoc_block_gain.v</code><br>The top-level synthesizable file for the Gain block
** <code>noc_shell_gain.v</code><br>The NoC Shell for the Gain block
** <code>rfnoc_block_gain_tb.sv</code><br>The simulation testbench
** <code>Makefile</code><br>The simulation Makefile
* <code>rfnoc-gain/blocks/gain.yml</code><br>The YAML block definition file for the Gain block
* <code>rfnoc-gain/icores/x310_rfnoc_image_core.yml</code><br>An example RFNoC image core YAML description showing how to connect the Gain block
* <code>rfnoc-gain/include/rfnoc/example/gain_block_control.hpp</code><br>The software block controller header
* <code>rfnoc-gain/lib/gain_block_control.cpp</code><br>The software block controller implementation
* <code>rfnoc-gain/apps/init_gain_block.cpp</code><br>An example showing how to find and initialize the Gain block


===Creating Your Own OOT Module===

'''This section is outdated, use rfnoc_modtool instead!'''

To create your own OOT module, make a copy of the <code>rfnoc-example</code> directory. This will contain all the subdirectories and infrastructure files that you need to create your custom module. The directory name for your copy should be renamed to your desired name; we recommend something like <code>rfnoc-foo</code>, for example, where <code>foo</code> is the name for your OOT module. You'll also need to change <code>rfnoc-example</code> within the module's <code>CMakeLists.txt</code> files to your module's name.

Let's start by creating our own copy of the <code>rfnoc-example</code> to work with. We'll call our module <code>demo</code>. You can put the copy wherever you like, but for this example we'll put it in our home directory.

$ cp -r <repo>/host/examples/rfnoc-example ~/
$ mv ~/rfnoc-example ~/rfnoc-demo

Now we need to edit our <code>CMakeLists.txt</code> files to rename our module. Edit the following files and change all instances of <code>rfnoc-example</code> to <code>rfnoc-demo</code>:

~/rfnoc-demo/CMakeLists.txt
~/rfnoc-demo/lib/CMakeLists.txt

===Building and Installing an OOT Module===
The OOT module will need to be built and installed in order to use its RFNoC blocks. To build and install the OOT module we just created, do the following:

$ mkdir ~/rfnoc-demo/build
$ cd ~/rfnoc-demo/build
$ cmake -DUHD_FPGA_DIR=<repo>/fpga/ ../

This configures the project to be installed in the default location. You may want to provide a different install directory to CMake using the <code>-DCMAKE_INSTALL_PREFIX</code>. Please refer to the [https://files.ettus.com/manual/page_build_guide.html UHD Installation Guide] or the installation guide for other CMake-based projects for instructions on configuring CMake.

Note that we specify the location of the FPGA source code using the <code>-DUHD_FPGA_DIR</code> option. This allows you to run the FPGA testbenches and to build the example FPGA image provided with the OOT example.

At this point, you can run <code>make help</code> to see what options are available. A few of the available make targets are described below:

* <code>make rfnoc-demo</code>: Build the block controllers for the RFNoC blocks
* <code>make testbenches</code>: Run the testbenches for the RFNoC blocks
* <code>make x310_rfnoc_image_core</code>: Build the FPGA example image
* <code>make install</code>: Install the module

To build and install the block, perform the following steps.

$ cd ~/rfnoc-demo/build
$ make
$ make install

Note that <code>sudo</code> may be required depending on the install location.

===Building an FPGA Image with OOT Blocks===

At this point you can build the example FPGA that's included in the <code>icores</code> directory. Take a look at <code>~/rfnoc-demo/icores/x310_rfnoc_image_core.yml</code>. Note that the <code>gain</code> block is added in exactly the same way that the FFT block was in [[#Example:_Adding_an_FFT_Block|Example: Adding an FFT Block]]. You can build this example FPGA for the X310 using the following steps:

$ cd ~/rfnoc-demo/build
$ make x310_rfnoc_image_core

Alternatively, you can call <code>rfnoc_image_builder</code> directly. In order to get the image builder to find your custom blocks, you may need to supply some additional arguments to find the OOT module, as shown in the following example:

$ rfnoc_image_builder -F <repo>/fpga –I ~/rfnoc-demo/include/rfnoc -y ~/rfnoc-demo/icores/x310_rfnoc_image_core.yml

The <code>-I</code> option is only required if the OOT module has not been installed on the system. 

If you have an X310, you can build and use the provided example to test the Gain block. If you have a different USRP, you can use its default <code>rfnoc_image_core.yml</code> as a starting point and follow the same steps that we followed for the FFT block in [[#Example:_Adding_an_FFT_Block|Example: Adding an FFT Block]], then build it using the process described above.

===Testing the Gain Example===

After building an FPGA image for your USRP and downloading it to your device, the Gain block should be available. Test this by running <code>uhd_usrp_probe</code>:

$ uhd_usrp_probe --args "type=x300,addr=192.168.30.2"

Again, note that your <code>args</code> may be different or may not be required if you only have a single USRP connected.

Take a look at the RFNoC blocks and the static connections on the device. You should see the following new blocks and connections:

| _____________________________________________________
| /
| | RFNoC blocks on this device:
...
| | * 0/Block#0
...
| _____________________________________________________
| /
| | Static connections on this device:
...
| | * 0/SEP#4:0==>0/Block#0:0
| | * 0/Block#0:0==>0/SEP#4:0
...

==Creating Your Own RFNoC Block==

The Gain block is a useful example and could even be used as the starting point for a new block, but rather than trying to copy and edit the Gain block, it is best to use the RFNoC ModTool to create a new block template. This is also required if you want to change the interfaces provided to your IP that are exposed by the NoC Shell.

===Understanding the Block Definition YAML===

The first step in creating a new block is to write a YAML description for the block that you want to create. The options available are described [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification]. You can also look at the blocks available in <code><repo>/host/include/uhd/rfnoc/blocks/</code> for examples. We'll provide a brief overview here.

Open up and take a look at the Gain block definition located in <code>~/rfnoc-demo/blocks/gain.yml</code>. Notice the different sections, which are described below:

* '''General Parameters'''<br>In this section we give our block a name (<code>module_name</code>) and a unique block ID (<code>noc_id</code>). The NoC ID is an arbitrary 32-bit number that will be used by the software to identify the block during system discovery. You can also specify the CHDR bus width, which should be 64 for Generation-3 USRPs.
* '''Clocks'''<br>In the <code>clocks</code> section, we define the clocks that will be used by the block. The <code>rfnoc_chdr</code> and <code>rfnoc_ctrl</code> clocks are required. Many blocks also have a <code>ce</code> clock for internal DSP.
* '''Control Interface'''<br>The <code>control</code> section defines what type of control interface to make available to your block. The control interface is used for register reads and writes. Most blocks do not need to modify this section and will use the <code>ctrlport</code> interface type. Control Port is the standard register interface used by RFNoC. The <code>clk_domain</code> parameter allows you to specify which clock domain to use for the register interface exposed to your block. Typically this is the same clock that is used for the <code>data</code> interface, to avoid clock crossings.
* '''Data Interface'''<br>The <code>data</code> section defines what type of data interface to make available to your block and describes the ports. Most blocks use either the <code>axis_pyld_ctxt</code> or the <code>axis_data</code> interface types.<br>The <code>clk_domain</code> parameter allows you to specify which clock domain to use for the data interfaces exposed to your block. Typically this is the same clock that is used for the <code>control</code> interface, to avoid clock crossings.<br>Under the <code>inputs</code> and <code>outputs</code> sections you can describe the input and output ports.
* '''IO Ports'''<br>The <code>io_ports</code> section is used to describe other device-specific ports to which your block needs to connect (such as the DRAM or radio interfaces). For most blocks, this section is not used.

A few other sections might be present in the YAML file (e.g., <code>registers</code> or <code>properties</code>). These sections are reserved for future use and can be left empty.

===Starting Your Own Block Definition===

Let's start by making a copy of the Gain block YAML for our use case.

$ cp ~/rfnoc-demo/blocks/gain.yml ~/rfnoc-demo/blocks/demo.yml

Now open the <code>demo.yml</code> file you just created and make the following changes:

# Change the name of the block from <code>gain</code> to <code>demo</code>
# Change the <code>noc_id</code> to <code>0x0000DE30</code>
# Change the <code>format</code> for the <code>in</code> and <code>out</code> ports from <code>int32</code> to <code>sc16</code>.

This YAML file now describes a block with the following features:

* The block named "demo"
* NoC ID of 0xDE30
* CtrlPort register interface on the <code>rfnoc_chdr</code> clock domain
* A single 32-bit input port named "In" on the <code>rfnoc_chdr</code> clock domain that will provide sc16 samples to your IP
* A single 32-bit output port named "Out" on the <code>rfnoc_chdr</code> clock domain that will receive sc16 samples from your IP

===Generating Your Block Using the ModTool===

Now that we have a block definition YAML file, we can generate the source code templates and NoC Shell for our block. To do so, run the following command:

$ python3 <repo>/host/utils/rfnoc_blocktool/rfnoc_create_verilog.py -c ~/rfnoc-demo/blocks/demo.yml -d ~/rfnoc-demo/fpga/rfnoc_block_demo

This will create a folder named <code>~/rfnoc-demo/fpga/rfnoc_block_demo</code> with an RFNoC block template for you to use. Explore the folder that was created. You should see the following files:

* '''<code>Makefile</code>''': This is the Makefile for the simulation testbench. See [https://files.ettus.com/manual/md_usrp3_sim_running_testbenches.html Running a Testbench] in the UHD and USRP Manual for instructions on how to run a testbench.
* '''<code>Makefile.srcs</code>''': This is another makefile that identifies the HDL source code that makes up your RFNoC block.
* '''<code>noc_shell_demo.v</code>''': This is the NoC Shell that was generated for your block. It provides the interfaces described in the block definition YAML.
* '''<code>rfnoc_block_demo.v</code>''': This is a template for your RFNoC block. It includes all the top-level ports required by RFNoC and instantiates the NoC Shell.
* '''<code>rfnoc_block_demo_tb.sv</code>''': This is a testbench template for your RFNoC block. It instantiates your RFNoC block and the bus functional models (BFMs) needed to communicate with your block in simulation.

Take a moment to look at the <code>rfnoc_block_demo.v</code> and <code>rfnoc_block_demo_tb.sv</code> files that were generated for your block. Notice the "User Logic" section towards the end of the <code>rfnoc_block_demo</code> module. This is the location where you can insert your own IP.

The input data samples come in on the <code>m_in_payload</code> AXI4-Stream bus. The output data samples go out on the <code>s_out_payload</code> AXI4-Stream data bus.

If your input packets are the same size as your output packets (i.e., for every sample in you generate one sample out) then the <code>m_in_context</code> data bus can be used to drive <code>s_out_context</code>. The context bus is described in detail in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

Similarly, the testbench has a section where you can add your own test sequences to the test bench.

If you decide you need to change the RFNoC interfaces for your block (e.g., add ports, or change the interface type), then it is recommended to update the block definition YAML then regenerate the block. Please take care to not overwrite any code you have written when regenerating the files for your block! Rerunning the tool will cause new files to be generated, with a new NoC Shell, and will demonstrate how to update your code for the new interfaces.

Refer to the Gain example and other RFNoC blocks for examples of how to complete your RFNoC block logic and testbenches.

==Summary==

In this guide we have given a brief introduction on how to develop for RFNoC in UHD 4.0. There's a lot more you can do than is described here, but this will hopefully get you started. Happy coding!

RFNoC Frequently Asked Questions

2024-06-26T09:33:25Z

MartinBraun: /* How do I add a clock with a different frequency? */

== Configuring the Stream Endpoint Buffer Size in RFNoC ==

=== What is the SEP buffer size? ===

Each stream endpoint (SEP) has an ingress buffer to store data received from others stream endpoints. This size of this buffer affects the data transfer rate that can be achieved when streaming to that endpoint. A larger ingress buffer in the stream endpoint means that there is more space to put data, minimizing idle time on the network. Additionally, streamers can queue up data before it is needed, reducing the chance of a buffer underflow.

=== How do I set the SEP buffer size? ===

The stream endpoint buffer size is set by adding a parameter under the endpoint you want to configure in the RFNoC image core YAML file. There are two parameters you can use to set the stream endpoint ingress buffer size in your RFNoC image core YAML file.

* <code>buff_size</code>: Buffer size in CHDR words. The size in bytes depends on the CHDR width. For example, if the <code>chdr_width</code> parameter for the device is 64, then each CHDR word is 8 bytes. So a buff size of 32768 would be 262,144 bytes or 256 KiB. See [https://github.com/EttusResearch/uhd/blob/197cdc4f665cbd4e6394a7eeb44b405f67ab10b1/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml#L20 here] for an example.
* <code>buff_size_bytes</code>: Buffer size in bytes. See [https://github.com/EttusResearch/uhd/blob/197cdc4f665cbd4e6394a7eeb44b405f67ab10b1/fpga/usrp3/top/x400/x410_200_rfnoc_image_core.yml#L21 here] for an example.

=== To what value should I set the SEP buffer size? ===

The buffer size should be a power of two in size to make optimal use of FPGA RAM resources. The default FPGA bitstreams typically set them to the largest size the FPGA can fit in order to maximize performance. Here are some general recommendations:

* Set to <code>0</code> if you don't need to send data to that SEP.
* Set to <code>8192</code> bytes (8 KiB = 1 MTU) minimum in order to stream data packets.
* Set to <code>32768</code> bytes (32 KiB = 4 MTU) in order to stream at maximum rates between SEPs on the same FPGA.
* Set to <code>262144</code> bytes (256 KiB = 32 MTU) or lager for high performance streaming between a host computer and the FPGA.

Note that the requirements are application-dependent, so optimal sizes for your application may be different. MTU refers to the maximum transmission unit, which is the largest CHDR packet supported by the FPGA.

If you need to free up FPGA resources (particularly block RAM) for your application, you can reduce the SEP buffer sizes. Just keep in mind that the maximum streaming rate may be affected.

== USRP DRAM ==

=== How much and what speed DRAM is available on each USRP? ===

The table below summarizes the DRAM that is connected to the USRP for use by RFNoC.

{| class="wikitable"
|+ USRP DRAM Summary
|-
! USRP Model !! DRAM Size !! Default DRAM Speed !! Default User Interface
|-
| E31x || 512 MiB || 16-bit @ 800 MT/s (1.6 GB/s) || 2 ch x 64-bit @ 100 MHz
|-
| E320 || 2 GiB || 32-bit @ 1333 MT/s (5.33 GB/s) || 4 ch x 64-bit @ 300 MHz
|-
| N3xx || 2 GiB || 32-bit @ 1300 MT/s (5.2 GB/s) || 4 ch x 64-bit @ 303.819 MHz
|-
| X3xx || 1 GiB || 32-bit @ 1200 MT/s (4.8 GB/s) || 2 ch x 64-bit @ 300 MHz
|-
| X410 (100 and 200 MHz BW) || 4 GiB || 64-bit @ 2.0 GT/s (16.0 GB/s) || 4 x 64-bit @ 250 MHz
|-
| X410 (400 MHz BW) || 4 GiB per bank<br>(8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank<br>(32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank<br>(8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank<br>(38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank<br>(8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank<br>(38.4 GB/s total) || 2 x 512-bit @ 300 MHz (using 2 banks)
|}

=== What DRAM data rates can I expect on each USRP? ===

DRAM performance is highly application-specific. For example, reading vs. reading and writing simultaneously, one data stream vs. multiple data streams, random access vs. sequential access, etc., can give dramatically different performance. Below are some measurements taken on different USRPs where a Null-Source-Sink RFNoC block is directly connected to a DMA FIFO block to test maximum streaming rates through the DRAM. The DRAM is shared between channels, so throughput goes down as the number of channels going through the DRAM is increased.

{| class="wikitable"
|+ Example DRAM Throughput (Per Channel)
|-
! USRP Model !! BIST (MB/s) !! 1 Ch (MS/s) !! 2 Ch (MS/s) !! 3 Ch (MS/s) !! 4 Ch (MS/s)
|-
| E31x || 666 || 166 || 91 || N/A || N/A
|-
| E320 || 1361 || 340 || 299 || 191 || 148
|-
| N3xx || 1368 || 341 || 295 || 191 || 144
|-
| X3xx || 1347 || 336 || 274 || N/A || N/A
|-
| X410 (100 and 200 MHz BW) || 1288 || 321|| 316|| 314 || 303
|-
| X410 (400 MHz BW) || 2801 || 697 || 672 || 672 || 672
|-
| X440 (400 MHz BW) || 3360 || 798 || 784 || 616 || 461
|-
| X440 (1600 MHz BW) || 8118 || 2007 || 2007 || N/A || N/A
|}
Notes:
# E31x, N3xx, and X410 were tested using UHD 4.2. E320 and X3xx were tested using UHD 4.3.
# BIST refers to the built-in self test, which gives a measure of raw data throughput for a single channel.
# For MS/s, we assume 4 bytes per sample (sc16).
# X410 with 400 MHz bandwidth uses two independent memory banks, with channels 0-1 on Bank 0, and channels 2-3 on Bank 1 by default. The traffic flows on Bank 0 and Bank 1 are independent and do not affect each other. Therefore, a 4-channel configuration has the same performance as a 2-channel configuration.
# X440 uses two independent memory banks. For 400 MHz, channels 0-3 are on Bank 0 and channels 4-7 are on Bank 1 by default. For 1600 MHz, channel 0 is on Bank 0 and channel 1 is on bank 1 by default. The traffic flows on Bank 0 and Bank 1 are independent and do not affect each other. Therefore, a 2-channel configuration has the same performance as a 1-channel configuration.

=== What can the DRAM be used for? ===

* '''DMA FIFO Block:''' The DMA FIFO block is used in situations where you need a large buffer to store samples.

* '''Replay Block:''' The Replay block is used to record and play back RF data. For example, you can record data from a host computer, then play it back over the radio. Or, record data from the radio, then play it back later to the host for analysis, or play it back to a radio at a specific timestamp. See [[Using the RFNoC Replay Block in UHD 4]] for additional information. The Replay block also has a FIFO capability for situations in which the DMA FIFO block is not available in your FPGA image.

* '''Custom Blocks:''' You can also create your own RFNoC block that uses DRAM. Refer to the DMA FIFO and/or Replay blocks as examples.

=== How do I add the Replay/DMA FIFO block to my FPGA image? ===

If the block you want is not included by default in the FPGA image you are using, you can add it to the RFNoC image core YAML file and rebuild the FPGA image using Vivado. See [[Getting Started with RFNoC in UHD 4.0]] for additional information on customizing an RFNoC image.

'''Note:''' DRAM is not enabled by default on E31x FPGA builds because the FPGA is not large enough to fit the default image with DRAM. You will need to remove components from your RFNoC image's YAML file to make room, then build the E31x image with the variable DRAM=1 set, or modify the E31x Makefile to enable DRAM by default.

'''Note:''' The default DRAM configuration used for X410 and X440 changes depending on the configured bandwidth. The default parameters to use for each image type is shown in the table below.

When adding the blocks to your RFNoC image core YAML file, the parameters must be set correctly for the type of USRP you intend to use. The memory data width (<code>MEM_DATA_W</code>) and address width (<code>MEM_ADDR_W</code>) must match exactly. The number of ports (<code>NUM_PORTS</code>) must not exceed the maximum number available. You can use fewer ports to save resources if you don't need all the DRAM ports.

{| class="wikitable"
|+ RFNoC Block Memory Parameters
|-
! USRP Model !! MEM_DATA_W !! MEM_ADDR_W !! NUM_PORTS (Max)
|-
| E31x || 64 || 29 || 2
|-
| E320 || 64 || 31 || 4
|-
| N3xx || 64 || 31 || 4
|-
| X3xx || 64 || 30 || 2
|-
| X410 (100 and 200 MHz BW) || 64 || 32 || 4
|-
| X410 (400 MHz BW) || 128 || 32 || 4
|-
| X440 (400 MHz BW) || 128 || 32 || 8
|-
| X440 (1600 MHz BW) || 512 || 32 || 2
|}

The DMA FIFO has a few additional parameters that should be provided. The clock rate (<code>MEM_CLK_RATE</code>) must match the value below for the built-in self test (BIST) to work correctly. The base address (<code>FIFO_ADDR_BASE</code>) and address mask (<code>FIFO_ADDR_MASK</code>) are written as Verilog constants and can be changed depending on your application. The <code>FIFO_ADDR_BASE</code> parameter contains the byte address for the first byte of the memory region to use for each port. The <code>FIFO_ADDR_MASK</code> parameter contains the address mask for each port, which tells the FIFO how much memory to use for each port. For example, an address mask of <code>30'h1FFFFFFF</code> means that 0x1FFFFFFF+1 bytes (i.e., 0x20000000 bytes or 512 MiB) will be used by the corresponding port. The address mask must be 1 less than a power of 2.

The example values in the table below use the entire memory and divide it evenly between all available ports.

{| class="wikitable"
|+ DMA FIFO Parameters
|-
! USRP Model !! MEM_CLK_RATE !! FIFO_ADDR_BASE !! FIFO_ADDR_MASK
|-
| E31x || "200e6" || "{29'h10000000, 29'h00000000}" || "{29'h0FFFFFFF, 29'h0FFFFFFF}"
|-
| E320 || "300e6" || "{31'h60000000, 31'h40000000, 31'h20000000, 31'h00000000}" || "{31'h1FFFFFFF, 31'h1FFFFFFF, 31'h1FFFFFFF, 31'h1FFFFFFF}"
|-
| N3xx || "303819444" || "{31'h60000000, 31'h40000000, 31'h20000000, 31'h00000000}" || "{31'h1FFFFFFF, 31'h1FFFFFFF, 31'h1FFFFFFF, 31'h1FFFFFFF}"
|-
| X3xx || "300e6" || "{30'h20000000, 30'h00000000}" || "{30'h1FFFFFFF, 30'h1FFFFFFF}"
|-
| X410 (100 and 200 MHz BW) || "250e6" || "{32'hC0000000, 32'h80000000, 32'h40000000, 32'h00000000}" || "{32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF}"
|-
| X410 (400 MHz BW) || "250e6" || "{32'h80000000, 32'h00000000, 32'h80000000, 32'h00000000}" || "{32'h7FFFFFFF, 32'h7FFFFFFF, 32'h7FFFFFFF, 32'h7FFFFFFF}"
|-
| X440 (400 MHz BW) || "300e6" || "{32'hC0000000, 32'h80000000, 32'h40000000, 32'h00000000, 32'hC0000000, 32'h80000000, 32'h40000000, 32'h00000000}" || "{32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF, 32'h3FFFFFFF}"
|-
| X440 (1600 MHz BW) || "300e6" || "{32'h00000000, 32'h00000000}" || "{32'hFFFFFFFF, 32'hFFFFFFFF}"
|}

==== Replay Example ====

See [https://github.com/EttusResearch/uhd/blob/197cdc4f665cbd4e6394a7eeb44b405f67ab10b1/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml#L69 x310_rfnoc_image_core.yml] for an example of how to instantiate the Replay block in the RFNoC image core YAML description. The following is a generic example that can be used for any USRP:
<nowiki>
noc_blocks:
# Instantiate the replay block
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: <see table>
MEM_DATA_W: <see table>
MEM_ADDR_W: <see table>

connections:
# Connect each port of the replay block to a stream endpoint
- { srcblk: <epN>, srcport: out0, dstblk: replay0, dstport: in_0 }
- { srcblk: replay0, srcport: out_0, dstblk: <epN>, dstport: in0 }
- { srcblk: <epN+1>, srcport: out0, dstblk: replay0, dstport: in_1 }
- { srcblk: replay0, srcport: out_1, dstblk: <epN+1>, dstport: in0 }
... repeat for each remaining Replay port
# Connect the replay block memory interface to the USRP DRAM
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram }

Connect the DRAM clock to the block:
clk_domains:
# Connect the DRAM clock to the replay block
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }</nowiki>

==== DMA FIFO Example ====

See [https://github.com/EttusResearch/uhd/blob/197cdc4f665cbd4e6394a7eeb44b405f67ab10b1/fpga/usrp3/top/e320/e320_rfnoc_image_core.yml#L49 e320_rfnoc_image_core.yml] for an example of how to instantiate the DMA FIFO block in the RFNoC image core YAML description. The following is a generic example that can be used for any USRP:
<nowiki>
noc_blocks:
# Instantiate the DMA FIFO block
fifo0:
block_desc: 'axi_ram_fifo.yml'
parameters:
NUM_PORTS: <see table>
MEM_DATA_W: <see table>
MEM_ADDR_W: <see table>
FIFO_ADDR_BASE: <see table>
FIFO_ADDR_MASK: <see table>
MEM_CLK_RATE: <see table>

connections:
# Connect each port of the DMA FIFO block to a stream endpoint, or insert it
# into the data path where desired. This examples uses stream endpoints.
- { srcblk: <epN>, srcport: out0, dstblk: fifo0, dstport: in_0 }
- { srcblk: replay0, srcport: out_0, dstblk: <epN>, dstport: in0 }
- { srcblk: <epN+1>, srcport: out0, dstblk: fifo0, dstport: in_1 }
- { srcblk: fifo0, srcport: out_1, dstblk: <epN+1>, dstport: in0 }
... repeat for each remaining FIFO port
# Connect the DMA FIFO block memory interface to the USRP DRAM
- { srcblk: fifo0, srcport: axi_ram, dstblk: _device_, dstport: dram }

clk_domains:
# Connect the DRAM clock to the replay block
- { srcblk: _device_, srcport: dram, dstblk: fifo0, dstport: mem }</nowiki>

== RFNoC Clocks ==

=== What clocks are available for me to use? ===

Each device has different clocks available. See below for a list of clocks exposed to RFNoC. Although they have intended purposes, you can use any of these clocks for any purpose. The <code>rfnoc_chdr_clock</code> is a good default choice. This clock is always available in your block, even if it is not explicitly connected in the RFNoC image YAML description.

=== What are the clock frequencies? ===

See the table below for the clock rates. The radio clock rate depends on the master clock rate.

====E31x====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 100 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
|-
| <code>dram</code> || DRAM interface clock || 100 MHz
|-
| <code>radio</code> || Radio interface clock || Same as master clock rate
|}

====E320====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 200 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
|-
| <code>dram</code> || DRAM interface clock || 166.667 MHz
|-
| <code>radio</code> || Radio interface clock || Same as master clock rate (200 kHz to 61.44 MHz)
|}

====N300/N310====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 200 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
|-
| <code>dram</code> || DRAM interface clock || 303.819 MHz
|-
| <code>radio</code> || Radio interface clock || Same as master clock rate (122.88 MHz, 125.0 MHz, or 153.6 MHz)
|}

====N32x====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 200 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
|-
| <code>dram</code> || DRAM interface clock || 303.819 MHz
|-
| <code>radio</code> || Radio interface clock || Same as master clock rate (200 MHz, 245.76 MHz, or 250 MHz)
|}

====X3xx====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 187.5 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 93.75 MHz
|-
| <code>ce</code> || Compute Engine clock || 214.286 MHz
|-
| <code>dram</code> || DRAM interface clock || 300 MHz
|-
| <code>radio</code> || Radio interface clock || Same as master clock rate (184.32 MHz or 200 MHz)
|}

====X410====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 200 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
|-
| <code>dram</code> || DRAM interface clock || 250 MHz
|-
| <code>radio</code> || Radio interface clock || 122.88 MHz when master clock rate is 122.88, 245.76, or 491.52 MHz<br>125 MHz when master clock rate is 125, 250, or 500 MHz
|-
| <code>radio_2x</code> || Radio interface clock 2x || Twice the frequency of <code>radio</code>
|}

====X440====
{| class="wikitable"
! Clock Name !! Description !! Frequency
|-
| <code>rfnoc_chdr</code> || RFNoC CHDR clock || 200 MHz
|-
| <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
|-
| <code>dram</code> || DRAM interface clock || 300 MHz
|-
| <code>radio0</code> || Radio interface clock for daughterboard 0 || Daughterboard 0 master clock rate divided by 8 (e.g., 62.5 MHz if master clock rate is 500 MHz)
|-
| <code>radio1</code> || Radio interface clock for daughterboard 1 || Daughterboard 1 master clock rate divided by 8
|-
| <code>radio0_2x</code> || Radio interface clock 2x for daughterboard 0 || Twice the frequency of <code>radio0</code>
|-
| <code>radio1_2x</code> || Radio interface clock 2x for daughterboard 1 || Twice the frequency of <code>radio1</code>
|}

=== How do I add a clock with a different frequency? ===

If you only need the clock within your own RFNoC block, you can modify the HDL for your block to generate the clock that you need from one of the available clocks. To do this, add a new clock to your block's YAML description, connect the available clock to your block in the YAML description of your RFNoC image, then add a Xilinx MMCM IP instance to your block's HDL and connect the available clock to its input.

Starting with UHD 4.7, you can add clock generation modules that create new clocks based on the existing clocks. Note that you must create such a module as an HDL module: Describing clocks in the YAML files will not cause them to be generated for you.

Assuming you have such a module, describe the clocks in the module's YAML files as such:

clocks:
- name: ce
direction: in
- name: my_clk
direction: out

Now you will have a new clock called <code>my_clk</code>, which is derived from the <code>ce</code> clock.

In older versions of UHD, adding custom clocks is not directly supported. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

If the clock is needed by multiple RFNoC blocks, or if you want to change an existing clock, you can modify the HDL for the USRP you are using to add or change a clock. If you add a new clock to the RFNoC image core, you must also update the BSP YAML file (located in [https://github.com/EttusResearch/uhd/tree/master/host/include/uhd/rfnoc/core <repo>/host/include/uhd/rfnoc/core]) so that the <code>rfnoc_image_builder</code> knows that the clock exists. How and where the clocks are generated varies between USRPs. Please refer to the source code for that USRP ([https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/top <repo>/fpga/usrp3/top]).

== Xilinx Vivado ==

=== Do I need a Vivado license to build custom RFNoC FPGA images? ===

All RFNoC-capable USRPs use Xilinx FPGAs that require a license to use Vivado, except for E31x USRPs, which can use the free Vivado HL WebPACK Edition. Vivado is required to build FPGAs for RFNoC.

=== Which version and edition of Vivado do I need? ===

See the [https://files.ettus.com/manual/md_usrp3_build_instructions.html UHD User Manual] for the latest Vivado version requirements. UHD versions 4.0 through 4.2 require Vivado 2019.1.

For E31x devices, you can use the free Vivado HL Webpack. For all other USRPs, you can use Design Edition or System Edition. We recommend Design Edition, unless you plan to use System Generator for DSP. System Generator is not required by RFNoC.

=== Can I use a different Vivado version from the one required by my UHD version? ===

This is technically possible, but it can be a lot of work to convert and adapt all of the IP to a new Vivado version, and your custom combination of UHD and Vivado versions will not have been tested or validated by Ettus Research. Therefore, this is not recommended or supported.

=== Do I need to install all components of Vivado? ===

No. You only need to install device support for the FPGA you intend to build. Other devices can be unchecked to save disk space. The following FPGA types are used by USRPs:

* '''SoCs > Zynq-7000:''' E31x, E320, N3xx
* '''SOCs > Zynq UltraScale+ RFSoC:''' X410
* '''7 Series > Kintex-7''': X3xx

The Software Development Kit (SDK) is typically not required, but can be installed if desired.

The Cable Drivers are needed if you plan to do JTAG download or debug. Note that on Linux, the cable drivers are copied to the install folder, but are not installed onto your system automatically. See Xilinx UG973 for instructions on installing the cable drivers on Linux.

== Building FPGA Images ==

=== Why did my FPGA build fail to meet timing constraints? ===

FPGAs have clocks that trigger the transfer of data between internal registers. The Vivado tool does a timing check near the end of the build to ensure that the paths from each driving register or port to each receiving register or port are not too long for the specified clock period or delay constraints. When it says "The design did not satisfy timing constraints" it means that Vivado couldn't arrange the logic on the chip in a way that meets all requirements. There are several reasons this might happen:

* You added new logic to the design with too much logic between registers. In this case, you should modify your design to make meeting timing easier.
* You added new logic, but made a mistake in which you're trying to use the wrong clock or reset, which makes it difficult to meet timing. In this case you need to correct the mistake in your design.
* The design has become too crowded, making it difficult for the tools to meet the timing requirements. In this case you need to remove something to make more room.
* Bad luck. The tools use pseudorandom algorithms to find solutions to really hard problems, and sometimes it doesn't find a good solution even when one is possible. In this case you can make a minor change to the design and build again to see if it does better the second time. If you don't change anything, Vivado will normally give you identical results for each build. In UHD 4.4 and later you can add the <code>BUILD_SEED=1</code> option to the <code>make</code> arguments to change a build seed that will affect the build results. Using a different seed number for each build will ensure that you get a unique build result each time. 0 is the default seed if not specified. Random build failures occur occasionally for some FPGA targets, in which case you should retry the build with a different seed.

The FPGA tools produce a timing report that says exactly which path failed to meet timing. Sometimes that can point you in the right direction. But sometimes the path indicated only failed because of another path that's even more difficult. Open <code>post_route_timing_summary.rpt</code> in the build output folder and search for "(VIOLATED)" to find the path(s) that failed.

=== My design doesn't fit in the FPGA. What can I do to reduce the size? ===

Read the <code>post_synth_util.rpt</code> to determine what resource(s) you are running out of in order to know what kinds of changes are needed. Below are several easy ways to reduce the resource utilization of the FPGA.

* If you are not using all RF channels of your device, modify the FPGA YAML file to remove the DDC, DUC, and Radio blocks for the unused channels, then regenerate the FPGA code using <code>rfnoc_image_builder</code>. Note that you may need at least one Radio block for RFNoC to work properly. You may also remove the DDC and/or the DUC if your application uses full bandwidth for one or more channels and therefore doesn't require up or down conversion.
* If you are not using DRAM, remove the Replay or DMA FIFO blocks. Also, on X4xx, change the <code>DRAM_CH</code> variable to 0 in the Makefile for the FPGA target you are building.
* If you do not need all SFP ports, use a build target that matches your needs. For example, on X4xx, the "X1" option (one 10 Gbps lane) uses the least resources whereas "X4" (four 10 Gbps lanes) uses a lot more, and the "CG" option (four 25 Gbps lanes) uses the most.
* If you do not need the full bandwidth of the device, use a smaller bandwidth option. For example, on X410, the "_100" option (100 MHz bandwidth) uses less resources than the "_200" option (200 MHz bandwidth).
* Add the <code>crossbar_routes</code> definition to the FPGA YAML file to include only the crossbar paths required for your application. This is an advanced feature in UHD 4.5 and later. This must be done carefully to avoid removing essential paths. See the X440 YAML files for examples.

Other reductions are possible but require advanced knowledge of UHD and/or RFNoC to avoid breaking key functionality of the device.

=== How do I create a Vivado project for my FPGA build? ===

Vivado supports two modes of operation known as "project mode" and "non-project mode". Project mode is more user-friendly because it creates a project file that is managed by Vivado and works natively in the Vivado GUI. Non-project mode is generally used by more advanced users who want full control over the Vivado build process and is typically used in fully scripted or automated build flows. The USRP build flow in UHD uses non-project mode. As a result, there is no Vivado project file by default.

It is possible to create a project file from the USRP build flow with the following steps:

# Start the USRP FPGA build in the GUI by adding <code>GUI=1</code> to the <code>make</code> arguments. Example:<br/><code>make X410_X4_200 GUI=1</code>
# After the build completes, run the following command in the TCL Console of Vivado to create the project file and switch to project mode:<br/><code>save_project_as project_name project_dir</code><br/>In this example, "project_name" is the name you want to give the project file and "project_dir" is the directory in which you want to put the project.
# Set the compile order to automatic: <br/><code>set_property source_mgmt_mode All [current_project]</code>

This project file can now be used independently of the normal FPGA build flow in UHD. It is up to the user to update this project file as the design changes since it will not be managed by the normal build flow in UHD.

=== My FPGA takes a long time to build. What can I do to make builds faster? ===

High-performance computers are recommended for FPGA builds since an FPGA build can take several hours.

The build process is divided into two steps, IP generation and the FPGA build.

==== IP Generation ====

This process can take several hours by default and is run automatically, if needed, when you build an FPGA target. Fortunately, this only needs to be done once for each USRP type and won't run again unless IP is changed.

You can speed up the IP generation by running this step with multiple jobs. For example:

$ make -j 4 X410_IP

This example will build four IP cores at a time. Note that this generally requires 4 times as much memory and needs at least 4 CPU cores. You can adjust the number of parallel jobs based on the amount of system memory and/or CPU cores you have available.

==== FPGA Build ====

Unfortunately, increasing the number of jobs does not speed up FPGA performance because there is only one Vivado instance for the FPGA build. Vivado, by default, will use multiple CPU cores, where possible, but this does not significantly improve build performance since many parts of the build are not easily parallelizable.

One way to shorten the build time is to reduce the size of the design. See above on how to reduce the size of your design.

In the case where you need to build multiple FPGA types, you can use the jobs option with <code>make</code> to build multiple FPGAs simultaneously, which can dramatically reduce the time required per build. Note that this requires a significant amount of memory and CPU cores and therefore is only recommended for systems that can handle such loads. An example is shown below for building two FPGA images in parallel:

$ make -j 2 X410_X4_200 X410_CG_400

It is also possible to open separate terminal instances and run one build in each instance to get the same effect. Do not build the same FPGA target in multiple instances, since multiple builds for the same target would conflict as they try to access and update the same files.

=== My FPGA build failed with a cryptic message or no message at all. How do I debug this? ===

When you build an FPGA target, a build directory is created in the FPGA's top directory that contains all the build outputs. Here you'll find the <code>build.log</code> file as well as report files and checkpoints. Not all log information is printed to the console during build, so make sure you check the <code>build.log</code> file for details. It may contain a useful error message that was not printed to the console.

Builds often fail when Vivado encounters an internal error or runs out of memory. For internal errors, the error message is typically not very helpful and is often due to a bug in Vivado. When Vivado runs out of memory, it may immediately terminate without giving any error message at all. Consider monitoring the memory usage during the FPGA build to see if you are approaching your system's limit.

If you have made changes to the design, try building an unmodified FPGA image from scratch to ensure the build process is working properly on your system. If this works, try adding your changes incrementally until the section of code causing the problem is identified.

Note that such errors are often beyond the control of Ettus Research and reaching out to Xilinx support is a better option if it is truly a Vivado issue.

=== I get a warning saying that an IP is locked, which results in errors later in the IP generation process. How do I resolve this? ===

Vivado "locks" IP, for example, when it needs to be updated for the running version of Vivado or FPGA device type. This is intended to force the user to fix the issue and to avoid building incompatible IP. Build failures related to IP being locked should never occur during a normal build. The IP version in the UHD repo always matches the Vivado version required for that release of UHD.

This can happen if you have used the wrong version of Vivado or do not have the correct Vivado patches installed. Refer to the <code>Generation 3 USRP Build Documentation</code> section of the [[UHD and USRP User Manual|UHD Manual] for the required version and patches. When you run the `source setenv.sh` step to setup your environment, the script will check to make sure you are using the correct version.

In some cases, reinstalling Vivado might be required.

Once the correct Vivado version and patches are installed, you will need to remove all build products (to remove any locked IP that was generated) and retry the build. For example:

$ source setupenv.sh # Setup environment and check the Vivado version
$ make cleanall # Remove any bad IP that was generated
$ make X410_X4_200 # Start the build process again

=== I see a "CRITICAL WARNING" in the build log. Is this expected? ===

There are many critical warnings that appear during the build process that can be safely ignored. For example, you may see the following:

CRITICAL WARNING: [Vivado 12-1790] Evaluation License Warning: This design contains one or more IP cores that use separately licensed features. If the design has been configured to make use of evaluation features, please note that these features will cease to function after a certain period of time. Please consult the core datasheet to determine whether the core which you have configured will be affected. Evaluation features should NOT be used in production systems.

The FPGA builds include IP for which the licenses are included with Vivado, but Vivado prints the warnings anyway. As long as you have a Vivado license and a bitstream was successfully generated, the IP should work as expected.

Getting Started with DPDK and UHD

2023-07-17T12:34:40Z

MartinBraun: /* Full Rate Streaming */

== Application Note Number and Authors ==

'''AN-500''' by Nate Temple, Alex Williams, Wade Fife, and Matt Prost


==Overview==

This application note walks through the process to get started with the Data Plane Development Kit (DPDK) driver within UHD.

==Abstract==

Up until now, UHD's only support for networked devices was backed by the kernel's sockets implementation. Every call to <code>send()</code> or <code>recv()</code> would cause a context switch and invite the kernel's scheduler to replace our thread with something else. Because the typical scheduler is optimized to distribute CPU time fairly across multiple loads, the timing-critical threads might sporadically be hit with sleeping time, and the thread might be migrated off its current CPU and forced to run on another. The overhead and random latency spikes make it difficult to enable reliable real-time streaming at higher rates.

DPDK is a high-speed packet processing framework that enables a kernel bypass for network drivers. By putting the entire driver in user space, avoiding context switches, and pinning I/O threads to cores, UHD and DPDK combine to largely prevent the latency spikes induced by the scheduler. In addition, the overall overhead for packet processing lowers.

== Supported Devices ==

===USRPs===

DPDK is supported on the following USRP devices:

* N300 / N310
* N320 / N321
* X300 / X310
* E320

=== Host Network Cards ===

DPDK is supported on many Intel and Mellanox based 10Gb NICs. Below is a list of NICs Ettus Research has tested. For a full list of NICs supported by DPDK, please see the DPDK manual.

* Intel X520-DA1
* Intel X520-DA2
* Intel X710-DA2
* Intel X710-DA4
* Intel XL710
* Mellanox MCX4121A-ACAT ConnectX-4 Lx
* Mellanox MCX516A-CCAT ConnectX-5

== References ==

* DPDK: https://www.dpdk.org/
** https://doc.dpdk.org/guides-17.11
** https://doc.dpdk.org/guides-18.11
* UHD Manual: https://files.ettus.com/manual/page_dpdk.html

== Dependencies ==

* UHD 3.x requires DPDK 17.11, which is included in the default repos of Ubuntu 18.04.x

* UHD 4.0 requires DPDK 18.11

* DPDK support was added for the N3xx/E320 USRPs with UHD 3.13.x.x

* DPDK support was added for the X3xx with UHD 3.14.1.0

== Installing DPDK ==

On Ubuntu 18.04.x, it is possible to install DPDK 17.11 via <code>apt</code>:

sudo apt install dpdk dpdk-dev

For DPDK 18.11, follow the instructions on the DPDK website to download, configure, and build DPDK (https://doc.dpdk.org/guides-18.11/linux_gsg/build_dpdk.html).

== Installing UHD ==

Once the <code>dpdk</code> and <code>dpdk-dev</code> packages are installed, UHD will locate them during a build and you should see DPDK in the enabled components lists when running cmake.

== Enable hugepages ==

Edit your grub configuration file, <code>/etc/default/grub</code>, and add the follow parameters to <code>GRUB_CMDLINE_LINUX_DEFAULT</code>:

iommu=pt intel_iommu=on hugepages=2048

On a vanilla Ubuntu system it should look like this:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash iommu=pt intel_iommu=on hugepages=2048"

Close <code>/etc/default/grub</code> and at the command prompt, update your grub configuration with the command:

sudo update-grub

For these settings to take effect, reboot your host machine.

== Preparing your UHD Configuration File ==

You should note the MAC addresses for your 10Gb NICs before proceeding.

The MAC addresses for your NICs can be found by running the command:

ip a

You should then create a UHD configuration file at the location <code>/root/.uhd/uhd.conf</code>.

sudo su
mkdir -p /root/.uhd
nano /root/.uhd/uhd.conf

=== UHD 3.x ===

An example <code>uhd.conf</code> file is listed below. Note that field names in UHD 3.x are slightly different from UHD 4.0.

You should update the following fields for your configuration from this example:

* Update the MAC address variables, <code>dpdk-mac</code>, to match your NIC

* Update the <code>dpdk-driver</code> if the location is different on your system. <code>/usr/lib/x86_64-linux-gnu/dpdk-17.11-drivers/</code> is the default location on Ubuntu 18.04.x when <code>dpdk</code> is installed via <code>apt</code>.

* Update the <code>dpdk-corelist</code> and <code>dpdk-io-cpu</code> fields. In this example, a two port NIC is used. There should be one core for the main <code>dpdk</code> thread (in this example <code>core #2</code>), and then separate cores assigned to each NIC (in this example <code>core #3</code> for the first port on the NIC, <code>core #4</code> for the second port on the NIC)

* Update the <code>dpdk-ipv4</code> fields to your desired IP range.
** <code>192.168.30.2</code>, <code>192.168.40.2</code> on a default X3xx system
** <code>192.168.10.2</code>, <code>192.168.20.2</code> on a default N3xx system
** <code>192.168.10.2</code> on a default E320 system

[use_dpdk=1]
dpdk-mtu=9000
dpdk-driver=/usr/lib/x86_64-linux-gnu/dpdk-17.11-drivers/
dpdk-corelist=2,3,4
dpdk-num-mbufs=4095
dpdk-mbufs-cache-size=315

[dpdk-mac=aa:bb:cc:dd:ee:f1]
dpdk-io-cpu = 3
dpdk-ipv4 = 192.168.10.1/24

[dpdk-mac=aa:bb:cc:dd:ee:f2]
dpdk-io-cpu = 4
dpdk-ipv4 = 192.168.20.1/24

'''Note:''' Additional information on the UHD configuration file can be found here: https://files.ettus.com/manual_archive/v3.15.0.0/html/page_dpdk.html#dpdk_nic_config

=== UHD 4.0 ===

An example <code>uhd.conf</code> file is listed below. Note that the field names in UHD 4.0 are slightly different from UHD 3.x.

You should update the following fields for your configuration from this example:

* Update the MAC address variables, <code>dpdk_mac</code>, to match your NIC

* Update the <code>dpdk_driver</code> if the location is different on your system. <code>/usr/local/lib/</code> is the default location on Ubuntu 18.04.x when DPDK 18.11 is manually built and installed.

* Update the <code>dpdk_corelist</code> and <code>dpdk_lcore</code> fields. In this example, a two port NIC is used. There should be one core for the main <code>dpdk</code> thread (in this example <code>core #2</code>), and then separate cores assigned to each NIC (in this example <code>core #3</code> for the first port on the NIC, <code>core #4</code> for the second port on the NIC)

* Update the <code>dpdk_ipv4</code> fields to your desired IP range.
** <code>192.168.30.2</code>, <code>192.168.40.2</code> on a default X3xx system
** <code>192.168.10.2</code>, <code>192.168.20.2</code> on a default N3xx system
** <code>192.168.10.2</code> on a default E320 system

[use_dpdk=1]
dpdk_mtu=9000
dpdk_driver=/usr/local/lib/
dpdk_corelist=2,3,4
dpdk_num_mbufs=4095
dpdk_mbuf_cache_size=315

[dpdk_mac=aa:bb:cc:dd:ee:f1]
dpdk_lcore = 3
dpdk_ipv4 = 192.168.10.1/24

[dpdk_mac=aa:bb:cc:dd:ee:f2]
dpdk_lcore = 4
dpdk_ipv4 = 192.168.20.1/24

'''Note:''' Additional information on the UHD configuration file can be found here: https://files.ettus.com/manual/page_dpdk.html#dpdk_nic_config

== Additional Host Configuration for NIC Vendors ==

The process for this step is different for Intel and Mellanox NICs and is detailed in individual sections below.

=== Intel X520 / X710 ===

The Intel based NICs will use the <code>vfio-pci</code> driver which must be loaded:

sudo modprobe vfio-pci

Next, you will need to rebind the NIC to the <code>vfio-pci</code> drivers.

First, identify the PCI address your NIC is at:

dpdk-devbind --status

Note the PCI address that your NIC is connected to for the next step.

Before the next step, you will need to turn off the NIC first before doing the rebind.

In Ubuntu under <code>System</code> -> <code>Network</code> -> click the switches to <code>off</code> for the 10Gb ports, then run the <code>dpdk-devbind</code> commands:

'''Note:''' Your PCI address will likely be different than <code>02:00.0</code> as shown in the example below.

sudo dpdk-devbind --bind=vfio-pci 02:00.0
sudo dpdk-devbind --bind=vfio-pci 02:00.1

Now if you run <code>dpdk-devbind --status</code> again, you should see the NICs listed under DPDK devices

# dpdk-devbind --status

Network devices using DPDK-compatible driver
============================================
0000:02:00.0 '82599ES 10-Gigabit SFI/SFP+ Network Connection 10fb' drv=vfio-pci unused=ixgbe
0000:02:00.1 '82599ES 10-Gigabit SFI/SFP+ Network Connection 10fb' drv=vfio-pci unused=ixgbe

'''Note:''' More info can be found here on the rebinding process: https://doc.dpdk.org/guides-17.11/linux_gsg/linux_drivers.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules

=== Mellanox NICs ===

The Mellanox NICs do not require rebinding using the <code>vfio-pci</code> driver. Mellanox provides additional drivers for DPDK.

Install and activate the Mellanox drivers:

sudo apt install librte-pmd-mlx5-17.11
sudo modprobe -a ib_uverbs mlx5_core mlx5_ib

For 18.11 you can download and install the latest Mellanox drivers from the mellanox website (https://www.mellanox.com/products/infiniband-drivers/linux/mlnx_ofed).

The MLX5 poll mode driver library (librte_pmd_mlx5) in DPDK provides support for Mellanox ConnextX-4 and ConnectX-5 cards. This driver must be enabled manually with the build option <code>CONFIG_RTE_LIBRTE_MLX5_PMD=y</code> when building DPDK.

=== Running UHD Applications with DPDK ===

UHD based application (including GNU Radio flowgraphs) can now be ran using a DPDK transport by passing in the Device Argument: <code>use_dpdk=1</code>.

'''Important Note:''' In order for UHD to use DPDK, the UHD application *must* be ran as the <code>root</code> user. Using <code>sudo</code> will not work, you should switch to the <code>root</code> user by running <code>sudo su</code>.

For example, running the <code>benchmark_rate</code> utility:

<pre>
# cd /usr/local/lib/uhd/examples

# ./benchmark_rate --rx_rate 125e6 --rx_subdev "A:0 B:0" --rx_channels 0,1 --tx_rate 125e6 --tx_subdev "A:0 B:0" --tx_channels 0,1 --args "addr=192.168.10.2,second_addr=192.168.20.2,mgmt_addr=10.2.1.19,master_clock_rate=125e6,use_dpdk=1"

[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106501; UHD_3.14.0.HEAD-0-gabf0db4e
EAL: Detected 8 lcore(s)
EAL: Some devices want iova as va but pa will be used because.. EAL: IOMMU does not support IOVA as VA
EAL: No free hugepages reported in hugepages-1048576kB
EAL: Probing VFIO support...
EAL: VFIO support initialized
EAL: PCI device 0000:02:00.0 on NUMA socket -1
EAL: Invalid NUMA socket, default to 0
EAL: probe driver: 8086:10fb net_ixgbe
EAL: using IOMMU type 1 (Type 1)
EAL: Ignore mapping IO port bar(2)
EAL: PCI device 0000:02:00.1 on NUMA socket -1
EAL: Invalid NUMA socket, default to 0
EAL: probe driver: 8086:10fb net_ixgbe
EAL: Ignore mapping IO port bar(2)
PMD: ixgbe_dev_link_status_print(): Port 0: Link Down
EAL: Port 0 MAC: aa bb cc dd ee f1
EAL: Port 0 UP: 1
PMD: ixgbe_dev_link_status_print(): Port 1: Link Down
EAL: Port 1 MAC: aa bb cc dd ee f2
EAL: Port 1 UP: 1
EAL: Init DONE!
EAL: Starting I/O threads!
USER2: Thread 1 started
[00:00:00.000003] Creating the usrp device with: addr=192.168.10.2,second_addr=192.168.20.2,mgmt_addr=10.2.1.19,master_clock_rate=125e6,use_dpdk=1...
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=10.2.1.19,type=n3xx,product=n310,serial=313ABDA,claimed=False,addr=192.168.10.2,second_addr=192.168.20.2,master_clock_rate=125e6,use_dpdk=1
[INFO] [MPM.PeriphManager] init() called with device args 'product=n310,time_source=internal,master_clock_rate=125e6,clock_source=internal,use_dpdk=1,second_addr=192.168.20.2,mgmt_addr=10.2.1.19'.
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000004)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1344 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1341 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1348 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1347 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000002)
Using Device: Single USRP:
Device: N300-Series Device
Mboard 0: ni-n3xx-313ABDA
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: Magnesium
RX Channel: 1
RX DSP: 0
RX Dboard: B
RX Subdev: Magnesium
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: Magnesium
TX Channel: 1
TX DSP: 0
TX Dboard: B
TX Subdev: Magnesium

[00:00:03.728707] Setting device timestamp to 0...
[INFO] [MULTI_USRP] 1) catch time transition at pps edge
[INFO] [MULTI_USRP] 2) set times next pps (synchronously)
[00:00:05.331920] Testing receive rate 125.000000 Msps on 2 channels
[00:00:05.610789] Testing transmit rate 125.000000 Msps on 2 channels
[00:00:15.878071] Benchmark complete.

Benchmark rate summary:
Num received samples: 2557247854
Num dropped samples: 0
Num overruns detected: 0
Num transmitted samples: 2504266704
Num sequence errors (Tx): 0
Num sequence errors (Rx): 0
Num underruns detected: 0
Num late commands: 0
Num timeouts (Tx): 0
Num timeouts (Rx): 0

Done!
</pre>

=== Tuning Notes ===

==== General Host Performance Tuning App Note ====

The Application Note linked below covers general performance tuning tips that should be applied:

* https://kb.ettus.com/USRP_Host_Performance_Tuning_Tips_and_Tricks

==== Increasing num_recv_frames ====

If you experience <code>Overflows</code> at higher data rates, adding the device argument <code>num_recv_frames=512</code> can help.

==== Full Rate Streaming (UHD 3.x only) ====

If you're streaming data at the full master clock rate, and there is no interpolation or decimation being performed on the FPGA, you can skip the DUC and DDC blocks within the FPGA with the following parameters:

* <code>skip_ddc=1</code>
* <code>skip_duc=1</code>

==== Full Rate on X3xx ====

If you're streaming two transmit channels at full rate (200e6) on the X3xx platform, you should additionally set the device arg:

* <code>enable_tx_dual_eth=1</code>

==== Isolate CPUs ====

Isolating the CPUs that are used for DPDK can improve performance. This can be done by adding the <code>isolcpus</code> parameter to your <code>GRUB_CONFIG</code>

isolcpus=2,3,4

==== Disable System Interrupts ====

Disabling system interrupts can improve the jitter and performance generally by 1-3%. This can be done by adding the parameters below to your <code>GRUB_CONFIG</code>

nohz_full=2,3,4 rcu_nocbs=2,3,4

==== Disable Hyper-threading ====

In some applications which require the highest possible CPU performance per core, disabling hyper-threading can provide roughly a 10% increase in core performance, at the cost of having less core threads. Hyper-threading can be disabled within the BIOs and varies by manufacturer.

==== Streaming on Multiple Channels ====

If you're streaming on multiple channels simultaneously, you can create multiple streamer objects on separate threads. This can be accomplished with the `benchmark_rate` example by using the parameter `--multi_streamer`.

==== Elevated Streaming Thread Priority ====

In UHD 4, streaming thread priorities can be elevated with the `uhd::set_thread_priority_safe()` function call. This can be accomplished with the benchmark_rate example by using parameter `--priority high`.

==== Additional Tuning Notes from Intel ====

* Performance report from Intel on DPDK 17.11: https://fast.dpdk.org/doc/perf/DPDK_17_11_Intel_NIC_performance_report.pdf
* How to get best performance with NICs on Intel platforms: https://doc.dpdk.org/guides/linux_gsg/nic_perf_intel_platform.html

== Known Issues / Troubleshooting ==

=== Underruns Every Second with DPDK + Ubuntu ===

With Linux kernels 5.10 and beyond, we have observed periodic underruns on systems that otherwise have no issues. These Linux kernel versions are the default for Ubuntu 20.04.3 LTS and later. The underrun issue is due to the <code>RT_RUNTIME_SHARE</code> feature being disabled by default in these versions of the Linux kernel (shown as <code>NO_RT_RUNTIME_SHARE</code>). The following procedure can be used to enable this feature. This process was tested on Linux kernel version 5.13; the procedure may be slightly different on other kernel versions. To determine the Linux kernel version of your system, in a terminal issue the command <code>uname -r</code>.

<pre>
$ sudo -s
$ cd /sys/kernel/debug/sched
$ cat features

GENTLE_FAIR_SLEEPERS START_DEBIT NO_NEXT_BUDDY LAST_BUDDY CACHE_HOT_BUDDY WAKEUP_PREEMPTION NO_HRTICK NO_HRTICK_DL NO_DOUBLE_TICK NONTASK_CAPACITY TTWU_QUEUE SIS_PROP NO_WARN_DOUBLE_CLOCK RT_PUSH_IPI '''NO_RT_RUNTIME_SHARE''' NO_LB_MIN ATTACH_AGE_LOAD WA_IDLE WA_WEIGHT WA_BIAS UTIL_EST UTIL_EST_FASTUP NO_LATENCY_WARN ALT_PERIOD BASE_SLICE

$ echo RT_RUNTIME_SHARE > features
$ cat features

GENTLE_FAIR_SLEEPERS START_DEBIT NO_NEXT_BUDDY LAST_BUDDY CACHE_HOT_BUDDY WAKEUP_PREEMPTION NO_HRTICK NO_HRTICK_DL NO_DOUBLE_TICK NONTASK_CAPACITY TTWU_QUEUE SIS_PROP NO_WARN_DOUBLE_CLOCK RT_PUSH_IPI '''RT_RUNTIME_SHARE''' NO_LB_MIN ATTACH_AGE_LOAD WA_IDLE WA_WEIGHT WA_BIAS UTIL_EST UTIL_EST_FASTUP NO_LATENCY_WARN ALT_PERIOD BASE_SLICE
</pre>

[[Category:Application Notes]]

X300/X310

2022-07-13T16:03:38Z

MartinBraun: /* FPGA */

== Device Overview ==
The Ettus Research USRP X310 is a high-performance, scalable software defined radio (SDR) platform for designing and deploying next generation wireless communications systems. The hardware architecture combines two extended-bandwidth daughterboard slots covering DC – 6 GHz with up to 160 MHz of baseband bandwidth, multiple high-speed interface options (PCIe, dual 10 GigE, dual 1 GigE), and a large user-programmable Kintex-7 FPGA in a convenient desktop or rack-mountable half-wide 1U form factor.

== Key Features==
===X300===
{|
|style="vertical-align:top"|
* Xilinx Kintex-7 XC7K325T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: DC - 6 GHz with suitable daughterboard
* Up 160MHz bandwidth per channel
* Two wide-bandwidth RF daughterboard slots
* Optional GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, ExpressCard, Dual 1G)
|[[File:Product x300.jpg|250px|center]]
|}

===X310===
{|
|style="vertical-align:top"|
* Xilinx Kintex-7 XC7K410T FPGA
* 14 bit 200 MS/s ADC
* 16 bit 800 MS/s DAC
* Frequency range: DC - 6 GHz with suitable daughterboard
* Up 160MHz bandwidth per channel
* Two wide-bandwidth RF daughterboard slots
* Optional GPSDO
* Multiple high-speed interfaces (Dual 10G, PCIe Express, ExpressCard, Dual 1G)
|[[File:Product x310.jpg|250px|center]]
|}

==Compatible Daughterboards==
* WBX-120 / WBX-40
* SBX-120 / SBX-40
* CBX-120 / CBX-40
* UBX-160 / UBX-40
* BasicTX / BasicRX
* LFRX / LFTX
* TwinRX
* DBSRX2 (EOL)
* RFX Series (EOL)
* TVRX2 (EOL)

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

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

===X300===
* Current Hardware Revision: 8
* Minimum version of UHD required: 3.9.0

===X310===
* Current Hardware Revision: 8
* Minimum version of UHD required: 3.9.0

===Clocking and Sampling Rates===
There are two master clock rates (MCR) supported on the X300 and 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===
27.7 x 21.8 x 3.9 cm

===Weight===
With 2x SBX-120: 1.7kg

===Drawings===
* [[Media:cu ettus-x3xx.pdf| Enclosure]]
* [[Media:cu x3xx motherboard cca.pdf| Motherboard]]
* [[Media:cu Rackmount Ettus-X3xx.pdf| Rackmount kit]]

===CAD/STP Models===
====X3xx====
* [[Media:cu x3xx motherboard cca.stp.gz| Motherboard]]

====X3xx Enclosure====
* [[Media:cu ettus x3xx.stp.gz|Enclosure]]

==Environmental Specifications==
===Operating Temperature Range===
* X300/X310: 25 °C

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

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

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

|[http://www.xilinx.com/support/documentation/data_sheets/ds180_7Series_Overview.pdf XC7K325T] / [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.fairchildsemi.com/datasheets/FI/FIN1002.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://www.micrel.com/_PDF/HBW/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/lit/ds/symlink/tps77625.pdf TPS77625_SM]
|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)
|-

|}

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

===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.

==FPGA==
* Utilization statistics are subject to change between UHD releases. This information is current as of UHD 3.9.4 and was taken directly from Xilinx Vivado 2014.4.

===X300===
<pre>
1. Slice Logic
--------------

+----------------------------+-------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------------------+-------+-----------+-------+
| Slice LUTs | 61622 | 203800 | 30.23 |
| LUT as Logic | 52887 | 203800 | 25.95 |
| LUT as Memory | 8735 | 64000 | 13.64 |
| LUT as Distributed RAM | 1878 | | |
| LUT as Shift Register | 6857 | | |
| Slice Registers | 62961 | 407600 | 15.44 |
| Register as Flip Flop | 62961 | 407600 | 15.44 |
| Register as Latch | 0 | 407600 | 0.00 |
| F7 Muxes | 1209 | 101900 | 1.18 |
| F8 Muxes | 150 | 50950 | 0.29 |
+----------------------------+-------+-----------+-------+

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

+-------------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+-------------------+------+-----------+-------+
| Block RAM Tile | 409 | 445 | 91.91 |
| RAMB36/FIFO* | 398 | 445 | 89.43 |
| RAMB36E1 only | 398 | | |
| RAMB18 | 22 | 890 | 2.47 |
| RAMB18E1 only | 22 | | |
+-------------------+------+-----------+-------+
* Note: Each Block RAM Tile only has one FIFO logic available and therefore can accommodate only one FIFO36E1 or one FIFO18E1. However, if a FIFO18E1 occupies a Block RAM Tile, that tile can still accommodate a RAMB18E1

4. DSP
------

+----------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------+------+-----------+-------+
| DSPs | 123 | 840 | 14.64 |
| DSP48E1 only | 123 | | |
+----------------+------+-----------+-------+

</pre>

===X310===
<pre>
1. Slice Logic
--------------

+----------------------------+-------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------------------+-------+-----------+-------+
| Slice LUTs | 61616 | 254200 | 24.23 |
| LUT as Logic | 52885 | 254200 | 20.80 |
| LUT as Memory | 8731 | 90600 | 9.63 |
| LUT as Distributed RAM | 1878 | | |
| LUT as Shift Register | 6853 | | |
| Slice Registers | 62958 | 508400 | 12.38 |
| Register as Flip Flop | 62958 | 508400 | 12.38 |
| Register as Latch | 0 | 508400 | 0.00 |
| F7 Muxes | 1209 | 127100 | 0.95 |
| F8 Muxes | 150 | 63550 | 0.23 |
+----------------------------+-------+-----------+-------+

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

+-------------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+-------------------+------+-----------+-------+
| Block RAM Tile | 409 | 795 | 51.44 |
| RAMB36/FIFO* | 398 | 795 | 50.06 |
| RAMB36E1 only | 398 | | |
| RAMB18 | 22 | 1590 | 1.38 |
| RAMB18E1 only | 22 | | |
+-------------------+------+-----------+-------+
* Note: Each Block RAM Tile only has one FIFO logic available and therefore can accommodate only one FIFO36E1 or one FIFO18E1. However, if a FIFO18E1 occupies a Block RAM Tile, that tile can still accommodate a RAMB18E1

4. DSP
------

+----------------+------+-----------+-------+
| Site Type | Used | Available | Util% |
+----------------+------+-----------+-------+
| DSPs | 123 | 1540 | 7.98 |
| DSP48E1 only | 123 | | |
+----------------+------+-----------+-------+

</pre>

===FPGA User Modifications===
The Verilog code for the FPGA in the USRP X300 and USRP X310 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.

==Firmware==

The USRP X300 series runs a small amount of software within the FPGA, within a ZPU soft processor. Its main responsibility is to provide access to some registers, handle the networking stacks, and monitor the USRP status.

The source code for the ZPU is stored in <code>firmware/usrp3/</code> in the UHD repository. To modify the firmware, you need to download a recent ZPU compiler (e.g. from https://github.com/zylin/zpugcc/tree/master/releases/20150428). Unpack the tarball (e.g., into <code>/usr/local</code>) and make sure the <code>zpu-elf-gcc</code> binary is in your path. Then, execute the following steps:
* Create and enter a build directory: <code>mkdir build && cd build</code>
* Run cmake: <code>cmake /path/to/firmware/usrp3/</code>
** If all is correctly configured, and the ZPU compiler can be found, this will pass without errors.
* Build the firmware: <code>make</code>
** This should yield output similar to this:

<pre>
Scanning dependencies of target x300
[ 79%] Generating x300_main.map
[ 83%] Generating x300_main.bin
[ 87%] Generating x300_main.ihx
[ 91%] Generating x300_main.dump
[ 95%] Generating x300_main.rom
[100%] Generating x300_main.coe
[100%] Built target x300
</pre>

* These files will be copied into the <code>build/x310</code> directory.
* To non-persistently load the newly built firmware image into the running FPGA image, simply launch a UHD session with the <code>fw</code> parameter. The binary must be within UHD's image dir, e.g. by copying x300_main.bin to the default image directory (e.g., <code>/usr/local/share/uhd/images</code>) or by temporarily setting the <code>UHD_IMAGES_DIR</code> variable:

UHD_IMAGES_DIR=/path/to/build/x300 uhd_usrp_probe --args type=x300,fw=x300_main.bin

* To permanently bake the firmware image into the FPGA bitfile, copy the file <code>x300_main.coe</code> to <code>fpga/usrp3/top/x300/ip/bootram/bootram.coe</code> and rebuild the bitfile.

==Interfaces and Connectivity==
Follow the links below for additional information on configuring each interface for the USRP X300 or X310 SDRs.

*[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_pcie_laptop ExpressCard (Laptop)] - 50 MS/s Full Duplex @ 16-bit
*[http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_hw_1gige Dual 1 Gigabit Ethernet] - 25 MS/s Full Duplex @ 16-bit

===Front Panel===
{|
| style="width:50%" |

* '''JTAG''': USB connector for the on-board USB-JTAG programmer
* '''RF A Group'''
** '''TX/RX LED''': Indicates that data is streaming on the TX/RX channel on daughterboard A
** '''RX2 LED''': Indicates that data is streaming on the RX2 channel on daughterboard A
* '''REF''': Indicates that the external Reference Clock is locked
* '''PPS''': Indicates a valid PPS signal by pulsing once per second
* '''AUX I/O''': Front panel GPIO connector.
* '''GPS''': Indicates that GPS reference is locked
* '''LINK''': Indicates that the host computer is communicating with the device (Activity)
* '''RF B Group'''
** '''TX/RX LED''': Indicates that data is streaming on the TX/RX channel on daughterboard B
** '''RX2 LED''': Indicates that data is streaming on the RX2 channel on daughterboard B
* '''PWR''': Power switch

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

===Rear Panel===
{|
| style="width:50%" |
* '''PWR''': Connector for the USRP-X Series power supply
* '''1G/10G ETH''': SFP+ ports for Ethernet interfaces
* '''REF OUT''': Output port for the exported reference clock
* '''REF IN''': Reference clock input
* '''PCIe x4''': Connector for Cabled PCI Express link
* '''PPS/TRIG OUT''': Output port for the PPS signal
* '''PPS/TRIG IN''': Input port for the PPS signal
* '''GPS''': Connection for the GPS antenna

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

===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.

===On-Board LEDs===
{| class="wikitable"

!LED
!Detail
!Description
|-

| DS1
| 1.2V
| Power
|-

| DS2
| TXRX1
| Red: TX, Green: RX
|-

| DS3
| RX1
| Green: RX
|-

| DS4
| REF
| Reference Lock
|-

| DS5
| PPS
| Flashes on Edge
|-

| DS6
| GPS
| GPS Lock
|-

| DS7
| SFP0
| Link, Right, Green
|-

| DS8
| SFP0
| Link Activity, Left, Yellow
|-

| DS10
| TXRX2
| Red: TX Green: RX
|-

| DS11
| RX2
| Green: RX
|-

| DS12
| 6V
| Daughterboard Power
|-

| DS13
| 3.8V
| Power
|-

| DS14
| 3.3V
| Management Power
|-

| DS15
| 3.3V
| Auxiliary Management Power
|-

| DS16
| 3.3V
| FPGA Power
|-

| DS19
| SFP1
| Link Active, Left, Yellow
|-

| DS20
| SFP1
| Link, Right, Green
|-

| DS21
| LINK
| Link Activity
|-

|}

===Power Connector===
Model: PDP-40 by CUI Inc.

Power plug connectors for custom power harnesses can be purchased here: https://www.digikey.com/products/en?KeyWords=CP-7340-ND&WT.z_cid=sp_102_buynow

Assembly instructions: [[Media:pdp-40.pdf]]

====Pin Detail====
* Pins #1 / #2: 12v
* Pins #3 / #4: Ground

[[File:pdp 40 power detail.png]]

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

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

'''Chinese Customers'''

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

==Certificate of Volatility==
===X300/X310===
* [[Media:volatility USRP X300 X310 r1.pdf]]

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

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

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

==Choosing USRP X310 vs USRP X300==
In terms of host bandwidth, interface options, and all other hardware features the USRP X300 and USRP 310 are identical. However, the USRP X310 provides a larger FPGA, a Xilinx XC7K410T, as opposed to XC7K325T. While both options provide a significant amount of free resources for custom FPGA development, the XC7K410T provides additional design margin, which translates to ease of development and future expandability. Most users choose the USRP X310 for their development.

{| class="wikitable" style="margin: auto;"
!colspan="3"|USRP X300 and X310 FPGA Resource Summary
|-
|rowspan="2"|Resource Type
|USRP X300 (XC7K325T)
|USRP X310 (XC7K410T)
|-
|Count
|Count
|-
|DSP48 Blocks
|840
|1540
|-
|Block Rams (18kB)
|890
|1590
|-
|Logic Cells
|326,080
|406,720
|-
|Slices (logic)
|50,950
|63,550
|-
|}

For up-to-date information on FPGA resource utilization in the stock FPGA design, please see "USRP 300/X310 FPGA Resources" in the Ettus Research knowledge base (https://kb.ettus.com).

==Choosing an RF Daughterboard==
With the increased sample rates used by the USRP X300 and USRP X310, these new device can support extended-bandwidth daughterboards. The WBX-120, SBX-120, and CBX-120 are recommended to take advantage of the full bandwidth capability of the USRP X300 and X310. The WBX-120, SBX-120, and CBX-120 have been upgraded from their predecessors (40 MHz) to use 120 MHz baseband filters. You can select your daughterboard based on the center frequency of your primary application.

{| class="wikitable" style="margin: auto;"
!Daughterboard
!Frequency Range
!Bandwidth
|-

|WBX-120
|50 MHz - 2200 MHz
|120 MHz
|-

|SBX-120
|400 MHz - 4400 MHz
|120 MHz
|-

|CBX-120
|1200 MHz - 6000 MHz
|120 MHz
|-

|UBX-160
|10 MHz - 6000 MHz
|160 MHz
|-

|TwinRX
|10 MHz - 6000 MHz
|80 MHz per channel, 160 MHz total
|-

|}

If your application is in the HF frequency range, the LFRX and LFTX are recommended for up to 30 MHz of bandwidth per channel. The BasicRX and BasicTX are ideal for configurations that use an external frontend for tuning and filtering with either an IF or baseband interface.

The USRP X300 and X310 are backward compatible with legacy daughterboards except for the RFX Series and XCVR2450. Please note, while there are two daughterboard slots, the USRP X300/X310 can only support a single TVRX2.

If you plan to transmit or receive over the air, you should also purchase an antenna.

==Choosing a Host Interface==

The USRP X300/X310 provide 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 X300/X310. 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 ™ X300 and X310, 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 Table 3.

{| class="wikitable" style="margin: auto;"
!colspan="4"|Table 3 - Interface Performance Summary
|-
!Interface
!Throughput (MS/s @ 16-bit)
!Target
!Recommended Kit
|-
|1 Gigabit
|25 MS/s
|Desktop/Laptop
|Components provided with USRP X300/X310 kit.
For additional connections, purchase the following:
[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]
|-
|Express Card
(PCIe, 1 lane)
|50 MS/s
|Laptop
|[https://www.ettus.com/product/details/ECARD-KIT ExpressCard Kit]
|-
|}

[[File:Connectivity 2.png|700px|center]]

<center>Figure 2 - Host Interface Options</center>

===10 Gigabit Ethernet===
See [https://kb.ettus.com/Using_Dual_10_Gigabit_Ethernet_on_the_USRP_X300/X310 this app note] for how to use the X3x0 with dual 10 GbE links.

'''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 ]

==International Power Supply Options==
The power supply provided with the USRP X300/X310 kit is packaged with a power cord that is compatible with power outlets in the US/Japan. If you are not using the USRP X300/X310 in the US/Japan, we recommend purchasing the International USRP X300/X310 Power Cord set.

==Option: GPS Disciplined, Oven-Controlled Oscillator (GPSDO)==
The USRP X300 and USRP X310 provide the option to integrate 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.

{| class="wikitable" style="margin: auto;"
|
!Internal TCXO
!GPS-Disciplined Clock
|-
|Frequency Reference
|TCXO
|OCXO
|-
|Frequency Accuracy (unlocked)
|± 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**
|-
|}

==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: General Purpose Input/Output (GPIO) Kit==
The USRP X300 and X310 include a DB15 connector on the front panel that provides convenient access to GPIO signals. Each pin can be configured as an input or output, uses 3.3V-level logic, and is protected with basic anti-static circuitry. These pins can be used to control external devices like RF switches and amplifiers, trigger software events on the host, or even provide basic debugging functionality. The USRP GPIO Kit is an affordable option that provides access to these signals with a DB15 cable and a breakout board. The breakout board allows the user to connect external devices through a terminal block. The user can also solder wires and components into the dedicated prototyping area.

==Option: Cables for MIMO Expansion==
Multiple USRP X300/X310s 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>

==Option: USRP X300/X310 Rackmount==

The USRP X300 and X310 were designed to be used with a [https://www.ettus.com/all-products/rackmount-1u/ 1U Rackmount Assembly] for building high-density MIMO systems in a compact and well-organized setup. This mount supports one or two compatible USRPs, and if two are mounted then there are rubber standoffs between the USRPs to avoid both direct contact and surface scratching. If the user will be developing in a laboratory environment or building a high-channel count USRP system, then a 1U Rackmount Assembly is highly recommended. This specific mount is compatible with only the USRP X300 and X310, and allows the integration of up to four bidirectional -- or eight receive-only -- RF channels per 1U.

==Guidance on SFP+ Adapters for Fiber Connectivity on USRP X300/X310==

Ettus Research currently offers direct-connect, copper cabling accessories for the USRP X300 and USRP X310. However, it is also possible to use multi-mode fiber instead of copper connections for these devices.

The USRP X Series is compatible with most brands of SFP+ fiber adapters. In some cases, other equipment in the systems such as 1/10 Gigabith Ethernet switches are only compatible with specific brands of SFP+ adapters and cables. As a general rule, we recommend checking compatibility with the switches and network cards in your system before purchasing an adapter.

Ettus Research does test the USRP X Series devices with our [https://www.ettus.com/product/details/10GIGE-KIT 10 Gigabit Ethernet Connectivity Kit] and a Blade Networks G8124 1/10 GigE switch. Here are is a list of known-good cables and adapters.

Ettus Research has only tested multi-mode fiber accessories.

===Known-Good Adapters===
* [https://approvedoptics.com/blade-networks-bn-ckm-sp-sr/ Approved Optics Blade Networks BN-CKM-SP-SR-A]

===Known-Good Cables===
* [https://www.colfaxdirect.com/store/pc/viewPrd.asp?idproduct=995&idcategory=2 Myricom Fiber Cables for 10GBase-SR, 3 Meters 10G-SR-3M]

==Guidance on 10Gb SFP+ to RJ45 Adapters==

Many new motherboards come equipped with an onboard 10Gb RJ45 NIC. It is possible to use a SFP+ to RJ45 adapter and operate at 10Gb speeds using a Cat6/7 Ethernet cables.

Ettus Research has tested the adapters linked below.

===Known-Good Adapters===
* [https://www.amazon.com/10Gtek-SFP-10G-T-S-Compatible-10GBase-T-Transceiver/dp/B01KFBFL16/ 10Gtek SFP+ to RJ45 Copper Module]
* [https://www.prolabs.com/products/transceivers/brocade/sfpplus/100-1000-10000base/10g-sfpp-t-c ProLabs 10G-SFPP-T-C]

==FAQ==
USRP™ X300 and USRP™ X310 SDRs Frequently Asked Questions

* '''What is the bandwidth of the USRP X300/X310'''

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. The actual analog bandwidth may be reduced due the RF daughterboard selected.

RF Daughterboard Bandwidths: See the daughterboard specifications [link]

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 X300/X310, please see the "USRP X300/X310 Configuration Guide" or the "USRP System Bandwidth" application note.

* '''How can I program the USRP X300/X310'''

Like all other USRP models, the USRP X300 and X310 are compatible with the USRP Hardware Driver™ (UHD) architecture. The UHD architecture is a common driver that allows users to develop and execute applications on a host-PC. UHD provides a direct C++ API to control and stream to/from the USRP X300/X310. 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 here.

* '''How can I modify the FPGA of the USRP X300/X310'''

The source code (Verilog) for the USRP X300/X310 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 [[UHD]] Software Resource page.

* '''How much free space is available in the USRP X300/X310 FPGA'''

Please see the USRP X300/X310 FPGA resources page for more information.

* '''What type of PC setup is recommended for use with the USRP X300/X310'''

The type of PC required depends heavily on the complexity and bandwidth of the application. To demonstrate the USRP X300/X310, we typically use a desktop computer with a quadcore i7, 8+ GB of DDR3, and install the PCIe interface card that is also provide with the 10 GigE, PCIe, and ExpressCard interface kits.

* '''What frequency range does the USRP X300/X310 cover'''

The frequency range depends on the daughterboard select by the users. For more information, please see the USRP X300/X310 Configuration Guide.

* '''What components do I need to purchase for a complete USRP X300/X310 system'''

For a more comprehensive guide, please see the USRP X300/X310 Configuration Guide.

* '''What is the difference between the USRP X300/X310'''

The USRP X310 includes a larger Kintex-7 series FPGA (XC7K410T) with additional development resources for more complex designs. The USRP X300 includes the smaller XC7K325T FPGA.

* '''What is the part number of the X3xx power connector'''
Model: PDP-40 by CUI Inc.
Power plug connectors for custom power harnesses can be purchased here: https://www.digikey.com/products/en?KeyWords=CP-7340-ND&WT.z_cid=sp_102_buynow

[[Category:Hardware Resources]]

USRP N300/N310/N320/N321 Getting Started Guide

2022-03-28T10:19:44Z

MartinBraun: /* Updating the Network Configurations */

==Kit Contents==
===N300===
{|
|style="vertical-align:top"|
* USRP N300
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
||[[File:n300 kit.png|450px|center]]
|}
===N310===

{|
|style="vertical-align:top"|
* USRP N310
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
||[[File:n310 kit.png|500px|center]]
|}

===N320===

{|
|style="vertical-align:top"|
* USRP N320
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
|[[File:n320 kit.png|500px|center]]
|}

===N321===

{|
|style="vertical-align:top"|
* USRP N321
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
||[[File:n321 kit.png|500px|center]]
|}
==Verify the Contents of Your Kit==
Ensure that your kit contains all the items listed above. If any items are missing, please contact sales@ettus.com immediately.

==You Will Need==
* microSD Card Writer

* For Network Mode: A host computer with an available 1 or 10 Gigabit Ethernet interface for sample streaming. In addition to the Ethernet interface used for sampling streaming, your host computer will require a separate 1 Gigabit Ethernet interface for command and control streaming.

* For Stand-Alone Embedded Mode: A host computer with an available 1 Gigabit Ethernet port or a USB 2.0 port to remotely access the embedded Linux operating system running on ARM CPU.

==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 cause the device to become non-functional. Take the following precautions to 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 device.
* 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
|-
|}

==Install and Setup the Software Tools on Your Host Computer==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on your host computer. A step-by-step guide for doing this is available at 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.

To find the latest release of UHD, see the UHD repository at https://github.com/EttusResearch/uhd.

The USRP N310 requires UHD version 3.11.0.0 or later.

The USRP N300 requires UHD version 3.12.0.0 or later.

The USRP N320/N321 requires UHD version 3.14.0.0 or later.

White Rabbit Ethernet-Based Synchronization of the N3xx USRP requires UHD version 3.12.0.0 or later. For additional details on White Rabbit Ethernet-Based Synchronization, please see the application note, [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices]].

'''When you receive a brand-new device, it is strongly recommended that you download the most recent filesystem image from the Ettus Research website and write it to the SD card that comes with the unit. It is not recommended that you use the SD card from the factory as-is. Instructions on downloading the latest filesystem image and writing it to the SD card are listed below.'''

'''Note that if you are operating the device in Network Mode, the version of UHD running on the host computer and the USRP N3xx must match.'''

==Connecting the Device==
===Interfaces Overview===
Listed below are the interfaces to connect to the USRP N3xx. Each interface has specific functionality, limitations and purpose.

'''Serial Console'''

The Serial Console provides a low level interface to the device typically used for debugging.

'''1 Gigabit RJ45 Connection'''

The 1 Gigabit RJ45 Connection interfaces with the on-board ARM CPU. When operated in "Network mode", this interface can optionally be used for UHD management traffic. Regardless of the operation mode (Network vs Embedded) this interface can be used to connect to the ARM via SSH. By default, the 1Gb RJ45 connection is configured to use a DHCP assigned IP address.

'''Dual SFP+ Connections'''

The Dual SFP+ Connections support multiple configurations for streaming high-speed, low-latency data, depending upon the FPGA image which is loaded.

'''QSFP+ Connection (N320/ N321 Only)'''

The QSFP+ Connection supports 2 x 10Gb lanes for streaming high-speed, low-latency data, while the onboard SFP0 connection is used for White Rabbit Ethernet-Based Synchronization.

===Setting up a Serial Console Connection===
It is possible to gain shell access to the device using a serial terminal emulator via the Serial Console port. Most Linux, OSX, or other Unix based operating systems have a tool called <code>screen</code> which can be used for this purpose.

If you do not have <code>screen</code> installed, it can be installed via your package manager. For Ubuntu/Debian based operating systems it can be installed with <code>apt</code> such as:

sudo apt install screen

The default Baud Rate for the Serial Console is: <code>115200</code>

The exact device node you should attach to depends on your operating system's driver and other USB devices that might already be connected. Modern Linux systems offer alternatives to simply trying device nodes; instead, the OS might have a directory of symlinks under <code>/dev/serial/by-id</code>:

$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_25163511FE00-if00-port0
usb-Digilent_Digilent_USB_Device_25163511FE00-if01-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if00-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if01-port0

NOTE: Exact names depend on the host operating system version and may differ.

Every N3XX series device connected to USB will by default show up as four different devices. The devices labeled <code>"USB_to_UART_Bridge_Controller"</code> are the devices that offer a serial prompt. The first (with the <code>if00</code> suffix) connects to the <code>ARM CPU</code>, whereas the second connects to the <code>STM32 Microcontroller</code>.

If you have multiple N3xx Serial Consoles connected to a single host, you may have to empirically test nodes.

Connecting to the ARM CPU can be performed with the command:

$ sudo screen /dev/serial/by-id/usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if00-port0 115200

Upon starting the USRP N3xx, boot messages will appear and rapidly update. Once the boot process successfully completes, a login prompt like the following should appear:

OpenEmbedded test ni-n3xx-313ABDA ttyPS0

ni-n3xx-313ABDA login:

Enter the username: <code>root</code>

By default, the <code>root</code> user's password is left blank. Press the <code>Enter</code> key when prompted for a password.

You should now be presented with a shell prompt similar to the following:

root@ni-n3xx-<motherboard serial #>:~#

Using the default configuration, the serial console will show all kernel log messages (which are not available when using SSH), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or boot-loader issues more efficiently than when logged in via SSH.

====Connecting to the microcontroller====

Using the Serial Console interface, it is possible to connect to the STM32 microcontroller with the command below. The STM32 controls the power sequencing and several other low level device operations.

$ sudo screen /dev/serial/by-id/usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if01-port0 115200

The STM32 interface provides a very simple prompt. The command <code>help</code> will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it (i.e., emulating a power button press) and other low-level diagnostics.

===Connecting to the ARM via SSH===
By default, the RJ45 1Gb management interface is configured to be assigned a DHCP IP address.

If you have access to a network which provides a DHCP server (such as a common router's LAN), attach the RJ45 1Gb port to this network. Details vary by vendor, however, most router management interfaces will provide a list of attached devices to the LAN including their IP address.

Without access to a router management interface, you can identify the IP address by connecting to the ARM CPU via Serial Console as detailed in the section above and running the command <code>ip a</code>:

Example Output:

<pre>
# ip a
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast qlen 1000
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
inet 192.168.1.151/24 brd 192.168.1.255 scope global dynamic eth0
valid_lft 42865sec preferred_lft 42865sec
3: sfp0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 9000 qdisc pfifo_fast qlen 1000
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
inet 192.168.10.2/24 brd 192.168.10.255 scope global sfp0
valid_lft forever preferred_lft forever
4: sfp1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 9000 qdisc pfifo_fast qlen 1000
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
</pre>

If you do not have access to a network with a DHCP server, you can create one using the Linux utility <code>dnsmasq</code>:

$ sudo dnsmasq -i <ETHERNET_ADAPTER_NAME> --dhcp-range=192.168.1.151,192.168.1.254 --except-interface=lo --bind-dynamic --no-daemon

NOTE: Modify the value <code><ETHERNET_ADAPTER_NAME></code> to match the interface you would like to create a DHCP server on.

After the device has obtained an IP address, you can remotely log into it from a Linux or macOS system with SSH, as shown below:

$ ssh root@192.168.1.151

NOTE: The IP address may vary depending on your network setup.

NOTE: The <code>root</code> password default password is empty/blank.

On Microsoft Windows, the SSH connection can be established using the third-party program Putty.

After logging in, you should be presented with a shell like the following:

root@ni-n3xx-<motherboard serial #>:~#

==Updating the Linux File System==
Before operating the device, it is strongly recommended to update to the latest version of the Embedded Linux file system. If you are operating the device in Network Mode, the version of UHD running on the host machine and N3xx USRP must match.

There is two ways to update the file system for the N3xx USRP:

1. Mender

2. Physically remove microSD card from device and write a new file system to the microSD card.

===File System Partition Layout===
The SD Card is divided into four partitions. There is two root file system partitions, a boot partition and a data partition.

Any data you would like to preserve through Mender updates should be saved to the <code>data</code> partition, which is mounted at <code>/data</code>.

===Updating the file system with Mender===
Mender is third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website https://mender.io). Mender can be executed locally on the device, or a Mender server can be set up which can be used to remotely update an arbitrary number of USRP devices. Users can host their own local Mender server, or use servers hosted by Mender as a paid service; contact Mender for more information.

====Mender Update Process====
When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted. Any data stored in the root partitions will be permanently lost with a Mender update.

After updating a partition with Mender, it will reboot into the newly updated partition. Only if the update is confirmed by the user, the update will be made permanent. This means that if an update fails, the device will be always able to reboot into the partition from which the update was originally launched, which presumably is in a working state. Another update can be launched now to correct the previous, failed update, until it works.

To obtain the file system Mender image (these are files with a <code>.mender</code> suffix), run the following command on the host computer with Internet access:

$ sudo uhd_images_downloader -t mender -t n3xx --yes

Example Output:
[INFO] Images destination: /usr/local/share/uhd/images
451639 kB / 451639 kB (100%) n3xx_common_mender_default-v3.14.0.0.zip
[INFO] Images download complete.

NOTE: In the output of the command, the folder destination where the images are saved is printed out.

Next, you will need to copy this Mender file system image to the USRP N3xx. This can be done with the Linux utility <code>scp</code>.

$ scp /usr/local/share/uhd/images/usrp_n3xx_fs.mender root@192.168.1.51:~/.

Note: The path and IP may different for your configuration, the command above assumes you're using the default installation path of <code>/usr/local</code> and that the N3xx's IP is <code>192.168.1.51</code>.

After copying the Mender file system image to the N3xx, connect to the N3xx using either the Serial Console, or via SSH to gain shell access.

On the N3xx, run <code>mender install /path/to/latest.mender</code> to update the file system:

$ mender install /home/root/usrp_n3xx_fs.mender

The artifact can also be stored on a remote server:
$ mender install <nowiki>http://server.name/path/to/latest.mender</nowiki>

This procedure will take a few minutes to complete. After mender has logged a successful update, reboot the device:
$ reboot

If the reboot worked, and the device seems functional, commit the changes so that the boot loader knows to permanently boot into this partition:
$ mender -commit

To identify the currently installed Mender artifact from the command line, the following file can be queried on the N3xx:
$ cat /etc/mender/artifact_info

If you are using a Mender server, the updates can be initiated from a web dashboard. From there, you can start the updates without having to log into the device, and you can update groups of USRPs with a few clicks in a web GUI. The dashboard can also be used to inspect the state of USRPs. This is a simple way to update groups of rack-mounted USRPs with custom file systems.

For more information on updating the file-system, refer to the UHD Manual at https://uhd.ettus.com.

===Updating the files system by writing the disk image===
Please see the separate application note, [[Writing the USRP File System Disk Image to a SD Card]], for step-by-step instructions on writing the file system image to the SD card.

==Updating the Network Configurations==
The USRP N3xx systemd network configuration files are located at: <code>/data/network/</code>

# ls /data/network/
eth0.network int0.network sfp0.network sfp1.network

or for older version of the file system: <code>/data/network/</code>

# ls /etc/systemd/network/
eth0.network sfp0.network sfp1.network

For details on configuration please refer to the [https://www.freedesktop.org/software/systemd/man/systemd.network.html systemd-networkd manual pages].

The factory settings are as follows:
<pre>
eth0 (DHCP):

[Match]
Name=eth0

[Network]
DHCP=ipv4

[DHCP]
UseHostname=false

sfp0 (static):

[Match]
Name=sfp0

[Network]
Address=192.168.10.2/24

[Link]
MTUBytes=9000

sfp1 (static):

[Match]
Name=sfp1

[Network]
Address=192.168.20.2/24

[Link]
MTUBytes=9000
</pre>

Additional notes on networking:

* Care needs to be taken when editing these files on the device, since <code>vi</code> / <code>vim</code> sometimes generates undo files (e.g. <code>/etc/systemd/network/sfp0.network~</code>), that <code>systemd-networkd</code> might accidentally pick up.
* Temporarily setting the IP addresses or MTU sizes via <code>ifconfig</code> or other command line tools will only change the value until the next reboot or reload of the FPGA image.
* If the MTU of the device and host computers differ, streaming issues can occur.
* Streaming via SFP0 at 1 Gb rates requires a MTU of <code>1500</code>
* Streaming via SFP0 at 10 Gb rates requires a MTU of <code>9000</code>

For addition details on network configuration here: https://files.ettus.com/manual/page_usrp_n3xx.html#n3xx_network_configuration

==Updating the FPGA Image==

===Network Mode FPGA Image Update===
The FPGA image should match the version of UHD installed on the host computer, when operated in Network mode. Connect the device to the host computer using either the RJ45 or SFP+ port, refer to the section above for detailed instructions.

To obtain all the FPGA images for a specific version of UHD, run the following command on the host computer with internet access:

$ sudo uhd_images_downloader

Example Output:

$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19810 kB / 19810 kB (100%) x3xx_x310_fpga_default-gf1ba32fe.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02123 kB / 02123 kB (100%) n230_n230_fpga_default-ge57dfe0.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00491 kB / 00491 kB (100%) b2xx_b200_fpga_default-ge57dfe0.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
08988 kB / 08988 kB (100%) e3xx_e320_fpga_default-g3de8954a.zip
23045 kB / 23045 kB (100%) n3xx_n310_fpga_default-g3de8954a.zip
00523 kB / 00523 kB (100%) b2xx_b205mini_fpga_default-ge57dfe0.zip
18937 kB / 18937 kB (100%) x3xx_x300_fpga_default-gf1ba32fe.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00144 kB / 00144 kB (100%) b2xx_common_fw_default-ga69ab0c.zip
25107 kB / 25107 kB (100%) n3xx_n320_fpga_default-g3de8954a.zip
00464 kB / 00464 kB (100%) b2xx_b200mini_fpga_default-ge57dfe0.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
16065 kB / 16065 kB (100%) n3xx_n300_fpga_default-g3de8954a.zip
05578 kB / 05578 kB (100%) e3xx_e310_fpga_default-g4bc2c6f.zip
00885 kB / 00885 kB (100%) b2xx_b210_fpga_default-ge57dfe0.zip
[INFO] Images download complete.

NOTE: In the above example output, the Images Destination folder is printed:

[INFO] Images destination: /usr/local/share/uhd/images

To list the N3xx FPGA images with a full path, run the command:

$ ls -w 1 /usr/local/share/uhd/images/usrp_n3*.bit

/usr/local/share/uhd/images/usrp_n300_fpga_AA.bit
/usr/local/share/uhd/images/usrp_n300_fpga_HG.bit
/usr/local/share/uhd/images/usrp_n300_fpga_WX.bit
/usr/local/share/uhd/images/usrp_n300_fpga_XG.bit
/usr/local/share/uhd/images/usrp_n310_fpga_AA.bit
/usr/local/share/uhd/images/usrp_n310_fpga_HG.bit
/usr/local/share/uhd/images/usrp_n310_fpga_WX.bit
/usr/local/share/uhd/images/usrp_n310_fpga_XG.bit
/usr/local/share/uhd/images/usrp_n320_fpga_AQ.bit
/usr/local/share/uhd/images/usrp_n320_fpga_HG.bit
/usr/local/share/uhd/images/usrp_n320_fpga_WX.bit
/usr/local/share/uhd/images/usrp_n320_fpga_XG.bit
/usr/local/share/uhd/images/usrp_n320_fpga_XQ.bit

To update the default <code>HG</code> variant of FPGA image, run the command:

$ uhd_image_loader --args "type=n3xx,addr=<N3xx_IP_ADDR>,fpga=HG"

Example Output:

uhd_image_loader --args "type=n3xx,addr=192.168.1.151,fpga=HG"
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.11.1.HEAD-0-gad6b0935
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.1.151,type=n3xx,product=n310,serial=313ABDA,claimed=False,skip_init=1
[INFO] [MPM.main] Launching USRP/MPM, version: 3.11.1.0-gunknown
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[INFO] [MPMD] Claimed device without full initialization.
[INFO] [MPMD IMAGE LOADER] Starting update. This may take a while.
[INFO] [MPM.PeriphManager] Updating component `fpga'
[INFO] [MPM.PeriphManager] Updating component `dts'
[INFO] [MPM.RPCServer] Resetting peripheral manager.
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.

To load a different default FPGA image (i.e. <code>XG</code>, <code>WG</code>), modify the device argument <code>fpga=</code> to a value of <code>fpga=XG</code> or <code>fpga=WG</code>.

To specify the path to a custom FPGA image, use the <code>--fpga-path</code> argument.

$ uhd_image_loader --args "type=n3xx,addr=<N3xx_IP_ADDR>" --fpga-path=/path/to/custom/fpga.bit

The Verilog code for the FPGA in the USRP N3xx 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. 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.

===Embedded Mode FPGA Image Update===

It is possible to update the FPGA image when operated in Embedded mode. Connect to the ARM CPU via Serial Console or SSH as detailed in the section above.

Updating the FPGA image from the ARM CPU is the same as detailed above for a Network mode update, except it is not required to provide an <code>addr</code> device argument.

uhd_image_loader --args "type=n3xx,fpga=HG"

<pre>
root@ni-n3xx-313ABDA:~# uhd_image_loader --args "type=n3xx,fpga=HG"
[INFO] [UHD] linux; GNU C++ version 7.2.0; Boost_106400; UHD_3.11.1.0-0-unknown
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=127.0.0.1,type=n3xx,product=n310,serial=313ABDA,claimed=False,skip_init=1
[INFO] [MPMD] Claimed device without full initialization.
[INFO] [MPMD IMAGE LOADER] Starting update. This may take a while.
[INFO] [MPM.PeriphManager] Updating component `fpga'
[INFO] [MPM.PeriphManager] Updating component `dts'
[INFO] [MPM.RPCServer] Resetting peripheral manager.
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.
</pre>

For more information on updating the FPGA image, refer to the UHD Manual at http://uhd.ettus.com .

==Setting Up a Streaming Connection==
The device supports multiple, high-speed, low-latency interfaces on the SFP+ ports for streaming samples to the host computer.

===1Gb Streaming SFP Port 0===
Complete the steps below to set up a streaming connection over the 1 Gigabit Ethernet interface on <code>SFP Port 0</code>.

When streaming via SFP Port 0 at 1 Gb speeds, it is important that the connection is direct between the Host and USRP. Placing a switch or other network gear between the Host and USRP can reduce throughput of the transport link. It is also generally recommended to avoid using USB to Ethernet Adapters for the high speed streaming interface, as they may limit performance or cause periodic flow control errors.

NOTE: The <code>HG</code> FPGA image must be loaded for <code>SFP Port 0</code> to operate at 1Gb speeds. If the <code>XG</code> image is loaded, the port will be unresponsive at 1Gb speeds.

1. Configure your Host's Ethernet adapter as shown below. This interface should be separate from the 1Gb NIC/network which is connected to the 1Gb RJ45 management interface.

IP Address: 192.168.10.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 1500

NOTE: When operating <code>SFP Port 0</code> at 1Gb speeds, it is important to set a MTU of <code>1500</code> and not a value of <code>automatic</code>.

2. Insert the RJ45 – SFP+ adapter into <code>SFP Port 0</code> .

3. Connect the adapter to a host computer using the Ethernet cable to SFP0.

The Green LED above <code>SFP Port 0</code> should illuminate.

4. To test the connection, <code>ping</code> the device at address <code>192.168.10.2</code> from the host, as shown
below:

$ ping 192.168.10.2
PING 192.168.10.2 (192.168.10.2) 56(84) bytes of data.
64 bytes from 192.168.10.2: icmp_seq=1 ttl=64 time=1.06 ms
^C
--- 192.168.10.2 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 1.065/1.065/1.065/0.000 ms

Press <code>CTRL+C</code> to stop the ping program.

Proceed to the next section "Verifying Device Operation".

===10Gb Streaming SFP Port 1===
Complete the steps below to set up a streaming connection over the 10 Gigabit Ethernet interface on <code>SFP Port 1</code>.

NOTE: Both the <code>HG</code> and <code>XG</code> FPGA images support 10Gb speeds over SFP Port 1.

1. Configure your Host's 10Gb Ethernet adapter as shown below.

IP Address: 192.168.20.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 9000

NOTE: When operating at 10Gb speeds, it is important to set a MTU of <code>9000</code> and not a value of <code>automatic</code>.

2. Connect the USRP to a host computer using either a 10Gb SFP or Fiber cable to <code>SFP Port 1</code>.

The Green LED above <code>SFP Port 1</code> should illuminate.

3. To test the connection, <code>ping</code> the device at address <code>192.168.20.2</code> from the host, as shown
below:

$ ping 192.168.20.2

Press <code>CTRL+C</code> to stop the ping program.

Proceed to the next section "Verifying Device Operation".

===Dual 10Gb Streaming SFP Ports 0/1===
Complete the steps below to set up a streaming connections over the Dual 10 Gigabit Ethernet interface on <code>SFP Ports 0/1</code>.

NOTE: The <code>XG</code> FPGA image must be loaded for <code>SFP Port 0</code> to operate at 10 Gb speeds. If the <code>HG</code> image is loaded, the port will be unresponsive at 10 Gb speeds.

1. Configure your Host's #1 10Gb Ethernet adapter as shown below.

IP Address: 192.168.10.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 9000

2. Configure your Host's #2 10Gb Ethernet adapter as shown below.

IP Address: 192.168.20.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 9000

NOTE: When operating at 10Gb speeds, it is important to set a MTU of <code>9000</code> and not a value of <code>automatic</code>.

3. Connect the USRP to a host computer using either a 10Gb SFP or Fiber cables to <code>SFP Ports 0/1</code>.

The Green LEDs above <code>SFP Ports 0/1</code> should illuminate.

4. To test the <code>SFP Port 0</code> connection, <code>ping</code> the device at address <code>192.168.10.2</code> from the host, as shown below:

$ ping 192.168.10.2

Press <code>CTRL+C</code> to stop the ping program.

5. To test the <code>SFP Port 1</code> connection, <code>ping</code> the device at address <code>192.168.20.2</code> from the host, as shown below:

$ ping 192.168.20.2

Press <code>CTRL+C</code> to stop the ping program.

Proceed to the next section "Verifying Device Operation".

For more details on Network Setup and Configuration, please see the “Interfaces and Connectivity” section on the [[N300/N310]] or [[N320/N321]] hardware resources pages.

==Verifying Device Operation==
Once you have successfully setup a management interface and streaming interface, you can now verify the devices operation using the included UHD utilities.

===Subdevice Specification Mapping===
====N300====
The USRP N300 contains 2 channels, each represented on the front panel as <code>RF0-1</code>. Below is the <code>subdev</code> mapping of RF Ports.

* RF0 = A:0
* RF1 = A:1

====N310====
The USRP N310 contains 4 channels, each represented on the front panel as <code>RF0-3</code>. Below is the <code>subdev</code> mapping of RF Ports.

=====UHD 3.11.x.x - 3.12.x.x=====
* RF0 = A:0
* RF1 = B:0
* RF2 = C:0
* RF3 = D:0

=====UHD 3.13.x.x+=====
* RF0 = A:0
* RF1 = A:1
* RF2 = B:0
* RF3 = B:1

====N320====
The USRP N320 contains 2 channels, each represented on the front panel as <code>RF0-1</code>. Below is the <code>subdev</code> mapping of RF Ports.

* RF0 = A:0
* RF1 = B:0

====N321====
The USRP N321 contains 2 channels, each represented on the front panel as <code>RF0-1</code>. Below is the <code>subdev</code> mapping of RF Ports.

* RF0 = A:0
* RF1 = B:0

Additional details of UHD Subdevice Specifications can be found here in the UHD Manual: http://files.ettus.com/manual/page_configuration.html#config_subdev

===Supported Sample Rates===

The USRP N300/N310 supports the three fixed Master Clock Rates listed below.

* 122.88 MHz
* 125.00 MHz
* 153.60 MHz

The USRP N320/N321 supports the three fixed Master Clock Rates listed below.

* 200.00 MHz
* 245.76 MHz
* 250.00 MHz

Sample rates as delivered to/from the host computer for USRP devices are constrained to follow several important rules.

It is important to understand that strictly-integer decimation and interpolation are used within USRP hardware to meet the requested sample rate requirements of the application at hand. That means that the desired sample rate must meet the requirement that master-clock-rate/desired-sample-rate be an integer ratio. Further, it is strongly desirable for that ratio to be even. This ratio is the decimation (down-conversion) or interpolation (up-conversion) factor. The decimation or interpolation factor may be between 1 and 1024. There are further constraints on the decimation or interpolation factor. If the decimation or interpolation factor exceeds 128, then it must be evenly divisible by 2. If the decimation or interpolation factor exceeds 256, then it must be evenly divisible by 4.

====Example Sample Rates====
Listed below are common sample rates for the given master clock rates. This is not a complete listing of the supported sample rates.

{| class="wikitable"
!Master Clock Rate
!colspan="20"|Decimation / Interpolation Rate <br> Host Sample Rate [Msps]
|-

|style="text-align:center;"| 1
|style="text-align:center;"| 2
|style="text-align:center;"| 4
|style="text-align:center;"| 6
|style="text-align:center;"| 8
|style="text-align:center;"| 10
|style="text-align:center;"| 12
|style="text-align:center;"| 14
|style="text-align:center;"| 16
|style="text-align:center;"| 18
|style="text-align:center;"| 20
|style="text-align:center;"| 30
|style="text-align:center;"| 32
|style="text-align:center;"| 64
|style="text-align:center;"| 100
|style="text-align:center;"| 128
|style="text-align:center;"| 200
|style="text-align:center;"| 256
|style="text-align:center;"| 512
|style="text-align:center;"| 1024
|-

|style="text-align:center;"| 122.88e6
|style="text-align:center;"| 61.44e6
|style="text-align:center;"| 30.72e6
|style="text-align:center;"| 20.48e6
|style="text-align:center;"| 15.36e6
|style="text-align:center;"| 12.288e6
|style="text-align:center;"| 10.24e6
|style="text-align:center;"| 8.7771e6
|style="text-align:center;"| 7.68e6
|style="text-align:center;"| 6.8267e6
|style="text-align:center;"| 6.144e6
|style="text-align:center;"| 4.096e6
|style="text-align:center;"| 3.84e6
|style="text-align:center;"| 1.92e6
|style="text-align:center;"| 1.2288e6
|style="text-align:center;"| 960e3
|style="text-align:center;"| 614.4e3
|style="text-align:center;"| 480e3
|style="text-align:center;"| 240e3
|style="text-align:center;"| 120e3
|-

|style="text-align:center;"| 125e6
|style="text-align:center;"| 62.5e6
|style="text-align:center;"| 31.25e6
|style="text-align:center;"| 20.833e6
|style="text-align:center;"| 15.625e6
|style="text-align:center;"| 12.5e6
|style="text-align:center;"| 10.417e6
|style="text-align:center;"| 8.9286e6
|style="text-align:center;"| 7.8125e6
|style="text-align:center;"| 6.9444e6
|style="text-align:center;"| 6.25e6
|style="text-align:center;"| 4.1667e6
|style="text-align:center;"| 3.90625e6
|style="text-align:center;"| 1.953125e6
|style="text-align:center;"| 1.25e6
|style="text-align:center;"| 976.5625e3
|style="text-align:center;"| 625e3
|style="text-align:center;"| 488.28125e3
|style="text-align:center;"| 244.14e3
|style="text-align:center;"| 122.07e3

|-

|style="text-align:center;"| 153.6e6
|style="text-align:center;"| 76.8e6
|style="text-align:center;"| 38.4e6
|style="text-align:center;"| 25.6e6
|style="text-align:center;"| 19.2e6
|style="text-align:center;"| 15.36e6
|style="text-align:center;"| 12.8e6
|style="text-align:center;"| 10.971e6
|style="text-align:center;"| 9.6e6
|style="text-align:center;"| 8.5333e6
|style="text-align:center;"| 7.68e6
|style="text-align:center;"| 5.12e6
|style="text-align:center;"| 4.8e6
|style="text-align:center;"| 2.4e6
|style="text-align:center;"| 1.536e6
|style="text-align:center;"| 1.2e6
|style="text-align:center;"| 768e3
|style="text-align:center;"| 600e3
|style="text-align:center;"| 300e3
|style="text-align:center;"| 150e3

|-

|}

====N320/N321 Example Sample Rates====
Listed below are common sample rates for the given master clock rates. This is not a complete listing of the supported sample rates.

{| class="wikitable"
!Master Clock Rate
!colspan="20"|Decimation / Interpolation Rate <br> Host Sample Rate [Msps]
|-

|style="text-align:center;"| 1
|style="text-align:center;"| 2
|style="text-align:center;"| 4
|style="text-align:center;"| 6
|style="text-align:center;"| 8
|style="text-align:center;"| 10
|style="text-align:center;"| 12
|style="text-align:center;"| 14
|style="text-align:center;"| 16
|style="text-align:center;"| 18
|style="text-align:center;"| 20
|style="text-align:center;"| 30
|style="text-align:center;"| 32
|style="text-align:center;"| 64
|style="text-align:center;"| 100
|style="text-align:center;"| 128
|style="text-align:center;"| 200
|style="text-align:center;"| 256
|style="text-align:center;"| 512
|style="text-align:center;"| 1024
|-

|style="text-align:center;"| 200e6
|style="text-align:center;"| 100e6
|style="text-align:center;"| 50e6
|style="text-align:center;"| 33.33e6
|style="text-align:center;"| 25e6
|style="text-align:center;"| 20e6
|style="text-align:center;"| 16.66e6
|style="text-align:center;"| 14.2857e6
|style="text-align:center;"| 12.5e6
|style="text-align:center;"| 11.11e6
|style="text-align:center;"| 10e6
|style="text-align:center;"| 6.667e6
|style="text-align:center;"| 6.25e6
|style="text-align:center;"| 3.125e6
|style="text-align:center;"| 2e6
|style="text-align:center;"| 1.5625e6
|style="text-align:center;"| 1e6
|style="text-align:center;"| 781.25e3
|style="text-align:center;"| 390.625e3
|style="text-align:center;"| 195.3125e3

|-

|style="text-align:center;"| 245.76e6
|style="text-align:center;"| 122.88e6
|style="text-align:center;"| 61.44e6
|style="text-align:center;"| 30.72e6
|style="text-align:center;"| 20.48e6
|style="text-align:center;"| 15.36e6
|style="text-align:center;"| 12.288e6
|style="text-align:center;"| 10.24e6
|style="text-align:center;"| 8.7771e6
|style="text-align:center;"| 7.68e6
|style="text-align:center;"| 6.8267e6
|style="text-align:center;"| 6.144e6
|style="text-align:center;"| 4.096e6
|style="text-align:center;"| 3.84e6
|style="text-align:center;"| 1.92e6
|style="text-align:center;"| 1.2288e6
|style="text-align:center;"| 960e3
|style="text-align:center;"| 614.4e3
|style="text-align:center;"| 480e3
|style="text-align:center;"| 240e3
|-

|style="text-align:center;"| 250e6
|style="text-align:center;"| 125e6
|style="text-align:center;"| 62.5e6
|style="text-align:center;"| 31.25e6
|style="text-align:center;"| 20.833e6
|style="text-align:center;"| 15.625e6
|style="text-align:center;"| 12.5e6
|style="text-align:center;"| 10.417e6
|style="text-align:center;"| 8.9286e6
|style="text-align:center;"| 7.8125e6
|style="text-align:center;"| 6.9444e6
|style="text-align:center;"| 6.25e6
|style="text-align:center;"| 4.1667e6
|style="text-align:center;"| 3.90625e6
|style="text-align:center;"| 1.953125e6
|style="text-align:center;"| 1.25e6
|style="text-align:center;"| 976.5625e3
|style="text-align:center;"| 625e3
|style="text-align:center;"| 488.28125e3
|style="text-align:center;"| 244.14e3

|-

|}

Additional information on Sample Rates can be found here in the UHD Manual: http://files.ettus.com/manual/page_general.html#general_sampleratenotes

===Probe the USRP===

====N300/N310====
The UHD utility <code>uhd_usrp_probe</code> provides detailed information of the USRP device.

From your host computer, run the command <code>uhd_usrp_probe</code>:

<pre>
$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.HEAD-0-ga0a71d10
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.10.2,type=n3xx,product=n310,serial=313ABDA,claimed=False,addr=192.168.10.2
[INFO] [MPM.main] Launching USRP/MPM, version: 3.13.1.0-gd3b7e90a
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Initialized 2 daughterboard(s).
[INFO] [MPM.PeriphManager] init() called with device args `time_source=internal,clock_source=internal'.
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000004)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1355 MB/s)
[INFO] [MPM.PeriphManager] init() called with device args `mgmt_addr=192.168.10.2,clock_source=internal,time_source=internal,product=n310'.
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1358 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1355 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1345 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000002)
_____________________________________________________
/
| Device: N300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-n3xx-313ABDA
| | eeprom_version: 1
| | mpm_version: 3.13.1.0-gd3b7e90a
| | pid: 16962
| | product: n310
| | rev: 3
| | rpc_connection: remote
| | serial: 313ABDA
| | type: n3xx
| | MPM Version: 1.2
| | FPGA Version: 5.2
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo, sfp0
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_tpv, ref_locked, gps_time, gps_locked, temp, gps_sky, fan
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: AD9371 Dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: AD9371 Dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: AD9371 Dual DAC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: AD9371 Dual DAC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1

</pre>

====N320====

<pre>

$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106600; UHD_3.14.0.0-0-g6875d061
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=127.0.0.1,type=n3xx,product=n320,serial=3181FFA,claimed=False
[INFO] [MPM.main] Launching USRP/MPM, version: 3.14.0.0-g6875d061
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 3181FFA
[INFO] [MPM.Rhodium-0] Successfully loaded all peripherals!
[INFO] [MPM.Rhodium-1] Successfully loaded all peripherals!
[INFO] [MPM.PeriphManager] Initialized 2 daughterboard(s).
[INFO] [MPM.PeriphManager] No QSFP board detected: Assuming it is disabled in the device tree overlay (e.g., HG, XG images).
[INFO] [MPM.PeriphManager] init() called with device args `time_source=internal,clock_source=internal'.
[INFO] [MPM.Rhodium-0] init() called with args `time_source=internal,clock_source=internal'
[INFO] [MPM.Rhodium-1] init() called with args `time_source=internal,clock_source=internal'
[INFO] [MPM.Rhodium-0.init.LMK04828] LMK initialized and locked!
[INFO] [MPM.Rhodium-1.init.LMK04828] LMK initialized and locked!
[INFO] [MPM.Rhodium-1.DAC37J82] DAC PLL Locked!
[INFO] [MPM.Rhodium-1.AD9695] ADC PLL Locked!
[INFO] [MPM.Rhodium-1.init] JESD204B Link Initialization & Training Complete
[INFO] [MPM.Rhodium-0.DAC37J82] DAC PLL Locked!
[INFO] [MPM.Rhodium-0.AD9695] ADC PLL Locked!
[INFO] [MPM.Rhodium-0.init] JESD204B Link Initialization & Training Complete
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [MPM.PeriphManager] init() called with device args `mgmt_addr=127.0.0.1,clock_source=internal,time_source=internal,product=n320'.
[INFO] [MPM.Rhodium-0] init() called with args `mgmt_addr=127.0.0.1,clock_source=internal,time_source=internal,product=n320'
[INFO] [MPM.Rhodium-1] init() called with args `mgmt_addr=127.0.0.1,clock_source=internal,time_source=internal,product=n320'
[INFO] [0/Replay_0] Initializing block control (NOC ID: 0x4E91A00000000004)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/FIFO_0] Initializing block control (NOC ID: 0xF1F0000000000000)
[INFO] [0/FIFO_1] Initializing block control (NOC ID: 0xF1F0000000000000)
_____________________________________________________
/
| Device: N300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-n3xx-3181FFA
| | eeprom_version: 2
| | mpm_version: 3.14.0.0-g6875d061
| | pid: 16962
| | product: n320
| | rev: 6
| | rpc_connection: local
| | serial: 3181FFA
| | type: n3xx
| | MPM Version: 1.2
| | FPGA Version: 5.3
| | FPGA git hash: 3de8954.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo, sfp0
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_tpv, temp, gps_sky, fan, gps_time, gps_locked, ref_locked, gps_gpgga
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 3175A79
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 3175A67
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 3175A79
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 3175A67
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * Replay_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1
| | | * FIFO_0
| | | * FIFO_1

</pre>

====N321====

<pre>
$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 7.3.1 20180712 (Red Hat 7.3.1-6); Boost_106400; UHD_3.14.0.0-0-g6875d061
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.20.2,type=n3xx,product=n320,serial=3166646,claimed=False,addr=192.168.20.2
[INFO] [MPM.PeriphManager] init() called with device args `time_source=internal,clock_source=internal,product=n320,mgmt_addr=192.168.20.2'.
[INFO] [MPM.Rhodium-0] init() called with args `time_source=internal,clock_source=internal,product=n320,mgmt_addr=192.168.20.2'
[INFO] [MPM.Rhodium-1] init() called with args `time_source=internal,clock_source=internal,product=n320,mgmt_addr=192.168.20.2'
[INFO] [0/Replay_0] Initializing block control (NOC ID: 0x4E91A00000000004)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/FIFO_0] Initializing block control (NOC ID: 0xF1F0000000000000)
[INFO] [0/FIFO_1] Initializing block control (NOC ID: 0xF1F0000000000000)
_____________________________________________________
/
| Device: N300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-n3xx-3166646
| | eeprom_version: 2
| | mpm_version: 3.14.0.0-g6875d061
| | pid: 16962
| | product: n320
| | rev: 6
| | rpc_connection: remote
| | serial: 3166646
| | type: n3xx
| | MPM Version: 1.2
| | FPGA Version: 5.3
| | FPGA git hash: 3de8954.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo, sfp0
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_sky, gps_time, gps_gpgga, gps_locked, fan, gps_tpv, ref_locked, temp
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 316D814
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 316D810
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 316D814
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 316D810
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * Replay_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1
| | | * FIFO_0
| | | * FIFO_1

</pre>

If you see warnings such as:

[WARNING] [UDP] The recv buffer could not be resized sufficiently.

You need to resize the socket buffers for your network interface card:

sudo sysctl -w net.core.rmem_max=288000
sudo sysctl -w net.core.wmem_max=288000
sudo sysctl -w net.core.rmem_max=33554432

===ASCII Art Example===
The UHD driver includes several example programs, which may serve as test programs or the basis for your application program. The source code can be obtained from the UHD repository on github at: https://github.com/EttusResearch/uhd/tree/master/host/examples

You can quickly verify the operation of your USRP N3xx by running the <code>rx_ascii_art_dft</code> UHD example program.

The <code>rx_ascii_art_dft</code> utility is a simple console based, real-time FFT display tool. It is not graphical in nature, so it can be easily run over an SSH connection within a terminal window, and does not need any graphical capability, such as X Windows, to be installed. It can also be run over a serial console connection, although this is not recommended, as the formatting may not render correctly.

You can run a simple test of the N3xx USRP by connecting an antenna and observing the spectrum of a commercial FM radio station in real-time, following the steps below:

1. Attach an antenna to the <code>Ch0/RX2</code> antenna port of the N3xx.

2. From your host computer, run the command:

'''N300/N310'''
<pre>
$ /usr/local/lib/uhd/examples/rx_ascii_art_dft --args "master_clock_rate=125e6,mgmt_addr=192.168.1.151,addr=192.168.10.2" --freq 98.5e6 --rate 2.5e6 --gain 50 --ref-lvl="-50" --dyn-rng 90 --ant "RX2" --subdev "A:0"
</pre>

'''N320/N321'''
<pre>
$ /usr/local/lib/uhd/examples/rx_ascii_art_dft --args "master_clock_rate=250e6,mgmt_addr=192.168.1.151,addr=192.168.10.2" --freq 98.5e6 --rate 2.5e6 --gain 50 --ref-lvl="-50" --dyn-rng 90 --ant "RX2" --subdev "A:0"
</pre>

NOTE: Modify the command line argument <code>freq</code> above to specify a tuning frequency for a strong local FM radio station. You will also need to update the IP Address to match your device IP.

3. You should see a real-time FFT display of 2.5 MHz of spectrum, centered at the specified tuning frequency.

4. Type "<code>Q</code>" or <code>Ctrl-C</code> to stop the program and to return to the Linux command line.

5. You can run with the <code>--help</code> argument to see a description of all available command-line options.

Example Output:

<pre>
$ /usr/local/lib/uhd/examples/rx_ascii_art_dft --args "master_clock_rate=125e6,mgmt_addr=192.168.1.151,addr=192.168.10.2" --freq 98.5e6 --rate 2.5e6 --gain 50 --ref-lvl="-50" --dyn-rng 90 --ant "RX2" --subdev "A:0"

Creating the usrp device with: master_clock_rate=125e6,mgmt_addr=192.168.1.151,addr=192.168.10.2...
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.11.1.HEAD-0-gad6b0935
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.1.151,type=n3xx,product=n310,serial=313ABDA,claimed=False,master_clock_rate=125e6,addr=192.168.10.2
[INFO] [MPM.main] Launching USRP/MPM, version: 3.11.1.0-gunknown
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [MPM.PeriphManager] init() called with device args `mgmt_addr=192.168.1.151,product=n310,master_clock_rate=125e6'.
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000004)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1336 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1338 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1346 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1350 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/Radio_2] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/Radio_3] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_2] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_3] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_2] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_3] Initializing block control (NOC ID: 0xD0C0000000000000)
Using Device: Single USRP:
Device: N300-Series Device
Mboard 0: ni-n3xx-313ABDA
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: Magnesium
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: Magnesium
TX Channel: 1
TX DSP: 0
TX Dboard: B
TX Subdev: Magnesium
TX Channel: 2
TX DSP: 0
TX Dboard: C
TX Subdev: Magnesium
TX Channel: 3
TX DSP: 0
TX Dboard: D
TX Subdev: Magnesium

Setting RX Rate: 2.500000 Msps...
Actual RX Rate: 2.500000 Msps...

Setting RX Freq: 98.500000 MHz...
Actual RX Freq: 98.500000 MHz...

Setting RX Gain: 50.000000 dB...
Actual RX Gain: 50.000000 dB...

Checking RX: all_los: locked ...

Done!
</pre>

===Benchmarking your system===
Included with the UHD driver example programs is a utility, <code>benchmark_rate</code> to benchmark the transport link of the system.

A system's maximum performance is dependent upon many factors. <code>benchmark_rate</code> will exercise the transport link and CPU of the system.

====1 Gb Interface====
NOTE: This example requires the <code>HG</code> FPGA image to be loaded.

'''N300/N310'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 3.84 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,master_clock_rate=122.88e6" \
--duration 60 \
--channels "0" \
--rx_rate 3.84e6 \
--rx_subdev "A:0" \
--tx_rate 3.84e6 \
--tx_subdev "A:0"

'''N310'''

This example will test four full-duplex streams at 1.25 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,master_clock_rate=125e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 1.25e6 \
--rx_subdev "A:0 A:1 B:0 B:1" \
--tx_rate 1.25e6 \
--tx_subdev "A:0 A:1 B:0 B:1"

'''N320/N321'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 3.84 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,master_clock_rate=245.76e6" \
--duration 60 \
--channels "0" \
--rx_rate 3.84e6 \
--rx_subdev "A:0" \
--tx_rate 3.84e6 \
--tx_subdev "A:0"

When streaming samples over a 1 Gb transport link, the maximum accumulative rate for all channels is 25 MS/s with a <code>sc16</code> OTW format. To achieve higher streaming rates, it is recommended to use the 10 Gb interfaces.

====10 Gb Interface SFP 1====
NOTE: This example will work with either the <code>HG</code> or <code>XG</code> FPGA image.

'''N300/N310'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 31.25 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=125e6" \
--duration 60 \
--channels "0" \
--rx_rate 31.25e6 \
--rx_subdev "A:0" \
--tx_rate 31.25e6 \
--tx_subdev "A:0"

'''N320/N321'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 31.25 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=250e6" \
--duration 60 \
--channels "0" \
--rx_rate 31.25e6 \
--rx_subdev "A:0" \
--tx_rate 31.25e6 \
--tx_subdev "A:0"

'''N310'''

This example will test four full-duplex streams at 30.72 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=122.88e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 30.72e6 \
--rx_subdev "A:0 A:1 B:0 B:1" \
--tx_rate 30.72e6 \
--tx_subdev "A:0 A:1 B:0 B:1"

'''N320/N321'''

This example will test two full-duplex streams at 30.72 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=245.76e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 30.72e6 \
--rx_subdev "A:0 B:0" \
--tx_rate 30.72e6 \
--tx_subdev "A:0 B:0"

====Dual 10 Gb Interface====
NOTE: This example requires the <code>XG</code> FPGA image to be loaded.

'''N310'''

This example will test four full-duplex streams at 62.5 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,second_addr=192.168.20.2,master_clock_rate=125e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 62.5e6 \
--rx_subdev "A:0 A:1 B:0 B:1" \
--tx_rate 62.5e6 \
--tx_subdev "A:0 A:1 B:0 B:1"

'''N320/N321'''

This example will test two full-duplex streams at 62.5 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,second_addr=192.168.20.2,master_clock_rate=250e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 62.5e6 \
--rx_subdev "A:0 B:0" \
--tx_rate 62.5e6 \
--tx_subdev "A:0 B:0"

==USRP N3xx Device Specific Operations==

===White Rabbit Ethernet-Based Synchronization===
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices]]

===N320/N321===
* [[USRP N320/N321 LO Distribution]]
* [[5G NR EVM Measurements with the USRP N320/N321]]

===Turning the Device Off/On===
To avoid damaging the file system and causing any corruption, do not turn the device off with the power button without first shutting down the system. Use this command to cleanly and properly shut the system down:

shutdown -h now

===Enable Auto Booting===
Auto booting of the N3xx when power is applied can be configured by enabling the flag on the device's EEPROM with the following command:

eeprom-set-flags 0x1

===Default Password===
The default user is <code>root</code> and the password is empty (no password).

It is recommended to update the <code>root</code> password, which can be done with the command <code>passwd</code>:

Example Output:

root@ni-n3xx-serial:~# passwd
Changing password for root
New password:
Re-enter new password:
passwd: password changed.

==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], or by phone at +14086106399 (Monday-Friday, 8 AM - 5 PM, Pacific Time). 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

[[Category:Getting Started Guides]]
[[Category:N300]]
[[Category:N310]]

[[Category:N320]]

[[Category:N321]]

Using the RFNoC Replay Block in UHD 4

2022-03-01T16:10:08Z

MartinBraun:

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

An introduction to RFNoC with UHD 4.0 and above can be found [[Getting_Started_with_RFNoC_in_UHD_4.0|here]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Insert the appropriate device args for your device, e.g.

uhd_usrp_probe --args type=x4xx,addr=192.168.30.2

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to load
an FPGA image which includes this block. See [[#building_fpga|this section]] for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
By default, we expose the entire memory of the device, but it is possible to modify
<code>axi_intercon_2x64_128_bd</code> if less memory should be made accessible.

Devices have the following amount of memory:
{|
|E310
|512 MiB
|-
|E320
|2 GiB
|-
|N3xx
|2 GiB
|-
|X310
|1 GiB
|-
|X410
|4 GiB per bank (note: not all banks may be connected)
|}

The currently available memory can be queried using the block controller and the
<code>get_mem_size()</code> API call.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing Back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. Playback can be stopped by issuing
a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory Alignment and Word Sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per DRAM transaction. For most configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size. The word size can go up to 512 bits.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay should fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

<span id="building_fpga">
==Building Custom FPGA Images with a Replay Block==
</span>

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location <code>~/src/uhd</code>.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

===Building the FPGA===

'''Note:''' Most bitfiles already include the replay block! This section is
only relevant if you want to build your own bitfile, or the bitfile you're using
does not contain the replay block already.

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2
MEM_ADDR_W: 30

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram }
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section. The blocks contain two parameters, NUM_PORTS, and MEM_ADDR_W. The former is the number of ports this RFNoC block may have. The latter is the width of the memory address word, i.e., it is log2(memory_size).
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

All devices have limits regarding the number of ports and the memory size. The following values may not be exceeded:

<pre>
E310:
NUM_PORTS: 2
MEM_ADDR_W: 29
E320:
NUM_PORTS: 4
MEM_ADDR_W: 31
N3xx:
NUM_PORTS: 4
MEM_ADDR_W: 31
X310:
NUM_PORTS: 2
MEM_ADDR_W: 30
X410:
NUM_PORTS: 4
MEM_ADDR_W: 32
</pre>

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml [ --fpga-dir ~/usr/uhd/fpga ]

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Using the RFNoC Replay Block in UHD 4

2022-03-01T12:19:04Z

MartinBraun:

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

An introduction to RFNoC with UHD 4.0 and above can be found [[Getting_Started_with_RFNoC_in_UHD_4.0|here]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Insert the appropriate device args for your device, e.g.

uhd_usrp_probe --args type=x4xx,addr=192.168.30.2

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to load
an FPGA image which includes this block. See [[#building_fpga|this section]] for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
By default, we expose the entire memory of the device, but it is possible to modify
<code>axi_intercon_2x64_128_bd</code> if less memory should be made accessible.

Devices have the following amount of memory:
{|
|E310
|512 MiB
|-
|E320
|2 GiB
|-
|N3xx
|2 GiB
|-
|X310
|1 GiB
|-
|X410
|4 GiB per bank (note: not all banks may be connected)
|}

The currently available memory can be queried using the block controller and the
<code>get_mem_size()</code> API call.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing Back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. Playback can be stopped by issuing
a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory Alignment and Word Sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per DRAM transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

<span id="building_fpga">
==Building Custom FPGA Images with a Replay Block==
</span>

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location <code>~/src/uhd</code>.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

===Building the FPGA===

'''Note:''' Most bitfiles already include the replay block! This section is
only relevant if you want to build your own bitfile, or the bitfile you're using
does not contain the replay block already.

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2
MEM_ADDR_W: 30

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram }
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section. The blocks contain two parameters, NUM_PORTS, and MEM_ADDR_W. The former is the number of ports this RFNoC block may have. The latter is the width of the memory address word, i.e., it is log2(memory_size).
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

All devices have limits regarding the number of ports and the memory size. The following values may not be exceeded:

<pre>
E310:
NUM_PORTS: 2
MEM_ADDR_W: 29
E320:
NUM_PORTS: 4
MEM_ADDR_W: 31
N3xx:
NUM_PORTS: 4
MEM_ADDR_W: 31
X310:
NUM_PORTS: 2
MEM_ADDR_W: 30
X410:
NUM_PORTS: 4
MEM_ADDR_W: 32
</pre>

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml [ --fpga-dir ~/usr/uhd/fpga ]

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Using the RFNoC Replay Block in UHD 4

2022-03-01T12:16:31Z

MartinBraun: /* Building the FPGA */

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

An introduction to RFNoC with UHD 4.0 and above can be found [[Getting_Started_with_RFNoC_in_UHD_4.0|here]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Insert the appropriate device args for your device, e.g.

uhd_usrp_probe --args type=x4xx,addr=192.168.30.2

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to load
an FPGA image which includes this block. See ... for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
By default, we expose the entire memory of the device, but it is possible to modify
<code>axi_intercon_2x64_128_bd</code> if less memory should be made accessible.

Devices have the following amount of memory:
{|
|E310
|512 MiB
|-
|E320
|2 GiB
|-
|N3xx
|2 GiB
|-
|X310
|1 GiB
|-
|X410
|4 GiB per bank (note: not all banks may be connected)
|}

The currently available memory can be queried using the block controller and the
<code>get_mem_size()</code> API call.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing Back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. Playback can be stopped by issuing
a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory Alignment and Word Sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per DRAM transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

==Building Custom FPGA Images with a Replay Block==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location <code>~/src/uhd</code>.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

<span id="building_fpga">==Building the FPGA==</span>

'''Note:''' Most bitfiles already include the replay block! This section is
only relevant if you want to build your own bitfile, or the bitfile you're using
does not contain the replay block already.

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2
MEM_ADDR_W: 30

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram }
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section. The blocks contain two parameters, NUM_PORTS, and MEM_ADDR_W. The former is the number of ports this RFNoC block may have. The latter is the width of the memory address word, i.e., it is log2(memory_size).
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

All devices have limits regarding the number of ports and the memory size. The following values may not be exceeded:

<pre>
E310:
NUM_PORTS: 2
MEM_ADDR_W: 29
E320:
NUM_PORTS: 4
MEM_ADDR_W: 31
N3xx:
NUM_PORTS: 4
MEM_ADDR_W: 31
X310:
NUM_PORTS: 2
MEM_ADDR_W: 30
X410:
NUM_PORTS: 4
MEM_ADDR_W: 32
</pre>

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml [ --fpga-dir ~/usr/uhd/fpga ]

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Using the RFNoC Replay Block in UHD 4

2022-03-01T12:12:51Z

MartinBraun:

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

An introduction to RFNoC with UHD 4.0 and above can be found [[Getting_Started_with_RFNoC_in_UHD_4.0|here]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Insert the appropriate device args for your device, e.g.

uhd_usrp_probe --args type=x4xx,addr=192.168.30.2

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to load
an FPGA image which includes this block. See ... for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
By default, we expose the entire memory of the device, but it is possible to modify
<code>axi_intercon_2x64_128_bd</code> if less memory should be made accessible.

Devices have the following amount of memory:
{|
|E310
|512 MiB
|-
|E320
|2 GiB
|-
|N3xx
|2 GiB
|-
|X310
|1 GiB
|-
|X410
|4 GiB per bank (note: not all banks may be connected)
|}

The currently available memory can be queried using the block controller and the
<code>get_mem_size()</code> API call.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing Back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. Playback can be stopped by issuing
a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory Alignment and Word Sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per DRAM transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

==Building Custom FPGA Images with a Replay Block==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location <code>~/src/uhd</code>.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

==Building the FPGA==

'''Note:''' Most bitfiles already include the replay block! This section is
only relevant if you want to build your own bitfile, or the bitfile you're using
does not contain the replay block already.

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2
MEM_ADDR_W: 30

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram }
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section. The blocks contain two parameters, NUM_PORTS, and MEM_ADDR_W. The former is the number of ports this RFNoC block may have. The latter is the width of the memory address word, i.e., it is log2(memory_size).
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

All devices have limits regarding the number of ports and the memory size. The following values may not be exceeded:

<pre>
E310:
NUM_PORTS: 2
MEM_ADDR_W: 29
E320:
NUM_PORTS: 4
MEM_ADDR_W: 31
N3xx:
NUM_PORTS: 4
MEM_ADDR_W: 31
X310:
NUM_PORTS: 2
MEM_ADDR_W: 30
X410:
NUM_PORTS: 4
MEM_ADDR_W: 32
</pre>

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml [ --fpga-dir ~/usr/uhd/fpga ]

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Using the RFNoC Replay Block in UHD 4

2022-03-01T11:54:53Z

MartinBraun: MartinBraun moved page Using the RFNoC Replay Block 4.0 to Using the RFNoC Replay Block 4

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

An introduction to RFNoC with UHD 4.0 and above can be found [[Getting_Started_with_RFNoC_in_UHD_4.0|here]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to build and load
an FPGA image which includes this block. See ... for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
For example, the <code>axi_intercon_2x64_128_bd</code> IP used by the X310 is
configured to give each connected device an address space of 32 MiB. As a
result, the Replay block will be limited to this amount of memory. The
<code>axi_intercon_2x64_128_bd</code> file must be modified if more than 32 MiB needs to be buffered.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing Back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. The <code>num_samps</code>
parameter is a 28-bit value, limiting this mode of playback to 2<sup>28</sup>
words at a time. Playback can be stopped by issuing a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory Alignment and Word Sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per DRAM transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

==Building Custom FPGA Images with a Replay Block==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location <code>~/src/uhd</code>.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

==Building the FPGA==

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2
MEM_ADDR_W: 30

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram }
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section.
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Using the RFNoC Replay Block 4.0

2022-03-01T11:54:53Z

MartinBraun: MartinBraun moved page Using the RFNoC Replay Block 4.0 to Using the RFNoC Replay Block 4

#REDIRECT [[Using the RFNoC Replay Block 4]]

UHD Python API

2022-02-10T08:59:49Z

MartinBraun: /* FAQ */

== What's the UHD Python API? ==

As the name suggests, it exposes the UHD API into Python. We use <code>pybind11</code>
to generate a Python module which exposes most of the C++ API, and some extra
features. The Python API is part of stable releases.

The USRP Hardware Driver and USRP Manual covers most information about the UHD Python API and can be found here: https://files.ettus.com/manual/page_python.html

== How can I use it? ==

In order to test the Python API, check out the <code>master</code> branch and build it like always. When running CMake, make sure that the Python API was enabled (<code>-DENABLE_PYTHON_API=ON</code>).

The output from CMake should look something like this:

<pre>
-- ######################################################
-- # UHD enabled components
-- ######################################################
-- * LibUHD
-- * LibUHD - C API
-- * LibUHD - Python API
-- * Examples
-- * Utils
-- * Tests
-- * USB
-- * B100
-- * B200
-- * USRP1
-- * USRP2
-- * X300
-- * N230
-- * OctoClock
-- * Manual
-- * API/Doxygen
-- * Man Pages
--
-- ######################################################
-- # UHD disabled components
-- ######################################################
-- * GPSD
-- * E100
-- * E300
</pre>

Please refer to the [https://files.ettus.com/manual/page_python.html USRP Manual] for extended instructions especially when installing on Windows.
Once it's built and installed, you'll be able to import the <code>uhd</code> Python
module.

<syntaxhighlight lang="python">
>>> import uhd
>>> my_usrp = uhd.usrp.MultiUSRP("type=b200")
>>> my_usrp.set_rx_gain(70)
</syntaxhighlight>

We have some examples in <code>[https://github.com/EttusResearch/uhd/tree/master/host/examples/python host/examples/python]</code>. The examples are very
simple, but concise.

==Example: pyuhd_rx_to_file.py==
This Python example is based on the C++ example <code>uhd/host/examples/rx_samples_to_file.cpp</code>.

<syntaxhighlight lang="python">
import uhd
import numpy as np
import argparse

def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("-a", "--args", default="", type=str)
parser.add_argument("-o", "--output-file", type=str, required=True)
parser.add_argument("-f", "--freq", type=float, required=True)
parser.add_argument("-r", "--rate", default=1e6, type=float)
parser.add_argument("-d", "--duration", default=5.0, type=float)
parser.add_argument("-c", "--channels", default=0, nargs="+", type=int)
parser.add_argument("-g", "--gain", type=int, default=10)
return parser.parse_args()

def main():
args = parse_args()
usrp = uhd.usrp.MultiUSRP(args.args)
num_samps = int(np.ceil(args.duration*args.rate))
if not isinstance(args.channels, list):
args.channels = [args.channels]
samps = usrp.recv_num_samps(num_samps, args.freq, args.rate, args.channels, args.gain)
with open(args.output_file, 'wb') as f:
np.save(f, samps, allow_pickle=False, fix_imports=False)

if __name__ == "__main__":
main()
</syntaxhighlight>

== What about documentation? ==

Documentation is currently pretty sparse. The best we can do right now is to ask
users to infer the documentation from the C++ API. For example, the Python has
an object called <code>MultiUSRP</code> which is an equivalent of the C++ <code>multi_usrp</code> API.
The methods on both classes are the same, and take the same arguments.

==FAQ==
'''Does it support Python 2 and 3?'''

Starting with UHD 4, Python 2 support has been removed.

'''Does it require GNU Radio?'''

No.

'''Does it use SWIG?'''

No, it uses <code>pybind11</code>. It also doesn't require the C API. Pybind11 is vendored with UHD so as to not require installing another dependency.

'''How does this relate to the Python API in gr-uhd?'''

It serves an entirely different purpose. This Python API is for people writing standalone applications for USRPs that *don't* use GNU Radio. <code>gr-uhd</code> is staying the way it is, and is going nowhere. If you're using GNU Radio, you probably don't care about this.

'''Are the UHD Python API and the gr-uhd Python API compatible?'''

Short answer: No. Long answer: There are very few cases where it makes sense to mix these APIs, so no. However, this means that a <code>TimeSpec</code> from the <code>Boost.Python</code> API is not convertible into a <code>time_spec_t</code> from the <code>gr-uhd</code> API.

'''Does it support RFNoC API?'''

For sure!

'''What's the streaming performance?'''

Worse than straight C++, but not a lot, thanks to NumPy. You can run <code>host/examples/benchmark_rate.py</code> if you want to see for yourself.
Overall, <code>recv()</code> calls are pretty efficient if you've pre-allocated a NumPy array, because we can cast that to a straight pointer (and also skip any type checking!) and then it's not that different from a <code>recv()</code> call in a C++ app. However, consuming the data is limited by how fast you can handle that in Python.

UHD Python API

2022-02-10T08:08:06Z

MartinBraun:

== What's the UHD Python API? ==

As the name suggests, it exposes the UHD API into Python. We use <code>pybind11</code>
to generate a Python module which exposes most of the C++ API, and some extra
features. The Python API is part of stable releases.

The USRP Hardware Driver and USRP Manual covers most information about the UHD Python API and can be found here: https://files.ettus.com/manual/page_python.html

== How can I use it? ==

In order to test the Python API, check out the <code>master</code> branch and build it like always. When running CMake, make sure that the Python API was enabled (<code>-DENABLE_PYTHON_API=ON</code>).

The output from CMake should look something like this:

<pre>
-- ######################################################
-- # UHD enabled components
-- ######################################################
-- * LibUHD
-- * LibUHD - C API
-- * LibUHD - Python API
-- * Examples
-- * Utils
-- * Tests
-- * USB
-- * B100
-- * B200
-- * USRP1
-- * USRP2
-- * X300
-- * N230
-- * OctoClock
-- * Manual
-- * API/Doxygen
-- * Man Pages
--
-- ######################################################
-- # UHD disabled components
-- ######################################################
-- * GPSD
-- * E100
-- * E300
</pre>

Please refer to the [https://files.ettus.com/manual/page_python.html USRP Manual] for extended instructions especially when installing on Windows.
Once it's built and installed, you'll be able to import the <code>uhd</code> Python
module.

<syntaxhighlight lang="python">
>>> import uhd
>>> my_usrp = uhd.usrp.MultiUSRP("type=b200")
>>> my_usrp.set_rx_gain(70)
</syntaxhighlight>

We have some examples in <code>[https://github.com/EttusResearch/uhd/tree/master/host/examples/python host/examples/python]</code>. The examples are very
simple, but concise.

==Example: pyuhd_rx_to_file.py==
This Python example is based on the C++ example <code>uhd/host/examples/rx_samples_to_file.cpp</code>.

<syntaxhighlight lang="python">
import uhd
import numpy as np
import argparse

def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("-a", "--args", default="", type=str)
parser.add_argument("-o", "--output-file", type=str, required=True)
parser.add_argument("-f", "--freq", type=float, required=True)
parser.add_argument("-r", "--rate", default=1e6, type=float)
parser.add_argument("-d", "--duration", default=5.0, type=float)
parser.add_argument("-c", "--channels", default=0, nargs="+", type=int)
parser.add_argument("-g", "--gain", type=int, default=10)
return parser.parse_args()

def main():
args = parse_args()
usrp = uhd.usrp.MultiUSRP(args.args)
num_samps = int(np.ceil(args.duration*args.rate))
if not isinstance(args.channels, list):
args.channels = [args.channels]
samps = usrp.recv_num_samps(num_samps, args.freq, args.rate, args.channels, args.gain)
with open(args.output_file, 'wb') as f:
np.save(f, samps, allow_pickle=False, fix_imports=False)

if __name__ == "__main__":
main()
</syntaxhighlight>

== What about documentation? ==

Documentation is currently pretty sparse. The best we can do right now is to ask
users to infer the documentation from the C++ API. For example, the Python has
an object called <code>MultiUSRP</code> which is an equivalent of the C++ <code>multi_usrp</code> API.
The methods on both classes are the same, and take the same arguments.

==FAQ==
'''Does it support Python 2 and 3?'''

Yes.

'''Does it require GNU Radio?'''

No.

'''Does it use SWIG?'''

No, it uses <code>Boost.Python</code>. We didn't want to add another dependency to UHD (i.e., SWIG) and Boost was already a dependency of UHD. It also doesn't require the C API.

'''How does this relate to the Python API in gr-uhd?'''

It serves an entirely different purpose. This Python API is for people writing standalone applications for USRPs that *don't* use GNU Radio. <code>gr-uhd</code> is staying the way it is, and is going nowhere. If you're using GNU Radio, you probably don't care about this.

'''Are the UHD Python API and the gr-uhd Python API compatible?'''

Short answer: No. Long answer: There are very few cases where it makes sense to mix these APIs, so no. However, this means that a <code>TimeSpec</code> from the <code>Boost.Python</code> API is not convertible into a <code>time_spec_t</code> from the <code>gr-uhd</code> API.

'''When will it be released?'''

It is currently on <code>master</code> branch, and will become part of the next major release.

'''Does it support RFNoC API?'''

Not yet, but it's in the pipeline. We wanted to get the basics (i.e. <code>multi_usrp</code> API) right first.

'''What's the streaming performance?'''

Worse than straight C++, but not a lot, thanks to NumPy. You can run <code>host/examples/benchmark_rate.py</code> if you want to see for yourself.
Overall, <code>recv()</code> calls are pretty efficient if you've preallocated a NumPy array, because we can cast that to a straight pointer (and also skip any type checking!) and then it's not that different from a <code>recv()</code> call in a C++ app. However, consuming the data is limited by how fast you can handle that in Python.

Knowledge Base

2022-02-07T15:29:03Z

MartinBraun: /* Software Resources */

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|<i class="fa fa-road"></i> 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]]
* [[USRP X410 Getting Started Guide|X410]]

'''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]]
* [[Getting Started with DPDK and UHD|DPDK]]

</div>
<div class="col-1-3">

== [[Hardware Resources|<i class="fa fa-cogs"></i> 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|<i class="fa fa-desktop"></i> Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[Getting_Started_with_RFNoC_in_UHD_4.0|RFNoC (UHD 4.x)]]
* [[RFNoC]] (UHD 3.x)

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

'''Reference Architectures'''
* [[Open Architecture For Radar and EW Research]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual|<i class="fa fa-flag"></i> UHD and USRP User Manual]] ==
'''Software'''
* [http://files.ettus.com/manual/ UHD Manual (master)]
* [https://files.ettus.com/manual_archive/ UHD Manual Archive (previous releases)]

'''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_n3xx.html N300/N310/N320/N321]
* [http://files.ettus.com/manual/page_usrp_e3xx.html E310/E312/E313/E320]

'''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]
* [http://files.ettus.com/manual/page_dboards.html#dboards_twinrx TwinRX]

'''Other'''
* [http://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes|<i class="fa fa-file-text-o"></i> 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|<i class="fa fa-book"></i> 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|<i class="fa fa-life-ring"></i> Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Slack|Slack]]
* [[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|<i class="fa fa-info-circle"></i> FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]

</div>
<div class="col-1-3">

== [[Legacy Products| <i class="fa fa-hourglass-end"></i> Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

Knowledge Base

2022-02-07T15:28:15Z

MartinBraun: /* Software Resources */

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|<i class="fa fa-road"></i> 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]]
* [[USRP X410 Getting Started Guide|X410]]

'''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]]
* [[Getting Started with DPDK and UHD|DPDK]]

</div>
<div class="col-1-3">

== [[Hardware Resources|<i class="fa fa-cogs"></i> 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|<i class="fa fa-desktop"></i> Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[RFNoC]] (UHD 3.0)

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

'''Reference Architectures'''
* [[Open Architecture For Radar and EW Research]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual|<i class="fa fa-flag"></i> UHD and USRP User Manual]] ==
'''Software'''
* [http://files.ettus.com/manual/ UHD Manual (master)]
* [https://files.ettus.com/manual_archive/ UHD Manual Archive (previous releases)]

'''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_n3xx.html N300/N310/N320/N321]
* [http://files.ettus.com/manual/page_usrp_e3xx.html E310/E312/E313/E320]

'''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]
* [http://files.ettus.com/manual/page_dboards.html#dboards_twinrx TwinRX]

'''Other'''
* [http://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes|<i class="fa fa-file-text-o"></i> 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|<i class="fa fa-book"></i> 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|<i class="fa fa-life-ring"></i> Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Slack|Slack]]
* [[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|<i class="fa fa-info-circle"></i> FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]

</div>
<div class="col-1-3">

== [[Legacy Products| <i class="fa fa-hourglass-end"></i> Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

RFNoC

2022-02-07T15:27:33Z

MartinBraun: MartinBraun moved page RFNoC to RFNoC (UHD 3.0)

#REDIRECT [[RFNoC (UHD 3.0)]]

RFNoC (UHD 3.0)

2022-02-07T15:27:32Z

MartinBraun: MartinBraun moved page RFNoC to RFNoC (UHD 3.0)

==Overview==
{|
|style="vertical-align:top; width: 60%;"|RFNoC is a network-distributed heterogeneous processing tool with a focus on enabling FPGA processing in USRP devices. It allows you to move data on and off of an FPGA in a transparent way, thus enabling seamless use of both host-based and FPGA-based processing in an application. It provides a way to leverage FPGA processing capabilities and IP in your application which can scale across multiple FPGAs and devices across a network.

Signal processing algorithms are contained modules known as "Computation Engines" or "RFNoC Blocks", and an interface wrapper is provided to encapsulate existing or external IP to use with RFNoC. This allows you to import Xilinx™ CoreGen™ IP blocks, for example, and use them immediately in your RFNoC application. The internals of a RFNoC block are wholly independent from any other block, and can be designed with any tool that supports AXI stream interfaces, including VHDL, Verilog, and Xilinx™ Vivado™ HLS.

We are quickly building out the library of ready-to-use RFNoC blocks and already have many available, including the blocks necessary for an OFDM stack (e.g., detection, synchronization, equalizer, packet demodulator).

RFNoC is integrated with the UHD™ software, and all USRP devices from the third-generation on (X300 Series, E300 Series) are supported by RFNoC out-of-the-box. Like UHD, RFNoC is also Free and Open Source Software (LGPL), and the full source code can be found in our public code repositories.
||[[File:rfnoc.png|250px]]
|}

==Framework and Data Flow Example==
Below is a figure of the RFNoC stack.

[[File:rfnoc_stack.png|650px]]

The example below shows basic data flow of an RFNoC application. While this shows one possible data flow, there are many possible combinations from Host block to FPGA block, FPGA block to Host block, Host to Host, FPGA to FPGA, etc.

[[File:gr_rfnoc_ex1.png|650px]]

==Supported Devices==
* E310/E312
* E320
* X300/X310
* N300/N310/N320/N321

==Sample of Available Blocks==
*FIFO
*FFT
*FIR
*fosphor (real-time spectrum analyzer)
*Decimator (Keep 1 in N)
*Log Power Calculator
*Radio Interface
*Vector IIR (moving average)
*Window multiplier (for FFT)
*OFDM: Burst detection + synchronization, equalizer, packet demodulator
*and [https://github.com/EttusResearch/fpga/tree/maint/usrp3/lib/rfnoc more...]

==RFNoC FAQs==
===FPGA===
====What is the purpose of the rb_stb signal on NoC Shell?====
When writing or reading a settings register in a RFNoC block, the block receives a command packet (with the register address / value to write as the payload) and sends out a response packet. The response packet acknowledges the command packet and includes readback data as the payload. In the write case, the readback data is usually discarded. In the read case, the readback data payload will be the value of the register read in the block.

The signal <code>rb_stb</code>, called readback strobe, is used to control the the output of the response packet. After receiving a command packet, Noc Shell’s command packet processor will not output a response packet unless <code>rb_stb</code> is asserted. This functionality can be used to throttle the reception of command packets / settings register read/writes.

Most blocks should keep <code>rb_stb</code> asserted. Note, the <code>rb_stb</code> bit width is as wide as the number of block ports in use. For example, a two block port RFNoC block should set <code>rb_stb</code> to <code>2’b11</code>, otherwise a command packet timeout will occur.

===UHD===
====Why do I have a command timeout error?====
Error message example:

<pre>RuntimeError: EnvironmentError: IOError: 0/FIR_0 user_reg_read64() failed: EnvironmentError: IOError: [0/FIR_0] sr_read64() failed: EnvironmentError: IOError: Block ctrl (CE_04_Port_70) no response packet - AssertionError: bool(buff)
in uint64_t ctrl_iface_impl::wait_for_ack(bool)
at /home/ettus/src/uhd/host/lib/rfnoc/ctrl_iface.cpp:205</pre>

<ul>
<li>Check <code>ce_clk</code> / <code>ce_rst</code> are correctly connected in <code>rfnoc_ce_auto_inst_<device>.v</code> file where <code><device></code> is <code>x300</code>, <code>x310</code>, or <code>e310</code>.</li>
<li>Check block is correctly connected to the crossbar. Generally this is only an issue if manually connecting RFNoC block’s signals to the crossbar.</li>
<li>Check if Noc Shell’s <code>rb_stb</code> signal is properly asserted. Note, <code>rb_stb</code> bit width must be as wide as the number of block ports in use, i.e. if using 2 block ports, <code>rb_stb</code> must be <code>2’b11</code>.</li>
<li>RFNoC block is using timed commands (<code>USE_TIMED_CMDS</code>) with Noc Shell and the command FIFO depth parameter (<code>CMD_FIFO_SIZE</code>) on Noc Shell is too small. UHD will issue up to 64 commands at once, so set <code>CMD_FIFO_SIZE</code> to at least <code>8</code>.</li>
</ul>

===GNU Radio===
====When do I use an RFNoC FIFO in my flowgraph and which kind if any?====

An '''RFNoC FIFO''' is needed in your flowgraph in the following 2 conditions:

First, if you are running a GNU Radio flowgraph that is structured as follows:

<code>Host block -> RFNoC block -> Host block</code>

In this case, you need to do either:

<code>Host block -> RFNoC FIFO -> RFNoC Block -> Host block</code>

-OR-

<code>Host block -> RFNoC Block -> RFNoC FIFO -> Host block</code>

The order doesn't matter. This structure also benefits from having the [http://gnuradio.org/redmine/projects/gnuradio/wiki/Guided_Tutorial_GRC#243-A-Note-on-the-Throttle-Block GNU Radio Throttle block] in the sequence. The reason behind the need to add the FIFO is because of performance inside of GNU Radio, so that the RX/TX work functions in the GNU Radio RFNoC block implementations run in separate threads.

Use <code>RFNoC: FIFO</code> (<code>AXI_FIFO_LOOPBACK</code>) in this case. See the following figure as an example.

[[File:fifo_v01.png|650px]]

Second, in the case where you are transmitting out to the antenna on the X3xx series devices, i.e.

<code>Host -> DmaFIFO -> Radio</code>

-OR-

<code>Host -> DmaFIFO -> DUC -> Radio</code>

Ethernet introduces a latency in flow control from the X3x0 back to the host. The latency will cause underruns unless a large buffer, i.e. <code>DMA_FIFO</code>, is added to the flowgraph.

Use <code>RFNoC: DmaFIFO</code> (<code>AXI_DMA_FIFO</code>) in this case. See the following figures as examples.

[[File:dma_fifo_v01.png|650px]]

-OR-

[[File:dma_fifo_v02.png|650px]]

====Splitting an RFNoC Data Stream in GNU Radio====

'''Copy Block:''' In the RFNoC domain, streams of data can not be split as easily as they are in the GNU Radio domain. The <code>Copy</code> block depicted in the screenshot below serves the function as a stream splitter at the FPGA-Host boundary. It’s main purpose, when <code>Enabled</code>, 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 <code>Copy</code> 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 <code>RFNoC: Split Stream</code> block, which would split the streams in the RFNoC domain, but this is not very useful here as we are moving into the GNURadio-domain.

[[File:rfnoc_ddc.grc_v02.png|650px]]

====What is the difference between USRP Sink/Source blocks and the RFNoC:Radio block?====

The USRP Source and Sink blocks use the <code>multi_usrp</code> API, whereas the <code>RFNoC:Radio</code> block uses the RFNoC API. In general, unless RFNoC features are desired, there is no need to use the <code>RFNoC:Radio</code> block. The <code>RFNoC:Radio</code> block is most useful when its output is connected directly to another RFNoC block. Below is a list of differences as well as a GRC screenshot to help differentiate between the two blocks.

Distinctions:
* The USRP Source/Sink blocks work with any version of UHD, and does not require <code>gr-ettus</code>. The <code>gr-ettus</code> Out-Of-Tree GNU Radio module is currently needed to use any RFNoC Blocks. This requirement will be removed as more RFNoC components are migrated into UHD.
* The USRP Source/Sink blocks include a superset of the not only the components of an <code>RFNoC:Radio</code>, but also <code>DDC/DUC</code> chains, and the <code>DRAM FIFO</code> (specific to X3xx series). When using the <code>RFNoC:Radio</code> block, the <code>DDC/DUC</code> blocks need to be added explicitly. See the figure below.
* When using the USRP Source/Sink blocks, it is not possible to connect to any RFNoC blocks.
* USRP Source/Sink blocks can only be used when using a <code>multi_usrp</code> API FPGA image (when looking in the USRP FPGA images directory they are the images without the term “RFNOC” in them), or an FPGA image that includes <code>RFNoC:Radio</code> and <code>RFNoC:DDC/DUC</code> blocks.

'''NOTE:''' The RFNOC:DmaFIFO block is only needed for the X3xx series devices.
[[File:rfnocRadio_uhdSinkSource_grc_v07.png|650px]]

===Tools===
====Xilinx License: Xilinx’s License manager looks for an Ethernet adapter with the name eth0...====

'''Problem:''' The Xilinx Vivado License Manager looks for an Ethernet adapter with the name <code>eth0</code>, but Ubuntu 16.04 and later now use a persistent naming scheme, with interface names such as (e.g. <code>np6s0, enp4s0, enp2s0f0, enp2s0f1, enx00ef5c620935</code>).

'''Solution:''' Rename the ethernet adapter to <code>eth0</code>.

Create this file:
<code>70-persistent-net.rules</code> in this <code>/etc/udev/rules.d/</code> directory
And adding the following line to the file (substitute <code>xx:xx:xx:xx:xx:xx</code> for the MAC address of the Ethernet adapter):

SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="xx:xx:xx:xx:xx:xx", ATTR{dev_id}=="0x0", ATTR{type}=="1", NAME="eth0"

Ubuntu information:

http://askubuntu.com/questions/767786/changing-network-interfaces-name-ubuntu-16-04

Xilinx information:

https://www.xilinx.com/support/answers/60510.html

==Licensing==
* [[Licensing FAQ]]

==RFNoC Resources==
*[[Getting_Started_with_RFNoC_Development|Getting Started with RFNoC Development]]
*[https://drive.google.com/file/d/0B6ccrJyAZaq3MTRDbmVUR0gwVU0/view GNU Radio 2016 Conference Presentation]
*[https://www.youtube.com/watch?v=8cPd3t88djE Virginia Tech Video Presentation]
*[https://kb.ettus.com/images/e/eb/RFNoC_Wireless_at_VirginiaTech_2014_Intro.pdf Virginia Tech Presentation - Introduction to RFNoC]
*[https://kb.ettus.com/images/1/1e/RFNoC_Wireless_at_VirginiaTech_2014_Host.pdf Virginia Tech Presentation - RFNoC Deep Dive: Host Side]
*[https://kb.ettus.com/images/7/78/RFNoC_Wireless_at_VirginiaTech_2014_FPGA.pdf Virginia Tech Presentation - RFNoC Deep Dive: FPGA]
*[https://conferences.sigcomm.org/sigcomm/2013/papers/srif/p45.pdf sigcom 2013 Paper]

[[Category:Software Resources]]

Using the RFNoC Replay Block in UHD 4

2022-02-07T15:19:16Z

MartinBraun:

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

An introduction to RFNoC with UHD 4.0 and above can be found [[Getting_Started_with_RFNoC_in_UHD_4.0|here]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to build and load
an FPGA image which includes this block. See ... for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
For example, the <code>axi_intercon_2x64_128_bd</code> IP used by the X310 is
configured to give each connected device an address space of 32 MiB. As a
result, the Replay block will be limited to this amount of memory. The
<code>axi_intercon_2x64_128_bd</code> file must be modified if more than 32 MiB needs to be buffered.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. The <code>num_samps</code>
parameter is a 28-bit value, limiting this mode of playback to 2<sup>28</sup>
words at a time. Playback can be stopped by issuing a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory alignment and word sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

==Building Custom FPGA Images with a Replay Block==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location ~/src/uhd.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

==Building the FPGA==

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram } MEM_ADDR_W: 30
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section.
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Getting Started with RFNoC in UHD 4.0

2022-02-07T15:18:11Z

MartinBraun: /* Streaming Example */

==Application Note Number and Authors==
'''AN-400''' by Sugandha Gupta, Brent Stapleton, Wade Fife, and Michael Dickens


==Abstract==
This guide describes how to get started with FPGA and Software development for RF Network-on-Chip (RFNoC™). It gives a brief introduction to RFNoC and explains the steps needed to generate, build, and use custom RFNoC images and introduces the process for creating and integrating new RFNoC IP blocks.


==Intended Audience==
This guide is written for hardware and software engineers who want to use the RF Network-on-Chip (RFNoC™) architecture or want to develop intellectual property (IP) using the RFNoC architecture. For more details on the architecture please refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

This guide assumes that you have some basic familiarity with USRPs, such as connecting them, configuring your network interfaces, etc., so that your USRP is ready for use. See the [https://kb.ettus.com/Getting_Started_Guides Getting Started Guide] for your USRP if you are just getting started with USRPs.

==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). RFNoC is available under the open-source GNU Lesser General Public License (LGPL). For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Prerequisites==
RFNoC is currently supported on the USRP X410 series, and all the Generation-3 USRPs in the X series (X3xx), E series (E3xx) and N series (N3xx). For details on the hardware, software, and process required to build custom USRP FPGA images that include RFNoC blocks, see the [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP Build Documentation] in the UHD and USRP Manual.

It is recommended that you learn how to build an FPGA image for your USRP and download it to the device before starting this guide if you have never done so before. This will ensure you have all the necessary software installed.

==Introduction to RFNoC==

===What is RFNoC?===

RFNoC™ is a heterogeneous processing framework used to implement high-throughput DSP in the FPGA for Software Defined Radio (SDR) systems in an easy-to-use and flexible way. It provides all the infrastructure required to insert signal-processing IP into the FPGA logic and communicate with it through software. It also provides highly-optimized software and FPGA code to enable high-performance streaming to and from IP blocks on the USRP device.

The IP blocks in RFNoC are called ''RFNoC blocks''. The RFNoC blocks wrap the IP and provide a custom interface to the RFNoC infrastructure through a tool-generated interface called the ''NoC Shell''. Many standard blocks are included in UHD 4.0. These blocks enable typical operation of the USRP and allow RFNoC to connect to the different hardware components of the USRP. Several of the included blocks are described in the section [[#Available RFNoC Blocks|Available RFNoC Blocks]]. You can mix the available blocks for your application, or develop your own custom RFNoC blocks with your own IP to open up new applications. The NoC Shell hides the complexity of RFNoC from your block, making it easy to plug your IP into the USRP.

RFNoC is used on all Generation-3 USRPs and is installed with UHD 4.0. USRPs ship with a default RFNoC image that can be used as is, or can be modified and/or customized to suite your application. So if you're using a modern USRP, it's running RFNoC under the hood even if you haven't customized anything.

===Example RFNoC Image===

The diagram below shows a simplified view of an RFNoC FPGA image that is similar to the default images available on USRPs.

<br>
[[File:simplified_rfnoc_image_uhd_4.png|center]]
<br>

Notice that an RFNoC FPGA is made up of several components. A description of each one is provided below.

* '''RFNoC Image Core'''<br>This is the main block of the RFNoC framework and instantiates the components that make up RFNoC. The contents of the image core are described by an RFNoC image core YAML file, and the Verilog code that represents this block is automatically generated by the RFNoC Image Builder tool based on the YAML description. In other words, you provide a description of what you want to be included in RFNoC and the tools generate the code to implement that description.
* '''Transport Adapter'''<br>The transport adapter is a component of the USRP that allows communication with an outside interface. These vary depending on the USRP model in use. For example, this could be a 10 Gbps Ethernet link for SFP+ port of the USRP, or a cabled PCIe interface.
* '''CHDR Crossbar'''<br>The CHDR crossbar is a dynamic router for RFNoC traffic. This is a high-throughput crossbar designed for RF streaming applications. It is reconfigurable at run time via software and can be used to configure routes between stream endpoints and transport adapters. The number of ports available is configurable by changing the RFNoC image core YAML file. CHDR (Condensed Hierarchical Datagram for RFNoC) refers to the network protocol that is used for RFNoC.
* '''Stream Endpoint (SEP)'''<br>The stream endpoint (SEP) provides the high-level flow control for traffic over the network. It also separates control traffic from data traffic to create a separate AXIS-Ctrl network for control traffic. Control traffic refers to things like register reads and writes for configuring and monitoring RFNoC blocks.
* '''Control Crossbar'''<br>The control crossbar is similar to the CHDR Crossbar, but is only for control traffic. It has a much lower throughput and has been optimized for control-traffic, making it much less resource intensive than the CHDR crossbar.
* '''Other Blocks'''<br>The DDC (digital down converter), DUC (digital up converter), and Radio in this example are RFNoC blocks that are included with UHD. These are standard components included the default USRP images and enable typical RF applications. Most blocks only communicate with the RFNoC network, but some blocks require access to external hardware interfaces, such as the radio or DRAM. In this example, the radio blocks connect to the radio hardware on the USRP.

===Static vs. Dynamic Routing===

The routes between blocks that go through the crossbar are ''dynamic''. That is, the routes can be changed at run time and are controlled by software. The CHDR crossbar is very powerful in that it allows any of its ports to communicate with each other. It allows for streaming between blocks on the same FPGA, between RFNoC blocks and a host computer, or between blocks on different USRPs. New signal processing chains can be added to this crossbar, as needed, for the application.

Similarly, the control crossbar supports dynamic routing, allowing any RFNoC block to send control traffic to any other RFNoC block, even to blocks on a different USRP. Control traffic can also be sent from the host computer to the RFNoC blocks, for example to read/write registers. Additionally, RFNoC blocks can send control to the host computer. In this example, the Radio block sends control traffic to the computer to report specific events, such as overflow or underflow in the radio.

The block connections that don't go through a crossbar (e.g., the connection from the radio to the DDC, and the DDC to the stream endpoint, etc.) are ''static'' connections. That is, they cannot be changed at run time. Making a connection static has the advantage that it does not require additional ports on the crossbar and that the connection can be made much simpler because the high-level network flow-control protocol used by CHDR is not required. This reduces latency between blocks and leads to FPGA resource savings, allowing more logic be included in a single FPGA image. The static connections are described by the RFNoC image core YAML file. In order to change the static connections, the YAML description needs to be updated and the FPGA image needs to be rebuilt.

===RFNoC Customization===

The RFNoC framework makes it easy to customize the RFNoC image and add your own IP blocks. Later on in this guide, we'll explore how you can customize the RFNoC image to add or remove blocks, as well as create your own RFNoC blocks and include them in your FPGA builds. This allows you to create highly-customized and high-performance FPGA images for your USRP.

==Setting Up==
To use RFNoC in UHD 4.0 you need to perform the following:

* Clone the UHD repository
* Install UHD
* Update your device's filesystem and FPGA image

Building custom RFNoC images requires the FPGA source code and build system. These are included in the UHD repository, located in <code><repo>/fpga/usrp3/</code>, where <code><repo></code> refers to the location where you cloned the UHD repository.

Please see the [http://files.ettus.com/manual/page_install.html Binary Installation] for UHD installation documentation or [https://files.ettus.com/manual/page_build_guide.html Building and Installing] instructions to build and install UHD from source. Additionally, [[Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux|AN-445]] provides step-by step instructions for cloning the repository and installing UHD from source.

Starting with UHD 3.15, RFNoC is enabled by default, and starting with UHD 4.0, it can no longer be disabled, so no additional instructions are necessary to install support for RFNoC in UHD.

Many of the UHD utilities we will use in this guide are based on Python. Please ensure that your <code>PYTHONPATH</code> is set correctly. If not set correctly, you will see errors indicating that Python could not find the <code>uhd</code> or <code>image_builder</code> libraries. The correct setting may depend on where you installed UHD and which Linux distribution you are using. If you installed UHD from source to the default location on Ubuntu, you may need to add <code>/usr/local/lib/python3/dist-packages</code> to your <code>PYTHONPATH</code> variable. For example:

$ export PYTHONPATH=/usr/local/lib/python3/dist-packages

Instructions for updating your device's filesystem (applicable to E3xx and N3xx) and FPGA image can be found in that device's [https://kb.ettus.com/Getting_Started_Guides Getting Started Guide]. If your filesystem is already up to date, or your device does not use a filesystem (e.g., X3xx), then instructions on flashing an FPGA image to a device can be found in the following locations:

* [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs X3xx series]
* [http://files.ettus.com/manual/page_usrp_e3xx.html#e3xx_getting_started_fpga_update E3xx series]
* [http://files.ettus.com/manual/page_usrp_n3xx.html#n3xx_getting_started_fpga_update N3xx 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 your USRP device will likely lead to an error message but can brick the device under some circumstances.

===Configure the Default Shell===

Make sure you are using the <code>Bash</code> shell. Many of the build scripts used by RFNoC are written for <code>Bash</code>. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

==Testing the Default FPGA Image==

Before continuing, please verify that you have downloaded and flashed the latest FPGA image for your version of UHD. All FPGA images for Generation-3 and above devices are RFNoC images, so there is no requirement to download a special image for RFNoC.

===Inspect the Default Image===

Before we start customizing our FPGA, let's get familiar with the default FPGA image, which is pre-built with a set of RFNoC blocks.

Run the following command, with your USRP connected to your PC, to see what is available on the device.

$ uhd_usrp_probe --args type=x300

Note that your <code>args</code> may be different, depending on the USRP device you're using. The example here works for X300/X310. Refer to the manual page on [https://files.ettus.com/manual/page_identification.html Identifying USRP Devices] for more details. If an RFNoC image was successfully loaded onto the USRP, the output will show something like the following:

<nowiki> _____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X310
| | revision: 11
| | revision_compat: 7
| | product: 30818
| | mac-addr0: 00:80:2f:17:40:6d
| | mac-addr1: 00:80:2f:17:40:6e
| | 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: 311EF81
| | FW Version: 6.0
| | FPGA Version: 38.0
| | FPGA git hash: be53058
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
...</nowiki>

More than this will likely be shown. The specifics of the output depend on the UHD version and which device you're running on. However, we're interested in the following sections:

* '''Device description'''. At the top, there is a section with basic information about your device, such as serial number, revision, etc. You can use this information to verify that you are indeed communicating with the correct device, and that the device has been updated. The FPGA git hash identifies the commit from which the FPGA image was built.
* '''RFNoC blocks on this device'''. This section lists all the RFNoC blocks in the loaded FPGA image. The blocks are listed by their block IDs. For example, <code>0/Radio#0</code> means that we're on device zero (<code>0/</code>), and we're talking about the first radio (with index <code>#0</code>). Unless you probe multiple devices at once by specifying multiple addresses in the <code>--args</code> argument, the device number will always be zero, but the block index will change depending on the number of blocks of that type. For example, on X310, <code>Radio#0</code> corresponds to RF A and <code>Radio#1</code> corresponds to RF B.
* '''Static connections on this device'''. This section lists how the blocks are pre-connected in the FPGA image. For example, the line <code>0/Radio#0:0==>0/DDC#0:0</code> means that radio zero, port zero (<code>:0</code>), is connected statically to DDC zero, port zero. Static connections can only be changed at compile time when building the FPGA image.

The connection endpoints labeled <code>SEP</code> are not RFNoC blocks. They are Stream Endpoints (SEPs). SEPs can send data packets to one another, or to streamers in software, using the CHDR crossbar, which is a dynamic router on the FPGA.

===Available RFNoC Blocks===

Many RFNoC blocks come with UHD. The HDL source code for these blocks resides in <code><repo>/fpga/usrp3/lib/rfnoc/blocks/</code>. several of the blocks are described below.

{| class="wikitable"
!Block Name
!HDL Name
!Description
|-
|AddSub
|<code>rfnoc_block_addsub</code>
|Add/Subtract Verilog/VHDL/HLS Example
|-
|DmaFIFO
|<code>rfnoc_block_axi_ram_fifo</code>
|FIFO that uses an AXI4 memory-mapped interface for storage. For use with external DRAM or on-chip SRAM.
|-
|DDC
|<code>rfnoc_block_ddc</code>
|Digital Down Converter
|-
|DUC
|<code>rfnoc_block_duc</code>
|Digital Up Converter
|-
|FFT
|<code>rfnoc_block_fft</code>
|Fast Fourier Transform
|-
|FIR
|<code>rfnoc_block_fir_filter</code>
|Finite Impulse Response Filter
|-
|Fosphor
|<code>rfnoc_block_fosphor</code>
|FFT and waterfall display tool
|-
|KeepOneInN
|<code>rfnoc_block_keep_one_in_n</code>
|Keep one sample/packet in N
|-
|LogPwr
|<code>rfnoc_block_logpwr</code>
|Computes an estimate of log2(i^2+q^2)
|-
|MovingAverage
|<code>rfnoc_block_moving_avg</code>
|Outputs the running average of the N most recent inputs of data stream
|-
|NullSrcSink
|<code>rfnoc_block_null_src_sink</code>
|Data source generator, sink, and loopback for testing
|-
|Radio
|<code>rfnoc_block_radio</code>
|Radio Interface
|-
|Replay
|<code>rfnoc_block_replay</code>
|Record/Playblack using AXI4 memory-mapped interface. For use with external DRAM or on-chip SRAM.
|-
|SigGen
|<code>rfnoc_block_siggen</code>
|Signal Generator. Supports sinusoidal, constant, and random outputs, with configurable gain.
|-
|SplitStream
|<code>rfnoc_block_split_stream</code>
|Splits a single data stream into two
|-
|Switchboard
|<code>rfnoc_block_switchboard</code>
|A configurable RFNoC datapath switch for testing
|-
|VectorIIR
|<code>rfnoc_block_vector_iir</code>
|Implements an IIR filter with variable length delay line
|-
|Window
|<code>rfnoc_block_window</code>
|Windowing module for use with FFT block
|}

===Streaming Example===

In the UHD installation directory, you'll find example applications (e.g., in <code>/usr/lib/uhd/examples/</code> or <code>/usr/local/lib/uhd/examples/</code>). We'll look at <code>rfnoc_rx_to_file</code> to familiarize ourselves with the RFNoC API.

If we look at the source code for this example (located at <code><repo>/host/examples/rfnoc_rx_to_file.cpp</code>), we can see the components necessary in an RFNoC application. In the <code>UHD_SAFE_MAIN</code> function, we create a few crucial objects, such as an RFNoC graph, a radio block controller, a DDC block controller, and an RX streamer.

auto graph = uhd::rfnoc::rfnoc_graph::make(args);
// ...
auto radio_ctrl = graph->get_block<uhd::rfnoc::radio_control>(radio_ctrl_id);
// ...
uhd::rfnoc::ddc_block_control::sptr ddc_ctrl;
// ...
auto rx_stream = graph->create_rx_streamer(1, stream_args);

We also make connections in our graph and configure our blocks.

// Connect blocks and commit the graph
for (auto& edge : chain) {
if (uhd::rfnoc::block_id_t(edge.dst_blockid).match(uhd::rfnoc::NODE_ID_SEP)) {
graph->connect(edge.src_blockid, edge.src_port, rx_stream, 0);
} else {
graph->connect(
edge.src_blockid, edge.src_port, edge.dst_blockid, edge.dst_port);
}
}
...
rate = radio_ctrl->set_rate(rate);
...
radio_ctrl->set_rx_frequency(freq, radio_chan);

Once our graph and blocks are configured, we use the <code>recv_to_file</code> function to receive data from our device and write it to a file on our host computer. Running this example with the <code>--help</code> argument shows the available options. For example, to receive 3 seconds of data at a specific frequency and sample rate, we can run:

rfnoc_rx_to_file --args type=x300 --freq 2.4e9 --rate 10e6 --duration 3

Now you are ready to move to the next step and build your own blocks and FPGA images.

==RFNoC Image Builder==

UHD provides tooling to help develop custom RFNoC images. In this guide we will demonstrate how to use the RFNoC Image Builder, which will allow you to change which blocks are included and the connections between blocks. Let's go over common decisions you'll have to make with this tool.

* '''Blocks Included'''<br>The particular blocks to be included in the image is the most impactful decision you'll make in the image building process, both in terms of image functionality and FPGA resource utilization. Adding more blocks means more processing in the image, but it also means longer FPGA build times and less space in the FPGA.
* '''Static Connections'''<br>Recall that blocks can be statically connected, as opposed to connecting every block to the CHDR crossbar (dynamically connected). The number of dynamic connections has a large impact on the size of the CHDR crossbar, so static connections are used to lower resource utilization. However, once a block is statically connected in a chain of blocks, data cannot be sent between arbitrary blocks; it must traverse and be processed by each block in the order defined by the static connections.
* '''Hardware Connections'''<br>All blocks share some connections defined by the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification]. These connections are made automatically and cannot be changed. Many blocks require additional connections, such as clocks for the internal DSP or external DRAM interfaces. These connections must also be specified.

Now that we've gone over some of the considerations, let's look at how to actually build a custom RFNoC image. This begins with the RFNoC image core YAML description.

===Understanding the RFNoC Image YAML File===

The image YAML file defines RFNoC blocks in the FPGA image. It is designed to be both human-readable and machine-parseable, which allows us to make edits quickly and easily. Each device type has a default YAML image file, which is named <code><DEVICE>_rfnoc_image_core.yml</code> (e.g., <code>x310_rfnoc_image_core.yml</code>). Take a look at the RFNoC image core YAML file for the X310 by opening <code><repo>/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml</code>. Notice that it has the following sections.

* '''General Parameters'''<br>Here we define the device, the bit width of our CHDR connections, as well as some versioning and licensing.
* '''Stream Endpoints'''<br>In the <code>stream_endpoints</code> section we list each stream endpoint (SEP) that we wish to instantiate. These will be directly connected to the CHDR crossbar and will allow us to make dynamic connections within the CHDR crossbar. Typically you will have one SEP that forms the start and end of a single DSP chain of RFNoC blocks.<br>You can also add some per-stream-endpoint configuration here, such as the ingress buffer size, which affects streaming performance from your computer to that SEP. For example, if we know that one SEP will be receiving data transferred from your computer to the USRP then a data buffer is needed to accept those incoming packets, in which case we specify the buffer size by setting the <code>buff_size</code> option on that SEP. Alternatively, if we know that a particular SEP only sends data from the USRP to the computer, then we won't need the ingress data buffer and we can set <code>buff-size</code> to 0, thus saving FPGA resources.<br>Each SEP can have an AXIS-Ctrl and an AXIS-CHDR port, as indicated by the <code>ctrl</code> and <code>data</code> options. At least one AXIS-Ctrl port is required to communicate with the RFNoC blocks, so <code>ctrl</code> typically enabled on just the first SEP. Every SEP will usually have AXIS-CHDR connections to one or more RFNoC blocks, so <code>data</code> is usually enabled on all SEPs.
* '''NoC Blocks'''<br>In the <code>noc_blocks</code> section we specify all the RFNoC blocks to include in the FPGA image. We'll need to give each block a unique name and reference a block definition YAML file (which we'll discuss in a later section). The blocks chosen have the greatest impact on the functionality of the image, as well as providing very coarse control over the FPGA resource utilization. We'll look at how to change the blocks included in the image as part of our example below.
*'''Static Connections'''<br>The <code>connections</code> section defines static connections between blocks, stream endpoints, and various hardware interfaces on the USRP. Statically connected chains of blocks will usually start and end at a stream endpoint (SEP). SEPs are automatically connected to the CHDR crossbar by the RFNoC infrastructure. Remember that data must be passed through the entire statically connected chain; dynamic connections cannot be made to the statically connected blocks in the middle of the chain. Other hardware connections, such as to the external DRAM, would also be specified here. We'll take a closer look at making connections as part of our example below.
* '''Clock Domains'''<br>The <code>clk_domains</code> section defines which clocks to connect to each block's clock inputs. Some blocks do not need any clock connections beyond the base clocks required by RFNoC. These required connections are not listed here, since they are always the same for each block. Other blocks may require additional clocks. For example, the radio blocks should be connected to the <code>radio</code> clock. Many other blocks require a <code>ce</code> (Compute Engine) clock, which is used for the block's internal DSP.

===Running the Image Builder===

Before we look at editing the image core YAML file, let's go over how to use the RFNoC image builder to generate a bitstream from that YAML file. Additional details on how to run the image builder can be found with the <code>--help</code> option:

$ rfnoc_image_builder --help

Here are some of the options provided:
* '''<code>-y</code>''': Path to the RFNoC image core YAML file
* '''<code>-t</code>''': The image target you would like to build. These are the same targets that are used in the FPGA <code>make</code> process. More details on these can be found in the [https://files.ettus.com/manual/md_usrp3_build_instructions.html Generation 3 USRP Build Documentation] of the UHD and USRP Manual. If not specified, the default specified in the image core YAML file will be used.
* '''<code>-l debug</code>''': Use the <code>debug</code> log level. This prints more information about the FPGA connections and available port names, which can be useful for debugging connection errors in the YAML file.
* '''<code>--generate-only</code>''': Generate the HDL files required, but do not build the FPGA. Users can then build the FPGA later using <code>make <target></code>.
* '''<code>-I</code>''': Path to the directory containing out-of-tree block YAML descriptions (the YAML files installed with UHD are included by default). This option is only needed if using an out-of-tree RFNoC block.
* '''<code>-F</code>''': Path to the FPGA source code (e.g., <code><repo>/fpga</code>). This path is only required if the current working directory is not within the UHD repository.

For example, to build the default RFNoC image for X310, you might use the following command:

$ cd <repo>/fpga/usrp3/top/x300/
$ rfnoc_image_builder -y ./x310_rfnoc_image_core.yml -t X310_XG

In this example <code><repo></code> refers to the location where you cloned the UHD repository and should be replaced by the location you used. <code>x310_rfnoc_image_core.yml</code> is the default RFNoC image core YAML file for the X310, which is in the x300 project directory. <code>X310_XG</code> is the make target to use for the build. <code>XG</code> in this case refers to dual 10 Gbps Ethernet.

For an out-of-tree RFNoC block, you will also need to specify the location of the block information. For example:

$ rfnoc_image_builder -F <repo>/fpga -I <repo>/host/examples/rfnoc-example -y <repo>/host/examples/rfnoc-example/icores/x310_rfnoc_image_core.yml -t X310_XG

This example shows how to build an FPGA with the Gain example out-of-tree RFNoC block, which is located in <code><repo>/host/examples/rfnoc-example/</code>. The <code>-F</code> option is added to specify the location of the FPGA source, and <code>-I</code> specifies the location of the out-of-tree block YAML.

The image builder performs several steps in order to build the FPGA image from the image coure YAML:

# It generates the <code><device>_rfnoc_image_core.v</code> file. This file includes the Verilog code described by the YAML image core file. A <code><device>_static_router.hex</code> file is also generated. This file describes the static connections that should be made by the Verilog code. In the case of the X310 examples above, the output files would be named <code>x310_rfnoc_image_core.v</code> and <code>x310_static_router.hex</code>, and would be placed in the project directory for the X310 (<code><repo>/fpga/usrp3/top/x300/</code>).
# The image builder will configure the environment for building the FPGA. This is equivalent to sourcing the <code>setupenv.sh</code> script for the device type being built. For example, in our example above, it would run <code>source <repo>/fpga/usrp3/top/x300/setupenv.sh</code>.
# The image builder runs <code>make <target></code> to build the IP and the FPGA bitstream for the indicated target. The generated <code>rfnoc_image_core.v</code> and <code>static_router.hex</code> are automatically pulled into this build. The completed bitstream will be located in <code><repo>/fpga/usrp3/top/{project}/build</code> directory, which is the same directory created through the normal make process. For example, for X310 it would be located in <code><repo>/fpga/usrp3/top/X300/build</code>.

===Example: Adding an FFT Block===

As an example, let's run through how to modify the YAML file to modify the RFNoC image. Suppose we have an application that we'd like to run on a USRP X310 and we would like to offload the FFT processing to the FPGA. UHD provides an FFT RFNoC block, and the default X310 image has some extra space in it, so we should be able to add this block. First, we copy the default X310 image core file, named <code>x310_rfnoc_image_core.yml</code>.

$ cd <repo>/fpga/usrp3/top/x300/
$ cp x310_rfnoc_image_core.yml x310_with_fft.yml

Now open <code>x310_with_fft.yml</code> in your favorite text editor. We'll start by making some room for our new block. The default images use very large ingress FIFO buffers for the main SEPs to maximize streaming performance. But we want to make sure we have enough memory buffer space for our new blocks. So Start by reducing the <code>buf_size</code> parameters for <code>ep0</code> and <code>ep2</code> from 65536 to 32768. If using a device other than X310, the numbers may be different, but you can similarly reduce the <code>buff_size</code> parameter by half. On smaller devices, it may be necessary to remove the Replay block to make room for the FFT blocks. After making the changes on X310, the result should look like the following:

stream_endpoints:
ep0: # Stream endpoint name
ctrl: True # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 32768 # Ingress buffer size for data
...
ep2: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 32768 # Ingress buffer size for data

Now we can add our FFT block. We'll put it on its own stream endpoint, so we first need to add a new stream endpoint. Add the following to the <code>stream_endpoints</code> section:

stream_endpoints:
...
ep_fft: # The name can be incremented from previous SEP
ctrl: False # Only the first SEP needs control traffic
data: True # We do want to pass data through this SEP
buff_size: 32768 # Ingress buffer size for data

In this example, we've named the SEP <code>ep_fft</code>. Other names could be given, as long as the name is unique (it does not have to be numbered). Now that we've allocated an SEP for our block, we need to instantiate the actual block. In the next section, add the following:

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft_1x64.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
EN_FFT_SHIFT: 1

Again, the name <code>fft0</code> is arbitrary, but the name must be unique. In some cases, there will also be block parameters you'll want to pass, such as the data format of the FFT output data. In our example, we're setting <code>EN_FFT_SHIFT</code> parameter to 1, which causes the FFT block to center the zero frequency bin.

Now that we've added our FFT block, we need to connect it to the stream endpoint. In the next section of the YAML file, we add the static connections:

connections:
...
- { srcblk: ep_fft, srcport: out0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep_fft, dstport: in0 }

This connects the output of SEP <code>ep_fft</code> to the input of block <code>fft0</code>, and the output of <code>fft0</code> to the input of <code>ep_fft</code>. Since we're placing the FFT block on its own SEP, the only connections we need to make are between the SEP and the FFT. All SEPs are automatically connected to the CHDR crossbar, so this effectively connects the FFT block to the crossbar, allowing it to communicate with anything on the RFNoC network.

The names of block ports are defined in the YAML descriptions for the blocks. Blocks can use any names for their ports, and they don't have to be numbered (unless the number of ports is parameterized). Generally, the block ports are named <code>in_N</code> for inputs to the block and <code>out_N</code> for outputs. SEP ports are named <code>in0</code> for the input <code>out0</code> for the output.

If you are having trouble connecting a block due to an unresolved connection, running <code>rfnoc_image_builder</code> with the <code>-l debug</code> option will list all available block ports.

Finally, the FFT block has an additional clock input port named <code>ce</code> that is used for the FFT signal processing. We need to connect it to a clock domain. Any clock that's at least as fast as the incoming data rate should be sufficient. For example, X3xx devices have a <code>ce</code> clock (214.286 MHz) that is usually a good choice, but <code>rfnoc_chdr</code> clock (200 MHz) should also work for this example. For N31x and E3xx devices, <code>rfnoc_chdr</code> clock is a good choice (200 MHz on N31x and 100 MHz on E3xx). For N32x, <code>radio</code> clock (250 MHz) is a good choice. For example, this is how you would connect the X310's <code>ce</code> clock to the <code>ce</code> port of the FFT block:

clk_domains:
...
- { srcblk: _device_, srcport: ce, dstblk: fft0, dstport: ce }

And this is how you would connect <code>rfnoc_chdr</code> clock to the <code>ce</code> port:

clk_domains:
...
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

And finally, this is how you would connect <code>radio</code> clock:

clk_domains:
...
- { srcblk: _device_, srcport: radio, dstblk: fft0, dstport: ce }

The source block name <code>_device_</code> is special and refers to the USRP device itself. Choose a clock that's apprpriate for your device and connect it as shown above.

And that's it! The next step will be to run the image builder on our modified YAML file. Once that's done, and the bitstream has been created, you can load it onto your USRP X310 device, and verify the blocks, as we did in the [[#Inspect_the_Default_Image|Inspect the Default Image]] section.

For example, from the X300 directory, you would run the following command to run the image builder:

$ rfnoc_image_builder -y x310_with_fft.yml -t X310_XG

To download the FPGA bitstream to the X310, run the following:

$ uhd_image_loader --args "type=x300,addr=192.168.30.2" --fpga-path ./build/usrp_x310_fpga_XG.bin

You may need to change the IP address to match your device, depending on your configuration. After completing the flash update and power-cycling the USRP, run <code>uhd_usrp_probe</code> to confirm that the FFT block was recognized.

$ uhd_usrp_probe --args "type=x300,addr=192.168.30.2"

Take a look at the RFNoC blocks and the static connections on the device. You should see the following new blocks and connections:

| _____________________________________________________
| /
| | RFNoC blocks on this device:
...
| | * 0/FFT#0
...
| _____________________________________________________
| /
| | Static connections on this device:
...
| | * 0/SEP#6:0==>0/FFT#0:0
| | * 0/FFT#0:0==>0/SEP#6:0
...


===Example: Adding an FFT Block to the Receive Chain===

Now that we've added the FFT block and verified that it is operating as expected, let's see if we can modify it a little. Let's say that we're sure that we always want to receive the FFT bins from our device, and we don't want to see the raw samples. In order to save some FPGA resources, we can move our FFT block to be between the DDC and the SEP, on the RX data path. Instead of the previous modifications to our YAML file, we want the following:

stream_endpoints:
...
# Unchanged from the default image core (no need for ep_fft).

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft_1x64.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
EN_FFT_SHIFT: 1

connections:
...
# Change this line:
# - { srcblk: ddc0, srcport: out_0, dstblk: ep0, dstport: in0 }
# Change it to the following to add fft0 between ddc0 and ep0:
- { srcblk: ddc0, srcport: out_0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep0, dstport: in0 }

clk_domains:
...
# As before, we still connect our FFT block to the clock domain
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

This last line is valid for E310/E320; for X300/X310/N300/N310/N320/N321 use the following:

- { srcblk: _device_, srcport: ce, dstblk: fft0, dstport: ce }

And as simply as that, we have added the FFT block to our RX block chain. Remember that this is a static connection, so when the resulting FPGA image is loaded onto your device, you will no longer be able to receive samples from the DDC directly; all samples on that chain will be processed by the FFT block, and you will only receive FFT bins from this radio chain.

==Out-of-tree Modules==

===OOT Overview===

Now that we've gone over what is provided by UHD, let's start to look at custom RFNoC development. It's recommended that custom RFNoC development be kept separate from the in-tree UHD RFNoC infrastructure and examples, in order to simplify version control and licensing. Modules located outside of the repository are called ''out-of-tree'' (OOT).

In order to understand how OOT modules for RFNoC are created, let's take a look at the example that's provided with UHD. You can find the example located in <code><repo>/host/examples/rfnoc-example/</code>. This example includes a simple Gain RFNoC block that we can use as a reference for creating our own OOT blocks.

===OOT Subdirectories===

Take a look at the <code>rfnoc-example</code> directory structure. An OOT module is a collection of block implementations, the software controllers for those blocks, and sometimes applications to demonstrate their functionality. These different components within the OOT module are organized into the directories described below.

* HDL and Image Resources
** <code>fpga/</code>: Contains the HDL (e.g., Verilog) required for the module. Each RFNoC block should have its own subdirectory here, such as <code>rfnoc_block_gain</code>, for the Gain block.
** <code>blocks/</code>: Contains the YAML RFNoC block definition files. These describe the block's interfaces and are used by the image builder. We'll go into more detail with regards to what goes into these YAML files in the [[#Creating_Your_Own_RFNoC_Block|Creating Your Own RFNoC Block]] section.
** <code>icores/</code>: Contains example FPGA image core YAML files, to demonstrate how to create an FPGA image using your custom blocks. These image core files may demonstrate important parameters or show recommended configurations for chains of blocks.
* Block Controller and Example Software
** <code>include/</code>: Contains the headers for the block controller software. Once installed, these headers will be used by UHD and other applications to interface with and control your custom RFNoC blocks.
** <code>lib/</code>: Contains the block controller implementations. The files here should implement the features outlined in the headers located in the <code>include/</code> directory. All unit test code should also be located here.
** <code>apps/</code>: Contains example applications for your custom blocks. These applications may demonstrate how to use the block controllers, common configurations, or how to process data from your blocks.
* Infrastructure
** <code>cmake/</code>: Contains any custom CMake commands the module may need. In general, simple modules will not need to modify this directory at all. More complicated modules with additional external dependencies may need to modify this.

Take some time to explore the files in the <code>rfnoc-example</code>. Note the following files and directories related to the Gain example:

* <code>rfnoc-example/fpga/rfnoc_block_gain/</code><br>This is the HDL for the Gain RFNoC block.
** <code>rfnoc_block_gain.v</code><br>The top-level synthesizable file for the Gain block
** <code>noc_shell_gain.v</code><br>The NoC Shell for the Gain block
** <code>rfnoc_block_gain_tb.sv</code><br>The simulation testbench
** <code>Makefile</code><br>The simulation Makefile
* <code>rfnoc-example/blocks/gain.yml</code><br>The YAML block definition file for the Gain block
* <code>rfnoc-example/icores/x310_rfnoc_image_core.yml</code><br>An example RFNoC image core YAML description showing how to connect the Gain block
* <code>rfnoc-example/include/rfnoc/example/gain_block_control.hpp</code><br>The software block controller header
* <code>rfnoc-example/lib/gain_block_control.cpp</code><br>The software block controller implementation
* <code>rfnoc-example/apps/init_gain_block.cpp</code><br>An example showing how to find and initialize the Gain block


===Creating Your Own OOT Module===

To create your own OOT module, make a copy of the <code>rfnoc-example</code> directory. This will contain all the subdirectories and infrastructure files that you need to create your custom module. The directory name for your copy should be renamed to your desired name; we recommend something like <code>rfnoc-foo</code>, for example, where <code>foo</code> is the name for your OOT module. You'll also need to change <code>rfnoc-example</code> within the module's <code>CMakeLists.txt</code> files to your module's name.

Let's start by creating our own copy of the <code>rfnoc-example</code> to work with. We'll call our module <code>demo</code>. You can put the copy wherever you like, but for this example we'll put it in our home directory.

$ cp -r <repo>/host/examples/rfnoc-example ~/
$ mv ~/rfnoc-example ~/rfnoc-demo

Now we need to edit our <code>CMakeLists.txt</code> files to rename our module. Edit the following files and change all instances of <code>rfnoc-example</code> to <code>rfnoc-demo</code>:

~/rfnoc-demo/CMakeLists.txt
~/rfnoc-demo/lib/CMakeLists.txt

===Building and Installing an OOT Module===
The OOT module will need to be built and installed in order to use its RFNoC blocks. To build and install the OOT module we just created, do the following:

$ mkdir ~/rfnoc-demo/build
$ cd ~/rfnoc-demo/build
$ cmake -DUHD_FPGA_DIR=<repo>/fpga/ ../

This configures the project to be installed in the default location. You may want to provide a different install directory to CMake using the <code>-DCMAKE_INSTALL_PREFIX</code>. Please refer to the [https://files.ettus.com/manual/page_build_guide.html UHD Installation Guide] or the installation guide for other CMake-based projects for instructions on configuring CMake.

Note that we specify the location of the FPGA source code using the <code>-DUHD_FPGA_DIR</code> option. This allows you to run the FPGA testbenches and to build the example FPGA image provided with the OOT example.

At this point, you can run <code>make help</code> to see what options are available. A few of the available make targets are described below:

* <code>make rfnoc-demo</code>: Build the block controllers for the RFNoC blocks
* <code>make testbenches</code>: Run the testbenches for the RFNoC blocks
* <code>make x310_rfnoc_image_core</code>: Build the FPGA example image
* <code>make install</code>: Install the module

To build and install the block, perform the following steps.

$ cd ~/rfnoc-demo/build
$ make
$ make install

Note that <code>sudo</code> may be required depending on the install location.

===Building an FPGA Image with OOT Blocks===

At this point you can build the example FPGA that's included in the <code>icores</code> directory. Take a look at <code>~/rfnoc-demo/icores/x310_rfnoc_image_core.yml</code>. Note that the <code>gain</code> block is added in exactly the same way that the FFT block was in [[#Example:_Adding_an_FFT_Block|Example: Adding an FFT Block]]. You can build this example FPGA for the X310 using the following steps:

$ cd ~/rfnoc-demo/build
$ make x310_rfnoc_image_core

Alternatively, you can call <code>rfnoc_image_builder</code> directly. In order to get the image builder to find your custom blocks, you may need to supply some additional arguments to find the OOT module, as shown in the following example:

$ rfnoc_image_builder -F <repo>/fpga –I ~/rfnoc-demo/include/rfnoc -y ~/rfnoc-demo/icores/x310_rfnoc_image_core.yml

The <code>-I</code> option is only required if the OOT module has not been installed on the system. 

If you have an X310, you can build and use the provided example to test the Gain block. If you have a different USRP, you can use its default <code>rfnoc_image_core.yml</code> as a starting point and follow the same steps that we followed for the FFT block in [[#Example:_Adding_an_FFT_Block|Example: Adding an FFT Block]], then build it using the process described above.

===Testing the Gain Example===

After building an FPGA image for your USRP and downloading it to your device, the Gain block should be available. Test this by running <code>uhd_usrp_probe</code>:

$ uhd_usrp_probe --args "type=x300,addr=192.168.30.2"

Again, note that your <code>args</code> may be different or may not be required if you only have a single USRP connected.

Take a look at the RFNoC blocks and the static connections on the device. You should see the following new blocks and connections:

| _____________________________________________________
| /
| | RFNoC blocks on this device:
...
| | * 0/Block#0
...
| _____________________________________________________
| /
| | Static connections on this device:
...
| | * 0/SEP#4:0==>0/Block#0:0
| | * 0/Block#0:0==>0/SEP#4:0
...

==Creating Your Own RFNoC Block==

The Gain block is a useful example and could even be used as the starting point for a new block, but rather than trying to copy and edit the Gain block, it is best to use the RFNoC ModTool to create a new block template. This is also required if you want to change the interfaces provided to your IP that are exposed by the NoC Shell.

===Understanding the Block Definition YAML===

The first step in creating a new block is to write a YAML description for the block that you want to create. The options available are described [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification]. You can also look at the blocks available in <code><repo>/host/include/uhd/rfnoc/blocks/</code> for examples. We'll provide a brief overview here.

Open up and take a look at the Gain block definition located in <code>~/rfnoc-demo/blocks/gain.yml</code>. Notice the different sections, which are described below:

* '''General Parameters'''<br>In this section we give our block a name (<code>module_name</code>) and a unique block ID (<code>noc_id</code>). The NoC ID is an arbitrary 32-bit number that will be used by the software to identify the block during system discovery. You can also specify the CHDR bus width, which should be 64 for Generation-3 USRPs.
* '''Clocks'''<br>In the <code>clocks</code> section, we define the clocks that will be used by the block. The <code>rfnoc_chdr</code> and <code>rfnoc_ctrl</code> clocks are required. Many blocks also have a <code>ce</code> clock for internal DSP.
* '''Control Interface'''<br>The <code>control</code> section defines what type of control interface to make available to your block. The control interface is used for register reads and writes. Most blocks do not need to modify this section and will use the <code>ctrlport</code> interface type. Control Port is the standard register interface used by RFNoC. The <code>clk_domain</code> parameter allows you to specify which clock domain to use for the register interface exposed to your block. Typically this is the same clock that is used for the <code>data</code> interface, to avoid clock crossings.
* '''Data Interface'''<br>The <code>data</code> section defines what type of data interface to make available to your block and describes the ports. Most blocks use either the <code>axis_pyld_ctxt</code> or the <code>axis_data</code> interface types.<br>The <code>clk_domain</code> parameter allows you to specify which clock domain to use for the data interfaces exposed to your block. Typically this is the same clock that is used for the <code>control</code> interface, to avoid clock crossings.<br>Under the <code>inputs</code> and <code>outputs</code> sections you can describe the input and output ports.
* '''IO Ports'''<br>The <code>io_ports</code> section is used to describe other device-specific ports to which your block needs to connect (such as the DRAM or radio interfaces). For most blocks, this section is not used.

A few other sections might be present in the YAML file (e.g., <code>registers</code> or <code>properties</code>). These sections are reserved for future use and can be left empty.

===Starting Your Own Block Definition===

Let's start by making a copy of the Gain block YAML for our use case.

$ cp ~/rfnoc-demo/blocks/gain.yml ~/rfnoc-demo/blocks/demo.yml

Now open the <code>demo.yml</code> file you just created and make the following changes:

# Change the name of the block from <code>gain</code> to <code>demo</code>
# Change the <code>noc_id</code> to <code>0x0000DE30</code>
# Change the <code>format</code> for the <code>in</code> and <code>out</code> ports from <code>int32</code> to <code>sc16</code>.

This YAML file now describes a block with the following features:

* The block named "demo"
* NoC ID of 0xDE30
* CtrlPort register interface on the <code>rfnoc_chdr</code> clock domain
* A single 32-bit input port named "In" on the <code>rfnoc_chdr</code> clock domain that will provide sc16 samples to your IP
* A single 32-bit output port named "Out" on the <code>rfnoc_chdr</code> clock domain that will receive sc16 samples from your IP

===Generating Your Block Using the ModTool===

Now that we have a block definition YAML file, we can generate the source code templates and NoC Shell for our block. To do so, run the following command:

$ python3 <repo>/host/utils/rfnoc_blocktool/rfnoc_create_verilog.py -c ~/rfnoc-demo/blocks/demo.yml -d ~/rfnoc-demo/fpga/rfnoc_block_demo

This will create a folder named <code>~/rfnoc-demo/fpga/rfnoc_block_demo</code> with an RFNoC block template for you to use. Explore the folder that was created. You should see the following files:

* '''<code>Makefile</code>''': This is the Makefile for the simulation testbench. See [https://files.ettus.com/manual/md_usrp3_sim_running_testbenches.html Running a Testbench] in the UHD and USRP Manual for instructions on how to run a testbench.
* '''<code>Makefile.srcs</code>''': This is another makefile that identifies the HDL source code that makes up your RFNoC block.
* '''<code>noc_shell_demo.v</code>''': This is the NoC Shell that was generated for your block. It provides the interfaces described in the block definition YAML.
* '''<code>rfnoc_block_demo.v</code>''': This is a template for your RFNoC block. It includes all the top-level ports required by RFNoC and instantiates the NoC Shell.
* '''<code>rfnoc_block_demo_tb.sv</code>''': This is a testbench template for your RFNoC block. It instantiates your RFNoC block and the bus functional models (BFMs) needed to communicate with your block in simulation.

Take a moment to look at the <code>rfnoc_block_demo.v</code> and <code>rfnoc_block_demo_tb.sv</code> files that were generated for your block. Notice the "User Logic" section towards the end of the <code>rfnoc_block_demo</code> module. This is the location where you can insert your own IP.

The input data samples come in on the <code>m_in_payload</code> AXI4-Stream bus. The output data samples go out on the <code>s_out_payload</code> AXI4-Stream data bus.

If your input packets are the same size as your output packets (i.e., for every sample in you generate one sample out) then the <code>m_in_context</code> data bus can be used to drive <code>s_out_context</code>. The context bus is described in detail in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

Similarly, the testbench has a section where you can add your own test sequences to the test bench.

If you decide you need to change the RFNoC interfaces for your block (e.g., add ports, or change the interface type), then it is recommended to update the block definition YAML then regenerate the block. Please take care to not overwrite any code you have written when regenerating the files for your block! Rerunning the tool will cause new files to be generated, with a new NoC Shell, and will demonstrate how to update your code for the new interfaces.

Refer to the Gain example and other RFNoC blocks for examples of how to complete your RFNoC block logic and testbenches.

==Summary==

In this guide we have given a brief introduction on how to develop for RFNoC in UHD 4.0. There's a lot more you can do than is described here, but this will hopefully get you started. Happy coding!

Getting Started with RFNoC in UHD 4.0

2022-02-07T15:08:05Z

MartinBraun: /* Prerequisites */

==Application Note Number and Authors==
'''AN-400''' by Sugandha Gupta, Brent Stapleton, Wade Fife, and Michael Dickens


==Abstract==
This guide describes how to get started with FPGA and Software development for RF Network-on-Chip (RFNoC™). It gives a brief introduction to RFNoC and explains the steps needed to generate, build, and use custom RFNoC images and introduces the process for creating and integrating new RFNoC IP blocks.


==Intended Audience==
This guide is written for hardware and software engineers who want to use the RF Network-on-Chip (RFNoC™) architecture or want to develop intellectual property (IP) using the RFNoC architecture. For more details on the architecture please refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

This guide assumes that you have some basic familiarity with USRPs, such as connecting them, configuring your network interfaces, etc., so that your USRP is ready for use. See the [https://kb.ettus.com/Getting_Started_Guides Getting Started Guide] for your USRP if you are just getting started with USRPs.

==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). RFNoC is available under the open-source GNU Lesser General Public License (LGPL). For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Prerequisites==
RFNoC is currently supported on the USRP X410 series, and all the Generation-3 USRPs in the X series (X3xx), E series (E3xx) and N series (N3xx). For details on the hardware, software, and process required to build custom USRP FPGA images that include RFNoC blocks, see the [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP Build Documentation] in the UHD and USRP Manual.

It is recommended that you learn how to build an FPGA image for your USRP and download it to the device before starting this guide if you have never done so before. This will ensure you have all the necessary software installed.

==Introduction to RFNoC==

===What is RFNoC?===

RFNoC™ is a heterogeneous processing framework used to implement high-throughput DSP in the FPGA for Software Defined Radio (SDR) systems in an easy-to-use and flexible way. It provides all the infrastructure required to insert signal-processing IP into the FPGA logic and communicate with it through software. It also provides highly-optimized software and FPGA code to enable high-performance streaming to and from IP blocks on the USRP device.

The IP blocks in RFNoC are called ''RFNoC blocks''. The RFNoC blocks wrap the IP and provide a custom interface to the RFNoC infrastructure through a tool-generated interface called the ''NoC Shell''. Many standard blocks are included in UHD 4.0. These blocks enable typical operation of the USRP and allow RFNoC to connect to the different hardware components of the USRP. Several of the included blocks are described in the section [[#Available RFNoC Blocks|Available RFNoC Blocks]]. You can mix the available blocks for your application, or develop your own custom RFNoC blocks with your own IP to open up new applications. The NoC Shell hides the complexity of RFNoC from your block, making it easy to plug your IP into the USRP.

RFNoC is used on all Generation-3 USRPs and is installed with UHD 4.0. USRPs ship with a default RFNoC image that can be used as is, or can be modified and/or customized to suite your application. So if you're using a modern USRP, it's running RFNoC under the hood even if you haven't customized anything.

===Example RFNoC Image===

The diagram below shows a simplified view of an RFNoC FPGA image that is similar to the default images available on USRPs.

<br>
[[File:simplified_rfnoc_image_uhd_4.png|center]]
<br>

Notice that an RFNoC FPGA is made up of several components. A description of each one is provided below.

* '''RFNoC Image Core'''<br>This is the main block of the RFNoC framework and instantiates the components that make up RFNoC. The contents of the image core are described by an RFNoC image core YAML file, and the Verilog code that represents this block is automatically generated by the RFNoC Image Builder tool based on the YAML description. In other words, you provide a description of what you want to be included in RFNoC and the tools generate the code to implement that description.
* '''Transport Adapter'''<br>The transport adapter is a component of the USRP that allows communication with an outside interface. These vary depending on the USRP model in use. For example, this could be a 10 Gbps Ethernet link for SFP+ port of the USRP, or a cabled PCIe interface.
* '''CHDR Crossbar'''<br>The CHDR crossbar is a dynamic router for RFNoC traffic. This is a high-throughput crossbar designed for RF streaming applications. It is reconfigurable at run time via software and can be used to configure routes between stream endpoints and transport adapters. The number of ports available is configurable by changing the RFNoC image core YAML file. CHDR (Condensed Hierarchical Datagram for RFNoC) refers to the network protocol that is used for RFNoC.
* '''Stream Endpoint (SEP)'''<br>The stream endpoint (SEP) provides the high-level flow control for traffic over the network. It also separates control traffic from data traffic to create a separate AXIS-Ctrl network for control traffic. Control traffic refers to things like register reads and writes for configuring and monitoring RFNoC blocks.
* '''Control Crossbar'''<br>The control crossbar is similar to the CHDR Crossbar, but is only for control traffic. It has a much lower throughput and has been optimized for control-traffic, making it much less resource intensive than the CHDR crossbar.
* '''Other Blocks'''<br>The DDC (digital down converter), DUC (digital up converter), and Radio in this example are RFNoC blocks that are included with UHD. These are standard components included the default USRP images and enable typical RF applications. Most blocks only communicate with the RFNoC network, but some blocks require access to external hardware interfaces, such as the radio or DRAM. In this example, the radio blocks connect to the radio hardware on the USRP.

===Static vs. Dynamic Routing===

The routes between blocks that go through the crossbar are ''dynamic''. That is, the routes can be changed at run time and are controlled by software. The CHDR crossbar is very powerful in that it allows any of its ports to communicate with each other. It allows for streaming between blocks on the same FPGA, between RFNoC blocks and a host computer, or between blocks on different USRPs. New signal processing chains can be added to this crossbar, as needed, for the application.

Similarly, the control crossbar supports dynamic routing, allowing any RFNoC block to send control traffic to any other RFNoC block, even to blocks on a different USRP. Control traffic can also be sent from the host computer to the RFNoC blocks, for example to read/write registers. Additionally, RFNoC blocks can send control to the host computer. In this example, the Radio block sends control traffic to the computer to report specific events, such as overflow or underflow in the radio.

The block connections that don't go through a crossbar (e.g., the connection from the radio to the DDC, and the DDC to the stream endpoint, etc.) are ''static'' connections. That is, they cannot be changed at run time. Making a connection static has the advantage that it does not require additional ports on the crossbar and that the connection can be made much simpler because the high-level network flow-control protocol used by CHDR is not required. This reduces latency between blocks and leads to FPGA resource savings, allowing more logic be included in a single FPGA image. The static connections are described by the RFNoC image core YAML file. In order to change the static connections, the YAML description needs to be updated and the FPGA image needs to be rebuilt.

===RFNoC Customization===

The RFNoC framework makes it easy to customize the RFNoC image and add your own IP blocks. Later on in this guide, we'll explore how you can customize the RFNoC image to add or remove blocks, as well as create your own RFNoC blocks and include them in your FPGA builds. This allows you to create highly-customized and high-performance FPGA images for your USRP.

==Setting Up==
To use RFNoC in UHD 4.0 you need to perform the following:

* Clone the UHD repository
* Install UHD
* Update your device's filesystem and FPGA image

Building custom RFNoC images requires the FPGA source code and build system. These are included in the UHD repository, located in <code><repo>/fpga/usrp3/</code>, where <code><repo></code> refers to the location where you cloned the UHD repository.

Please see the [http://files.ettus.com/manual/page_install.html Binary Installation] for UHD installation documentation or [https://files.ettus.com/manual/page_build_guide.html Building and Installing] instructions to build and install UHD from source. Additionally, [[Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux|AN-445]] provides step-by step instructions for cloning the repository and installing UHD from source.

Starting with UHD 3.15, RFNoC is enabled by default, and starting with UHD 4.0, it can no longer be disabled, so no additional instructions are necessary to install support for RFNoC in UHD.

Many of the UHD utilities we will use in this guide are based on Python. Please ensure that your <code>PYTHONPATH</code> is set correctly. If not set correctly, you will see errors indicating that Python could not find the <code>uhd</code> or <code>image_builder</code> libraries. The correct setting may depend on where you installed UHD and which Linux distribution you are using. If you installed UHD from source to the default location on Ubuntu, you may need to add <code>/usr/local/lib/python3/dist-packages</code> to your <code>PYTHONPATH</code> variable. For example:

$ export PYTHONPATH=/usr/local/lib/python3/dist-packages

Instructions for updating your device's filesystem (applicable to E3xx and N3xx) and FPGA image can be found in that device's [https://kb.ettus.com/Getting_Started_Guides Getting Started Guide]. If your filesystem is already up to date, or your device does not use a filesystem (e.g., X3xx), then instructions on flashing an FPGA image to a device can be found in the following locations:

* [http://files.ettus.com/manual/page_usrp_x3x0.html#x3x0_load_fpga_imgs X3xx series]
* [http://files.ettus.com/manual/page_usrp_e3xx.html#e3xx_getting_started_fpga_update E3xx series]
* [http://files.ettus.com/manual/page_usrp_n3xx.html#n3xx_getting_started_fpga_update N3xx 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 your USRP device will likely lead to an error message but can brick the device under some circumstances.

===Configure the Default Shell===

Make sure you are using the <code>Bash</code> shell. Many of the build scripts used by RFNoC are written for <code>Bash</code>. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

==Testing the Default FPGA Image==

Before continuing, please verify that you have downloaded and flashed the latest FPGA image for your version of UHD. All FPGA images for Generation-3 and above devices are RFNoC images, so there is no requirement to download a special image for RFNoC.

===Inspect the Default Image===

Before we start customizing our FPGA, let's get familiar with the default FPGA image, which is pre-built with a set of RFNoC blocks.

Run the following command, with your USRP connected to your PC, to see what is available on the device.

$ uhd_usrp_probe --args type=x300

Note that your <code>args</code> may be different, depending on the USRP device you're using. The example here works for X300/X310. Refer to the manual page on [https://files.ettus.com/manual/page_identification.html Identifying USRP Devices] for more details. If an RFNoC image was successfully loaded onto the USRP, the output will show something like the following:

<nowiki> _____________________________________________________
/
| Device: X-Series Device
| _____________________________________________________
| /
| | Mboard: X310
| | revision: 11
| | revision_compat: 7
| | product: 30818
| | mac-addr0: 00:80:2f:17:40:6d
| | mac-addr1: 00:80:2f:17:40:6e
| | 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: 311EF81
| | FW Version: 6.0
| | FPGA Version: 38.0
| | FPGA git hash: be53058
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
...</nowiki>

More than this will likely be shown. The specifics of the output depend on the UHD version and which device you're running on. However, we're interested in the following sections:

* '''Device description'''. At the top, there is a section with basic information about your device, such as serial number, revision, etc. You can use this information to verify that you are indeed communicating with the correct device, and that the device has been updated. The FPGA git hash identifies the commit from which the FPGA image was built.
* '''RFNoC blocks on this device'''. This section lists all the RFNoC blocks in the loaded FPGA image. The blocks are listed by their block IDs. For example, <code>0/Radio#0</code> means that we're on device zero (<code>0/</code>), and we're talking about the first radio (with index <code>#0</code>). Unless you probe multiple devices at once by specifying multiple addresses in the <code>--args</code> argument, the device number will always be zero, but the block index will change depending on the number of blocks of that type. For example, on X310, <code>Radio#0</code> corresponds to RF A and <code>Radio#1</code> corresponds to RF B.
* '''Static connections on this device'''. This section lists how the blocks are pre-connected in the FPGA image. For example, the line <code>0/Radio#0:0==>0/DDC#0:0</code> means that radio zero, port zero (<code>:0</code>), is connected statically to DDC zero, port zero. Static connections can only be changed at compile time when building the FPGA image.

The connection endpoints labeled <code>SEP</code> are not RFNoC blocks. They are Stream Endpoints (SEPs). SEPs can send data packets to one another, or to streamers in software, using the CHDR crossbar, which is a dynamic router on the FPGA.

===Available RFNoC Blocks===

Many RFNoC blocks come with UHD. The HDL source code for these blocks resides in <code><repo>/fpga/usrp3/lib/rfnoc/blocks/</code>. several of the blocks are described below.

{| class="wikitable"
!Block Name
!HDL Name
!Description
|-
|AddSub
|<code>rfnoc_block_addsub</code>
|Add/Subtract Verilog/VHDL/HLS Example
|-
|DmaFIFO
|<code>rfnoc_block_axi_ram_fifo</code>
|FIFO that uses an AXI4 memory-mapped interface for storage. For use with external DRAM or on-chip SRAM.
|-
|DDC
|<code>rfnoc_block_ddc</code>
|Digital Down Converter
|-
|DUC
|<code>rfnoc_block_duc</code>
|Digital Up Converter
|-
|FFT
|<code>rfnoc_block_fft</code>
|Fast Fourier Transform
|-
|FIR
|<code>rfnoc_block_fir_filter</code>
|Finite Impulse Response Filter
|-
|Fosphor
|<code>rfnoc_block_fosphor</code>
|FFT and waterfall display tool
|-
|KeepOneInN
|<code>rfnoc_block_keep_one_in_n</code>
|Keep one sample/packet in N
|-
|LogPwr
|<code>rfnoc_block_logpwr</code>
|Computes an estimate of log2(i^2+q^2)
|-
|MovingAverage
|<code>rfnoc_block_moving_avg</code>
|Outputs the running average of the N most recent inputs of data stream
|-
|NullSrcSink
|<code>rfnoc_block_null_src_sink</code>
|Data source generator, sink, and loopback for testing
|-
|Radio
|<code>rfnoc_block_radio</code>
|Radio Interface
|-
|Replay
|<code>rfnoc_block_replay</code>
|Record/Playblack using AXI4 memory-mapped interface. For use with external DRAM or on-chip SRAM.
|-
|SigGen
|<code>rfnoc_block_siggen</code>
|Signal Generator. Supports sinusoidal, constant, and random outputs, with configurable gain.
|-
|SplitStream
|<code>rfnoc_block_split_stream</code>
|Splits a single data stream into two
|-
|Switchboard
|<code>rfnoc_block_switchboard</code>
|A configurable RFNoC datapath switch for testing
|-
|VectorIIR
|<code>rfnoc_block_vector_iir</code>
|Implements an IIR filter with variable length delay line
|-
|Window
|<code>rfnoc_block_window</code>
|Windowing module for use with FFT block
|}

===Streaming Example===

In the UHD installation directory, you'll find example applications (e.g., in <code>/usr/lib/uhd/examples/</code> or <code>/usr/local/lib/uhd/examples/</code>). We'll look at <code>rfnoc_rx_to_file</code> to familiarize ourselves with the RFNoC API.

If we look at the source code for this example (located at <code><repo>/host/examples/rfnoc_rx_to_file.cpp</code>), we can see the components necessary in an RFNoC application. In the <code>UHD_SAFE_MAIN</code> function, we create a few crucial objects, such as an RFNoC graph, a radio block controller, a DDC block controller, and an RX streamer.

uhd::rfnoc::rfnoc_graph::sptr graph = uhd::rfnoc::rfnoc_graph::make(args);
...
uhd::rfnoc::radio_control::sptr radio_ctrl =
graph->get_block<uhd::rfnoc::radio_control>(radio_ctrl_id);
...
uhd::rfnoc::ddc_block_control::sptr ddc_ctrl;
...
uhd::rx_streamer::sptr rx_stream = graph->create_rx_streamer(1, stream_args);

We also make connections in our graph and configure our blocks.

// Connect blocks and commit the graph
for (auto& edge : chain) {
if (uhd::rfnoc::block_id_t(edge.dst_blockid).match(uhd::rfnoc::NODE_ID_SEP)) {
graph->connect(edge.src_blockid, edge.src_port, rx_stream, 0);
} else {
graph->connect(
edge.src_blockid, edge.src_port, edge.dst_blockid, edge.dst_port);
}
}
...
rate = radio_ctrl->set_rate(rate);
...
radio_ctrl->set_rx_frequency(freq, radio_chan);

Once our graph and blocks are configured, we use the <code>recv_to_file</code> function to receive data from our device and write it to a file on our host computer. Running this example with the <code>--help</code> argument shows the available options. For example, to receive 3 seconds of data at a specific frequency and sample rate, we can run:

rfnoc_rx_to_file --args type=x300 --freq 2.4e9 --rate 10e6 --duration 3

Now you are ready to move to the next step and build your own blocks and FPGA images.

==RFNoC Image Builder==

UHD provides tooling to help develop custom RFNoC images. In this guide we will demonstrate how to use the RFNoC Image Builder, which will allow you to change which blocks are included and the connections between blocks. Let's go over common decisions you'll have to make with this tool.

* '''Blocks Included'''<br>The particular blocks to be included in the image is the most impactful decision you'll make in the image building process, both in terms of image functionality and FPGA resource utilization. Adding more blocks means more processing in the image, but it also means longer FPGA build times and less space in the FPGA.
* '''Static Connections'''<br>Recall that blocks can be statically connected, as opposed to connecting every block to the CHDR crossbar (dynamically connected). The number of dynamic connections has a large impact on the size of the CHDR crossbar, so static connections are used to lower resource utilization. However, once a block is statically connected in a chain of blocks, data cannot be sent between arbitrary blocks; it must traverse and be processed by each block in the order defined by the static connections.
* '''Hardware Connections'''<br>All blocks share some connections defined by the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification]. These connections are made automatically and cannot be changed. Many blocks require additional connections, such as clocks for the internal DSP or external DRAM interfaces. These connections must also be specified.

Now that we've gone over some of the considerations, let's look at how to actually build a custom RFNoC image. This begins with the RFNoC image core YAML description.

===Understanding the RFNoC Image YAML File===

The image YAML file defines RFNoC blocks in the FPGA image. It is designed to be both human-readable and machine-parseable, which allows us to make edits quickly and easily. Each device type has a default YAML image file, which is named <code><DEVICE>_rfnoc_image_core.yml</code> (e.g., <code>x310_rfnoc_image_core.yml</code>). Take a look at the RFNoC image core YAML file for the X310 by opening <code><repo>/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml</code>. Notice that it has the following sections.

* '''General Parameters'''<br>Here we define the device, the bit width of our CHDR connections, as well as some versioning and licensing.
* '''Stream Endpoints'''<br>In the <code>stream_endpoints</code> section we list each stream endpoint (SEP) that we wish to instantiate. These will be directly connected to the CHDR crossbar and will allow us to make dynamic connections within the CHDR crossbar. Typically you will have one SEP that forms the start and end of a single DSP chain of RFNoC blocks.<br>You can also add some per-stream-endpoint configuration here, such as the ingress buffer size, which affects streaming performance from your computer to that SEP. For example, if we know that one SEP will be receiving data transferred from your computer to the USRP then a data buffer is needed to accept those incoming packets, in which case we specify the buffer size by setting the <code>buff_size</code> option on that SEP. Alternatively, if we know that a particular SEP only sends data from the USRP to the computer, then we won't need the ingress data buffer and we can set <code>buff-size</code> to 0, thus saving FPGA resources.<br>Each SEP can have an AXIS-Ctrl and an AXIS-CHDR port, as indicated by the <code>ctrl</code> and <code>data</code> options. At least one AXIS-Ctrl port is required to communicate with the RFNoC blocks, so <code>ctrl</code> typically enabled on just the first SEP. Every SEP will usually have AXIS-CHDR connections to one or more RFNoC blocks, so <code>data</code> is usually enabled on all SEPs.
* '''NoC Blocks'''<br>In the <code>noc_blocks</code> section we specify all the RFNoC blocks to include in the FPGA image. We'll need to give each block a unique name and reference a block definition YAML file (which we'll discuss in a later section). The blocks chosen have the greatest impact on the functionality of the image, as well as providing very coarse control over the FPGA resource utilization. We'll look at how to change the blocks included in the image as part of our example below.
*'''Static Connections'''<br>The <code>connections</code> section defines static connections between blocks, stream endpoints, and various hardware interfaces on the USRP. Statically connected chains of blocks will usually start and end at a stream endpoint (SEP). SEPs are automatically connected to the CHDR crossbar by the RFNoC infrastructure. Remember that data must be passed through the entire statically connected chain; dynamic connections cannot be made to the statically connected blocks in the middle of the chain. Other hardware connections, such as to the external DRAM, would also be specified here. We'll take a closer look at making connections as part of our example below.
* '''Clock Domains'''<br>The <code>clk_domains</code> section defines which clocks to connect to each block's clock inputs. Some blocks do not need any clock connections beyond the base clocks required by RFNoC. These required connections are not listed here, since they are always the same for each block. Other blocks may require additional clocks. For example, the radio blocks should be connected to the <code>radio</code> clock. Many other blocks require a <code>ce</code> (Compute Engine) clock, which is used for the block's internal DSP.

===Running the Image Builder===

Before we look at editing the image core YAML file, let's go over how to use the RFNoC image builder to generate a bitstream from that YAML file. Additional details on how to run the image builder can be found with the <code>--help</code> option:

$ rfnoc_image_builder --help

Here are some of the options provided:
* '''<code>-y</code>''': Path to the RFNoC image core YAML file
* '''<code>-t</code>''': The image target you would like to build. These are the same targets that are used in the FPGA <code>make</code> process. More details on these can be found in the [https://files.ettus.com/manual/md_usrp3_build_instructions.html Generation 3 USRP Build Documentation] of the UHD and USRP Manual. If not specified, the default specified in the image core YAML file will be used.
* '''<code>-l debug</code>''': Use the <code>debug</code> log level. This prints more information about the FPGA connections and available port names, which can be useful for debugging connection errors in the YAML file.
* '''<code>--generate-only</code>''': Generate the HDL files required, but do not build the FPGA. Users can then build the FPGA later using <code>make <target></code>.
* '''<code>-I</code>''': Path to the directory containing out-of-tree block YAML descriptions (the YAML files installed with UHD are included by default). This option is only needed if using an out-of-tree RFNoC block.
* '''<code>-F</code>''': Path to the FPGA source code (e.g., <code><repo>/fpga</code>). This path is only required if the current working directory is not within the UHD repository.

For example, to build the default RFNoC image for X310, you might use the following command:

$ cd <repo>/fpga/usrp3/top/x300/
$ rfnoc_image_builder -y ./x310_rfnoc_image_core.yml -t X310_XG

In this example <code><repo></code> refers to the location where you cloned the UHD repository and should be replaced by the location you used. <code>x310_rfnoc_image_core.yml</code> is the default RFNoC image core YAML file for the X310, which is in the x300 project directory. <code>X310_XG</code> is the make target to use for the build. <code>XG</code> in this case refers to dual 10 Gbps Ethernet.

For an out-of-tree RFNoC block, you will also need to specify the location of the block information. For example:

$ rfnoc_image_builder -F <repo>/fpga -I <repo>/host/examples/rfnoc-example -y <repo>/host/examples/rfnoc-example/icores/x310_rfnoc_image_core.yml -t X310_XG

This example shows how to build an FPGA with the Gain example out-of-tree RFNoC block, which is located in <code><repo>/host/examples/rfnoc-example/</code>. The <code>-F</code> option is added to specify the location of the FPGA source, and <code>-I</code> specifies the location of the out-of-tree block YAML.

The image builder performs several steps in order to build the FPGA image from the image coure YAML:

# It generates the <code><device>_rfnoc_image_core.v</code> file. This file includes the Verilog code described by the YAML image core file. A <code><device>_static_router.hex</code> file is also generated. This file describes the static connections that should be made by the Verilog code. In the case of the X310 examples above, the output files would be named <code>x310_rfnoc_image_core.v</code> and <code>x310_static_router.hex</code>, and would be placed in the project directory for the X310 (<code><repo>/fpga/usrp3/top/x300/</code>).
# The image builder will configure the environment for building the FPGA. This is equivalent to sourcing the <code>setupenv.sh</code> script for the device type being built. For example, in our example above, it would run <code>source <repo>/fpga/usrp3/top/x300/setupenv.sh</code>.
# The image builder runs <code>make <target></code> to build the IP and the FPGA bitstream for the indicated target. The generated <code>rfnoc_image_core.v</code> and <code>static_router.hex</code> are automatically pulled into this build. The completed bitstream will be located in <code><repo>/fpga/usrp3/top/{project}/build</code> directory, which is the same directory created through the normal make process. For example, for X310 it would be located in <code><repo>/fpga/usrp3/top/X300/build</code>.

===Example: Adding an FFT Block===

As an example, let's run through how to modify the YAML file to modify the RFNoC image. Suppose we have an application that we'd like to run on a USRP X310 and we would like to offload the FFT processing to the FPGA. UHD provides an FFT RFNoC block, and the default X310 image has some extra space in it, so we should be able to add this block. First, we copy the default X310 image core file, named <code>x310_rfnoc_image_core.yml</code>.

$ cd <repo>/fpga/usrp3/top/x300/
$ cp x310_rfnoc_image_core.yml x310_with_fft.yml

Now open <code>x310_with_fft.yml</code> in your favorite text editor. We'll start by making some room for our new block. The default images use very large ingress FIFO buffers for the main SEPs to maximize streaming performance. But we want to make sure we have enough memory buffer space for our new blocks. So Start by reducing the <code>buf_size</code> parameters for <code>ep0</code> and <code>ep2</code> from 65536 to 32768. If using a device other than X310, the numbers may be different, but you can similarly reduce the <code>buff_size</code> parameter by half. On smaller devices, it may be necessary to remove the Replay block to make room for the FFT blocks. After making the changes on X310, the result should look like the following:

stream_endpoints:
ep0: # Stream endpoint name
ctrl: True # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 32768 # Ingress buffer size for data
...
ep2: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 32768 # Ingress buffer size for data

Now we can add our FFT block. We'll put it on its own stream endpoint, so we first need to add a new stream endpoint. Add the following to the <code>stream_endpoints</code> section:

stream_endpoints:
...
ep_fft: # The name can be incremented from previous SEP
ctrl: False # Only the first SEP needs control traffic
data: True # We do want to pass data through this SEP
buff_size: 32768 # Ingress buffer size for data

In this example, we've named the SEP <code>ep_fft</code>. Other names could be given, as long as the name is unique (it does not have to be numbered). Now that we've allocated an SEP for our block, we need to instantiate the actual block. In the next section, add the following:

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft_1x64.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
EN_FFT_SHIFT: 1

Again, the name <code>fft0</code> is arbitrary, but the name must be unique. In some cases, there will also be block parameters you'll want to pass, such as the data format of the FFT output data. In our example, we're setting <code>EN_FFT_SHIFT</code> parameter to 1, which causes the FFT block to center the zero frequency bin.

Now that we've added our FFT block, we need to connect it to the stream endpoint. In the next section of the YAML file, we add the static connections:

connections:
...
- { srcblk: ep_fft, srcport: out0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep_fft, dstport: in0 }

This connects the output of SEP <code>ep_fft</code> to the input of block <code>fft0</code>, and the output of <code>fft0</code> to the input of <code>ep_fft</code>. Since we're placing the FFT block on its own SEP, the only connections we need to make are between the SEP and the FFT. All SEPs are automatically connected to the CHDR crossbar, so this effectively connects the FFT block to the crossbar, allowing it to communicate with anything on the RFNoC network.

The names of block ports are defined in the YAML descriptions for the blocks. Blocks can use any names for their ports, and they don't have to be numbered (unless the number of ports is parameterized). Generally, the block ports are named <code>in_N</code> for inputs to the block and <code>out_N</code> for outputs. SEP ports are named <code>in0</code> for the input <code>out0</code> for the output.

If you are having trouble connecting a block due to an unresolved connection, running <code>rfnoc_image_builder</code> with the <code>-l debug</code> option will list all available block ports.

Finally, the FFT block has an additional clock input port named <code>ce</code> that is used for the FFT signal processing. We need to connect it to a clock domain. Any clock that's at least as fast as the incoming data rate should be sufficient. For example, X3xx devices have a <code>ce</code> clock (214.286 MHz) that is usually a good choice, but <code>rfnoc_chdr</code> clock (200 MHz) should also work for this example. For N31x and E3xx devices, <code>rfnoc_chdr</code> clock is a good choice (200 MHz on N31x and 100 MHz on E3xx). For N32x, <code>radio</code> clock (250 MHz) is a good choice. For example, this is how you would connect the X310's <code>ce</code> clock to the <code>ce</code> port of the FFT block:

clk_domains:
...
- { srcblk: _device_, srcport: ce, dstblk: fft0, dstport: ce }

And this is how you would connect <code>rfnoc_chdr</code> clock to the <code>ce</code> port:

clk_domains:
...
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

And finally, this is how you would connect <code>radio</code> clock:

clk_domains:
...
- { srcblk: _device_, srcport: radio, dstblk: fft0, dstport: ce }

The source block name <code>_device_</code> is special and refers to the USRP device itself. Choose a clock that's apprpriate for your device and connect it as shown above.

And that's it! The next step will be to run the image builder on our modified YAML file. Once that's done, and the bitstream has been created, you can load it onto your USRP X310 device, and verify the blocks, as we did in the [[#Inspect_the_Default_Image|Inspect the Default Image]] section.

For example, from the X300 directory, you would run the following command to run the image builder:

$ rfnoc_image_builder -y x310_with_fft.yml -t X310_XG

To download the FPGA bitstream to the X310, run the following:

$ uhd_image_loader --args "type=x300,addr=192.168.30.2" --fpga-path ./build/usrp_x310_fpga_XG.bin

You may need to change the IP address to match your device, depending on your configuration. After completing the flash update and power-cycling the USRP, run <code>uhd_usrp_probe</code> to confirm that the FFT block was recognized.

$ uhd_usrp_probe --args "type=x300,addr=192.168.30.2"

Take a look at the RFNoC blocks and the static connections on the device. You should see the following new blocks and connections:

| _____________________________________________________
| /
| | RFNoC blocks on this device:
...
| | * 0/FFT#0
...
| _____________________________________________________
| /
| | Static connections on this device:
...
| | * 0/SEP#6:0==>0/FFT#0:0
| | * 0/FFT#0:0==>0/SEP#6:0
...


===Example: Adding an FFT Block to the Receive Chain===

Now that we've added the FFT block and verified that it is operating as expected, let's see if we can modify it a little. Let's say that we're sure that we always want to receive the FFT bins from our device, and we don't want to see the raw samples. In order to save some FPGA resources, we can move our FFT block to be between the DDC and the SEP, on the RX data path. Instead of the previous modifications to our YAML file, we want the following:

stream_endpoints:
...
# Unchanged from the default image core (no need for ep_fft).

noc_blocks:
...
fft0: # FFT block name
block_desc: 'fft_1x64.yml' # Block YAML descriptor file
parameters: # Specify any Verilog module parameters (optional)
EN_FFT_SHIFT: 1

connections:
...
# Change this line:
# - { srcblk: ddc0, srcport: out_0, dstblk: ep0, dstport: in0 }
# Change it to the following to add fft0 between ddc0 and ep0:
- { srcblk: ddc0, srcport: out_0, dstblk: fft0, dstport: in_0 }
- { srcblk: fft0, srcport: out_0, dstblk: ep0, dstport: in0 }

clk_domains:
...
# As before, we still connect our FFT block to the clock domain
- { srcblk: _device_, srcport: rfnoc_chdr, dstblk: fft0, dstport: ce }

This last line is valid for E310/E320; for X300/X310/N300/N310/N320/N321 use the following:

- { srcblk: _device_, srcport: ce, dstblk: fft0, dstport: ce }

And as simply as that, we have added the FFT block to our RX block chain. Remember that this is a static connection, so when the resulting FPGA image is loaded onto your device, you will no longer be able to receive samples from the DDC directly; all samples on that chain will be processed by the FFT block, and you will only receive FFT bins from this radio chain.

==Out-of-tree Modules==

===OOT Overview===

Now that we've gone over what is provided by UHD, let's start to look at custom RFNoC development. It's recommended that custom RFNoC development be kept separate from the in-tree UHD RFNoC infrastructure and examples, in order to simplify version control and licensing. Modules located outside of the repository are called ''out-of-tree'' (OOT).

In order to understand how OOT modules for RFNoC are created, let's take a look at the example that's provided with UHD. You can find the example located in <code><repo>/host/examples/rfnoc-example/</code>. This example includes a simple Gain RFNoC block that we can use as a reference for creating our own OOT blocks.

===OOT Subdirectories===

Take a look at the <code>rfnoc-example</code> directory structure. An OOT module is a collection of block implementations, the software controllers for those blocks, and sometimes applications to demonstrate their functionality. These different components within the OOT module are organized into the directories described below.

* HDL and Image Resources
** <code>fpga/</code>: Contains the HDL (e.g., Verilog) required for the module. Each RFNoC block should have its own subdirectory here, such as <code>rfnoc_block_gain</code>, for the Gain block.
** <code>blocks/</code>: Contains the YAML RFNoC block definition files. These describe the block's interfaces and are used by the image builder. We'll go into more detail with regards to what goes into these YAML files in the [[#Creating_Your_Own_RFNoC_Block|Creating Your Own RFNoC Block]] section.
** <code>icores/</code>: Contains example FPGA image core YAML files, to demonstrate how to create an FPGA image using your custom blocks. These image core files may demonstrate important parameters or show recommended configurations for chains of blocks.
* Block Controller and Example Software
** <code>include/</code>: Contains the headers for the block controller software. Once installed, these headers will be used by UHD and other applications to interface with and control your custom RFNoC blocks.
** <code>lib/</code>: Contains the block controller implementations. The files here should implement the features outlined in the headers located in the <code>include/</code> directory. All unit test code should also be located here.
** <code>apps/</code>: Contains example applications for your custom blocks. These applications may demonstrate how to use the block controllers, common configurations, or how to process data from your blocks.
* Infrastructure
** <code>cmake/</code>: Contains any custom CMake commands the module may need. In general, simple modules will not need to modify this directory at all. More complicated modules with additional external dependencies may need to modify this.

Take some time to explore the files in the <code>rfnoc-example</code>. Note the following files and directories related to the Gain example:

* <code>rfnoc-example/fpga/rfnoc_block_gain/</code><br>This is the HDL for the Gain RFNoC block.
** <code>rfnoc_block_gain.v</code><br>The top-level synthesizable file for the Gain block
** <code>noc_shell_gain.v</code><br>The NoC Shell for the Gain block
** <code>rfnoc_block_gain_tb.sv</code><br>The simulation testbench
** <code>Makefile</code><br>The simulation Makefile
* <code>rfnoc-example/blocks/gain.yml</code><br>The YAML block definition file for the Gain block
* <code>rfnoc-example/icores/x310_rfnoc_image_core.yml</code><br>An example RFNoC image core YAML description showing how to connect the Gain block
* <code>rfnoc-example/include/rfnoc/example/gain_block_control.hpp</code><br>The software block controller header
* <code>rfnoc-example/lib/gain_block_control.cpp</code><br>The software block controller implementation
* <code>rfnoc-example/apps/init_gain_block.cpp</code><br>An example showing how to find and initialize the Gain block


===Creating Your Own OOT Module===

To create your own OOT module, make a copy of the <code>rfnoc-example</code> directory. This will contain all the subdirectories and infrastructure files that you need to create your custom module. The directory name for your copy should be renamed to your desired name; we recommend something like <code>rfnoc-foo</code>, for example, where <code>foo</code> is the name for your OOT module. You'll also need to change <code>rfnoc-example</code> within the module's <code>CMakeLists.txt</code> files to your module's name.

Let's start by creating our own copy of the <code>rfnoc-example</code> to work with. We'll call our module <code>demo</code>. You can put the copy wherever you like, but for this example we'll put it in our home directory.

$ cp -r <repo>/host/examples/rfnoc-example ~/
$ mv ~/rfnoc-example ~/rfnoc-demo

Now we need to edit our <code>CMakeLists.txt</code> files to rename our module. Edit the following files and change all instances of <code>rfnoc-example</code> to <code>rfnoc-demo</code>:

~/rfnoc-demo/CMakeLists.txt
~/rfnoc-demo/lib/CMakeLists.txt

===Building and Installing an OOT Module===
The OOT module will need to be built and installed in order to use its RFNoC blocks. To build and install the OOT module we just created, do the following:

$ mkdir ~/rfnoc-demo/build
$ cd ~/rfnoc-demo/build
$ cmake -DUHD_FPGA_DIR=<repo>/fpga/ ../

This configures the project to be installed in the default location. You may want to provide a different install directory to CMake using the <code>-DCMAKE_INSTALL_PREFIX</code>. Please refer to the [https://files.ettus.com/manual/page_build_guide.html UHD Installation Guide] or the installation guide for other CMake-based projects for instructions on configuring CMake.

Note that we specify the location of the FPGA source code using the <code>-DUHD_FPGA_DIR</code> option. This allows you to run the FPGA testbenches and to build the example FPGA image provided with the OOT example.

At this point, you can run <code>make help</code> to see what options are available. A few of the available make targets are described below:

* <code>make rfnoc-demo</code>: Build the block controllers for the RFNoC blocks
* <code>make testbenches</code>: Run the testbenches for the RFNoC blocks
* <code>make x310_rfnoc_image_core</code>: Build the FPGA example image
* <code>make install</code>: Install the module

To build and install the block, perform the following steps.

$ cd ~/rfnoc-demo/build
$ make
$ make install

Note that <code>sudo</code> may be required depending on the install location.

===Building an FPGA Image with OOT Blocks===

At this point you can build the example FPGA that's included in the <code>icores</code> directory. Take a look at <code>~/rfnoc-demo/icores/x310_rfnoc_image_core.yml</code>. Note that the <code>gain</code> block is added in exactly the same way that the FFT block was in [[#Example:_Adding_an_FFT_Block|Example: Adding an FFT Block]]. You can build this example FPGA for the X310 using the following steps:

$ cd ~/rfnoc-demo/build
$ make x310_rfnoc_image_core

Alternatively, you can call <code>rfnoc_image_builder</code> directly. In order to get the image builder to find your custom blocks, you may need to supply some additional arguments to find the OOT module, as shown in the following example:

$ rfnoc_image_builder -F <repo>/fpga –I ~/rfnoc-demo/include/rfnoc -y ~/rfnoc-demo/icores/x310_rfnoc_image_core.yml

The <code>-I</code> option is only required if the OOT module has not been installed on the system. 

If you have an X310, you can build and use the provided example to test the Gain block. If you have a different USRP, you can use its default <code>rfnoc_image_core.yml</code> as a starting point and follow the same steps that we followed for the FFT block in [[#Example:_Adding_an_FFT_Block|Example: Adding an FFT Block]], then build it using the process described above.

===Testing the Gain Example===

After building an FPGA image for your USRP and downloading it to your device, the Gain block should be available. Test this by running <code>uhd_usrp_probe</code>:

$ uhd_usrp_probe --args "type=x300,addr=192.168.30.2"

Again, note that your <code>args</code> may be different or may not be required if you only have a single USRP connected.

Take a look at the RFNoC blocks and the static connections on the device. You should see the following new blocks and connections:

| _____________________________________________________
| /
| | RFNoC blocks on this device:
...
| | * 0/Block#0
...
| _____________________________________________________
| /
| | Static connections on this device:
...
| | * 0/SEP#4:0==>0/Block#0:0
| | * 0/Block#0:0==>0/SEP#4:0
...

==Creating Your Own RFNoC Block==

The Gain block is a useful example and could even be used as the starting point for a new block, but rather than trying to copy and edit the Gain block, it is best to use the RFNoC ModTool to create a new block template. This is also required if you want to change the interfaces provided to your IP that are exposed by the NoC Shell.

===Understanding the Block Definition YAML===

The first step in creating a new block is to write a YAML description for the block that you want to create. The options available are described [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification]. You can also look at the blocks available in <code><repo>/host/include/uhd/rfnoc/blocks/</code> for examples. We'll provide a brief overview here.

Open up and take a look at the Gain block definition located in <code>~/rfnoc-demo/blocks/gain.yml</code>. Notice the different sections, which are described below:

* '''General Parameters'''<br>In this section we give our block a name (<code>module_name</code>) and a unique block ID (<code>noc_id</code>). The NoC ID is an arbitrary 32-bit number that will be used by the software to identify the block during system discovery. You can also specify the CHDR bus width, which should be 64 for Generation-3 USRPs.
* '''Clocks'''<br>In the <code>clocks</code> section, we define the clocks that will be used by the block. The <code>rfnoc_chdr</code> and <code>rfnoc_ctrl</code> clocks are required. Many blocks also have a <code>ce</code> clock for internal DSP.
* '''Control Interface'''<br>The <code>control</code> section defines what type of control interface to make available to your block. The control interface is used for register reads and writes. Most blocks do not need to modify this section and will use the <code>ctrlport</code> interface type. Control Port is the standard register interface used by RFNoC. The <code>clk_domain</code> parameter allows you to specify which clock domain to use for the register interface exposed to your block. Typically this is the same clock that is used for the <code>data</code> interface, to avoid clock crossings.
* '''Data Interface'''<br>The <code>data</code> section defines what type of data interface to make available to your block and describes the ports. Most blocks use either the <code>axis_pyld_ctxt</code> or the <code>axis_data</code> interface types.<br>The <code>clk_domain</code> parameter allows you to specify which clock domain to use for the data interfaces exposed to your block. Typically this is the same clock that is used for the <code>control</code> interface, to avoid clock crossings.<br>Under the <code>inputs</code> and <code>outputs</code> sections you can describe the input and output ports.
* '''IO Ports'''<br>The <code>io_ports</code> section is used to describe other device-specific ports to which your block needs to connect (such as the DRAM or radio interfaces). For most blocks, this section is not used.

A few other sections might be present in the YAML file (e.g., <code>registers</code> or <code>properties</code>). These sections are reserved for future use and can be left empty.

===Starting Your Own Block Definition===

Let's start by making a copy of the Gain block YAML for our use case.

$ cp ~/rfnoc-demo/blocks/gain.yml ~/rfnoc-demo/blocks/demo.yml

Now open the <code>demo.yml</code> file you just created and make the following changes:

# Change the name of the block from <code>gain</code> to <code>demo</code>
# Change the <code>noc_id</code> to <code>0x0000DE30</code>
# Change the <code>format</code> for the <code>in</code> and <code>out</code> ports from <code>int32</code> to <code>sc16</code>.

This YAML file now describes a block with the following features:

* The block named "demo"
* NoC ID of 0xDE30
* CtrlPort register interface on the <code>rfnoc_chdr</code> clock domain
* A single 32-bit input port named "In" on the <code>rfnoc_chdr</code> clock domain that will provide sc16 samples to your IP
* A single 32-bit output port named "Out" on the <code>rfnoc_chdr</code> clock domain that will receive sc16 samples from your IP

===Generating Your Block Using the ModTool===

Now that we have a block definition YAML file, we can generate the source code templates and NoC Shell for our block. To do so, run the following command:

$ python3 <repo>/host/utils/rfnoc_blocktool/rfnoc_create_verilog.py -c ~/rfnoc-demo/blocks/demo.yml -d ~/rfnoc-demo/fpga/rfnoc_block_demo

This will create a folder named <code>~/rfnoc-demo/fpga/rfnoc_block_demo</code> with an RFNoC block template for you to use. Explore the folder that was created. You should see the following files:

* '''<code>Makefile</code>''': This is the Makefile for the simulation testbench. See [https://files.ettus.com/manual/md_usrp3_sim_running_testbenches.html Running a Testbench] in the UHD and USRP Manual for instructions on how to run a testbench.
* '''<code>Makefile.srcs</code>''': This is another makefile that identifies the HDL source code that makes up your RFNoC block.
* '''<code>noc_shell_demo.v</code>''': This is the NoC Shell that was generated for your block. It provides the interfaces described in the block definition YAML.
* '''<code>rfnoc_block_demo.v</code>''': This is a template for your RFNoC block. It includes all the top-level ports required by RFNoC and instantiates the NoC Shell.
* '''<code>rfnoc_block_demo_tb.sv</code>''': This is a testbench template for your RFNoC block. It instantiates your RFNoC block and the bus functional models (BFMs) needed to communicate with your block in simulation.

Take a moment to look at the <code>rfnoc_block_demo.v</code> and <code>rfnoc_block_demo_tb.sv</code> files that were generated for your block. Notice the "User Logic" section towards the end of the <code>rfnoc_block_demo</code> module. This is the location where you can insert your own IP.

The input data samples come in on the <code>m_in_payload</code> AXI4-Stream bus. The output data samples go out on the <code>s_out_payload</code> AXI4-Stream data bus.

If your input packets are the same size as your output packets (i.e., for every sample in you generate one sample out) then the <code>m_in_context</code> data bus can be used to drive <code>s_out_context</code>. The context bus is described in detail in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

Similarly, the testbench has a section where you can add your own test sequences to the test bench.

If you decide you need to change the RFNoC interfaces for your block (e.g., add ports, or change the interface type), then it is recommended to update the block definition YAML then regenerate the block. Please take care to not overwrite any code you have written when regenerating the files for your block! Rerunning the tool will cause new files to be generated, with a new NoC Shell, and will demonstrate how to update your code for the new interfaces.

Refer to the Gain example and other RFNoC blocks for examples of how to complete your RFNoC block logic and testbenches.

==Summary==

In this guide we have given a brief introduction on how to develop for RFNoC in UHD 4.0. There's a lot more you can do than is described here, but this will hopefully get you started. Happy coding!

Using the RFNoC Replay Block in UHD 4

2022-02-04T13:43:12Z

MartinBraun: /* Building the FPGA */

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to build and load
an FPGA image which includes this block. See ... for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
For example, the <code>axi_intercon_2x64_128_bd</code> IP used by the X310 is
configured to give each connected device an address space of 32 MiB. As a
result, the Replay block will be limited to this amount of memory. The
<code>axi_intercon_2x64_128_bd</code> file must be modified if more than 32 MiB needs to be buffered.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. The <code>num_samps</code>
parameter is a 28-bit value, limiting this mode of playback to 2<sup>28</sup>
words at a time. Playback can be stopped by issuing a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory alignment and word sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

==Building Custom FPGA Images with a Replay Block==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location ~/src/uhd.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

==Building the FPGA==

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram } MEM_ADDR_W: 30
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section.
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Using the RFNoC Replay Block

2022-02-04T13:42:46Z

MartinBraun:

==Application Note Number==
'''AN-642'''

==Abstract==
This application note guides a user through basic use of the
RFNoC Replay block in UHD 3.x and explains how to run the UHD Replay example. This example covers use on the X300/X310 and N310 products. UHD 4.0 and later is not covered in [[Using the RFNoC Replay Block 4.0]].

==Overview==
The Replay block is an RFNoC block that allows recording and playback of arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay block, it must be instantiated in the design and connected to the DRAM interface. It can take the place of the DMA FIFO(s) or be used concert with the DMA FIFO(s). In this note we will be replacing the DMA FIFO block with the Replay block and running a UHD example that records data to DRAM from a file then plays it back over the radio continuously.

==Prerequisites==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Your system must be configured for RFNoC development to compile and use the RFNoC examples. Here we briefly explain how to setup a system to build and run the RFNoC Replay example.

'''Note:''' Refer to Application Note AN-823 [[Getting Started with RFNoC Development]] for a more detailed overview of RFNoC development.

To begin, use the following <code>git clone</code> command to download the needed UHD repository. The <code>--recursive</code> option causes the latest compatible FPGA code to also be cloned into the <code>fpga-src</code> subfolder.

$ git clone --recursive https://github.com/EttusResearch/uhd.git

Then checkout the appropriate version of UHD that you intend to use. Replay block support was added in UHD 3.14. The latest UHD 3.x version is recommended.

$ git checkout UHD-3.15.LTS
$ git submodule update --recursive

===Building and Installing UHD===

If you have not already done so, follow the steps in Application Note '''AN-445''' under the heading [[Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux#Update_and_Install_dependencies|Update and Install dependencies]].

'''Note:''' Refer to Application Note [[Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux|AN-445]] for detailed instructions on building and installing UHD from the source code. However, RFNoC must be enabled when running CMake in order to run the RFNoC examples. The instructions below summarize the basic steps required to build and install UHD so that you can run the Replay example.

To build and install UHD, begin by opening a terminal in the UHD repository that you cloned, then create a <code>build</code> folder within the <code>host</code> host folder of the repository.

$ cd uhd/host
$ mkdir build
$ cd build

Run CMake with RFNoC enabled to create the Makefiles.

$ cmake -DENABLE_RFNOC=ON ../

Run Make to build UHD with RFNoC support.

$ make

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

$ sudo make install

Update the system's shared library cache.

$ sudo ldconfig

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

'''Note:''' the <code>LD_LIBRARY_PATH</code> location may vary depending on your Linux distribution.

$ export LD_LIBRARY_PATH=/usr/local/lib

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need to have the Xilinx development tools installed. The specific version required depends on the branch and state of the FPGA code. The UHD-3.13 branches require Vivado 17.4. Refer to the installation instructions for Vivado in order to install these tools. It is recommended that you use the default install location of <code>/opt/Xilinx/Vivado</code> to ensure compatibility with the FPGA build flow.

==Building the FPGA==

In order to use the Replay block, it must be built into the FPGA image for the USRP you plan to use. This is currently a manual step. The instructions below are for the X310, but similar instructions apply to the N310.

First, we must modify the Verilog code to include the Replay Block. To do this, modify the file <code>fpga-src/top/x300/x300_core.v</code> and change localparam <code>USE_REPLAY</code> from 0 to 1. This causes the FPGA code to instantiate <code>noc_block_replay</code> instead of <code>noc_block_axi_dma_fifo</code>. Note that the DMA FIFO will not be included in this example and therefore cannot be used.

'''Note:''' If using the N310, modify the file <code>fpga-src/top/n3xx/n3xx_core.v</code> and make the same change. Other products that support RFNoC can also use the replay block. However, in other products, the noc_block_replay instance would need to be manually instantiated in the code following the examples given in the <code>x300_core.v</code> and <code>n3xx_core.v</code> files.

After making the required code change, you are ready to rebuild the FPGA image. Begin by setting up the environment to use the FPGA build tools.

$ cd uhd/fpga-src/usrp3/top/x300
$ source ./setup.sh

Run make to build the desired FPGA image. For example, to build the X310 HG image, use the following command:

$ make X310_HG

Once compilation is complete, download the image to your USRP product. For example, if the X310 HG image were connected to SFP port 0 (1 Gigabit Ethernet) using the default IP address, then you would run the following command.

$ uhd_image_loader --args="type=x300,addr=192.168.10.2" --fpga-path=./build-X310_HG/x300.bit

After the download has completed, power cycle the X310 to load the new bitstream. Confirm that the Replay block appears in the system by running <code>uhd_usrp_probe</code>.

$ uhd_usrp_probe --args="addr=192.168.10.2"

You should see the <code>Replay</code> block listed among the RFNoC blocks on the device.

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

==Building the Replay Example==

In this section we will compile the replay_from_file UHD example. Begin by creating a CMake file for the Replay example using <code>uhd/host/examples/init_usrp/CMakeLists.txt</code> as an example.

$ cd uhd/host/examples
$ mkdir replay_samples_from_file
$ cd replay_samples_from_file
$ cp ../init_usrp/CMakeLists.txt ./

Edit <code>CMakeLists.txt</code> and change the <code>init_usrp</code> references to <code>replay_samples_from_file</code> and <code>init_usrp.cpp</code> to <code>../replay_samples_from_file.cpp</code>.

[[File:uhd cpp makefile edits.png|650px]]

You can now invoke CMake and run Make to build the example.

$ mkdir build
$ cd build
$ cmake ../
$ make

==Running the Example==

The <code>replay_samples_from_file</code> example assumes that you have a file containing the samples you wish to replay. This could be generated in advance or recorded using <code>rx_samples_to_file</code> or another method. For this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>) to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000 samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz. Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real and 16-bit imaginary components). We can run the program by invoking python from the command line.

$ python ./sample_gen.py

'''Note:''' The <code>replay_samples_from_file</code> example does not perform rate conversion (i.e., the the DUC is not used), so the rate specified must match the native sample rate of your device (i.e., 200 Msps for the X300/X310 or 125 Msps for the N310). The samples file should contain <code>sc16</code> data samples and should be a multiple of 2 samples (8 bytes) in size, since the Replay block records and plays back in multiples of 8 bytes. For example, for the N310 you could change <code>SAMPLE_RATE</code> in the Python program to 125.0e6, which would result in 64 periods of the 500 kHz tone.

To run the UHD Replay example, you could enter a command like the following.

$ ./replay_samples_from_file --freq 915e6 --gain 10 --file samples.dat

This example would stream the samples from the file to the Replay block on the FPGA, where they are recorded into the USRP's on-board DRAM, then would cause Replay block to play back the samples to the radio continuously with a base frequency of 915 MHz, creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.

==Using the Replay Block==

The Replay block is contained in <code>noc_block_replay.v</code>. This block works like a record and playback buffer that uses DRAM on the USRP to store samples. It connects to the RFNoC crossbar and to the DRAM in the same way that the <code>noc_block_axi_dma_fifo</code> block does. Data can be streamed to the block, like to any other RFNoC block. Playback is analogous to the way the <code>noc_block_radio_core</code> works when we ask it to receive radio samples.

One key difference is that the Replay block works only with 64-bit samples. Therefore, all addresses, buffer sizes, and transfers should be a multiple of 8 bytes. For example, when using <code>sc16</code> samples (4 bytes each) everything should be a multiple of two samples to ensure we are always working with multiples of 8 bytes.

'''Note:''' Refer to the example source code in <code>replay_samples_from_file.cpp</code> for a more detailed example of how to use the Replay block.

Prior to streaming data to the Replay block for recording, it is necessary to configure the base address and size of the record buffer.

// Configure the record buffer
replay_ctrl->config_record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives into the DRAM at byte offset <code>buffer_start_byte_address</code> and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is filled, recording automatically stops. Care should be taken to configure the memory buffers so that they do not overlap if more than one Replay block or buffer is being used simultaneously. The memory addresses and sizes should be 8-byte aligned.

'''Note:''' Care should be taken to not transfer more data to the Replay block than the size of the record buffer. Additional data is not accepted or dropped by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the size of the DRAM on the USRP and how the memory interface is configured on the USRP. For example, the <code>axi_intercon_2x64_128_bd</code> IP used by the X310 is configured to give each connected device an address space of 32 MiB. As a result, the Replay block will be limited to this amount of memory. The <code>axi_intercon_2x64_128_bd</code> file must be modified if more than 32 MiB needs to be buffered.

To begin recording data to the Replay block, the record logic should be initialized:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and it resets the internal counters that track how much data has been recorded. If a previous recording has taken place then it is a good idea to ensure that stale data was not queued up in the RF network on the FPGA from a previous run. The <code>replay_samples_from_file</code> example does this by calling <code>record_restart()</code> then waiting to see if any new data shows up unexpectedly in the record buffer. If so, it restarts recording then waits again to see if data continues to appear.

You can determine when all data has been received by checking the status of the record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected);

Prior to playing back recorded data, it is necessary to configure the base address and size of the playback buffer. To play back previously recorded data, set the start address to the same address that was used for the record buffer and set the size of the playback buffer to the match the amount of data that was recorded. Note that the record and playback buffers do not need to the same, allowing a single Replay block to both record and playback to different regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command. Playback automatically wraps around to the start of the buffer if more data is requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only the specified number of samples to be played once. The <code>num_samps</code> parameter is a 28-bit value, limiting this mode of playback to 2<sup>28</sup> words at a time. Playback can be stopped by issuing a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is received (DRAM reads are not aborted mid-transaction). As a result, some data will continue to stream from the Replay block after the stop command is issued while waiting for the DRAM read to complete and for all the internal buffers to empty. The <code>replay_samples_from_file</code> example determines when playback streaming has stopped by reading the 64-bit <code>SR_READBACK_REG_GLOBAL_PARAMS</code> register and waiting for the packet count to stop increasing.

Using the RFNoC Replay Block in UHD 4

2022-02-04T13:41:09Z

MartinBraun: Created page with "==Application Note Number== '''AN-642b''' ==Abstract== This application note guides a user through basic use of the RFNoC Replay block in UHD 4.x and explains how to run the..."

==Application Note Number==
'''AN-642b'''

==Abstract==

This application note guides a user through basic use of the RFNoC Replay block
in UHD 4.x and explains how to run the UHD Replay example. This example covers
the USRP X410, X310/X300, N300/N310/N320 and E320 devices. For UHD 3.x, please
refer to [[Using_the_RFNoC_Replay_Block|the UHD 3.x replay block Application Note]].

==Overview==

The Replay block is an RFNoC block that allows recording and playback of
arbitrary data using DRAM on the USRP hardware as a buffer. To use the Replay
block, it must be instantiated in the design and connected to the DRAM interface.

The replay block is a standard feature of UHD and RFNoC, and a custom compile of
UHD is not required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs, so when using these images,
the following examples can be run without any manual builds of UHD or FPGA images.

==Prerequisites==

To follow this application note, you need a device with a replay block instantiated,
and a UHD version recent enough to have the full support for the replay block
(UHD 4.2 and beyond). To test for the replay block capabilities, connect and
enable your USRP device, and run the following command:

uhd_usrp_probe --args <device args>

Depending on your device, the output could look like this (truncated):

_____________________________________________________
/
| Device: X400-Series Device
| _____________________________________________________
| /
| | Mboard: ni-x4xx-<serial>
| | pid: 1040
| | rev: 4
| | rev_compat: 4
| | serial: <serial>
| | MPM Version: 4.0
| | FPGA Version: 7.6
| | FPGA git hash: <hash>.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, qsfp0, gpsdo
| | Clock sources: mboard, internal, external, nsync, gpsdo
| | Sensors: ...
| _____________________________________________________
| /
| | RFNoC blocks on this device:
| |
| | * 0/DDC#0
| | * 0/DDC#1
| | * 0/DUC#0
| | * 0/DUC#1
| | * 0/Radio#0
| | * 0/Radio#1
| | * 0/Replay#0
| _____________________________________________________
| /
| | Static connections on this device:
| |
| | * 0/SEP#0:0==>0/DUC#0:0
| | * 0/DUC#0:0==>0/Radio#0:0
| | * 0/Radio#0:0==>0/DDC#0:0
| | * 0/DDC#0:0==>0/SEP#0:0
| | * 0/SEP#1:0==>0/DUC#0:1
| | * 0/DUC#0:1==>0/Radio#0:1
| | * 0/Radio#0:1==>0/DDC#0:1
| | * 0/DDC#0:1==>0/SEP#1:0
| | * 0/SEP#2:0==>0/DUC#1:0
| | * 0/DUC#1:0==>0/Radio#1:0
| | * 0/Radio#1:0==>0/DDC#1:0
| | * 0/DDC#1:0==>0/SEP#2:0
| | * 0/SEP#3:0==>0/DUC#1:1
| | * 0/DUC#1:1==>0/Radio#1:1
| | * 0/Radio#1:1==>0/DDC#1:1
| | * 0/DDC#1:1==>0/SEP#3:0
| | * 0/SEP#4:0==>0/Replay#0:0
| | * 0/Replay#0:0==>0/SEP#4:0
| | * 0/SEP#5:0==>0/Replay#0:1
| | * 0/Replay#0:1==>0/SEP#5:0
| | * 0/SEP#6:0==>0/Replay#0:2
| | * 0/Replay#0:2==>0/SEP#6:0
| | * 0/SEP#7:0==>0/Replay#0:3
| | * 0/Replay#0:3==>0/SEP#7:0

The output tells us that this USRP has a Replay block instantiated (<code>0/Replay#0</code>).
It has four static connections to stream endpoints, which also tells us that
this is a four-port replay block.

If your device does not report a replay block, then you need to build and load
an FPGA image which includes this block. See ... for instructions on how to do
this before you proceed. If it does report a block, you can move to the next
section.

==Running the Example==

The <code>rfnoc_replay_samples_from_file</code> example assumes that you have a
file containing the samples you wish to replay. This could be generated in
advance or recorded using <code>rx_samples_to_file</code> or another method. For
this demonstration, we'll create a simple Python program (<code>sample_gen.py</code>)
to generate some samples to use:

import math
import struct

SAMPLE_RATE = 200.0e6 # Sample rate in Hz
FREQUENCY = 500.0e3 # Frequency of sinusoid to generate, in Hz
NUM_SAMPLES = 16000 # Number of samples to generate
AMPLITUDE = 0.5 # Amplitude of the signal (from 0 to 1.0)
FILE_NAME = 'samples.dat'

file = open(FILE_NAME, 'wb')

for i in range(NUM_SAMPLES):
I = int((2**15-1) * AMPLITUDE * math.cos(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
Q = int((2**15-1) * AMPLITUDE * math.sin(i / (SAMPLE_RATE / FREQUENCY) * 2 * math.pi))
file.write(struct.pack('<2h', I, Q))

file.close()

This program generates a file named <code>samples.dat</code> that contains 16000
samples (40 periods) of a 500 kHz tone sampled at a rate of 200 MHz.
Each sample is saved in <code>sc16</code> format (signed complex with 16-bit real
and 16-bit imaginary components). We can run the program by invoking python from
the command line.

$ python ./sample_gen.py

To run the UHD Replay example, enter a command like the following (the path to
the examples depends on your installation method, for a normal installation via
apt-get, examples will be located in <code>/usr/lib/uhd/examples</code> or
<code>/usr/local/lib/uhd/examples</code>).

$ cd /path/to/examples
$ ./replay_samples_from_file --args <device args> --freq 915e6 --gain 10 --file samples.dat --rate 200e6

This example would stream the samples from the file to the Replay block on the
FPGA, where they are recorded into the USRP's on-board DRAM. Then, the Replay block
will play the samples to the radio continuously with a base frequency of 915 MHz,
creating a tone at 915.5 MHz. Press <code>Ctrl+C</code> to stop transmitting.
Alternatively, use the <code>--nsamps</code> command line argument to transmit
a certain number of samples before returning to the command line. Use the
<code>--help</code> argument to see a full list of arguments.

The advantage of this example compared to directly streaming the file to the
device is twofold:

* The initial upload to DRAM can happen at any link rate. Even when using 1 GbE, this example will work.
* Once uploaded, the host computer is basically idle. The FPGA will handle the streaming to the radio front-end.

The [https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp source code]
for <code>rfnoc_replay_samples_from_file</code> may be considered an example
for best practices on how to use the replay block.

==Using the Replay Block==

This block works like a record and playback buffer that uses DRAM on the USRP to
store samples.
Data can be streamed to the block, like to any other RFNoC block.

Refer the [https://files.ettus.com/manual/classuhd_1_1rfnoc_1_1replay__block__control.html manual of the replay block controller]
for a comprehensive description of its features and API calls.

In the following, we shall use the C++ API to demonstrate the most important
API calls. We will assume there is a replay block controller called
<code>replay_ctrl</code> available in the current context, and it is of type
<code>uhd::rfnoc::replay_block_control::sptr</code>.

===Recording Data===

Before streaming data to the replay block, it needs to be configured for recording:

replay_ctrl->record(buffer_start_byte_address, buffer_size_in_bytes, replay_chan);

This tells the Replay block that it should start recording any data it receives
on port <code>port</code> into the DRAM at byte offset <code>buffer_start_byte_address</code>
and should use up to <code>buffer_size_in_bytes</code> bytes. Once the buffer is
filled, recording automatically stops. Care should be taken to configure the
memory buffers so that they do not overlap if more than one Replay block or
buffer is being used simultaneously.

Call this once for every port that you expect to stream data into.

'''Note:''' Care should be taken to not transfer more data to the Replay block
than the size of the record buffer. Additional data is not accepted or dropped
by the replay block, but flow control will cause data to back up in the RF network on the FPGA.

'''Note:''' The amount of memory available to the Replay block is limited by the
size of the DRAM on the USRP and how the memory interface is configured on the USRP.
For example, the <code>axi_intercon_2x64_128_bd</code> IP used by the X310 is
configured to give each connected device an address space of 32 MiB. As a
result, the Replay block will be limited to this amount of memory. The
<code>axi_intercon_2x64_128_bd</code> file must be modified if more than 32 MiB needs to be buffered.

To restart recording from the same offset, the following API call can be used:

replay_ctrl->record_restart(replay_chan);

This resets the record pointer to point back to the beginning of the buffer and
it resets the internal counters that track how much data has been recorded. If
a previous recording has taken place then it is a good idea to ensure that
stale data was not queued up in the RF network on the FPGA from a previous run.
The <code>replay_samples_from_file</code> example does this by calling
<code>record_restart()</code> then waiting to see if any new data shows up
unexpectedly in the record buffer. If so, it restarts recording then waits
again to see if data continues to appear.

You can determine when all data has been received by checking the status of the
record fullness.

// Wait for recording to complete
while (replay_ctrl->get_record_fullness(replay_chan) < num_bytes_expected)
std::this_thread::sleep_for(100ms);

===Playing back Data===

Prior to playing back recorded data, it is necessary to configure the base
address and size of the playback buffer. To play back previously recorded data,
set the start address to the same address that was used for the record buffer
and set the size of the playback buffer to the match the amount of data that
was recorded. Note that the record and playback buffers do not need to be the
same, allowing a single Replay block to both record and playback to different
regions of memory simultaneously.

// Configure the Replay block to play back everything that was recorded
num_bytes_recorded = replay_ctrl->get_record_fullness(replay_chan);
replay_ctrl->config_play(buffer_start_byte_address, num_bytes_recorded, replay_chan);

To play back the data in the playback buffer, issue the appropriate UHD stream command.
Playback automatically wraps around to the start of the buffer if more data is
requested than the size of the playback buffer.

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_START_CONTINUOUS);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

or

uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
stream_cmd.num_samps = words_to_replay;
stream_cmd.stream_now = true;
replay_ctrl->issue_stream_cmd(stream_cmd, replay_chan);

<code>STREAM_MODE_START_CONTINUOUS</code> causes playback to continue indefinitely
until explicitly stopped. <code>STREAM_MODE_NUM_SAMPS_AND_DONE</code> causes only
the specified number of samples to be played once. The <code>num_samps</code>
parameter is a 28-bit value, limiting this mode of playback to 2<sup>28</sup>
words at a time. Playback can be stopped by issuing a stop command.

stream_cmd.stream_mode = uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS;
replay_ctrl->issue_stream_cmd(stream_cmd);

This will stop playback at the end of the next DRAM read after the command is
received (DRAM reads are not aborted mid-transaction). As a result, some data
will continue to stream from the Replay block after the stop command is issued
while waiting for the DRAM read to complete and for all the internal buffers to
empty.

When using the C++ API, the <code>play()</code> API call is a useful shorthand
for configuring playback and submitting the stream command at the same time:

replay_ctrl->play(buffer_start_byte_address, num_bytes_to_play, replay_chan, start_time, repeat);

In either case, the start time is optional. When given, the first sample to leave
the block on playback is tagged with this timestamp.

===Memory alignment and word sizes===

There are two memory alignment values that need to be considered when dealing
with the replay block. The first is the word size, which is the minimum number of
bytes per transaction. For all default configurations, the word size is 64 bits,
which means that only even numbers of samples can be recorded or played back
when using 16-bit complex samples (at 4 bytes per sample). Use the <code>get_word_size()</code>
API call to identify the correct word size.

The second alignment value is the memory's page boundaries. The start addresses
for record and replay must fall onto a 4 kiB memory boundary to ensure correct
alignment of data.

==Building Custom FPGA Images with a Replay Block==

===Configure the Default Shell===

Before you begin, make sure you are using the <code>Bash</code> shell. See [[Software_Development_on_the_E3xx_USRP_-_Building_RFNoC_UHD_/_GNU_Radio_/_gr-ettus_from_Source#Reconfigure_Default_Shell|Reconfigure Default Shell]] in AN-315 for detailed instructions.

===Cloning the Repository===

Note: Cloning the repository is only required when building custom FPGA images.
If the replay block is already built into the USRP's bit file, this is not
required. By default, UHD ships the Replay block with the default images for
the X410, X310/X300, N300/N310/N320 series of USRPs.

If you do require access to the source code, e.g. to build an FPGA image with a
custom replay block configuration, run the following command:

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

For the rest of the Application Note, we assume the repository was cloned into
the location ~/src/uhd.

===Installing the FPGA Tools===

In order to build the FPGA image for the intended USRP product, you will need
to have the Xilinx development tools installed. The specific version required
depends on the UHD version. Refer to the
[https://files.ettus.com/manual/md_usrp3_build_instructions.html manual] for the
correct version for your UHD version, and the installation instructions for
Vivado in order to install these tools. It is recommended that you use the
default install location of <code>/opt/Xilinx/Vivado</code>.

==Building the FPGA==

In order to use the Replay block, it must be built into the FPGA image for the
USRP you plan to use. This is currently a manual step. The instructions below
are for the X310, but similar instructions apply to other RFNoC-capable
devices.

To create a custom FPGA image with a replay, you need to create an image core file.
The following lines are the relevant lines from the
[https://github.com/EttusResearch/uhd/blob/master/fpga/usrp3/top/x300/x310_rfnoc_image_core.yml X310 default image core file]:

stream_endpoints:
# ... all the other stream endpoints...
ep4: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data
ep5: # Stream endpoint name
ctrl: False # Endpoint passes control traffic
data: True # Endpoint passes data traffic
buff_size: 4096 # Ingress buffer size for data

noc_blocks:
# ... all the other blocks...
replay0:
block_desc: 'replay.yml'
parameters:
NUM_PORTS: 2

connections:
# ...connections for all the other blocks...
# ep4 to replay0(0)
- { srcblk: ep4, srcport: out0, dstblk: replay0, dstport: in_0 }
# replay0(0) to ep4
- { srcblk: replay0, srcport: out_0, dstblk: ep4, dstport: in0 }
# ep5 to replay0(1)
- { srcblk: ep5, srcport: out0, dstblk: replay0, dstport: in_1 }
# replay0(1) to ep5
- { srcblk: replay0, srcport: out_1, dstblk: ep5, dstport: in0 }
# BSP Connections
- { srcblk: replay0, srcport: axi_ram, dstblk: _device_, dstport: dram } MEM_ADDR_W: 30
clk_domains:
# ...all other clock domains...
- { srcblk: _device_, srcport: dram, dstblk: replay0, dstport: mem }

As you can see, the replay block requires configuration in up to four sections:
* For maximum flexibility, every port of the replay block will receive its own stream endpoint. This is not a requirement of the replay block, but allows its flexible use.
* Of course, the block needs to be declared in the <code>noc_blocks</code> section.
* It must be connected to the stream endpoints in the <code>connections</code> section, as well as to the DRAM banks (BSP connection).
* Finally, the clock domain needs to be connected.

When the YAML image core file is complete, save it, e.g., as x310_replay_image_core.yml,
and pass it to the image builder:

rfnoc_image_builder -y x310_replay_image_core.yml

This will create a bitfile that contains the replay block. It can be loaded onto
the device using the <code>uhd_image_loader</code> tool:

uhd_image_loader --args type=x300,addr=<ip address> --fpga-path=/path/to/usrp_x310_fpga_HG.bit

When this is complete, the replay block is ready to use.

==Source files==

For reference, the following files implement the replay block:

* Verilog/HDL sources: https://github.com/EttusResearch/uhd/tree/master/fpga/usrp3/lib/rfnoc/blocks/rfnoc_block_replay
* C++ Block controller sources (header, block controller, Python bindings, unit tests):
** https://github.com/EttusResearch/uhd/blob/master/host/include/uhd/rfnoc/replay_block_control.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control.cpp
** https://github.com/EttusResearch/uhd/blob/master/host/lib/rfnoc/replay_block_control_python.hpp
** https://github.com/EttusResearch/uhd/blob/master/host/tests/rfnoc_block_tests/replay_block_test.cpp
* Example: https://github.com/EttusResearch/uhd/blob/master/host/examples/rfnoc_replay_samples_from_file.cpp

Verifying the Operation of the USRP Using UHD and GNU Radio

2020-09-09T19:05:36Z

MartinBraun: /* UHD Programs */

==Application Note Number==
'''AN-936'''

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

==Abstract==
This AN explains how to use UHD and GNU Radio, once installed, to verify the correct operation of the USRP. Several test procedures are explained in detail. Several tests make use of an optional spectrum analyzer and signal generator.

==Overview==
This application note will cover testing your USRP to verify it is operational. You will need to have a working installation of UHD to preform the following steps to verify your USRP. If you do not have UHD installed, 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.

Alternatively, you may use the [[Live SDR Environment]] to perform the following steps. More information about the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==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. 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
|-
|}

==Finding the Device==
*Report detailed information on UHD-supported Software Radio Peripherals attached by USB, network, or embedded configuration. Details include unit names, revision numbers, and available sensors on all attached USRP motherboards and daughterboards.
uhd_usrp_probe

Example output from <code>uhd_usrp_probe</code>:

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

-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
_____________________________________________________
/
| Device: USRP2 / N-Series Device
| _____________________________________________________
| /
| | Mboard: N210r4
| | hardware: 2577
| | mac-addr: 00:00:00:00:00:00
| | ip-addr: 192.168.10.2
| | subnet: 255.255.255.255
| | gateway: 255.255.255.255
| | gpsdo: none
| | serial: xxxxxx
| | FW Version: 12.4
| | FPGA Version: 11.1
| |
| | Time sources: none, external, _external_, mimo
| | Clock sources: internal, external, mimo
| | Sensors: mimo_locked, ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: WBX, WBX + Simple GDB (0x0053)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: WBXv2 RX+GDB
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.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: ads62p44
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | | | Gain range fine: 0.0 to 0.5 step 0.1 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: WBX (0x0052)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: WBXv2 TX+GDB
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.000 MHz
| | | | Gain range PGA0: 0.0 to 25.0 step 0.1 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9777
| | | | Gain Elements: None

</pre>

*Find UHD-supporting Software Radio Peripherals attached by USB, network or embedded configuration. Uses broadcast packets for discovery. Often blocked by routers, switches, firewalls.
uhd_find_devices

Example output from <code>uhd_find_devices</code>:

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

--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
type: usrp2
addr: 192.168.10.2
name:
serial: xxxxxx
</pre>

*View firewall settings with:
sudo iptables -L

==UHD Programs==
The example programs included with the UHD driver will be located at:
$install_prefix/lib/uhd/examples

On Linux, the default installation prefix location is <code>/usr/local</code>.

The example programs are located in the folder:
/usr/local/lib/uhd/examples

On OSX, the configuration is similar to Linux, however the default installation prefix location is <code>/opt/local</code>.

The example programs will be located in the folder:
/opt/local/lib/uhd/examples

On Windows, the default installation prefix will be <code>C:\Program Files\UHD\</code>.

The example programs will be located in the folder:
C:\Program Files\UHD\lib\uhd\examples

Before executing the following commands, change directory to the appropriate location.

==Benchmarking your system==
*Benchmarks interface with device.
./benchmark_rate --rx_rate 10e6 --tx_rate 10e6

Example output from <code>benmark_rate</code>:

<pre>
$ ./benchmark_rate --rx_rate 10e6 --tx_rate 10e6
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting device timestamp to 0...
Testing receive rate 10.000000 Msps on 1 channels
Testing transmit rate 10.000000 Msps on 1 channels

Benchmark rate summary:
Num received samples: 100104043
Num dropped samples: 0
Num overflows detected: 0
Num transmitted samples: 100229019
Num sequence errors: 0
Num underflows detected: 0
Num late commands: 0
Num timeouts: 0

Done!

</pre>

==Receiving Samples==
*Saves samples to file
./rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat

Example output from <code>rx_samples_to_file</code>:

<pre>
$ ./rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Waiting for "lo_locked": ++++++++++ locked.

Press Ctrl + C to stop streaming...

Done!
</pre>

Example of file size output from <code>rx_samples_to_file</code>:

<pre>
$ ls -al usrp_samples.dat
-rw-rw-r-- 1 user user 200040000 Sep 1 14:43 usrp_samples.dat
</pre>

==Transmitting Samples==
*Transmits samples from file
./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat

Example of output from <code>tx_samples_from_file</code>:

<pre>
$ ./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 10.000000 dB...
Actual TX Gain: 10.000000 dB...

Checking TX: LO: locked ...

Done!
</pre>

==Terminal DFT/FFT==
*Creates ASCII/Ncurses FFT
./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30

Example output from <code>rx_ascii_art_dft</code>:

<pre>
$ ./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Setting RX Bandwidth: 5.000000 MHz...
Actual RX Bandwidth: 5.000000 MHz...

Checking RX: LO: locked ...
</pre>

Example screenshot of <code>rx_ascii_art_dft</code> running:

[[File:rx ascii art dft.png|900px]]

==Transmit test signal==
*Transmits specific waveform
./tx_waveforms --freq 915e6 --rate 5e6 --gain 0

Example output from <code>tx_waveforms</code>:

<pre>
$ ./tx_waveforms --freq 915e6 --rate 5e6 --gain 0
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 0.000000 dB...
Actual TX Gain: 0.000000 dB...

Setting device timestamp to 0...
Checking TX: LO: locked ...
Press Ctrl + C to stop streaming...
^C
Done!
</pre>

==Additional UHD Utilities==
*Downloads FPGA images for current UHD version
sudo uhd_images_downloader

Example output from running <code>uhd_images_downloader</code>:

<pre>
$ [sudo] uhd_images_downloader # Use sudo if installing into /usr or /usr/local on Linux systems
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.000.000-release.zip
Downloading images to: /tmp/tmpPYd_5J/uhd-images_003.010.000.000-release.zip
58959 kB / 58959 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

*Flashes an image onto the X300/X310 FPGA
usrp_x3xx_fpga_burner

*Reading and writing motherboard EEPROM
usrp_burn_mb_eeprom

*Reading and writing daughterboard EEPROM
usrp_burn_db_eeprom

[[Category:Application Notes]]

Verifying the Operation of the USRP Using UHD and GNU Radio

2020-09-09T19:04:08Z

MartinBraun: /* Receiving Samples */

==Application Note Number==
'''AN-936'''

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

==Abstract==
This AN explains how to use UHD and GNU Radio, once installed, to verify the correct operation of the USRP. Several test procedures are explained in detail. Several tests make use of an optional spectrum analyzer and signal generator.

==Overview==
This application note will cover testing your USRP to verify it is operational. You will need to have a working installation of UHD to preform the following steps to verify your USRP. If you do not have UHD installed, 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.

Alternatively, you may use the [[Live SDR Environment]] to perform the following steps. More information about the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==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. 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
|-
|}

==Finding the Device==
*Report detailed information on UHD-supported Software Radio Peripherals attached by USB, network, or embedded configuration. Details include unit names, revision numbers, and available sensors on all attached USRP motherboards and daughterboards.
uhd_usrp_probe

Example output from <code>uhd_usrp_probe</code>:

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

-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
_____________________________________________________
/
| Device: USRP2 / N-Series Device
| _____________________________________________________
| /
| | Mboard: N210r4
| | hardware: 2577
| | mac-addr: 00:00:00:00:00:00
| | ip-addr: 192.168.10.2
| | subnet: 255.255.255.255
| | gateway: 255.255.255.255
| | gpsdo: none
| | serial: xxxxxx
| | FW Version: 12.4
| | FPGA Version: 11.1
| |
| | Time sources: none, external, _external_, mimo
| | Clock sources: internal, external, mimo
| | Sensors: mimo_locked, ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: WBX, WBX + Simple GDB (0x0053)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: WBXv2 RX+GDB
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.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: ads62p44
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | | | Gain range fine: 0.0 to 0.5 step 0.1 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: WBX (0x0052)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: WBXv2 TX+GDB
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.000 MHz
| | | | Gain range PGA0: 0.0 to 25.0 step 0.1 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9777
| | | | Gain Elements: None

</pre>

*Find UHD-supporting Software Radio Peripherals attached by USB, network or embedded configuration. Uses broadcast packets for discovery. Often blocked by routers, switches, firewalls.
uhd_find_devices

Example output from <code>uhd_find_devices</code>:

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

--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
type: usrp2
addr: 192.168.10.2
name:
serial: xxxxxx
</pre>

*View firewall settings with:
sudo iptables -L

==UHD Programs==
The example programs included with the UHD driver will be located at:
$install_prefix/lib/uhd/examples

On Linux, the default installation prefix location is <code>/usr/local</code>.

The example programs are located in the folder:
/usr/local/lib/uhd/examples

On OSX, the configuration is similar to Linux, however the default installation prefix location is <code>/opt/local</code>.

The example programs will be located in the folder:
/opt/local/lib/uhd/examples

On Windows, the default installation prefix will be <code>C:\Program Files\UHD\</code>.

The example programs will be located in the folder:
C:\Program Files\UHD\lib\uhd\examples

==Benchmarking your system==
*Benchmarks interface with device.
./benchmark_rate --rx_rate 10e6 --tx_rate 10e6

Example output from <code>benmark_rate</code>:

<pre>
$ ./benchmark_rate --rx_rate 10e6 --tx_rate 10e6
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting device timestamp to 0...
Testing receive rate 10.000000 Msps on 1 channels
Testing transmit rate 10.000000 Msps on 1 channels

Benchmark rate summary:
Num received samples: 100104043
Num dropped samples: 0
Num overflows detected: 0
Num transmitted samples: 100229019
Num sequence errors: 0
Num underflows detected: 0
Num late commands: 0
Num timeouts: 0

Done!

</pre>

==Receiving Samples==
*Saves samples to file
./rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat

Example output from <code>rx_samples_to_file</code>:

<pre>
$ ./rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Waiting for "lo_locked": ++++++++++ locked.

Press Ctrl + C to stop streaming...

Done!
</pre>

Example of file size output from <code>rx_samples_to_file</code>:

<pre>
$ ls -al usrp_samples.dat
-rw-rw-r-- 1 user user 200040000 Sep 1 14:43 usrp_samples.dat
</pre>

==Transmitting Samples==
*Transmits samples from file
./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat

Example of output from <code>tx_samples_from_file</code>:

<pre>
$ ./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 10.000000 dB...
Actual TX Gain: 10.000000 dB...

Checking TX: LO: locked ...

Done!
</pre>

==Terminal DFT/FFT==
*Creates ASCII/Ncurses FFT
./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30

Example output from <code>rx_ascii_art_dft</code>:

<pre>
$ ./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Setting RX Bandwidth: 5.000000 MHz...
Actual RX Bandwidth: 5.000000 MHz...

Checking RX: LO: locked ...
</pre>

Example screenshot of <code>rx_ascii_art_dft</code> running:

[[File:rx ascii art dft.png|900px]]

==Transmit test signal==
*Transmits specific waveform
./tx_waveforms --freq 915e6 --rate 5e6 --gain 0

Example output from <code>tx_waveforms</code>:

<pre>
$ ./tx_waveforms --freq 915e6 --rate 5e6 --gain 0
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 0.000000 dB...
Actual TX Gain: 0.000000 dB...

Setting device timestamp to 0...
Checking TX: LO: locked ...
Press Ctrl + C to stop streaming...
^C
Done!
</pre>

==Additional UHD Utilities==
*Downloads FPGA images for current UHD version
sudo uhd_images_downloader

Example output from running <code>uhd_images_downloader</code>:

<pre>
$ [sudo] uhd_images_downloader # Use sudo if installing into /usr or /usr/local on Linux systems
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.000.000-release.zip
Downloading images to: /tmp/tmpPYd_5J/uhd-images_003.010.000.000-release.zip
58959 kB / 58959 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

*Flashes an image onto the X300/X310 FPGA
usrp_x3xx_fpga_burner

*Reading and writing motherboard EEPROM
usrp_burn_mb_eeprom

*Reading and writing daughterboard EEPROM
usrp_burn_db_eeprom

[[Category:Application Notes]]

Verifying the Operation of the USRP Using UHD and GNU Radio

2020-09-09T19:03:55Z

MartinBraun: /* Transmitting Samples */

==Application Note Number==
'''AN-936'''

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

==Abstract==
This AN explains how to use UHD and GNU Radio, once installed, to verify the correct operation of the USRP. Several test procedures are explained in detail. Several tests make use of an optional spectrum analyzer and signal generator.

==Overview==
This application note will cover testing your USRP to verify it is operational. You will need to have a working installation of UHD to preform the following steps to verify your USRP. If you do not have UHD installed, 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.

Alternatively, you may use the [[Live SDR Environment]] to perform the following steps. More information about the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==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. 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
|-
|}

==Finding the Device==
*Report detailed information on UHD-supported Software Radio Peripherals attached by USB, network, or embedded configuration. Details include unit names, revision numbers, and available sensors on all attached USRP motherboards and daughterboards.
uhd_usrp_probe

Example output from <code>uhd_usrp_probe</code>:

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

-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
_____________________________________________________
/
| Device: USRP2 / N-Series Device
| _____________________________________________________
| /
| | Mboard: N210r4
| | hardware: 2577
| | mac-addr: 00:00:00:00:00:00
| | ip-addr: 192.168.10.2
| | subnet: 255.255.255.255
| | gateway: 255.255.255.255
| | gpsdo: none
| | serial: xxxxxx
| | FW Version: 12.4
| | FPGA Version: 11.1
| |
| | Time sources: none, external, _external_, mimo
| | Clock sources: internal, external, mimo
| | Sensors: mimo_locked, ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: WBX, WBX + Simple GDB (0x0053)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: WBXv2 RX+GDB
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.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: ads62p44
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | | | Gain range fine: 0.0 to 0.5 step 0.1 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: WBX (0x0052)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: WBXv2 TX+GDB
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.000 MHz
| | | | Gain range PGA0: 0.0 to 25.0 step 0.1 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9777
| | | | Gain Elements: None

</pre>

*Find UHD-supporting Software Radio Peripherals attached by USB, network or embedded configuration. Uses broadcast packets for discovery. Often blocked by routers, switches, firewalls.
uhd_find_devices

Example output from <code>uhd_find_devices</code>:

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

--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
type: usrp2
addr: 192.168.10.2
name:
serial: xxxxxx
</pre>

*View firewall settings with:
sudo iptables -L

==UHD Programs==
The example programs included with the UHD driver will be located at:
$install_prefix/lib/uhd/examples

On Linux, the default installation prefix location is <code>/usr/local</code>.

The example programs are located in the folder:
/usr/local/lib/uhd/examples

On OSX, the configuration is similar to Linux, however the default installation prefix location is <code>/opt/local</code>.

The example programs will be located in the folder:
/opt/local/lib/uhd/examples

On Windows, the default installation prefix will be <code>C:\Program Files\UHD\</code>.

The example programs will be located in the folder:
C:\Program Files\UHD\lib\uhd\examples

==Benchmarking your system==
*Benchmarks interface with device.
./benchmark_rate --rx_rate 10e6 --tx_rate 10e6

Example output from <code>benmark_rate</code>:

<pre>
$ ./benchmark_rate --rx_rate 10e6 --tx_rate 10e6
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting device timestamp to 0...
Testing receive rate 10.000000 Msps on 1 channels
Testing transmit rate 10.000000 Msps on 1 channels

Benchmark rate summary:
Num received samples: 100104043
Num dropped samples: 0
Num overflows detected: 0
Num transmitted samples: 100229019
Num sequence errors: 0
Num underflows detected: 0
Num late commands: 0
Num timeouts: 0

Done!

</pre>

==Receiving Samples==
*Saves samples to file
./rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat

Example output from <code>rx_samples_to_file</code>:

<pre>
$ /usr/local/lib/uhd/examples/rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Waiting for "lo_locked": ++++++++++ locked.

Press Ctrl + C to stop streaming...

Done!
</pre>

Example of file size output from <code>rx_samples_to_file</code>:

<pre>
$ ls -al usrp_samples.dat
-rw-rw-r-- 1 user user 200040000 Sep 1 14:43 usrp_samples.dat
</pre>

==Transmitting Samples==
*Transmits samples from file
./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat

Example of output from <code>tx_samples_from_file</code>:

<pre>
$ ./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 10.000000 dB...
Actual TX Gain: 10.000000 dB...

Checking TX: LO: locked ...

Done!
</pre>

==Terminal DFT/FFT==
*Creates ASCII/Ncurses FFT
./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30

Example output from <code>rx_ascii_art_dft</code>:

<pre>
$ ./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Setting RX Bandwidth: 5.000000 MHz...
Actual RX Bandwidth: 5.000000 MHz...

Checking RX: LO: locked ...
</pre>

Example screenshot of <code>rx_ascii_art_dft</code> running:

[[File:rx ascii art dft.png|900px]]

==Transmit test signal==
*Transmits specific waveform
./tx_waveforms --freq 915e6 --rate 5e6 --gain 0

Example output from <code>tx_waveforms</code>:

<pre>
$ ./tx_waveforms --freq 915e6 --rate 5e6 --gain 0
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 0.000000 dB...
Actual TX Gain: 0.000000 dB...

Setting device timestamp to 0...
Checking TX: LO: locked ...
Press Ctrl + C to stop streaming...
^C
Done!
</pre>

==Additional UHD Utilities==
*Downloads FPGA images for current UHD version
sudo uhd_images_downloader

Example output from running <code>uhd_images_downloader</code>:

<pre>
$ [sudo] uhd_images_downloader # Use sudo if installing into /usr or /usr/local on Linux systems
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.000.000-release.zip
Downloading images to: /tmp/tmpPYd_5J/uhd-images_003.010.000.000-release.zip
58959 kB / 58959 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

*Flashes an image onto the X300/X310 FPGA
usrp_x3xx_fpga_burner

*Reading and writing motherboard EEPROM
usrp_burn_mb_eeprom

*Reading and writing daughterboard EEPROM
usrp_burn_db_eeprom

[[Category:Application Notes]]

Verifying the Operation of the USRP Using UHD and GNU Radio

2020-09-09T19:03:25Z

MartinBraun: /* Additional UHD Utilities */

==Application Note Number==
'''AN-936'''

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

==Abstract==
This AN explains how to use UHD and GNU Radio, once installed, to verify the correct operation of the USRP. Several test procedures are explained in detail. Several tests make use of an optional spectrum analyzer and signal generator.

==Overview==
This application note will cover testing your USRP to verify it is operational. You will need to have a working installation of UHD to preform the following steps to verify your USRP. If you do not have UHD installed, 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.

Alternatively, you may use the [[Live SDR Environment]] to perform the following steps. More information about the [[Live SDR Environment]] is available at the [[Live SDR Environment Getting Started Guides]] page.

==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. 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
|-
|}

==Finding the Device==
*Report detailed information on UHD-supported Software Radio Peripherals attached by USB, network, or embedded configuration. Details include unit names, revision numbers, and available sensors on all attached USRP motherboards and daughterboards.
uhd_usrp_probe

Example output from <code>uhd_usrp_probe</code>:

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

-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
_____________________________________________________
/
| Device: USRP2 / N-Series Device
| _____________________________________________________
| /
| | Mboard: N210r4
| | hardware: 2577
| | mac-addr: 00:00:00:00:00:00
| | ip-addr: 192.168.10.2
| | subnet: 255.255.255.255
| | gateway: 255.255.255.255
| | gpsdo: none
| | serial: xxxxxx
| | FW Version: 12.4
| | FPGA Version: 11.1
| |
| | Time sources: none, external, _external_, mimo
| | Clock sources: internal, external, mimo
| | Sensors: mimo_locked, ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX DSP: 1
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: WBX, WBX + Simple GDB (0x0053)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: WBXv2 RX+GDB
| | | | Antennas: TX/RX, RX2, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.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: ads62p44
| | | | Gain range digital: 0.0 to 6.0 step 0.5 dB
| | | | Gain range fine: 0.0 to 0.5 step 0.1 dB
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | |
| | | Freq range: -50.000 to 50.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: WBX (0x0052)
| | | Serial: xxxxxx
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: WBXv2 TX+GDB
| | | | Antennas: TX/RX, CAL
| | | | Sensors: lo_locked
| | | | Freq range: 68.750 to 2200.000 MHz
| | | | Gain range PGA0: 0.0 to 25.0 step 0.1 dB
| | | | Bandwidth range: 40000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: ad9777
| | | | Gain Elements: None

</pre>

*Find UHD-supporting Software Radio Peripherals attached by USB, network or embedded configuration. Uses broadcast packets for discovery. Often blocked by routers, switches, firewalls.
uhd_find_devices

Example output from <code>uhd_find_devices</code>:

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

--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
type: usrp2
addr: 192.168.10.2
name:
serial: xxxxxx
</pre>

*View firewall settings with:
sudo iptables -L

==UHD Programs==
The example programs included with the UHD driver will be located at:
$install_prefix/lib/uhd/examples

On Linux, the default installation prefix location is <code>/usr/local</code>.

The example programs are located in the folder:
/usr/local/lib/uhd/examples

On OSX, the configuration is similar to Linux, however the default installation prefix location is <code>/opt/local</code>.

The example programs will be located in the folder:
/opt/local/lib/uhd/examples

On Windows, the default installation prefix will be <code>C:\Program Files\UHD\</code>.

The example programs will be located in the folder:
C:\Program Files\UHD\lib\uhd\examples

==Benchmarking your system==
*Benchmarks interface with device.
./benchmark_rate --rx_rate 10e6 --tx_rate 10e6

Example output from <code>benmark_rate</code>:

<pre>
$ ./benchmark_rate --rx_rate 10e6 --tx_rate 10e6
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting device timestamp to 0...
Testing receive rate 10.000000 Msps on 1 channels
Testing transmit rate 10.000000 Msps on 1 channels

Benchmark rate summary:
Num received samples: 100104043
Num dropped samples: 0
Num overflows detected: 0
Num transmitted samples: 100229019
Num sequence errors: 0
Num underflows detected: 0
Num late commands: 0
Num timeouts: 0

Done!

</pre>

==Receiving Samples==
*Saves samples to file
./rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat

Example output from <code>rx_samples_to_file</code>:

<pre>
$ /usr/local/lib/uhd/examples/rx_samples_to_file --freq 98e6 --rate 5e6 --gain 20 --duration 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Waiting for "lo_locked": ++++++++++ locked.

Press Ctrl + C to stop streaming...

Done!
</pre>

Example of file size output from <code>rx_samples_to_file</code>:

<pre>
$ ls -al usrp_samples.dat
-rw-rw-r-- 1 user user 200040000 Sep 1 14:43 usrp_samples.dat
</pre>

==Transmitting Samples==
*Transmits samples from file
./tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat

Example of output from <code>tx_samples_from_file</code>:

<pre>
$ /usr/local/lib/uhd/examples/tx_samples_from_file --freq 915e6 --rate 5e6 --gain 10 usrp_samples.dat
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 10.000000 dB...
Actual TX Gain: 10.000000 dB...

Checking TX: LO: locked ...

Done!
</pre>

==Terminal DFT/FFT==
*Creates ASCII/Ncurses FFT
./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30

Example output from <code>rx_ascii_art_dft</code>:

<pre>
$ ./rx_ascii_art_dft --freq 98e6 --rate 5e6 --gain 20 --bw 5e6 --ref-lvl -30
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 5.000000 Msps...
Actual RX Rate: 5.000000 Msps...

Setting RX Freq: 98.000000 MHz...
Actual RX Freq: 98.000000 MHz...

Setting RX Gain: 20.000000 dB...
Actual RX Gain: 20.000000 dB...

Setting RX Bandwidth: 5.000000 MHz...
Actual RX Bandwidth: 5.000000 MHz...

Checking RX: LO: locked ...
</pre>

Example screenshot of <code>rx_ascii_art_dft</code> running:

[[File:rx ascii art dft.png|900px]]

==Transmit test signal==
*Transmits specific waveform
./tx_waveforms --freq 915e6 --rate 5e6 --gain 0

Example output from <code>tx_waveforms</code>:

<pre>
$ ./tx_waveforms --freq 915e6 --rate 5e6 --gain 0
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

Creating the usrp device with: ...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Using Device: Single USRP:
Device: USRP2 / N-Series Device
Mboard 0: N210r4
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: WBXv2 RX+GDB
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: WBXv2 TX+GDB

Setting TX Rate: 5.000000 Msps...
Actual TX Rate: 5.000000 Msps...

Setting TX Freq: 915.000000 MHz...
Actual TX Freq: 915.000000 MHz...

Setting TX Gain: 0.000000 dB...
Actual TX Gain: 0.000000 dB...

Setting device timestamp to 0...
Checking TX: LO: locked ...
Press Ctrl + C to stop streaming...
^C
Done!
</pre>

==Additional UHD Utilities==
*Downloads FPGA images for current UHD version
sudo uhd_images_downloader

Example output from running <code>uhd_images_downloader</code>:

<pre>
$ [sudo] uhd_images_downloader # Use sudo if installing into /usr or /usr/local on Linux systems
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.000.000-release.zip
Downloading images to: /tmp/tmpPYd_5J/uhd-images_003.010.000.000-release.zip
58959 kB / 58959 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

*Flashes an image onto the X300/X310 FPGA
usrp_x3xx_fpga_burner

*Reading and writing motherboard EEPROM
usrp_burn_mb_eeprom

*Reading and writing daughterboard EEPROM
usrp_burn_db_eeprom

[[Category:Application Notes]]

UHD Python API

2018-06-21T01:13:14Z

MartinBraun: Merge to master

== What's the UHD Python API? ==

As the name suggests, it exposes the UHD API into Python. We use <code>Boost.Python</code>
to generate a Python module which exposes most of the C++ API, and some extra
features. The Python API is currently part of master branch.

The pre-release announcement covers most of the information and can be found here: http://lists.ettus.com/pipermail/usrp-users_lists.ettus.com/2017-June/025379.html

We'll be doing some more development on this branch before we're merging it, but most importantly, we'd like to get some feedback from the greater community.

The biggest thing missing is more documentation, but it already includes some examples. It's definitely ready for testing!

== How can I use it? ==

In order to test the Python API, check out the <code>master</code> branch and build it like always. When running CMake, make sure that the Python API was enabled (<code>-DENABLE_PYTHON_API=ON</code>).

The output from CMake should look something like this:

<pre>
-- ######################################################
-- # UHD enabled components
-- ######################################################
-- * LibUHD
-- * LibUHD - C API
-- * LibUHD - Python API
-- * Examples
-- * Utils
-- * Tests
-- * USB
-- * B100
-- * B200
-- * USRP1
-- * USRP2
-- * X300
-- * N230
-- * OctoClock
-- * Manual
-- * API/Doxygen
-- * Man Pages
--
-- ######################################################
-- # UHD disabled components
-- ######################################################
-- * GPSD
-- * E100
-- * E300
</pre>

Once it's built and installed, you'll be able to import the <code>uhd</code> Python
module:

<syntaxhighlight lang="python">
>>> import uhd
>>> my_usrp = uhd.usrp.MultiUSRP("type=b200")
>>> my_usrp.set_rx_gain(70)
</syntaxhighlight>

We have some examples in <code>[https://github.com/EttusResearch/uhd/tree/master/host/examples/python host/examples/python]</code>. The examples are very
simple, but concise.

==Example: pyuhd_rx_to_file.py==
This Python example is based on the C++ example <code>uhd/host/examples/rx_samples_to_file.cpp</code>.

<syntaxhighlight lang="python">
import uhd
import numpy as np
import argparse

def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("-a", "--args", default="", type=str)
parser.add_argument("-o", "--output-file", type=str, required=True)
parser.add_argument("-f", "--freq", type=float, required=True)
parser.add_argument("-r", "--rate", default=1e6, type=float)
parser.add_argument("-d", "--duration", default=5.0, type=float)
parser.add_argument("-c", "--channels", default=0, nargs="+", type=int)
parser.add_argument("-g", "--gain", type=int, default=10)
return parser.parse_args()

def main():
args = parse_args()
usrp = uhd.usrp.MultiUSRP(args.args)
num_samps = int(np.ceil(args.duration*args.rate))
if not isinstance(args.channels, list):
args.channels = [args.channels]
samps = usrp.recv_num_samps(num_samps, args.freq, args.rate, args.channels, args.gain)
with open(args.output_file, 'wb') as f:
np.save(f, samps, allow_pickle=False, fix_imports=False)

if __name__ == "__main__":
main()
</syntaxhighlight>

== What about documentation? ==

Documentation is currently pretty sparse. The best we can do right now is to ask
users to infer the documentation from the C++ API. For example, the Python has
an object called <code>MultiUSRP</code> which is an equivalent of the C++ <code>multi_usrp</code> API.
The methods on both classes are the same, and take the same arguments.

==FAQ==
'''Does it support Python 2 and 3?'''

Yes.

'''Does it require GNU Radio?'''

No.

'''Does it use SWIG?'''

No, it uses <code>Boost.Python</code>. We didn't want to add another dependency to UHD (i.e., SWIG) and Boost was already a dependency of UHD. It also doesn't require the C API.

'''How does this relate to the Python API in gr-uhd?'''

It serves an entirely different purpose. This Python API is for people writing standalone applications for USRPs that *don't* use GNU Radio. <code>gr-uhd</code> is staying the way it is, and is going nowhere. If you're using GNU Radio, you probably don't care about this.

'''Are the UHD Python API and the gr-uhd Python API compatible?'''

Short answer: No. Long answer: There are very few cases where it makes sense to mix these APIs, so no. However, this means that a <code>TimeSpec</code> from the <code>Boost.Python</code> API is not convertible into a <code>time_spec_t</code> from the <code>gr-uhd</code> API.

'''When will it be released?'''

It is currently on <code>master</code> branch, and will become part of the next major release.

'''Does it support RFNoC API?'''

Not yet, but it's in the pipeline. We wanted to get the basics (i.e. <code>multi_usrp</code> API) right first.

'''What's the streaming performance?'''

Worse than straight C++, but not a lot, thanks to NumPy. You can run <code>host/examples/benchmark_rate.py</code> if you want to see for yourself.
Overall, <code>recv()</code> calls are pretty efficient if you've preallocated a NumPy array, because we can cast that to a straight pointer (and also skip any type checking!) and then it's not that different from a <code>recv()</code> call in a C++ app. However, consuming the data is limited by how fast you can handle that in Python.

UHD Python API

2017-07-11T00:15:30Z

MartinBraun: /* FAQ */ Added gr q

== What's the UHD Python API? ==

As the name suggests, it exposes the UHD API into Python. We use <code>Boost.Python</code>
to generate a Python module which exposes most of the C++ API, and some extra
features.

The Python API is currently in a public beta test. We very much encourage users
to try it out and voice their feedback. It is our intention to merge this API
into the master branch soon, and ship it as a regular feature.

The pre-release announcement covers most of the information and can be found here: http://lists.ettus.com/pipermail/usrp-users_lists.ettus.com/2017-June/025379.html

We'll be doing some more development on this branch before we're merging it, but most importantly, we'd like to get some feedback from the greater community.

The biggest thing missing is more documentation, but it already includes some examples. It's definitely ready for testing!

==Feedback==
Any feedback is encouraged, please use the Github issue linked below for Python API discussion/bugs/improvements:

https://github.com/EttusResearch/uhd/issues/105

== How can I use it? ==

In order to test the Python API, check out the <code>python-api</code> branch (see:
https://github.com/EttusResearch/uhd/tree/python-api) and build it like any
other UHD branch. When running CMake, make sure that the Python API was enabled.

The output from CMake should look something like this:

<pre>
-- ######################################################
-- # UHD enabled components
-- ######################################################
-- * LibUHD
-- * LibUHD - C API
-- * LibUHD - Python API
-- * Examples
-- * Utils
-- * Tests
-- * USB
-- * B100
-- * B200
-- * USRP1
-- * USRP2
-- * X300
-- * N230
-- * OctoClock
-- * Manual
-- * API/Doxygen
-- * Man Pages
--
-- ######################################################
-- # UHD disabled components
-- ######################################################
-- * GPSD
-- * E100
-- * E300
</pre>

Once it's built and installed, you'll be able to import the <code>uhd</code> Python
module:

<syntaxhighlight lang="python">
>>> import uhd
>>> my_usrp = uhd.usrp.MultiUSRP("type=b200")
>>> my_usrp.set_rx_gain(70)
</syntaxhighlight>

We have some examples in <code>[https://github.com/EttusResearch/uhd/tree/python-api/host/examples/python host/examples/python]</code>. The examples are very
simple, but concise.

==Example: pyuhd_rx_to_file.py==
This Python example is based on the C++ example <code>uhd/host/examples/rx_samples_to_file.cpp</code>.

<syntaxhighlight lang="python">
import uhd
import numpy as np
import argparse

def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("-a", "--args", default="", type=str)
parser.add_argument("-o", "--output-file", type=str, required=True)
parser.add_argument("-f", "--freq", type=float, required=True)
parser.add_argument("-r", "--rate", default=1e6, type=float)
parser.add_argument("-d", "--duration", default=5.0, type=float)
parser.add_argument("-c", "--channels", default=0, nargs="+", type=int)
parser.add_argument("-g", "--gain", type=int, default=10)
return parser.parse_args()

def main():
args = parse_args()
usrp = uhd.usrp.MultiUSRP(args.args)
num_samps = int(np.ceil(args.duration*args.rate))
if not isinstance(args.channels, list):
args.channels = [args.channels]
samps = usrp.recv_num_samps(num_samps, args.freq, args.rate, args.channels, args.gain)
with open(args.output_file, 'wb') as f:
np.save(f, samps, allow_pickle=False, fix_imports=False)

if __name__ == "__main__":
main()
</syntaxhighlight>

== What about documentation? ==

Documentation is currently pretty sparse. The best we can do right now is to ask
users to infer the documentation from the C++ API. For example, the Python has
an object called <code>MultiUSRP</code> which is an equivalent of the C++ <code>multi_usrp</code> API.
The methods on both classes are the same, and take the same arguments.

==FAQ==
'''Does it support Python 2 and 3?'''

Yes.

'''Does it require GNU Radio?'''

No.

'''Does it use SWIG?'''

No, it uses <code>Boost.Python</code>. We didn't want to add another dependency to UHD (i.e., SWIG) and Boost was already a dependency of UHD. It also doesn't require the C API.

'''How does this relate to the Python API in gr-uhd?'''

It serves an entirely different purpose. This Python API is for people writing standalone applications for USRPs that *don't* use GNU Radio. <code>gr-uhd</code> is staying the way it is, and is going nowhere. If you're using GNU Radio, you probably don't care about this.

'''Are the UHD Python API and the gr-uhd Python API compatible?'''

Short answer: No. Long answer: There are very few cases where it makes sense to mix these APIs, so no. However, this means that a <code>TimeSpec</code> from the <code>Boost.Python</code> API is not convertible into a <code>time_spec_t</code> from the <code>gr-uhd</code> API.

'''When will it be released?'''

TBD, but if we hear a lot of encouragement that'll drive things along faster. It'll go into <code>master</code> branch whenever it's considered stable enough, and then in the first major release after that merge.

'''Does it support RFNoC API?'''

Not yet, but it's not hard to add. We wanted to get the basics (i.e. <code>multi_usrp</code> API) right first.

'''What's the streaming performance?'''

Worse than straight C++. Better than I would have thought, thanks to NumPy. We have no benchmarks yet. Overall, <code>recv()</code> calls are pretty efficient if you've preallocated a NumPy array, because we can cast that to a straight pointer (and also skip any type checking!!!!!!) and then it's not that different from a <code>recv()</code> call in a C++ app. However, consuming the data is limited by how

UHD Python API

2017-07-10T23:29:59Z

MartinBraun:

== What's the UHD Python API? ==

As the name suggests, it exposes the UHD API into Python. We use Boost.Python
to generate a Python module which exposes most of the C++ API, and some extra
features.

The Python API is currently in a public beta test. We very much encourage users
to try it out and voice their feedback. It is our intention to merge this API
into the master branch soon, and ship it as a regular feature.

The pre-release announcement covers most of the information:

<pre>
Hi all,

some people have already heard the rumour that we're working on a Python
API for UHD that does not involve gr-uhd. And yes, it's true. A minute
ago, I published our current development branch on github:

https://github.com/EttusResearch/uhd/tree/python-api

We'll be doing some more development on this branch before we're merging
it, but most importantly, we'd like to get some feedback from the
greater community.

The biggest thing missing is more documentation, but it already includes
some examples. It's definitely ready for testing!
If you have feedback, post it either in this thread, or on github:
https://github.com/EttusResearch/uhd/issues/105

I've tried to preempt some questions:

- Does it support Python 2 and 3? Yes.
- Does it use SWIG? No, it uses Boost.Python. We didn't want to add
another dependency to UHD (i.e., SWIG) and Boost was already a
dependency of UHD. It also doesn't require the C API.
- How does this relate to the Python API in gr-uhd? It serves an
entirely different purpose. This Python API is for people writing
standalone applications for USRPs that *don't* use GNU Radio. gr-uhd is
staying the way it is, and is going nowhere. If you're using GNU Radio,
you probably don't care about this.
- Are the UHD Python API and the gr-uhd Python API compatible? Short
answer: No. Long answer: There are very few cases where it makes sense
to mix these APIs, so no. However, this means that a TimeSpec from the
Boost.Python API is not convertible into a time_spec_t from the gr-uhd API.
- When will it be released? TBD, but if we hear a lot of encouragement
that'll drive things along faster. It'll go into master branch whenever
it's considered stable enough, and then in the first major release after
that merge.
- Does it support RFNoC API? Not yet, but it's not hard to add. We
wanted to get the basics (i.e. multi_usrp API) right first.
- What's the streaming performance? Worse than straight C++. Better than
I would have thought, thanks to numpy. We have no benchmarks yet.
Overall, recv() calls are pretty efficient if you've preallocated a
numpy array, because we can cast that to a straight pointer (and also
skip any type checking!!!!!!) and then it's not that different from a
recv() call in a C++ app. However, consuming the data is limited by how
fast you can handle that in Python.
</pre>

== How can I use it? ==

In order to test the Python API, check out the python-api branch (see:
https://github.com/EttusResearch/uhd/tree/python-api) and build it like any
other UHD branch. When running CMake, make sure that the Python API was enabled.

The output from CMake should look something like this:

<pre>
-- ######################################################
-- # UHD enabled components
-- ######################################################
-- * LibUHD
-- * LibUHD - C API
-- * LibUHD - Python API
-- * Examples
-- * Utils
-- * Tests
-- * USB
-- * B100
-- * B200
-- * USRP1
-- * USRP2
-- * X300
-- * N230
-- * OctoClock
-- * Manual
-- * API/Doxygen
-- * Man Pages
--
-- ######################################################
-- # UHD disabled components
-- ######################################################
-- * GPSD
-- * E100
-- * E300
</pre>

Once it's built and installed, you'll be able to import the '''uhd''' Python
module:

<syntaxhighlight lang="python">
>>> import uhd
>>> my_usrp = uhd.usrp.MultiUSRP("type=b200")
>>> my_usrp.set_rx_gain(70)
</syntaxhighlight>

We have some examples in '''host/examples/python'''. The examples are very
simple, but concise.

== What about documentation? ==

Documentation is currently pretty sparse. The best we can do right now is to ask
users to infer the documentation from the C++ API. For example, the Python has
an object called 'MultiUSRP' which is an equivalent of the C++ 'multi_usrp' API.
The methods on both classes are the same, and take the same arguments.

UHD Python API

2017-07-10T21:59:40Z

MartinBraun: Not finished yet

Getting Started with RFNoC Development

2017-07-10T16:27:58Z

MartinBraun: Typo (removed a ')

==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<br> 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-01-17T01:31:33Z

MartinBraun: /* Verify Environment */ uhd_config_info

==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<br> Nicolas Cuervo
|style="text-align:center;"| Initial creation

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

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

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

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

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

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

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

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

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

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

This will do the following:

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

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

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

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

$ pybombs config makewidth 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.0.0.rfnoc-devel-161-g83150fdd

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

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

$ uhd_images_downloader

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

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

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

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

<code>usrp_x310_fpga_HG.bit</code>

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

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

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

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

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

|}

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

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

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

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

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

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

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

Example for an X310 USRP:

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

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

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

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

rfnoc_rx_to_file.cpp

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

rfnoc_nullsource_ce_rx.cpp

These examples demonstrate the core features and flexibility of RFNoC.

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

===Getting started with GNU Radio + RFNoC===
A good way of getting started with RFNoC in a more tangible fashion 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 and compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs:

* 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 your 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] Y
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 (the blue signal has both “I” and “Q” data):

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

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

For the setting register that will hold the constant value as well as the read back register:

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

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

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

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

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

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

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

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

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

|FIFO
|noc_block_axi_fifo_loopback.v
|Simple FIFO loopback / passthrough block.
|-

|FFT
|noc_block_fft.v
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|noc_block_fir_filter.v
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|noc_block_window.v
|Windowing block for use with FFT block.
|-

|Vector IIR
|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
|noc_block_keep_one_in_n.v
|Keeps one packet every N packets.
|-

|AddSub
|noc_block_addsub.v
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|noc_block_null_source_sink.v
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|noc_block_packet_resizer.v
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|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>)

<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 these 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>.

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Primary Application Note]
* [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).

===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-01-17T01:30:11Z

MartinBraun: /* Create development environment manually */

==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<br> Nicolas Cuervo
|style="text-align:center;"| Initial creation

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

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

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

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

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

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

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

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

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

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

This will do the following:

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

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

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

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

$ pybombs config makewidth 3

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

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

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

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

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

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

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

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

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

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

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

===Verify Environment===
Running the command “<code>uhd_usrp_probe</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_usrp_probe --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 tangible fashion 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 and compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs:

* 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 your 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] Y
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 (the blue signal has both “I” and “Q” data):

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

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

For the setting register that will hold the constant value as well as the read back register:

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

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

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

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

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

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

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

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

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

|FIFO
|noc_block_axi_fifo_loopback.v
|Simple FIFO loopback / passthrough block.
|-

|FFT
|noc_block_fft.v
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|noc_block_fir_filter.v
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|noc_block_window.v
|Windowing block for use with FFT block.
|-

|Vector IIR
|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
|noc_block_keep_one_in_n.v
|Keeps one packet every N packets.
|-

|AddSub
|noc_block_addsub.v
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|noc_block_null_source_sink.v
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|noc_block_packet_resizer.v
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|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>)

<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 these 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>.

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Primary Application Note]
* [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).

===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-01-17T01:29:18Z

MartinBraun: /* Create development environment using PyBOMBS */ Added ref to pybombs config foo

==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<br> Nicolas Cuervo
|style="text-align:center;"| Initial creation

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

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

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

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

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

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

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

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

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

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

This will do the following:

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

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

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

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

$ pybombs config makewidth 3

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

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

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

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

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

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

===Create 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_usrp_probe</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_usrp_probe --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 tangible fashion 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 and compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs:

* 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 your 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] Y
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 (the blue signal has both “I” and “Q” data):

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

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

For the setting register that will hold the constant value as well as the read back register:

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

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

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

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

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

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

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

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

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

|FIFO
|noc_block_axi_fifo_loopback.v
|Simple FIFO loopback / passthrough block.
|-

|FFT
|noc_block_fft.v
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|noc_block_fir_filter.v
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|noc_block_window.v
|Windowing block for use with FFT block.
|-

|Vector IIR
|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
|noc_block_keep_one_in_n.v
|Keeps one packet every N packets.
|-

|AddSub
|noc_block_addsub.v
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|noc_block_null_source_sink.v
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|noc_block_packet_resizer.v
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|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>)

<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 these 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>.

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Primary Application Note]
* [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).

===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-01-17T01:24:17Z

MartinBraun: /* Create development environment using PyBOMBS */

==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<br> Nicolas Cuervo
|style="text-align:center;"| Initial creation

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

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

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

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

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

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

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

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

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

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

This will do the following:

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

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

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

'''NOTE:''' A user can specify how many cores are used during compile time by specifying the <code>--config makewidth=X</code> argument, where “<code>X</code>” is an integer number. The default is set to 4. 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 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_usrp_probe</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_usrp_probe --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 tangible fashion 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 and compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs:

* 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 your 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] Y
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 (the blue signal has both “I” and “Q” data):

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

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

For the setting register that will hold the constant value as well as the read back register:

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

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

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

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

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

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

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

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

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

|FIFO
|noc_block_axi_fifo_loopback.v
|Simple FIFO loopback / passthrough block.
|-

|FFT
|noc_block_fft.v
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|noc_block_fir_filter.v
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|noc_block_window.v
|Windowing block for use with FFT block.
|-

|Vector IIR
|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
|noc_block_keep_one_in_n.v
|Keeps one packet every N packets.
|-

|AddSub
|noc_block_addsub.v
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|noc_block_null_source_sink.v
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|noc_block_packet_resizer.v
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|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>)

<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 these 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>.

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Primary Application Note]
* [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).

===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-01-17T01:22:33Z

MartinBraun: Minor: PyBOMBS clarification

==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<br> Nicolas Cuervo
|style="text-align:center;"| Initial creation

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

==Abstract==
This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example.

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

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

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

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

$ 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>
* 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 during compile time by specifying the <code>--config makewidth=X</code> argument, where “<code>X</code>” is an integer number. The default is set to 4. 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 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_usrp_probe</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_usrp_probe --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 tangible fashion 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 and compiled into the FPGA image currently running on the USRP.

A couple of rules for building GNU Radio flowgraphs:

* 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 your 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] Y
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 (the blue signal has both “I” and “Q” data):

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

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

For the setting register that will hold the constant value as well as the read back register:

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

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

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

And for the processing section:

assign m_axis_data_tready = s_axis_data_tready;
assign s_axis_data_tvalid = m_axis_data_tvalid;
assign s_axis_data_tlast = m_axis_data_tlast;

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

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

'''assign s_axis_data_tdata = {i_mult_gain[15:0], q_mult_gain[15:0]};'''

'''NOTE:''' Because the multiplication process can occur in the same clock cycle there is no need for handshaking with the AXI <code>tready, tvalid and tlast</code> signals and therefore they are simply passed through the <code>gain</code> RFNoC block.

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

Below is a figure that shows the structure of the testbench created by the RFNoC Modtool.

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

`TEST_CASE_START("Test sequence");
'''gain = 100;'''
'''tb_streamer.write_user_reg(sid_noc_block_gain, noc_block_gain.SR_GAIN, gain);'''
fork
begin

tb_streamer.recv(recv_payload,md);
for (int i = 0; i < SPP/2; i++) begin
'''expected_value = i*gain;'''

Create a <code>build</code> directory, verify directory location is <code>rfnoc-tutorial</code> and run:

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

|FIFO
|noc_block_axi_fifo_loopback.v
|Simple FIFO loopback / passthrough block.
|-

|FFT
|noc_block_fft.v
|Xilinx coregen based Fast Fourier Transform up to length 4096.
|-

|FIR
|noc_block_fir_filter.v
|Xilinx coregen based Finite Impulse Response Filter, 41 taps, reconfigurable tap coefficients.
|-

|Window
|noc_block_window.v
|Windowing block for use with FFT block.
|-

|Vector IIR
|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
|noc_block_keep_one_in_n.v
|Keeps one packet every N packets.
|-

|AddSub
|noc_block_addsub.v
|Example of using multiple block ports in a single RFNoC block to add and subtract streams.
|-

|Null Source Sink
|noc_block_null_source_sink.v
|Generates dummy packets and can consume packets at a configurable rate. Useful for testing.
|-

|Packet Resizer
|noc_block_packet_resizer.v
|Resizes input packets to a configurable size (larger or smaller than source packets).
|-

|Split Stream
|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>)

<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 these 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>.

==Links and Additional Resources==
===RFNoC additional resources===
* [https://kb.ettus.com/RFNoC RFNoC Primary Application Note]
* [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).

===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]]

UHD

2016-12-02T02:17:11Z

MartinBraun:

==Introduction==
The Ettus Research USRP™ family of Software Defined Radios (SDRs) are versatile devices that allow users to transmit and receive many different and custom waveforms at various frequencies and settings on a common hardware platform. Commercial, academic, and military customers employ the flexible and reusable USRP hardware for research, wireless exploration, and field deployments.

The USRP comes in many form factors and configurations. The main categories of USRPs are:

*Bus (B) Series – Connected to a host computer via a USB connection
*Network(N) Series – Connected to a host computer via an Ethernet connection
*High Performance (X) Series – Connection can be Ethernet or a x4 PCI-Express connection
*Embedded (E) Series – Meant to run stand-alone (without a host computer).

The USRP Hardware Driver (UHD) is a user-space library that runs on a general purpose processor (GPP) and communicates with and controls all of the USRP device family. The B, N and X series USRPs send and receive samples from a host computer as illustrated in figure 1. And since our embedded series USRPs house an internal GPP you can run these radios without the need of a host computer (stand-alone mode).

[[File:Uhd intro figure 1.png|700px|center]]

USRPs are transceivers, meaning that they can both transmit and receive RF signals. UHD provides the necessary control used to transport user waveform samples to and from USRP hardware as well as control various parameters (e.g. sampling rate, center frequency, gains, etc) of the radio.

UHD GPP driver and firmware code is written in C/C++ while the code developed for the FPGA (Field Programmable Gate Array) is written in Verilog. There is a C/C++ API that can interface to other software frameworks, as in the case of GNU Radio, or a user can simply build custom signal processing applications directly on top of the UHD C/C++ API. Figure 2 illustrates this concept:

[[File:Uhd intro figure 2.png|700px|center]]
<center>Figure 2. UHD components</center>

==Open Source==
The majority of the UHD 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, UHD is available under the open-source GNU Public License version 3 (GPLv3), as well as an alternate, less-restrictive license offered only by Ettus Research. For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Release Cycle==
Due to the open source nature of UHD, the entire development process is also open, and it is possible to track UHD’s development through our [https://github.com/EttusResearch/uhd Git] version control system. Users can make a choice if they prefer the latest development code, which is most feature-rich but can be unstable at times, or the more thoroughly tested code that does not include the latest development.
Versioned releases (e.g., UHD version 3.9.2) happen approximately every two months, and usually only include bugfixes compared to the previous version (e.g., UHD 3.9.2 has the same feature set as 3.9.1, but is more stable). These bugfix releases are done off of the maint branch, which is where all the bugfix development happens.

New feature development is done on the master branch. This branch should not be considered stable, even though we use continuous integration systems to monitor its state. However, it is possible that APIs or dependency requirements change on the master branch.

At the end of a feature development cycle, the master branch is frozen, and only bugfixes are accepted into the master branch. Once the master branch is considered stable, the maint branch is reset to master, and a new versioned release is produced from the previous master branch. This is indicated by a major version number jump (e.g., when going from 3.8.3 to 3.9.0). Major version releases occur 1-2 times per year, and usually accompany new product releases.

Aside from the maint and master branches, new feature branches are sometimes published (temporarily) to give insight into upcoming features, and earlier access to new development.

==Code Portability==
The UHD software API supports application development on all USRP SDR products. Using a common software interface is critical, enabling code portability and, allowing applications to transition seamlessly to other USRP SDR systems when development requirements expand or new systems become available. Hence, it enables a significant reduction in development effort by allowing you to preserve and reuse your legacy code. UHD can be installed on Linux, Windows, or a Mac. Installation packages for these platforms as well as instructions for building from source can be found [http://files.ettus.com/manual/page_install.html here].

[[File:Uhd intro figure 3.png|700px|center]]

==Dependencies==

===Python===
Compatible with Python 2.7 and above (Python 3 is supported). Note Python is required for building, and some utilities that ship with UHD are written in Python. It is not, in general, required for running UHD applications.

===Linux Notes===
This is dependent on the distribution you are using, but most, if not all, of the dependencies should be available in the package repositories for your package manager.

===Mac OS X Notes===
Install the Xcode app to get the build tools (GCC and Make). Use MacPorts to get the Boost and Mako dependencies. Other dependencies can be downloaded as DMG installers from the web or installed via MacPorts. See the UHD OS X build instructions for more information: Build Instructions (Mac OS X)

===Windows Notes===
The dependencies can be acquired through installable EXE files. Usually, the Windows installer can be found on the project's website. Some projects do not host Windows installers, and if this is the case, follow the auxiliary download URL for the Windows installer (below).

===Git===
* Required to check out the repository (not necessary if building from tarballs).
* On Windows, install Cygwin with Git support to checkout the repository or install msysGit from http://code.google.com/p/msysgit/downloads/list.

===Build Dependencies===

{| class="wikitable"
| UHD Version || GCC || Clang || MS Visual C++ || CMake || Boost || LibUSB || Mako || Doxygen || Python || Xilinx Vivado
|-
| 3.9.X || >= 4.4 || >= 3.3 || >= 2012 (11.0) || >= 2.8 || >= 1.46 || >= 1.0 || >= 0.5.0 || >= 1.8 (recommended) || >= 2.7 || == 2014.4
|-
| 3.9.10.X || >= 4.8 || >= 3.3 || >= 2012 (11.0) || >= 2.8 || >= 1.53 || >= 1.0 || >= 0.5.0 || >= 1.8 (recommended) || >= 2.7 || == 2015.4
|-
|}

Other compilers (or lower versions) may work, but are unsupported.

Note on MSVC: The free [https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx Visual Studio Express Edition for Desktop] works.

Note on Boost: Older versions of UHD may not work with newer versions of Boost, as the Boost API sometimes changes (and we can't retroactively change old versions). For example, UHD 3.8.X (and older) won't work with Boost 1.60.

==Sample streaming==
UHD handles the control for transporting I and Q samples (see [http://www.ni.com/tutorial/4805/en/ here] for information on I and Q samples) by using standard interface methods such as Ethernet, USB and PCI-Express. Samples can be sent in a continuous stream as in figure 4a or in bursts, figure 4b. In addition the user has the ability to specify when samples are received or transmitted by using built in burst and timed commands.

[[File:Uhd intro figure 4.png|700px|center]]

<center>Figure 4. a) Continuous Sample Streaming. b) Burst Sample Mode (SOB = Start of Burst while EOB = End of Burst).</center>

==RF Frequency Fine Tuning==
USRP RF front ends may support a certain frequency step size that does not meet all or many of a user’s requirements. For this reason, UHD includes Digital Up-Conversion (DUC) and Digital Down-Conversion (DDC) DSP blocks in the FPGA for fine tuning the RF frequency (see [http://files.ettus.com/manual/page_general.html#general_tuning_process here]). This allows users to:
*Have a sub-Hz RF frequency step size
*Mitigate the DC problem that exists on Direct Conversion (Zero IF) hardware (see [http://files.ettus.com/manual/page_general.html#general_tuning here]).
*Fast tune inside the available bandwidth

[[File:Uhd intro figure 5.png|700px|center]]

==Sample Rate==
Different SDR configurations, waveforms, and applications require different sample rates. For example, a user may wish to monitor 100 MHz of instantaneous RF bandwidth, but their host PC may only be capable of analyzing 20 MHz of real-time bandwidth. For this and other cases, UHD allows users to set various sample rates to meet their custom application. Within the FPGA, UHD includes decimation and interpolation blocks in order to perform these sample rate translations.

==IQ Corrections==
Inherent to all direct conversion (zero IF) RF architectures is the effect of IQ imbalance. A video entitled “Effects of Quadrature Impairments on 802.11ac EVM”, found [http://www.ni.com/rf-academy/wireless/ here], demonstrates this attribute. Find additional information [http://www.ni.com/tutorial/5657/en/ here]. In summary, any given signal on a device using a direct conversion architecture has two paths for TX and two paths for RX. One path is the In-phase or “I” and the other is Quadrature “Q”, also referred to as Real and Imaginary.

[[File:Uhd intro figure 6.png|700px|center]]

Because of slight differences due to variances in components, temperature, and other factors, the I and Q signal paths are subject to different conditions, thus altering the original signal that existed at initial capture. When the phase or amplitude of either the I or Q get altered the results show up as signals not actually present in the original signal.
For example, note the following IQ impairment simulation in this GNU Radio Flowgraph created in GNU Radio Companion.

[[File:Uhd intro figure 7.png|700px|center]]

By using the “HW Impairments” block, you can simulate what happens when the I and Q signal paths are disrupted. In figure 8a there are no impairments added. However, when the amplitude of the I path is increased slightly, you get the artifact as show in figure 8b

[[File:Uhd intro figure 8.png|700px|center]]

It is possible to mitigate some of these unwanted effects in the digital domain. UHD contains function blocks within the FPGA to compensate for IQ impairments; these blocks appeared in figure 1 as IQC blocks. A user can customize the parameters of these blocks based on empirical measurement or allow UHD to perform an automatic analysis and provide parameters based on a built-in IQ correction algorithm. See the following functions in the [http://files.ettus.com/manual/page_calibration.html UHD manual] for more information:

*uhd_cal_rx_iq_balance: - mimimizes RX IQ imbalance vs. LO frequency
*uhd_cal_tx_dc_offset: - mimimizes TX DC offset vs. LO frequency
*uhd_cal_tx_iq_balance: - mimimizes TX IQ imbalance vs. LO frequency

==Multiple USRPs==
UHD makes scaling the number of channels on a USRP system simple by treating them all as one composite device, see figure 9 below. In the case of the X300/X310, when USRPs are used in this multi-USRP configuration users can use an [https://www.ettus.com/product/details/OctoClock-G external clocking source] (having both a 10 MHz clock reference and a PPS signal) to synchronize all the devices together.

[[File:Uhd intro figure 9.png|700px|center]]

As an example, in an 8 channel receive system the “USRP Source” block in GNU Radio Companion would look like figure 10 below

[[File:Uhd intro figure 10.png|700px|center]]

==GPIO – General Purpose Input Output==
General Purpose Input Output (GPIO) pins can be controlled manually through UHD or can be set from UHD to be automatically triggered when events such as TX or RX occur. An example of where or how to use this automatic triggering: when a user connects an RF amplifier to the TX or RX port of the USRP, the amplifier can be powered on only when the USRP is transmitting. You can find out more about the aux GPIO on the E3x0/X3x0 [http://files.ettus.com/manual/page_gpio_api.html here].

[[File:Uhd intro figure 11.png|700px|center]]

==RF Front End Expansion==
While mostly a function of HW, the USRP can interface with different RF front ends from 3rd parties. By using the BasicRX and BasicTX daughterboards, a user can send or receive a Baseband or IF (Intermediate Frequency) analog signal to 3rd party front ends.

==GNU Radio==
In addition to leading development of the gr-uhd module that integrates the USRP family (UHD) into GNU Radio, Ettus Research frequently contributes to the GNU Radio project. Although USRP radios are often associated with the GNU Radio software framework, many USRP applications (such as [http://www.openbts.org OpenBTS]) run without GNU Radio. For more information on GNU Radio see [https://www.ettus.com/sdr-software/detail/gnu-radio here].

==Conclusion==
UHD aids commercial, academic, military, hobbyists and other SDR users with rapid prototyping or deployment of wireless protocols by providing a flexible feature rich SDR API.

==Additional Resources==

Github: https://github.com/EttusResearch/uhd

Manual: http://files.ettus.com/manual/index.html

[[Category:Software Resources]]

UHD

2016-12-02T02:15:36Z

MartinBraun: Flipped deps table, added note on Boost

==Introduction==
The Ettus Research USRP™ family of Software Defined Radios (SDRs) are versatile devices that allow users to transmit and receive many different and custom waveforms at various frequencies and settings on a common hardware platform. Commercial, academic, and military customers employ the flexible and reusable USRP hardware for research, wireless exploration, and field deployments.

The USRP comes in many form factors and configurations. The main categories of USRPs are:

*Bus (B) Series – Connected to a host computer via a USB connection
*Network(N) Series – Connected to a host computer via an Ethernet connection
*High Performance (X) Series – Connection can be Ethernet or a x4 PCI-Express connection
*Embedded (E) Series – Meant to run stand-alone (without a host computer).

The USRP Hardware Driver (UHD) is a user-space library that runs on a general purpose processor (GPP) and communicates with and controls all of the USRP device family. The B, N and X series USRPs send and receive samples from a host computer as illustrated in figure 1. And since our embedded series USRPs house an internal GPP you can run these radios without the need of a host computer (stand-alone mode).

[[File:Uhd intro figure 1.png|700px|center]]

USRPs are transceivers, meaning that they can both transmit and receive RF signals. UHD provides the necessary control used to transport user waveform samples to and from USRP hardware as well as control various parameters (e.g. sampling rate, center frequency, gains, etc) of the radio.

UHD GPP driver and firmware code is written in C/C++ while the code developed for the FPGA (Field Programmable Gate Array) is written in Verilog. There is a C/C++ API that can interface to other software frameworks, as in the case of GNU Radio, or a user can simply build custom signal processing applications directly on top of the UHD C/C++ API. Figure 2 illustrates this concept:

[[File:Uhd intro figure 2.png|700px|center]]
<center>Figure 2. UHD components</center>

==Open Source==
The majority of the UHD 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, UHD is available under the open-source GNU Public License version 3 (GPLv3), as well as an alternate, less-restrictive license offered only by Ettus Research. For more information on our licensing policy, please contact [mailto:info@ettus.com info@ettus.com].

==Release Cycle==
Due to the open source nature of UHD, the entire development process is also open, and it is possible to track UHD’s development through our [https://github.com/EttusResearch/uhd Git] version control system. Users can make a choice if they prefer the latest development code, which is most feature-rich but can be unstable at times, or the more thoroughly tested code that does not include the latest development.
Versioned releases (e.g., UHD version 3.9.2) happen approximately every two months, and usually only include bugfixes compared to the previous version (e.g., UHD 3.9.2 has the same feature set as 3.9.1, but is more stable). These bugfix releases are done off of the maint branch, which is where all the bugfix development happens.

New feature development is done on the master branch. This branch should not be considered stable, even though we use continuous integration systems to monitor its state. However, it is possible that APIs or dependency requirements change on the master branch.

At the end of a feature development cycle, the master branch is frozen, and only bugfixes are accepted into the master branch. Once the master branch is considered stable, the maint branch is reset to master, and a new versioned release is produced from the previous master branch. This is indicated by a major version number jump (e.g., when going from 3.8.3 to 3.9.0). Major version releases occur 1-2 times per year, and usually accompany new product releases.

Aside from the maint and master branches, new feature branches are sometimes published (temporarily) to give insight into upcoming features, and earlier access to new development.

==Code Portability==
The UHD software API supports application development on all USRP SDR products. Using a common software interface is critical, enabling code portability and, allowing applications to transition seamlessly to other USRP SDR systems when development requirements expand or new systems become available. Hence, it enables a significant reduction in development effort by allowing you to preserve and reuse your legacy code. UHD can be installed on Linux, Windows, or a Mac. Installation packages for these platforms as well as instructions for building from source can be found [http://files.ettus.com/manual/page_install.html here].

[[File:Uhd intro figure 3.png|700px|center]]

==Dependencies==

===Python===
Compatible with Python 2.7 and above (Python 3 is supported). Note Python is required for building, and some utilities that ship with UHD are written in Python. It is not, in general, required for running UHD applications.

===Linux Notes===
This is dependent on the distribution you are using, but most, if not all, of the dependencies should be available in the package repositories for your package manager.

===Mac OS X Notes===
Install the Xcode app to get the build tools (GCC and Make). Use MacPorts to get the Boost and Mako dependencies. Other dependencies can be downloaded as DMG installers from the web or installed via MacPorts. See the UHD OS X build instructions for more information: Build Instructions (Mac OS X)

===Windows Notes===
The dependencies can be acquired through installable EXE files. Usually, the Windows installer can be found on the project's website. Some projects do not host Windows installers, and if this is the case, follow the auxiliary download URL for the Windows installer (below).

===Git===
* Required to check out the repository (not necessary if building from tarballs).
* On Windows, install Cygwin with Git support to checkout the repository or install msysGit from http://code.google.com/p/msysgit/downloads/list.

===Build Dependencies===

{| class="wikitable"
| UHD Version || GCC || Clang || MS Visual C++ || CMake || Boost || LibUSB || Mako || Doxygen || Python || Xilinx Vivado
|-
| 3.9.X || >= 4.4 || >= 3.3 || >= 2012 (11.0) || >= 2.8 || >= 1.46 || >= 1.0 || >= 0.5.0 || >= 1.8 (recommended) || >= 2.7 || == 2014.4
|-
| 3.9.10.X || >= 4.8 || >= 3.3 || >= 2012 (11.0) || >= 2.8 || >= 1.53 || >= 1.0 || >= 0.5.0 || >= 1.8 (recommended) || >= 2.7 || == 2015.4
|-
|}

Other compilers (or lower versions) may work, but are unsupported.

Note on MSVC: The free [https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx Visual Studio Express Edition for Desktop] works.

Note on Boost: Older versions of UHD may not work with newer versions of Boost, as the Boost API sometimes changes (and we can't retroactively change old versions).

==Sample streaming==
UHD handles the control for transporting I and Q samples (see [http://www.ni.com/tutorial/4805/en/ here] for information on I and Q samples) by using standard interface methods such as Ethernet, USB and PCI-Express. Samples can be sent in a continuous stream as in figure 4a or in bursts, figure 4b. In addition the user has the ability to specify when samples are received or transmitted by using built in burst and timed commands.

[[File:Uhd intro figure 4.png|700px|center]]

<center>Figure 4. a) Continuous Sample Streaming. b) Burst Sample Mode (SOB = Start of Burst while EOB = End of Burst).</center>

==RF Frequency Fine Tuning==
USRP RF front ends may support a certain frequency step size that does not meet all or many of a user’s requirements. For this reason, UHD includes Digital Up-Conversion (DUC) and Digital Down-Conversion (DDC) DSP blocks in the FPGA for fine tuning the RF frequency (see [http://files.ettus.com/manual/page_general.html#general_tuning_process here]). This allows users to:
*Have a sub-Hz RF frequency step size
*Mitigate the DC problem that exists on Direct Conversion (Zero IF) hardware (see [http://files.ettus.com/manual/page_general.html#general_tuning here]).
*Fast tune inside the available bandwidth

[[File:Uhd intro figure 5.png|700px|center]]

==Sample Rate==
Different SDR configurations, waveforms, and applications require different sample rates. For example, a user may wish to monitor 100 MHz of instantaneous RF bandwidth, but their host PC may only be capable of analyzing 20 MHz of real-time bandwidth. For this and other cases, UHD allows users to set various sample rates to meet their custom application. Within the FPGA, UHD includes decimation and interpolation blocks in order to perform these sample rate translations.

==IQ Corrections==
Inherent to all direct conversion (zero IF) RF architectures is the effect of IQ imbalance. A video entitled “Effects of Quadrature Impairments on 802.11ac EVM”, found [http://www.ni.com/rf-academy/wireless/ here], demonstrates this attribute. Find additional information [http://www.ni.com/tutorial/5657/en/ here]. In summary, any given signal on a device using a direct conversion architecture has two paths for TX and two paths for RX. One path is the In-phase or “I” and the other is Quadrature “Q”, also referred to as Real and Imaginary.

[[File:Uhd intro figure 6.png|700px|center]]

Because of slight differences due to variances in components, temperature, and other factors, the I and Q signal paths are subject to different conditions, thus altering the original signal that existed at initial capture. When the phase or amplitude of either the I or Q get altered the results show up as signals not actually present in the original signal.
For example, note the following IQ impairment simulation in this GNU Radio Flowgraph created in GNU Radio Companion.

[[File:Uhd intro figure 7.png|700px|center]]

By using the “HW Impairments” block, you can simulate what happens when the I and Q signal paths are disrupted. In figure 8a there are no impairments added. However, when the amplitude of the I path is increased slightly, you get the artifact as show in figure 8b

[[File:Uhd intro figure 8.png|700px|center]]

It is possible to mitigate some of these unwanted effects in the digital domain. UHD contains function blocks within the FPGA to compensate for IQ impairments; these blocks appeared in figure 1 as IQC blocks. A user can customize the parameters of these blocks based on empirical measurement or allow UHD to perform an automatic analysis and provide parameters based on a built-in IQ correction algorithm. See the following functions in the [http://files.ettus.com/manual/page_calibration.html UHD manual] for more information:

*uhd_cal_rx_iq_balance: - mimimizes RX IQ imbalance vs. LO frequency
*uhd_cal_tx_dc_offset: - mimimizes TX DC offset vs. LO frequency
*uhd_cal_tx_iq_balance: - mimimizes TX IQ imbalance vs. LO frequency

==Multiple USRPs==
UHD makes scaling the number of channels on a USRP system simple by treating them all as one composite device, see figure 9 below. In the case of the X300/X310, when USRPs are used in this multi-USRP configuration users can use an [https://www.ettus.com/product/details/OctoClock-G external clocking source] (having both a 10 MHz clock reference and a PPS signal) to synchronize all the devices together.

[[File:Uhd intro figure 9.png|700px|center]]

As an example, in an 8 channel receive system the “USRP Source” block in GNU Radio Companion would look like figure 10 below

[[File:Uhd intro figure 10.png|700px|center]]

==GPIO – General Purpose Input Output==
General Purpose Input Output (GPIO) pins can be controlled manually through UHD or can be set from UHD to be automatically triggered when events such as TX or RX occur. An example of where or how to use this automatic triggering: when a user connects an RF amplifier to the TX or RX port of the USRP, the amplifier can be powered on only when the USRP is transmitting. You can find out more about the aux GPIO on the E3x0/X3x0 [http://files.ettus.com/manual/page_gpio_api.html here].

[[File:Uhd intro figure 11.png|700px|center]]

==RF Front End Expansion==
While mostly a function of HW, the USRP can interface with different RF front ends from 3rd parties. By using the BasicRX and BasicTX daughterboards, a user can send or receive a Baseband or IF (Intermediate Frequency) analog signal to 3rd party front ends.

==GNU Radio==
In addition to leading development of the gr-uhd module that integrates the USRP family (UHD) into GNU Radio, Ettus Research frequently contributes to the GNU Radio project. Although USRP radios are often associated with the GNU Radio software framework, many USRP applications (such as [http://www.openbts.org OpenBTS]) run without GNU Radio. For more information on GNU Radio see [https://www.ettus.com/sdr-software/detail/gnu-radio here].

==Conclusion==
UHD aids commercial, academic, military, hobbyists and other SDR users with rapid prototyping or deployment of wireless protocols by providing a flexible feature rich SDR API.

==Additional Resources==

Github: https://github.com/EttusResearch/uhd

Manual: http://files.ettus.com/manual/index.html

[[Category:Software Resources]]

Getting Started with RFNoC Development

2016-07-12T20:47:07Z

MartinBraun:

= Overview =

This application note gives a brief introduction into the steps required to start developing RFNoC blocks on your computer.
First, you need to make sure that you have all the tools required to do RFNoC development.
Then, we will set up a development sandbox in which you can do your RFNoC development.
Finally, we will run through the basic steps required to actually write custom RFNoC blocks.

= Prerequisites =

For any of this to work, you need to make sure you have all the tools to do both software and FPGA development.
Confirm you have the following tools installed:

* Xilinx Vivado. The specific version depends on the branch and state of the FPGA code and is very important. Make sure to install the correct version, you can look up the required version on the local version of the manual.
* Software build tools. If you can compile UHD from source, you have all the necessary components (If you're using PyBOMBS, this is definitely the case).

Please make sure these tools are available before proceeding to the next step.

= Creating a development environment =

In the following, we will assume that GNU Radio is used as a helper tool for RFNoC development. Note that GNU Radio is by no means required to use or develop RFNoC, but it makes it a great deal easier to use a framework on top of RFNoC for visualization etc., and GNU Radio is freely available and well suited for the task. In order to get your development environment set up, you will need the following software packages:

* UHD
* GNU Radio
* gr-ettus

The cleanest way to set this up is to install everything into a dedicated directory. PyBOMBS is the simplest way to do this.
If you haven't already downloaded and installed PyBOMBS, you can do so by running the following commands:

$ 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

From here, the easiest way to set up a PyBOMBS development environment is to run the following command:

$ pybombs prefix init ~/prefix/rfnoc -R rfnoc [-a alias]

This will do the following:

* Create a directory in ~/prefix/rfnoc (you can choose a different directory, of course)
* Clone UHD, FPGA, GNU Radio, and gr-ettus sources into that directory
* Compile and install all the software

Then, you need to enable the prefix:

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

PyBOMBS is by no means a requirement for doing any of these steps. If you wish to install the software manually, follow the individual install notes for GNU Radio, UHD and gr-ettus and make sure they are reachable by linkers and compilers.

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

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

If you already have UHD, GNU Radio and/or gr-ettus installed, it would be sufficient to checkout the branches mentioned and update them them (git pull). Thereafter, rebuild each of the repositories (first UHD, then GNU Radio, then gr-ettus).

= RFNoC Framework =

First, let's review briefly the RFNoC framework structure. The colourful image down here shows the basic structure of the RFNoC Stack.

[[File:rfnoc_stack.png|RFNoC Stack|600px|left|RFNoC Stack|link=https://kb.ettus.com/images/3/34/rfnoc_stack.png]]

From the stack there are clearly 5 different elements which a RFNoC developer has to take into account when creating an out-of-tree block. How these elements interact with each other is explained in more detail at [2][3][4]. However, from here we could easily infer that there are, at least, 3 components our out-of-tree block needs to address:

;1. Does it have a complete FPGA Integration?
:A Verilog file that describes the hardware implementation is what allows us to take advantage of the powerful FPGA that is being shipped with the current and next gen USRPs. For the current stage of development, the .v file has to not only implement the custom desired functionality but also a efficient interaction with the AXI bus and other FPGA blocks. In addition, the file has to be located in an specific location so that the building process can find it and use it as a resource for the IP generation.

;2. Does it have a block declaration/control?
:Now that the design has the hardware implementation in Verilog, we would like to take the samples (or other data items) out of the USRP and receive them at our host. The block has to have a block declaration file which defines, at least, its inputs and outputs and the NoC-ID, which is the method of identification between the HW part of our design and the SW part. Now, we might add some control over the samples that are being streamed into the block, and for that we have two options that depend on the complexity of the control that we want to apply: if as developers we can add control using NoC-Script, that could easily be added into the XML file. But if we need more exhaustive control and multiple data stream treatment, we might want to add more coding into it. Block controllers can be added as C++ in the UHD host, carefully generating the headers and adding them in the correct include folder and in the same manner, develop our control and add it in the library folder.

;3. Does it have GNU Radio integration?
: (Note: This is only required if using GNU Radio. Other frameworks might have similar requirements). GNU Radio is where the application runs, and where more control over the host is applied, by adding block-specific settings, such as sample rate or bandwidths. In addition, is where we have the our block ready to connect it to other several blocks (which can be also RFNoC blocks). That means that we are almost done with our design. In order to do so, we have to add a new XML file that allows us to bind our design with GNU Radio, and where we can edit the type on our I/Os, add variables for posterior signal processing, and a bunch of other design-specific parameters. In the same XML file we could add, just as we could have done at the block controllers, more block control by the means of NoC-Script. If we choose to do that, we could point our design to a "generic" implementation to control our GRC block. If we, otherwise, need even more control, we could choose to generate block code, that afterwards has to be located at gr-ettus: the headers as an include, the implementations as libraries.

So, you may think that this is just normal protocol of the RFNoC OOT block generation method. But, in order to answer this three questions with your OOT design, you have to take care of correct FPGA interfacing, correct API instantiation and right includes and correct location where to put your files... while you also put effort to the development of your custom design! Here at Ettus, we think that you should put all your effort in your custom design and let the '''RFNoC modtool''' do the dirty work.

= RFNoC Modtool =

In order to minimize the effort needed to implement a new RFNoC module, this gr_modtool-based tool provides the basic structure of the necessary files needed for the user to start with the development of his/her custom design right away. As it is gr_modtool-based, the manual found at [1] is also a great reference for this tool. Here, we discuss the features specific for the RFNoC modtool.

With the use of RFNoC ModTool, you can skip the struggle of locating the files of your design at different locations that depend (until now) on the location of your UHD and gr-ettus installation paths. Instead, you focus on your implementation and the tool takes care of boilerplate code and linking.

With the use of this tool, the questions stated in the last section would result in something like:
;1. Does it have a complete FPGA Integration?
: If not, start your design in the pregenerated verilog file, which also provides most of the standard AXI interface already done.

;2. Does it have a block declaration/control?
: Well, it has the files now, so write your functions if you need them. Don't even worry about modifying the files to add your NoC-ID: the tool will do that for you with the ID of your choice.

;3 Does it have GNU Radio integration?
:It has it now. You just need to put additional control, in case you need it.

Don't worry about relocating your files, they are where they need to be: '''in your custom location.''' The tool generates the files so that the whole building process takes into account your design regardless of the location of your OOT module in your machine.

== Tool Installation ==

The tool is currently shipped within gr-ettus (radio-redo branch), so by installing gr-ettus, rfnocmodtool automatically becomes available.

== Tool Utilization ==

After the installation, you are ready to use the tool to generate standard code for your Out-of-tree module. To check the usage of the tool, just type:

$ rfnocmodtool help

linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e
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.

If you have used the gr_modtool provided by GNURadio, you'll be familiar with this usage.

== Creating an RFNoC OOT Module ==

At this point you are all set up to start generating your own RFNoC OOT and if you were thinking that it is just as easy as it is with gr_modtool, you are completely right! Simply go to your prefixes source location (~/prefix/rfnoc/src) and type:

$ rfnocmodtool newmod [NAME OF THE MODULE]

In the following, assume we want to create a module with the name 'example'. You can write the name of your module right after the 'newmod' command, but if you happen to forget it, the tool will ask for it interactively. This will create a folder containing the basic folders that you may need for a functional module.

$ rfnocmodtool newmod example
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e

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

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

In contrast with gr_modtool, this includes a folder called 'rfnoc', which is where we put the UHD/FPGA files (more details below).

=== Adding custom blocks ===

Now you can start adding blocks to your module. The only thing to do is go inside of the module you just created and type:

$ rfnocmodule add [NAME OF THE BLOCK]

For demonstrative purposes, lets create a block named 'copy'. As for the new module, the tool will ask you for the name of the block if you not put it in the first line. There is a bunch of directives that you could pass to the tool, but if you run it without any of these directives you should expect the following interactive parsing output:

$ rfnocmodtool add copy
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e

RFNoC module name identified: example
Block/code identifier: copy
Enter valid argument list, including default arguments:
Add Python QA code? [Y/n]
Add C++ QA code? [y/N]
Block NoC ID (Hexadecimal): FFFF
Skip Block Controllers Generation? [y/N]
Skip Block interface Generation? [y/N]

The tool is going to ask you about a valid argument list, in case you have that clear at this stage of your design, and for the generation of QA codes which are, such as in the case of gr_modtool, optional. Right after that, specific RFNoC questions appear:

* 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 you don't provide the NoC ID, it will be set to a random number.
* Block Controllers Generation: The block controllers are the C++ control that you can apply to the UHD-part of the design. In these files, you can add more control over this layer of your design. However, if you can manage to add the control you need over NoC-Script, you can omit the cpp/hpp block control files generation, reason why this is optional.
* Block Interface: Analogously to the block controllers, you may want to add more design specific functionality to your design at the GNURadio interface. To do that, you add the logic into the block-interface files. In the same manner, if your control can be managed by adding NoC-Script to your xml file, you can disregard the generation of files.

Also, it is important to notice that if you don't intend to use the block controllers or you are not sure if you would, the presence of them in your design would do no harm. So, if in doubt, just add them. You may or may not add more functions inside them in a future stage of development of your OOT module. After finishing the parsing, the following files are going to be generated/edited:

Adding file 'lib/copy_impl.h'...
Adding file 'lib/copy_impl.cc'...
Adding file 'include/example/copy.h'...
Adding file 'include/example/copy_block_ctrl.hpp'...
Adding file 'lib/copy_block_ctrl_impl.cpp'...
Editing swig/example_swig.i...
Adding file 'python/qa_copy.py'...
Editing python/CMakeLists.txt...
Adding file 'grc/example_copy.xml'...
Adding file 'rfnoc/blocks/copy.xml'...
Adding file 'rfnoc/fpga-src/noc_block_copy.v'...
rfnoc/testbenches/noc_block_copy_tb folder created
Adding file 'rfnoc/testbenches/noc_block_copy_tb/noc_block_copy_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_copy_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_copy_tb/CMakeLists.txt'...

And, at this stage, you are all set up to start adding your custom functionalities.

=== Building the FPGA image ===

After you are done with your block development, you may want to generate the fpga image to actually run your implementation. A small script to help you do this is provided within the fpga repository that you installed in the [[Getting_Started_with_RFNoC_Development#Creating a development environment|Creating a development environment]] section.

The script is called 'make.py', and it is located at {INSTALL_PREFIX}/fpga/usrp3/tools/scripts. You can run the help by typing:

make.py --help

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
Path directory of the RFNoC Out-of-Tree module fpga srcs
{OOT_moddir}/rfnoc/fpga-src
-m MAX_NUM_BLOCKS, --max-num-blocks MAX_NUM_BLOCKS
Maximum number of blocks (Max. Allowed for x310|x300:
11, 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...]

There are also a good amount of arguments that you can pass to this script. For example, let's create an FPGA image using the 'copy' block we created earlier:

make.py fft copy fft window -I {OOT_moddir/rfnoc-example}/rfnoc/fpga-src/ -d x310 -t X310_RFNOC_HG -m 5 --fill-with-fifos [-o rfnoc_inst.v]

We're also adding an FFT and Window block, which are already in the script's path (they ship with the the Ettus FPGA code).

Here's how the script is used:

* '''Blocks:''' The first arguments are the names of blocks that you want to have in your image separated by a space. They can be from the blocks that you have from your OOT module or from the ones that are provided from Ettus, or a combination of those as well. There are two things to keep in mind while listing blocks here:
** So far, there is a restriction on the amount of blocks that you can add into the FPGA image: 10 for the X3X0 devices, and 14 for the E3X0 (if space permits).

:Although the amount of blocks is constantly increasing (thanks to the constant development and contribution of the community), a brief overview of the blocks from which you can choose can be found at [7].

* '''Include_dir: ''' To add your custom block to the FPGA Image, you just have to tell the Vivado builder where to find it. Here, with the -I directive you give the /Path/to/your/fpga-src, which is inside the rfnoc/ folder of your RFNoC OOT module. It is important to notice that inside this folder there is also a file called 'Makefile.srcs', in which you can find the path of your OOT and a list of all the OOT blocks that you have developed in your custom module. This is an autogenerated file, which is populated everytime that you add a block. Manually modifying this block may result in inconveniences.

* '''Device''': Generation-3 USRP devices support RFNoC, but the nextGen USRPs will support RFNoC as well. Having this in mind, with this -d directive you tell the script in which device you intend to use the image. By omitting this directive, the script will choose the X310 device as default. In the example, however, we chose explicitly the -d x310

* '''Target''': there are several build options, and you can choose the one that suits better with your design with the -t directive. Detailed information about the build targets can be found at the build instructions for USRP3, found under [6]. If -t is not given, a default target will be chosen for the given device. In the example, the -t X310_RFNOC_HG builds our design intended for the USRP X310 device, with 1GigE on SFP+ Port0, 10Gig on SFP+ Port1, and a DRAM TX FIFO.

* '''amount of blocks:''' if your RFNoC image doesn't really have the need of several RFNoC blocks, you can set the number of blocks to be inserted in the FPGA by running the -m directive. In the example command, 5 blocks are being added to the .bit file.

* '''Fill with FIFOs: ''' You can list a number of blocks smaller than the maximum allowed (or than the number fixed with -m). In addition, you can fill the rest of free slots with FIFO blocks. In the example, one FIFO block is going to be added to the FPGA image.

* '''Output file: ''' the purpose of the whole 'make.py' script is to autogenerate an instantiation file and populate the source files needed for Vivado to build the FPGA satisfactorily. But sometimes you may only want to see the effect of adding your OOT module on the fpga/ directory, or how the instantiation file would look like. With the -o directive, you generate the instantiation file and save it at the desired path with the given name. In the example, it is saved at the tmp/ directory with the name verilog_CE.v. Keep in mind that if you don't give the -o directory, the rfnoc_ce_auto_inst_x3x0.v file will be overwritten and the FPGA image build process will start automatically.

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

'''NOTE:''' [Environment setup] - The script will also set up your Vivado environment by automatically running the 'setupenv.sh' located at /top/{device}. So you don't have to run this script before running the make.py. In addition, keep in mind that the setupenv.sh assumes that your Vivado is installed in the default location /opt/Xilinx/Vivado. If you chose a different installation directory, you may want to modify the setupenv.sh script.

=== Creating and running testbenches ===

In order to make the iteration process much quicker, we encourage you to design test benches for each of your RFNoC blocks before implementing them into the FPGA image. By doing so, you can detect bugs or flaws in a relatively early stage of your design. RFNoC modtool provides the structure for the testbenches for each of the out-of-tree blocks that you add with the "rfnocmodtool add" option.

You can see that in the [[Getting_Started_with_RFNoC_Development#Adding custom blocks|Adding custom blocks]] section, the last files generated are:

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

The ''noc_block_copy_tb'' is a folder generated to contain all the files related to the test bench of the ''copy'' block. Each time that you create a new OOT block, a new folder will be generated as well. Inside of this folder, three files are located:

* '''CMakeLists.txt:''' this is an empty file used, so far, only to increase the scope of the compilers.
* '''noc_block_copy_tb.sv: ''' this is a ''System Verilog'' file, in which your custom tests are to be located. This is the '''only''' file that you have to modify according with your design.
* '''Makefile: ''' This file determinates the directives that run the simulation.

This files require the Vivado tools to work, so you have to have this tool installed (preferably at the default location,'' /opt/Xilinx''). Also, you would have to set up the Vivado environmental variables. Until now, you had to do this by hand, which is somewhat cumbersome. Now, with the use of the structure given by RFNoC modtool, the only thing that you have to do is build your own OOT module, which you have to do anyways! The builders will look up for the default locations of Vivado and the fpga repository and will set up your test benches so that they are ready to use, and you can fully focus on your design. To do so, simply create a build directory:

mkdir build && cd build/

and then run cmake. If you are using PyBOMBS, cmake will detect automatically the location of the ''fpga'' repository. If you are installing by source, you'd have to provide the location where you installed it.

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

Then, and only for the first time, you have to run the following command:

make test_tb

This command will modify your files by setting the correct path to the simulation tools. From now on, every time that you add a new block, this command will be run automatically.

Now you are ready to run the test bench! you don't have to go to the testbench directory, you can run it right there at the OOT main 'build/' directory! just run ''make noc_block_[name_of_your_block]_tb'', which in this example case is:

make noc_block_copy_tb

And the simulation will start. With every block that you create, also a make directive will be available for you to run the simulation right there at the main build directory.

= Other Resources =
[1] [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNURadio OutOfTree Modules tutorial]

[2] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf Introduction to RFNoC]

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

[4] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]

[5] [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015] Explaining the slides of [2][3][4] (In that order)

[6] [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]

[7] [https://kb.ettus.com/RFNoC_Getting_Started_Guides Knowledge base guide: RFNoC getting started]

[[Category:Software Resources]]

Getting Started with RFNoC Development

2016-07-06T23:35:36Z

MartinBraun:

= NOT FINISHED DONT READ! =

= Overview =

This application note gives a brief introduction into the steps required to start developing RFNoC blocks on your computer.
First, you need to make sure that you have all the tools required to do RFNoC development.
Then, we will set up a development sandbox in which you can do your RFNoC development.
Finally, we will run through the basic steps required to actually write custom RFNoC blocks.

= Prerequisites =
For any of this to work, you need to make sure you have all the tools to do both software and FPGA development.
Confirm you have the following tools installed:

* Xilinx Vivado. The specific version depends on the branch and state of the FPGA code and is very important. Make sure to install the correct version.
* Software build tools. If you can compile UHD from source, you have all the necessary components (If you're using PyBOMBS

Please make sure these tools are available before proceeding to the next step.

= Creating a development environment =

In the following, we will assume that GNU Radio is used as a helper tool for RFNoC development. Note that GNU Radio is by no means required to use or develop RFNoC, but it makes it a great deal easier. So in order to get your development environment set up, you will need the following software packages:

* UHD
* GNU Radio
* gr-ettus

The cleanest way to set this up is to install everything into a dedicated directory. PyBOMBS is the simplest way to do this.
If you haven't already downloaded and installed PyBOMBS, you can do so by running the following commands:

$ 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

From here, the easiest way to set up a PyBOMBS development environment is to run the following command:

$ pybombs prefix init ~/prefix/rfnoc -R rfnoc [-a alias]

This will do the following:

* Create a directory in ~/prefix/rfnoc
* Clone UHD, FPGA, GNU Radio, and gr-ettus sources into that directory
* Compile and install all the software

Then, enable the prefix:

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

PyBOMBS is by no means required to do any of these steps. If you wish to install the software manually, follow the individual install notes for GNU Radio, UHD and gr-ettus and make sure they are reachable by linkers and compilers.

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

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

If you have already UHD, GNU Radio and/or gr-ettus installed, it would be sufficient to checkout to the branches mentioned and pull them. Thereafter, build each of the repositories (first UHD, then GNU Radio, then gr-ettus).

= RFNoC Framework =

First, let's review briefly the RFNoC framework structure. The colourful image down here shows the basic structure of the RFNoC Stack.

[[File:rfnoc_stack.png|RFNoC Stack|600px|left|RFNoC Stack|link=https://kb.ettus.com/images/3/34/rfnoc_stack.png]]

From the stack there are clearly 5 different elements which a RFNoC developer has to take into account when creating an out-of-tree block. How these elements interact with each other is explained in more detail at [2][3][4]. However, from here we could easily infer that there are, at least, 3 questions that our out-of-tree design had to answer until this day:

;1. Does it have a complete FPGA Integration?
:A verilog file that describes the hardware implementation is what allows us to take advantage of the powerful FPGA that is being shipped with the current and next gen USRPs. For the current stage of development, the .v file has to not only implement the custom desired functionality but also a efficient interaction with the AXI bus and other FPGA blocks. In addition, the file has to be located in an specific location so that the building process can find it and use it as a resource for the IP generation.

;2. Does it have a block declaration/control?
:Now that the design has the hardware implementation in Verilog, we would like to take the samples (or other data items) out of the USRP and receive them at our host. The block has to have a clear declaration which defines, at least, its inputs and outputs (which are self explanatory) and the NoC-ID, which is the method of identification between the HW part of our design and the SW part. Now, we might add some control over the samples that are being streamed into the block, and for that we have two options that depend on the complexity of the control that we want to apply: if as developers we can add control using NoC-Script, that could easily be added into the XML file. But if we need more exhaustive control and multiple data stream treatment, we might want to add more coding into it. Block controllers can be added as C++ in the UHD host, carefully generating the headers and adding them in the correct include folder and in the same manner, develop our control and add it in the library folder.

;3. Does it have GNURadio integration?
: (Note: This is only required if using GNU Radio. Other frameworks might have similar requirements). GNURadio is where the application runs, and where more control over the host is applied, by adding block-specific settings, such as sample rate or bandwidths. In addition, is where we have the our block ready to connect it to other several blocks (which can be also RFNoC blocks). That means that we are almost done with our design. In order to do so, we have to add a new XML file that allows us to bind our design with GNURadio, and where we can edit the type on our I/Os, add variables for posterior signal processing, and a bunch of other design-specific parameters. In the same XML file we could add, just as we could have done at the block controllers, more block control by the means of NoC-Script. If we choose to do that, we could point our design to a "generic" implementation to control our GRC block. If we, otherwise, need even more control, we could choose to generate block code, that afterwards has to be located at gr-ettus: the headers as an include, the implementations as libraries.

So, you may think that this is just normal protocol of the RFNoC OOT block generation method. But, in order to answer this three questions with your OOT design, you have to take care of correct FPGA interfacing, correct API instantiation and right includes and correct location where to put your files... while you also put effort to the development of your custom design! Here at Ettus, we think that you should put all your effort in your custom design and let the '''RFNoC modtool''' do the dirty work.

= RFNoC Modtool =

In order to minimize the effort needed to implement a new RFNoC module, this gr_modtool-based tool provides the basic structure of the necessary files needed for the user to start with the development of his/her custom design right away. As it is gr_modtool-based, the manual found at [1] is also a great reference for this tool. Here, we discuss the features specific for the RFNoC modtool.

With the use of RFNoC ModTool, you can skip the struggle of locating the files of your design at different locations that depend (until now) on the location of your UHD and gr-ettus installation paths. Instead, you focus on your implementation and the tool takes care of boilerplate code and linking.

With the use of this tool, the questions stated in the last section would result in something like:
;1. Does it have a complete FPGA Integration?
: If not, start your design in the pregenerated verilog file, which also provides most of the standard AXI interface already done.

;2. Does it have a block declaration/control?
: Well, it has the files now, so write your functions if you need them. Don't even worry about modifying the files to add your NoC-ID: the tool will do that for you with the ID of your choice.

;3 Does it have GNURadio integration?
:It has it now. You just need to put additional control, in case you need it.

Don't worry about relocating your files, they are where they need to be: '''in your custom location.''' The tool generates the files so that the whole building process takes into account your design regardless of the location of your OOT module in your machine.

== Tool Installation ==

The tool is currently shipped within gr-ettus (radio-redo branch), so by installing gr-ettus, rfnocmodtool automatically becomes available.

== Tool Utilization ==

After the installation, you are ready to use the tool to generate standard code for your Out-of-tree module. To check the usage of the tool, just type:

$ rfnocmodtool help

linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e
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.

If you have used the gr_modtool provided by GNURadio, you'll be familiar with this usage.

== Creating an RFNoC OOT Module ==

At this point you are all set up to start generating your own RFNoC OOT and if you were thinking that it is just as easy as it is with gr_modtool, you are completely right! Simply go to your prefixes source location (~/prefix/rfnoc/src) and type:

$ rfnocmodtool newmod [NAME OF THE MODULE]

In the following, assume we want to create a module with the name 'example'. You can write the name of your module right after the 'newmod' command, but if you happen to forget it, the tool will ask for it interactively. This will create a folder containing the basic folders that you may need for a functional module.

$ rfnocmodtool newmod example
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e

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

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

In contrast with gr_modtool, this includes a folder called 'rfnoc', which is where we put the UHD/FPGA files (more details below).

=== Adding custom blocks ===

Now you can start adding blocks to your module. The only thing to do is go inside of the module you just created and type:

$ rfnocmodule add [NAME OF THE BLOCK]

For demonstrative purposes, lets create a block named 'copy'. As for the new module, the tool will ask you for the name of the block if you not put it in the first line. There is a bunch of directives that you could pass to the tool, but if you run it without any of these directives you should expect the following interactive parsing output:

$ rfnocmodtool add copy
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e

RFNoC module name identified: example
Block/code identifier: copy
Enter valid argument list, including default arguments:
Add Python QA code? [Y/n]
Add C++ QA code? [y/N]
Block NoC ID (Hexadecimal): FFFF
Skip Block Controllers Generation? [y/N]
Skip Block interface Generation? [y/N]

The tool is going to ask you about a valid argument list, in case you have that clear at this stage of your design, and for the generation of QA codes which are, such as in the case of gr_modtool, optional. Right after that, specific RFNoC questions appear:

* 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 you don't provide the NoC ID, it will be set to a random number.
* Block Controllers Generation: The block controllers are the C++ control that you can apply to the UHD-part of the design. In these files, you can add more control over this layer of your design. However, if you can manage to add the control you need over NoC-Script, you can omit the cpp/hpp block control files generation, reason why this is optional.
* Block Interface: Analogously to the block controllers, you may want to add more design specific functionality to your design at the GNURadio interface. To do that, you add the logic into the block-interface files. In the same manner, if your control can be managed by adding NoC-Script to your xml file, you can disregard the generation of files.

Also, it is important to notice that if you don't intend to use the block controllers or you are not sure if you would, the presence of them in your design would do no harm. So, if in doubt, just add them. You may or may not add more functions inside them in a future stage of development of your OOT module. After finishing the parsing, the following files are going to be generated/edited:

Adding file 'lib/copy_impl.h'...
Adding file 'lib/copy_impl.cc'...
Adding file 'include/example/copy.h'...
Adding file 'include/example/copy_block_ctrl.hpp'...
Adding file 'lib/copy_block_ctrl_impl.cpp'...
Editing swig/example_swig.i...
Adding file 'python/qa_copy.py'...
Editing python/CMakeLists.txt...
Adding file 'grc/example_copy.xml'...
Adding file 'rfnoc/blocks/copy.xml'...
Adding file 'rfnoc/fpga-src/noc_block_copy.v'...
rfnoc/testbenches/noc_block_copy_tb folder created
Adding file 'rfnoc/testbenches/noc_block_copy_tb/noc_block_copy_tb.sv'...
Adding file 'rfnoc/testbenches/noc_block_copy_tb/Makefile'...
Adding file 'rfnoc/testbenches/noc_block_copy_tb/CMakeLists.txt'...

And, at this stage, you are all set up to start adding your custom functionalities.

=== Building the FPGA image ===

After you are done with your block development, you may want to generate the fpga image to actually run your implementation. A small script to help you do this is provided within the fpga repository that you installed in the [[Getting_Started_with_RFNoC_Development#Creating a development environment|Creating a development environment]] section.

The script is called 'make.py', and it is located at {INSTALL_PREFIX}/fpga/usrp3/tools/scripts. You can run the help by typing:

make.py --help

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
Path directory of the RFNoC Out-of-Tree module fpga srcs
{OOT_moddir}/rfnoc/fpga-src
-m MAX_NUM_BLOCKS, --max-num-blocks MAX_NUM_BLOCKS
Maximum number of blocks (Max. Allowed for x310|x300:
11, 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...]

As it can be seen, there is also a good amount of arguments that you can pass to this script. Let's analyse an example of this: suppose that the OOT module that we created on the last step is ready to be burned into the FPGA, and for that we are going to use this command:

make.py fft copy fft window -I {OOT_moddir/rfnoc-example}/rfnoc/fpga-src/ -d x310 -t X310_RFNOC_HG -m 5 --fill-with-fifos -o ~/tmp/verilog_CE.v

and this command already gives us a lot of insight on how to use this script.

* '''Blocks:''' right after the script name you list the blocks that you want to have in your image separated by a space. They can be from the blocks that you have from your OOT module or from the ones that are provided from Ettus, or a combination of those as well. There are two things to keep in mind while listing blocks here:
** So far, there is a restriction on the amount of blocks that you can add into the FPGA image: 11 for the X3X0 devices, and 6 for the E3X0.
** The FPGAs provided in the USRPs are powerful and have rather high capacity. However, if the overall logic connections needed to implement the blocks that you listed is rather huge, then your FPGA may run out space and your synthesis may fail. For the example, we list two fft blocks and one window block (which are blocks provided with the installation) and one copy block (which is part of our custom design).

:Although the amount of blocks is constantly increasing (thanks to the constant development and contribution of the community), a brief overview of the blocks from which you can choose can be found at [7].

* '''Include_dir: '''Sure, you can add your custom block to the FPGA Image, you just have to tell the Vivado builder where to find it. Here, with the -I directive you give the /Path/to/your/fpga-src, which is inside the rfnoc/ folder of your RFNoC OOT module. It is important to notice that inside this folder there is also a file called 'Makefile.srcs', in which you can find the path of your OOT and a list of all the OOT blocks that you have developed in your custom module. This is an autogenerated file, which is populated everytime that you add a block. Manually modifying this block may result in inconveniences.

* '''Device''': nowadays the USRP3 devices support RFNoC, but the nextGen USRPs will support RFNoC as well. Having this in mind, with this -d directive you tell the script in which device you intend to use the image. By omitting this directive, the script will choose the X310 device as default. In the example, however, we chose explicitly the -d x310

* '''Target''': there are several build options, and you can choose the one that suits better with your design with the -t directive. Detailed information about the build targets can be found at the build instructions for USRP3, found under [6]. If not -t is given, a default target will be chosen for the given device. In the example, the -t X310_RFNOC_HG builds our design intended for the USRP X310 device, with 1GigE on SFP+ Port0, 10Gig on SFP+ Port1. DRAM TX FIFO.

* '''amount of blocks:''' if your RFNoC image doesn't really have the need of several RFNoC blocks, you can set the number of blocks to be inserted in the FPGA by running the -m directive. In the example command, 5 blocks are being added to the .bit.

* '''Fill with FIFOs: ''' You can list a number of blocks smaller than the maximum allowed (or than the number fixed with -m). In addition, you can fill the rest of free slots with FIFO blocks. In the example, one FIFO block is going to be added to the FPGA image.

* '''Output file: ''' the purpose of the whole 'make.py' script is to autogenerate an instantiation file and populate the source files needed for Vivado to build the FPGA satisfactorily. But sometimes you may only want to see the effect of adding your OOT module on the fpga/ directory, or how the instantiation file would look like. With the -o directive, you generate the instantiation file and save it at the desired path with the given name. In the example, it is saved at the tmp/ directory with the name verilog_CE.v. Keep in mind that if you don't give the -o directory, the rfnoc_ce_auto_inst_x3x0.v file will be overwritten and the FPGA image build process will start automatically.

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

'''NOTE:''' [Environment setup] - The script will also set up your Vivado environment by automatically running the 'setupenv.sh' located at /top/{device}. So you don't have to run this script before running the make.py. In addition, keep in mind that the setupenv.sh assumes that your Vivado is installed in the default location /opt/Xilinx/Vivado. If you chose a different installation directory, you may want to modify the setupenv.sh script.

=== Creating and running testbenches ===

In order to make the iteration process much quicker, we encourage you to design test benches for each of your RFNoC blocks before implementing them into the FPGA image. By doing so, you can detect bugs or flaws in a relatively early stage of your design. RFNoC modtool provides the structure for the testbenches for each of the out-of-tree blocks that you add with the "rfnocmodtool add" option.

You can see that in the [[Getting_Started_with_RFNoC_Development#Adding custom blocks|Adding custom blocks]] section, the last files generated are:

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

The ''noc_block_copy_tb'' is a folder generated to contain all the files related to the test bench of the ''copy'' block. Each time that you create a new OOT block, a new folder will be generated as well. Inside of this folder, three files are located:

* '''CMakeLists.txt:''' this is an empty file used, so far, only to increase the scope of the compilers.
* '''noc_block_copy_tb.sv: ''' this is a ''System Verilog'' file, in which your custom tests are to be located. This is the '''only''' file that you have to modify according with your design.
* '''Makefile: ''' This file determinates the directives that run the simulation.

This files require the Vivado tools to work, so you have to have this tool installed (preferably at the default location,'' /opt/Xilinx''). Also, you would have to set up the Vivado environmental variables. Until now, you had to do this by hand, which is somewhat cumbersome. Now, with the use of the structure given by RFNoC modtool, the only thing that you have to do is build your own OOT module, which you have to do anyways! The builders will look up for the default locations of Vivado and the fpga repository and will set up your test benches so that they are ready to use, and you can fully focus on your design. To do so, simply create a build directory:

mkdir build && cd build/

and then run cmake. If you are using PyBOMBS, cmake will detect automatically the location of the ''fpga'' repository. If you are installing by source, you'd have to provide the location where you installed it.

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

Then, and only for one time, you have to run the following command:

make test_tb

This command will modify your files by setting the correct path to the simulation tools. From now on, every time that you add a new block, this command will be run automatically.

Now you are ready to run the test bench! you don't have to go to the testbench directory, you can run it right there at the OOT main 'build/' directory! just run ''make noc_block_[name_of_your_block]_tb'', which in this example case is:

make noc_block_copy_tb

And the simulation will start. With every block that you create, also a make directive will be available for you to run the simulation right there at the main build directory.

= Other Resources =
[1] [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNURadio OutOfTree Modules tutorial]

[2] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf Introduction to RFNoC]

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

[4] [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]

[5] [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015] Explaining the slides of [2][3][4] (In that order)

[6] [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]

[7] [https://kb.ettus.com/RFNoC_Getting_Started_Guides Knowledge base guide: RFNoC getting started]

[[Category:Software Resources]]

Software Development on the E310 and E312

2016-06-23T22:53:01Z

MartinBraun:

==Application Note Number==
'''AN-311'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-05-24
|style="text-align:center;"| Martin Braun<br> Nicolas Cuervo
|style="text-align:center;"| Initial creation
|}

==Abstract==
This application note will cover the software development process on the USRP E310 and E312.

==Overview==

Note: Linux only.

When developing software for the embedded series, the recommended workflow is to set up a cross-compiling environment. Software is *not* compiled on the device, but on a separate machine (a more powerful machine that can compile much faster).

E310/E312 manual page with supplemental info:

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

Also useful:

* http://gnuradio.org/redmine/projects/gnuradio/wiki/Embedded

PyBOMBS documentation:
* http://gnuradio.org/redmine/projects/pybombs/wiki
* https://github.com/gnuradio/pybombs

== Preparing the device ==

It's best to start from scratch for any kind of embedded development, so the first step is to download the latest release for the device. For the E310/E312, this means downloading the latest SD card images from the website: http://files.ettus.com/e3xx_images/ and installing it to the SD card according to the manual.

Once the latest image is flashed, turn on the device.

=== Network setup ===

For the following tutorial, it is necessary that you can SSH into the embedded device from your development machine and vice versa. For information on how to set up networking on the embedded device, consult the manual.

In the following, we will assume that the hostname of the development machine is <code>desktop</code>, the hostname of the embedded device is <code>e3xx</code> and the username on the development machine is <code>dev</code>.

On the development machine you should be able to run the following command:

$ ssh root@e3xx

And on the embedded device you should be able to run the following command:

$ ssh dev@desktop

You might need to access the embedded device through a serial console to set up networking. Consult the device's manual for details.

== Preparing the development machine ==

This procedure can be done by using PyBOMBS or manually installing all the elements from source.

=== Preparation using PyBOMBS ===

PyBOMBS (Python Build Overlay Managed Bundle System) has currently a recipe that automates the installation of all the elements necessary to cross-compile for the E3XX. In order to use this method, first download and install PyBOMBS:

$ sudo pip install git+https://github.com/gnuradio/pybombs.git

After you have PyBOMBS installed, download and install the necessary recipes to set up the machine:

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

The "Ettus" recipe provides the necessary elements for the E3XX, the gr-recipes repository provides all the other packages (GNU Radio, out of tree modules, etc.). More information about the recipes and PyBOMBS in general can be found at the PyBOMBS manual (links provided in the "Overview" section).

On some distributions (e.g. Ubuntu), PyBOMBS can run into shell issues. To avoid those problems, it is recommended to run the following command before continuing, and choose "no" in the prompted dialogue:

$ sudo dpkg-reconfigure dash

Now you can proceed to install the SDK, UHD, GNU Radio and gr-ettus with this simple command:

$ pybombs prefix init /path/to/prefix -R e3xx-radio-redo [-a alias]

Where "/path/to/prefix" has to be previously created (for example ~/prefix/ or ~/prefix/e300). Keep in mind that this command will take a while to finish, due to the size and amount of files that need to be downloaded, cloned and installed.

After the installation is finished, proceed to the [[Software_Development_on_the_E310_and_E312#Running the new UHD via sshfs|Running the new UHD via sshfs]] section.

=== Preparation from Source ===
On your development machine, you will need to create a directory in which the development will take place. This directory is called the '''prefix''', and in the following, we will assume it is in <code>~/prefix</code>. If you have not created it before, run the following command:

$ mkdir ~/prefix

==== Installing the SDK ====

Since you're cross-compiling (i.e., compiling for a different architecture than the development machine's) you require an SDK to do the development. Go the page where you downloaded the device image, and make sure you get the corresponding SDK.

SDKs have filenames such as <code>oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh</code>. The files are quite big, so it can take a while to download them.

The SDKs contain the compiler toolchain, but also contain libraries etc. that already exist on the embedded device. This way, when compiling and linking, you know that what you compile on your development machine will also work on the device.

To install the SDK, execute the downloaded file:

$ sh ./oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh

Depending on your setup, you may have to use the following command:

$ bash ./oecore-x86_64-armv7ahf-vfp-neon-toolchain-nodistro.0.sh

(If that's the case, you may want to run the sudo dpkg-configure dash command, see the PyBOMBS section).
It will ask you where to install it to. Choose the prefix path (<code>~/prefix</code>).
Unzipping and installing takes a while. After it's done, you should see something like this:

$ ls ~/prefix
environment-setup-armv7ahf-vfp-neon-oe-linux-gnueabi
site-config-armv7ahf-vfp-neon-oe-linux-gnueabi
sysroots/
usr/
version-armv7ahf-vfp-neon-oe-linux-gnueabi

(The exact contents of the directory may differ).

==== Setting up the environment ====

Before running any of the following commands, you need to set up the environment as outlined on the device manual.
You need to source the environment file:

$ cd ~/prefix
$ source ./environment-setup-armv7ahf-vfp-neon-oe-linux-gnueabi
$ echo $CC # This is just to confirm it worked.
arm-oe-linux-gnueabi-gcc -march=armv7-a -mfloat-abi=hard -mfpu=neon --sysroot=~/prefix/e300/sysroots/armv7ahf-vfp-neon-oe-linux-gnueabi

As you can see, it will change all kinds of paths to use different compilers and libraries.
Note that during this shell session, you won't be able to run a lot of other things on your development machines, so you should dedicate a separate shell window for this.

Your development machine is now ready to cross-compile.

== Compiling and installing UHD ==

To cross-compile software, the SDK and the environment settings are usually not sufficient.
Your software requires a toolchain setup at configuration time to build correctly. UHD brings
support for this out of the box, so let's use UHD as an example on how to build custom software.
First, let's make sure you have the source code for UHD in your prefix (it can be elsewhere, but
for this example we'll keep *everything* inside the prefix directory).

$ cd ~/prefix
$ mkdir src/ # Let's create a src/ subdirectory which we'll use throughout the tutorial
$ git clone https://github.com/EttusResearch/uhd.git
$ cd src/uhd/host
$ mkdir build
$ cd build

Now, before we do the next step, confirm that you have the correct environment loaded (see the step
before). We now need to configure the build setup to cross-compile correctly.

$ cmake -DCMAKE_TOOLCHAIN_FILE=../host/cmake/Toolchains/oe-sdk_cross.cmake -DCMAKE_INSTALL_PREFIX=/usr -DENABLE_E300=ON ..

The exact command may differ (consult the device manual). However, two things are notable:

* We specify a toolchain file. This is how CMake knows how to set up a cross-compile, if the environment variables are set up correctly.
* Second, we specify the install prefix as <code>/usr</code>. This might seem odd, but it's actually the prefix *on the device*, not on our development machine.

Now that we have it all set up, we can compile:

$ make -j4

This step might take longer than you're used to -- that's because cross-compiling is slightly slower than native compiles. However, it's much, much faster than trying to compile on the device.

Installing is also slightly different than usual:

$ make install DESTDIR=~/prefix

The <code>DESTDIR</code> part will make sure it gets installed into the prefix, and doesn't try to actually install to <code>/usr/</code>.

== Running the new UHD via sshfs ==

The cleanest way to test your newly built UHD is to mount the prefix onto your embedded device.
From your development machine, log onto the embedded device and mount the prefix:

$ ssh root@e3xx # After this, we're logged onto the embedded device
$ pwd # Check where we are
/home/root
$ mkdir usr # Create a directory to mount our prefix, this only needs doing once
$ sshfs dev@desktop:prefix/ usr/ # This will mount the prefix on the development machine to ~/usr
$ ls usr/ # The actual output of this may differ
environment-setup-armv7ahf-vfp-neon-oe-linux-gnueabi
site-config-armv7ahf-vfp-neon-oe-linux-gnueabi
sysroots/
usr/
version-armv7ahf-vfp-neon-oe-linux-gnueabi

The output of the final <code>ls</code> command should be the same as before when doing <code>ls ~/prefix</code> on the development machine.
Nearly there! Now, we need to update the environment variables and paths in our ssh session on the embedded device.
We will add a new file called <code>set_env</code> into the prefix with the following contents (if you prepared your development machine with PyBOMBS, this file should be already included):

LOCALPREFIX=~/usr
export PATH=$LOCALPREFIX/bin:$PATH
export LD_LOAD_LIBRARY=$LOCALPREFIX/lib:$LD_LOAD_LIBRARY
export LD_LIBRARY_PATH=$LOCALPREFIX/lib:$LD_LIBRARY_PATH
export PYTHONPATH=$LOCALPREFIX/lib/python2.7/site-packages:$PYTHONPATH
export PKG_CONFIG_PATH=$LOCALPREFIX/lib/pkgconfig:$PKG_CONFIG_PATH
export GRC_BLOCKS_PATH=$LOCALPREFIX/share/gnuradio/grc/blocks:$GRC_BLOCKS_PATH
export UHD_RFNOC_DIR=$LOCALPREFIX/share/uhd/rfnoc/
export UHD_IMAGES_DIR=$LOCALPREFIX/share/uhd/images

You can see the contents is very simple -- all it does is point the most important paths into our prefix.
Going back to the SSH session on the embedded device, you should be able to source that file now:

$ which uhd_find_devices # This will point to the old UHD, which we do not want
/usr/bin/uhd_find_devices
$ source ./set_env
$ which uhd_find_devices # Now it should point to the new version
/home/root/usr/bin/uhd_find_devices

The last command is to make sure you're actually using the newly compiled UHD, because all of the SD card images already ship a version of UHD.
In the example above, it worked, and we're ready to go!

The examples get installed to <code>lib/</code>, so if you want to try your newly compiled UHD, you can do so by running, e.g., the following command:

$ ~/prefix/lib/uhd/examples/benchmark_rate --tx_rate 1e6

Or anything else in the <code>examples</code> subdirectory.

At this point, it should be clear why the prefix/sshfs approach is so useful. Everything that is related to the install is stored in the same directory, you can zip it up and move it another computer if you like, and the embedded device doesn't actually store any of the development files. As soon as you unmount the sshfs mount, and reset the environment, it will be back in its default state.

== Compiling and installing GNU Radio ==

[[File:cmake_gr.png|thumb|left|Output example of CMakeGUI for the build of GNU Radio.|link=https://kb.ettus.com/images/f/f9/cmake_gr.png]]

In principle, the work flow for GNU Radio is just the same as for UHD. However, GNU Radio depends on UHD, and you want it to use the new UHD instead of the one that ships with the device (and is in your SDK).
There are two ways to go ahead: You could either also install UHD into your SDK, but the downside is that you then taint your SDK and it's a non-reversible operation.

A much easier way is to simply point your GNU Radio configuration to the new UHD libs instead of the old ones.
Again, clone the repo into <code>~/prefix/src/gnuradio</code>, and then run the following command (again, you need to make sure the environment is set up correctly):

$ cd ~/prefix
$ source ./environment-setup-armv7ahf-vfp-neon-oe-linux-gnueabi # To be sure that our environment is correctly set up
$ cd src/
$ git clone --recursive https://github.com/gnuradio/gnuradio.git
$ cd gnuradio
$ mkdir build-arm
$ cd build-arm
$ cmake -Wno-dev -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake -DCMAKE_INSTALL_PREFIX=/usr -DENABLE_GR_VOCODER=OFF -DENABLE_GR_ATSC=OFF -DENABLE_GR_DTV=OFF -DENABLE_DOXYGEN=OFF ../
$ make -j4 # This may take a while
$ make -j4 install DESTDIR=~/prefix

To confirm that this worked, it can help to open the CMake configuration in a GUI and check that the UHD-related variables point to the correct libraries. To see more detailed information about the compile, click the "Advanced" checkbox. By doing so, a several number of configuration options appear, which can be not only read but also modified. Notice that the path for UHD_includes and UHD_libraries should point to the UHD source folder installed in the step before. If they are still pointing to the UHD that comes with the device (which is [$PREFIX$}/sysroots/armv7ahf-vfp-neon-oe-linux-gnueabi/usr/lib/cmake/uhd) they should be modified by changing the path directly on the CMake GUI or by adding recompiling since cmake from terminal by adding the directives accordingly, as follows:
$ cmake -Wno-dev -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake \-DCMAKE_INSTALL_PREFIX=/usr -DENABLE_GR_VOCODER=OFF -DENABLE_GR_ATSC=OFF -DENABLE_GR_DTV=OFF -DENABLE_DOXYGEN=OFF -DUHD_DIR=~/prefix/usr/lib/cmake/uhd/ -DUHD_INCLUDE_DIRS=~/prefix/usr/include -DUHD_LIBRARIES=~/prefix/usr/lib/libuhd.so ../

=== Using GNU Radio Companion ===

Since the embedded devices usually don't have a screen, GNU Radio Companion (GRC) is not a useful tool on the device. However, the development machine can be used to generate flow graphs and compile to Python. Some best practices:

* Save both the .grc file and the generated .py file into the prefix
* Set the 'No GUI' option for Python files that are to be executed on the embedded device
* Run the Python scripts generated from GRC on the command line on the embedded device
* If you need visualization, run a separate flow graph on the development machine with the visualization GUI widgets. Use UDP sinks/sources or ZeroMQ blocks to pass data from the embedded device to the development machine.

=== Compiling and installing out-of-tree modules (e.g. gr-ettus) ===

Again, the process is very similar to building GNU Radio. You must make sure that all the correct libraries are linked to, and that it doesn't accidentally pick up libraries from the SDK (e.g. GNU Radio libraries).

# TODO add screenshot cmake-gui on how this should look like

[[Category:Application Notes]]

Getting Started with RFNoC Development

2016-06-21T23:15:08Z

MartinBraun:

Getting Started with RFNoC Development

2016-06-21T23:12:36Z

MartinBraun:

Getting Started with RFNoC Development

2016-06-21T23:12:14Z

MartinBraun: Widened scope

Getting Started with RFNoC Development

2016-06-21T22:26:24Z

MartinBraun: MartinBraun moved page RFNoC-modtool to Getting Started with RFNoC Development: Old title was misleading

= NOT FINISHED DONT READ! =

==Overview==
{|
|style="vertical-align:top; width: 60%;"|In order to minimize the effort needed to implement a new RFNoC module, this gr_modtool-based tool provides the basic structure of the necessary files needed for the user to start with the development of his/her custom design right away. As it is gr_modtool-based, the manual found at [1] is also a great reference for this tool. Here, we discuss the features for this specific variation

With the use of RFNoC ModTool, you can skip the struggle of locating the files of your design at different locations that depend (until now) on the location of your UHD and gr-ettus installation paths. Instead, you focus on your implementation and the tool takes care of boilerplate code and linking.

== Tool Installation ==

The tool is currently shipped within gr-ettus (radio-redo branch), so you can install it using PyBOMBS or from source.

=== gr-ettus Installation using PyBOMBS ===

If you haven't already downloaded and installed PyBOMBS, you can do it by running the following commands:

$ 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

From here, the easiest way to set up a PyBOMBS development environment is to run the following command:

$ pybombs prefix init /path/to/prefix -R rfnoc [-a alias]

This will do the following:

- Create a directory in /path/to/prefix
- Clone UHD, FPGA, GNU Radio, and gr-ettus sources into that directory
- Start the builds for the software

=== gr-ettus Installation by source ===

It is important to notice that this tool is still in an early stage, and this creates the necessity of installing the gr-ettus dependencies that are compatible with the tool, reason why it is recommended to checkout directly to the stated branches:

$ git clone --recursive -b rfnoc-radio-redo https://github.com/EttusResearch/uhd.git
$ git clone -b maint https://github.com/gnuradio/gnuradio.git
$ git clone -b radio-redo https://github.com/EttusResearch/gr-ettus.git

If you have already uhd, gnuradio and/or gr-ettus installed, it would be sufficient to checkout to the branches mentioned and pull them. Thereafter, build each of the repositories (first UHD, then GNU Radio, then gr-ettus).

== Tool Utilization ==

After the installation, you are ready to use the tool to generate standard code for your Out-of-tree module. To check the usage of the tool, just type:

$ rfnocmodtool --help

linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e

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.

If you have used the gr_modtool provided by GNURadio, you'd be familiar with this usage.

=== Creating a RFNoC OOT Module ===

At this point you are all set up to start generating your own RFNoC OOT and if you were thinking that it is just as easy as it is with gr_modtool, you are completely right! Simply go to a desired location and type:

$ rfnocmodtool newmod [NAME OF THE MODULE]

In the following, assume we want to create a module with the name 'example'. You can write the name of your module right after the 'newmod' command, but if you happen to forget it, the tool will ask for it interactively. This will create a folder containing the basic folders that you may need for a functional module.

$ rfnocmodtool newmod example
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.rfnoc-radio-redo-0-fd4d734e

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

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

In contrast with gr_modtool, this includes al folder called 'rfnoc', which is where we put the UHD/FPGA files (more details below).

=== Adding custom blocks ===

Now you can start adding blocks to your module. The only thing to do is go inside of the module you just created and type:

$ rfnocmodule add [NAME OF THE BLOCK]

==Other Resources==
[1] GNURadio OutOfTree Modules: http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules

https://github.com/EttusResearch/uhd/wiki/RFNoC:-Getting-Started

https://github.com/EttusResearch/uhd/wiki/RFNoC:--Specification

[[Category:Software Resources]]