PCILeechGen on GitHub (sercanarga/PCILeechGen)

PCILeechGen README

PCILeechGen

Custom firmware generator for PCILeech FPGA boards. Reads a real PCI/PCIe donor device through VFIO, clones its identity (config space, BARs, capabilities), and builds a ready-to-flash .bin bitstream via Vivado.

Discord Community: https://discord.gg/kcWVCAhNSg

WARNING: FOR EDUCATIONAL AND RESEARCH USE ONLY *

This tool is provided for educational and research purposes only. The *
authors do not condone cheating, anti-cheat circumvention, or any use that *
violates terms of service. Users are responsible for compliance with all *
applicable laws and agreements. *

SPECIAL THANKS

FTWDMA Sponsorship https://ftwdma.com Ozempic Sponsorship, generous contributor https://github.com/fiticod Santiago NVMe and firmware contributions https://github.com/sgorm0 TrueTuring Sponsorship, NVMe and xHCI fixes https://github.com/TrueTuring CaptainDMA Sponsorship https://captaindma.com pcileech-fpga The FPGA framework this project builds upon https://github.com/ufrisk/pcileech-fpga

PREREQUISITES

Go 1.26+
Linux with IOMMU/VFIO enabled
Vivado 2023.2 (for synthesis)

VFIO needs IOMMU enabled in BIOS and in the kernel parameters (intel_iommu=on or amd_iommu=on).

HOW IT WORKS

scan -> check -> build -> flash

scan enumerate PCI devices, detect VFIO status check validate the donor device, read config space and BARs build clone identity -> generate SV/COE/TCL -> Vivado synthesis -> .bin flash write the bitstream to the FPGA board

The donor device is read through VFIO; its config space, BARs and capabilities are cloned, scrubbed, and compiled into ready-to-flash firmware. Run the stages in order.

QUICK START

git clone --recurse-submodules https://github.com/sercanarga/PCILeechGen.git cd PCILeechGen && make build

sudo ./bin/pcileechgen scan sudo ./bin/pcileechgen check --bdf 0000:02:00.0 sudo ./bin/pcileechgen build --bdf 0000:02:00.0 --board CaptainDMA_100T

Run "check" before "build" to verify donor and board compatibility. Full synthesis takes 30-60 minutes; add --skip-vivado for artifacts only.

COMMANDS

scan list PCI devices with VFIO status check validate a donor device (BAR size vs board BRAM) build generate firmware artifacts (+ Vivado) validate verify artifacts match the donor context verify-manifest check SHA256 integrity of build output mmio-trace capture live or import saved BAR MMIO access traces boards list supported FPGA boards version print version

Common build flags: --bdf donor device BDF (required) --board target board (required) --skip-vivado artifacts only, no synthesis --force allow donor BAR > board BRAM (may truncate) --from-json offline build from saved device_context.json --output output directory (default: pcileech_datastore)

Output directories are ownership-protected. Use a new --output path for the first build. Run "pcileechgen --help" for command-specific options.

FEATURES

captures PCIe identity, config space, BARs and capabilities
generates donor-sized BAR models and MSI-X tables
emulates the NVMe admin queue and DMA flow
scrubs config space and preserves register write behavior
validates donor/board compatibility and generated artifacts

SUPPORTED BOARDS

Board FPGA Lanes Form factor

CaptainDMA_M2_x1 XC7A35T-325 x1 M.2 CaptainDMA_M2_x4 XC7A35T-325 x4 M.2 CaptainDMA_35T XC7A35T-484 x1 PCIe CaptainDMA_75T XC7A75T-484 x1 PCIe CaptainDMA_100T XC7A100T-484 x1 PCIe ScreamerM2 XC7A35T-325 x1 M.2 pciescreamer XC7A35T-484 x1 PCIe NeTV2_35T XC7A35T-484 x1 M.2 NeTV2_100T XC7A100T-484 x1 M.2 PCIeSquirrel XC7A35T-484 x1 PCIe EnigmaX1 XC7A75T-484 x1 PCIe ZDMA XC7A100T-484 x4 PCIe GBOX XC7A35T-484 x1 Mini PCIe ac701_ft601 XC7A200T-676 x4 Dev Board acorn XC7A200T-484 x4 M.2 litefury XC7A100T-484 x4 M.2 sp605_ft601 XC6SLX45T-484 x1 Dev Board

Donor compatibility is checked separately. Run "pcileechgen boards" for current board details.

OUTPUT

The output directory contains the donor snapshot, generated RTL/IP source, config-space data, build manifest and validation reports. A normal Vivado build also includes the final bitstream.

DEVELOPMENT

make test run all tests make test-coverage tests with coverage report make lint run linter make check vet + lint + test

LICENSE

PolyForm Noncommercial License 1.0.0 https://github.com/sercanarga/PCILeechGen/blob/main/LICENSE.md

Unlicensed (fork pcileech-fpga modules) https://github.com/sercanarga/pcileech-fpga

400 ·GitHub

PCILeechGen

What is this?

PCILeechGen is a CLI tool that generates custom firmware for PCILeech FPGA boards. It reads a real donor PCI/PCIe device through VFIO, clones its identity (config space, BARs, capabilities), and produces a ready-to-flash .bin bitstream via Vivado.

Is this a GUI app or a command-line pipeline?

It is a pure command-line tool built around four ordered stages you run as separate subcommands: scan, check, build, and flash.

How do I get it running?

Clone with submodules and build it with 'make build', then run 'sudo ./bin/pcileechgen scan' to list PCI devices, 'check --bdf ' to validate your donor, and 'build --bdf --board ' to generate the firmware.

Do I need Vivado and IOMMU set up first?

Yes: Go 1.26+, a Linux machine with IOMMU/VFIO enabled in BIOS and kernel parameters, and Xilinx Vivado 2023.2 for full synthesis (which can be skipped with --skip-vivado).

How long does a full build take, and can I skip Vivado?

A full synthesis build takes 30-60 minutes; pass --skip-vivado to only generate the RTL/config-space artifacts without running Vivado.

Can I run this on Windows?

No, it requires a Linux host with VFIO/IOMMU support to read the donor device; there is no Windows build.

What's the catch with the license?

It ships under the PolyForm Noncommercial License 1.0.0 (forked pcileech-fpga modules stay unlicensed), and the README explicitly warns it is for educational and research use only, not for cheating or anti-cheat circumvention.

Which FPGA boards are supported?

It covers the CaptainDMA family (M2x1, M2x4, 35T, 75T, 100T), ScreamerM2, pciescreamer, NeTV2 35T/100T, PCIeSquirrel, EnigmaX1, ZDMA, GBOX, ac701ft601, acorn, litefury and sp605ft601, with current details printed via the 'boards' command.

What is the mmio-trace command for?

It captures live or imported BAR MMIO access traces, useful for checking that the generated firmware preserves the donor's real register behavior.

How do I check that a build is correct?

Run 'validate' to confirm generated artifacts match the donor context, or 'verify-manifest' to check the SHA256 integrity of the build output.

What are similar projects?

linux, binwalk, w1700k-sdr, mu300-linux, open-gpu-kernel-modules, pwndbg, BLEhound, wifit3

Which topics is it in?

driver, embedded-systems, kernel, low-level, firmware, systems-programming, embedded, hardware, reverse-engineering, cybersecurity, command-line, go

Creator: sercanarga
Size: 55.5 MB
Stars: 400
Updated: CommitSep 18 Release9d17fc6Sep 18
Age: 7mo
Commits · 90 Days