Ettus Knowledge Base - User contributions [en]

RFNoC Frequently Asked Questions

2025-10-01T15:06:40Z

WadeFife: Reorder questions and remove redundant questions

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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 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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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 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 should I install? ===

You should always use the Vivado version specified in the UHD documentation for your UHD release, including any required patches. See the [https://files.ettus.com/manual/md_usrp3_build_instructions.html UHD User Manual] for the latest Vivado version requirements.

The exact version string can be found in the <code>setupenv.sh</code> script for the FPGA target you intend to build (e.g., <code>fpga/usrp3/top/x400/setupenv.sh</code>).

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

=== How do I get Vivado 2021.1 to work on Ubuntu 22.04 and later? ===

Vivado needs the <code>libncurses5</code> and <code>libtinfo5</code>, which are no longer included by default in recent Ubuntu installations. To install them, run the following commands:

sudo apt update
wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2ubuntu0.1_amd64.deb
sudo apt install ./libtinfo5_6.3-2ubuntu0.1_amd64.deb
wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libncurses5_6.3-2ubuntu0.1_amd64.deb
sudo apt install ./libncurses5_6.3-2ubuntu0.1_amd64.deb

=== Can I use a different Vivado version? ===

While it is technically possible to use a different Vivado version, doing so comes with significant risks. Vivado versions are not fully compatible with each other, and changing the version usually leads to FPGA build failures. Furthermore, the shipping FPGA images for each UHD release are tested and validated using the specified Vivado version. Other versions are untested. For these reasons, the build process checks the Vivado version and will raise an error if you run <code>setupenv.sh</code> with an unsupported version installed.

Because alternative versions are untested, using a different Vivado version is strongly discouraged. If you choose to proceed anyway, you must:

* Update the Vivado version string in the setupenv.sh script for your FPGA target.
* Update all IP blocks to versions compatible with the new Vivado release, and modify any connections in the USRP code to match the updated IP interfaces. Failure to update the IP blocks will result in errors about the IP being locked. Incorrect or incomplete updates to IP connections may cause build failures or result in a non-functional FPGA image.
* Additional changes may be required depending on the Vivado version and the specific USRP target you are building. Unfortunately, it's not possible to predict these changes in advance.

== 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. In UHD 4.7 and later, this can be done by adding the <code>-g</code> argument to the <code>rfnoc_image_builder</code> command. In UHD 4.6 and earlier, this can be done by adding <code>GUI=1</code> to the <code>make</code> arguments. Example: <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: <code>save_project_as project_name project_dir</code> 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: <code>set_property source_mgmt_mode All [current_project]</code>

In some cases, it may also be necessary to reset the output products for some of the IP. If you get an error message about a BD sub-design being not generated for the synthesis target, then navigate to the "IP Sources" tab in the Project Manager Sources window, then right-click on affected IP and select "Reset Output Products...", then click "Reset".

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.

=== When I start an FPGA build or use rfnoc_image_builder, I get an error "setupenv.sh: source: not found" and the build fails. What happened? ===

In some Linux distributions (e.g. Ubuntu) <code>dash</code> is set as default shell which can cause FPGA builds to fail.

Below is an example of the error. Note, that your message may look somewhat different depending on UHD version and USRP target but the important lines are marked in bold.

rfnoc_image_builder -y e320_rfnoc_image_core_fft.yml -t E320_1G
Using FPGA directory /home/someuser/uhd/fpga
Selected device: e320
Build artifacts directory already exists (contents will be overwritten).
Launching build with the following settings:
* FPGA Directory: /home/someuser/uhd/fpga/usrp3/top/e320
* Build Artifacts Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build-usrp_e320_fpga_1G
* Build Output Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build
* Build IP Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build-ip
Executing the following command: . ./setupenv.sh && make E320_1G BUILD_DIR=/home/someuser/uhd/fpga/usrp3/top/e320/build-usrp_e320_fpga_1G IMAGE_CORE_NAME=usrp_e320_fpga_1G
'''/bin/sh: 6: ./setupenv.sh: Bad substitution'''
'''/bin/sh: 8: ./setupenv.sh: declare: not found'''
/bin/sh: 9: ./setupenv.sh: PRODUCT_ID_MAP[E320]=zynq/xc7z045/ffg900/-3: not found
'''/bin/sh: 15: ./setupenv.sh: source: not found'''
Build finished with return code 127.

It is recommended to set the default shell to <code>bash</code> by running the following command in the terminal. When asked <code>Use dash as the default system shell (/bin/sh)?</code> choose <code><No></code>.

$ sudo dpkg-reconfigure dash

Confirm your default shell was changed to bash by running this command:

$ ll /bin/sh

You should see output similar to this:

lrwxrwxrwx 1 root root 4 Oct 10 2020 /bin/sh -> bash*

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

RFNoC Frequently Asked Questions

2025-10-01T14:41:27Z

WadeFife: Add which Vivado version to use, and using different Vivado version

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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 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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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.

=== Why does the Vivado 2021.1 installer get stuck or not start on Ubuntu? ===

The Vivado installer needs the libncurses5 and libtinfo5 libraries to run correctly. They can be installed by running the following commands:

sudo apt update
wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2ubuntu0.1_amd64.deb
sudo apt install ./libtinfo5_6.3-2ubuntu0.1_amd64.deb
wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libncurses5_6.3-2ubuntu0.1_amd64.deb
sudo apt install ./libncurses5_6.3-2ubuntu0.1_amd64.deb

== 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. In UHD 4.7 and later, this can be done by adding the <code>-g</code> argument to the <code>rfnoc_image_builder</code> command. In UHD 4.6 and earlier, this can be done by adding <code>GUI=1</code> to the <code>make</code> arguments. Example: <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: <code>save_project_as project_name project_dir</code> 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: <code>set_property source_mgmt_mode All [current_project]</code>

In some cases, it may also be necessary to reset the output products for some of the IP. If you get an error message about a BD sub-design being not generated for the synthesis target, then navigate to the "IP Sources" tab in the Project Manager Sources window, then right-click on affected IP and select "Reset Output Products...", then click "Reset".

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.

=== When I start an FPGA build or use rfnoc_image_builder, I get an error "setupenv.sh: source: not found" and the build fails. What happened? ===

In some Linux distributions (e.g. Ubuntu) <code>dash</code> is set as default shell which can cause FPGA builds to fail.

Below is an example of the error. Note, that your message may look somewhat different depending on UHD version and USRP target but the important lines are marked in bold.

rfnoc_image_builder -y e320_rfnoc_image_core_fft.yml -t E320_1G
Using FPGA directory /home/someuser/uhd/fpga
Selected device: e320
Build artifacts directory already exists (contents will be overwritten).
Launching build with the following settings:
* FPGA Directory: /home/someuser/uhd/fpga/usrp3/top/e320
* Build Artifacts Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build-usrp_e320_fpga_1G
* Build Output Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build
* Build IP Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build-ip
Executing the following command: . ./setupenv.sh && make E320_1G BUILD_DIR=/home/someuser/uhd/fpga/usrp3/top/e320/build-usrp_e320_fpga_1G IMAGE_CORE_NAME=usrp_e320_fpga_1G
'''/bin/sh: 6: ./setupenv.sh: Bad substitution'''
'''/bin/sh: 8: ./setupenv.sh: declare: not found'''
/bin/sh: 9: ./setupenv.sh: PRODUCT_ID_MAP[E320]=zynq/xc7z045/ffg900/-3: not found
'''/bin/sh: 15: ./setupenv.sh: source: not found'''
Build finished with return code 127.

It is recommended to set the default shell to <code>bash</code> by running the following command in the terminal. When asked <code>Use dash as the default system shell (/bin/sh)?</code> choose <code><No></code>.

$ sudo dpkg-reconfigure dash

Confirm your default shell was changed to bash by running this command:

$ ll /bin/sh

You should see output similar to this:

lrwxrwxrwx 1 root root 4 Oct 10 2020 /bin/sh -> bash*

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

=== How do I get Vivado 2021.1 to work with Ubuntu 22.04 and later? ===

Vivado 2021.1 requires the <code>libncurses5</code> library, which is no longer included by default in recent Ubuntu installations.

==== Ubuntu 22.04 ====

You can install <code>libncurses5</code> by running the following commands:

$ sudo apt update
$ sudo apt install libncurses5

==== Ubuntu 24.04 ====

In Ubuntu 24.04, <code>libncurses5</code> is no longer available in the default repositories. To install it, you need to add a repository that includes the required package.

First, create or edit the file:

/etc/apt/sources.list.d/ubuntu-focal-sources.list

Then add the following line to the file:

deb http://security.ubuntu.com/ubuntu focal-security main universe

Next, update your package list and install the library:

$ sudo apt update
$ sudo apt install libncurses5

=== Which Vivado version should I install? ===

You should always use the Vivado version specified in the UHD documentation for your UHD release, including any required patches. The exact version string can be found in the <code>setupenv.sh</code> script for the FPGA target you intend to build (e.g., <code>fpga/usrp3/top/x400/setupenv.sh</code>).

=== Can I use a different Vivado version? ===

While it is technically possible to use a different Vivado version, doing so comes with significant risks. Vivado versions are not fully compatible with each other, and changing the version usually leads to FPGA build failures. Furthermore, the shipping FPGA images for each UHD release are tested and validated using the specified Vivado version. Other versions are untested. For these reasons, the build process checks the Vivado version and will raise an error if you run <code>setupenv.sh</code> with an unsupported version installed.

Because alternative versions are untested, using a different Vivado version is strongly discouraged. If you choose to proceed anyway, you must:

* Update the Vivado version string in the setupenv.sh script for your FPGA target.
* Update all IP blocks to versions compatible with the new Vivado release, and modify any connections in the USRP code to match the updated IP interfaces. Failure to update the IP blocks will result in errors about the IP being locked. Incorrect or incomplete updates to IP connections may cause build failures or result in a non-functional FPGA image.

RFNoC Frequently Asked Questions

2025-10-01T14:35:45Z

WadeFife: Add how to install libncurses on Ubuntu 22 and later

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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 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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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.

=== Why does the Vivado 2021.1 installer get stuck or not start on Ubuntu? ===

The Vivado installer needs the libncurses5 and libtinfo5 libraries to run correctly. They can be installed by running the following commands:

sudo apt update
wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2ubuntu0.1_amd64.deb
sudo apt install ./libtinfo5_6.3-2ubuntu0.1_amd64.deb
wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libncurses5_6.3-2ubuntu0.1_amd64.deb
sudo apt install ./libncurses5_6.3-2ubuntu0.1_amd64.deb

== 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. In UHD 4.7 and later, this can be done by adding the <code>-g</code> argument to the <code>rfnoc_image_builder</code> command. In UHD 4.6 and earlier, this can be done by adding <code>GUI=1</code> to the <code>make</code> arguments. Example: <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: <code>save_project_as project_name project_dir</code> 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: <code>set_property source_mgmt_mode All [current_project]</code>

In some cases, it may also be necessary to reset the output products for some of the IP. If you get an error message about a BD sub-design being not generated for the synthesis target, then navigate to the "IP Sources" tab in the Project Manager Sources window, then right-click on affected IP and select "Reset Output Products...", then click "Reset".

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.

=== When I start an FPGA build or use rfnoc_image_builder, I get an error "setupenv.sh: source: not found" and the build fails. What happened? ===

In some Linux distributions (e.g. Ubuntu) <code>dash</code> is set as default shell which can cause FPGA builds to fail.

Below is an example of the error. Note, that your message may look somewhat different depending on UHD version and USRP target but the important lines are marked in bold.

rfnoc_image_builder -y e320_rfnoc_image_core_fft.yml -t E320_1G
Using FPGA directory /home/someuser/uhd/fpga
Selected device: e320
Build artifacts directory already exists (contents will be overwritten).
Launching build with the following settings:
* FPGA Directory: /home/someuser/uhd/fpga/usrp3/top/e320
* Build Artifacts Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build-usrp_e320_fpga_1G
* Build Output Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build
* Build IP Directory: /home/someuser/uhd/fpga/usrp3/top/e320/build-ip
Executing the following command: . ./setupenv.sh && make E320_1G BUILD_DIR=/home/someuser/uhd/fpga/usrp3/top/e320/build-usrp_e320_fpga_1G IMAGE_CORE_NAME=usrp_e320_fpga_1G
'''/bin/sh: 6: ./setupenv.sh: Bad substitution'''
'''/bin/sh: 8: ./setupenv.sh: declare: not found'''
/bin/sh: 9: ./setupenv.sh: PRODUCT_ID_MAP[E320]=zynq/xc7z045/ffg900/-3: not found
'''/bin/sh: 15: ./setupenv.sh: source: not found'''
Build finished with return code 127.

It is recommended to set the default shell to <code>bash</code> by running the following command in the terminal. When asked <code>Use dash as the default system shell (/bin/sh)?</code> choose <code><No></code>.

$ sudo dpkg-reconfigure dash

Confirm your default shell was changed to bash by running this command:

$ ll /bin/sh

You should see output similar to this:

lrwxrwxrwx 1 root root 4 Oct 10 2020 /bin/sh -> bash*

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

=== How do I get Vivado 2021.1 to work with Ubuntu 22.04 and later? ===

Vivado 2021.1 requires the <code>libncurses5</code> library, which is no longer included by default in recent Ubuntu installations.

==== Ubuntu 22.04 ====

You can install <code>libncurses5</code> by running the following commands:

$ sudo apt update
$ sudo apt install libncurses5

==== Ubuntu 24.04 ====

In Ubuntu 24.04, <code>libncurses5</code> is no longer available in the default repositories. To install it, you need to add a repository that includes the required package.

First, create or edit the file:

/etc/apt/sources.list.d/ubuntu-focal-sources.list

Then add the following line to the file:

deb http://security.ubuntu.com/ubuntu focal-security main universe

Next, update your package list and install the library:

$ sudo apt update
$ sudo apt install libncurses5

RFNoC Frequently Asked Questions

2025-01-29T22:13:35Z

WadeFife: Added workaround for the BD sub-design not being generated after converting to project mode

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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 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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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. In UHD 4.7 and later, this can be done by adding the <code>-g</code> argument to the <code>rfnoc_image_builder</code> command. In UHD 4.6 and earlier, this can be done by adding <code>GUI=1</code> to the <code>make</code> arguments. Example: <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: <code>save_project_as project_name project_dir</code> 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: <code>set_property source_mgmt_mode All [current_project]</code>

In some cases, it may also be necessary to reset the output products for some of the IP. If you get an error message about a BD sub-design being not generated for the synthesis target, then navigate to the "IP Sources" tab in the Project Manager Sources window, then right-click on affected IP and select "Reset Output Products...", then click "Reset".

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.

RFNoC Frequently Asked Questions

2024-06-26T13:53:27Z

WadeFife: Add CE clocks to N3xx and X4xx, which were added in UHD 4.6

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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 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>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
|-
| <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: <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: <code>save_project_as project_name project_dir</code> 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: <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.

RFNoC Frequently Asked Questions

2024-02-12T16:06:44Z

WadeFife: Added additional explanation of the build.log file.

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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 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? ===

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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.

RFNoC Frequently Asked Questions

2024-01-17T03:18:42Z

WadeFife: Add FAQ about "critical warnings" during the build process, which is expected.

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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 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? ===

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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.

RFNoC Frequently Asked Questions

2023-10-20T19:19:04Z

WadeFife: Adding clocks for X440

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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 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? ===

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

RFNoC Frequently Asked Questions

2023-10-14T21:29:08Z

WadeFife: Fix N32x rfnoc_chdr clock 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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 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_clk</code>
|}

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

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

RFNoC Frequently Asked Questions

2023-10-14T21:27:49Z

WadeFife: Add RFNoC control clock

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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 || 187.5 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 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_clk</code>
|}

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

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

RFNoC Frequently Asked Questions

2023-10-14T21:16:15Z

WadeFife: Fixed N300/N310 DRAM clock rate

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>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>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>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 || 187.5 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>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>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 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_clk</code>
|}

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

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

RFNoC Frequently Asked Questions

2023-08-18T21:45:24Z

WadeFife: Add X440 memory performance numbers

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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>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>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>dram</code> || DRAM interface clock || 303.189 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 || 187.5 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>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>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 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_clk</code>
|}

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

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

RFNoC Frequently Asked Questions

2023-08-17T22:00:36Z

WadeFife: Add X440 memory parameters

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 MHz (using 2 banks)
|-
| X440 (400 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (38.4 GB/s total) || 8 x 128-bit @ 300 MHz (using 2 banks)
|-
| X440 (1600 MHz BW) || 4 GiB per bank (8 GiB total) || 64-bit @ 2.4 GT/s (19.2 GB/s) per bank (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
|}
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).
# The 128-bit DRAM on X410 uses two memory banks. Channels 0 and 1 are on Bank 0, and channels 2 and 3 are on Bank 1.

=== 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>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>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>dram</code> || DRAM interface clock || 303.189 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 || 187.5 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>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>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 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_clk</code>
|}

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

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

RFNoC Frequently Asked Questions

2023-08-04T15:15:01Z

WadeFife: Add FAQ section related to building FPGA images

== 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 (8 GiB total) || 64-bit @ 2.0 GT/s (16.0 GB/s) per bank (32.0 GB/s total) || 4 x 128-bit @ 250 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
|}
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).
# The 128-bit DRAM on X410 uses two memory banks. Channels 0 and 1 are on Bank 0, and channels 2 and 3 are on Bank 1.

=== 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 X410 configures its DRAM differently for 100/200 MHz bandwidth images and 400 MHz bandwidth. The parameters used will be different in each case, as 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
|}

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}"
|}

==== 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>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>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>dram</code> || DRAM interface clock || 303.189 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 || 187.5 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>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>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 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_clk</code>
|}

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

Adding custom clocks is not directly supported yet. Describing them in the YAML file will not cause them to be generated for you. If you can't use any of the available clocks, you can modify the HDL code to generate a clock.

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.

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: <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: <code>save_project_as project_name project_dir</code> 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: <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? ===

Check the <code>build.log</code> in the FPGA build folder for clues that may not have been 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

UHD and USRP User Manual

2023-08-03T21:51:31Z

WadeFife: Added link to the manual archive

'''Software'''
* [https://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_e3x0.html E310/E312]

'''Daughterboards'''
* [http://files.ettus.com/manual/page_dboards.html#dboards_basictx BasicRX/LFRX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_basicrx BasicTX/LFTX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_cbx CBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_sbx SBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_wbx WBX]
* [http://files.ettus.com/manual/page_dboards.html#dboards_wbx UBX]

'''Other'''
* [http://files.ettus.com/manual/page_octoclock.html OctoClock]

RFNoC Frequently Asked Questions

2023-06-12T22:16:21Z

WadeFife:

Getting Started with RFNoC Development

2023-04-19T13:40:12Z

WadeFife: Fix link to mailing list

==Application Note Number==

'''AN-823'''


==Abstract==
'''Note:''' This application note applies to UHD 3.x and does not cover UHD 4.x. For UHD 4.x, see [[Getting Started with RFNoC in UHD 4.0]].

This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example. RFNoC is currently supported on any 3rd generation USRP hardware, currently: E310/E312, E320, N300/N310/N320/N321, and X300/X310. '''However''', this document primarily covers using RFNoC for the USRP X300/X310 and E310/E312. Using RFNoC with the other USRPs is similar to that documented herein.

==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). 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 only supported on 3rd generation USRP hardware as noted in the Abstract.

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 2017.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).

* Any 3rd generation USRP hardware as noted in the Abstract.

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

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

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

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

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

This will do the following:

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

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

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

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

$ pybombs config makewidth 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.0.0.rfnoc-devel-161-g83150fdd

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

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

$ uhd_images_downloader

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

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

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

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

<code>usrp_x310_fpga_HG.bit</code>

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

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

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

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

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

|}

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

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

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

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

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

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

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

Example for an X310 USRP:

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

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

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

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

rfnoc_rx_to_file.cpp

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

rfnoc_nullsource_ce_rx.cpp

These examples demonstrate the core features and flexibility of RFNoC.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

List of possible commands:

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

===Creating an RFNoC OOT Module===

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

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

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

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

To see what files and directories were created run:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

Right under the “Verification” section:

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

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

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

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

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

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

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

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

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

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

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

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

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

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

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

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

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

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

|}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

To run it, enter the following commands:

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

The application will then be launched:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.
.
.

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

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

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

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

===Compile, Install and Verify===

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

$ uhd_usrp_probe

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

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

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

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

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

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

