Skip to content

Quick Start Guide

Get up and running with PCILeech Firmware Generator in minutes. This guide assumes you've completed the installation.

🎯 Overview

This tutorial covers:

  1. Finding a donor device (BDF)
  2. Generating your first firmware
  3. Understanding the output
  4. Optional: Flashing to an FPGA

Before starting, ensure you have:

  • PCILeech Firmware Generator installed
  • At least one PCIe device bound to VFIO
  • Root access (sudo) and membership in the vfio group
  • (Optional) Xilinx Vivado for synthesis

Step 1: Find a donor device (BDF)

Use lspci to discover PCIe devices and their BDFs:

# List PCIe devices with numeric IDs (BDFs)
lspci -Dnn

# Example output (note the BDF at the start of each line):
# 0000:01:00.0  Ethernet controller [0200]: Intel Corporation 82599ES [8086:10fb]
# 0000:02:00.0  VGA compatible controller [0300]: NVIDIA Corporation TU106 [10de:1f06]
# 0000:03:00.0  Non-Volatile memory controller [0108]: Samsung NVMe [144d:a808]

Pick a BDF (e.g., 0000:01:00.0). If nothing appears, check your VFIO setup (see Installation).

Step 2: Choose your target board

Supported board names are defined in the project. Common identifiers:

  • pcileech_100t484_x1 — Artix-7 100T, 484 BGA, PCIe x1
  • pcileech_35t325_x4 — Artix-7 35T, 325 BGA, PCIe x4
  • pcileech_75t484_x1 — Artix-7 75T, 484 BGA, PCIe x1

Tip: Run the interactive picker (TUI, Linux only) or consult src/device_clone/board_config.py.

Step 3: Generate your first firmware

Use the CLI with a BDF and board name. Root privileges are required for hardware access.

sudo pcileech build --bdf 0000:01:00.0 --board pcileech_100t484_x1

About the build process:

  • The build system uses Podman containers by default for consistency
  • If the container image doesn't exist, it will be built automatically
  • If Podman isn't installed, you'll be prompted to run locally instead
  • Local builds work but require all dependencies installed on your system

With interactive TUI (Linux only)

sudo pcileech tui

From a developer checkout, install the console entrypoint (pip install -e .) to use the pcileech command.

Advanced options

# Enable advanced SystemVerilog features and manufacturing variance
sudo pcileech build --bdf 0000:01:00.0 --board pcileech_100t484_x1 --advanced-sv --enable-variance

# Generate a donor-info JSON template alongside build artifacts
sudo pcileech build --bdf 0000:01:00.0 --board pcileech_100t484_x1 --generate-donor-template donor_info.json

Note: Older flags like --device-id, --vendor-id, or --unique are not supported directly. Use donor templates and the build configuration. See Firmware Uniqueness.

Step 4: Understand the output

After generation you'll find a build directory. Typical artifacts include:

my_first_firmware/
├── pcileech_top.sv           # Top-level SystemVerilog module
├── <board>_bar_*.sv         # Board-specific controllers
├── config_space_init.hex     # Configuration space initialization
├── vivado_project.tcl        # Vivado project / synthesis script
├── device_info.json          # Extracted device information (donor info)
└── logs/
  ├── generation.log        # Detailed generation log
  └── vfio_extraction.log   # VFIO extraction details

Step 5: Verify generation success

# Verify output files
ls -la my_first_firmware/

# Check generation log for any issues
grep -i error my_first_firmware/logs/generation.log || echo "No errors found"

# Validate SystemVerilog / run synthesis with Vivado (optional)
cd my_first_firmware/
vivado -mode batch -source vivado_project.tcl

Step 6: Build FPGA bitstream (optional)

cd my_first_firmware/
vivado -mode batch -source vivado_project.tcl

# Bitstream typically appears under:
# project.runs/impl_1/pcileech_top.bit

Step 7: Flash to FPGA (optional)

sudo pcileech flash my_first_firmware/pcileech_top.bin --board pcileech_100t484_x1

Custom donor templates

Generate and use a donor template:

# Generate a donor template from your device
sudo pcileech donor-template --save-to my_device.json --bdf 0000:01:00.0

# Edit my_device.json as needed, then:
sudo pcileech build --bdf 0000:01:00.0 --board pcileech_100t484_x1 --donor-template my_device.json

Installing from source

If you're working from a source checkout, ensure you've initialized the submodules:

# Clone with submodules (required for lib/voltcyclone-fpga)
git clone --recurse-submodules https://github.com/VoltCyclone/PCILeechFWGenerator.git
cd PCILeechFWGenerator

# If already cloned without submodules:
git submodule update --init --recursive

# Install in development mode
pip install -e .

Note for developers: When working from a git checkout, the lib/voltcyclone-fpga submodule is required and contains FPGA board definitions and synthesis templates.

Note for pip users: If you installed via pip install pcileechfwgenerator, the submodule contents are already bundled, so no additional steps are needed.

✨ Tips for success

  1. Choose simple donors first (NICs are easier than GPUs).
  2. Match PCIe lane count to your use case.
  3. Always review generation logs and device_info.json.
  4. Enforce uniqueness: don't hardcode IDs. See Firmware Uniqueness.

🎓 Next steps

Questions? See Troubleshooting or Issue Reporting.