BELK-TN-005: Running PYNQ on Bora

Info Box Applies to Bora Applies to BORA Xpress

History

Version	Date	Notes
1.0.0	September 2018	First public release
1.1.0	October 2018	Moved to PYNQ 2.3

Introduction

As stated in the official documentation, Python Productivity for Zynq (Pynq)'s main goal is ...

... to make it easier for designers of embedded systems to exploit the unique benefits of APSoCs in their applications. Specifically, PYNQ enables architects, engineers and programmers who design embedded systems to use Zynq APSoCs, without having to use ASIC-style design tools to design programmable logic circuits.

PYNQ achieves this goal in three ways:

- Programmable logic circuits are presented as hardware libraries called overlays. These overlays are analogous to software libraries. A software engineer can select the overlay that best matches their application. The overlay can be accessed through an application programming interface (API). Creating a new overlay still requires engineers with expertise in designing programmable logic circuits. The key difference however, is the build once, re-use many times paradigm. Overlays, like software libraries, are designed to be configurable and re-used as often as possible in many different applications.

- PYNQ uses Python for programming both the embedded processors and the overlays. Python is a “productivity-level” language. To date, C or C++ are the most common, embedded programming languages. In contrast, Python raises the level of programming abstraction and programmer productivity. These are not mutually-exclusive choices, however. PYNQ uses CPython which is written in C, and integrates thousands of C libraries and can be extended with optimized code written in C. Wherever practical, the more productive Python environment should be used, and whenever efficiency dictates, lower-level C code can be used.

- PYNQ is an open-source project that aims to work on any computing platform and operating system. This goal is achieved by adopting a web-based architecture, which is also browser agnostic. We incorporate the open-source Jupyter notebook infrastructure to run an Interactive Python (IPython) kernel and a web server directly on the ARM Cortex A9 of the Zynq device. The web server brokers access to the kernel via a suite of browser-based tools that provide a dashboard, bash terminal, code editors and Jupyter notebooks. The browser tools are implemented with a combination of JavaScript, HTML and CSS and run on any modern browser.

source: https://pynq.readthedocs.io

This Technical Note shows hot to run PYNQ on Bora platform. It is worth remembering that, even though the procedure was tested on Bora, it should work on BoraX as well without any modification.

To see PYN in action, please see this clip.

Testbed's hardware and software configuration

As stated before, the procedure was tested on Bora/BoraEVB hardware platform.

With regard to the software configuration, the following versions were used:

• U-Boot 2014.07 released with BELK 2.1.0
• Linux kernel 4.14.0 (at the time of this writing, this version was not officially supported by any BELK release yet)
• root file system: extracted from Pynq-Z1 v2.3 image and mounted from microSD card.

Original root file system included several kernel drivers built as modules. The Linux kernel used for this test was different than the kernel released along with the PYNQ's root file system, however. Consequently, these modules were not compatible with the kernel running on Bora. To overcome this issue, these drivers were linked statically into the kernel image.

Setting up the board

U-Boot environment was configured in order to retrieve the kernel image and the device tree blob from the microSD card. Also, it was configured to make the kernel to mount the root file system from a partition of the microSD card.

The following box shows the full boot process (clock on the "Expand" box):

TBD aggiornare

Testing the PYNQ framework

The following image shows the PYNQ processes running.

Running processes ordered by memory occupation

To test the whole framework, the following testbed was used.

Testbed block diagram

The test consisted of the following steps:

• First, a FIR filter was generated using the wizard provided by Vivado.
• The resulting IP was instantiated in Programmable Logic (PL).
• Using Jupyter Notebooks, the Python test code was edited and run.
  • Two different approaches were used: generic driver and IP-specific driver.

This example was inspired by [tutorial].

• Open Jupyter Notebook: In order to open the Jupyter Notebook web dashboard, do the following steps:
  • Open the browser (only Google Chrome is supported)
  • Go to http://<IP address>:9090 if your board is connected to a computer via static IP address or to http://pynq:9090 if your board is connected to a router on network
  • Log in with username xilinx and password xilinx.