==Troubleshooting==
===Xilinx Vivado===
====Compile issues====
=====Synthesis is failing=====
Verify all the correct Xilinx [[Getting Started with RFNoC Development#Prerequisites|prerequisite software]] is installed.

Additional helpful information can be found in the following Xilinx forum posts:
* https://forums.xilinx.com/t5/Synthesis/Synthesis-failed-without-reporting-any-error/td-p/686000
* https://forums.xilinx.com/t5/Installation-and-Licensing/Vivado-on-Linux-synthesis-fails-with-no-error-message/td-p/732143

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

==Reference Files==
The following reference files are included within the gain_src.tar.gz archive linked below:

* gain.xml
* noc_block_gain.v
* noc_block_gain_tb.sv
* tutorial_gain.xml
* rfnoc_gain.grc

[[Media:gain src.tar.gz]]

==Links and Additional Resources==
===RFNoC additional resources===
* [https://youtube.com/watch?v=j-EfyPVpaJ8 Video: RFNoC Getting Started Video Tutorial]
* [https://kb.ettus.com/Mailing_Lists USRP Mailing List]
* [https://kb.ettus.com/RFNoC RFNoC Software Resources Page]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf RFNoC Introduction]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]
* [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015 ]
** Explaining the slides of Intro, FPGA and Host presentations above (in that order).
* [https://www.youtube.com/watch?v=51rpjJ2W0Qs Video: It's the RFNoC Life for Us by Martin Braun at GRCon16, 2016]

===GNU Radio resources===
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNU Radio OutOfTree Modules tutorial]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio Installation]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/Tutorials GNU Radio Tutorials]

===UHD resources===
* [http://lists.ettus.com/mailman/listinfo/usrp-users_lists.ettus.com USRP Mailing List]
* [https://kb.ettus.com/UHD UHD Software Resources Page]
* [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]
* [http://files.ettus.com/manual/ UHD Manual]

===Other resources===
* [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]
* [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD + GNU Radio Application Note (Linux)]
* [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS]

[[Category:Application Notes]]

RFNoC Frequently Asked Questions

2022-12-24T19:02:54Z

WadeFife: Updated DRAM performance numbers for X3xx and E320 due to bug fix for those USRPs.

RFNoC Frequently Asked Questions

2022-10-26T15:00:50Z

WadeFife: Added example connections for FIFO and Replay YAML examples.

USRP N300/N310/N320/N321 Getting Started Guide

2022-07-15T18:01:31Z

WadeFife: Fix old location for network config

==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 versions of the file system: <code>/etc/systemd/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 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 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-07-15T17:10:24Z

WadeFife: Add notes specific to E31x devices.

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

'''Note:''' The FPGA size on E31x devices is limited, so it is not recommended
for use with the Replay block. In order to fit the Replay block on the FPGA,
use the E320 or a larger USRP instead.

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.


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

'''Note:''' Because the DRAM does not fit by default on the E31x devices, it is
not included in the build by default. To include the DRAM on E31x builds, set
the environment variable <code>DRAM=1</code> before building (e.g.,
<code>DRAM=1 rfnoc_image_builder ...</code>). The E320 is the recommended E-series
device for use with the Replay block.

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

USRP X410 Getting Started Guide

2022-05-13T14:27:59Z

WadeFife: Updated instructions for flashing eMMC to fix incorrect filename and add copy arg to bmaptool.

==Kit Contents==
===X410===
{|
|style="vertical-align:top"|
* NI Ettus USRP X410
* DC Power Supply (12V, 20A)
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to USB-C Cable (1m)
* Getting Started Guide URL (QR Code)
* Safety, Environmental, and Regulatory Information
||[[File:X410.jpg|450px|center]]
|}

==You Will Need==
* 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 +14 dBm continuous <=3GHz, +17 dBm continuous >3GHz, or +20dBm more than 5 minutes >3GHz 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 X410 requires UHD version 4.1 or later.

'''When you receive a brand-new device, it is strongly recommended that you download the latest filesystem image from the Ettus Research website update the unit. It is not recommended that you use the filesystem from the factory as-is. Instructions on downloading the latest filesystem image and updating it is 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 X410 must match.'''

==Assembling the X410==
Inside the kit you will find the X410 and an X410 power supply. Plug these in, connect the 1GbE RJ45 interface to your network, and power on the device by pressing the power button.

==The STM32 Microcontroller==

The STM32 microcontroller (also referred to as the "SCU") controls various low-level features of the X4x0 series motherboard: It controls the power sequencing, reads out fan speeds and some of the temperature sensors. It is connected to the RFSoC via an I2C bus. It is running software based on Chromium EC.

It is possible to log into the STM32 using the serial interface (see Connecting to the Microcontroller). This will allow certain low-level controls, such as remote power cycling should the CPU have become unresponsive for whatever reason.

===Updating the SCU===

The writable SCU image file is stored on the filesystem under /lib/firmware/ni/ec-titanium-revX.RW.bin (where X is a revision compatibility number). To update, simply replace the .bin file with the updated version and reboot.

==eMMC Storage==

The main non-volatile storage of the USRP is a 16 GB eMMC storage. This storage can be made accessible as a USB Mass Storage device through the USB-OTG connector on the back panel.

The entire root file system (Linux kernel, libraries) and any user data are stored on the eMMC. It is partitioned into four partitions:

Boot partition (contains the bootloader). This partition usually does not require modification.
A data partition, mounted in /data. This is the only partition that is not erased during file system updates.
Two identical system partitions (root file systems). These contain the operating system and the home directory (anything mounted under / that is not the data or boot partition). The reason there are two of these is to enable remote updates: An update running on one partition can update the other one without any effect to the currently running system. Note that the system partitions are erased during updates and are thus unsuitable for permanently storing information.
Note: It is possible to access the currently inactive root file system by mounting it. After logging into the device using serial console or SSH (see the following two sections), run the following commands:

<code>
$ mkdir temp

$ mount /dev/mmcblk0p3 temp # This assumes mmcblk0p3 is currently not mounted

$ ls temp # You are now accessing the idle partition:

bin data etc lib media proc sbin tmp usr
boot dev home lost+found mnt run sys uboot var
</code>

The device node in the mount command might differ, depending on which partition is currently already mounted.

==USB Access to eMMC==

While Mender should be used for routine filesystem updates (see Updating Filesystems), it is also possible to access the X410's internal eMMC from an external host over USB. This allows accessing or modifying the filesystem, as well as the ability to flash the device with an entirely new filesystem.

In order to do so, you'll need an external computer with two USB ports, and two USB cables to connect the computer to your X410. The instructions below assume a Linux host.

First, connect to the APU serial console at a baud rate of 115200. Boot the device, and stop the boot sequence by typing noautoboot at the prompt. Then, run the following command in the U-boot command prompt:

<code>ums 0 mmc 0</code>

This will start the USB mass storage gadget to expose the eMMC as a USB mass storage device. You should see a spinning indicator on the console, which indicates the gadget is active.

Next, connect your external computer to the X410's USB to PS port using an OTG cable. Your computer should recognize the X410 as a mass storage device, and you should see an entry in your kernel logs (dmesg) that looks like this:

<code>
usb 3-1: New USB device found, idVendor=3923, idProduct=7a7d, bcdDevice= 2.23

usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0

usb 3-1: Product: USB download gadget

usb 3-1: Manufacturer: National Instruments

sd 6:0:0:0: [sdc] 30932992 512-byte logical blocks: (15.8 GB/14.8 GiB)

sdc: sdc1 sdc2 sdc3 sdc4

sd 6:0:0:0: [sdc] Attached SCSI removable disk
</code>

The exact output will depend on your machine, but from this log you can see that the X410 was recognized and /dev/sdc is the block device representing the eMMC, with 4 partitions detected (see eMMC Storage for details on the partition layout).

It is now possible to treat the X410's eMMC as you would any other USB drive: the individual partitions can be mounted and accessed, or the entire block device can be read/written.

Once you're finished accessing the device over USB, the u-boot gadget may be stopped by hitting Ctrl-C at the APU serial console.

==Flashing the eMMC==

Once the X410's eMMC is accessible over USB, it's possible to write the filesystem image using bmaptool. You can obtain the latest filesystem image by running:

<code>uhd_images_downloader -t sdimg -t x4xx</code>

The output of this command will indicate where the downloaded images were put, or specify a custom location using using the <code>-i INSTALL_LOCATION</code> argument.

To write the image to the X410's eMMC, run the following command, replacing <code>/dev/sdX</code> with the block device of the X410's eMMC (found in your kernel log or by running <code>lsblk</code>). Take care to use the correct block device or else you might overwrite the wrong drive!

<code>sudo bmaptool copy --bmap /path/to/usrp_x4xx_fs.sdimg.bmap /path/to/usrp_x4xx_fs.sdimg /dev/sdX</code>

==Using a USRP X4x0 from UHD==
Like any other USRP, all X4x0 USRPs are controlled by the UHD software. To integrate a USRP X4x0 into your C++ application, you would generate a UHD device in the same way you would for any other USRP:

<code>auto usrp = uhd::usrp::multi_usrp::make("type=x4xx");</code>

For a list of which arguments can be passed into make(), see Section Device Arguments.

==Updating Filesystems==

Mender is a third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website). 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. Mender servers can be self-hosted, or hosted by Mender (see mender.io for pricing and availability).

When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted (note: the onboard flash storage contains two separate root file system partitions, only one is ever used at a single time). Any data stored on that partition will be permanently lost, including the currently loaded FPGA image. After updating that partition, 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 initiate an update from the device itself, download a Mender artifact containing the update itself. These are files with a .mender suffix. They can be downloaded by using the uhd_images_downloader utility:

<code>$ uhd_images_downloader -t mender -t x4xx</code>

Append the -l switch to print out the URLs only:

<code>$ uhd_images_downloader -t mender -t x4xx -l</code>

Then run mender on the command line:

<code>$ mender install /path/to/latest.mender</code>

The artifact can also be stored on a remote server:

<code>$ mender install http://server.name/path/to/latest.mender</code>

This procedure will take a while. If the new filesystem requires an update to the MB CPLD, see Updating the Motherboard CPLD before proceeding. After mender has logged a successful update, reboot the device:

<code>$ reboot</code>

If the reboot worked, and the device seems functional, commit the changes so the boot loader knows to permanently boot into this partition:

<code>$ mender commit</code>

To identify the currently installed Mender artifact from the command line, the following file can be queried:

<code>$ cat /etc/mender/artifact_info</code>

If you are running a hosted 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 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.

==Network Interfaces==
The Ettus USRP X410 has various network interfaces:

eth0: RJ45 port.

The RJ45 port comes up with a default configuration of DHCP, that will request a network address from your DHCP server (if available on your network). This interface is agnostic of FPGA image flavor.

int0: internal interface for network communication between the embedded ARM processor and FPGA.

The internal network interface is configured with a static address: 169.254.0.1/24. This interface is agnostic of FPGA image flavor.

sfpX [, sfpX_1, sfpX_2, sfpX_3]: QSFP28 network interface(s), up-to four (one per lane) based on implemented protocol.

Each QSFP28 port has four high-speed transceiver lanes. Therefore, depending on the FPGA image flavor, up-to four different network interfaces may exist per QSFP28 port, using the sfpXfor the first lane, and sfpX_1-3 for the other three lanes. Each network interface has a default static IP address. Note that for multi-lane protocols, such as 100 GbE, a single interface is used (sfpX).
The configuration files for these network interfaces are stored in: <code>/data/network/</code>

{| class="wikitable"
|-
! Interface Name
! Description
! Default Configuration
! Configuration File
! Example: X4_200 FPGA image
|-
| eth0
| RJ45
| style="vertical-align:middle; background-color:#FFF;" | DHCP
| style="vertical-align:middle; background-color:#FFF;" | eth0.network
| DHCP
|-
| int0
| Internal
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
| style="vertical-align:middle; background-color:#FFF;" | int0.network
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
|-
| sfp0
| QSFP28 0 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
|-
| style="background-color:#FFF;" | sfp0_1
| QSFP28 0 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_1.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
|-
| style="background-color:#FFF;" | sfp0_2
| QSFP28 0 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_2.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
|-
| sfp0_3
| QSFP28 0 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_3.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
|-
| sfp1
| QSFP28 1 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.20.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| sfp1_1
| QSFP28 1 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.21.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_2
| QSFP28 1 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.22.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_2.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_3
| QSFP28 1 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.23.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_3.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
|}

==Network Connectivity==
Once the X410 has booted, determine the IP address and verify network connectivity by running uhd_find_devices on the host computer:

<code>
$ uhd_find_devices

-- UHD Device 0

Device Address:
serial: 1234ABC
addr: 10.2.161.10
claimed: False
mgmt_addr: 10.2.161.10
product: x410
type: x4xx
</code>

By default, an X410 will use DHCP to attempt to find an address.

At this point, you should run:

<code>uhd_usrp_probe --args addr=<IP address></code>
to ensure functionality of the device.

Note: If you receive the following error:

<code>Error: RuntimeError: Graph edge list is empty for rx channel 0</code>
then you will need to download a UHD-compatible FPGA as described in Updating the FPGA or using the following command (it assumes that FPGA images have been downloaded previously using uhd_images_downloader, or that the command is run on the device itself):

<code>uhd_image_loader --args type=x4xx,addr=<ip address>,fpga=X4_200</code>
When running on the device, use <code>127.0.0.1</code> as the IP address.

You can now use existing UHD examples or applications (such as rx_sample_to_file, rx_ascii_art_dft, or tx_waveforms) or other UHD-compatible applications to start receiving and transmitting with the device.

See Network Interfaces for further details on the various network interfaces available on the X410.

===Network Status LEDs===
The Ettus USRP X410 is equipped with status LEDs for its network-capable ports: RJ45 and QSFP28s, see RJ45 LED Behavior and QSFP28 LED Behavior accordingly.

====RJ45 LED Behavior====
The RJ45 port has two independent LEDs: green (right) and yellow (left). The table below summarizes the LEDs' behavior. Note that link speed indication is not currently supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! Green LED
! Yellow LED
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| On
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| On
| Blinking
|}

====QSFP28 LED Behavior====
Each QSFP28 connector has four LEDs, one for each high-speed transceiver lane. The table below summarizes the LEDs' behavior, note that for multi-lane protocols, such as 100 GbE, the corresponding LEDs are ganged together. Within the same image, multiple speeds on the same port (e.g., both 10 GbE and 100 GbE) are not supported, therefore link speed indication is not supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! QSFP28 LED (4 Total)
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| Green (solid)
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| Amber (blinking)
|}

==Security-related Settings==
The X410 ships without a root password set. It is possible to ssh into the device by simply connecting as root, and thus gaining access to all subsystems. To set a password, run the command

<code>$ passwd</code>
on the device.

==Serial Connection==
It is possible to gain access to the device using a serial terminal emulator. To do so, the USB debug port needs to be connected to a separate computer to gain access. Most Linux, OSX, or other Unix flavors have a tool called 'screen' which can be used for this purpose, by running the following command:

<code>$ sudo screen /dev/ttyUSB2 115200</code>
In this command, we prepend 'sudo' to elevate user privileges (by default, accessing serial ports is not available to regular users), we specify the device node (in this case, /dev/ttyUSB2), and the baud rate (115200).

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

<code>$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0
</code>

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

The first (with the if02 suffix) connects to the STM32 microcontroller (SCU), whereas the second (with the if03 suffix) connects to Linux running on the RFSoC APU.

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 115200</code>
After entering the username root (no password is set by default), you should be presented with a shell prompt similar to the following:

<code>root@ni-x4xx-1234ABC:~#</code>
On this prompt, you can enter any Linux command available. Using the default configuration, the serial console will also show all kernel log messages (unlike when using SSH, for example), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or bootloader issues more efficiently than when logged in via SSH.

==Connecting to the Microcontroller==
The microcontroller (which controls the power sequencing, among other things) also has a serial console available. To connect to the microcontroller, use the other UART device. In the example above:

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 115200</code>

It provides a very simple prompt. The command 'help' will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it and other low-level diagnostics. For example, running the command reboot will emulate a reset button press, resetting the state of the device, while the command powerbtn will emulate a power button press, turning the device back on again.

==SSH Connection==
The USRP X410 has two network connections: The dual QSFP28 ports, and an RJ45 connector. The latter is by default configured by DHCP; by plugging it into into 1 Gigabit switch on a DHCP-capable network, it will get assigned an IP address and thus be accessible via ssh.

In case your network setup does not include a DHCP server, refer to the section Serial Connection. A serial login can be used to assign an IP address manually.

After the device obtained an IP address you can log in from a Linux or OSX machine by typing:

<code>$ ssh root@ni-x4xx-1234ABC # Replace with your actual device name!</code>
Depending on your network setup, using a .local domain may work:

<code>$ ssh root@ni-x4xx-1234ABC.local</code>
Of course, you can also connect to the IP address directly if you know it (or set it manually using the serial console).

Note: The device's hostname is derived from its serial number by default (<code>ni-x4xx-$SERIAL</code>). You can change the hostname by creating the file <code>/data/network/hostname</code>, saving the desired hostname in it, then rebooting.

On Microsoft Windows, the connection can be established using a tool such as PuTTY, by selecting a username of root without password.

Like with the serial console, you should be presented with a prompt like the following:

<code>root@ni-x4xx-1234ABC:~#</code>

== Autoboot ==

The USRP X410 can be configured to power on and boot automatically when power is applied. This setting can be controlled using the <code>eeprom-set-autoboot</code> script. This script is executed directly on the USRP X410. To enable autoboot, run <code>eeprom-set-autoboot on</code>; to disable autoboot, run <code>eeprom-set-autoboot off</code>.

==Updating the FPGA==

The FPGA can be updated simply using uhd_image_loader:

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device> --fpga-path <path to .bit></code>
or

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device>,fpga=FPGA_TYPE</code>
A UHD install will likely have pre-built images in /usr/share/uhd/images/. Up-to-date images can be downloaded using the uhd_images_downloader script:

<code>uhd_images_downloader</code>
will download images into /usr/share/uhd/images/ (the path may differ, depending on how UHD was installed).

Also note that the USRP already ships with compatible FPGA images on the device - these images can be loaded by SSH'ing into the device and running:

<code>uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_200</code>

==FPGA Image Flavors==

Unlike the USRP X310 or other third-generation USRP devices, the FPGA image flavors do not only encode how the QSFP28 connectors are configured, but also which master clock rates are available. This is because the data converter configuration is part of the FPGA image (the ADCs/DACs on the X410 are on the same die as the FPGA). The image flavors consist of two short strings, separated by an underscore, e.g. X4_200 is an image flavor which contains 4x 10 GbE, and can handle an analog bandwidth of 200 MHz. The first two characters describe the configuration of the QSFP28 ports: 'X' stands for 10 GbE, 'C' stands for 100 GbE. See the following table for more details.

1x 10 GbE (Lane 0)

The analog bandwidth determines the available master clock rates. As of UHD 4.1, only the X4_200 image is shipped with UHD, which allows a 245.76 MHz or 250 MHz master clock rate. The other images are considered experimental (unsupported).

==Device Arguments==

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold; text-align:center;"
! Key
! Description
! Example Value
|-
| addr
| IPv4 address of primary SFP+ port to connect to.
| addr=192.168.30.2
|-
| second_addr
| IPv4 address of secondary SFP+ port to connect to.
| second_addr=192.168.40.2
|-
| mgmt_addr
| IPv4 address or hostname to which to connect the RPC client. Defaults to `addr'.
| mgmt_addr=ni-sulfur-311FE00
|-
| find_all
| When using broadcast, find all devices, even if unreachable via CHDR.
| find_all=1
|-
| master_clock_rate
| Master Clock Rate in Hz.
| master_clock_rate=250e6
|-
| serialize_init
| Force serial initialization of daughterboards.
| serialize_init=1
|-
| skip_init
| Skip the initialization process for the device.
| skip_init=1
|-
| time_source
| Specify the time (PPS) source.
| time_source=internal
|-
| clock_source
| Specify the reference clock source.
| clock_source=internal
|-
| ref_clk_freq
| Specify the external reference clock frequency, default is 10 MHz.
| ref_clk_freq=20e6
|-
| discovery_port
| Override default value for MPM discovery port.
| discovery_port=49700
|-
| rpc_port
| Override default value for MPM RPC port.
| rpc_port=49701
|}

==GPS==

The USRP X410 includes a Jackson Labs LTE-Lite GPS module. Its antenna port is on the rear panel (see Front and Back Panels). When the X410 has access to GPS satellite signals, it can use this module to read out the current GPS time and location as well as to discipline an onboard OCXO.

To use the GPS as a clock and time reference, simply use gpsdo as a clock or time source. Alternatively, set gpsdo as a synchronization source:

<code>
// Set clock/time individually:
usrp->set_clock_source("gpsdo");
usrp->set_time_source("gpsdo");
// This is equivalent to the previous commands, but faster, as it sets
// both settings simultaneously and avoids duplicating settings that are shared
// between these calls.
usrp->set_sync_source("clock_source=gpsdo,time_source=gpsdo");
</code>

Note the GPS module is not always enabled. Its power-on status can be queried using the gps_enabled GPS sensor (see also The Sensor API). When disabled, none of the sensors will return useful (if any) values.

When selecting gpsdo as a clock source, the GPS will always be enabled. Note that acquiring a GPS lock can take some time after enabling the GPS, so if a UHD application is enabling the GPS dynamically, it might take some time before a GPS lock is reported.

==Front-Panel Programmable GPIOs==

The USRP X410 has two HDMI front-panel connectors, which are connected to the FPGA.

Support for using these with UHD is not yet available.

==Subdev Specifications==

The RF ports on the front panel of the X410 + ZBX correspond to the following subdev specifications:

{| class="wikitable"
|-
! Label
! style="text-align:center; vertical-align:middle; font-weight:bold;" | Subdev Spec
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 0
| A:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 1
| A:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 0
| B:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 1
| B:1
|}

The subdev spec slot identifiers "A" and "B" are not reflected on the front panel. They were set to match valid subdev specifications of previous USRPs, maintaining backward compatibility.

These values can be used for uhd::usrp::multi_usrp::set_rx_subdev_spec() and uhd::usrp::multi_usrp::set_tx_subdev_spec() as with other USRPs.

==Rear Panel Status LEDs==

The USRP X410 is equipped with four LEDs located on the device's rear panel. Each LED supports four different states: Off, Green, Red, and Amber. One LED (PWR) indicates the device's power state (see Power LED below). The other three LEDs (LED 0, LED 1, and LED 2) are user-configurable, different behaviors are supported for each of these LEDs (see User-configurable LEDs below).

[[File:x4xx_rearpanel_status_leds.png|125px]]

===X4x0 Rear Panel Status LEDs===
Power LED
The USRP X410's PWR LED is reserved to visually indicate the user the device's power state. Power LED Behavior describes what each LED state represents.

===Power LED Behavior===

{| class="wikitable" style="background-color:#FFF;"
|- style="font-weight:bold; text-align:center;"
! PWR LED State
! style="vertical-align:middle;" | Meaning
|- style="vertical-align:middle;"
| Off
| No power is applied
|- style="vertical-align:middle;"
| Amber
| Power is good but X410 is powered off
|- style="vertical-align:middle;"
| Green
| Power is good and X410 is powered on
|- style="vertical-align:middle;"
| Red
| Power error state
|}

===User-configurable LEDs===
The USRP X410's user-configurable rear panel status LEDs (LED 0, LED 1, and LED 2) allow the user to have visual indication of various device conditions. Supported LED Behaviors provides a complete list of the supported behaviors for each user-configurable LED. By default, these LEDs are configured as described in LEDs Default Behavior.

The user may alter the default LEDs behavior either temporarily or persistently, see the Temporarily change the LED Behavior or Persistently in the UHD manual to change the LED Behavior accordingly.

https://files.ettus.com/manual/page_usrp_x4xx.html

==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:X410]]

RFNoC Frequently Asked Questions

2022-04-21T15:39:26Z

WadeFife:

RFNoC Frequently Asked Questions

2022-04-20T22:54:37Z

WadeFife:

RFNoC Frequently Asked Questions

2022-04-20T22:50:33Z

WadeFife: Add Vivado Information

RFNoC Frequently Asked Questions

2022-04-20T22:12:46Z

WadeFife:

RFNoC Frequently Asked Questions

2022-04-20T22:11:24Z

WadeFife: Add DRAM throughput numbers.

RFNoC Frequently Asked Questions

2022-04-18T21:02:53Z

WadeFife:

RFNoC Frequently Asked Questions

2022-04-18T20:51:56Z

WadeFife:

RFNoC Frequently Asked Questions

2022-04-18T20:44:15Z

WadeFife: Cleaned up DRAM tables.

RFNoC Frequently Asked Questions

2022-04-18T19:22:28Z

WadeFife: Added DRAM section

RFNoC Frequently Asked Questions

2022-04-18T16:26:26Z

WadeFife: Added additional details about adding or changing clocks.

RFNoC Frequently Asked Questions

2022-04-15T22:09:58Z

WadeFife:

RFNoC Frequently Asked Questions

2022-04-15T22:08:11Z

WadeFife: Added RFNoC clocks FAQ

RFNoC Frequently Asked Questions

2022-04-15T21:15:41Z

WadeFife: Added Stream Endpoint buffer size questions

USRP X410 Getting Started Guide

2022-04-15T17:52:15Z

WadeFife:

==Kit Contents==
===X410===
{|
|style="vertical-align:top"|
* NI Ettus USRP X410
* DC Power Supply (12V, 20A)
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to USB-C Cable (1m)
* Getting Started Guide URL (QR Code)
* Safety, Environmental, and Regulatory Information
||[[File:X410.jpg|450px|center]]
|}

==You Will Need==
* 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 +14 dBm continuous <=3GHz, +17 dBm continuous >3GHz, or +20dBm more than 5 minutes >3GHz 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 X410 requires UHD version 4.1 or later.

'''When you receive a brand-new device, it is strongly recommended that you download the latest filesystem image from the Ettus Research website update the unit. It is not recommended that you use the filesystem from the factory as-is. Instructions on downloading the latest filesystem image and updating it is 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 X410 must match.'''

==Assembling the X410==
Inside the kit you will find the X410 and an X410 power supply. Plug these in, connect the 1GbE RJ45 interface to your network, and power on the device by pressing the power button.

==The STM32 Microcontroller==

The STM32 microcontroller (also referred to as the "SCU") controls various low-level features of the X4x0 series motherboard: It controls the power sequencing, reads out fan speeds and some of the temperature sensors. It is connected to the RFSoC via an I2C bus. It is running software based on Chromium EC.

It is possible to log into the STM32 using the serial interface (see Connecting to the Microcontroller). This will allow certain low-level controls, such as remote power cycling should the CPU have become unresponsive for whatever reason.

===Updating the SCU===

The writable SCU image file is stored on the filesystem under /lib/firmware/ni/ec-titanium-revX.RW.bin (where X is a revision compatibility number). To update, simply replace the .bin file with the updated version and reboot.

==eMMC Storage==

The main non-volatile storage of the USRP is a 16 GB eMMC storage. This storage can be made accessible as a USB Mass Storage device through the USB-OTG connector on the back panel.

The entire root file system (Linux kernel, libraries) and any user data are stored on the eMMC. It is partitioned into four partitions:

Boot partition (contains the bootloader). This partition usually does not require modification.
A data partition, mounted in /data. This is the only partition that is not erased during file system updates.
Two identical system partitions (root file systems). These contain the operating system and the home directory (anything mounted under / that is not the data or boot partition). The reason there are two of these is to enable remote updates: An update running on one partition can update the other one without any effect to the currently running system. Note that the system partitions are erased during updates and are thus unsuitable for permanently storing information.
Note: It is possible to access the currently inactive root file system by mounting it. After logging into the device using serial console or SSH (see the following two sections), run the following commands:

<code>
$ mkdir temp

$ mount /dev/mmcblk0p3 temp # This assumes mmcblk0p3 is currently not mounted

$ ls temp # You are now accessing the idle partition:

bin data etc lib media proc sbin tmp usr
boot dev home lost+found mnt run sys uboot var
</code>

The device node in the mount command might differ, depending on which partition is currently already mounted.

==USB Access to eMMC==

While Mender should be used for routine filesystem updates (see Updating Filesystems), it is also possible to access the X410's internal eMMC from an external host over USB. This allows accessing or modifying the filesystem, as well as the ability to flash the device with an entirely new filesystem.

In order to do so, you'll need an external computer with two USB ports, and two USB cables to connect the computer to your X410. The instructions below assume a Linux host.

First, connect to the APU serial console at a baud rate of 115200. Boot the device, and stop the boot sequence by typing noautoboot at the prompt. Then, run the following command in the U-boot command prompt:

<code>ums 0 mmc 0</code>

This will start the USB mass storage gadget to expose the eMMC as a USB mass storage device. You should see a spinning indicator on the console, which indicates the gadget is active.

Next, connect your external computer to the X410's USB to PS port using an OTG cable. Your computer should recognize the X410 as a mass storage device, and you should see an entry in your kernel logs (dmesg) that looks like this:

<code>
usb 3-1: New USB device found, idVendor=3923, idProduct=7a7d, bcdDevice= 2.23

usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0

usb 3-1: Product: USB download gadget

usb 3-1: Manufacturer: National Instruments

sd 6:0:0:0: [sdc] 30932992 512-byte logical blocks: (15.8 GB/14.8 GiB)

sdc: sdc1 sdc2 sdc3 sdc4

sd 6:0:0:0: [sdc] Attached SCSI removable disk
</code>

The exact output will depend on your machine, but from this log you can see that the X410 was recognized and /dev/sdc is the block device representing the eMMC, with 4 partitions detected (see eMMC Storage for details on the partition layout).

It is now possible to treat the X410's eMMC as you would any other USB drive: the individual partitions can be mounted and accessed, or the entire block device can be read/written.

Once you're finished accessing the device over USB, the u-boot gadget may be stopped by hitting Ctrl-C at the APU serial console.

==Flashing the eMMC==

Once the X410's eMMC is accessible over USB, it's possible to write the filesystem image using bmaptool. You can obtain the latest filesystem image by running:

<code>uhd_images_downloader -t sdimg -t x4xx</code>

The output of this command will indicate where the downloaded image can be found.

Run:

<code> sudo bmaptool /path/to/usrp_x4xx_fs.sdimg.bz2 /dev/sdX</code>

to flash the eMMC with this image (replacing /dev/sdX with the block device of the X410's eMMC as indicated by your kernel log).

==Using a USRP X4x0 from UHD==
Like any other USRP, all X4x0 USRPs are controlled by the UHD software. To integrate a USRP X4x0 into your C++ application, you would generate a UHD device in the same way you would for any other USRP:

<code>auto usrp = uhd::usrp::multi_usrp::make("type=x4xx");</code>

For a list of which arguments can be passed into make(), see Section Device Arguments.

==Updating Filesystems==

Mender is a third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website). 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. Mender servers can be self-hosted, or hosted by Mender (see mender.io for pricing and availability).

When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted (note: the onboard flash storage contains two separate root file system partitions, only one is ever used at a single time). Any data stored on that partition will be permanently lost, including the currently loaded FPGA image. After updating that partition, 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 initiate an update from the device itself, download a Mender artifact containing the update itself. These are files with a .mender suffix. They can be downloaded by using the uhd_images_downloader utility:

<code>$ uhd_images_downloader -t mender -t x4xx</code>

Append the -l switch to print out the URLs only:

<code>$ uhd_images_downloader -t mender -t x4xx -l</code>

Then run mender on the command line:

<code>$ mender install /path/to/latest.mender</code>

The artifact can also be stored on a remote server:

<code>$ mender install http://server.name/path/to/latest.mender</code>

This procedure will take a while. If the new filesystem requires an update to the MB CPLD, see Updating the Motherboard CPLD before proceeding. After mender has logged a successful update, reboot the device:

<code>$ reboot</code>

If the reboot worked, and the device seems functional, commit the changes so the boot loader knows to permanently boot into this partition:

<code>$ mender commit</code>

To identify the currently installed Mender artifact from the command line, the following file can be queried:

<code>$ cat /etc/mender/artifact_info</code>

If you are running a hosted 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 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.

==Network Interfaces==
The Ettus USRP X410 has various network interfaces:

eth0: RJ45 port.

The RJ45 port comes up with a default configuration of DHCP, that will request a network address from your DHCP server (if available on your network). This interface is agnostic of FPGA image flavor.

int0: internal interface for network communication between the embedded ARM processor and FPGA.

The internal network interface is configured with a static address: 169.254.0.1/24. This interface is agnostic of FPGA image flavor.

sfpX [, sfpX_1, sfpX_2, sfpX_3]: QSFP28 network interface(s), up-to four (one per lane) based on implemented protocol.

Each QSFP28 port has four high-speed transceiver lanes. Therefore, depending on the FPGA image flavor, up-to four different network interfaces may exist per QSFP28 port, using the sfpXfor the first lane, and sfpX_1-3 for the other three lanes. Each network interface has a default static IP address. Note that for multi-lane protocols, such as 100 GbE, a single interface is used (sfpX).
The configuration files for these network interfaces are stored in: <code>/data/network/</code>

{| class="wikitable"
|-
! Interface Name
! Description
! Default Configuration
! Configuration File
! Example: X4_200 FPGA image
|-
| eth0
| RJ45
| style="vertical-align:middle; background-color:#FFF;" | DHCP
| style="vertical-align:middle; background-color:#FFF;" | eth0.network
| DHCP
|-
| int0
| Internal
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
| style="vertical-align:middle; background-color:#FFF;" | int0.network
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
|-
| sfp0
| QSFP28 0 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
|-
| style="background-color:#FFF;" | sfp0_1
| QSFP28 0 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_1.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
|-
| style="background-color:#FFF;" | sfp0_2
| QSFP28 0 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_2.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
|-
| sfp0_3
| QSFP28 0 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_3.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
|-
| sfp1
| QSFP28 1 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.20.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| sfp1_1
| QSFP28 1 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.21.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_2
| QSFP28 1 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.22.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_2.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_3
| QSFP28 1 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.23.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_3.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
|}

==Network Connectivity==
Once the X410 has booted, determine the IP address and verify network connectivity by running uhd_find_devices on the host computer:

<code>
$ uhd_find_devices

-- UHD Device 0

Device Address:
serial: 1234ABC
addr: 10.2.161.10
claimed: False
mgmt_addr: 10.2.161.10
product: x410
type: x4xx
</code>

By default, an X410 will use DHCP to attempt to find an address.

At this point, you should run:

<code>uhd_usrp_probe --args addr=<IP address></code>
to ensure functionality of the device.

Note: If you receive the following error:

<code>Error: RuntimeError: Graph edge list is empty for rx channel 0</code>
then you will need to download a UHD-compatible FPGA as described in Updating the FPGA or using the following command (it assumes that FPGA images have been downloaded previously using uhd_images_downloader, or that the command is run on the device itself):

<code>uhd_image_loader --args type=x4xx,addr=<ip address>,fpga=X4_200</code>
When running on the device, use <code>127.0.0.1</code> as the IP address.

You can now use existing UHD examples or applications (such as rx_sample_to_file, rx_ascii_art_dft, or tx_waveforms) or other UHD-compatible applications to start receiving and transmitting with the device.

See Network Interfaces for further details on the various network interfaces available on the X410.

===Network Status LEDs===
The Ettus USRP X410 is equipped with status LEDs for its network-capable ports: RJ45 and QSFP28s, see RJ45 LED Behavior and QSFP28 LED Behavior accordingly.

====RJ45 LED Behavior====
The RJ45 port has two independent LEDs: green (right) and yellow (left). The table below summarizes the LEDs' behavior. Note that link speed indication is not currently supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! Green LED
! Yellow LED
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| On
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| On
| Blinking
|}

====QSFP28 LED Behavior====
Each QSFP28 connector has four LEDs, one for each high-speed transceiver lane. The table below summarizes the LEDs' behavior, note that for multi-lane protocols, such as 100 GbE, the corresponding LEDs are ganged together. Within the same image, multiple speeds on the same port (e.g., both 10 GbE and 100 GbE) are not supported, therefore link speed indication is not supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! QSFP28 LED (4 Total)
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| Green (solid)
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| Amber (blinking)
|}

==Security-related Settings==
The X410 ships without a root password set. It is possible to ssh into the device by simply connecting as root, and thus gaining access to all subsystems. To set a password, run the command

<code>$ passwd</code>
on the device.

==Serial Connection==
It is possible to gain access to the device using a serial terminal emulator. To do so, the USB debug port needs to be connected to a separate computer to gain access. Most Linux, OSX, or other Unix flavors have a tool called 'screen' which can be used for this purpose, by running the following command:

<code>$ sudo screen /dev/ttyUSB2 115200</code>
In this command, we prepend 'sudo' to elevate user privileges (by default, accessing serial ports is not available to regular users), we specify the device node (in this case, /dev/ttyUSB2), and the baud rate (115200).

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

<code>$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0
</code>

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

The first (with the if02 suffix) connects to the STM32 microcontroller (SCU), whereas the second (with the if03 suffix) connects to Linux running on the RFSoC APU.

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 115200</code>
After entering the username root (no password is set by default), you should be presented with a shell prompt similar to the following:

<code>root@ni-x4xx-1234ABC:~#</code>
On this prompt, you can enter any Linux command available. Using the default configuration, the serial console will also show all kernel log messages (unlike when using SSH, for example), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or bootloader issues more efficiently than when logged in via SSH.

==Connecting to the Microcontroller==
The microcontroller (which controls the power sequencing, among other things) also has a serial console available. To connect to the microcontroller, use the other UART device. In the example above:

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 115200</code>

It provides a very simple prompt. The command 'help' will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it and other low-level diagnostics. For example, running the command reboot will emulate a reset button press, resetting the state of the device, while the command powerbtn will emulate a power button press, turning the device back on again.

==SSH Connection==
The USRP X410 has two network connections: The dual QSFP28 ports, and an RJ45 connector. The latter is by default configured by DHCP; by plugging it into into 1 Gigabit switch on a DHCP-capable network, it will get assigned an IP address and thus be accessible via ssh.

In case your network setup does not include a DHCP server, refer to the section Serial Connection. A serial login can be used to assign an IP address manually.

After the device obtained an IP address you can log in from a Linux or OSX machine by typing:

<code>$ ssh root@ni-x4xx-1234ABC # Replace with your actual device name!</code>
Depending on your network setup, using a .local domain may work:

<code>$ ssh root@ni-x4xx-1234ABC.local</code>
Of course, you can also connect to the IP address directly if you know it (or set it manually using the serial console).

Note: The device's hostname is derived from its serial number by default (<code>ni-x4xx-$SERIAL</code>). You can change the hostname by creating the file <code>/data/network/hostname</code>, saving the desired hostname in it, then rebooting.

On Microsoft Windows, the connection can be established using a tool such as PuTTY, by selecting a username of root without password.

Like with the serial console, you should be presented with a prompt like the following:

<code>root@ni-x4xx-1234ABC:~#</code>

== Autoboot ==

The USRP X410 can be configured to power on and boot automatically when power is applied. This setting can be controlled using the <code>eeprom-set-autoboot</code> script. This script is executed directly on the USRP X410. To enable autoboot, run <code>eeprom-set-autoboot on</code>; to disable autoboot, run <code>eeprom-set-autoboot off</code>.

==Updating the FPGA==

The FPGA can be updated simply using uhd_image_loader:

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device> --fpga-path <path to .bit></code>
or

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device>,fpga=FPGA_TYPE</code>
A UHD install will likely have pre-built images in /usr/share/uhd/images/. Up-to-date images can be downloaded using the uhd_images_downloader script:

<code>uhd_images_downloader</code>
will download images into /usr/share/uhd/images/ (the path may differ, depending on how UHD was installed).

Also note that the USRP already ships with compatible FPGA images on the device - these images can be loaded by SSH'ing into the device and running:

<code>uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_200</code>

==FPGA Image Flavors==

Unlike the USRP X310 or other third-generation USRP devices, the FPGA image flavors do not only encode how the QSFP28 connectors are configured, but also which master clock rates are available. This is because the data converter configuration is part of the FPGA image (the ADCs/DACs on the X410 are on the same die as the FPGA). The image flavors consist of two short strings, separated by an underscore, e.g. X4_200 is an image flavor which contains 4x 10 GbE, and can handle an analog bandwidth of 200 MHz. The first two characters describe the configuration of the QSFP28 ports: 'X' stands for 10 GbE, 'C' stands for 100 GbE. See the following table for more details.

1x 10 GbE (Lane 0)

The analog bandwidth determines the available master clock rates. As of UHD 4.1, only the X4_200 image is shipped with UHD, which allows a 245.76 MHz or 250 MHz master clock rate. The other images are considered experimental (unsupported).

==Device Arguments==

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold; text-align:center;"
! Key
! Description
! Example Value
|-
| addr
| IPv4 address of primary SFP+ port to connect to.
| addr=192.168.30.2
|-
| second_addr
| IPv4 address of secondary SFP+ port to connect to.
| second_addr=192.168.40.2
|-
| mgmt_addr
| IPv4 address or hostname to which to connect the RPC client. Defaults to `addr'.
| mgmt_addr=ni-sulfur-311FE00
|-
| find_all
| When using broadcast, find all devices, even if unreachable via CHDR.
| find_all=1
|-
| master_clock_rate
| Master Clock Rate in Hz.
| master_clock_rate=250e6
|-
| serialize_init
| Force serial initialization of daughterboards.
| serialize_init=1
|-
| skip_init
| Skip the initialization process for the device.
| skip_init=1
|-
| time_source
| Specify the time (PPS) source.
| time_source=internal
|-
| clock_source
| Specify the reference clock source.
| clock_source=internal
|-
| ref_clk_freq
| Specify the external reference clock frequency, default is 10 MHz.
| ref_clk_freq=20e6
|-
| discovery_port
| Override default value for MPM discovery port.
| discovery_port=49700
|-
| rpc_port
| Override default value for MPM RPC port.
| rpc_port=49701
|}

==GPS==

The USRP X410 includes a Jackson Labs LTE-Lite GPS module. Its antenna port is on the rear panel (see Front and Back Panels). When the X410 has access to GPS satellite signals, it can use this module to read out the current GPS time and location as well as to discipline an onboard OCXO.

To use the GPS as a clock and time reference, simply use gpsdo as a clock or time source. Alternatively, set gpsdo as a synchronization source:

<code>
// Set clock/time individually:
usrp->set_clock_source("gpsdo");
usrp->set_time_source("gpsdo");
// This is equivalent to the previous commands, but faster, as it sets
// both settings simultaneously and avoids duplicating settings that are shared
// between these calls.
usrp->set_sync_source("clock_source=gpsdo,time_source=gpsdo");
</code>

Note the GPS module is not always enabled. Its power-on status can be queried using the gps_enabled GPS sensor (see also The Sensor API). When disabled, none of the sensors will return useful (if any) values.

When selecting gpsdo as a clock source, the GPS will always be enabled. Note that acquiring a GPS lock can take some time after enabling the GPS, so if a UHD application is enabling the GPS dynamically, it might take some time before a GPS lock is reported.

==Front-Panel Programmable GPIOs==

The USRP X410 has two HDMI front-panel connectors, which are connected to the FPGA.

Support for using these with UHD is not yet available.

==Subdev Specifications==

The RF ports on the front panel of the X410 + ZBX correspond to the following subdev specifications:

{| class="wikitable"
|-
! Label
! style="text-align:center; vertical-align:middle; font-weight:bold;" | Subdev Spec
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 0
| A:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 1
| A:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 0
| B:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 1
| B:1
|}

The subdev spec slot identifiers "A" and "B" are not reflected on the front panel. They were set to match valid subdev specifications of previous USRPs, maintaining backward compatibility.

These values can be used for uhd::usrp::multi_usrp::set_rx_subdev_spec() and uhd::usrp::multi_usrp::set_tx_subdev_spec() as with other USRPs.

==Rear Panel Status LEDs==

The USRP X410 is equipped with four LEDs located on the device's rear panel. Each LED supports four different states: Off, Green, Red, and Amber. One LED (PWR) indicates the device's power state (see Power LED below). The other three LEDs (LED 0, LED 1, and LED 2) are user-configurable, different behaviors are supported for each of these LEDs (see User-configurable LEDs below).

[[File:x4xx_rearpanel_status_leds.png|125px]]

===X4x0 Rear Panel Status LEDs===
Power LED
The USRP X410's PWR LED is reserved to visually indicate the user the device's power state. Power LED Behavior describes what each LED state represents.

===Power LED Behavior===

{| class="wikitable" style="background-color:#FFF;"
|- style="font-weight:bold; text-align:center;"
! PWR LED State
! style="vertical-align:middle;" | Meaning
|- style="vertical-align:middle;"
| Off
| No power is applied
|- style="vertical-align:middle;"
| Amber
| Power is good but X410 is powered off
|- style="vertical-align:middle;"
| Green
| Power is good and X410 is powered on
|- style="vertical-align:middle;"
| Red
| Power error state
|}

===User-configurable LEDs===
The USRP X410's user-configurable rear panel status LEDs (LED 0, LED 1, and LED 2) allow the user to have visual indication of various device conditions. Supported LED Behaviors provides a complete list of the supported behaviors for each user-configurable LED. By default, these LEDs are configured as described in LEDs Default Behavior.

The user may alter the default LEDs behavior either temporarily or persistently, see the Temporarily change the LED Behavior or Persistently in the UHD manual to change the LED Behavior accordingly.

https://files.ettus.com/manual/page_usrp_x4xx.html

==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:X410]]

