/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`):

```bash
#!/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`.
  ```bash
  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:

```bash
# 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:

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

## Troubleshooting

| Issue | Cause | Solution |
| :--- | :--- | :--- |
| `bad interpreter` | Script uses CRLF line endings | Convert using `sed -i 's/\r$//'`. |
| `syntax error near (...)` | Windows PATH contains special characters | Export a stripped PATH: `export PATH="/usr/bin:/bin:$HOME/.local/bin"`. |
| `vivado not found` | Wrapper script not in PATH | Check if `echo $PATH` includes the script path. |
| `cmd.exe: command not found` | Missing Windows interoperability path | Use absolute path `/mnt/c/Windows/System32/cmd.exe`. |
| `file.v does not exist` | Incompatible TCL path format | Use `sed` to convert `/mnt/X/` to `X:/`. |

## Usage Example
Invoke directly from the WSL terminal:
```bash
vivado -version
```
Build Pynq-Z2 with LiteX:
```bash
python3 -m litex_boards.targets.tul_pynq_z2 --build
```