PYNQ Documentation

PYNQ.remote is an extension to the PYNQ framework designed for the remote control of AMD FPGA-based devices. It shifts the Python API from the target device to a host machine, communicating via gRPC.

Key Benefits

• Host-side Python Ecosystem: Allows integration into host-based workflows (AI inference, data processing, real-time visualizations) by leveraging the host's computing power while the FPGA handles specialized tasks.
• Reduced Target Footprint: Uses a minimal Petalinux image and a target-side C++ API (PYNQ.cpp) to reduce image sizes from ~7GB to under 200MB, making it suitable for RAM disk deployment in edge or IoT applications.
• API Compatibility: Classic PYNQ code and Jupyter notebooks can run remotely with minimal or no changes.
• Extensibility: Users can extend the system with custom remote APIs using Protobuf definitions.

The xsdfec package provides drivers for the RF Soft-Decision Forward Error Correction (SD-FEC) integrated block IP. This IP supports:

• Low Density Parity Check (LDPC) encoding and decoding (highly configurable on a codeword-by-codeword basis).
• Turbo code decoding.

For more technical details on the underlying IP, refer to the Xilinx SD-FEC product page.

PYNQ (Python productivity) is an open-source framework from AMD that provides a Jupyter-based environment and Python APIs for AMD Xilinx Adaptive Computing platforms. It allows developers to use programmable logic without needing ASIC-style design tools by leveraging high-level abstractions.

Supported Platforms:

• Zynq®
• Zynq Ultrascale+™
• Zynq RFSoC™
• Kria™ SOMs

The PYNQ-Z2 base overlay is a reference design that enables out-of-the-box peripheral support by connecting hardware IP blocks to the Zynq PS. It includes:

• HDMI: Both Input and Output interfaces connected directly to PL pins.
• Audio: Support for line-in, headphones out, and microphone.
• User IO: Tri-color LEDs, switches, pushbuttons, and individual LEDs routed to PS GPIO.
• PYNQ MicroBlaze: Dedicated soft-processor subsystems for Pmod (2x), Arduino (1x), and RPi (1x) interfaces.
• Trace Analyzer: Three blocks (PMODA, PMODB, and RASPBERRYPI) to capture IO signals and stream them to PS DRAM for analysis (e.g., using Wavedrom in Jupyter).

The python_packages_jammy/pre-built directory is used to store Python wheels that have been built from source within a chroot environment (for example, numpy built for armhf).

To understand the lifecycle of these files—specifically how they are moved into or out of the SD card image during the build process—you must examine the pre.sh and post.sh scripts located within the specific package folder.

The PYNQ CLI allows you to execute basic functionalities directly from a shell. The pynq command acts as a dispatcher: when you run pynq <subcommand>, it searches for and executes an underlying executable named pynq-<subcommand>.

To see all available subcommands and options, use the --help flag.

The ZCU104 base overlay enables out-of-the-box use of board peripherals by connecting hardware IP blocks to the Zynq PS. Once the system boots, these peripherals are immediately accessible via Python.

Key hardware included in the ZCU104 base overlay:

• DisplayPort & HDMI: Supports both HDMI 2.0 input and output. HDMI interfaces use video DMA to stream data to/from PS DRAM. Note that while the DisplayPort is connected to the PS, video can be streamed from HDMI PL sources to the DisplayPort.
• User IO: 4x user LEDs, 4x dip-switches, and 4x push buttons controlled via AXI GPIO controllers.
• PYNQ MicroBlaze: 2x Pmod PYNQ MicroBlaze subsystems (connected to PMOD 0 and PMOD 1) for controlling various peripheral interfaces and protocols without changing the PL design.

The WiFi Connect package enables a board to connect to a WiFi network automatically at boot using wpa_supplicant. To configure your networks, you must place specific configuration files in the boot partition of the SD card.

Configuration Files

• wpa_supplicant.conf: A standard wpa_supplicant configuration file. This file lists all the networks the board should attempt to connect to.
• wifi.ko (Optional): A driver file used to inject WiFi drivers that are not included in the mainline kernel.

In PYNQ, an Overlay is a class of Programmable Logic (PL) design that functions similarly to a software library. Instead of being hard-coded into the hardware, an overlay can be downloaded into the AMD-Xilinx Programmable Logic at runtime to provide specific functionality to a software application.

Key characteristics of a PYNQ overlay include:

• Configurability: Unlike standard highly optimized PL designs, overlays are designed to be reusable across a broad set of applications.
• Python Interface: Every PYNQ overlay includes a Python interface, allowing software developers to interact with the hardware using standard Python package syntax.

PYNQ.cpp is a C++ hardware abstraction library designed for AMD adaptive SoC platforms. It provides a C++ equivalent to the PYNQ Python API, offering low-level interface capabilities for interacting with FPGA fabric, managing memory, and performing device operations.

Key characteristics:

• Hardware Abstraction: Provides the same low-level control over FPGA resources as the Python-based PYNQ.
• Standalone Capability: Can be used independently of PYNQ.remote to build custom low-level C++ applications.
• Ecosystem Integration: Designed to work seamlessly with PYNQ.remote.