Resolve Issues with Generating and Loading Bitstreams

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, which can result in MATLAB® becoming unresponsive after you call the hdlsetuptoolpath function

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

  • Routing errors of type N2rt13HDRTExceptionE

If your bitstream build fails due to over-utilization of the available resources on the FPGA, or the bitstream build is successful 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 initiate end you encounter the error "Valid license was not found", run the Vivado License Manager and ensure 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

Ensure 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:

 Verify Vivado Installation

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 is not included by default on some Linux® distributions, 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, then libtinfo.so.5 is not present in the cache. To resolve this issue, you can create a symbolic link to the available library, libtinfo.so.6. The steps depend on whether you have sudo permissions.

 Create Symbolic Link on OS (Requires Root Privileges)

 Create Symbolic Link in Current MATLAB Session

Reduce Project Directory Path Length

If your bitstream build terminates prematurely with the error "make[1]: /bin/sh: Argument list too long", specify a project directory with a shorter path.

  1. Return to the Workflow Settings step.

  2. Update the Project Folder parameter. Specify an absolute path that is relatively short. For example, "/home/user/prj".

If a shorter project folder path is not sufficient to resolve the issue, you can try setting a support package root directory with a shorter path using the matlabshared.supportpkg.setSupportPackageRoot function. When you change the root folder, support packages installed in the new location become available on the MATLAB path. Any previously installed support packages are removed from the MATLAB path, but the files are still available.

Work Around Routing Error

You can encounter this sporadic routing error 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.
If you observe this error, make a non-functional change to your DUT or retry the build with a different build seed. For instructions, see Retry Build with Different Build Seed.

Retry Build with Different Build Seed

If you encounter build or timing failures and you cannot identify a reason for the failure, try building the bitstream with a different seed. You can trigger a change in build seed by making a non-functional 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 ... "

Prevent Out-of-Memory Failures

If the memory resources available to Vivado are inadequate, 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 has 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, try closing any other memory-intensive processes during the build. For details about how much memory is required to build bitstreams, see System Requirements.

See Also

Topics