Tutorial: Rebuilding the PYNQ base overlay (PYNQ v2.6)

Rebuilding the PYNQ base overlay

PYNQ v2.6, Vivado 2020.1

Note: This is a update to an earlier version (v2.3, Vivado 2018.2) of this tutorial.

The base overlay for the PYNQ-Z1 and PYNQ-Z2 boards allows peripherals to be used out-of-the-box with PYNQ. The overlay includes IP for controlling HDMI, Audio, GPIO (LEDs, buttons and switches) and slave processors for controlling Pmod, Arduino, and RaspberryPi peripherals. It is not necessary to build the overlay, as the compiled design is already preloaded in the PYNQ image. However, recreating the Vivado design will allow you to explore the base design and modify it for your own use. For example, you may want to remove all but the Video IP, and add your own custom filters, or keep the IOPs and add additional logic to your design.

The PYNQ repository includes the source code and IP for the base overlay. Hardware designers may want to modify or reuse parts of the base overlay design.

This tutorial will show how to rebuild the PYNQ base overlay for the PYNQ-Z1/PYNQ-Z2 boards. This tutorial uses Vivado 2020.1 and code from the PYNQ v2.6 release.

Clone the PYNQ repo

Start by cloning the PYNQ GitHub repository. (Or you can fork it to your own repository and clone your fork.)

git clone

If you don’t want to use git, you can download a Zip file of the repository from GitHub:

The PYNQ repository contains the following directories:

  • boards - board specific source code, including the Vivado project sources for the base overlay
  • docs - sources for the PYNQ documentation on
  • pynq - the core PYNQ Python and other source code
  • sdbuild - source code and instructions for rebuilding the PYNQ image
  • tests - used for automated testing of the pynq codebase

This tutorial will use the files in the boards folder.

PYNQ provides direct support for three main boards, PYNQ-Z1, PYNQ-Z2, ZCU104. In the boards directory, you will see a corresponding directory for each board, along with an ip directory and a sw_repo directory.

The Xilinx Vivado software contains a library of IP that can be used for building new designs. The PYNQ ip directory contains additional custom IP that isn’t available in the main Vivado IP library. For example, the IP for the HDMI controllers for the PYNQ-Z1 and PYNQ-Z2 can be found in the ip directory.

The sw_repo directory contains software source code related to overlays. For example, PYNQ can use MicroBlaze soft processors in the fabric. Source code for MicroBlaze applications is specific to overlays, and is included here, rather than in the main pynq Python directory at the top level of this repository.

This tutorial will concentrate on the base overlay for the PYNQ-Z2 board. The base overlays for other boards can be rebuilt in a similar way.

Rebuild the base design

A Makefile is provided that can be used to rebuild the base overlay on Linux by running make all in the base directory. Make sure you have sourced the correct version of VIvado before running make.

The Makefile launches Vivado and calls some Tcl scripts to build the base overlay. Windows doesn’t support make. To rebuild the base overlay you can execute the Tcl files from Vivado manually. This is also a good opportunity to explain how the build process works, and explain what the Tcl files are!

The base overlay is built from IP in the Vivado catalog, and IP in the ip directory. Some of the PYNQ IP is based on HDL code and other IP is provided as HLS source code (notice the hls directory).

Before HLS IP can be used in a Vivado design, the base design in this case, the HLS IP must be built. If it is useful, you can reuse any of the PYNQ IP for your own designs.

Build required IP

  • Open Vivado (2020.1)

A build_ip.tcl TCL script is provided to rebuild the HLS IP required for this design. (./boards/Pynq-Z1/base/build_ip.tcl)

This script will only build IP in the ip/hls directory that is required for the base overlay. It also checks if the IP has already been build and skips any IP that is built or not required… This means if you need to use the IP in another design, or want to rebuild the base overlay later, the IP won’t be recompiled, saving some time.

To run the Tcl files, enter the following commands in the Vivado Tcl console:

   cd <PYNQ repository>/boards/Pynq-Z2/base
   source ./build_ip.tcl

The base.tcl file (./pynq/boards/Pynq-Z2/base/base.tcl) will be used to create a new Vivado project, generate the base overlay design. In a change from previous versions of PYNQ, the Vivado design is created, but the bitstream will not be generated during this step. This allows you to review or study the design. It isn’t necessary to generate the bitstream for the base design, as it is already provided precompiled in the PYNQ image. You can make changes to the base design and then build the bitstream.

   source ./base.tcl

The base overlay bitstream is already installed in the PYNQ image for the PYNQ-Z1, PYNQ-Z2 and ZCU104 boards, so you don’t need to rebuild it. If you *really* want to rebuild it, you can click the Generate Bitstream button in the Vivado GUI. The build_bitstream.tcl Tcl file (./pynq/boards/Pynq-Z2/base/build_bitstream.tcl) can also be used to generate the bitstream if you want to continue using scripts. Note that this process can time some time (~30-60 minutes) depending on the specification of the computer you are building the design on. There are also some Vivado settings you can change to speed this up if you only want to build this design once. By default the design has out-of-context switched. The first build will take longer, but if you make iterative modifications to the design rebuilding should be faster.

If this was a new overlay, you would build the design. The generated .bit and .hwh would be copied to the board.
For reference, the bitstream is here:
The HWH is here:

The check_timing.tcl Tcl file (./pynq/boards/Pynq-Z2/base/check_timing.tcl) can be used to check your design meets timing. If you are familar with Vivado, you can open your project and analyze the timing and the rest of your implementation in Vivado. .

   source ./build_bitstream.tcl
   source ./check_timing.tcl

If you chose not to generate the bitstream using the Tcl file, you can generate it later in Vivado by clicking on the Generate Bitstream button. You can also analyze timing in Vivado, and the rest of your implementation.


Vivado - Xilinx software for building hardware designs for Zynq

IP - Intellectual Property - hardware blocks that implement a function. IP blocks can be reused to create new hardware designs.

git - version control application and system

IP-XACT - an XML format for IP that defines and describes individual blocks. Xilinx IP in Vivado is based on this format. IP-XACT makes it easier to use IP to create new designs.

VHDL and Verilog are hardware description, or hardware design languages used to create hardware.

HLS - High Level Synthesis allows hardware designs to be created by describing them using higher level languages (mainly C/C++) instead of VHDL or Verilog.