Avnet HDL git HOWTO (Vivado 2020.1 and earlier)

You may know that Avnet provides PetaLinux BSPs and other reference designs for the Xilinx Zynq and Zynq UltraScale+ Zed SOMs (MicroZed, PicoZed, and UltraZed) and development boards (MiniZed and Ultra96), but did you also know that Avnet provides Xilinx Vivado TCL and Linux bash scripts for users to build these designs?  Avnet provides git repositories on github for everything that is needed for users to build and customize these reference designs.  A Xilinx Zynq or Zynq MPSoC design captured and built in Vivado is the hardware platform foundation for any software that will be built to run on it. This blog article will focus on building a reference hardware platform using a Vivado TCL build script from the Avnet "hdl" github repository.

Before we Begin

Bold assumptions:

User is familiar with:

• git commands
• Linux command line
• Xilinx Vivado tools

Software requirements:

• Ubuntu v16.04 LTS 64-bit host OS
• Vivado tools installed and licensed

Hardware requirements:

• A PC with enough RAM to build the design for the target device (https://www.xilinx.com/products/design-tools/vivado/memory.html).  Generally speaking the larger the device, the more RAM that is required.  For example the Avnet UltraZed-EV SOM uses a Zynq UltraScale+ 7EV device (the largest device currently used on any Avnet dev board or SOM) that requires 11GB of RAM to be installed.
• At least 100GB of free disk space (after Xilinx Vivado and other tools have been installed)

Repository Setup

Make the Repositories Folder

The git repositories must be installed into the same parent folder because the build scripts use relative paths to reference their required input files.  Choose a folder where you wish to clone the git repositories and run the scripts.  You will need at least 100GB of free disk space in this folder.  For example, you may wish to clone the repositories into a /home/<user>/git/avnet folder.

$ cd ~

$ mkdir -p git/avnet

$ cd git/avnet

Clone the Repositories

Clone the Avnet "hdl" and "bdf" git repositories.  The "bdf" repository stores the Vivado Board Definition Files (BDFs) that are required to build or open any designs that target a known SOM or development board.  Xilinx provides BDFs for their boards (ZC702, ZCU102, etc.) and includes them in the Vivado installation.  Avnet provides this repository for the BDFs that target their SOMs and dev boards.

$ git clone https://github.com/avnet/bdf.git

The "hdl" git repository stores all of the TCL build scripts and design input files (constraints files, IP sources, etc.).

$ git clone https://github.com/avnet/hdl.git

Checkout the Correct git Branch

As you may know, git uses the concept of branches to separate revision controlled versions of source files.  For a stable repository with not many changes, like the bdf store, all changes can be tracked on the master branch.  For a more dynamic repository, like the hdl store, it makes sense to create branches tied to the version of Vivado tools the build scripts, etc. are meant to work with

$ cd bdf

$ git checkout master

$ cd ../hdl

$ git checkout <2019.1 | 2019.2 | 2020.1>

Repository File Structure

The Avnet "hdl" git repository for Vivado projects contains the following subdirectories:

The Boards folder contains subfolders for each known dev board and SOM & carrier board combination.  In each subfolder are the Vivado design-specific constraints and TCL scripts.  The IP folder contains subfolders of Avnet-created IP that is used in various designs.  The Projects folder contains design-specific subfolders where the Vivado project will be built.  These subfolders contain constraints files, software sources SDK build scripts, and HDL sources.  The Scripts folder and ProjectScripts subfolder contain the board and design-specific TCL build scripts.  This structure has been setup for maximum flexibility in design creation as well as maximum reuse of designs . Avnet has made a commitment to using this structure to implement our designs in order to give our customers a consistent look and feel to our reference designs. This will allow anyone to be able to edit a project to fit their needs.

Anatomy of a Build Script

To get an understanding of what happens when we launch a scripted Vivado build, let's take a look at a sample build script and follow the chain of events that occur.  For this example we will examine the make_ultra96v2_oob.tcl build script.

This script doesn't look like much, but the whole build process starts here.  This script specifies:

• The name of the board we are targeting:  board=ULTRA96V2
• The name of the project we are building:  project=ultra96v2_oob
• Whether or not to also build any standalone software via the Xilinx SDK:  sdk=no
• Whether or not to close the Vivado project when the script completes:  close_project=yes
• Whether or not to check the version of Vivado for compatibility with this design:  version_override=yes
• The device architecture of the target device:  dev_arch=zynqmp

These arguments get passed to the make.tcl file, which will then:

• Examine the arguments to make sure they are valid
• Set the TCL environment variable for the location of the BDF files (relative to the hdl git repository)
• Set environment variables to specify locations of the board, IP and project files
• Launch the project-specific build script in the ProjectScripts subfolder (ultra96v2_oob.tcl)
• Build any specified software via the Xilinx SDK
• Create a git tag if requested

The project-specific build script in the ProjectScripts folder (ultra96v2_oob.tcl) will perform the following:

• Create the Vivado project if it doesn't exist already
• Apply any board-specific project property settings (fetched from the BDF file)

• Generate any Avnet IP blocks used in the design and add them to the design

• Create the Vivado block design and add the Zynq or Zynq UltraScale+ Processing System (PS) block

• Configure the PS with any extra board or project-specific settings (fetched from board-specific Boards subfolder)

• Add any peripherals, IP blocks, AXI interconnect, device I/Os, etc. to the device Programmable Logic (PL) (fetched from board-specific Boards subfolder)

• Import any required design constraints files

• Create the HDL wrapper file and add it to the design

• Run synthesis and implementation to build the design

• Create the archive file for the design (<board>.dsa)

Initialize the Build Environment

Before launching Vivado to run the build script we must first source the shell scripts to set the required environment variables for the Xilinx Vivado and SDK tools.

$ source /opt/Xilinx/Vivado/<Vivado version>/settings64.sh

$ source /opt/Xilinx/SDK/<Vivado version>/settings64.sh

Note!  The <Vivado version> MUST MATCH the git branch that was checkout of the "hdl" repository.

Launch the Vivado Build Script

From the Command Line:

$ cd ~/git/avnet/hdl/Scripts

$ vivado -mode batch -source ./make_ultra96v2_oob.tcl

The build will begin and the terminal window will display the progress as the block design is created and the design is built

Once the build is complete you can open the design in Vivado.

$ vivado &

Click on Open Project in the Quick Start GUI pane and navigate to the Projects/<project>/<board_version> subfolder.

Select the project name and click OK to open to open it.

Follow the steps in Examine the Completed Design below.

From the Vivado GUI:

Launch the version of Vivado that matches the branch checked out of the "HDL" repository and navigate to the TCL Console window.

Navigate to the <>/hdl/Scripts folder.

Launch the build script.

The build will begin and the GUI will display the progress as the block design is created and the design is built.

Examine the Completed Design

Once the Vivado design has finished building you can open the block design to examine how the design was built and customize it for your own needs.

The Value of a Known-Good Design and Starting Point

The key idea behind these TCL build scripts and this "hdl" github repository is to easily create a known-good design targeting an Avnet SOM or dev board quickly, easily, and repeatably.  Being able to start a Xilinx design from a known-good starting point is critical when designing with complex devices like Zynq and Zynq MPSoC.  There are many device PS and PL IP configuration details, from memory controller setup and clocking settings and I/O constraints, etc., that can cause hours and days of anguish to debug if they aren't done correctly.  For the engineers at Avnet these build scripts have the added benefit of providing a starting point when it is time to update a published reference design.  Public users are also welcome to use these repositories and contribute.