Resolve Issues with Generating and Loading Bitstreams

R2026b
Since R2026a

Issue

The targeting workflow uses AMD® Vivado® design software to generate custom bitstreams for NI™ USRP™ radios. Failures or errors you can encounter while generating and loading bitstreams include:

  • Errors related to your Vivado version or license

  • Compatibility issues between Vivado and your host OS version

  • Missing Linux® build tools (gcc, patch) required by the RFNoC image builder

  • Errors due to a support package root path that is too long

  • Build failures, timing failures, or out-of-memory errors

  • Routing errors of type N2rt13HDRTExceptionE

  • Failures during base FPGA IP compilation

If your bitstream build fails due to over-utilization of the available resources on the FPGA, or the bitstream build succeeds but fails to achieve timing closure, see Reduce Resource Utilization and Achieve Timing Closure.

Possible Solutions

Verify Vivado License

If your bitstream build fails to start and you encounter the error "Valid license was not found", run the Vivado License Manager and verify that you have a valid license loaded.

Verify Vivado Installation

To build bitstreams using the targeting workflow, you must have Vivado development tools version 2021.1 and the AR76780 patch. To apply the patch, follow the instructions in the README file included with the patch download.

Note

Verify that you have installed Vivado version 2021.1. Version 2021.1.1 is not supported.

If you encounter issues with your Vivado installation, follow these steps to verify the version and patch:

  1. In a terminal, print the version information. Replace /opt/Xilinx/Vivado/2021.1 with the location of your Vivado installation directory.

    /opt/Xilinx/Vivado/2021.1/bin/vivado -version
    Verify that the output includes the correct version and patch numbers:
    v2021.1_AR76780

  2. If you used METHOD 1 outlined in the README file to extract the patch files in a subdirectory of the Vivado installation directory, verify that the directory structure is correct. From the Vivado installation directory, display the directory structure of the patches subdirectory. Replace /opt/Xilinx/Vivado/2021.1 with the location of your Vivado installation directory.

    tree -L 5 /opt/Xilinx/Vivado/2021.1/patches/

    Verify that the directory exists and that it has a subdirectory named AR76780 that contains the extracted patch files. For example:

    /opt/Xilinx/Vivado/2021.1/patches/
└── AR76780
    └── vivado
        ├── data
        │   ├── ip
        │   │   └── xilinx
        │   └── patches
        │       └── AR76780.dat
        └── patch_readme
            └── AR76780_Vivado_2021_1_preliminary_rev1.txt

8 directories, 2 files

Add Missing Legacy Library

If MATLAB® becomes unresponsive after you use the hdlsetuptoolpath (HDL Coder) function to configure the Vivado tool path, you might be missing the libtinfo.so.5 library. Vivado depends on the legacy library libtinfo.so.5, which some Linux distributions do not include by default, for example, Ubuntu® 24.04 and Debian® 13.

To confirm this library is missing, check the system's dynamic linker cache for versions of the libtinfo library. In a terminal, enter this command:

ldconfig -p | grep -E 'libtinfo\.so(\.5)?$'
If the only version returned is libtinfo.so.6, the cache does not contain libtinfo.so.5. To resolve this issue, you can create a symbolic link to the available library, libtinfo.so.6. The steps depend on whether you have root privileges.

If you have root privileges on your host computer, you can create a symbolic link to enable your system to use the available version of the library, libtinfo.so.6, when Vivado tries to use the unavailable legacy package.

  1. In a terminal, find the location of the libtinfo.so.6 library.

    ldconfig -p | grep libtinfo.so.6

  2. Create a symbolic link from the missing library libtinfo.so.5 to the available library libtinfo.so.6.

    sudo ln -s /usr/lib/x86_64-linux-gnu/libtinfo.so.6.0 /usr/lib/x86_64-linux-gnu/libtinfo.so.5

  3. Test that Vivado can start.

    vivado -help

