PYNQ Framework Brief

PYNQ includes major common building blocks into PYNQ libraries to bring a typical embedded system up into running with a very fast pace. I created a table to cover the major libraries and their classes. I added my own understanding of the learning curve for each category as a beginner level now.

My previous two blogs for this challenge already touched Audio, Video, and PMOD IOP classes.

Overlay class is part of PL control library. Ref[1] is the reference for all development of PYNQ libraries and overlay classes. Overlay design framework is a brilliant method to use FPGA PL(programmable logic) at software API layer under open-source community supports.

Learning PYNQ Overlay from Supported IPs, PS/PL Interface and PL Control

It has been overwhelmingly learning PYNQ Overlay framework since last two months. After reading the document from Ref [1], I decided to start a simple PYNQ project which including PS GPIO, low pass FIR acceleration and DebugBridge. There are five classes will be exercised in the simple project.

1. GPIO class

The Zynq device has up to 64 GPIOs from PS to PL. It is used for simple control type operations. I started to learn PYNQ overlay from GPIO class.

2. Allocate class

From PYNQ V2.7, PS/PL interface used Allocate library for memory allocation instead of xlnk class. I will demonstrate how to use Allocate library in the FIR DMA acceleration part of the simple PYNQ project.

3. DMA class

PYNQ DMA class is a fundamental building block for high performance burst transfers between PS DRAM and PL logic blocks.

4. Python Overlay API

There are three files needed for loading an overlay: FPGA bitstream, Vivado Block Design TCL file and HWH file from Vivado HW handoff.

TCL and HWH file name should match with FPGA bistream file. TCL/HWH file is used to provide information about Vivado project development, which lists IPs in the design, GPIOs, PS to PL clock configuration, memory addresses and so on.

5. DebugBridge class

The DebugBridge class provides a mechanism which make PYNQ can interact with Xilinx Virtual Cable (XVC) server on Debug Bridge IP in AXI-to-BSCAN and AXI-to-JTAG configuration. I will demonstrate how to implement DebugBridge in the simple PYNQ project here.

A Simple PYNQ Overlay Project Journey

1. The block diagram of the simple PYNQ project is presented as below. Three Zynq PS ports/types are exercised here: PS GPIO, PS HP/ACP/GP for DMA, and Xilinx XVC server on Debug Bridge IP.

The overall Vivado block diagram is presented as below.

Figure 1. Arty_Z20_SoC Block Diagram

I created a folder at Jupyter  Notebook of PYNQ V3.0.1  on Zynq_Z7_20 platform. I uploaded 3 files from Vivido project output: bitstream, TCL and HWH file. All the files have same name.

2. PS GPIO

I followed PYNQ tutorial: PS GPIO from Cathal McCabe (Ref[2]) under Vivado 2022.1 tool chain. It really gave me a solid lift to get into PYNQ overlay journey at the beginning of PYNQ training.

• Vivado flow for PS GPIO

Building PS GPIO at Vivado PL side is very simple.  Cathal McCabe did a decent job to educate me how to create PL and/or/xor/nor gates and connect them with PS GPIO pins for PYNQ overlay framework. Ref[2] is the link for the guidance of this part. I will use this part for DebugBridge overlay demonstration later.

• PYNQ Jupyter flow

The GPIO class calling from PYNQ library is very straightforward. I found that I used the simple PS GPIO scripts to validate PYNQ image booting properly more often than I thought since the result was almost self-explained.

3. FIR Accelerator

PYNQ framework is a great vehicle to interact with Matlab/algorithm for FPGA acceleration implementation. I picked the path to learn how to accelerate a low pass FIR filter on Arty-Z7-20 platform.

• Matlab/algorithm flow

There are many tools to design a low pass filter. Python SciPy which is supported on PYNQ can be used for LP FIR filter design. However, I decided to use Matlab for PYNQ projects here since I planed to use Matlab for my future HLS flow, which might not be part of this design challenge project due to the limited time left from now on.

I shared the simple Matlab file to generate a 31-order low pass FIR coefficient set for FPGA implementation.

% Matlab FIR design flow
 lpFIR = designfilt('lowpassfir', 'FilterOrder', 31, 'PassbandFrequency', 2e6, ...
 'StopbandFrequency', 10e6, 'SampleRate', 100e6);
% Plot FIR frequency response 
 fvtool(lpFIR);
  
