.. rst-class:: break_before 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? .. _troubleshooting-installation: Installation ------------ .. _troubleshooting-upgrade-v5: 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. .. code-block:: tcl 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 6. Close Vivado. 7. 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. 8. Rename the Vitis project directory to ``xibif``. For example, if your project is named ``MyProject``, rename ``hw/vitis/MyProject`` to ``hw/vitis/xibif``. 9. 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. 10. Run ``xibif build --fix-vitis`` to regenerate the Vitis project. **Confirm** the message that the user register file has changed. 11. Run ``xibif upgrade`` to update the source files to the latest version. 12. Verify and adjust project settings as needed by running ``xibif settings``. 13. 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.