RFNoC Frequently Asked Questions - Revision history

WadeFife: Added X420 and fast_ce clock

2026-10-14T15:40:18Z

Added X420 and fast_ce clock

JonathonPendlum: Add FAQ for Vivado build error when using custom SystemVerilog packages

2025-10-09T13:53:02Z

Add FAQ for Vivado build error when using custom SystemVerilog packages

WadeFife: Reorder questions and remove redundant questions

2025-10-01T15:06:40Z

Reorder questions and remove redundant questions

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

2025-10-01T14:41:27Z

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

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

2025-10-01T14:35:45Z

Add how to install libncurses on Ubuntu 22 and later

JonathonPendlum: Add how to install libraries required for Vivado 2021.1 installation on Ubuntu

2025-07-23T07:00:32Z

Add how to install libraries required for Vivado 2021.1 installation on Ubuntu

JonathonPendlum: Added FAQ about FPGA build failures due to dash being the default shell instead of bash

2025-05-22T18:41:19Z

Added FAQ about FPGA build failures due to dash being the default shell instead of bash

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

2025-01-29T22:13:35Z

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

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

2024-06-26T13:53:27Z

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

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

2024-06-26T09:33:25Z

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

@@ Line 301: / Line 301: @@
 |-
 | <code>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
 |-
 | <code>dram</code> || DRAM interface clock || 250 MHz
@@ Line 307: / Line 309: @@
 |-
 | <code>radio_2x</code> || Radio interface clock 2x || Twice the frequency of <code>radio</code>
 |}
@@ Line 318: / Line 343: @@
 |-
 | <code>ce</code> || Compute Engine clock || 266.667 MHz (available in UHD 4.6 and later)
 |-
 | <code>dram</code> || DRAM interface clock || 300 MHz

← Older revision		Revision as of 13:53, 9 October 2025
Line 526:		Line 526:

	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.		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.
		+
		+	=== Why does my build fail when I use a custom SystemVerilog package with in my RFNoC block? ===
		+
		+	One potential cause is due to the order of files in your block's Makefile.srcs. The SystemVerilog file with the package definition must be listed ''before'' any other module that imports the package. Otherwise, Vivado will fail with a "X is not declared" error during synthesis.

@@ Line 352: / Line 352: @@
 == Xilinx Vivado ==
-=== Do I need a Vivado license to build custom RFNoC FPGA images? ===
+=== 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 do I need? ===
+=== Which version and edition of Vivado should I install? ===
-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.
+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.
-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.
+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 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? ===
@@ Line 378: / Line 374: @@
 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? ===
+=== How do I get Vivado 2021.1 to work on Ubuntu 22.04 and later? ===
-The Vivado installer needs the libncurses5 and libtinfo5 libraries to run correctly. They can be installed by running the following commands:
+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
@@ Line 387: / Line 383: @@
   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 ==
@@ Line 520: / Line 526: @@
 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.

← Older revision		Revision as of 14:41, 1 October 2025
Line 548:		Line 548:
	$ sudo apt update		$ sudo apt update
	$ sudo apt install libncurses5		$ 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.

← Older revision		Revision as of 14:35, 1 October 2025
Line 520:		Line 520:

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

← Older revision		Revision as of 07:00, 23 July 2025
Line 377:		Line 377:

	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.		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 ==		== Building FPGA Images ==

← Older revision		Revision as of 18:41, 22 May 2025
Line 444:		Line 444:

	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.		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? ===		=== My FPGA build failed with a cryptic message or no message at all. How do I debug this? ===

@@ Line 409: / Line 409: @@
 It is possible to create a project file from the USRP build flow with the following steps:
-# Start the USRP FPGA build in the GUI by adding <code>GUI=1</code> to the <code>make</code> arguments. Example:<br/><code>make X410_X4_200 GUI=1</code>
+# 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:<br/><code>save_project_as project_name project_dir</code><br/>In this example, "project_name" is the name you want to give the project file and "project_dir" is the directory in which you want to put the project.
 # Set the compile order to automatic: <br/><code>set_property source_mgmt_mode All [current_project]</code>
 This project file can now be used independently of the normal FPGA build flow in UHD. It is up to the user to update this project file as the design changes since it will not be managed by the normal build flow in UHD.

@@ Line 254: / Line 254: @@
 |-
 | <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
 |-
 | <code>dram</code> || DRAM interface clock || 303.819 MHz
@@ Line 267: / Line 269: @@
 |-
 | <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
 |-
 | <code>dram</code> || DRAM interface clock || 303.819 MHz
@@ Line 295: / Line 299: @@
 |-
 | <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
 |-
 | <code>dram</code> || DRAM interface clock || 250 MHz
@@ Line 310: / Line 316: @@
 |-
 | <code>rfnoc_ctrl</code> || RFNoC Control clock || 40 MHz
 |-
 | <code>dram</code> || DRAM interface clock || 300 MHz

@@ Line 323: / Line 323: @@
 === 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.
-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]).
+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.
 == Xilinx Vivado ==