Custom PYNQ Image Build Flow

The following article outlines a step-by-step walkthrough for porting the PYNQ platform (Python for ZYNQ) to a custom board. Prerequisites include a Vivado generated and tested base design specifying the Zynq part number and DRAM (if applicable) configuration of the project board.

Setting up the Environment

Before the PYNQ image build process can even start, it is imperative that the correct versioning for the desired image be installed. Ubuntu, Vivado, and Petalinux versions must all align to the corresponding version of PYNQ in order for the build to run successfully. The following table can be used to setup a virtual machine with correct versioning. For my project using the Red-Pitaya 125-10, I choose image_v3.0.1.

In your machines (or virtual machines) terminal, create a new folder to hold the PYNQ project repository, initialize a git environment within that folder, and clone the PYNQ source code files from the link shown below.

$ mkdir <project-name>
$ cd <project-name>
$ git init
$ git clone https://github.com/Xilinx/PYNQ.git

Checkout the repository branch for the version of PYNQ to be built (same as in the table above), then commit and save the changes.

$ git checkout <image-version>
$ git add .
$ git commit -m "initial commit"

The Xilinx provides an automated setup script within this source code that needs to be ran before initiating the project. This script will setup your build enviroment by checking for compatible software versions as well as installing any additional packages not installed on the host. Use the following terminal command to run the script (may require sudo privledges).

$ source <project-name>/PYNQ/sdbuild/scripts/setup_host.sh

It is important that the setup runs successfully in order for the build process to complete later in later steps. The following is a helpful add on to the setup command that logs all generated terminal outputs to a text file. Using this file, you can guarantee there were no errors, and all packages were installed correctly on the host.

$ source scripts/setup_host.sh | tee setup_output.txtSetting up the Board Repository

A custom file structure within the project repository must be created and maintained throughout the build process which describes the boards hardware, processors, device tree, etc. Modify the current project file system to match the following base structure. Each file in holds important information not only for building the PYNQ image, but also for booting the base design at runtime.

Some important notes on the above file structure:

• NAMING! It is important the <board_name> given in the top-level folder be consistent throughout the project as it is constantly referenced in subsequent makefiles and other scripts.
• The base folder should contain the Vivado generated bitsream (.bit) and hardware handoff (.hwh) files. These files are used at boot time to establish an initial design to be loaded onto the programmable logic which is typically some level of verification that all on board components loaded correctly. A python file can also be included in this folder to run a program on this loaded hardware at boot time.
• The packages folder is where new board packages are included to be preinstalled on board when booted or more python scripts can be included to run at boot time on the preloaded hardware. The above boot.py and pre.sh scripts flash all on board LEDs after an ethernet link is established as an example of some of the typical tasks these scripts may carry out.
• The petalinux_bsp folder holds the system-user device tree structure include file (.dtsi) which outlines drivers to be downloaded and instigated in the programming system. Again, it is important that these files and folders are precisely named for the PYNQ compiler to recognize them.
• The <board_name> specification file (.spec) describes important naming and system specifications referenced throughout the makefiles. This file should be syntactically written as follows assuming <board_name> is replaced with the corresponding top folder board name (see below). The STAGE4_PACKAGES_<board_name> is another place to include packages to be installed at boot time. This variable can be utilized as seen below or ignored and packages installed at run time.

After the above file structure is set up and all Vivado generated designs have been included the build process can begin.

Including Prebuilt's

In order to speed up the build process (and since I have never successfully built PYNQ any other way) it is recommended to include a prebuilt PYNQ source distribution and root file system corresponding to the desired PYNQ version. This drastically speeds up the build process and since most boards rely on either Zynq-7000 or Zynq-Ultrascale+ chips is common practice.

Within the PYNQ/sdbuild repository, create a new folder named prebuilt. Inside this folder copy the PYNQ source distribution and PYNQ root file system tar.gz files to this folder. These files for image_v3.0.0 can be found at the following links.

PYNQ_SDIST = https://github.com/Xilinx/PYNQ/releases*assests dropdown*

PYNQ_ROOTFS = http://www.pynq.io/board.html*SD card image*

These files should be renamed as seen below in order for the makefiles to parse them correctly.

Finally... Building the Image

The makefile depends on all Xilinx and Petalinux tools for the build process and therefore must be activated in the current terminal. Navigate to your installation directory of Vivado, Vitis, and Petalinux and run the corresponding settings64.sh/settings.sh scripts within each repository.

$ source <path-to-Xilinx>/<version>/Vivado/<version>/settings64.sh
$ source <path-to-Xilinx>/<version>/Vitis<version>/settings64.sh
$ source <path-to-Xilinx>/<version>/Petalinux/<version>/settings.sh

Navigate back the PYNQ/sdbuild repository, open the boards folder, and delete all other boards besides the desired board folder previously created. The compiler will try to create PYNQ images for all boards in this folder, so this greatly reduces the build process. Locally save these changes before proceeding. Finally, the make command can be run from the PYNQ/sdbuild repo to initiate the build process. The makefile should correctly assume the PYNQ source distribution and root file system are included in a prebuilt folder but if any error occurs, they can be specifically recognized using the following flags.

$ make PYNQ_SDIST=//<path-to-project>/sdbuild/prebuilt/pynq_sdist.tar.gz 
  PYNQ_ROOTFS=//<path-to-project>/sdbuild/prebuilt/pynq_rootfs.arm.tar.gz 
  BOARDS=<board_name> BOARDDIR=//<path-to-project>/boards/<board_name>

After the build process completes all created files will be packaged into an image stored in the following project directory location:

<path-to-project>/sdbuild/output/<board_name>.iso

Trouble Shooting

The build process is quite fragile and more often than not errors will occur. The following outlines the most common and their work arounds / solutions.

1. PYNQ_DIST or PYNQ_ROOTFS files not found error(s)

When this error occurs, it is most likely because the location, or more importantly the naming of the prebuilt source distribution or root file system is incorrect. As referenced before the two files should be located inside of PYNQ/sdbuild/prebuilt/ and labeled pynq_rootfs.<arm/aarch64>.tar.gz and pynq_sdist.tar.gz accordingly.

2. Build stopping after successfully checking environment

My first couple builds (with all flags assigned correctly) led to the build stopping shortly after verifying system packages (about 1 minute into the build). This happens becuase for some reason the makefile searches for board files two folders past the boards folder itself. Instead of correcting the all the referenced makefile paths the easiest workaround is to build the errored structure they are looking for as follows.

As seen above an extra folder layer is added between boards and the included board files named <board_name>... again. This will resolve the early quit error and allow the build process to continue to run.

3. KERNEL_DEVSRC error (late in build process)

If the build process errors out halfway through and produces a kernel-devsrc incomplete error, or something of the sort, this is due to race conditions during the long build process. Either some dependency was not finished installing before it was called, or an online request did not complete in time. The work around for this error follows the Petalinux offline build flow and is outlined well in the following article.

How to build PetaLinux in offline mode - FPGA Developer