🖥️ PCILeech Firmware Generator TUI

PyPI version Python Support License: MIT

A modern Text User Interface (TUI) for the PCILeech firmware generation workflow, built with the Textual framework.

📑 Table of Contents

🔍 Overview

The TUI provides an interactive, user-friendly interface that addresses the key pain points of the command-line workflow:

  • Enhanced Device Discovery: Visual PCIe device browser with detailed information
  • Guided Configuration: Intuitive configuration wizard with validation
  • Real-time Build Monitoring: Live progress tracking with resource usage
  • Error Guidance: Intelligent error analysis with suggested fixes
  • Profile Management: Save and load configuration profiles

🚀 Installation

Prerequisites

  • Python 3.9 or higher
  • Root/sudo access (required for device binding)
  • Podman container runtime
  • PCILeech firmware generation environment

Install TUI Dependencies

# Install TUI-specific dependencies
pip install -r requirements-tui.txt

# Or install individual packages
pip install textual rich psutil watchdog pydantic

🎮 Usage

Launch TUI Mode

There are several ways to launch the TUI:

# Method 1: Using the unified entrypoint (recommended)
sudo python3 pcileech.py tui

# Method 2: Direct execution 
sudo python3 -m src.tui.main

# Method 3: Using the sudo wrapper (if installed)
./install-sudo-wrapper.sh  # Install the wrapper first (one-time setup)
pcileech-tui-sudo

Note: UI operations require root privileges. The sudo wrapper script preserves the Python environment when running with sudo, preventing module import errors.

TUI Interface Overview

The TUI is organized into several panels:

1. Device Selection Panel (Top Left)

  • Lists all detected PCIe devices
  • Shows device status, BDF address, name, driver, and IOMMU group
  • Provides device suitability indicators
  • Refresh and details buttons

2. Configuration Panel (Top Right)

  • Displays current build configuration
  • Shows board type, device type, and enabled features
  • Configure, load profile, and save profile buttons

3. Build Progress Panel (Middle)

  • Real-time build progress with stage tracking
  • Resource usage monitoring (CPU, memory, disk)
  • Build control buttons (start, pause, stop)
  • Log viewing capability

4. System Status Panel (Bottom Left)

  • Podman availability and status
  • Vivado detection and version
  • USB device count
  • Disk space information
  • Root access status

5. Quick Actions Panel (Bottom Right)

  • Device scanning
  • Output directory access
  • Build report viewing
  • Advanced settings
  • Documentation links

✨ Features

Device Management

  • Auto-discovery: Automatically scans and lists PCIe devices
  • Enhanced Information: Shows vendor names, driver status, IOMMU groups
  • Suitability Assessment: Rates devices for firmware generation compatibility
  • Driver Status: Indicates if devices are bound to drivers

Configuration Management

  • Profile System: Save and load configuration profiles
  • Default Profiles: Pre-configured profiles for common scenarios:
    • Network Device Standard
    • Storage Device Optimized
    • Quick Development
    • Full Featured
  • Validation: Real-time configuration validation with error messages

Build Monitoring

  • Stage Tracking: Visual progress through 6 build stages:
    1. Environment Validation
    2. Device Analysis
    3. Register Extraction
    4. SystemVerilog Generation
    5. Vivado Synthesis
    6. Bitstream Generation
  • Resource Monitoring: Real-time CPU, memory, and disk usage
  • Error Detection: Automatic error detection with guided recovery

System Integration

  • Backward Compatibility: Maintains all existing CLI functionality
  • Container Integration: Seamless integration with Podman containers
  • Log Management: Integrated log viewing and analysis
  • USB Device Support: Automatic USB device detection for flashing

⚙️ Configuration Profiles

Profile Locations

Profiles are stored in ~/.pcileech/profiles/ as JSON files.

Default Profiles

Network Device Standard

{
  "name": "Network Device Standard",
  "board_type": "pcileech_35t325_x1",
  "advanced_sv": true,
  "enable_variance": true,
  "behavior_profiling": true,
  "profile_duration": 30.0,
  "donor_dump": true
}

Quick Development

{
  "name": "Quick Development",
  "board_type": "pcileech_35t325_x1",
  "advanced_sv": false,
  "enable_variance": false,
  "flash_after_build": true,
  "donor_dump": true
}

Local Build

{
  "name": "Local Build",
  "board_type": "pcileech_35t325_x1",
  "advanced_sv": true,
  "enable_variance": true,
  "donor_dump": false,
  "local_build": true,
  "donor_info_file": "~/.pcileech/donor_info.json"
}

Creating Custom Profiles

  1. Configure settings in the TUI
  2. Click “Save Profile”
  3. Enter a profile name
  4. Profile is saved to ~/.pcileech/profiles/

⌨️ Keyboard Shortcuts

  • Ctrl+C: Exit application
  • Tab: Navigate between panels
  • Enter: Activate selected button/item
  • Space: Toggle checkboxes
  • ↑/↓: Navigate lists and tables
  • F1: Help (if implemented)

🔧 Error Handling

The TUI provides intelligent error analysis and guidance:

Common Errors and Solutions

VFIO Binding Failed

  • Cause: IOMMU not enabled or vfio-pci module not loaded
  • Solutions:
    • Enable IOMMU in BIOS
    • Load vfio-pci module: modprobe vfio-pci
    • Unbind current driver first

Container Image Not Found

  • Cause: DMA firmware container not built
  • Solutions:
    • The container is now automatically built when needed
    • If automatic build fails, manually build with: podman build -t dma-fw .
    • Check Podman installation and internet connectivity

