Difference between revisions of "Using the RFNoC Replay Block"

From Ettus Knowledge Base
Jump to: navigation, search
Line 17: Line 17:
  
 
==Abstract==
 
==Abstract==
This application note guides a user through basic use of the RFNoC Replay block and explains how to run the UHD Replay example. This example covers use on the X310 and N310 products.
+
This application note guides a user through basic use of the RFNoC Replay block and explains how to run the UHD Replay example. This example covers use on the X300/X310 and N310 products.
  
 
==Overview==
 
==Overview==
The Replay block is an RFNoC block that allows recording and playback of arbitrary data using the USRP hardware's DRAM as a buffer. In order to be used, the Replay block must be instantiated in the design and connected to the DRAM. It can take the place of a DMA FIFO or be used concert with a DMA FIFO. 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 repeatedly.
+
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==
 
==Prerequisites==
Line 26: Line 26:
 
===Cloning the Repository===
 
===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 examples.
+
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.
 
'''Note:''' Refer to Application Note AN-823 [[Getting Started with RFNoC Development]] for a more detailed overview of RFNoC development.
  
To begin, use these <code>git clone</code> commands to download the needed UHD and FPGA branches.
+
To begin, use the following <code>git clone</code> commands to download the needed UHD and FPGA repositories.
  
'''Note:''' At the time of writing, the FPGA code is included in UHD-3.13 and later, but the UHD example is not yet included in any releases. So for this application note we will use the master branches.
+
'''Note:''' At the time of writing, the UHD example is not in a current release so for this application note we will use the master branches.
  
 
     $ git clone https://github.com/EttusResearch/uhd.git  
 
     $ git clone https://github.com/EttusResearch/uhd.git  
 
     $ git clone https://github.com/EttusResearch/fpga.git
 
     $ git clone https://github.com/EttusResearch/fpga.git
  
If UHD and/or FPGA are already installed, it would be sufficient to checkout the branches mentioned and update them them (<code>git pull</code>) then rebuild UHD.
+
If UHD and/or FPGA are already installed, then it would be sufficient to checkout the branches mentioned and update them (<code>git pull</code>) then rebuild UHD.
  
 
===Building and Installing UHD===
 
===Building and Installing UHD===
  
