Skip to content

🛠️ Development Guide

The code needs to run on linux but can be developed anywhere with a python vers >3.9

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

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

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/

Important: The lib/voltcyclone-fpga submodule is required and contains FPGA board definitions, synthesis templates, and constraints files. Always clone with --recurse-submodules or initialize submodules with git submodule update --init --recursive.

📦 Building from Source

# Build distributions
python -m build

# Install locally
pip install dist/*.whl

Unit testing

TUI Tests are next to the code in the tui dir, app tests are in the tests/ dir. make test in the repo is the easiest way to run unit tests locally. The github action will run them in CI.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for detailed guidelines.

Quick Start: 1. Fork the repository 2. Create a feature branch (git checkout -b feature/amazing-feature) 3. Make your changes with tests 4. Submit a pull request

🏗️ Architecture

The project is structured as follows:

  • Core Generator: Main PCILeech firmware generation logic
  • TUI Interface: Modern terminal interface using Textual
  • VFIO Integration: Linux VFIO driver interaction
  • Template System: SystemVerilog template processing
  • Testing Framework: Comprehensive test suite

📝 Coding Standards

  • Follow PEP 8 style guidelines
  • Use type hints for all functions
  • Write comprehensive docstrings
  • Add unit tests for new features
  • Use descriptive commit messages

🔍 Debugging

The project includes extensive logging and debugging features:

# Verbose logs
sudo -E pcileech build -v --bdf 0000:03:00.0 --board pcileech_35t325_x4

🐳 Container Development

The build system uses Podman containers by default for consistency and reproducibility. The container image is automatically built when needed.

Understanding Container vs Local Builds

Container builds (default):

  • Uses Podman to run builds in an isolated environment
  • Ensures consistent dependencies and behavior
  • Automatically builds the image if it doesn't exist
  • Recommended for most development work

Local builds (fallback):

  • Used when Podman is not installed or unavailable
  • Requires all dependencies installed on your system
  • You'll be prompted to confirm when Podman isn't available

Manual Container Operations

# Build the container image manually (optional)
podman build -t pcileechfwgenerator:latest .

# Run development shell in container
podman run -it --privileged \
  -v $(pwd):/workspace \
  -v /sys/kernel/debug:/sys/kernel/debug:rw \
  pcileechfwgenerator:latest bash

Note: Kernel modules must be built on the host system (see src/donor_dump/Makefile).