Insufficient Permissions

  • Cause: Not running with root privileges
  • Solutions:
    • Run with sudo: sudo python3 pcileech.py tui
    • Add user to required groups

🚀 Advanced Features

Donor Device Configuration

The TUI provides options for configuring how donor device information is obtained:

  • Default Mode: By default, the system builds and uses the donor_dump kernel module to extract real device information from the selected PCIe device. This provides the most accurate firmware generation.

  • Local Build Mode: When enabled, this mode skips using the donor_dump kernel module and instead uses either:

    • A previously saved donor information file (specified via the “Donor Info File” option)
    • Synthetic donor information generated based on the selected device type

Configuration Options:

  • Donor Dump: Enable/disable using the donor_dump kernel module (enabled by default)
  • Local Build: Enable to use a donor info file or synthetic data instead of a real device
  • Donor Info File: Path to a JSON file containing donor information from a previous run

Benefits of Local Build Mode:

  • No Kernel Module: Useful in environments where building kernel modules is restricted
  • No Physical Device: Generate firmware without requiring the donor device to be present
  • Reproducible Builds: Use the same donor information across multiple builds

Usage:

  1. Select a device in the Device Selection Panel
  2. Open the Configuration Panel
  3. To use the default mode (recommended), ensure “Donor Dump” is enabled
  4. To use Local Build mode:
    • Enable “Local Build” option
    • Disable “Donor Dump” option
    • Optionally specify a “Donor Info File” path
  5. Start the build process

TUI Configuration Panel

Behavior Profiling

The TUI provides a seamless interface for enabling and configuring behavior profiling:

  • Enable/Disable: Toggle behavior profiling in the configuration panel
  • Duration Control: Set custom profiling duration (in seconds)
  • Real-time Monitoring: Track profiling progress in the build progress panel
  • Profile Integration: Automatically integrates profiling data into the build process

Configuration Options:

  • Behavior Profiling: Enable/disable the profiling feature
  • Profile Duration: Set the duration for capturing device behavior (default: 30.0 seconds)
  • Device Type: Select specific device type for optimized profiling

Benefits:

  • Enhanced Realism: Generated firmware mimics actual device behavior patterns
  • Improved Timing: More accurate register access timing based on real measurements
  • Optimized Performance: Device-specific optimizations based on observed behavior

Usage:

  1. Select a device in the Device Selection Panel
  2. Open the Configuration Panel
  3. Enable “Behavior Profiling” option
  4. Adjust “Profile Duration” if needed
  5. Start the build process

During the build, a dedicated “Behavior Profiling” stage will appear in the progress panel, showing real-time status of the profiling process.

System Status Monitoring

The TUI continuously monitors:

  • Podman service status
  • Vivado installation and version
  • Available USB devices
  • System resources (CPU, memory, disk)
  • VFIO support status

Build Process Integration

  • Container Orchestration: Manages Podman container lifecycle
  • Progress Parsing: Parses build output for progress indicators
  • Resource Tracking: Monitors system resource usage during builds
  • Log Analysis: Analyzes build logs for errors and warnings

Configuration Validation

  • Real-time Validation: Validates configuration as you type
  • Compatibility Checks: Warns about incompatible settings
  • Resource Requirements: Estimates resource requirements

🐛 Troubleshooting

TUI Won’t Start

  1. Check Dependencies: 
    pip install -r requirements-tui.txt
  2. Check Python Version: 
    python3 --version  # Should be 3.8+
  3. Check Terminal Compatibility:
    • Ensure terminal supports ANSI colors
    • Try different terminal emulator

Device Detection Issues

  1. Run as Root: 
    # Using the sudo wrapper (recommended)
./install-sudo-wrapper.sh  # Install the wrapper first
pcileech-tui-sudo
   
# Or directly with sudo
sudo python3 pcileech.py tui

    Note: When running with sudo, you might encounter the error ModuleNotFoundError: No module named 'src'. This happens because sudo changes the Python module search path. Use the provided sudo wrapper script to avoid this issue.

  2. Check lspci: 
    lspci -Dnn
  3. Verify IOMMU: 
    dmesg | grep -i iommu

Build Failures

  1. Check Container Image: 
    podman images | grep dma-fw
  2. Verify Device Binding: 
    ls -la /dev/vfio/
  3. Check Logs:
    • Use “View Logs” button in TUI
    • Check generate.log file

🛠️ Development

Architecture

The TUI follows a modular architecture:

src/tui/
├── main.py              # Main application
├── models/              # Data models
├── core/                # Business logic services
├── widgets/             # Custom UI widgets
├── screens/             # Screen components
└── styles/              # CSS styling

Key Components

  • DeviceManager: PCIe device discovery and management
  • ConfigManager: Configuration and profile management
  • BuildOrchestrator: Build process orchestration
  • StatusMonitor: System status monitoring

Extending the TUI

  1. Add New Widgets: Create custom widgets in src/tui/widgets/
  2. Add New Screens: Create screen components in src/tui/screens/
  3. Extend Models: Add new data models in src/tui/models/
  4. Add Services: Create new services in src/tui/core/

🤝 Contributing

  1. Follow the existing code structure
  2. Add type hints to all functions
  3. Include docstrings for public methods
  4. Test with various PCIe devices
  5. Ensure backward compatibility

📄 License

Same as the main PCILeech project.

⚠️ Disclaimer

This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.

Version 0.5.0 - Major release with TUI interface and professional packaging