pynq

主要源文链接：http://pynq.readthedocs.io/en/latest/python_environment.html
源码地址：https://github.com/xilinx/pynq

---

基本介绍

下面是一段来自Digilent对PYNQ-z1的介绍：
The PYNQ-Z1 board is designed to be used with PYNQ, a new open-source framework that enables embedded programmers to exploit the capabilities of Xilinx Zynq All Programmable SoCs (APSoCs) without having to design programmable logic circuits. Instead, the APSoC is programmed using Python and the code is developed and tested directly on the PYNQ-Z1. The programmable logic circuits are imported as hardware libraries and programmed through their APIs in essentially the same way that the software libraries are imported and programmed.

组成

PYNQ-z1是第一块支持pynq的板子，上面搭载了Zynq-Xz7z020芯片。
可编程逻辑（Programming Logic, PL）和处理系统（Processing System, PS）
在官方提供的板载系统文件（下载地址）中集成了pynq开发所需的系统，系统包括：
- Jupyter notebook开发环境的网络服务端
- Linux系统
- Ipython核和包
- 基本硬件库和对FPGA编程的API

应用

PYNQ 的使用者可以设计有以下属性的嵌入式应用：
- parallel hardware execution
- high frame-rate video processing
- hardware accelerated algorithms
- real-time signal processing
- high bandwidth IO
- low latency control
PYNQ-Z1是一块通用的嵌入式开发板，用户可以编程它的软硬件来实现如下应用:
- Computer vision
- Industrial control
- The Internet of things (IoT)
- Drones
- Encryption
- Embedded computing acceleration
- Real-time processing and many more…

pynq的安装

开发板上的pynq的python包可以通过pip安装和更新，当通过电脑的浏览器连接了板载系统后，可以通过创建一个终端连接至pynq的SD card来更新pynq的包，命令如下：

sudo pip3.6 install --upgrade git+https://github.com/Xilinx/PYNQ.git

Xilinx提供的板载系统中包含Vivado project、bitstream,、SDK project、Python source code以及notebook文件，开发者可以更改，并且鼓励通过Github向官方提交新项目和修正。

pynq Package

所有的PYNQ代码在Github上以python包的形式开源。
基本的模块
- pynq.ps： 促进PS的管理以及PS/PL的接口
- pynq.pl：促进PL的管理
pynq.overlay - Manages the state, drivers, and and contents of overlays.
数据移动模块
- pynq.mmio：实现 PYNQ Memory Mapped IO (MMIO) API
- pynq.gpio：实现 PYNQ General-Purpose IO (GPIO) by wrapping the Linux Sysfs API
- pynq.xlnk：未PYNQ DMA实现存储定位（memory allocation）
中断和异步IO模块
pynq.interrupt - Implements PYNQ asyncio
PYNQ的子包
pynq.lib - Contains sub-packages with drivers for for PMOD, Arduino and Logictools PYNQ Libraries, and drivers for various communication controllers (GPIO, DMA, Video, Audio)

pynq类

PL

PL类通常被作为overlay的内部模块使用. The PL class launches a PL server which manages the loaded overlay. PL服务器可以通过调度管理来防止overlay之间的冲突和覆盖。
The overlay Tcl文件是PL类进行解析的（调用overlay的时间这一解析过程是自动调用PL产生的），来产生IP, clock, interrupts, and gpio dictionaries (lists of information about IP, clocks and signals in the overlay).

PL.timestamp # Get the timestamp when the current overlay was loaded
PL.ip_dict # List IP in the overlay
PL.gpio_dict # List GPIO in the overlay
PL.interrupt_controllers # List interrupt controllers in the overlay
PL.interrupt_pins # List interrupt pins in the overlay
PL.hierarchy_dict # List the hierarchies in the overlay

Bitstream

The Bitstream class这个类是写在pl.py源文件中的（好像Bitstream的属性和方法也可以通过PL调用），也是overlay(Bitstream inherits from this class)的子类，可以用来代替overlay来向PL下载bitstream文件，而且不需要Tcl文件。 还是建议使用Overlay class来使用这些属性。
bitstream可以项板子下载overlay，不需要Tcl文件，慎用。

from pynq import Bitstream
bit_base = Bitstream("base.bit")
bit_base.download()
bit_base.bitfile_name

输出：“base.bit”被下载到板子上，输出其文件路径和文件名

‘/opt/python3.6/lib/python3.6/site-packages/pynq/overlays/base/base.bit’

使用

pynq是集成在一个已经编译好的Linux镜像（precompiled Linux image）中的，从官网下载Linux镜像，然后刻录在一张容量不小于8G的SD card中，经过PYNQ setup就可以在PYNQ-Z1的板子上启动。开发者通过通过TCP/IP协议将主机与版在系统相连，在主机一端可以进行文件系统的访问和编程，编程是通过Jupyter notebook(a browser based interactive computing environment)实现。通过Jupyter notebook开发者可以通过python调用hardware libraries and overlays on the programmable logic。
如果需要添加新的python模块或者封装一个C代码，就必须使用Xilinx或第三方集成开发环境，例如 Xilinx SDK software development environment。另外，The PYNQ-Z1 is fully supported by the free WebPACK version of Xilinx Vivado。

PYNQ precompiled image

pynq的源代码以及SDK software projects和Python-C source codes are also stored along with the Python source code，都在板载系统的/pynq文件夹中。 After installing the pynq package, the compiled target files will be saved automatically into the pynq package.

board files and overlays

