Troubleshooting

Build failures

Check the following if the project fails to build or generate a bitstream:

  1. Are you using the correct version of Vivado for this version of the repository? Check the version specified in the Requirements section of the README.md file.

  2. Did you follow the build instructions ? If it still doesn’t build, please let us know and provide details of your setup and the error message(s).

  3. libhailort / hailortcli fail at do_configure with a CA-cert path under /usr/local/oe-sdk-hardcoded-buildpath/.... This is the PetaLinux 2025.2 eSDK git-native CA-bundle relocation issue. Apply the one-time sudo symlink described in Build issue and workaround. PetaLinux/Makefile runs a check_ca_workaround prerequisite that prints the same fix if you haven’t applied it yet.

  4. bitbake petalinux-image-minimal failed with _setscene Fetcher failure errors. Transient public sstate mirror 404s. Re-run the same make petalinux TARGET=<board> command; the second attempt finds the packages in the local sstate cache populated by the first run.

Boot-time issues

SD init fails with -110 on ZCU104

The Vivado design for this repo (and other Opsero ZynqMP designs) exports a minimal sdhci1 node into the XSA. The 2025.2 PetaLinux device-tree generator does not fill in the bus-width / clock-frequency / voltage properties this controller needs, and Linux times out with -110 during SD card init. The ZCU104 BSP adds an explicit sdhci1 override block in system-user.dtsi that restores the properties the stock AMD ZCU104 BSP carries. If you forked the BSP, copy that block over.

hailo driver WARN_ON in find_vma() (kernel ≥ 6.5)

The HailoRT v4.23 hailo_pci driver calls find_vma() without holding mmap_lock, which kernel 6.5+ asserts on. The repo applies the same patch that Hailo shipped on its v5.3-hotfix branch — see PetaLinux/bsp/<board>/project-spec/meta-user/recipes-kernel/hailo-pci/. If you see the WARN_ON, confirm the bbappend’s do_compile:prepend() hook ran (it logs Applying hailo-pci mmap_lock patch for kernel >= 6.5).

Black screen on DisplayPort

The 2025.2 v_mix → DPSUB display pipeline requires xlnx_mixer.connect_drm_bridge=1 on the kernel command line. All BSPs in this repo set it via CONFIG_SUBSYSTEM_USER_CMDLINE. If you override the cmdline in a fork, ensure that flag is preserved or the mixer probe will not bring the bridge up.

Monitor resolution limited to 1080p

If using a 2K resolution DisplayPort monitor with the UltraZed EV carrier, you may find that it can only be used at 1080p or less resolution. This is due to the fact that the UltraZed EV carrier has only a single lane connected to the DisplayPort connector, and not all DisplayPort monitors are able to support resolutions of 1080p and higher over a single lane.