Using the RFNoC Replay Block

2022-03-23T17:40:25Z

WadeFife: Updated link to "Using the RFNoC Replay Block in UHD 4"

==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 covered in [[Using the RFNoC Replay Block in UHD 4]].

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

Application Notes

2022-03-23T17:39:18Z

WadeFife: Added new AN for Replay Block in UHD 4

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.

{| class="wikitable"
!colspan="4"|Application Notes
|-

! style="text-align:center;"| Number
! style="text-align:center;"| Title
! style="text-align:center;"| Abstract
! style="text-align:center;"| Author(s)
|-

|style="width: 10%; text-align: center;"| AN-088
|style="width: 30%;"| [[USRP Host Performance Tuning Tips and Tricks]]
|style="width: 50%;"| This application note provides various tips and tricks for tuning your host computer for best performance when working with USRP devices.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-111
|style="width: 30%;"| [[UHD Device Eraser and Certificates of Volatility]]
|style="width: 50%;"| This AN provides an overview of the UHD Device Eraser utility as well as links to the Certificates of Volatility for all Ettus products.
|style="width: 10%; text-align: center;"| Michael Dickens
|-

|style="width: 10%; text-align: center;"| AN-117
|style="width: 30%;"| [[GPSDO Selection Guide]]
|style="width: 50%;"| This AN explains how to select and use a GPSDO with the USRP B-, N-, and X-series devices.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-121
|style="width: 30%;"| [[Debugging FPGA images]]
|style="width: 50%;"| This application note covers the basics to get you through the process of probing the signals inside an FPGA. In order to accomplish that, we will review briefly the 'Xilinx ChipScope Analyzer' and will apply it to one of our core RFNoC blocks: the RFNoC Signal generator.
|style="width: 10%; text-align: center;"| Nicolas Cuervo Sugandha Gupta
|-

|style="width: 10%; text-align: center;"| AN-142
|style="width: 30%;"| [[Transmitting DVB-S2 with GNU Radio and an USRP B210]]
|style="width: 50%;"| This application note will demonstrate using an USRP B210 and the GNU Radio DTV example flowgraph to transmit a DVB-S2 video stream to an off-the-shelf satellite receiver.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-158
|style="width: 30%;"| [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices]]
|style="width: 50%;"| This application note provides instructions for synchronizing multiple USRP N3xx devices using White Rabbit Ethernet-based synchronization.
|style="width: 10%; text-align: center;"| Dan Baker
Wan Liu
|-

