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

Learn
1

Rebuilding the PYNQ base overlay

NOTE: There is a newer version of this tutorial here (PYNQ v2.6, Vivado 2020.1).

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.
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 code from the PYNQ v2.3 release and Vivado 2018.2

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

Alternatively, a Zip of the repository can be downloaded from GitHub if you don’t use Git:

download_github_zip
download_github_zip800Ă—480 46.4 KB

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

This tutorial will use the files in the boards folder.

PYNQ supports 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.

pynq_boards_folder
pynq_boards_folder695Ă—258 12.4 KB

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-Z1 board. The base overlays for other boards can be rebuilt in a similar way.

Rebuild the base design

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).

pynq_ip_folder
pynq_ip_folder695Ă—413 21.9 KB

Before HLS IP can be used in a Vivado design, the base design in this case, the HLS IP must be built or compiled.

Build required IP

  • Open Vivado (2018.2)

vivado
vivado801Ă—601 48.9 KB

A TCL script is provided to rebuild the HLS IP required for this design. (./boards/Pynq-Z1/base/build_base_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. 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.

A second Tcl file, ( ./pynq/boards/Pynq-Z1/basebase.tcl) will be used to create a new Vivado project, generate the base overlay design, and compile it to generate the bitstream.

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

   cd <PYNQ repository>/boards/Pynq-Z1/base
   source ./build_base_ip.tcl

pynq_build_hls_ip
pynq_build_hls_ip800Ă—600 95.3 KB

The base.tclwill generate a bitstream, which may take some time depending on the computer that you are using. If you want to create the design without compiling and generating the bitstream, find the following line in the base.tcl file and comment it out. (Remember the compiled bitstream is already on your board, so it isn’t necessary to rebuild it.)

launch_runs impl_1 -to_step write_bitstream -jobs 4

Execute the following command in the Tcl console.

   source ./base.tcl

If you chose not to generate the bitstream in the Tcl file, you can generate it later in Vivado by clicking on the Generate Bitstream button.

The base overlay is already installed in the PYNQ image for the PYNQ-Z1/PYNQ-Z2 boards. If this was a new overlay, the .bit and .tcl could be copied to the board. This will be covered in a later tutorial.

The block design for the base overlay should now be created.

pynq_base_design
pynq_base_design1316Ă—750 52.3 KB

The base design contains a large number of IP blocks and design elements which will be explored in the next tutorial.

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 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.

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.

5 Likes
2

Like it.

This should be

source ./base.tcl

in order to avoid confusion.:slight_smile:

3

Thanks @rock! Fixed.

4

I used the same procedure for rebuilding base overlay for zedbaord, but ended up with IO mismatch errors at the implementation phase. I modified base.tcl and build_base.tcl to match the device on Zedboard.Does it need an xdc?

5

Yes, the Zedboard has different pin mappings. You can modify the XDC, or assign pins in the Vivado GUI. Do you know where to find this info? (In the XDC for Zedboard, or in the user guide) and do you know how to apply the settings?

Cathal

6

Yes, done! Thanks that works.

8

Hi, I clone the PYNQ repo through:
git clone GitHub - Xilinx/PYNQ: Python Productivity for ZYNQ
But couldn’t find
launch_runs impl_1 -to_step write_bitstream -jobs 4
in base.tcl file.
could anyone tell me why ?

9

This has been updated slightly since the tutorial was written.
base.tcl doesn’t build the bitstream anymore.
This step was separated into build_bitstream.tcl

The reason for this was that creating the bitstream takes some time. If you only want to look at the Vivado project, you shouldn’t need to wait for the bitstream to be built.
base.tcl now only creates the project (without building the bitstream).

The makefile now has some extra options. You can run make with the option you want, or you can run the build_bitstream.tcl from the Vivado Tcl prompt.

Cathal

1 Like
10

thank you ~
I just found there’s no “launch_run …” command since V2.4.

11

There is also a makefile which you can use in the overlay folder.

make

will get you the entire project with bitstream done.

make hls_ip block_design

will get you the project without implementation.

2 Likes
12

I git down the image_v2.2, and rebuild the base in my vivado2017.4, but when i source the base.tcl, some errors occured:
[BD 41-145] Parameter S_AXI.PROTOCOL not found on block timer_1
all about the timer_1.so how can i work it well? thanks.

14

Hi! Can you please make a new tutorial or modify this one?

build_base_ip.tcl not longer exists.

15

Updated for v2.6 here: https://discuss.pynq.io/t/tutorial-rebuilding-the-pynq-base-overlay-v2-6/1993?u=cathalmccabe
I’ll edit the tutorial to add this link at the top.

Cathal