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

[cathalmccabe]

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 https://github.com/Xilinx/PYNQ

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 http://pynq.readthedocs.io
• 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:
.\PYNQ\boards\Pynq-Z2\base\base\base.runs\impl_1\base_wrapper.bit
The HWH is here:
.\PYNQ\boards\Pynq-Z2\base\base\base.srcs\sources_1\bd\base\hw_handoff\base.hwh

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.

Terminology

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.

[Ari_C]

Hello,

I am trying to do this tutorial with Vivado 2019.2. Everytime I run the command
source ./base.tcl
I get the following error:
catch {common::send_gid_msg -ssname BD::TCL -id 2041 -severity “ERROR” “This script was generated using Vivado <$scripts_vivado_version> and is being run in <$current_vivado_version> of Vivado. Please run the script in Vivado <$scripts_vivado_version> then open the design in Vivado <$current_vivado_version>. Upgrade the design by running "Tools => Report => Report IP Status…", then run write_bd_tcl to create an updated script.”}

Do you know what could be causing this?

[mizan]

As you said, you are using Vivado 2019.2 and the script is written for Vivado 2020.1. You can try changing the version name to 2019.2 in the TCL file (line no. 75). But afterwards there could be errors (not sure).

[Ari_C]

Hello there, me again. Changing the version in the .tcl files to the version of Vivado I am currently using seeimingly fixed the problem with the error message I was getting. However I am now seeing a new error after running the
source ./base.tcl
command

invalid command name “common::send_gid_msg”
while executing
“common::send_gid_msg -ssname BD::TCL -id 2003 -severity “INFO” “Currently there is no design <$design_name> in project, so creating one…””
invoked from within
"if { ${design_name} eq “” } {
#USE CASES:
#1) Design_name not set

set errMsg “Please set the variable <design_name> to a non-empty valu…”
(file “./base.tcl” line 132)

what do I need to do to stop this error from occurring?

I was also wondering if having access to the pattern generator and boolena generator in Vivado would allow for more pins to be used to create patterns.

[changomutney909]

Hello everyone. is it possible to open the 2020.1 tcl script with 2020.2 vivado software? I am unable to find a base overlay version with a tcl script version any higher than 2020.1. is there a repo some where that has up to date versions int?

I have tried simply changing the date in the 2020.1 tcl file to 2020,2.

this allows me to open the file but it doesn’t build the base layer in vivado . is there a list of instructions on how to solve this or should i just ditch the 2020.2 version of xilinx in favour of the 2020.1?

Thank you

[cathalmccabe]

It should be straightforward to update the script. However, PYNQ 2.6 has only been tested with Vivado 2020.1 so you should try stick to this version if you can. You may be able to build the hardware with a different version of Vivado and then find other problems when you try to run the design.

Cathal

[changomutney909]

Ok. I will install xilinx 2020.1.

Thanks for replying so quickly.

[marioruiz]

You can use the branch image_v2.7

GitHub - Xilinx/PYNQ at image_v2.7

Be aware that this branch has not been fully verified.

Mario

[changomutney909]

Thank you mario.

I will use with caution

[devleon]

I just tried building the image_v2.7 branch, as I can’t install Vivado 2020.1 on my Ubuntu 20.04 installation. I have installed Vivado 2020.2, and when executing source ./build_ip.tcl I’m getting the following error:

INFO: [HLS 200-10] Analyzing design file 'color_convert/color_convert.cpp' ... 
ERROR: [HLS 207-812] 'features.h' file not found: /home/leon/xilinx/tools/xilinx-2020.2/Vitis_HLS/2020.2/tps/lnx64/gcc-6.2.0/lib/gcc/x86_64-pc-linux-gnu/6.2.0/../../../../include/c++/6.2.0/x86_64-pc-linux-gnu/bits/os_defines.h:39:10

Any idea what I could do?

Edit: Managed to get the ip to build, I was missing two packages: build-essential and libc6-dev-i386.

However, when running base.tcl, I now get the following error:

# create_root_design ""
FALSE
ERROR: [IP_Flow 19-3188] Error occurred while initializing 'base_clk_wiz_10MHz_0'
Tcl error in update procedure while setting value 'MMCM' on the parameter 'PRIMITIVE'. FALSE

ERROR: [IP_Flow 19-3428] Failed to create Customization object base_clk_wiz_10MHz_0
CRITICAL WARNING: [IP_Flow 19-5622] Failed to create IP instance 'base_clk_wiz_10MHz_0'. Failed to customize IP instance 'base_clk_wiz_10MHz_0'. Failed to load customization data
ERROR: [BD 41-1712] Create IP failed with errors
ERROR: [BD 5-7] Error: running create_bd_cell  -vlnv xilinx.com:ip:clk_wiz:6.0 -type ip -name clk_wiz_10MHz .
ERROR: [Common 17-39] 'create_bd_cell' failed due to earlier errors.

    while executing
"create_bd_cell -type ip -vlnv xilinx.com:ip:clk_wiz:6.0 clk_wiz_10MHz "
    (procedure "create_root_design" line 112)
    invoked from within
"create_root_design """
    (file "./base.tcl" line 4778)
update_compile_order -fileset sources_1

I think I got it working. It seems the error is related to language specific issues.
Changing my Region Format to English (US) as well as setting the following before running vivado seems to have made it work:

export LANG=en_US.UTF-8
export LC_CTYPE="en_US.UTF-8" 
export LC_NUMERIC="en_US.UTF-8"

[SeppeBudenaers]

Hey,
I encountered timing issues when building the base design. I have followed the tutorial like you said just in vivado 2024.1. I even tried to ignore this timing issue but when i load this overlay into Jupiter notebook. and try to use the HDMI out it doesn’t output anything.

I tested the code with base.bit and there it works perfectly. so i assume it is a timing issue like the warnings in vivado said.