|style="width: 10%; text-align: center;"| AN-177
|style="width: 30%;"| [[About USRP Bandwidths and Sampling Rates]]
|style="width: 50%;"| This AN provides insight into the topics of USRP architecture, system bandwidth, host interface throughput, and available sampling rates.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-178
|style="width: 30%;"| [[Resolving Audio Codec Enumeration Issues On The E31x]]
|style="width: 50%;"| This application note covers Resolving Audio Codec Enumeration Issues On The E31x.
|style="width: 10%; text-align: center;"| Logan Fagg
|-

|style="width: 10%; text-align: center;"| AN-188
|style="width: 30%;"| [[Interrogating Passive Wireless SAW Sensors with the USRP]]
|style="width: 50%;"| Typical interrogator design for wireless SAW sensor systems require many discrete components and lengthy build times, making it difficult to rapidly adapt to sensor designs in a research environment. We have employed the USRP B200 as a SAW sensor interrogation system. Interrogation of wideband orthogonal frequency coded (OFC) SAW sensors imposes strict requirements on the timing and synchronization of the transceiver. The USRP FPGA has been modified to operate in a synchronous, pulsed mode of operation, allowing rapid data acquisition and the full 56MHz bandwidth to be utilized. Data from the USRP is passed to a custom matched filter correlator routine to extract sensor parameters. The system is capable of interrogating multiple sensors, simultaneously. Demonstration of the system is accomplished by wirelessly interrogating SAW sensors at 915MHz and extracting temperature.
|style="width: 10%; text-align: center;"| Trip Humphries
|-

|style="width: 10%; text-align: center;"| AN-204
|style="width: 30%;"| [[Getting Started with UHD and C++]]
|style="width: 50%;"| This AN explains how to write and build C++ programs that use the UHD API and introduces
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-244
|style="width: 30%;"| [[Direction Finding with the USRP™ X-Series and TwinRX™]]
|style="width: 50%;"| This application note covers using the USRP™ TwinRX™ daughterboard in a direction find application using the MUSIC algorithm.
|style="width: 10%; text-align: center;"| Srikanth Pagadarai Travis Collins Alexander M. Wyglinski
|-

|style="width: 10%; text-align: center;"| AN-296
|style="width: 30%;"| [[Using Dual 10 Gigabit Ethernet on the USRP X300/X310]]
|style="width: 50%;"| This short guide is meant to help in quickly setting up an X-series USRP for use over two 10 Gigabit Ethernet links simultaneously.
|style="width: 10%; text-align: center;"| Paul David
|-

|style="width: 10%; text-align: center;"| AN-305
|style="width: 30%;"| [[X300/X310 Device Recovery]]
|style="width: 50%;"| This application note covers the details of recovering the USRP X300/X310 via JTAG.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-309
|style="width: 30%;"| [[About the Motherboard and Daughtercard EEPROM on USRP Devices]]
|style="width: 50%;"| This AN discusses the EEPROM storage on various USRP devices and daughtercards. This guides explains how to update the EEPROM contents and recover from EEPROM corruption. The product codes, which are also stored in the EEPROM, for all USRP devices and daughtercards are also given for reference.
|style="width: 10%; text-align: center;"| Trip Humphries
|-

|style="width: 10%; text-align: center;"| AN-311
|style="width: 30%;"| [[Software Development on the E310 and E312]]
|style="width: 50%;"| This application note covers the software development process on the USRP E310 and E312.
|style="width: 10%; text-align: center;"| Martin Braun Nicolas Cuervo
|-

|style="width: 10%; text-align: center;"| AN-315
|style="width: 30%;"| [[Software Development on the E3xx USRP - Building RFNoC UHD / GNU Radio / gr-ettus from Source]]
|style="width: 50%;"| This application note is one of a multi-part series which will cover the software development process on the USRP E310, E312 and E313. It will cover building the rfnoc-devel branch of UHD, GNU Radio and gr-ettus from source for the host machine, and cross-compiling the rfnoc-devel branch of UHD, GNU Radio and gr-ettus for the E3xx USRP.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-322
|style="width: 30%;"| [[Experiments with the UBX Daughterboard in the HF Band]]
|style="width: 50%;"| We show the results of experiments with the UBX daughtercard on an USRP X310 platform for use in the HF frequency range, from 1.8MHz to 30MHz. While the UBX is nominally rated for use only down to 10 MHz, with careful flow-graph design, and pre-filtering, it provides quite-good performance across the HF bands.
|style="width: 10%; text-align: center;"| Marcus Leech
|-

|style="width: 10%; text-align: center;"| AN-325
|style="width: 30%;"| [[N200/N210 Device Recovery]]
|style="width: 50%;"| This application note covers the details of recovering your N200/N210.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-335
|style="width: 30%;"| [[Streaming processed data from the E31x with GNU Radio and ZMQ]]
|style="width: 50%;"| This application note will demonstrate using the USRP E310 to remotely stream processed data to a host machine.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-355
|style="width: 30%;"| [[Modifying an X310 Chassis for External LO Sharing]]
|style="width: 50%;"| This document describes how to modify an X310 chassis to wire the LO out of the back plate. Doing this will allow the user to export and import an LO signal as desired when using a compatible daughterboard such as the TwinRX.
|style="width: 10%; text-align: center;"| Sam Reiter
|-

|style="width: 10%; text-align: center;"| AN-363
|style="width: 30%;"| [[Implementation of an ADS-B/Mode-S Receiver in GNU Radio]]
|style="width: 50%;"| This AN guides the reader through the implementation of an ADS-B receiver using the gr-air-modes Out-of-Tree (OOT) module for GNU Radio. An explanation of ADS-B is also provided, and several real-world, over-the-air examples and profiled.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-400
|style="width: 30%;"| [[Getting Started with RFNoC in UHD 4.0]]
|style="width: 50%;"| This AN describes how use RFNoC in UHD 4.0, including building FPGA images for RFNoC, changing which blocks are included in the build, and creating your own RFNoC blocks.
|style="width: 10%; text-align: center;"| Sugandha Gupta Brent Stapleton Wade Fife
|-

|style="width: 10%; text-align: center;"| AN-401
|style="width: 30%;"| [[RFNoC 4 Migration Guide]]
|style="width: 50%;"| Guide on how to migrate RFNoC blocks written for RFNoC 3 to RFNoC 4.
|style="width: 10%; text-align: center;"| Jonathon Pendlum
|-

|style="width: 10%; text-align: center;"| AN-444
|style="width: 30%;"| [[Using B200/B210/B200mini/B205mini on OSX / macOS with UHD]]
|style="width: 50%;"| This AN provides a basic guide for what to expect when using a USB-based B-series USRP on OSX / macOS with UHD.
|style="width: 10%; text-align: center;"| Michael Dickens
|-

|style="width: 10%; text-align: center;"| AN-445
|style="width: 30%;"| [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux]]
|style="width: 50%;"| This AN provides a comprehensive step-by-step guide for building, installing, and maintaining the open-source toolchain, specifically UHD and GNU Radio, for the USRP from source code on the Linux platform. Other alternate installation methods are also discussed.
|style="width: 10%; text-align: center;"| Neel Pandeya
|-

|style="width: 10%; text-align: center;"| AN-452
|style="width: 30%;"| [[5G NR EVM Measurements with the USRP N320/N321]]
|style="width: 50%;"| Example EVM measurements are shown using the USRP N320/N321 receiver and the 5G New Radio (5G NR) modulation standard. The use of I/Q image calibration and spur-dodging are demonstrated as methods to improve EVM performance.
|style="width: 10%; text-align: center;"| Drew Fischer
|-

|style="width: 10%; text-align: center;"| AN-492
|style="width: 30%;"| [[Selecting a RF Daughterboard]]
|style="width: 50%;"| This AN explores the RF daughterboards used by the N-series and X-series USRP devices at a high level, compares devices across several primary features, and walks the reader through the process of selecting a particular device for the their application.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-500
|style="width: 30%;"| [[Getting Started with DPDK and UHD]]
|style="width: 50%;"| This application note walks through the process to get started with the Data Plane Development Kit (DPDK) driver within UHD.
|style="width: 10%; text-align: center;"| Nate Temple Alex Williams Wade Fife Matt Prost
|-

|style="width: 10%; text-align: center;"| AN-503
|style="width: 30%;"| [[Converting an X310 into an NI-USRP Rio]]
|style="width: 50%;"| This Application Note explains how to use an Ettus Research-branded USRP with LabVIEW, and in effect, convert it into an NI-USRP RIO.
|style="width: 10%; text-align: center;"| Tim Fountain
|-

|style="width: 10%; text-align: center;"| AN-504
|style="width: 30%;"| [[USRP N Series Quick Start (Daughterboard Installation)]]
|style="width: 50%;"| This application note is a detailed step-by-step guide to install a daughterboard into the USRP N200/N210.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-524
|style="width: 30%;"| [[Building and Installing UHD and GNU Radio in an Offline Environment]]
|style="width: 50%;"| This application note will provide step-by-step instructions on building and installing UHD and GNU Radio in an offline environment.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-525
|style="width: 30%;"| [[Building and Installing UHD and GNU Radio to a Custom Prefix]]
|style="width: 50%;"| This application note provides step-by-step instructions on building and installing UHD and GNU Radio to a local directory.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-561
|style="width: 30%;"| [[Implementation of a Simple FM Receiver in GNU Radio]]
|style="width: 50%;"| This AN shows a quick and simple implementation of an FM receiver for the USRP using GNU Radio. The goal is to easily demonstrate a practical application, and to verify that the USRP is functioning properly.
|style="width: 10%; text-align: center;"| Neel Pandeya
|-

|style="width: 10%; text-align: center;"| AN-611
|style="width: 30%;"| [[Building and Installing the USRP Open Source Toolchain (UHD and GNU Radio) on Windows]]
|style="width: 50%;"| This AN provides a comprehensive step-by-step guide for building, installing, and maintaining the open-source toolchain, specifically UHD and GNU Radio, for the USRP from source code on the Windows platform.
|style="width: 10%; text-align: center;"| Derek Kozel
|-

|style="width: 10%; text-align: center;"| AN-620
|style="width: 30%;"| [[Troubleshooting X300/X310 Device Discovery Issues]]
|style="width: 50%;"| Troubleshooting guide to intended to cover some of the most commonly recommended steps to enable USRP connectivity.
|style="width: 10%; text-align: center;"| Sam Reiter
|-

|style="width: 10%; text-align: center;"| AN-621
|style="width: 30%;"| [[Troubleshooting N310/N320 Device Discovery Issues]]
|style="width: 50%;"| Troubleshooting guide to intended to cover some of the most commonly recommended steps to enable USRP connectivity. Serves as a supplement to the N3xx getting started guide.
|style="width: 10%; text-align: center;"| Sam Reiter
|-

|style="width: 10%; text-align: center;"| AN-630
|style="width: 30%;"| [[Writing the USRP File System Disk Image to a SD Card]]
|style="width: 50%;"| This application note will provide step-by-step instructions on writing a file system disk image to a SD card using Linux.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-638
|style="width: 30%;"| [[Running UHD and GNU Radio on NI USRP-RIO]]
|style="width: 50%;"| This AN explains the process to updating your NI USRP-RIO to run UHD and GNU Radio.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple Michael Dickens
|-

|style="width: 10%; text-align: center;"| AN-642
|style="width: 30%;"| [[Using the RFNoC Replay Block]]
|style="width: 50%;"| 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.
|style="width: 10%; text-align: center;"| Wade Fife
|-

|style="width: 10%; text-align: center;"| AN-642b
|style="width: 30%;"| [[Using the RFNoC Replay Block in UHD 4]]
|style="width: 50%;"| 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.
|style="width: 10%; text-align: center;"| Martin Braun
|-

|style="width: 10%; text-align: center;"| AN-666
|style="width: 30%;"| [[Mean Time Between Failure (MTBF) of USRPs and Daughterboards]]
|style="width: 50%;"| This AN provides information about the MTBF for USRPs and daughterboards
|style="width: 10%; text-align: center;"| Michael Dickens
|-

|style="width: 10%; text-align: center;"| AN-725
|style="width: 30%;"| [[USRP N320/N321 LO Distribution]]
|style="width: 50%;"| This application note provides an overview of using the LO Distribution of the N320/N321 USRPs.
|style="width: 10%; text-align: center;"| Brian Avenell
|-

|style="width: 10%; text-align: center;"| AN-732
|style="width: 30%;"| [[USRP E312 Battery Replacement Instructions]]
|style="width: 50%;"| This application note covers replacing the battery cell inside the USRP E312.
|style="width: 10%; text-align: center;"| Robin Coxe
|-

|style="width: 10%; text-align: center;"| AN-788
|style="width: 30%;"| [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on OS X]]
|style="width: 50%;"| This AN provides a comprehensive step-by-step guide for building, installing, and maintaining the open-source toolchain, specifically UHD and GNU Radio, for the USRP from source code on the Mac OS X platform.
|style="width: 10%; text-align: center;"| Michael Dickens
|-

|style="width: 10%; text-align: center;"| AN-800
|style="width: 30%;"| [[Enabling Ethernet Connectivity on Octoclock and Octoclock-G]]
|style="width: 50%;"| This document supplements the UHD Manual's guide for updating the Octoclock bootloader to allow for Ethernet communications with the device.
|style="width: 10%; text-align: center;"| Sam Reiter
|-

|style="width: 10%; text-align: center;"| AN-822
|style="width: 30%;"| [[Open Architecture For Radar and EW Research]]
|style="width: 50%;"| This application note provides guidance for designing a system that uses the NI Open Architecture for Radar and EW Research.
|style="width: 10%; text-align: center;"| Michael Dickens Neel Pandeya Jovian Wysocki
|-

|style="width: 10%; text-align: center;"| AN-823
|style="width: 30%;"| [[Getting Started with RFNoC Development]]
|style="width: 50%;"| This application note gives a brief introduction into the steps required to start developing RFNoC blocks on your computer with UHD 3.
|style="width: 10%; text-align: center;"| Martin Braun Nicolas Cuervo
|-

|style="width: 10%; text-align: center;"| AN-832
|style="width: 30%;"| [[Mapping Between ER-USRP and NI-USRP Product Numbers]]
|style="width: 50%;"| This application note covers the details of the mapping between Ettus Research USRP and National Instruments USRP product numbers.
|style="width: 10%; text-align: center;"| Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-881
|style="width: 30%;"| [[Selecting a USRP Device]]
|style="width: 50%;"| This AN explores the USRP family at a high level, compares devices across several primary features, and walks the reader through the process of selecting a particular device for the their application.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-882
|style="width: 30%;"| [[Synchronization and MIMO Capability with USRP Devices]]
|style="width: 50%;"| Discusses the requirements for Multiple-In-Multiple-Out (MIMO) and phased-array systems. Summarizes the MIMO capability of each USRP device and daughterboard, and shows how to build MIMO systems with the USRP product family.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-883
|style="width: 30%;"| [[Synchronizing USRP Events Using Timed Commands in UHD]]
|style="width: 50%;"| Guide to cover common USRP synchronization scenarios and deep-dive into the use of timed commands within USRPs.
|style="width: 10%; text-align: center;"| Sam Reiter
|-

|style="width: 10%; text-align: center;"| AN-904
|style="width: 30%;"| [[USRP X Series Quick Start (Daughterboard Installation)]]
|style="width: 50%;"| This application note is a detailed step-by-step guide to install a daughterboard into the USRP X300/X310.
|style="width: 10%; text-align: center;"| Neel Pandeya Nate Temple
|-

|style="width: 10%; text-align: center;"| AN-936
|style="width: 30%;"| [[Verifying the Operation of the USRP Using UHD and GNU Radio]]
|style="width: 50%;"| 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.
|style="width: 10%; text-align: center;"| Neel Pandeya
|-

|}

Using the RFNoC Replay Block in UHD 4

2022-03-23T17:38:08Z

WadeFife: WadeFife moved page Using the RFNoC Replay Block 4 to Using the RFNoC Replay Block in UHD 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>

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.


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

2022-03-23T17:38:08Z

WadeFife: WadeFife moved page Using the RFNoC Replay Block 4 to Using the RFNoC Replay Block in UHD 4

#REDIRECT [[Using the RFNoC Replay Block in UHD 4]]

Using the RFNoC Replay Block

2022-03-23T17:32:08Z

WadeFife: Removed "not" that shouldn't be there

==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 covered in [[Using the RFNoC Replay Block 4]].

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

Getting Started with RFNoC Development

2022-03-23T17:24:33Z

WadeFife: Added note that this AN is for UHD 3 and added link to UHD 4 version.

==Application Note Number==

'''AN-823'''


==Abstract==
'''Note:''' This application note applies to UHD 3.x and does not cover UHD 4.x. For UHD 4.x, see [[Getting Started with RFNoC in UHD 4.0]].

This application note guides a user through basic information on the RFNoC architecture, installing necessary software to develop custom RFNoC blocks, also called Computation Engines (CE), and walks through the steps of creating a custom RFNoC block using an example. RFNoC is currently supported on any 3rd generation USRP hardware, currently: E310/E312, E320, N300/N310/N320/N321, and X300/X310. '''However''', this document primarily covers using RFNoC for the USRP X300/X310 and E310/E312. Using RFNoC with the other USRPs is similar to that documented herein.

==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). 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 only supported on 3rd generation USRP hardware as noted in the Abstract.

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 2017.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).

* Any 3rd generation USRP hardware as noted in the Abstract.

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

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

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

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

* UHD
* GNU Radio
* gr-ettus

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

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

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

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

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

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

This will do the following:

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

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

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

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

$ pybombs config makewidth 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.0.0.rfnoc-devel-161-g83150fdd

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

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

$ uhd_images_downloader

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

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

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

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

<code>usrp_x310_fpga_HG.bit</code>

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

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

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

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

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

|}

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

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

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

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

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

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

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

Example for an X310 USRP:

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

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

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

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

rfnoc_rx_to_file.cpp

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

rfnoc_nullsource_ce_rx.cpp

These examples demonstrate the core features and flexibility of RFNoC.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

List of possible commands:

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

===Creating an RFNoC OOT Module===

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

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

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

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

To see what files and directories were created run:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Inside of this folder are the following three files:

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

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

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

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

Right under the “Verification” section:

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

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

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

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

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

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

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

$ mkdir build && cd build/

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

If PyBOMBS used, run:

$ cmake ../

If PyBOMBS not used, run:

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

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

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

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

$ make test_tb
Scanning dependencies of target test_tb
Built target test_tb

Testbenches can be executed by running the command:

$ make noc_block_[name_of_your_block]_tb

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

$ make noc_block_gain_tb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Generate the NoC block instantiation file

positional arguments:
blocks List block names to instantiate.

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

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

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

These blocks can be identified by the following pattern:

noc_block_{NAME}.v

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

Incorrect method:

$ ./uhd_image_builder.py noc_block_null_source_sink noc_block_siggen ...

Correct method:

$ ./uhd_image_builder.py null_source_sink siggen ...

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

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

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

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

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

!Block
!Filename
!Description
|-

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

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

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

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

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

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

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

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

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

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

|}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ uhd_usrp_probe

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

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

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

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

To run it, enter the following commands:

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

The application will then be launched:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.
.
.

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

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

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

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

===Compile, Install and Verify===

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

$ uhd_usrp_probe

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

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

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

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

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

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