If you have not already done so, follow the steps in Application Note '''AN-445 under''' [[Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux#Update_and_Install_dependencies|Update and Install dependencies]].
+
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 run the Replay example.
+
'''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.
 
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.
Line 55: Line 55:
 
     $ cmake -DENABLE_RFNOC=ON ../
 
     $ cmake -DENABLE_RFNOC=ON ../
  
Run Make with RFNOC enabled to build UHD with RFNoC support.
+
Run Make to build UHD with RFNoC support.
  
 
     $ make
 
     $ make
  
Install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.
+
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
 
   $ sudo make install
Line 67: Line 67:
 
   $ sudo ldconfig
 
   $ 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.
+
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
 
   $ export LD_LIBRARY_PATH=/usr/local/lib
  
===Installing FPGA Tools===
+
===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.
 
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==
 
==Building the FPGA==
Line 80: Line 81:
 
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.
 
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/top/x300/x300_core.v</code> and change localparam <code>USE_REPLAY</code> from 0 to 1. This changes the FPGA 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 can not be used.
+
First, we must modify the Verilog code to include the Replay Block. To do this, modify the file <code>fpga/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/top/n3xx/n3xx_core.v</code> and make the same change. Other products that support RFNoC can also use the replay block. However, currently, the Replay block must be manually instantiated in the code.
+
'''Note:''' If using the N310, modify the file <code>fpga/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.
 
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.
Line 89: Line 90:
 
     $ source ./setup.sh
 
     $ source ./setup.sh
  
Run make to build the desired FPGA image. For example, for the X310 HG image, use could use the following command:
+
Run make to build the desired FPGA image. For example, to build the X310 HG image, use the following command:
  
 
     $ make X310_HG
 
     $ make X310_HG
  
Once compilation is complete, download the image to your USRP X310 product. For example, if the X310 HG image is connected to SFP port 0 (1 Gigabit Ethernet) using the default IP address, then you would run the following command.
+
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
 
     $ 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 --args="addr=192.168.10.2"</code>.
+
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"
 
     $ uhd_usrp_probe --args="addr=192.168.10.2"
  
You should see <code>Replay
+
You should see the <code>Replay</code> block listed among the RFNoC blocks on the device.
  
 
   |  |    _____________________________________________________
 
   |  |    _____________________________________________________
Line 124: Line 125:
 
     $ cp ../init_usrp/CMakeLists.txt ./
 
     $ cp ../init_usrp/CMakeLists.txt ./
  
Edit <code>CMakeList.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>.
+
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]]
 
[[File:uhd cpp makefile edits.png|650px]]
Line 137: Line 138:
 
==Running the Example==
 
==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.
+
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.
  
'''Note:''' The <code>replay_samples_from_file</code> does not perform rate conversion, so the rate specified must match the native sample rate of your device (i.e., 200 Msps for the X310, 125 Msps for the N310). The samples file should contains sc16 (16-bit signed complex) samples and should be a multiple of 2 samples (8 bytes) since the Replay block records and plays back in multiples of 8 bytes.
+
'''Note:''' The <code>replay_samples_from_file</code> example does not perform rate conversion, 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 contains sc16 (16-bit signed complex) 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.
  
 
To run the example, enter the following command.
 
To run the example, enter the following command.
  
./replay_samples_from_file --freq 915e6 --gain 10 --file usrp_samples.dat
+
    $ ./replay_samples_from_file --freq 915e6 --gain 10 --file usrp_samples.dat
 +
 
 +
This will replay the data from the file continuously. Press <code>Ctrl+C</code> to stop transmitting.

Revision as of 11:20, 8 October 2018

Application Note Number

TBD

Revision History

Date Author Details
2018-10-05 Wade Fife Initial creation

Abstract

This application note guides a user through basic use of the RFNoC Replay block and explains how to run the UHD Replay example. This example covers use on the X300/X310 and N310 products.

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

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 git clone commands to download the needed UHD and FPGA repositories.

Note: At the time of writing, the UHD example is not in a current release so for this application note we will use the master branches.

   $ git clone https://github.com/EttusResearch/uhd.git 
   $ git clone https://github.com/EttusResearch/fpga.git

If UHD and/or FPGA are already installed, then it would be sufficient to checkout the branches mentioned and update them (git pull) then rebuild UHD.

Building and Installing UHD

If you have not already done so, follow the steps in Application Note AN-445 under the heading Update and Install dependencies.

Note: Refer to Application Note 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 build folder within the host 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 /usr/local/lib 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 LD_LIBRARY_PATH 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 $HOME/.bashrc file.

Note: the LD_LIBRARY_PATH 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 /opt/Xilinx/Vivado 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 fpga/top/x300/x300_core.v and change localparam USE_REPLAY from 0 to 1. This causes the FPGA code to instantiate noc_block_replay instead of noc_block_axi_dma_fifo. 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 fpga/top/n3xx/n3xx_core.v 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 x300_core.v and n3xx_core.v 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 fpga/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 uhd_usrp_probe.

   $ uhd_usrp_probe --args="addr=192.168.10.2"

You should see the Replay 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 uhd/host/examples/init_usrp/CMakeLists.txt as an example.

   $ cd uhd/host/examples
   $ mkdir replay_samples_from_file
   $ cd replay_samples_from_file
   $ cp ../init_usrp/CMakeLists.txt ./

Edit CMakeLists.txt and change the init_usrp references to replay_samples_from_file and init_usrp.cpp to ../replay_samples_from_file.cpp.

uhd cpp makefile edits.png

You can now invoke CMake and run Make to build the example.

   $ mkdir build
   $ cd build
   $ cmake ../
   $ make

Running the Example

The replay_samples_from_file example assumes that you have a file containing the samples you wish to replay. This could be generated in advance or recorded using rx_samples_to_file or another method.

Note: The replay_samples_from_file example does not perform rate conversion, 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 contains sc16 (16-bit signed complex) 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.

To run the example, enter the following command.

   $ ./replay_samples_from_file --freq 915e6 --gain 10 --file usrp_samples.dat

This will replay the data from the file continuously. Press Ctrl+C to stop transmitting.