PCILeech Firmware Generator

Generate authentic PCIe DMA firmware from real donor hardware using a 3-stage host-container-host pipeline. This tool extracts donor configurations from a local device via VFIO and generates unique PCILeech FPGA bitstreams.

Warning

This tool requires real hardware. The templates are built using the device identifiers directly from a donor card and placeholder values are explicitly avoided. Using your own donor device ensures your firmware will be unique.

Build Pipeline

The generator uses a 3-stage pipeline:

Stage 1 (Host): Collects PCIe device data via VFIO on the host
Stage 2 (Container or Local): Generates firmware artifacts from collected data (no VFIO access in container)
Stage 3 (Host): Runs Vivado synthesis on the host (optional)

The container does NOT access VFIO devices - it only performs templating using pre-collected data. See Host-Container Pipeline for details.

Key Features

Donor Hardware Analysis: Extract real PCIe device configurations and register maps from live hardware via VFIO
Overlay-Only Architecture: Generate device-specific .coe configuration files that integrate with upstream pcileech-fpga HDL modules
Dynamic Device Capabilities: Generate realistic network, storage, media, and USB controller capabilities with pattern-based analysis
Full 4KB Config-Space Shadow: Complete configuration space emulation with BRAM-based overlay memory
MSI-X Table Replication: Exact replication of MSI-X tables from donor devices with interrupt delivery logic
Unified Context Building: Centralized template context generation ensuring consistency across all output files
Active Device Interrupts: MSI-X interrupt controller with timer-based and event-driven interrupt generation
Interactive TUI: Modern Textual-based interface with real-time device monitoring and guided workflows
Containerized Build Pipeline: Podman-based synthesis environment with automated VFIO setup
USB-JTAG Flashing: Direct firmware deployment to DMA boards via integrated flash utilities

For complete setup including IOMMU configuration, see the Installation Guide.

Requirements

Python ≥ 3.11
Donor PCIe card (any inexpensive NIC, sound, or capture card)
Linux OS with VFIO support (required for Stage 1 data collection)

Optional Requirements

Podman or Docker - For isolated Stage 2 templating (container does NOT access VFIO)
DMA board - pcileech_enigma_x1, pcileech_75t484_x1, pcileech_35t325_x4, or pcileech_100t484_x1
Vivado - 2022.2+ for bitstream synthesis (Stage 3)
bpftrace - For advanced MMIO learning (sudo apt install bpftrace)

Web GUI (Point-and-Click Interface)

The Web GUI provides a beginner-friendly interface for the entire firmware generation workflow:

# From repository checkout
cd PCILeechFWGenerator
sudo python3 gui/app.py

Then open http://localhost:5000 in your browser.

Web GUI Features:

Visual device selection (shows all VFIO-bound PCIe devices)
Board selection with 15+ supported variants
One-click build with real-time progress
Automatic container-based firmware generation
Vivado integration for complete .bin generation

Web GUI Workflow

Bind your donor device to VFIO (see VFIO Setup below)
Select your donor device from the dropdown
Choose your target board (e.g., pcileech_enigma_x1)
Click Build - the tool will:
- Collect device data via VFIO (Stage 1)
- Generate firmware in container (Stage 2)
- Run Vivado synthesis (Stage 3)
Get your .bin file in the output directory

VFIO Setup (Critical First Step)

VFIO passthrough is required to read your donor device's configuration. This section covers common issues and solutions.

Enable IOMMU in BIOS/GRUB

Enable in BIOS: Look for "VT-d" (Intel) or "AMD-Vi" (AMD) and enable it

Add kernel parameters (edit /etc/default/grub):

# Intel systems:
GRUB_CMDLINE_LINUX_DEFAULT="intel_iommu=on iommu=pt"

# AMD systems:
GRUB_CMDLINE_LINUX_DEFAULT="amd_iommu=on iommu=pt"

Update GRUB and reboot:
```
sudo update-grub
sudo reboot
```

Verify IOMMU is enabled:

dmesg | grep -i iommu
# Should show "IOMMU enabled" or similar

Load VFIO Modules

# Load modules (run every boot, or add to /etc/modules)
sudo modprobe vfio
sudo modprobe vfio_pci
sudo modprobe vfio_iommu_type1

# Verify modules loaded
lsmod | grep vfio

Bind Device to VFIO

# Find your donor device
lspci -nn | grep -i ethernet  # or network, audio, etc.
# Example output: 05:00.0 Ethernet controller [0200]: Realtek ... [10ec:8161]

# Get the device's IOMMU group
ls /sys/bus/pci/devices/0000:05:00.0/iommu_group/devices/
# Note: ALL devices in the same group must be unbound

# Unbind from current driver
echo "0000:05:00.0" | sudo tee /sys/bus/pci/devices/0000:05:00.0/driver/unbind

# Bind to vfio-pci (replace 10ec 8161 with YOUR vendor:device IDs)
echo "10ec 8161" | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id

Common VFIO Binding Issues

"Device or resource busy"

Another driver is using the device. Unbind it first:

echo "0000:05:00.0" | sudo tee /sys/bus/pci/devices/0000:05:00.0/driver/unbind

"No such file or directory" for driver/unbind

Device has no driver bound. Try binding directly:

echo "10ec 8161" | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id

"IOMMU group has other devices"

All devices in an IOMMU group must be bound to vfio-pci or have no driver:

# List all devices in the group
ls /sys/bus/pci/devices/0000:05:00.0/iommu_group/devices/
# Unbind each device that has a driver

"vfio: No such device"

The vfio-pci module isn't loaded:

sudo modprobe vfio_pci

