Skip to content

PCILeech Firmware Generator

CI codecov Python Version License

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
  1. Stage 1 (Host): Collects PCIe device data via VFIO
  2. Stage 2 (Container or Local): Generates firmware from collected data
  3. Stage 3 (Host): Runs Vivado through the generated build_all.tcl (optional; --templates-only stops 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

Build Process

Technical Reference

Troubleshooting

🎯 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 β†’