caption

1. MOVE FILE TO AND FROM JUPYTER NOTEBOOK

To access the Pynq home area as a network drive to transfer file to and from the board: - open a file browser and click "Go" > "Enter Location" - insert location smb://192.168.2.99/xilinx - log as "xilinx" with password "xilinx"

1. WRITE AND RUN PYTHON FUNCTIONS

This section describes how to write and run python code on the web interface. - create a new notebook by clicking on the "New" button at the top and select "Python 3" - select "Code" on top bar and write some Python code - click "Run" on top bar to run code on kernel

/* immagine : jupyter_new_file.png immagine : jupyter_start_writing_python.png

• /

The procedure was tested with a FIR filter from SciPy library applied to a noisy signal.

/* vedi http://www.fpgadeveloper.com/2018/03/how-to-accelerate-a-python-function-with-pynq.html fino al paragrafo "Software FIR filter using SciPy" */

1. ACCELERATE A PYTHON FUNCTION

1. INTRO

To accelerate a Python function on the Zynq-7000, PYNQ can load a custom overlay. Overlays are built with Vivado 2018.2 and are composed by: - fpga bitstream (*.bit file) - block design (*.tcl file)

The test consisted of the following steps: - First, a FIR filter was generated using the wizard provided by Vivado. - The resulting IP was instantiated in Programmable Logic (PL). - Using Jupyter Notebooks, the Python test code was edited and run.

   	- Two different approaches were used: generic driver and IP-specific driver.

1. CREATE A NEW CUSTOM PYNQ OVERLAY // titolo specifico per filtro fir?

/* sezione da approfondire */

- /* instruzioni di setup vivado */ - Open a new Vivado project, select "RTL project" and "BORA SOM" as target board - Create your block design - Add "FIR compiler" block (included in Vivado default IP) and setup it. To create a new filter block starting from the code c read the paragraph %CREATE A NEW BLOCK IP FROM C CODE% - Add "AXI direct memory access" block and setup it - Enable on "ZYNQ7 Processing System" block an "High Performance AXI 32b/64b Slave Ports" on interface HP0 - Connect AXIS_DATA bus of AXI and FIR block - "Run Connection Automation" to complete wiring - create Hierarchy of AXI and FIR block named "filter" - export bitstream file running "Generate Bitstream" - export block design using tcl console command "write_bd_tcl </path/name>.tcl" - rename generated files as "<overlay_name>.bit" and "<overlay_name>.tcl" - create folder <overlay_name> and insert generated files - copy folder in PYNQ target in pynq/overlays/

Overlay is ready to use in PYNQ Python console.

/* immagine: jupyter_vivado_filter.png */

1. RUN CUSTOM PYNQ OVERLAY WITH GENERIC DRIVER // titolo specifico per filtro fir?

/* sezione da approfondire e riscrivere meglio */

- Load Overlay and Xlnx modules from pynq and pynq.lib.dma. - Create Overlay and Xlnk object - you can comunicate directly on dma buffer.

/* vedi http://www.fpgadeveloper.com/2018/03/how-to-accelerate-a-python-function-with-pynq.html paragrafo "Hardware FIR Implementation" */

1. RUN CUSTOM PYNQ OVERLAY WITH IP-SPECIFIC DRIVER // titolo specifico per filtro fir?

/* sezione da approfondire e riscrivere meglio */ /* da testare exportazione con diversi setaggi da vivado per checkhierarchy */

- import DefaultHierarchy from pynq - create a new class for fir filter with a method to comunicate directly on dma buffer - create a checkhierarchy method to check ip contained under "filter" hierarchy

/* vedi http://www.fpgadeveloper.com/2018/03/how-to-accelerate-a-python-function-with-pynq.html paragrafo "Driver for FIR accelerator" */

1. CREATE A NEW BLOCK IP FROM C CODE

/* sezione da scrivere la prossima settimana */