Troubleshooting
Common issues and solutions.
Environment Setup
Vivado Not Found
Symptom: vivado: command not found
Solution:
source /opt/Xilinx/Vivado/2025.1/settings64.sh
# Make permanent
echo 'source /opt/Xilinx/Vivado/2025.1/settings64.sh' >> ~/.bashrc
Python Import Errors
Symptom: ModuleNotFoundError: No module named 'litex'
Solution:
pip3 install --user litex litex-boards
export PATH=$HOME/.local/bin:$PATH
USB Permission Denied
Symptom: Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
Solution:
# Temporary
sudo chmod 666 /dev/ttyUSB*
# Permanent
sudo usermod -a -G dialout $USER
# Logout and login
Build Errors
Synthesis Fails - Timing
Symptom:
CRITICAL WARNING: Timing constraints are not met
WNS: -1.234ns
Solution:
Reduce clock frequency:
# LiteX
python3 vcu118.py --sys-clk-freq=80e6 # Was 100e6
Out of Memory
Symptom: Build crashes, system freezes
Solution:
# Limit parallel jobs
export MAKEFLAGS="-j2"
# Increase swap
sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
License Error
Symptom: License checkout failed
Solution:
# Check license
echo $XILINXD_LICENSE_FILE
# Or run license manager
vlm &
For VCU-118, you need Standard edition license (eval or purchased). WebPACK doesn’t support Ultrascale+.
Missing FPGA Part
Symptom: Part xcvu9p not found
Solution:
Re-run installer to add Ultrascale+ device support:
sudo /opt/Xilinx/Vivado/2025.1/xsetup
FPGA Programming
Cable Not Detected
Symptom: No devices detected
Solution:
- Check USB connection:
lsusb | grep Xilinx
- Install cable drivers:
cd /opt/Xilinx/Vivado/2025.1/data/xicom/cable_drivers/lin64/install_script/install_drivers
sudo ./install_drivers
- WSL users - USB passthrough:
usbipd list
usbipd attach --wsl --busid X-X
Programming Fails
Symptom: Programming failed at 30%
Solution:
- Check power supply to board
- Verify correct .bit file for board
- Try lower JTAG frequency:
openocd -c "adapter speed 1000" -f board/vcu118.cfg
Serial Console
No Output
Symptom: Screen is blank after programming
Solution:
- Check baud rate:
screen /dev/ttyUSB1 115200 # Not 9600
- Check correct USB port:
ls -l /dev/ttyUSB*
# Usually ttyUSB0 = JTAG, ttyUSB1 = UART
- Check FPGA programmed:
- Look for LEDs on board
- Run
lsusb, should show Xilinx device
- Try reset:
- Press reset button on board
- Power cycle
Garbled Output
Symptom: Random characters
Solution:
Clock frequency mismatch. Check UART clock divider matches system clock.
Boot Issues
Linux Kernel Panics
Symptom:
Kernel panic - not syncing: VFS: Unable to mount root fs
Solution:
- Check device tree:
dtc -I dtb -O dts microwatt.dtb | grep memory
- Verify initrd:
file rootfs.cpio.gz
# Should be gzip compressed
- Check bootargs:
console=ttyS0,115200 root=/dev/ram0
Hangs at Boot
Symptom: Boot stops at “Starting kernel…”
Solution:
- Enable early printk in kernel config
- Check memory controller initialization
- Verify DDR4 timing constraints
LiteX Specific
Build Fails - Yosys
Symptom: Yosys not found
Solution:
cd ~/litex
./litex_setup.py --install --user
SoC Build Fails - Missing Board
Symptom: Board vcu118 not found
Solution:
pip3 install --user --upgrade litex-boards
Performance Issues
WSL Builds Slow
Symptom: Build takes 3x longer than expected
Solution:
Move project to WSL filesystem:
# Bad (slow)
cd /mnt/c/Users/name/projects
# Good (fast)
cd ~/projects
File I/O across WSL/Windows boundary is slow.
Vivado GUI Sluggish
Symptom: Vivado GUI freezes, slow
Solution:
- Use batch mode when possible:
vivado -mode batch -source build.tcl
- Resource limits:
Ensure WSL has enough RAM (see
.wslconfig)
Getting Help
Still stuck?
- Check logs:
cat build/*/vivado.log
- Community:
- Matrix: #powercommons:matrix.org
- Codeberg: codeberg.org/PowerCommons
- Upstream:
- Microwatt: github.com/antonblanchard/microwatt
- LiteX: github.com/enjoy-digital/litex/wiki
- Vivado: xilinx.com/support
- Provide details:
- OS and version
- Vivado version
- Complete error log
- Steps to reproduce