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 via VFIO and generates unique PCILeech FPGA bitstreams.
Real Hardware Required
This tool requires a real donor PCIe device. Placeholder values are explicitly avoided - your firmware will be unique to your donor hardware.
π Quick Start
# Create virtual environment (required on modern Linux)
python3 -m venv ~/.pcileech-venv
source ~/.pcileech-venv/bin/activate
# Install with TUI support
pip install pcileechfwgenerator[tui]
# Add alias for running with sudo (add to ~/.bashrc)
alias pcileech-sudo='sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main'
# Load VFIO modules
sudo modprobe vfio vfio-pci
# Launch interactive TUI
pcileech-sudo tui
# Or use CLI directly
pcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1
For complete setup including IOMMU configuration, see the Installation Guide.
π 3-Stage Build Pipeline
PCILeech uses a host β container β host pipeline:
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β Stage 1 β β Stage 2 β β Stage 3 β
β HOST βββββΆβ CONTAINER βββββΆβ HOST β
β β β (or local) β β β
β VFIO Collection β β Templating β β Vivado Synth β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
Requires No VFIO Requires
hardware access Vivado
- Stage 1 (Host): Collects PCIe device data via VFIO
- Stage 2 (Container or Local): Generates firmware from collected data
- Stage 3 (Host): Runs Vivado through the generated
build_all.tcl(optional;--templates-onlystops after Stage 2). Routed timing, clock coverage, DRC and CDC checks must pass before the bitstream is written. See Build Gates
The container does NOT access VFIO - it only performs templating. See Host-Container Pipeline for details.
β¨ Key Features
- Donor Hardware Analysis: Extract real PCIe configurations via VFIO
- Full 4KB Config-Space Shadow: Complete configuration space in BRAM
- MSI-X Serving: The donor's MSI-X table and PBA are served from the donor's own BAR, including multi-BAR layouts. See MSI-X and Requester Support
- Requester Tracking: Tag tracking and completion timeouts for device-initiated reads (CaptainDMA 100T)
- Gated Stage 3 Builds: A bitstream is written only after timing, clock coverage, DRC and CDC checks pass
- Offline Captures: Collect once, render later without the donor (see the main repository README)
- Dynamic Device Capabilities: Automatic PCIe capability detection
- Interactive TUI: Guided workflow with real-time monitoring
- Containerized Builds: Isolated, reproducible Stage 2 templating
π Requirements
| Requirement | Details |
|---|---|
| OS | Linux only (Ubuntu 22.04+ recommended) |
| Python | 3.11 or higher |
| Hardware | Any PCIe device as donor |
| Optional | Podman (container builds), Vivado 2022.2 or newer (Stage 3) |
| Boards | Included in the pip package. A source checkout needs git clone --recurse-submodules |
π Documentation
Getting Started
- Installation Guide - Complete setup instructions
- Quick Start - Generate your first firmware
- Build Walkthrough - A full annotated build
- Vivado Setup - Vivado edition, version and errors
Build Process
- Host-Container Pipeline - Understanding the 3-stage flow
- Container Builds - Container configuration
- Build Gates - What Stage 3 checks before writing a bitstream
- MSI-X and Requester Support - What the firmware serves and its limits
Technical Reference
- Config Space Shadow - PCIe config space emulation
- Template Architecture - Firmware generation system
- Dynamic Capabilities - PCIe capability handling
Troubleshooting
- Troubleshooting Guide - Common issues and solutions
- Device Cloning - Cloning workflow details
π― Use Cases
- Security Research: PCIe/DMA security testing
- Education: PCIe protocol learning, FPGA development
- Development: Driver development, hardware debugging
π‘οΈ Responsible Use
Legal Compliance
This tool is for legitimate security research, education, and development. Users must ensure compliance with all applicable laws. Only use on systems you own or have permission to test.
π License
MIT License - see LICENSE.
Ready? Start with the Installation Guide β