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
  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 <addr>       donor device BDF (required)
    --board <name>     target board (required)
    --skip-vivado      artifacts only, no synthesis
    --force            allow donor BAR > board BRAM (may truncate)
    --from-json <f>    offline build from saved device_context.json
    --output <dir>     output directory (default: pcileech_datastore)

  Output directories are ownership-protected. Use a new --output path for the
  first build. Run "pcileechgen <command> --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