Skip to content

Installation Guide

This guide will walk you through installing the PCILeech Firmware Generator on your system.

System Requirements

Operating System

  • Linux: Ubuntu 20.04+ (recommended), Debian 11+, RHEL 8+, or similar
  • Python: 3.8 or higher
  • Memory: 4GB RAM minimum, 8GB recommended for complex devices
  • Storage: 2GB free space for FPGA tools and generated firmware

Hardware Requirements

  • FPGA Development Board: Supported Xilinx board (see Supported Devices)
  • Donor PCIe Device: Any standard PCIe device for configuration extraction
  • USB-JTAG Programmer: For optional FPGA programming (Xilinx Platform Cable or compatible)

Installation Methods

# Install the latest stable release
pip install pcileech-fw-generator

# Verify installation
pcileech --version

Method 2: Install from Source

# Clone the repository
git clone https://github.com/ramseymcgrath/PCILeechFWGenerator.git
cd PCILeechFWGenerator

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Or install normally
pip install .

Method 3: Container (optional)

A Containerfile is provided primarily for CI and for creating a reproducible runtime image. You do not need to build or run the container to use the generator for VFIO-based workflows — prefer installing from PyPI or running from source as shown in Methods 1 and 2.

Important notes:

  • The kernel module and any kernel-linked helpers (for donor dumping) must be built on the host kernel and cannot be reliably built or loaded from inside the container. See src/donor_dump/Makefile for host build instructions.
  • The container is optional. It is intended for CI and reproducible runtimes only; it is not required for normal development or hardware access.

If you are using CI or need a reproducible image, you may still build the container locally; do not assume the image will be pulled from a public registry. Building or running the image is strictly optional and not required for VFIO workflows.

VFIO Setup

The generator requires VFIO drivers to access donor devices. Here's how to set them up:

1. Enable IOMMU

Add to your kernel command line (usually in /etc/default/grub):

# For Intel CPUs
GRUB_CMDLINE_LINUX="intel_iommu=on iommu=pt"

# For AMD CPUs
GRUB_CMDLINE_LINUX="amd_iommu=on iommu=pt"

Update GRUB and reboot:

sudo update-grub
sudo reboot

2. Load VFIO Modules

# Load required modules
sudo modprobe vfio-pci
sudo modprobe vfio-iommu-type1

# Make persistent (add to /etc/modules)
echo "vfio-pci" | sudo tee -a /etc/modules
echo "vfio-iommu-type1" | sudo tee -a /etc/modules

3. Bind Device to VFIO

Find your device:

# List PCIe devices
lspci -nn

# Example output:
# 01:00.0 Ethernet controller [0200]: Intel Corporation 82599ES [8086:10fb]

Bind to VFIO:

# Replace with your device ID and vendor:device codes
echo "8086 10fb" | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id
echo "0000:01:00.0" | sudo tee /sys/bus/pci/devices/0000:01:00.0/driver/unbind
echo "0000:01:00.0" | sudo tee /sys/bus/pci/drivers/vfio-pci/bind

Xilinx Vivado Setup (Optional)

For FPGA synthesis and programming, install Xilinx Vivado:

1. Download Vivado

  • Visit Xilinx Downloads
  • Download Vivado ML Edition (2020.1 or later)
  • Choose WebPACK (free) or Standard/Enterprise edition

2. Install Vivado

# Extract and run installer
tar -xvf Xilinx_Unified_*.tar.gz
cd Xilinx_Unified_*/
sudo ./xsetup

3. Setup Environment

Add to your ~/.bashrc or ~/.zshrc:

# Xilinx Vivado
source /opt/Xilinx/Vivado/2023.1/settings64.sh  # Adjust version
export PATH=$PATH:/opt/Xilinx/Vivado/2023.1/bin

USB-JTAG Driver Setup (Optional)

For programming FPGAs via USB-JTAG:

1. Install Cable Drivers

# For Xilinx Platform Cable
cd /opt/Xilinx/Vivado/2023.1/data/xicom/cable_drivers/lin64/install_script/install_drivers
sudo ./install_drivers

# For Digilent cables
wget https://github.com/Digilent/digilent.adept.runtime/releases/download/v2.27.9/digilent.adept.runtime_2.27.9-amd64.deb
sudo dpkg -i digilent.adept.runtime_2.27.9-amd64.deb

2. Setup udev Rules

Create /etc/udev/rules.d/52-xilinx-ftdi-usb.rules:

# Xilinx USB cables
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", GROUP="plugdev"

# Digilent cables
SUBSYSTEM=="usb", ATTRS{idVendor}=="1443", GROUP="plugdev"

Reload udev rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Verification

Verify your installation:

# Check basic installation
pcileech --help

# Check VFIO access (requires bound device)
lspci -Dnn

# Check Vivado integration (if installed)
pcileech check

# Run self-test
pcileech check --self-test

Troubleshooting

Common Issues

Permission Denied

# Add user to vfio group
sudo usermod -a -G vfio $USER

# Add user to plugdev group (for USB-JTAG)
sudo usermod -a -G plugdev $USER

# Logout and login again

IOMMU Not Available

# Check IOMMU status
dmesg | grep -i iommu

# Verify kernel command line
cat /proc/cmdline

Device Not Found

# Check device binding
ls -la /sys/bus/pci/drivers/vfio-pci/

# Check IOMMU groups
find /sys/kernel/iommu_groups/ -type l

Vivado Not Found

# Check Vivado installation
which vivado

# Source Vivado settings
source /opt/Xilinx/Vivado/*/settings64.sh

Getting Help

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Review the FAQ
  3. Search existing GitHub Issues
  4. Join our Discord Community
  5. Create a new issue with detailed logs and system information

Next Steps

Once installation is complete:

  1. Quick Start Guide: Generate your first firmware
  2. Device Cloning: Learn about device extraction
  3. Development Guide: Contributing to the project

Ready to generate firmware? Continue to the Quick Start Guide!