All board related files including Vivado projects, bitstreams, and example notebooks, can be found in the /boards folder.
In Linux, you can rebuild the overlay by running make in the corresponding overlay folder (e.g. /boards/Pynq-Z1/base). In Windows, you need to source the appropriate tcl files in the corresponding overlay folder.

pynq的python环境

pynq的python环境是python3.6，在ARM Cortex-A9 处理器上运行，源文中提供了两个例子，一个是计算一个整数范围内的因子和质数，另一个是用nympy和asyncio库与逻辑阵列进行通信。

传统的python编程：因子和质数

Numpy Data Movement

PYNQ中可以利用numpy模块可以实现与PL（programmable logic）之间的数据共享。 我们可以利用python的numpy包在ARM处理器上定义缓冲区，然后将缓冲区的指针送给PL实现数据共享。

Asyncio Integration

PYNQ 也利用Python 的asyncio模块来实现与PL之间的事件通信（或者说中断）。
在PYNQ上运行的Python程序可以使用asyncio库来异步管理多个 IO-bound 任务，从而避免主程序因为慢速的IO系统而阻塞。相反，主程序可以继续执行其他任务，当之前等待的任务需要响应时再返回处理。当然了，再PL端需要一个能够处理中断的器件（interrupt-enabled device are loaded on programmable logic）。

overlay设计

pynq的overlay包括两个组成部分：bitstream文件和project block diagram Tcl文件。
要设计pynq的overlay需要熟悉数字电路硬件设计、编译Zynq系统和Vivado设计工具（应该是the free WebPACK version of Xilinx Vivado）。

overlay Tcl

应该就是整个系统设计的配置文件，IP integrator block diagram。一个定制的手写的Tcl文件可以被用来创建Vivado工程，但是overlay的Tcl文件必须用Vivado导出。
The Tcl from the Vivado IP Integrator block design for the PL design is used by PYNQ to automatically identify the Zynq system configuration, IP including versions, interrupts, resets, and other control signals.
The Tcl file can be generated in Vivado by exporting the IP Integrator block diagram at the end of the overlay design process. The Tcl file should be provided with a bitstream when downloading an overlay. The PYNQ PL class will automatically parse the Tcl.
To generate the Tcl for the Block Diagram from the Vivado GUI:

导出方式

VivadoGUI界面：Click File > Export > Block Design
或者在Tcl控制台中输入以下命令: write_bd_tcl
The Tcl 文件名和bitstream的名字必须匹配。例如， my_overlay.bit and my_overlay.tcl.
The Tcl 在overlay被实例化和下载时被解析。

from pynq import Overlay
ol = Overlay("base.bit") # Tcl is parsed here

overlay的可编程性

一个overlay应该具有post-bitstream可编程性（programmability）来允许系统的定制，现在已经有一些可复用的PYNQ IP模块来支持可编程性。例如，一个PYNQ MicroBlaze 可以被用在Pmod和Arduino接口上，来自多个overlay的IP可以被复用来提供run-time configurability.

Zynq PS Settings

一个Vivado project for a Zynq design包括两部分：the PL design, and the PS configuration settings.
用来启动板子的PYNQ镜像在启动的时间配置了Zynq PS。这将固定住PS 的大部分配置configuration，包括 setup of DRAM, and enabling of the Zynq PS peripherals, including SD card, Ethernet, USB and UART which are used by PYNQ.
The PS 的配置也有包含PL时钟在内的系统时钟。 PL时钟可以在run-time的时间被配置来满足overlay的要求.这是PYNQ Overlay类自动完成的。.在下载一个新的overlay的过程中，时钟配置信息从Tcl文件中读取，新的时钟设置在下载完成之前就被自动配置了。

基础overlay工程

基础overlay可以在PYNQ的源码中找到，可以作为参考设计，也可以重新编译。
/boards/Pynq-Z1/base

PS/PL的interface

AXI(Advanced eXtensible Interface)
The Zynq 在PS和PL之间有9个AXI 接口。在PL一侧，有4x AXI Master HP (High Performance) ports, 2x AXI GP (General Purpose) ports, 2x AXI Slave GP ports and 1x AXI Master ACP port，在他们之间也有GPIO控制器。

HP ports、GP ports、ACP ports以及GPIO和PS以及各级存储器是什么连接关系呢？
有4个pynq的类来管理the Zynq PS (including the PS DRAM) and PL interfaces之间的数据移动：
- GPIO - General Purpose Input/Output
- MMIO - Memory Mapped IO
- Xlnk - Memory allocation
- DMA - Direct Memory Access
使用哪个类取决于PL和PS的接口类型。运行在PYNQ上的Python程序可以通过连接在一个GP端口的AXI从接口访问到IP，MMIO就可以。
连接AXI Master port的IP是不能被PS直接控制的，AXI Master port允许IP直接访问DRAM，在这之前DRAM应该先被定位，Xlnk可以用来做定位。PS的DRAM和PL之间更加高速的数据传输是通过DMA实现的，实现的类是DMA。

GPIO

Zynq PS端有两个连接到PL的32 bit GPIO控制器，PL不需要映射到系统的存储上，通过很简单的方式进行信息传输，例如复位信号和中断信号。

MMIO

Any IP connected to the AXI Slave GP port will be mapped into the system memory map. MMIO can be used read/write a memory mapped location.
适合传输少量数据。

DMA

Xlnk

Xlnk可以用来在内存中定位一块缓存给PL用，PS端也可以直接访问这块缓存。

Interrupt

中断Interrupt

PYNQ MicroBlaze Subsystem

the MicroBlaze soft processors running inside an overlay.