Troubleshooting Guide

This section is dedicated to common road bumps or problems while using XiBIF.

Project Building

Invalid Path to Xilinx Executable

It may occur that a non-existing path to a Xilinx executable is given/entered into the .xibif file. Naturally, the executables are not found and the program terminates.

Linker Script Path

When a version of XiBIF prior to 4.1 is used to create a project, the linker script path in Vitis is not given relative to the project but as an absolute path. When a project is moved, this path does not change and thus the linker script cannot be found.

Vitis cannot find fsbl.elf

Aaaah, Vitis is a really well written piece of software, isn’t it? Failure to find an fsbl.elf file (the bootloader) usually comes from parts of the project having a path that is too long. Vitis generates deeply nested directories, so even if you are only a few folders deep, it may fail.

The easiest fix for this issue is to move the project further upwards in the directory tree.

Connection Issues

Zybo Phy Setup Error

When using a Zybo board with Revision D, you might encounter an error during the phy setup phase of the Ethernet connection. This is due to a software bug in the Ethernet driver provided by Xilinx. XiBIF version 5.0.0 and later contains a workaround for this issue.

100 MBit Ethernet Connection not Working

Xilinx introduced a bug in the 2023.1 release of Vitis where the 100 MBit (and 10 MBit) Ethernet connection does not work anymore. A workaround was introduced in version 4.5.2 of XiBIF. If you are using an older version, only 1 GBit connections will work.

USB-to-Ethernet Bug

The Windows driver for some USB-to-Ethernet adapters seems to have a bug when used on a USB 3.x port. If you experience an unstable connection, try a USB 2.0 port.

Enabling I- and D-Cache

Sometimes it can occur that an application using the streaming feature crashes for no apparent reason. We suspect this is a software bug on Vitis side. It can sometimes be fixed by uncommenting the Disable I- and D-cache statements in the main.c file.

Firewall

XiBIF communicates over the network port 6 & 7. Additionally, the hardware server from Xilinx requires the port 3121 to be open.

Ensure that your firewall allows communication over these ports.

No Response from FPGA

  • Check the IP Settings: Ensure the computer and XiBIF board have the correct IP addresses.

  • Network Adapter: Ensure the Ethernet adapter is enabled and properly connected.

  • Firewall Issues: Temporarily turn off any firewalls or security software that might block the connection.

  • WSL: If you are using Windows Subsystem for Linux, the network interfaces to your computer are unreachable from Linux by default. You must manually add the network route to your computer’s routing table.

Streaming Issues

No AXI Stream Data

Consider the following questions when you are unable to receive data over the stream interface.

  • Is the Stream source actually producing data?

  • Are the AXI-Stream signals set correctly? Can you prove it in a simulation?

  • Are there other AXI-Stream sources that might block your data from arriving?

  • Is the design that you are simulating actually loaded onto the FPGA?

Installation

Upgrade to version 5.0.0

XiBIF 5.0.0 introduces breaking changes, so upgrading existing projects is not supported automatically. To upgrade, apply the following manual steps:

  1. Create a backup of your project file .xibif before making any changes. Note that this file might be hidden in your file explorer, so ensure that you have enabled the option to show hidden files.

  2. Create a new project with XiBIF version 5.0.0 using the xibif new command in a temporary location. Use the same name, board, and Xilinx version as your existing project. If you are unsure about any settings, you can open the .xibif file of your existing project and check the settings with a text editor.

  3. Copy the .xibif file from the temporary project to your existing project. Overwrite the existing project file.

  4. Switch to the existing project directory and run xibif start vivado. Wait until Vivado has started before continuing.

  5. Execute the following tcl-commands in the Vivado Tcl Console. Copy and execute them line by line as Vivado somehow does not like them to be executed in a group. This will rename the block design to xibif_bd and regenerate the wrapper file.

set old_bd_name [open_bd_design [get_files *.bd]]
set new_bd_path [save_bd_design_as xibif_bd]
close_bd_design $old_bd_name
add_files -norecurse $new_bd_path
make_wrapper -files [get_files -quiet xibif_bd.bd] -top -import -force
generate_target all [get_files -quiet xibif_bd.bd]
set_property top xibif_bd_wrapper [current_fileset]
set old_bd_files [get_files -quiet "*${old_bd_name}.bd"]
remove_files $old_bd_files
file delete -force $old_bd_files
set old_bd_files [get_files -quiet "*${old_bd_name}_wrapper.vhd"]
remove_files $old_bd_files
file delete -force $old_bd_files

  1. Close Vivado.

  2. Download the file config-regs and copy it to the folder hw/regs/ in your project. If you already have a file named config-regs in that folder, you can skip this step.

  3. Rename the Vitis project directory to xibif. For example, if your project is named MyProject, rename hw/vitis/MyProject to hw/vitis/xibif.

  4. Build the Vivado project with xibif build --to vivado:export. This will generate the required files for the next step. Confirm the message that the user register file has changed.

  5. Run xibif build --fix-vitis to regenerate the Vitis project. Confirm the message that the user register file has changed.

  6. Run xibif upgrade to update the source files to the latest version.

  7. Verify and adjust project settings as needed by running xibif settings.

  8. Remove the backup of the .xibif file that you created in step 1 and the temporary project that you created in step 2.

Cannot update beyond 4.1.0

Most of the time when updating via PIP does not work as expected, it is due to a missing dependency. For v4.1.0 specifically, we added support for a custom tool for testbench generation called hdltbgen. When this tool is missing, installing a newer version is not possible.

Use pip install hdltbgen to install the tool.