==Troubleshooting==
===Xilinx Vivado===
====Compile issues====
=====Synthesis is failing=====
Verify all the correct Xilinx [[Getting Started with RFNoC Development#Prerequisites|prerequisite software]] is installed.

Additional helpful information can be found in the following Xilinx forum posts:
* https://forums.xilinx.com/t5/Synthesis/Synthesis-failed-without-reporting-any-error/td-p/686000
* https://forums.xilinx.com/t5/Installation-and-Licensing/Vivado-on-Linux-synthesis-fails-with-no-error-message/td-p/732143

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

==Reference Files==
The following reference files are included within the gain_src.tar.gz archive linked below:

* gain.xml
* noc_block_gain.v
* noc_block_gain_tb.sv
* tutorial_gain.xml
* rfnoc_gain.grc

[[Media:gain src.tar.gz]]

==Links and Additional Resources==
===RFNoC additional resources===
* [https://youtube.com/watch?v=j-EfyPVpaJ8 Video: RFNoC Getting Started Video Tutorial]
* [http://lists.ettus.com/mailman/listinfo/usrp-users_lists.ettus.com USRP Mailing List]
* [https://kb.ettus.com/RFNoC RFNoC Software Resources Page]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Intro.pdf RFNoC Introduction]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_FPGA.pdf RFNoC Deep Dive: FPGA]
* [https://www.ettus.com/content/files/RFNoC_Wireless_at_VT_Host.pdf RFNoC Deep Dive: Host side]
* [https://www.youtube.com/watch?v=8cPd3t88djE Video: RFNoC presented at Wireless @ Virginia Tech, 2015 ]
** Explaining the slides of Intro, FPGA and Host presentations above (in that order).
* [https://www.youtube.com/watch?v=51rpjJ2W0Qs Video: It's the RFNoC Life for Us by Martin Braun at GRCon16, 2016]

===GNU Radio resources===
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules GNU Radio OutOfTree Modules tutorial]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGRFromSource GNU Radio Installation]
* [http://gnuradio.org/redmine/projects/gnuradio/wiki/Tutorials GNU Radio Tutorials]

===UHD resources===
* [http://lists.ettus.com/mailman/listinfo/usrp-users_lists.ettus.com USRP Mailing List]
* [https://kb.ettus.com/UHD UHD Software Resources Page]
* [http://files.ettus.com/manual/md_usrp3_build_instructions.html USRP3 build instructions]
* [http://files.ettus.com/manual/ UHD Manual]

===Other resources===
* [https://www.xilinx.com/support/documentation/ip_documentation/ug761_axi_reference_guide.pdf Xilinx - AXI reference guide]
* [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD + GNU Radio Application Note (Linux)]
* [http://gnuradio.org/redmine/projects/pybombs/wiki PyBOMBS]

[[Category:Application Notes]]

USRP X410 Getting Started Guide

2022-03-22T21:27:30Z

WadeFife: Change SFP network port config file location

==Kit Contents==
===X410===
{|
|style="vertical-align:top"|
* NI Ettus USRP X410
* DC Power Supply (12V, 20A)
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to USB-C Cable (1m)
* Getting Started Guide URL (QR Code)
* Safety, Environmental, and Regulatory Information
||[[File:X410.jpg|450px|center]]
|}

==You Will Need==
* 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 +14 dBm continuous <=3GHz, +17 dBm continuous >3GHz, or +20dBm more than 5 minutes >3GHz 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 X410 requires UHD version 4.1 or later.

'''When you receive a brand-new device, it is strongly recommended that you download the latest filesystem image from the Ettus Research website update the unit. It is not recommended that you use the filesystem from the factory as-is. Instructions on downloading the latest filesystem image and updating it is 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 X410 must match.'''

==Assembling the X410==
Inside the kit you will find the X410 and an X410 power supply. Plug these in, connect the 1GbE RJ45 interface to your network, and power on the device by pressing the power button.

==The STM32 Microcontroller==

The STM32 microcontroller (also referred to as the "SCU") controls various low-level features of the X4x0 series motherboard: It controls the power sequencing, reads out fan speeds and some of the temperature sensors. It is connected to the RFSoC via an I2C bus. It is running software based on Chromium EC.

It is possible to log into the STM32 using the serial interface (see Connecting to the Microcontroller). This will allow certain low-level controls, such as remote power cycling should the CPU have become unresponsive for whatever reason.

===Updating the SCU===

The writable SCU image file is stored on the filesystem under /lib/firmware/ni/ec-titanium-revX.RW.bin (where X is a revision compatibility number). To update, simply replace the .bin file with the updated version and reboot.

==eMMC Storage==

The main non-volatile storage of the USRP is a 16 GB eMMC storage. This storage can be made accessible as a USB Mass Storage device through the USB-OTG connector on the back panel.

The entire root file system (Linux kernel, libraries) and any user data are stored on the eMMC. It is partitioned into four partitions:

Boot partition (contains the bootloader). This partition usually does not require modification.
A data partition, mounted in /data. This is the only partition that is not erased during file system updates.
Two identical system partitions (root file systems). These contain the operating system and the home directory (anything mounted under / that is not the data or boot partition). The reason there are two of these is to enable remote updates: An update running on one partition can update the other one without any effect to the currently running system. Note that the system partitions are erased during updates and are thus unsuitable for permanently storing information.
Note: It is possible to access the currently inactive root file system by mounting it. After logging into the device using serial console or SSH (see the following two sections), run the following commands:

<code>
$ mkdir temp

$ mount /dev/mmcblk0p3 temp # This assumes mmcblk0p3 is currently not mounted

$ ls temp # You are now accessing the idle partition:

bin data etc lib media proc sbin tmp usr
boot dev home lost+found mnt run sys uboot var
</code>

The device node in the mount command might differ, depending on which partition is currently already mounted.

==USB Access to eMMC==

While Mender should be used for routine filesystem updates (see Updating Filesystems), it is also possible to access the X410's internal eMMC from an external host over USB. This allows accessing or modifying the filesystem, as well as the ability to flash the device with an entirely new filesystem.

In order to do so, you'll need an external computer with two USB ports, and two USB cables to connect the computer to your X410. The instructions below assume a Linux host.

First, connect to the APU serial console at a baud rate of 115200. Boot the device, and stop the boot sequence by typing noautoboot at the prompt. Then, run the following command in the U-boot command prompt:

<code>ums 0 mmc 0</code>

This will start the USB mass storage gadget to expose the eMMC as a USB mass storage device. You should see a spinning indicator on the console, which indicates the gadget is active.

Next, connect your external computer to the X410's USB to PS port using an OTG cable. Your computer should recognize the X410 as a mass storage device, and you should see an entry in your kernel logs (dmesg) that looks like this:

<code>
usb 3-1: New USB device found, idVendor=3923, idProduct=7a7d, bcdDevice= 2.23

usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0

usb 3-1: Product: USB download gadget

usb 3-1: Manufacturer: National Instruments

sd 6:0:0:0: [sdc] 30932992 512-byte logical blocks: (15.8 GB/14.8 GiB)

sdc: sdc1 sdc2 sdc3 sdc4

sd 6:0:0:0: [sdc] Attached SCSI removable disk
</code>

The exact output will depend on your machine, but from this log you can see that the X410 was recognized and /dev/sdc is the block device representing the eMMC, with 4 partitions detected (see eMMC Storage for details on the partition layout).

It is now possible to treat the X410's eMMC as you would any other USB drive: the individual partitions can be mounted and accessed, or the entire block device can be read/written.

Once you're finished accessing the device over USB, the u-boot gadget may be stopped by hitting Ctrl-C at the APU serial console.

==Flashing the eMMC==

Once the X410's eMMC is accessible over USB, it's possible to write the filesystem image using bmaptool. You can obtain the latest filesystem image by running:

<code>uhd_images_downloader -t sdimg -t x4xx</code>

The output of this command will indicate where the downloaded image can be found.

Run:

<code> sudo bmaptool /path/to/usrp_x4xx_fs.sdimg.bz2 /dev/sdX</code>

to flash the eMMC with this image (replacing /dev/sdX with the block device of the X410's eMMC as indicated by your kernel log).

==Using a USRP X4x0 from UHD==
Like any other USRP, all X4x0 USRPs are controlled by the UHD software. To integrate a USRP X4x0 into your C++ application, you would generate a UHD device in the same way you would for any other USRP:

<code>auto usrp = uhd::usrp::multi_usrp::make("type=x4xx");</code>

For a list of which arguments can be passed into make(), see Section Device Arguments.

==Updating Filesystems==

Mender is a third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website). 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. Mender servers can be self-hosted, or hosted by Mender (see mender.io for pricing and availability).

When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted (note: the onboard flash storage contains two separate root file system partitions, only one is ever used at a single time). Any data stored on that partition will be permanently lost, including the currently loaded FPGA image. After updating that partition, 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 initiate an update from the device itself, download a Mender artifact containing the update itself. These are files with a .mender suffix. They can be downloaded by using the uhd_images_downloader utility:

<code>$ uhd_images_downloader -t mender -t x4xx</code>

Append the -l switch to print out the URLs only:

<code>$ uhd_images_downloader -t mender -t x4xx -l</code>
Then run mender on the command line:

<code>$ mender install /path/to/latest.mender</code>

The artifact can also be stored on a remote server:

<code>$ mender install http://server.name/path/to/latest.mender</code>

This procedure will take a while. If the new filesystem requires an update to the MB CPLD, see Updating the Motherboard CPLD before proceeding. After mender has logged a successful update, reboot the device:

<code>$ reboot</code>

If the reboot worked, and the device seems functional, commit the changes so the boot loader knows to permanently boot into this partition:

<code>$ mender commit</code>

To identify the currently installed Mender artifact from the command line, the following file can be queried:

<code>$ cat /etc/mender/artifact_info</code>

If you are running a hosted 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 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.

==Network Interfaces==
The Ettus USRP X410 has various network interfaces:

eth0: RJ45 port.

The RJ45 port comes up with a default configuration of DHCP, that will request a network address from your DHCP server (if available on your network). This interface is agnostic of FPGA image flavor.

int0: internal interface for network communication between the embedded ARM processor and FPGA.

The internal network interface is configured with a static address: 169.254.0.1/24. This interface is agnostic of FPGA image flavor.

sfpX [, sfpX_1, sfpX_2, sfpX_3]: QSFP28 network interface(s), up-to four (one per lane) based on implemented protocol.

Each QSFP28 port has four high-speed transceiver lanes. Therefore, depending on the FPGA image flavor, up-to four different network interfaces may exist per QSFP28 port, using the sfpXfor the first lane, and sfpX_1-3 for the other three lanes. Each network interface has a default static IP address. Note that for multi-lane protocols, such as 100 GbE, a single interface is used (sfpX).
The configuration files for these network interfaces are stored in: <code>/data/network/</code>

{| class="wikitable"
|-
! Interface Name
! Description
! Default Configuration
! Configuration File
! Example: X4_200 FPGA image
|-
| eth0
| RJ45
| style="vertical-align:middle; background-color:#FFF;" | DHCP
| style="vertical-align:middle; background-color:#FFF;" | eth0.network
| DHCP
|-
| int0
| Internal
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
| style="vertical-align:middle; background-color:#FFF;" | int0.network
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
|-
| sfp0
| QSFP28 0 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
|-
| style="background-color:#FFF;" | sfp0_1
| QSFP28 0 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_1.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
|-
| style="background-color:#FFF;" | sfp0_2
| QSFP28 0 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_2.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
|-
| sfp0_3
| QSFP28 0 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_3.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
|-
| sfp1
| QSFP28 1 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.20.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| sfp1_1
| QSFP28 1 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.21.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_2
| QSFP28 1 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.22.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_2.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_3
| QSFP28 1 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.23.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_3.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
|}

==Network Connectivity==
Once the X410 has booted, determine the IP address and verify network connectivity by running uhd_find_devices on the host computer:

<code>
$ uhd_find_devices

-- UHD Device 0

Device Address:
serial: 1234ABC
addr: 10.2.161.10
claimed: False
mgmt_addr: 10.2.161.10
product: x410
type: x4xx
</code>

By default, an X410 will use DHCP to attempt to find an address.

At this point, you should run:

<code>uhd_usrp_probe --args addr=<IP address></code>
to ensure functionality of the device.

Note: If you receive the following error:

<code>Error: RuntimeError: Graph edge list is empty for rx channel 0</code>
then you will need to download a UHD-compatible FPGA as described in Updating the FPGA or using the following command (it assumes that FPGA images have been downloaded previously using uhd_images_downloader, or that the command is run on the device itself):

<code>uhd_image_loader --args type=x4xx,addr=<ip address>,fpga=X4_200</code>
When running on the device, use <code>127.0.0.1</code> as the IP address.

You can now use existing UHD examples or applications (such as rx_sample_to_file, rx_ascii_art_dft, or tx_waveforms) or other UHD-compatible applications to start receiving and transmitting with the device.

See Network Interfaces for further details on the various network interfaces available on the X410.

===Network Status LEDs===
The Ettus USRP X410 is equipped with status LEDs for its network-capable ports: RJ45 and QSFP28s, see RJ45 LED Behavior and QSFP28 LED Behavior accordingly.

====RJ45 LED Behavior====
The RJ45 port has two independent LEDs: green (right) and yellow (left). The table below summarizes the LEDs' behavior. Note that link speed indication is not currently supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! Green LED
! Yellow LED
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| On
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| On
| Blinking
|}

====QSFP28 LED Behavior====
Each QSFP28 connector has four LEDs, one for each high-speed transceiver lane. The table below summarizes the LEDs' behavior, note that for multi-lane protocols, such as 100 GbE, the corresponding LEDs are ganged together. Within the same image, multiple speeds on the same port (e.g., both 10 GbE and 100 GbE) are not supported, therefore link speed indication is not supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! QSFP28 LED (4 Total)
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| Green (solid)
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| Amber (blinking)
|}

==Security-related Settings==
The X410 ships without a root password set. It is possible to ssh into the device by simply connecting as root, and thus gaining access to all subsystems. To set a password, run the command

<code>$ passwd</code>
on the device.

==Serial Connection==
It is possible to gain access to the device using a serial terminal emulator. To do so, the USB debug port needs to be connected to a separate computer to gain access. Most Linux, OSX, or other Unix flavors have a tool called 'screen' which can be used for this purpose, by running the following command:

<code>$ sudo screen /dev/ttyUSB2 115200</code>
In this command, we prepend 'sudo' to elevate user privileges (by default, accessing serial ports is not available to regular users), we specify the device node (in this case, /dev/ttyUSB2), and the baud rate (115200).

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

<code>$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0
</code>

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

The first (with the if02 suffix) connects to the STM32 microcontroller (SCU), whereas the second (with the if03 suffix) connects to Linux running on the RFSoC APU.

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 115200</code>
After entering the username root (no password is set by default), you should be presented with a shell prompt similar to the following:

<code>root@ni-x4xx-1234ABC:~#</code>
On this prompt, you can enter any Linux command available. Using the default configuration, the serial console will also show all kernel log messages (unlike when using SSH, for example), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or bootloader issues more efficiently than when logged in via SSH.

==Connecting to the Microcontroller==
The microcontroller (which controls the power sequencing, among other things) also has a serial console available. To connect to the microcontroller, use the other UART device. In the example above:

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 115200</code>

It provides a very simple prompt. The command 'help' will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it and other low-level diagnostics. For example, running the command reboot will emulate a reset button press, resetting the state of the device, while the command powerbtn will emulate a power button press, turning the device back on again.

==SSH Connection==
The USRP X410 has two network connections: The dual QSFP28 ports, and an RJ45 connector. The latter is by default configured by DHCP; by plugging it into into 1 Gigabit switch on a DHCP-capable network, it will get assigned an IP address and thus be accessible via ssh.

In case your network setup does not include a DHCP server, refer to the section Serial Connection. A serial login can be used to assign an IP address manually.

After the device obtained an IP address you can log in from a Linux or OSX machine by typing:

<code>$ ssh root@ni-x4xx-1234ABC # Replace with your actual device name!</code>
Depending on your network setup, using a .local domain may work:

<code>$ ssh root@ni-x4xx-1234ABC.local</code>
Of course, you can also connect to the IP address directly if you know it (or set it manually using the serial console).

Note: The device's hostname is derived from its serial number by default (<code>ni-x4xx-$SERIAL</code>). You can change the hostname by creating the file <code>/data/network/hostname</code>, saving the desired hostname in it, then rebooting.

On Microsoft Windows, the connection can be established using a tool such as PuTTY, by selecting a username of root without password.

Like with the serial console, you should be presented with a prompt like the following:

<code>root@ni-x4xx-1234ABC:~#</code>

== Autoboot ==

The USRP X410 can be configured to power on and boot automatically when power is applied. This setting can be controlled using the <code>eeprom-set-autoboot</code> script. This script is executed directly on the USRP X410. To enable autoboot, run <code>eeprom-set-autoboot on</code>; to disable autoboot, run <code>eeprom-set-autoboot off</code>.

==Updating the FPGA==

The FPGA can be updated simply using uhd_image_loader:

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device> --fpga-path <path to .bit></code>
or

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device>,fpga=FPGA_TYPE</code>
A UHD install will likely have pre-built images in /usr/share/uhd/images/. Up-to-date images can be downloaded using the uhd_images_downloader script:

<code>uhd_images_downloader</code>
will download images into /usr/share/uhd/images/ (the path may differ, depending on how UHD was installed).

Also note that the USRP already ships with compatible FPGA images on the device - these images can be loaded by SSH'ing into the device and running:

<code>uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_200</code>

==FPGA Image Flavors==

Unlike the USRP X310 or other third-generation USRP devices, the FPGA image flavors do not only encode how the QSFP28 connectors are configured, but also which master clock rates are available. This is because the data converter configuration is part of the FPGA image (the ADCs/DACs on the X410 are on the same die as the FPGA). The image flavors consist of two short strings, separated by an underscore, e.g. X4_200 is an image flavor which contains 4x 10 GbE, and can handle an analog bandwidth of 200 MHz. The first two characters describe the configuration of the QSFP28 ports: 'X' stands for 10 GbE, 'C' stands for 100 GbE. See the following table for more details.

1x 10 GbE (Lane 0)

The analog bandwidth determines the available master clock rates. As of UHD 4.1, only the X4_200 image is shipped with UHD, which allows a 245.76 MHz or 250 MHz master clock rate. The other images are considered experimental (unsupported).

==Device Arguments==

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold; text-align:center;"
! Key
! Description
! Example Value
|-
| addr
| IPv4 address of primary SFP+ port to connect to.
| addr=192.168.30.2
|-
| second_addr
| IPv4 address of secondary SFP+ port to connect to.
| second_addr=192.168.40.2
|-
| mgmt_addr
| IPv4 address or hostname to which to connect the RPC client. Defaults to `addr'.
| mgmt_addr=ni-sulfur-311FE00
|-
| find_all
| When using broadcast, find all devices, even if unreachable via CHDR.
| find_all=1
|-
| master_clock_rate
| Master Clock Rate in Hz.
| master_clock_rate=250e6
|-
| serialize_init
| Force serial initialization of daughterboards.
| serialize_init=1
|-
| skip_init
| Skip the initialization process for the device.
| skip_init=1
|-
| time_source
| Specify the time (PPS) source.
| time_source=internal
|-
| clock_source
| Specify the reference clock source.
| clock_source=internal
|-
| ref_clk_freq
| Specify the external reference clock frequency, default is 10 MHz.
| ref_clk_freq=20e6
|-
| discovery_port
| Override default value for MPM discovery port.
| discovery_port=49700
|-
| rpc_port
| Override default value for MPM RPC port.
| rpc_port=49701
|}

==GPS==

The USRP X410 includes a Jackson Labs LTE-Lite GPS module. Its antenna port is on the rear panel (see Front and Back Panels). When the X410 has access to GPS satellite signals, it can use this module to read out the current GPS time and location as well as to discipline an onboard OCXO.

To use the GPS as a clock and time reference, simply use gpsdo as a clock or time source. Alternatively, set gpsdo as a synchronization source:

<code>
// Set clock/time individually:
usrp->set_clock_source("gpsdo");
usrp->set_time_source("gpsdo");
// This is equivalent to the previous commands, but faster, as it sets
// both settings simultaneously and avoids duplicating settings that are shared
// between these calls.
usrp->set_sync_source("clock_source=gpsdo,time_source=gpsdo");
</code>

Note the GPS module is not always enabled. Its power-on status can be queried using the gps_enabled GPS sensor (see also The Sensor API). When disabled, none of the sensors will return useful (if any) values.

When selecting gpsdo as a clock source, the GPS will always be enabled. Note that acquiring a GPS lock can take some time after enabling the GPS, so if a UHD application is enabling the GPS dynamically, it might take some time before a GPS lock is reported.

==Front-Panel Programmable GPIOs==

The USRP X410 has two HDMI front-panel connectors, which are connected to the FPGA.

Support for using these with UHD is not yet available.

==Subdev Specifications==

The RF ports on the front panel of the X410 + ZBX correspond to the following subdev specifications:

{| class="wikitable"
|-
! Label
! style="text-align:center; vertical-align:middle; font-weight:bold;" | Subdev Spec
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 0
| A:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 1
| A:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 0
| B:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 1
| B:1
|}

The subdev spec slot identifiers "A" and "B" are not reflected on the front panel. They were set to match valid subdev specifications of previous USRPs, maintaining backward compatibility.

These values can be used for uhd::usrp::multi_usrp::set_rx_subdev_spec() and uhd::usrp::multi_usrp::set_tx_subdev_spec() as with other USRPs.

==Rear Panel Status LEDs==

The USRP X410 is equipped with four LEDs located on the device's rear panel. Each LED supports four different states: Off, Green, Red, and Amber. One LED (PWR) indicates the device's power state (see Power LED below). The other three LEDs (LED 0, LED 1, and LED 2) are user-configurable, different behaviors are supported for each of these LEDs (see User-configurable LEDs below).

[[File:x4xx_rearpanel_status_leds.png|125px]]

===X4x0 Rear Panel Status LEDs===
Power LED
The USRP X410's PWR LED is reserved to visually indicate the user the device's power state. Power LED Behavior describes what each LED state represents.

===Power LED Behavior===

{| class="wikitable" style="background-color:#FFF;"
|- style="font-weight:bold; text-align:center;"
! PWR LED State
! style="vertical-align:middle;" | Meaning
|- style="vertical-align:middle;"
| Off
| No power is applied
|- style="vertical-align:middle;"
| Amber
| Power is good but X410 is powered off
|- style="vertical-align:middle;"
| Green
| Power is good and X410 is powered on
|- style="vertical-align:middle;"
| Red
| Power error state
|}

===User-configurable LEDs===
The USRP X410's user-configurable rear panel status LEDs (LED 0, LED 1, and LED 2) allow the user to have visual indication of various device conditions. Supported LED Behaviors provides a complete list of the supported behaviors for each user-configurable LED. By default, these LEDs are configured as described in LEDs Default Behavior.

The user may alter the default LEDs behavior either temporarily or persistently, see the Temporarily change the LED Behavior or Persistently in the UHD manual to change the LED Behavior accordingly.

https://files.ettus.com/manual/page_usrp_x4xx.html

==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:X410]]

E320 Getting Started Guide

2022-03-22T21:22:21Z

WadeFife: Show both old and new SFP network port config file locations

==Kit Contents==

===E320 Board-only===
{|
|style="vertical-align:top"|
* USRP E320
* Power connector (assembly required)
* 4 M3x0.5, M3x5 Standoffs
* 1 Gb Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* 1 Gb SFP+ to RJ45 Adapter
* Getting Started Guide
* Ettus Research Sticker
|[[File:e320 board only.jpg|500px|center]]
|}

===E320 Full Enclosure===
{|
|style="vertical-align:top"|
* USRP E320 in enclosure
* DC Power Supply (12V, 7A)
* 1 Gb Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* 1 Gb SFP+ to RJ45 Adapter
* Getting Started Guide
* Ettus Research Sticker
* T8 Torx Wrench
|[[File:e320 enclosure kit.jpg|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==

* For Network Mode: A host computer with an 1 or 10 Gb Ethernet interface. If operating with the 10 Gb Ethernet interface, the "XG" FPGA image must be loaded before the SFP+ port will operate at 10 Gb speeds. Optionally a second 1 Gb Ethernet interface can be used to connect to the onboard ARM CPU for remote management.

* For Embedded Mode: A host computer is only required for initial device configuration, remote control and management, or data visualization. The host computer can connect to the RJ45 1 Gb port or Serial Console port to remotely access the Open Embedded Linux operating system running on the ARM CPU. Once configured, the USRP E320 can operate as a stand-alone device without a connection to a remote host computer.

* For Board-only Version: A third-party 10-14V/3A power supply, which requires assembly with the power connect components included in the kit. An assembled power supply can be purchased here: https://www.ettus.com/product/details/12V-PWR

==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 anything especially metal objects to touch the board while it is powered on.
* 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.
* Never touch the circuit board or heatsink while the device is powered on.
* All connections should be made/removed while is device is powered off.

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

To use your Universal Software Radio Peripheral (USRP™), you must have software tools correctly installed and configured on your host computer. Step-by-step guides for these software tools are found in the Application Notes for 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]].

The USRP E320 requires UHD version 3.13.0.2 or later. It is strongly recommended to use the latest stable release of UHD on both the host computer and the USRP via the filesystem on the SD card. If this release fails to work in some way, then try the maintenance branch of the latest stable version. If you are operating the device in Network Mode, the version of UHD running on the host machine and E320 USRP must match to within the same maintenance release and branch. See the [https://github.com/ettusresearch/uhd UHD GitHub repository] for the latest release and maintenance branch.

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

'''Serial Console'''

The Serial Console provides a low-level interface to the ARM CPU and STM32 microcontroller, typically used for debugging. The serial console can also be used as a JTAG connection to the FPGA.

'''1 Gb RJ45 Connection'''

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

'''SFP+ Connection'''

The SFP+ Connection supports multiple interfaces for streaming high-speed, low-latency data, depending upon which FPGA image is loaded.

===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, OS X, or other Unix based operating systems have a utility 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 distribution's package manager. For Ubuntu/Debian based operating systems it can be installed with the package manager <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-FTDI_Dual_RS232-HS-if00-port0
usb-FTDI_Dual_RS232-HS-if01-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6A69-if00-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6A69-if01-port0

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

Every E320 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>STM32 Microcontroller</code>, whereas the second connects to the <code>ARM CPU</code>.

If you have multiple E320 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_007F6A69-if01-port0 115200

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

Alchemy 2018.04 ni-e320-serial ttyPS0
ni-e320-serial 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-e320-<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_007F6A69-if00-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 1 Gb 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 1 Gb 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 8000 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
</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.50,192.168.1.100 --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 systems with SSH, as shown below:

$ ssh root@192.168.1.51

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

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

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

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

root@ni-e320-<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 E320 USRP must match.

There is two ways to update the file system for the E320 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 are 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 "data" 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 e320 --yes

Example Output:
[INFO] Images destination: /usr/local/share/uhd/images
395769 kB / 395769 kB (100%) e3xx_e320_mender_default-v3.13.1.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 E320. This can be done with the Linux utility <code>scp</code>.

$ scp /usr/local/share/uhd/images/usrp_e320_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 E320's IP is <code>192.168.1.51</code>.

After copying the Mender file system image to the E320, connect to the E320 using either the Serial Console, or via SSH to gain shell access.

On the E320, run <code>mender -rootfs /path/to/latest.mender</code> to update the file system:

root@ni-e320-serial:~# mender -rootfs /home/root/usrp_e320_fs.mender

Example Output:

<pre>
root@ni-e320-316E375:~# mender -rootfs /home/root/usrp_e320_fs.mender
INFO[0000] Start updating from local image file: [/home/root/usrp_e320_fs.mender] module=rootfs
Installing update from the artifact of size 399640064
INFO[0000] opening device /dev/mmcblk0p3 for writing module=block_device
INFO[0000] partition /dev/mmcblk0p3 size: 2046820352 module=block_device
................................ 0% 1024 KiB
................................ 0% 2048 KiB
................................ 0% 3072 KiB
[truncated for readability]
................................ 99% 389120 KiB
................................ 99% 390144 KiB
................................ 100% 390273 KiB
INFO[0740] wrote 2046820352/2046820352 bytes of update to device /dev/mmcblk0p3 module=device
INFO[0744] Enabling partition with new image installed to be a boot candidate: 3 module=device

</pre>

The artifact can also be stored on a remote server:
$ mender -rootfs <http://server.name/path/to/latest.mender>

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 E320:
$ 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 http://uhd.ettus.com.

===Updating the files system by writing the disk image===
The microSD card is accessible directly on the Board-only version of the E320 USRP. The E320 Full Enclosure version must be opened with the included Torx wrench.

NOTE: This method will overwrite all data saved on the microSD card, including any data saved to the <code>/data</code> partition.

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 microSD card.

==Updating the Network Configurations==
The USRP E320 systemd network configuration files are located either at: <code>/etc/systemd/network/</code>

# ls /etc/systemd/network/
eth0.network sfp0.network

or for newer versions of the file system: <code>/data/network/</code>

# ls /data/network/
eth0.network int0.network sfp0.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=v4

[DHCPv4]
UseHostname=false

sfp0 (static):

[Match]
Name=sfp0

[Network]
Address=192.168.10.2/24

[Link]
MTUBytes=8000
</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>/data/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>8000</code>

For addition details on network configuration here: https://files.ettus.com/manual/page_usrp_e320.html#e320_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.

Network mode FPGA image updates must be made through the RJ45 management interface.

To obtain all the FPGA images for your installed version of UHD, run the following command on the host computer with internet access:

$ sudo uhd_images_downloader -t e320 -t fpga

Example Output:

$ uhd_images_downloader -t e320 -t fpga
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

There is two versions of the E320 FPGA images shipped with UHD:

- <code>1G</code> for 1 Gb rates on the SFP+ port (default image)

- <code>XG</code> for 10 Gb rates on the SFP+ port

In this example, we load the <code>XG</code> variant of the FPGA image.

$ uhd_image_loader --args "type=e3xx,mgmt_addr=<E320_RJ45_IP_ADDR>,fpga=XG"

Example Output:

$ uhd_image_loader --args "mgmt_addr=192.168.1.51,type=e3xx,fpga=XG"
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.0-1-gd3b7e90a
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.1.51,type=e3xx,product=e320,serial=316E375,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: 316E375
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.
[INFO] [MPM.PeriphManager] Found 1 daughterboard(s).

The FPGA is immediately updated, and this FPGA image will continue to be used. The device does not need to be power cycled to use the new image.

To load a different FPGA image (i.e. <code>1G</code>), modify the device argument <code>fpga=</code> to a value of <code>fpga=1G</code>.

To specify the path to a custom FPGA image, use the <code>--fpga-path</code> argument.

$ uhd_image_loader --args "type=e3xx,mgmt_addr=<E320_RJ45_IP_ADDR>" --fpga-path=/path/to/custom/fpga.bit

{|
|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;" |The Verilog code for the FPGA in the USRP E320 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 [[#Setting_up_a_Serial_Console_Connection|via Serial Console]] or [[E320_Getting_Started_Guide#Connecting_to_the_ARM_via_SSH| via SSH]]. It is generally recommend to use SSH over the RJ45 interface for remote management.

Run the command <code>uhd_images_downloader</code> to download the FPGA images to the device's file system:

NOTE: The 1 Gb RJ45 management interface will require Internet access for this next step.

<pre>
root@ni-e320-serial:~# python3 /usr/bin/uhd_images_downloader -t e320 -t fpga
[INFO] Images destination: /usr/share/uhd/images
[INFO] No inventory file found at /usr/share/uhd/images/inventory.json. Creating an empty one.
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
[INFO] Images download complete.
</pre>

NOTE: The default UHD FPGA Images destination within the E320's file-system is <code>/usr/share/uhd/images</code>. The default UHD FPGA Images destination on a typical host installation is <code>/usr/local/share/uhd/images</code>.

Updating the FPGA image from the ARM CPU is the same as detailed above for a Network mode update:

<pre>
root@ni-e320-serial:~# uhd_image_loader --args "type=e3xx,fpga=1G"
[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106600; UHD_3.13.1.0-0-unknown
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=127.0.0.1,type=e3xx,product=e320,serial=316E375,claimed=False,skip_init=1
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[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: 316E375
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.
[INFO] [MPM.PeriphManager] Found 1 daughterboard(s).

</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+ port for streaming samples to the host computer.

===1 Gb Streaming via SFP+ Port ===
Complete the steps below to set up a streaming connection over the 1 Gb Ethernet interface on the <code>SFP+ Port</code>.

NOTE: The <code>1G</code> FPGA image must be loaded for the <code>SFP+ Port</code> to operate at 1 Gb speeds. If the <code>XG</code> image is loaded, the port will be unresponsive at 1Gb speeds.

1. Configure your Host's 1 Gb Ethernet interface as shown below. This interface should be separate from the 1 Gb NIC/network which is connected to the 1 Gb 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 the <code>SFP+ Port</code> at 1 Gb speeds, it is important to set a MTU of <code>1500</code> and not a value of <code>automatic</code>. Mismatched MTU values on either the Host or E320 may cause flow control errors. Your computer may need to be restarted for the MTU value to take effect.

2. Insert the RJ45-to-SFP+ adapter into the <code>SFP+ Port</code>.

3. Connect the SFP+ adapter on the device to an Ethernet port on the host computer using a standard Ethernet cable.

The Green LED above the <code>SFP+ Port</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.

5. Verify your MTU is set correctly for 1 Gb speeds on the E320. See the section [[E320_Getting_Started_Guide#Updating_the_Network_Configurations|Updating the Network Configurations]] for additional details.

Proceed to the next section [[E320_Getting_Started_Guide#Verifying_Device_Operation|Verifying Device Operation]].

===10 Gb Streaming via SFP+ Port===
Load the <code>XG</code> FPGA image for 10 Gb streaming as detailed in the section [[E320_Getting_Started_Guide#Updating_the_FPGA_Image|Updating the FPGA Image]]. You will need to use a 10 GigE cable that can be plugged in directly to the SFP+ connector on the board.

NOTE: The <code>XG</code> FPGA image must be loaded for the <code>SFP+ Port</code> to operate at 10 Gb speeds. If the <code>1G</code> image is loaded, the port will be unresponsive at 10 Gb speeds. Mismatched MTU values on either the Host or E320 may cause flow control errors.

1. Configure your Host's 10 Gb Ethernet interface as shown below.

IP Address: 192.168.10.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 8000

NOTE: When operating the <code>SFP+ Port</code> at 10 Gb speeds, it is important to set a MTU of <code>8000</code> and not a value of <code>automatic</code>. Mismatched MTU values on either the Host or E320 may cause flow control errors. Your computer may need to be restarted for the MTU value to take effect.

2. Connect the SFP+ port on the device to an Ethernet port on the host computer using a 10 Gb SFP+ copper or fiber cable.

The Green LED above the <code>SFP+ Port</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.

5. Verify your MTU is set correctly for 10 Gb speeds on the E320. See the section [[E320_Getting_Started_Guide#Updating_the_Network_Configurations|Updating the Network Configurations]] for additional details.

Proceed to the next section [[E320_Getting_Started_Guide#Verifying_Device_Operation|Verifying Device Operation]].

==Verifying Device Operation==
Once you have successfully setup a management interface and streaming interface, you can now verify the devices operation using the include UHD utilities.

===Subdevice Specification Mapping===
The USRP E320 contains 2 channels, each represented on the front panel as <code>RF A</code> and <code>RF B</code>. Below is the <code>subdev</code> mapping of RF Ports.

'''E320'''
* RF A = A:0
* RF B = A:1

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 E320 supports master clock rate from 200 kHz to 61.44 MHz and can be changed by adding <code>master_clock_rate=<rate></code> to the default UHD args. The default master clock rate is 16 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.

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 E320===
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 --args "addr=192.168.10.2"
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.0-1-gd3b7e90a
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.10.2,type=e3xx,product=e320,serial=316E375,claimed=False,addr=192.168.10.2
[INFO] [MPM.PeriphManager] init() called with device args `product=e320,mgmt_addr=192.168.10.2'.
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000000)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1343 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1335 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000003320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
_____________________________________________________
/
| Device: E300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-e320-316E375
| | eeprom_version: 2
| | mpm_version: 3.13.1.0-gd3b7e90a
| | pid: 58144
| | product: e320
| | rev: 2
| | rpc_connection: remote
| | serial: 316E375
| | type: e3xx
| | MPM Version: 1.2
| | FPGA Version: 3.0
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_locked, temp_main_power, ref_locked, temp_rf_channelA, temp_fpga, gps_sky, temp_rf_channelB, fan, temp_internal, gps_tpv, gps_time
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Neon
| | | | Antennas: RX2, TX/RX
| | | | Sensors: lo_locked, ad9361_temperature, rssi, lo_lock
| | | | Freq range: 70.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 76.0 step 1.0 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 1
| | | | Name: Neon
| | | | Antennas: RX2, TX/RX
| | | | Sensors: lo_locked, ad9361_temperature, rssi, lo_lock
| | | | Freq range: 70.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 76.0 step 1.0 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: AD9361 Dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Neon
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9361_temperature
| | | | Freq range: 47.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 89.8 step 0.2 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 1
| | | | Name: Neon
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9361_temperature
| | | | Freq range: 47.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 89.8 step 0.2 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: AD9361 Dual DAC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * DDC_0
| | | * DUC_0

</pre>

===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 E320 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 E320 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>RF A / RX2</code> antenna port of the E320.

2. From your host computer, run the command:

$ /usr/local/lib/uhd/examples/rx_ascii_art_dft \
--args "addr=192.168.10.2" \
--freq 98.5e6 \
--rate 2e6 \
--gain 40 \
--ref-lvl="-30" \
--dyn-rng 90 \
--ant "RX2" \
--subdev "A:0"

NOTE: Modify the commandline 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 MHz of spectrum, centered at the specified tuning frequency.

4. Type "<code>Q</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>
$ ./rx_ascii_art_dft --args "addr=192.168.10.2" --freq 98.5e6 --rate 2e6 --gain 40 --ref-lvl="-30" --dyn-rng 90 --ant "RX2" --subdev "A:0"

Creating the usrp device with: addr=192.168.10.2...
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.0-1-gd3b7e90a
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.10.2,type=e3xx,product=e320,serial=316E375,claimed=False,addr=192.168.10.2
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000000)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1334 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1325 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000003320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [MPM.PeriphManager] init() called with device args `product=e320,mgmt_addr=192.168.10.2'.
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
Using Device: Single USRP:
Device: E300-Series Device
Mboard 0: ni-e320-316E375
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: Neon
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: Neon
TX Channel: 1
TX DSP: 1
TX Dboard: A
TX Subdev: Neon

Setting RX Rate: 2.000000 Msps...
Actual RX Rate: 2.000000 Msps...

Setting RX Freq: 98.500000 MHz...
Actual RX Freq: 98.500000 MHz...

Setting RX Gain: 40.000000 dB...
Actual RX Gain: 40.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>1G</code> FPGA image to be loaded.

This example will test one full-duplex stream using "RFA/A:0", at a rate of 2 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2" \
--duration 60 \
--channels "0" \
--rx_rate 2e6 \
--rx_subdev "A:0" \
--tx_rate 2e6 \
--tx_subdev "A:0"

This example will test two full-duplex streams at 2 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2" \
--duration 60 \
--channels "0,1" \
--rx_rate 2e6 \
--rx_subdev "A:0 A:1" \
--tx_rate 2e6 \
--tx_subdev "A:0 A:1"

This example will test two full-duplex streams at 12.5 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2,master_clock_rate=25e6" \
--duration 60 \
--channels "0,1" \
--rx_rate 12.5e6 \
--rx_subdev "A:0 A:1" \
--tx_rate 12.5e6 \
--tx_subdev "A:0 A:1"

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 ====
NOTE: These examples require the <code>XG</code> FPGA image to be loaded.

This example will test one full-duplex stream using "RFA/A:0", at a rate of 61.44 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2,master_clock_rate=61.44e6" \
--duration 60 \
--channels "0" \
--rx_rate 61.44e6 \
--rx_subdev "A:0" \
--tx_rate 61.44e6 \
--tx_subdev "A:0"

This example will test two full-duplex stream, at a rate of 30.72 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2,master_clock_rate=61.44e6" \
--duration 60 \
--channels "0,1" \
--rx_rate 30.72e6 \
--rx_subdev "A:0 A:1" \
--tx_rate 30.72e6 \
--tx_subdev "A:0 A:1"

==USRP E320 Device Specific Operations==

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

=== Autoboot ===

The USRP E320 can be configured to power on and boot automatically when power is applied. By default, autoboot is disabled on all USRPs that support it. To control autoboot on the USRP E320, first determine the current value for <code>MCU_FLAGS[0]</code> by running <code>eeprom-dump</code>. The least significant bit when <code>MCU_FLAGS[0]</code> is viewed as a binary value controls the autoboot.

For example
<pre>
root@ni-e320-XXXXXXX:~# eeprom-dump
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: cbd79a61 (matches)
</pre>
shows <code>-- MCU_FLAGS[0]: 00000008</code>; <code>0x08</code> (<code>0b00001000</code> in binary) indicates that autoboot is disabled. If this value were <code>0x09</code> (<code>0b00001001</code> in binary) it would indicate that autoboot is enabled because least significant bit is 1; same would be true if this value is <code>0x01</code> (<code>0b00000001</code> in binary).

To enable or disable autoboot, copy the existing value of <code>MCU_FLAGS[0]</code> retrieved by <code>eeprom-dump</code> into <code><MCU_FLAGS[0]></code> below and run the command:

* Disable autoboot on USRP E320 (sets least significant bit to 0), regardless of whether currently enabled or disabled:
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x<MCU_FLAGS[0]> & ~0x1))
</pre>
Thus, for the value noted above (autoboot is already disabled, so this command doesn't actually change anything):
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x00000008 & ~0x1))
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: cbd79a61 (matches)
-- Reading back
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: 448fb572 (matches)
</pre>

* Enable autoboot on USRP E320 (sets least significant bit to 1), regardless of whether currently enabled or disabled. For example when changing from autoboot disabled to enabled:
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x<MCU_FLAGS[0]> | 0x1))
</pre>
Thus, for the value noted above:
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x00000008 | 0x1))
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: cbd79a61 (matches)
-- Reading back
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000009
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: 448fb572 (matches)
</pre>

If setting this flag ''does not'' allow autoboot control on the USRP E320, then the device boot firmware needs to be updated. This update is accomplished via the following instructions.

On the USRP E320 via ssh or serial terminal, [https://files.ettus.com/binaries/misc/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6.tar.gz download the update MCU firmware] and extract it:
<pre>
root@ni-e320-XXXXXXX:~# curl https://files.ettus.com/binaries/misc/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6.tar.gz | tar zxf -
</pre>
This will create a directory <code>upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6</code>. Go into this directory and run the firmware flash script:
<pre>
root@ni-e320-XXXXXXX:~# cd upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6
root@ni-e320-XXXXXXX:~/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6# ./flash-firmware.sh
This script updates the microcontroller firmware (RO part). The change is
persistent across power cycles. Incorrect updates can only fixed be a manual
process which requires opening the enclosure.

Updating the microcontroller firmware (RO part) is only required if the Ettus
Research support told you to do so.

Press "y" to continue
</pre>
At the prompt, press the <code>y</code> key to continue. Pressing any other key aborts the procedure:
<pre>
Press "y" to continue n

aborting
root@ni-e320-317F9BF:~/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6#
</pre>
Pressing the <code>y</code> key:
<pre>
Press "y" to continue y

This script will flash ec-neon-rev3.RO.flat to the device
old RO version: neon_vX.X.XXXX-XXXXXXX
new RO version: neon_v1.1.7358-a190641

Press "y" to continue
</pre>
At the prompt, press the <code>y</code> key ''again'' to continue. Pressing any other key aborts the procedure as before.
<pre>
Press "y" to continue y

./ectool --interface=dev reboot_ec RW
./ectool --interface=dev flashread 0x0 65536 ec-neon-rev3.RO.flat.old
Reading 65536 bytes at offset 0...
done.
./ectool --interface=dev flasherase 0x0 65536
Erasing 65536 bytes at offset 0...
done.
./ectool --interface=dev flashwrite 0x0 ec-neon-rev3.RO.flat
Reading 49592 bytes from ec-neon-rev3.RO.flat...
Writing to offset 0...
Write size 112...
done.

copying new firmware files
'ec-neon-rev3.bin' -> '/lib/firmware/ni/ec-neon-rev3.bin'
'ec-neon-rev3.RW.bin' -> '/lib/firmware/ni/ec-neon-rev3.RW.bin'
root@ni-e320-317F9BF:~/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6#
</pre>

Once the script is done, reboot the USRP (e.g., <code>shutdown -r now</code>), and when it comes up the autoboot flag should now work as desired. If these instructions ''do not'' work, then email [mailto:support@ettus.com support@ettus.com] and ask for alternative instructions on how to update the USRP E320 RO and RW boot firmware such that this EEPROM flag setting is honored.

===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-e320-serial:~# passwd
Changing password for root
New password:
Re-enter new password:
passwd: password changed.

==Known Issues==
===Problematic NICs===
In some streaming modes, the Intel I219-LM NIC can produce flow control and sequence errors. It is recommended to use a USB3 to 1 Gb Ethernet Adapter for hosts which have an I219-LM NIC.

==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:E320]]

E320 Getting Started Guide

2022-03-22T21:16:22Z

WadeFife: Change SFP network port config file location

==Kit Contents==

===E320 Board-only===
{|
|style="vertical-align:top"|
* USRP E320
* Power connector (assembly required)
* 4 M3x0.5, M3x5 Standoffs
* 1 Gb Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* 1 Gb SFP+ to RJ45 Adapter
* Getting Started Guide
* Ettus Research Sticker
|[[File:e320 board only.jpg|500px|center]]
|}

===E320 Full Enclosure===
{|
|style="vertical-align:top"|
* USRP E320 in enclosure
* DC Power Supply (12V, 7A)
* 1 Gb Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* 1 Gb SFP+ to RJ45 Adapter
* Getting Started Guide
* Ettus Research Sticker
* T8 Torx Wrench
|[[File:e320 enclosure kit.jpg|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==

* For Network Mode: A host computer with an 1 or 10 Gb Ethernet interface. If operating with the 10 Gb Ethernet interface, the "XG" FPGA image must be loaded before the SFP+ port will operate at 10 Gb speeds. Optionally a second 1 Gb Ethernet interface can be used to connect to the onboard ARM CPU for remote management.

* For Embedded Mode: A host computer is only required for initial device configuration, remote control and management, or data visualization. The host computer can connect to the RJ45 1 Gb port or Serial Console port to remotely access the Open Embedded Linux operating system running on the ARM CPU. Once configured, the USRP E320 can operate as a stand-alone device without a connection to a remote host computer.

* For Board-only Version: A third-party 10-14V/3A power supply, which requires assembly with the power connect components included in the kit. An assembled power supply can be purchased here: https://www.ettus.com/product/details/12V-PWR

==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 anything especially metal objects to touch the board while it is powered on.
* 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.
* Never touch the circuit board or heatsink while the device is powered on.
* All connections should be made/removed while is device is powered off.

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

To use your Universal Software Radio Peripheral (USRP™), you must have software tools correctly installed and configured on your host computer. Step-by-step guides for these software tools are found in the Application Notes for 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]].

The USRP E320 requires UHD version 3.13.0.2 or later. It is strongly recommended to use the latest stable release of UHD on both the host computer and the USRP via the filesystem on the SD card. If this release fails to work in some way, then try the maintenance branch of the latest stable version. If you are operating the device in Network Mode, the version of UHD running on the host machine and E320 USRP must match to within the same maintenance release and branch. See the [https://github.com/ettusresearch/uhd UHD GitHub repository] for the latest release and maintenance branch.

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

'''Serial Console'''

The Serial Console provides a low-level interface to the ARM CPU and STM32 microcontroller, typically used for debugging. The serial console can also be used as a JTAG connection to the FPGA.

'''1 Gb RJ45 Connection'''

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

'''SFP+ Connection'''

The SFP+ Connection supports multiple interfaces for streaming high-speed, low-latency data, depending upon which FPGA image is loaded.

===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, OS X, or other Unix based operating systems have a utility 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 distribution's package manager. For Ubuntu/Debian based operating systems it can be installed with the package manager <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-FTDI_Dual_RS232-HS-if00-port0
usb-FTDI_Dual_RS232-HS-if01-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6A69-if00-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6A69-if01-port0

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

Every E320 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>STM32 Microcontroller</code>, whereas the second connects to the <code>ARM CPU</code>.

If you have multiple E320 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_007F6A69-if01-port0 115200

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

Alchemy 2018.04 ni-e320-serial ttyPS0
ni-e320-serial 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-e320-<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_007F6A69-if00-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 1 Gb 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 1 Gb 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 8000 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
</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.50,192.168.1.100 --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 systems with SSH, as shown below:

$ ssh root@192.168.1.51

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

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

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

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

root@ni-e320-<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 E320 USRP must match.

There is two ways to update the file system for the E320 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 are 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 "data" 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 e320 --yes

Example Output:
[INFO] Images destination: /usr/local/share/uhd/images
395769 kB / 395769 kB (100%) e3xx_e320_mender_default-v3.13.1.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 E320. This can be done with the Linux utility <code>scp</code>.

$ scp /usr/local/share/uhd/images/usrp_e320_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 E320's IP is <code>192.168.1.51</code>.

After copying the Mender file system image to the E320, connect to the E320 using either the Serial Console, or via SSH to gain shell access.

On the E320, run <code>mender -rootfs /path/to/latest.mender</code> to update the file system:

root@ni-e320-serial:~# mender -rootfs /home/root/usrp_e320_fs.mender

Example Output:

<pre>
root@ni-e320-316E375:~# mender -rootfs /home/root/usrp_e320_fs.mender
INFO[0000] Start updating from local image file: [/home/root/usrp_e320_fs.mender] module=rootfs
Installing update from the artifact of size 399640064
INFO[0000] opening device /dev/mmcblk0p3 for writing module=block_device
INFO[0000] partition /dev/mmcblk0p3 size: 2046820352 module=block_device
................................ 0% 1024 KiB
................................ 0% 2048 KiB
................................ 0% 3072 KiB
[truncated for readability]
................................ 99% 389120 KiB
................................ 99% 390144 KiB
................................ 100% 390273 KiB
INFO[0740] wrote 2046820352/2046820352 bytes of update to device /dev/mmcblk0p3 module=device
INFO[0744] Enabling partition with new image installed to be a boot candidate: 3 module=device

</pre>

The artifact can also be stored on a remote server:
$ mender -rootfs <http://server.name/path/to/latest.mender>

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 E320:
$ 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 http://uhd.ettus.com.

===Updating the files system by writing the disk image===
The microSD card is accessible directly on the Board-only version of the E320 USRP. The E320 Full Enclosure version must be opened with the included Torx wrench.

NOTE: This method will overwrite all data saved on the microSD card, including any data saved to the <code>/data</code> partition.

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 microSD card.

==Updating the Network Configurations==
The USRP E320 systemd network configuration files are located at: <code>/data/network/</code>

# ls /data/network/
eth0.network sfp0.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=v4

[DHCPv4]
UseHostname=false

sfp0 (static):

[Match]
Name=sfp0

[Network]
Address=192.168.10.2/24

[Link]
MTUBytes=8000
</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>/data/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>8000</code>

For addition details on network configuration here: https://files.ettus.com/manual/page_usrp_e320.html#e320_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.

Network mode FPGA image updates must be made through the RJ45 management interface.

To obtain all the FPGA images for your installed version of UHD, run the following command on the host computer with internet access:

$ sudo uhd_images_downloader -t e320 -t fpga

Example Output:

$ uhd_images_downloader -t e320 -t fpga
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

There is two versions of the E320 FPGA images shipped with UHD:

- <code>1G</code> for 1 Gb rates on the SFP+ port (default image)

- <code>XG</code> for 10 Gb rates on the SFP+ port

In this example, we load the <code>XG</code> variant of the FPGA image.

$ uhd_image_loader --args "type=e3xx,mgmt_addr=<E320_RJ45_IP_ADDR>,fpga=XG"

Example Output:

$ uhd_image_loader --args "mgmt_addr=192.168.1.51,type=e3xx,fpga=XG"
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.0-1-gd3b7e90a
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.1.51,type=e3xx,product=e320,serial=316E375,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: 316E375
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.
[INFO] [MPM.PeriphManager] Found 1 daughterboard(s).

The FPGA is immediately updated, and this FPGA image will continue to be used. The device does not need to be power cycled to use the new image.

To load a different FPGA image (i.e. <code>1G</code>), modify the device argument <code>fpga=</code> to a value of <code>fpga=1G</code>.

To specify the path to a custom FPGA image, use the <code>--fpga-path</code> argument.

$ uhd_image_loader --args "type=e3xx,mgmt_addr=<E320_RJ45_IP_ADDR>" --fpga-path=/path/to/custom/fpga.bit

{|
|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;" |The Verilog code for the FPGA in the USRP E320 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 [[#Setting_up_a_Serial_Console_Connection|via Serial Console]] or [[E320_Getting_Started_Guide#Connecting_to_the_ARM_via_SSH| via SSH]]. It is generally recommend to use SSH over the RJ45 interface for remote management.

Run the command <code>uhd_images_downloader</code> to download the FPGA images to the device's file system:

NOTE: The 1 Gb RJ45 management interface will require Internet access for this next step.

<pre>
root@ni-e320-serial:~# python3 /usr/bin/uhd_images_downloader -t e320 -t fpga
[INFO] Images destination: /usr/share/uhd/images
[INFO] No inventory file found at /usr/share/uhd/images/inventory.json. Creating an empty one.
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
[INFO] Images download complete.
</pre>

NOTE: The default UHD FPGA Images destination within the E320's file-system is <code>/usr/share/uhd/images</code>. The default UHD FPGA Images destination on a typical host installation is <code>/usr/local/share/uhd/images</code>.

Updating the FPGA image from the ARM CPU is the same as detailed above for a Network mode update:

<pre>
root@ni-e320-serial:~# uhd_image_loader --args "type=e3xx,fpga=1G"
[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106600; UHD_3.13.1.0-0-unknown
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=127.0.0.1,type=e3xx,product=e320,serial=316E375,claimed=False,skip_init=1
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[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: 316E375
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.
[INFO] [MPM.PeriphManager] Found 1 daughterboard(s).

</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+ port for streaming samples to the host computer.

===1 Gb Streaming via SFP+ Port ===
Complete the steps below to set up a streaming connection over the 1 Gb Ethernet interface on the <code>SFP+ Port</code>.

NOTE: The <code>1G</code> FPGA image must be loaded for the <code>SFP+ Port</code> to operate at 1 Gb speeds. If the <code>XG</code> image is loaded, the port will be unresponsive at 1Gb speeds.

1. Configure your Host's 1 Gb Ethernet interface as shown below. This interface should be separate from the 1 Gb NIC/network which is connected to the 1 Gb 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 the <code>SFP+ Port</code> at 1 Gb speeds, it is important to set a MTU of <code>1500</code> and not a value of <code>automatic</code>. Mismatched MTU values on either the Host or E320 may cause flow control errors. Your computer may need to be restarted for the MTU value to take effect.

2. Insert the RJ45-to-SFP+ adapter into the <code>SFP+ Port</code>.

3. Connect the SFP+ adapter on the device to an Ethernet port on the host computer using a standard Ethernet cable.

The Green LED above the <code>SFP+ Port</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.

5. Verify your MTU is set correctly for 1 Gb speeds on the E320. See the section [[E320_Getting_Started_Guide#Updating_the_Network_Configurations|Updating the Network Configurations]] for additional details.

Proceed to the next section [[E320_Getting_Started_Guide#Verifying_Device_Operation|Verifying Device Operation]].

===10 Gb Streaming via SFP+ Port===
Load the <code>XG</code> FPGA image for 10 Gb streaming as detailed in the section [[E320_Getting_Started_Guide#Updating_the_FPGA_Image|Updating the FPGA Image]]. You will need to use a 10 GigE cable that can be plugged in directly to the SFP+ connector on the board.

NOTE: The <code>XG</code> FPGA image must be loaded for the <code>SFP+ Port</code> to operate at 10 Gb speeds. If the <code>1G</code> image is loaded, the port will be unresponsive at 10 Gb speeds. Mismatched MTU values on either the Host or E320 may cause flow control errors.

1. Configure your Host's 10 Gb Ethernet interface as shown below.

IP Address: 192.168.10.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 8000

NOTE: When operating the <code>SFP+ Port</code> at 10 Gb speeds, it is important to set a MTU of <code>8000</code> and not a value of <code>automatic</code>. Mismatched MTU values on either the Host or E320 may cause flow control errors. Your computer may need to be restarted for the MTU value to take effect.

2. Connect the SFP+ port on the device to an Ethernet port on the host computer using a 10 Gb SFP+ copper or fiber cable.

The Green LED above the <code>SFP+ Port</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.

5. Verify your MTU is set correctly for 10 Gb speeds on the E320. See the section [[E320_Getting_Started_Guide#Updating_the_Network_Configurations|Updating the Network Configurations]] for additional details.

Proceed to the next section [[E320_Getting_Started_Guide#Verifying_Device_Operation|Verifying Device Operation]].

==Verifying Device Operation==
Once you have successfully setup a management interface and streaming interface, you can now verify the devices operation using the include UHD utilities.

===Subdevice Specification Mapping===
The USRP E320 contains 2 channels, each represented on the front panel as <code>RF A</code> and <code>RF B</code>. Below is the <code>subdev</code> mapping of RF Ports.

'''E320'''
* RF A = A:0
* RF B = A:1

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 E320 supports master clock rate from 200 kHz to 61.44 MHz and can be changed by adding <code>master_clock_rate=<rate></code> to the default UHD args. The default master clock rate is 16 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.

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 E320===
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 --args "addr=192.168.10.2"
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.0-1-gd3b7e90a
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.10.2,type=e3xx,product=e320,serial=316E375,claimed=False,addr=192.168.10.2
[INFO] [MPM.PeriphManager] init() called with device args `product=e320,mgmt_addr=192.168.10.2'.
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000000)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1343 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1335 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000003320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
_____________________________________________________
/
| Device: E300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-e320-316E375
| | eeprom_version: 2
| | mpm_version: 3.13.1.0-gd3b7e90a
| | pid: 58144
| | product: e320
| | rev: 2
| | rpc_connection: remote
| | serial: 316E375
| | type: e3xx
| | MPM Version: 1.2
| | FPGA Version: 3.0
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_locked, temp_main_power, ref_locked, temp_rf_channelA, temp_fpga, gps_sky, temp_rf_channelB, fan, temp_internal, gps_tpv, gps_time
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Neon
| | | | Antennas: RX2, TX/RX
| | | | Sensors: lo_locked, ad9361_temperature, rssi, lo_lock
| | | | Freq range: 70.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 76.0 step 1.0 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 1
| | | | Name: Neon
| | | | Antennas: RX2, TX/RX
| | | | Sensors: lo_locked, ad9361_temperature, rssi, lo_lock
| | | | Freq range: 70.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 76.0 step 1.0 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: AD9361 Dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Neon
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9361_temperature
| | | | Freq range: 47.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 89.8 step 0.2 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 1
| | | | Name: Neon
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9361_temperature
| | | | Freq range: 47.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 89.8 step 0.2 dB
| | | | Bandwidth range: 20000000.0 to 40000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: AD9361 Dual DAC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * DDC_0
| | | * DUC_0

</pre>

===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 E320 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 E320 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>RF A / RX2</code> antenna port of the E320.

2. From your host computer, run the command:

$ /usr/local/lib/uhd/examples/rx_ascii_art_dft \
--args "addr=192.168.10.2" \
--freq 98.5e6 \
--rate 2e6 \
--gain 40 \
--ref-lvl="-30" \
--dyn-rng 90 \
--ant "RX2" \
--subdev "A:0"

NOTE: Modify the commandline 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 MHz of spectrum, centered at the specified tuning frequency.

4. Type "<code>Q</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>
$ ./rx_ascii_art_dft --args "addr=192.168.10.2" --freq 98.5e6 --rate 2e6 --gain 40 --ref-lvl="-30" --dyn-rng 90 --ant "RX2" --subdev "A:0"

Creating the usrp device with: addr=192.168.10.2...
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.0-1-gd3b7e90a
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.10.2,type=e3xx,product=e320,serial=316E375,claimed=False,addr=192.168.10.2
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000000)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1334 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1325 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000003320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [MPM.PeriphManager] init() called with device args `product=e320,mgmt_addr=192.168.10.2'.
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
[INFO] [0/Radio_0] Performing CODEC loopback test...
[INFO] [0/Radio_0] CODEC loopback test passed
Using Device: Single USRP:
Device: E300-Series Device
Mboard 0: ni-e320-316E375
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: Neon
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: Neon
TX Channel: 1
TX DSP: 1
TX Dboard: A
TX Subdev: Neon

Setting RX Rate: 2.000000 Msps...
Actual RX Rate: 2.000000 Msps...

Setting RX Freq: 98.500000 MHz...
Actual RX Freq: 98.500000 MHz...

Setting RX Gain: 40.000000 dB...
Actual RX Gain: 40.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>1G</code> FPGA image to be loaded.

This example will test one full-duplex stream using "RFA/A:0", at a rate of 2 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2" \
--duration 60 \
--channels "0" \
--rx_rate 2e6 \
--rx_subdev "A:0" \
--tx_rate 2e6 \
--tx_subdev "A:0"

This example will test two full-duplex streams at 2 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2" \
--duration 60 \
--channels "0,1" \
--rx_rate 2e6 \
--rx_subdev "A:0 A:1" \
--tx_rate 2e6 \
--tx_subdev "A:0 A:1"

This example will test two full-duplex streams at 12.5 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2,master_clock_rate=25e6" \
--duration 60 \
--channels "0,1" \
--rx_rate 12.5e6 \
--rx_subdev "A:0 A:1" \
--tx_rate 12.5e6 \
--tx_subdev "A:0 A:1"

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 ====
NOTE: These examples require the <code>XG</code> FPGA image to be loaded.

This example will test one full-duplex stream using "RFA/A:0", at a rate of 61.44 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2,master_clock_rate=61.44e6" \
--duration 60 \
--channels "0" \
--rx_rate 61.44e6 \
--rx_subdev "A:0" \
--tx_rate 61.44e6 \
--tx_subdev "A:0"

This example will test two full-duplex stream, at a rate of 30.72 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "addr=192.168.10.2,master_clock_rate=61.44e6" \
--duration 60 \
--channels "0,1" \
--rx_rate 30.72e6 \
--rx_subdev "A:0 A:1" \
--tx_rate 30.72e6 \
--tx_subdev "A:0 A:1"

==USRP E320 Device Specific Operations==

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

=== Autoboot ===

The USRP E320 can be configured to power on and boot automatically when power is applied. By default, autoboot is disabled on all USRPs that support it. To control autoboot on the USRP E320, first determine the current value for <code>MCU_FLAGS[0]</code> by running <code>eeprom-dump</code>. The least significant bit when <code>MCU_FLAGS[0]</code> is viewed as a binary value controls the autoboot.

For example
<pre>
root@ni-e320-XXXXXXX:~# eeprom-dump
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: cbd79a61 (matches)
</pre>
shows <code>-- MCU_FLAGS[0]: 00000008</code>; <code>0x08</code> (<code>0b00001000</code> in binary) indicates that autoboot is disabled. If this value were <code>0x09</code> (<code>0b00001001</code> in binary) it would indicate that autoboot is enabled because least significant bit is 1; same would be true if this value is <code>0x01</code> (<code>0b00000001</code> in binary).

To enable or disable autoboot, copy the existing value of <code>MCU_FLAGS[0]</code> retrieved by <code>eeprom-dump</code> into <code><MCU_FLAGS[0]></code> below and run the command:

* Disable autoboot on USRP E320 (sets least significant bit to 0), regardless of whether currently enabled or disabled:
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x<MCU_FLAGS[0]> & ~0x1))
</pre>
Thus, for the value noted above (autoboot is already disabled, so this command doesn't actually change anything):
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x00000008 & ~0x1))
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: cbd79a61 (matches)
-- Reading back
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: 448fb572 (matches)
</pre>

* Enable autoboot on USRP E320 (sets least significant bit to 1), regardless of whether currently enabled or disabled. For example when changing from autoboot disabled to enabled:
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x<MCU_FLAGS[0]> | 0x1))
</pre>
Thus, for the value noted above:
<pre>
root@ni-e320-XXXXXXX:~# eeprom-set-flags $((0x00000008 | 0x1))
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000008
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: cbd79a61 (matches)
-- Reading back
-- PID/REV: e320 0002
-- MCU_FLAGS[0]: 00000009
-- MCU_FLAGS[1]: 00000000
-- MCU_FLAGS[2]: 00000000
-- MCU_FLAGS[3]: 00000000
-- Serial: XXXXXXX
-- eth_addr0: XX:XX:XX:XX:XX:XX
-- eth_addr1: XX:XX:XX:XX:XX:XX
-- eth_addr2: XX:XX:XX:XX:XX:XX
-- DT-Compat/MCU-Compat: 0000 0002
-- CRC: 448fb572 (matches)
</pre>

If setting this flag ''does not'' allow autoboot control on the USRP E320, then the device boot firmware needs to be updated. This update is accomplished via the following instructions.

On the USRP E320 via ssh or serial terminal, [https://files.ettus.com/binaries/misc/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6.tar.gz download the update MCU firmware] and extract it:
<pre>
root@ni-e320-XXXXXXX:~# curl https://files.ettus.com/binaries/misc/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6.tar.gz | tar zxf -
</pre>
This will create a directory <code>upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6</code>. Go into this directory and run the firmware flash script:
<pre>
root@ni-e320-XXXXXXX:~# cd upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6
root@ni-e320-XXXXXXX:~/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6# ./flash-firmware.sh
This script updates the microcontroller firmware (RO part). The change is
persistent across power cycles. Incorrect updates can only fixed be a manual
process which requires opening the enclosure.

Updating the microcontroller firmware (RO part) is only required if the Ettus
Research support told you to do so.

Press "y" to continue
</pre>
At the prompt, press the <code>y</code> key to continue. Pressing any other key aborts the procedure:
<pre>
Press "y" to continue n

aborting
root@ni-e320-317F9BF:~/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6#
</pre>
Pressing the <code>y</code> key:
<pre>
Press "y" to continue y

This script will flash ec-neon-rev3.RO.flat to the device
old RO version: neon_vX.X.XXXX-XXXXXXX
new RO version: neon_v1.1.7358-a190641

Press "y" to continue
</pre>
At the prompt, press the <code>y</code> key ''again'' to continue. Pressing any other key aborts the procedure as before.
<pre>
Press "y" to continue y

./ectool --interface=dev reboot_ec RW
./ectool --interface=dev flashread 0x0 65536 ec-neon-rev3.RO.flat.old
Reading 65536 bytes at offset 0...
done.
./ectool --interface=dev flasherase 0x0 65536
Erasing 65536 bytes at offset 0...
done.
./ectool --interface=dev flashwrite 0x0 ec-neon-rev3.RO.flat
Reading 49592 bytes from ec-neon-rev3.RO.flat...
Writing to offset 0...
Write size 112...
done.

copying new firmware files
'ec-neon-rev3.bin' -> '/lib/firmware/ni/ec-neon-rev3.bin'
'ec-neon-rev3.RW.bin' -> '/lib/firmware/ni/ec-neon-rev3.RW.bin'
root@ni-e320-317F9BF:~/upgrade_mcu_neon_v1.1.7358-a190641-musl-glibc-rev3-6#
</pre>

Once the script is done, reboot the USRP (e.g., <code>shutdown -r now</code>), and when it comes up the autoboot flag should now work as desired. If these instructions ''do not'' work, then email [mailto:support@ettus.com support@ettus.com] and ask for alternative instructions on how to update the USRP E320 RO and RW boot firmware such that this EEPROM flag setting is honored.

===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-e320-serial:~# passwd
Changing password for root
New password:
Re-enter new password:
passwd: password changed.

==Known Issues==
===Problematic NICs===
In some streaming modes, the Intel I219-LM NIC can produce flow control and sequence errors. It is recommended to use a USB3 to 1 Gb Ethernet Adapter for hosts which have an I219-LM NIC.

==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:E320]]

USRP X410 Getting Started Guide

2022-03-22T00:08:29Z

WadeFife: Correct instructions for changing hostname.

==Kit Contents==
===X410===
{|
|style="vertical-align:top"|
* NI Ettus USRP X410
* DC Power Supply (12V, 20A)
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to USB-C Cable (1m)
* Getting Started Guide URL (QR Code)
* Safety, Environmental, and Regulatory Information
||[[File:X410.jpg|450px|center]]
|}

==You Will Need==
* 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 +14 dBm continuous <=3GHz, +17 dBm continuous >3GHz, or +20dBm more than 5 minutes >3GHz 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 X410 requires UHD version 4.1 or later.

'''When you receive a brand-new device, it is strongly recommended that you download the latest filesystem image from the Ettus Research website update the unit. It is not recommended that you use the filesystem from the factory as-is. Instructions on downloading the latest filesystem image and updating it is 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 X410 must match.'''

==Assembling the X410==
Inside the kit you will find the X410 and an X410 power supply. Plug these in, connect the 1GbE RJ45 interface to your network, and power on the device by pressing the power button.

==The STM32 Microcontroller==

The STM32 microcontroller (also referred to as the "SCU") controls various low-level features of the X4x0 series motherboard: It controls the power sequencing, reads out fan speeds and some of the temperature sensors. It is connected to the RFSoC via an I2C bus. It is running software based on Chromium EC.

It is possible to log into the STM32 using the serial interface (see Connecting to the Microcontroller). This will allow certain low-level controls, such as remote power cycling should the CPU have become unresponsive for whatever reason.

===Updating the SCU===

The writable SCU image file is stored on the filesystem under /lib/firmware/ni/ec-titanium-revX.RW.bin (where X is a revision compatibility number). To update, simply replace the .bin file with the updated version and reboot.

==eMMC Storage==

The main non-volatile storage of the USRP is a 16 GB eMMC storage. This storage can be made accessible as a USB Mass Storage device through the USB-OTG connector on the back panel.

The entire root file system (Linux kernel, libraries) and any user data are stored on the eMMC. It is partitioned into four partitions:

Boot partition (contains the bootloader). This partition usually does not require modification.
A data partition, mounted in /data. This is the only partition that is not erased during file system updates.
Two identical system partitions (root file systems). These contain the operating system and the home directory (anything mounted under / that is not the data or boot partition). The reason there are two of these is to enable remote updates: An update running on one partition can update the other one without any effect to the currently running system. Note that the system partitions are erased during updates and are thus unsuitable for permanently storing information.
Note: It is possible to access the currently inactive root file system by mounting it. After logging into the device using serial console or SSH (see the following two sections), run the following commands:

<code>
$ mkdir temp

$ mount /dev/mmcblk0p3 temp # This assumes mmcblk0p3 is currently not mounted

$ ls temp # You are now accessing the idle partition:

bin data etc lib media proc sbin tmp usr
boot dev home lost+found mnt run sys uboot var
</code>

The device node in the mount command might differ, depending on which partition is currently already mounted.

==USB Access to eMMC==

While Mender should be used for routine filesystem updates (see Updating Filesystems), it is also possible to access the X410's internal eMMC from an external host over USB. This allows accessing or modifying the filesystem, as well as the ability to flash the device with an entirely new filesystem.

In order to do so, you'll need an external computer with two USB ports, and two USB cables to connect the computer to your X410. The instructions below assume a Linux host.

First, connect to the APU serial console at a baud rate of 115200. Boot the device, and stop the boot sequence by typing noautoboot at the prompt. Then, run the following command in the U-boot command prompt:

<code>ums 0 mmc 0</code>

This will start the USB mass storage gadget to expose the eMMC as a USB mass storage device. You should see a spinning indicator on the console, which indicates the gadget is active.

Next, connect your external computer to the X410's USB to PS port using an OTG cable. Your computer should recognize the X410 as a mass storage device, and you should see an entry in your kernel logs (dmesg) that looks like this:

<code>
usb 3-1: New USB device found, idVendor=3923, idProduct=7a7d, bcdDevice= 2.23

usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0

usb 3-1: Product: USB download gadget

usb 3-1: Manufacturer: National Instruments

sd 6:0:0:0: [sdc] 30932992 512-byte logical blocks: (15.8 GB/14.8 GiB)

sdc: sdc1 sdc2 sdc3 sdc4

sd 6:0:0:0: [sdc] Attached SCSI removable disk
</code>

The exact output will depend on your machine, but from this log you can see that the X410 was recognized and /dev/sdc is the block device representing the eMMC, with 4 partitions detected (see eMMC Storage for details on the partition layout).

It is now possible to treat the X410's eMMC as you would any other USB drive: the individual partitions can be mounted and accessed, or the entire block device can be read/written.

Once you're finished accessing the device over USB, the u-boot gadget may be stopped by hitting Ctrl-C at the APU serial console.

==Flashing the eMMC==

Once the X410's eMMC is accessible over USB, it's possible to write the filesystem image using bmaptool. You can obtain the latest filesystem image by running:

<code>uhd_images_downloader -t sdimg -t x4xx</code>

The output of this command will indicate where the downloaded image can be found.

Run:

<code> sudo bmaptool /path/to/usrp_x4xx_fs.sdimg.bz2 /dev/sdX</code>

to flash the eMMC with this image (replacing /dev/sdX with the block device of the X410's eMMC as indicated by your kernel log).

==Using a USRP X4x0 from UHD==
Like any other USRP, all X4x0 USRPs are controlled by the UHD software. To integrate a USRP X4x0 into your C++ application, you would generate a UHD device in the same way you would for any other USRP:

<code>auto usrp = uhd::usrp::multi_usrp::make("type=x4xx");</code>

For a list of which arguments can be passed into make(), see Section Device Arguments.

==Updating Filesystems==

Mender is a third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website). 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. Mender servers can be self-hosted, or hosted by Mender (see mender.io for pricing and availability).

When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted (note: the onboard flash storage contains two separate root file system partitions, only one is ever used at a single time). Any data stored on that partition will be permanently lost, including the currently loaded FPGA image. After updating that partition, 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 initiate an update from the device itself, download a Mender artifact containing the update itself. These are files with a .mender suffix. They can be downloaded by using the uhd_images_downloader utility:

<code>$ uhd_images_downloader -t mender -t x4xx</code>

Append the -l switch to print out the URLs only:

<code>$ uhd_images_downloader -t mender -t x4xx -l</code>
Then run mender on the command line:

<code>$ mender install /path/to/latest.mender</code>

The artifact can also be stored on a remote server:

<code>$ mender install http://server.name/path/to/latest.mender</code>

This procedure will take a while. If the new filesystem requires an update to the MB CPLD, see Updating the Motherboard CPLD before proceeding. After mender has logged a successful update, reboot the device:

<code>$ reboot</code>

If the reboot worked, and the device seems functional, commit the changes so the boot loader knows to permanently boot into this partition:

<code>$ mender commit</code>

To identify the currently installed Mender artifact from the command line, the following file can be queried:

<code>$ cat /etc/mender/artifact_info</code>

If you are running a hosted 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 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.

==Network Interfaces==
The Ettus USRP X410 has various network interfaces:

eth0: RJ45 port.

The RJ45 port comes up with a default configuration of DHCP, that will request a network address from your DHCP server (if available on your network). This interface is agnostic of FPGA image flavor.

int0: internal interface for network communication between the embedded ARM processor and FPGA.

The internal network interface is configured with a static address: 169.254.0.1/24. This interface is agnostic of FPGA image flavor.

sfpX [, sfpX_1, sfpX_2, sfpX_3]: QSFP28 network interface(s), up-to four (one per lane) based on implemented protocol.

Each QSFP28 port has four high-speed transceiver lanes. Therefore, depending on the FPGA image flavor, up-to four different network interfaces may exist per QSFP28 port, using the sfpXfor the first lane, and sfpX_1-3 for the other three lanes. Each network interface has a default static IP address. Note that for multi-lane protocols, such as 100 GbE, a single interface is used (sfpX).
The configuration files for these network interfaces are stored in: <code>/etc/systemd/network/</code>

{| class="wikitable"
|-
! Interface Name
! Description
! Default Configuration
! Configuration File
! Example: X4_200 FPGA image
|-
| eth0
| RJ45
| style="vertical-align:middle; background-color:#FFF;" | DHCP
| style="vertical-align:middle; background-color:#FFF;" | eth0.network
| DHCP
|-
| int0
| Internal
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
| style="vertical-align:middle; background-color:#FFF;" | int0.network
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
|-
| sfp0
| QSFP28 0 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
|-
| style="background-color:#FFF;" | sfp0_1
| QSFP28 0 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_1.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
|-
| style="background-color:#FFF;" | sfp0_2
| QSFP28 0 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_2.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
|-
| sfp0_3
| QSFP28 0 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_3.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
|-
| sfp1
| QSFP28 1 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.20.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| sfp1_1
| QSFP28 1 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.21.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_2
| QSFP28 1 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.22.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_2.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_3
| QSFP28 1 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.23.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_3.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
|}

==Network Connectivity==
Once the X410 has booted, determine the IP address and verify network connectivity by running uhd_find_devices on the host computer:

<code>
$ uhd_find_devices

-- UHD Device 0

Device Address:
serial: 1234ABC
addr: 10.2.161.10
claimed: False
mgmt_addr: 10.2.161.10
product: x410
type: x4xx
</code>

By default, an X410 will use DHCP to attempt to find an address.

At this point, you should run:

<code>uhd_usrp_probe --args addr=<IP address></code>
to ensure functionality of the device.

Note: If you receive the following error:

<code>Error: RuntimeError: Graph edge list is empty for rx channel 0</code>
then you will need to download a UHD-compatible FPGA as described in Updating the FPGA or using the following command (it assumes that FPGA images have been downloaded previously using uhd_images_downloader, or that the command is run on the device itself):

<code>uhd_image_loader --args type=x4xx,addr=<ip address>,fpga=X4_200</code>
When running on the device, use <code>127.0.0.1</code> as the IP address.

You can now use existing UHD examples or applications (such as rx_sample_to_file, rx_ascii_art_dft, or tx_waveforms) or other UHD-compatible applications to start receiving and transmitting with the device.

See Network Interfaces for further details on the various network interfaces available on the X410.

===Network Status LEDs===
The Ettus USRP X410 is equipped with status LEDs for its network-capable ports: RJ45 and QSFP28s, see RJ45 LED Behavior and QSFP28 LED Behavior accordingly.

====RJ45 LED Behavior====
The RJ45 port has two independent LEDs: green (right) and yellow (left). The table below summarizes the LEDs' behavior. Note that link speed indication is not currently supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! Green LED
! Yellow LED
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| On
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| On
| Blinking
|}

====QSFP28 LED Behavior====
Each QSFP28 connector has four LEDs, one for each high-speed transceiver lane. The table below summarizes the LEDs' behavior, note that for multi-lane protocols, such as 100 GbE, the corresponding LEDs are ganged together. Within the same image, multiple speeds on the same port (e.g., both 10 GbE and 100 GbE) are not supported, therefore link speed indication is not supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! QSFP28 LED (4 Total)
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| Green (solid)
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| Amber (blinking)
|}

==Security-related Settings==
The X410 ships without a root password set. It is possible to ssh into the device by simply connecting as root, and thus gaining access to all subsystems. To set a password, run the command

<code>$ passwd</code>
on the device.

==Serial Connection==
It is possible to gain access to the device using a serial terminal emulator. To do so, the USB debug port needs to be connected to a separate computer to gain access. Most Linux, OSX, or other Unix flavors have a tool called 'screen' which can be used for this purpose, by running the following command:

<code>$ sudo screen /dev/ttyUSB2 115200</code>
In this command, we prepend 'sudo' to elevate user privileges (by default, accessing serial ports is not available to regular users), we specify the device node (in this case, /dev/ttyUSB2), and the baud rate (115200).

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

<code>$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0
</code>

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

The first (with the if02 suffix) connects to the STM32 microcontroller (SCU), whereas the second (with the if03 suffix) connects to Linux running on the RFSoC APU.

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 115200</code>
After entering the username root (no password is set by default), you should be presented with a shell prompt similar to the following:

<code>root@ni-x4xx-1234ABC:~#</code>
On this prompt, you can enter any Linux command available. Using the default configuration, the serial console will also show all kernel log messages (unlike when using SSH, for example), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or bootloader issues more efficiently than when logged in via SSH.

==Connecting to the Microcontroller==
The microcontroller (which controls the power sequencing, among other things) also has a serial console available. To connect to the microcontroller, use the other UART device. In the example above:

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 115200</code>

It provides a very simple prompt. The command 'help' will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it and other low-level diagnostics. For example, running the command reboot will emulate a reset button press, resetting the state of the device, while the command powerbtn will emulate a power button press, turning the device back on again.

==SSH Connection==
The USRP X410 has two network connections: The dual QSFP28 ports, and an RJ45 connector. The latter is by default configured by DHCP; by plugging it into into 1 Gigabit switch on a DHCP-capable network, it will get assigned an IP address and thus be accessible via ssh.

In case your network setup does not include a DHCP server, refer to the section Serial Connection. A serial login can be used to assign an IP address manually.

After the device obtained an IP address you can log in from a Linux or OSX machine by typing:

<code>$ ssh root@ni-x4xx-1234ABC # Replace with your actual device name!</code>
Depending on your network setup, using a .local domain may work:

<code>$ ssh root@ni-x4xx-1234ABC.local</code>
Of course, you can also connect to the IP address directly if you know it (or set it manually using the serial console).

Note: The device's hostname is derived from its serial number by default (<code>ni-x4xx-$SERIAL</code>). You can change the hostname by creating the file <code>/data/network/hostname</code>, saving the desired hostname in it, then rebooting.

On Microsoft Windows, the connection can be established using a tool such as PuTTY, by selecting a username of root without password.

Like with the serial console, you should be presented with a prompt like the following:

<code>root@ni-x4xx-1234ABC:~#</code>

== Autoboot ==

The USRP X410 can be configured to power on and boot automatically when power is applied. This setting can be controlled using the <code>eeprom-set-autoboot</code> script. This script is executed directly on the USRP X410. To enable autoboot, run <code>eeprom-set-autoboot on</code>; to disable autoboot, run <code>eeprom-set-autoboot off</code>.

==Updating the FPGA==

The FPGA can be updated simply using uhd_image_loader:

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device> --fpga-path <path to .bit></code>
or

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device>,fpga=FPGA_TYPE</code>
A UHD install will likely have pre-built images in /usr/share/uhd/images/. Up-to-date images can be downloaded using the uhd_images_downloader script:

<code>uhd_images_downloader</code>
will download images into /usr/share/uhd/images/ (the path may differ, depending on how UHD was installed).

Also note that the USRP already ships with compatible FPGA images on the device - these images can be loaded by SSH'ing into the device and running:

<code>uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_200</code>

==FPGA Image Flavors==

Unlike the USRP X310 or other third-generation USRP devices, the FPGA image flavors do not only encode how the QSFP28 connectors are configured, but also which master clock rates are available. This is because the data converter configuration is part of the FPGA image (the ADCs/DACs on the X410 are on the same die as the FPGA). The image flavors consist of two short strings, separated by an underscore, e.g. X4_200 is an image flavor which contains 4x 10 GbE, and can handle an analog bandwidth of 200 MHz. The first two characters describe the configuration of the QSFP28 ports: 'X' stands for 10 GbE, 'C' stands for 100 GbE. See the following table for more details.

1x 10 GbE (Lane 0)

The analog bandwidth determines the available master clock rates. As of UHD 4.1, only the X4_200 image is shipped with UHD, which allows a 245.76 MHz or 250 MHz master clock rate. The other images are considered experimental (unsupported).

==Device Arguments==

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold; text-align:center;"
! Key
! Description
! Example Value
|-
| addr
| IPv4 address of primary SFP+ port to connect to.
| addr=192.168.30.2
|-
| second_addr
| IPv4 address of secondary SFP+ port to connect to.
| second_addr=192.168.40.2
|-
| mgmt_addr
| IPv4 address or hostname to which to connect the RPC client. Defaults to `addr'.
| mgmt_addr=ni-sulfur-311FE00
|-
| find_all
| When using broadcast, find all devices, even if unreachable via CHDR.
| find_all=1
|-
| master_clock_rate
| Master Clock Rate in Hz.
| master_clock_rate=250e6
|-
| serialize_init
| Force serial initialization of daughterboards.
| serialize_init=1
|-
| skip_init
| Skip the initialization process for the device.
| skip_init=1
|-
| time_source
| Specify the time (PPS) source.
| time_source=internal
|-
| clock_source
| Specify the reference clock source.
| clock_source=internal
|-
| ref_clk_freq
| Specify the external reference clock frequency, default is 10 MHz.
| ref_clk_freq=20e6
|-
| discovery_port
| Override default value for MPM discovery port.
| discovery_port=49700
|-
| rpc_port
| Override default value for MPM RPC port.
| rpc_port=49701
|}

==GPS==

The USRP X410 includes a Jackson Labs LTE-Lite GPS module. Its antenna port is on the rear panel (see Front and Back Panels). When the X410 has access to GPS satellite signals, it can use this module to read out the current GPS time and location as well as to discipline an onboard OCXO.

To use the GPS as a clock and time reference, simply use gpsdo as a clock or time source. Alternatively, set gpsdo as a synchronization source:

<code>
// Set clock/time individually:
usrp->set_clock_source("gpsdo");
usrp->set_time_source("gpsdo");
// This is equivalent to the previous commands, but faster, as it sets
// both settings simultaneously and avoids duplicating settings that are shared
// between these calls.
usrp->set_sync_source("clock_source=gpsdo,time_source=gpsdo");
</code>

Note the GPS module is not always enabled. Its power-on status can be queried using the gps_enabled GPS sensor (see also The Sensor API). When disabled, none of the sensors will return useful (if any) values.

When selecting gpsdo as a clock source, the GPS will always be enabled. Note that acquiring a GPS lock can take some time after enabling the GPS, so if a UHD application is enabling the GPS dynamically, it might take some time before a GPS lock is reported.

==Front-Panel Programmable GPIOs==

The USRP X410 has two HDMI front-panel connectors, which are connected to the FPGA.

Support for using these with UHD is not yet available.

==Subdev Specifications==

The RF ports on the front panel of the X410 + ZBX correspond to the following subdev specifications:

{| class="wikitable"
|-
! Label
! style="text-align:center; vertical-align:middle; font-weight:bold;" | Subdev Spec
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 0
| A:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 1
| A:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 0
| B:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 1
| B:1
|}

The subdev spec slot identifiers "A" and "B" are not reflected on the front panel. They were set to match valid subdev specifications of previous USRPs, maintaining backward compatibility.

These values can be used for uhd::usrp::multi_usrp::set_rx_subdev_spec() and uhd::usrp::multi_usrp::set_tx_subdev_spec() as with other USRPs.

==Rear Panel Status LEDs==

The USRP X410 is equipped with four LEDs located on the device's rear panel. Each LED supports four different states: Off, Green, Red, and Amber. One LED (PWR) indicates the device's power state (see Power LED below). The other three LEDs (LED 0, LED 1, and LED 2) are user-configurable, different behaviors are supported for each of these LEDs (see User-configurable LEDs below).

[[File:x4xx_rearpanel_status_leds.png|125px]]

===X4x0 Rear Panel Status LEDs===
Power LED
The USRP X410's PWR LED is reserved to visually indicate the user the device's power state. Power LED Behavior describes what each LED state represents.

===Power LED Behavior===

{| class="wikitable" style="background-color:#FFF;"
|- style="font-weight:bold; text-align:center;"
! PWR LED State
! style="vertical-align:middle;" | Meaning
|- style="vertical-align:middle;"
| Off
| No power is applied
|- style="vertical-align:middle;"
| Amber
| Power is good but X410 is powered off
|- style="vertical-align:middle;"
| Green
| Power is good and X410 is powered on
|- style="vertical-align:middle;"
| Red
| Power error state
|}

===User-configurable LEDs===
The USRP X410's user-configurable rear panel status LEDs (LED 0, LED 1, and LED 2) allow the user to have visual indication of various device conditions. Supported LED Behaviors provides a complete list of the supported behaviors for each user-configurable LED. By default, these LEDs are configured as described in LEDs Default Behavior.

The user may alter the default LEDs behavior either temporarily or persistently, see the Temporarily change the LED Behavior or Persistently in the UHD manual to change the LED Behavior accordingly.

https://files.ettus.com/manual/page_usrp_x4xx.html

==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:X410]]

Using the RFNoC Replay Block in UHD 4

2022-02-25T22:02:43Z

WadeFife: Minor edits, formatting changes

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

Knowledge Base

2022-02-08T20:47:46Z

WadeFife: Add UHD 4 version of Getting Started with RFNoC to Other category

Welcome to the Ettus Research Knowledge Base (KB). The KB is continuously being updated and expanded. If you have any suggestions, or do not find what you are looking for, then please [http://www.ettus.com/contact Contact Us].
__NOTOC__
<div class="row">
<div class="col-1-3">
== [[Getting Started Guides| Getting Started Guides]] ==

'''Motherboards'''
* [[B200/B210/B200mini/B205mini Getting Started Guides|B200/B210/B200mini/B205mini]]
* [[Ettus USRP E300 Embedded Family Getting Started Guides|E310/E312/E313]]
* [[E320 Getting Started Guide|E320]]
* [[N200/N210 Getting Started Guides|N200/N210]]
* [[USRP N300/N310/N320/N321 Getting Started Guide|N300/N310/N320/N321]]
* [[X300/X310 Getting Started Guides|X300/X310]]
* [[USRP-2974 Getting Started Guide|USRP-2974]]
* [[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_in_UHD_4.0|RFNoC Development (UHD 4.x)]]
* [[Getting_Started_with_RFNoC_Development|RFNoC Development (UHD 3.x)]]
* [[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| Hardware Resources]] ==
'''Motherboards'''
* [[B200/B210/B200mini/B205mini]]
* [[Ettus USRP E300 Embedded Family Hardware Resources|E310/E312/E313]]
* [[E320|E320]]
* [[N200/N210]]
* [[N300/N310]]
* [[N320/N321]]
* [[X300/X310]]
* [[USRP-2974]]

'''Daughterboards'''
* [[BasicTX/BasicRX]]
* [[CBX]]
* [[LFTX/LFRX]]
* [[SBX]]
* [[TwinRX]]
* [[UBX]]
* [[WBX]]

'''Other'''
* [[OctoClock CDA-2990]]
* [[GPSDO]]
* [[Antennas]]

</div>
<div class="col-1-3">

== [[Software Resources| Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[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| 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| Application Notes]] ==
Application Notes (AN) and technical articles written by engineers, for engineers. These articles offer experienced analysis, design ideas, reference designs, and tutorials—to make you productive and successful using USRP devices.
</div>
<div class="col-1-3">

== [[Additional Resources| Additional Resources]] ==
* [[Suggested Reading|Suggested Reading]]
* [[Suggested Videos|Suggested Videos]]
* [[SDR Events]]
* [[CGRAN]]
</div>
</div>

<div class="row">
<div class="col-1-3">

== [[Technical Support| Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[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| FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]

</div>
<div class="col-1-3">

== [[Legacy Products| Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

Using the RFNoC Replay Block

2021-10-19T19:10:41Z

WadeFife: Removed history section. Updated for UHD 3.15. Added note about UHD 4 not being covered by this article.

==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 by this 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. 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 228 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.

Getting Started with RFNoC in UHD 4.0

2021-06-28T15:17:28Z

WadeFife: Added more information/corrections about how to choose a clock domain for the FFT block.

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

 
[[File:simplified_rfnoc_image_uhd_4.png|center]]
 

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

* '''RFNoC Image Core''' 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''' 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''' 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)''' 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''' 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''' 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''' 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''' 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''' 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''' Here we define the device, the bit width of our CHDR connections, as well as some versioning and licensing.
* '''Stream Endpoints''' 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. 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. 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''' 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''' 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''' 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> This is the HDL for the Gain RFNoC block.
** <code>rfnoc_block_gain.v</code> The top-level synthesizable file for the Gain block
** <code>noc_shell_gain.v</code> The NoC Shell for the Gain block
** <code>rfnoc_block_gain_tb.sv</code> The simulation testbench
** <code>Makefile</code> The simulation Makefile
* <code>rfnoc-example/blocks/gain.yml</code> The YAML block definition file for the Gain block
* <code>rfnoc-example/icores/x310_rfnoc_image_core.yml</code> 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> The software block controller header
* <code>rfnoc-example/lib/gain_block_control.cpp</code> The software block controller implementation
* <code>rfnoc-example/apps/init_gain_block.cpp</code> 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''' 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''' 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''' 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''' 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. 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. Under the <code>inputs</code> and <code>outputs</code> sections you can describe the input and output ports.
* '''IO Ports''' 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!