wsl-vivado

name: wsl-vivado description: Guide on how to invoke Windows Vivado toolchain from WSL environment using wrapper scripts for cross-platform FPGA development and building.

WSL-Vivado Cross-Platform Integration Skill

Introduction

This skill provides a configuration scheme to run development frameworks (such as LiteX, Cocotb, etc.) in a Linux/WSL environment while utilizing native Windows Vivado for synthesis, implementation, and bitstream loading.

Core Configuration Flow

1. Locate Windows Vivado Path

Confirm the full path of vivado.bat on the Windows side.

• Example: D:/Xilinx/Vivado/2018.3/bin/vivado.bat

2. Create WSL Wrapper Script

Create a wrapper script in the WSL terminal (recommended path: ~/.local/bin/vivado):

#!/bin/bash
# Call Windows Vivado and forward all arguments
# Note: Use absolute path for cmd.exe to avoid PATH conflicts
/mnt/c/Windows/System32/cmd.exe /c "D:/Xilinx/Vivado/2018.3/bin/vivado.bat" "$@"

[!CAUTION] Line Ending Warning: The script must use LF (Linux) line endings. If created in Windows and copied to WSL, fix it using the following command in WSL: sed -i 's/\r$//' /path/to/wrapper

3. Set Permissions and Environment

• Grant execution permission: chmod +x ~/.local/bin/vivado
• Update PATH: Ensure the directory containing the wrapper script is at the front of your PATH.

  export PATH="$HOME/.local/bin:$PATH"
  

4. Path Compatibility Notes

• Mount Points: Attempt to develop under Windows mount directories such as /mnt/c/ or /mnt/d/ to ensure Windows tools can directly access the files.
• LiteX Installation: It is strongly recommended to install LiteX in a shared directory (e.g., /mnt/d/litex) instead of an internal WSL path (e.g., /home/user/litex).

5. TCL Path Conversion (Crucial!)

Vivado TCL scripts generated by frameworks like LiteX use /mnt/d/... format paths, which Windows Vivado cannot recognize. They must be converted before running:

# Convert /mnt/d/ to D:/ format
sed -i 's|/mnt/d/|D:/|g' /mnt/d/litex/build/*/gateware/*.tcl
sed -i 's|/mnt/c/|C:/|g' /mnt/c/project/build/*/gateware/*.tcl

6. PYTHONPATH Option (Optional)

If you don't want to reinstall Python packages, you can redirect them via environment variables:

export PYTHONPATH=/mnt/d/litex/litex:/mnt/d/litex/litex-boards:/mnt/d/litex/migen:/mnt/d/litex/pythondata-cpu-vexriscv

Troubleshooting

Usage Example

Invoke directly from the WSL terminal:

vivado -version

Build Pynq-Z2 with LiteX:

python3 -m litex_boards.targets.tul_pynq_z2 --build