PCILeechGen README

The project's README from github.com/sercanarga/PCILeechGen. As one markdown file: README.md.

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



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

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

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

PCILeechGen (sercanarga/PCILeechGen)

Searching Database…

Что это?PCILeechGen — CLI-инструмент, который генерирует кастомную прошивку для FPGA-плат PCILeech. Он читает реальное донорское PCI/PCIe-устройство через VFIO, клонирует его идентичность (конфигурационное пространство, BAR, возможности) и через Vivado создаёт готовый к прошивке битстрим .bin.
Это GUI-приложение или консольный конвейер?Это чисто консольный инструмент, построенный вокруг четырёх последовательных этапов, которые запускаются отдельными подкомандами: scan, check, build и flash.
Как его запустить?Склонируйте с подмодулями и соберите через 'make build', затем выполните 'sudo ./bin/pcileechgen scan', чтобы вывести список PCI-устройств, 'check --bdf ' для проверки донора и 'build --bdf --board ' для генерации прошивки.
Нужно ли сначала настроить Vivado и IOMMU?Да: Go 1.26+, машина на Linux с включёнными в BIOS и параметрах ядра IOMMU/VFIO, а также Xilinx Vivado 2023.2 для полного прохода синтеза (который можно пропустить с --skip-vivado).
Сколько длится полная сборка и можно ли пропустить Vivado?Полная сборка с синтезом занимает 30-60 минут; передайте --skip-vivado, чтобы только сгенерировать артефакты RTL/конфигурационного пространства без запуска Vivado.
Можно запустить это на Windows?Нет, для чтения донорского устройства нужен Linux-хост с поддержкой VFIO/IOMMU; сборки для Windows нет.
В чём подвох с лицензией?Проект распространяется под PolyForm Noncommercial License 1.0.0 (форкнутые модули 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?Она записывает трассировки доступа к MMIO BAR — живые или импортированные; это полезно, чтобы проверить, что сгенерированная прошивка сохраняет реальное поведение регистров донора.
Как проверить, что сборка корректна?Запустите 'validate', чтобы убедиться, что сгенерированные артефакты соответствуют контексту донора, или 'verify-manifest' для проверки целостности SHA256 результата сборки.
Creator
sercanarga
Size
55.5 MB
Stars
400
Age
7mo
Commits · 90 Days