You can apply a user-level workaround by creating a local symbolic link to enable MATLAB to use the available version of the library, libtinfo.so.6, when Vivado tries to use the unavailable legacy package. This option modifies the environment variables for the current MATLAB session only.

  1. In the MATLAB Command Window, find the location of the libtinfo.so.6 library.

    !ldconfig -p | grep libtinfo.so.6

  2. Create a local symbolic link from the missing library libtinfo.so.5 to the available library libtinfo.so.6.

    !ln -s /usr/lib/x86_64-linux-gnu/libtinfo.so.6 ./libtinfo.so.5

  3. Prepend the local folder to the MATLAB path for the current session.

    setenv('LD_LIBRARY_PATH', [pwd, ':', getenv('LD_LIBRARY_PATH')]);

  4. Test that Vivado can start.

    !vivado -help

Install Missing Build Tools

If the bitstream build fails with an error indicating that cc or patch is not found, your Linux system is missing build tools required by the RFNoC image builder. Most desktop Linux distributions include these tools by default, but minimal installations might not.

To resolve this issue, on Debian-based distributions, including Ubuntu, install the gcc and patch packages.

sudo apt install gcc patch

If your system does not provide a cc symlink after installing gcc, set the CC environment variable before starting MATLAB.

export CC=gcc

Reduce Support Package Root Path Length

If your bitstream build terminates prematurely with the error "make[1]: /bin/sh: Argument list too long", your support package root folder path is too long. Use the matlabshared.supportpkg.setSupportPackageRoot function to set a shorter support package root path. For example, "/home/user/sp". This function requires administrative privileges on the target folder and on matlabroot. After you change the root folder, reinstall support packages in the new location.

Prevent Out-of-Memory Failures

If the memory resources available to Vivado are insufficient, the process fails with an out-of-memory (OOM) error. To check for any OOM events, enter this code in a new terminal: 

# dmesg | grep -i -E 'killed process|oom'
If an OOM event occurred, the system returns log messages. For example:
[195173.733148] Killed process 26149 (vivado) total-vm:11582276kB, anon-rss:8889460kB, file-rss:0kB, shmem-rss:0kB
[195174.231579] oom_reaper: reaped process 26149 (vivado), now anon-rss:0kB, file-rss:0kB, shmem-rss:0kB

To resolve this issue, close any other memory-intensive processes during the build. For details about how much memory is required to build bitstreams, see System Requirements.

Work Around Routing Error

If your bitstream build fails with the following routing error, make a nonfunctional change to your DUT or retry the build with a different build seed. For instructions, see Retry Build with Different Build Seed. This sporadic error can occur when building a bitstream with Vivado version 2021.1.

ERROR: [Route 35-9] Router encountered a fatal exception of type 'N2rt13HDRTExceptionE' - 'Trying to tool lock on already tool locked arc
ERROR: [Common 17-39] 'route_design' failed due to earlier errors.

Retry Build with Different Build Seed

If you encounter build or timing failures and you cannot identify the cause, try building the bitstream with a different seed. You can trigger a change in build seed by making a nonfunctional change to your DUT, or you can set the BUILD_SEED environment variable in MATLAB before you start the bitstream build:

setenv('BUILD_SEED','101')
You can verify that the seed you set was used by inspecting the build log:
EXTRA_DEFS=" ... BUILD_SEED=101 ... "

Remove Prebuilt IP Directories

If the base FPGA IP compilation fails or is interrupted, the resulting files can remain in a locked or incomplete state, preventing later builds from completing. The workflow compiles the base FPGA IP the first time you build a bitstream for a given device type.

To resolve this issue, remove the prebuilt IP directories and retry the build.

ipDirs = dir(fullfile(getUHDInstallLocation,'glnxa64','fpga','usrp3','top','*','build-ip'));
ipDirs = unique({ipDirs.folder});
for i = 1:numel(ipDirs)
    rmdir(ipDirs{i},'s');
end
After you remove these directories, the next bitstream build regenerates the common IP.

See Also

Topics