Permission denied accessing /dev/vfio/*

Run with sudo or add your user to the vfio group:

sudo usermod -aG vfio $USER
# Then log out and back in

Verify VFIO Binding

# Check device is bound to vfio-pci
ls -la /sys/bus/pci/devices/0000:05:00.0/driver
# Should show: driver -> ../../../bus/pci/drivers/vfio-pci

# Check VFIO device exists
ls /dev/vfio/
# Should show your IOMMU group number (e.g., "19")

Container Setup (For Stage 2)

The container handles firmware generation (Stage 2) without needing VFIO access:

# Build the container image
podman build -t pcileech-fwgen -f Containerfile .

# Or with Docker
docker build -t pcileech-fwgen -f Containerfile .

The Web GUI and CLI automatically use the container if available.

Rebuilding the Container

If you pull updates, rebuild the container:

git pull
podman rmi pcileech-fwgen
podman build -t pcileech-fwgen -f Containerfile .

CLI Commands

# Interactive TUI (recommended for first-time users)
pcileech-sudo tui

# Full 3-stage build pipeline
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1

# Stage 1 only (collect device data, no templating)
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1 --host-collect-only

# Force local mode for Stage 2 (skip container)
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1 --local

# Full build with Vivado synthesis (Stage 3)
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1 \
    --vivado-path /tools/Xilinx/2025.1/Vivado --vivado-jobs 8 --vivado-timeout 7200

# Check VFIO configuration
pcileech-sudo check --device 0000:03:00.0

# Flash firmware to device (after Vivado synthesis produces .bit file)
pcileech-sudo flash pcileech_datastore/output/*.bit --board pcileech_35t325_x1

# Show version information (doesn't need sudo)
pcileech version

Version Updates

The tool automatically checks for newer versions during CLI builds. You can:

Disable automatic checks: set PCILEECH_DISABLE_UPDATE_CHECK=1
Show current version: pcileech version

Development from Repository

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

# Initialize submodule (only needed for local development, NOT for container builds)
git submodule update --init --recursive

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# From a dev checkout you can still run the root script
sudo -E python3 pcileech.py tui

Note for developers: When working from a git checkout for local development, you must clone with --recurse-submodules or run git submodule update --init --recursive after cloning. The lib/voltcyclone-fpga submodule contains FPGA board definitions and synthesis templates.

Note for container users: The container (used only for Stage 2 templating) automatically clones the voltcyclone-fpga repository during image build. The container does NOT access VFIO - it only generates firmware from pre-collected device data.

Note for pip users: The voltcyclone-fpga submodule contents are bundled automatically in pip distributions, so no additional steps are needed.

Troubleshooting

Having issues? Check our comprehensive Troubleshooting Guide which covers:

VFIO Setup Issues - IOMMU configuration, module loading, device binding
Installation Problems - Virtual environment setup, Python 3.12+ issues
BAR Detection Issues - Power state problems, device compatibility
Locked IP Cores - Vivado licensing and IP regeneration

Common Issues

"externally-managed-environment" Error

You must use a virtual environment on modern Linux:

python3 -m venv ~/.pcileech-venv
source ~/.pcileech-venv/bin/activate
pip install pcileechfwgenerator[tui]

"ModuleNotFoundError: No module named 'textual'"

Install with TUI support:

pip install pcileechfwgenerator[tui]

"Permission denied" / VFIO Errors

Use the venv's Python with sudo:

sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech tui

Quick Diagnostic

pcileech-sudo check --device 0000:03:00.0 --interactive

Direct Documentation Links

Installation Guide - Complete installation instructions
Quick Start Guide - Get started in minutes
Host-Container Pipeline - Understanding the 3-stage build flow
Container Builds - Container configuration and troubleshooting
Troubleshooting Guide - Comprehensive troubleshooting and diagnostic guide
Device Cloning Process - Complete guide to the cloning workflow
Firmware Uniqueness - How authenticity is achieved
Manual Donor Dump - Step-by-step manual extraction
PCILeech Configuration - Key configuration parameters explained
Development Setup - Contributing and development guide
TUI Documentation - Interactive interface guide
Config space info - Config space shadow info

Output Files

After a successful build, artifacts are placed in the datastore (default: pcileech_datastore/):

pcileech_datastore/
├── device_context.json       # Stage 1: Collected device data
├── msix_data.json            # Stage 1: MSI-X capability data
└── output/
    ├── pcileech_top.sv       # Top-level SystemVerilog module
    ├── device_config.sv      # Device configuration module
    ├── config_space_init.hex # Configuration space initialization (BRAM)
    ├── *.tcl                 # Vivado project/build scripts
    └── *.bit                 # Bitstream (only after Stage 3 Vivado synthesis)

Cleanup & Safety

Rebind donors: Use TUI/CLI to rebind donor devices to original drivers
Keep firmware private: Generated firmware contains real device identifiers
Use isolated build environments: Never build on production systems

Important

This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.

Docs

Docs are managed in the site repo and served by cloudflare.

Acknowledgments

PCILeech Community: For feedback and contributions
@Simonrak for the writemask implementation

License

This project is licensed under the Apache License - see the LICENSE file for details.

Legal Notice

AGAIN This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.

Security Considerations:

Never build firmware on systems used for production or sensitive operations
Use isolated build environments (Seperate dedicated hardware)
Keep generated firmware private and secure
Follow responsible disclosure practices for any security research
Use the SECURITY.md template to raise security concerns

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
PCILeechFWGenerator		PCILeechFWGenerator
attached_assets		attached_assets
.replit		.replit
README.md		README.md
main.py		main.py
pyproject.toml		pyproject.toml
replit.md		replit.md
uv.lock		uv.lock
zipFile.zip		zipFile.zip

restneeded/FWGen-WebGUI

Folders and files

Latest commit

History

Repository files navigation