Requirements - JPShag/PCILeech-DMA-Firmware GitHub Wiki

This section outlines the essential hardware and software components, along with the recommended environment setup, necessary to embark on custom firmware development for PCIe device emulation. Having these prerequisites in place before you begin will streamline your development process.

[Device Compatibility]] ](/JPShag/PCILeech-DMA-Firmware/wiki/[[Gathering-Donor-Device-Information)

4.1 Hardware

  • Donor PCIe Device
    • Purpose: This is the physical hardware device whose configuration and behavior you intend to emulate on your FPGA. It serves as the authoritative source for critical identification details, register values, and operational characteristics.
    • Examples: Common examples include a standard Network Interface Card (NIC), a SATA or NVMe storage controller, a USB controller, or any other generic PCIe expansion card that you can safely remove from a system for analysis. It is highly recommended to use a device that is not essential for the system's operation, as you will be inspecting its low-level configuration.
  • DMA FPGA Card
    • Description: An FPGA-based development board specifically designed or adapted to perform Direct Memory Access (DMA) operations over a PCIe interface. This is the platform onto which your custom firmware will be loaded.
    • Examples: As detailed in Device Compatibility#3.1 Supported FPGA-Based Hardware, compatible cards include the Squirrel (Artix-7 35T), Enigma-X1 (Artix-7 75T), ZDMA (Artix-7 100T), or various Kintex-7 based solutions. Ensure your chosen card has a PCIe edge connector.
  • JTAG Programmer
    • Purpose: This crucial tool facilitates the communication between your development PC and the FPGA on your DMA card. It's used to program (flash) the compiled bitstream onto the FPGA and, importantly, for interactive debugging using tools like Vivado's Hardware Manager and Integrated Logic Analyzer (ILA).
    • Examples:
      • Xilinx Platform Cable USB II: A traditional, widely compatible programmer for Xilinx FPGAs. Ensure you have the necessary drivers installed.
      • Digilent JTAG-HS3 / JTAG-HS2: Popular and reliable programmers known for good Vivado integration and support. The HS3 offers faster programming speeds.
      • Integrated JTAG: Some FPGA boards may have an onboard USB-to-JTAG bridge (e.g., a FTDI chip) which eliminates the need for a separate programmer. Consult your board's documentation.

4.2 Software

  • Xilinx Vivado Design Suite
    • Description: The official, comprehensive FPGA development environment from Xilinx (now AMD). Vivado is essential for synthesizing your HDL code, implementing the design onto the target FPGA, generating the final bitstream, and performing hardware debugging. It includes the necessary IP cores, compilers, and utilities.
    • Download: Visit the official Xilinx (AMD) downloads page: https://www.xilinx.com/support/download.html.
    • Version Note: While older versions like Vivado 2020.1 might be referenced in some legacy guides, it is strongly recommended to download a recent stable version (e.g., Vivado 2023.x or later) compatible with your target FPGA family (Artix-7, Kintex-7). The PCILeech-FPGA project generally supports newer Vivado versions.
  • Visual Studio Code
    • Description: A highly customizable and feature-rich code editor from Microsoft. It's an excellent choice for writing and editing your Verilog/SystemVerilog HDL code due to its extensive extension ecosystem, offering features like syntax highlighting, linting, auto-completion, and version control integration.
    • Download: https://code.visualstudio.com/
  • PCILeech-FPGA
    • Description: An open-source framework and base code repository for FPGA-based DMA development. It provides ready-to-use PCIe IP core instantiations and a well-structured project that serves as an excellent starting point for custom firmware. This guide heavily leverages its architecture.
    • Repository: https://github.com/ufrisk/pcileech-fpga
  • Arbor (MindShare)
    • Description: A powerful and user-friendly software tool specifically designed for in-depth scanning and analysis of PCIe devices. It provides detailed insights into the configuration space, capabilities, and registers of connected PCIe hardware, making it invaluable for gathering donor device information.
    • Download: Available from the MindShare website: https://www.mindshare.com/ (You will likely need to navigate to their software section).
    • Note: Typically requires account creation and may offer a time-limited trial.
  • Alternative PCIe Device Analysis Tools
    • Telescan PE (Teledyne LeCroy):
    • OS-Native Tools (For basic checks):
      • Windows Device Manager: Provides basic Vendor ID, Device ID, Subsystem ID, and Class Code information under the "Details" tab of a device's properties.
      • Linux lspci utility: A powerful command-line tool for inspecting PCIe devices. Use lspci -nn for Vendor/Device IDs, lspci -vvv for verbose details including BARs and capabilities, and lspci -s <BUS:DEV.FUN> -xxxx for raw configuration space dumps.

4.3 Environment Setup

A clean and correctly configured development environment is crucial to avoid common pitfalls and ensure a smooth workflow.

4.3.1 Install Xilinx Vivado Design Suite

Steps:

  1. Visit the Xilinx (AMD) Vivado Download Page: https://www.xilinx.com/support/download.html.
  2. Download the Appropriate Version: Select the latest stable version of Vivado that is compatible with your operating system and, importantly, with your specific FPGA device (e.g., Artix-7, Kintex-7). Check the Vivado release notes for device support.
  3. Run the Installer: Execute the downloaded installer and follow the on-screen instructions carefully.
  4. Select Necessary Components: During installation, you will be prompted to select which device families to install. Crucially, select the device family corresponding to your FPGA board (e.g., "7 Series" for Artix-7/Kintex-7). This saves significant disk space compared to installing all families. Ensure you select the "Design Tools" (Synthesis, Implementation) and "Programming & Debugging" components.
  5. Launch Vivado: After installation, launch Vivado to confirm it opens without errors and that licenses (if applicable) are correctly configured.

4.3.2 Install Visual Studio Code

Steps:

  1. Visit the Visual Studio Code Download Page: https://code.visualstudio.com/.
  2. Download and Install: Download the installer for your operating system and follow the standard installation prompts.
  3. Install Extensions for HDL Support: Once VS Code is installed, open it and navigate to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X). Search for and install relevant extensions for Verilog/SystemVerilog, such as:
    • Verilog-HDL/SystemVerilog (by mshr-h)
    • VHDL (if you also work with VHDL) These extensions provide syntax highlighting, linting, and other helpful features.

4.3.3 Clone the PCILeech-FPGA Repository

This repository contains the base firmware structure and scripts you'll be modifying.

Steps:

  1. Open a Terminal or Command Prompt: (e.g., Git Bash on Windows, Terminal on Linux).
  2. Navigate to Your Desired Directory: Choose a location where you want to store your projects. 
    cd ~/Projects/ # On Linux/macOS
cd C:\Users\YourUsername\Documents\Projects\ # On Windows
  3. Clone the Repository: 
    git clone [https://github.com/ufrisk/pcileech-fpga.git](https://github.com/ufrisk/pcileech-fpga.git)
  4. Navigate to the Cloned Directory: 
    cd pcileech-fpga
    This will be your main project directory. The PCILeech-FPGA project often contains subdirectories for different board variants (e.g., pcileech-artix-7-50t, pcileech-squirrel-35t). You will navigate into the relevant board-specific directory for your particular hardware.

4.3.4 Set Up a Clean Development Environment

Recommendation: Always work in an isolated or dedicated environment, especially when dealing with low-level hardware and potential security implications.

Steps:

  1. Use a Dedicated Development Machine or Virtual Machine:
    • Physical Machine: If possible, use a separate physical computer for your FPGA development and testing. This prevents accidental system instability or security risks on your primary machine.
    • Virtual Machine (VM): A VM can be a good option for isolating the development environment. However, direct PCIe passthrough (PCIe Hotplug or VT-d passthrough) to the VM is generally required for the FPGA card to be detected and operate correctly, which can be complex to configure and may still expose the host if not done carefully. For initial tool installation and code editing, a VM is perfectly fine.
  2. Minimize Background Applications: Ensure no other resource-intensive applications are running that might interfere with Vivado's performance during synthesis and implementation.
  3. Disable Conflicting Software: Temporarily disable any anti-virus, firewall, or security software that might interfere with low-level hardware access or JTAG communication during development and testing. Remember to re-enable them when you're done with your work.

[Device Compatibility]] ](/JPShag/PCILeech-DMA-Firmware/wiki/[[Gathering-Donor-Device-Information)