% Convert floating FIR coefficients into 16-bit fixed data for FPGA 
 FPGA_bl = 16;
 lpFIR_coef_FPGA=ceil(lpFIR.Coefficients().*2^FPGA_bl);

The sample frequency is 100MHz, the passband frequency is 2MHz, and the stopband frequency is 10Mhz. Matlab fvtool print out the frequency response of the targeted FIR filter as below.

16-bit fixed data is selected for FPGA implementation. A simple rounding up at Matlab code to convert the floating data into 16-bit data there.

Here is the set of 31-order FIR coefficients which is signed 16-bit data:

-178,-282,-444,-597,-689,-659,-443,8,720,1680,2837,4096,5337,6425,7234,7666,7666,7234,6425,5337,4096,2837,1680,720,8,-443,-659,-689,-597,-444,-282,-178

• Vivado flow for FIR filter and DAM IPs

I started to learn FIR filter acceleration flow from Jeff Johnson’s blog. Ref[3] is the link of his PYNQ file for the topic.There are two Vivado IPs used for the training: FIR compiler 7.2(Ref[4]) and AXI DMA as below. 

The snapshot of FIR compiler IP configuration is as follows

DMA IP configuration is presented as below.

 Figure 1, Arty_Z20_SoC.pdf presents the overall Vivado project design.

4.DebugBridge IP for PYNQ

• What is DebugBridge IP?

PYNQ community said DebugBridge IP is mostly for AMD/Xilinx flow. The documentation of this part at Ref[1] is limited. AMD/Xilinx PG245, Debug Bridge v3.0,(Ref[5]) gave me a good understanding of the IP user guide. Debug Bridge IP basically is a controller which establishes a debugging communication on the Zynq FPGA  to a remote server without using a JTAG debugging cable. The generic function diagram from PG245 is illustrated as below. (Notes: FPGA debug core needs to be system_ILA core.)

As you can see from the diagram, an Ethernet port from Zynq FPGA provides the communication channel between the server to the targeted FPGA debugging cores.

• Vivado flow for DebugBridge

       Tool chain for Debug Bridge flow:   Vivado 2022.1 and  Vivado Lab 2022.1

Here is the flow at Vivado side for Debug Bridge IP configuration.

• PYNQ Jupyter flow

 Here is the PYNQ script to call DebugBridge class. As you can tell XVC serer is started. However, something is still missing.

We need to start Vivado Lab at a host PC now since the server for the debug bridge is located at the remote Vivado Lab.

Click "Add Xilinx Virtual Calbe (XVC)" button for the new hardware target as below.

Then input the IP address from PYNQ platform into Vivado Lab as below. For my case, 192.168.50.67 is the one, which is same as the IP address I used for Jupyter Lab on my host PC.

After that, Vivado Lab listed two Hardware Target since I plugged USB/Jtag port cable with my host PC as well.

After I selected Xilinx/192.168.50.67:2542 which has10MHz JTAG clock rate. The final report is presented as below.

Well done, Vivado Lab. PYNQ Jupyter Lab was clever too. Here is the updated Jupyter Lab Web page at the same time. Jupyter even knew my host PC IP address automatically.

Here is the initial Vivado Lab GUI without loading debug probe file.

Same as a typical ILA core at Vivado Lab flow, I uploaded the associated debug probe file as below.

I was able to display signal waveforms at Vivado Lab from DebugBridge now.

Reference of the Jupyter  Lab script for the above ILA plot.

Future Path on PYNQ/Z7_Color_AID Project

 I will focus on the Z7_color_AID project build block and architecture work.

References

[1] PYNQ Libraries   v3.1     https://pynq.readthedocs.io/en/latest/pynq_libraries.html                  2024

[2] https://github.com/cathalmccabe/PYNQ_tutorials/tree/master/ps_gpio                                    2021

[3] fpgadeveloper/FIR Acceleration on PYNQ.ipynb https://gist.github.com/fpgadeveloper/c086319971f68226b424bce98d430098         2021

[4] PG149, FIR Compiler v7.2                                                    AMD/Xilinx                                     2022

[5] PG245, Debug Bridge v3.0                                                   AMD/Xilinx                                      2018

Previous Blogs:

Z7_Color_AID-Blog#01:First Impression of PYNQ on Arty-Z7-20

Z7_Color_AID Blog #2: Reproduce PYNQ Image on Ubuntu 20.04