PCILeechGen（sercanarga/PCILeechGen）GitHub 项目：常见问题与相似项目

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

这是什么？

PCILeechGen 是一个为 PCILeech FPGA 板卡生成定制固件的命令行工具。它通过 VFIO 读取一块真实的捐赠 PCI/PCIe 设备，克隆其身份（配置空间、BAR、能力），并通过 Vivado 生成可直接烧录的 .bin 比特流。

这是图形界面应用，还是命令行流水线？

它是纯命令行工具，围绕四个按顺序执行的阶段构建，每个阶段作为独立的子命令运行：scan、check、build 和 flash。

怎么让它跑起来？

带子模块克隆并用 'make build' 构建，然后运行 'sudo ./bin/pcileechgen scan' 列出 PCI 设备，用 'check --bdf ' 校验你的捐赠设备，再用 'build --bdf --board ' 生成固件。

我需要先装好 Vivado 和配置好 IOMMU 吗？

需要：Go 1.26+，一台在 BIOS 和内核参数中启用 IOMMU/VFIO 的 Linux 机器，以及用于完整综合的 Xilinx Vivado 2023.2（可以用 --skip-vivado 跳过）。

完整构建要多久？能跳过 Vivado 吗？

完整综合构建需要 30-60 分钟；加上 --skip-vivado 参数可以只生成 RTL/配置空间产物，不运行 Vivado。

我能在 Windows 上运行它吗？

不行，它需要支持 VFIO/IOMMU 的 Linux 主机来读取捐赠设备，没有 Windows 版本。

这个许可证有什么限制？

它采用 PolyForm Noncommercial License 1.0.0 发布（fork 的 pcileech-fpga 模块仍无许可证），README 明确警告它仅供教育和研究用途，不能用于作弊或绕过反作弊。

支持哪些 FPGA 板卡？

它覆盖 CaptainDMA 系列（M2x1、M2x4、35T、75T、100T）、ScreamerM2、pciescreamer、NeTV2 35T/100T、PCIeSquirrel、EnigmaX1、ZDMA、GBOX、ac701ft601、acorn、litefury 和 sp605ft601，最新详情可通过 'boards' 命令打印。

mmio-trace 命令是干什么的？

它用于捕获实时或导入的 BAR MMIO 访问轨迹，方便检查生成的固件是否保留了捐赠设备真实的寄存器行为。

我怎么检查构建结果是否正确？

运行 'validate' 确认生成的产物与捐赠设备上下文一致，或运行 'verify-manifest' 检查构建输出的 SHA256 完整性。

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