Notebook describing the process of porting to Zybo

Zynq-7000-Porting.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Zynq-7000 Porting Tutorial\n",
    "\n",
    "This document describes how to go about porting the PYNQ software to other boards based on Zynq-7000. It uses the Zybo board as an example but the same steps can be applied to any similar board.\n",
    "\n",
    "## Overview of the process\n",
    "\n",
    "The main task is assembling the required boot files and configurations. In particular we need the following\n",
    " * The processing system configuration\n",
    " * The U-boot version and configuration\n",
    " * The Linux kernel and configuration\n",
    " * A bitstream to load at boot time\n",
    "\n",
    "Once we have the boot files we can reuse most the root filesystem configuration from the PYNQ-Z1 to create the full configuration of the image.\n",
    "\n",
    "## Boot files\n",
    "\n",
    "### config\n",
    "\n",
    "Most of the process of generating the boot files is automated however we need to provide the configurations.\n",
    "\n",
    "First we'll create a new directory in the `boot_configs` directory.\n",
    "\n",
    "Looking through the config file of the PYNQ-Z1-defconfig boot configuration gives us the list of files that we need to provide to complete the port so we'll copy it in as a template and go about modifying it\n",
    "\n",
    "```\n",
    "BOOT_CONFIG_DIR := $(dir $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))\n",
    "BOOT_CONFIG_ABS = $(CURDIR)/${BOOT_CONFIG_DIR}\n",
    "\n",
    "LINUX_REPO ?= https://github.com/Xilinx/linux-xlnx.git\n",
    "LINUX_COMMIT ?= 4e93098735caeb862042d6bf601503666cdc0b69\n",
    "\n",
    "UBOOT_REPO ?= https://github.com/Digilent/u-boot-digilent.git\n",
    "UBOOT_COMMIT ?= e2382ceaffc0c36dc21c01576c1e454af0e01ca1\n",
    "\n",
    "BOARD = Pynq-Z1\n",
    "BOARD_PART = xc7z020clg400-1\n",
    "PS_CONFIG_TCL ?= ${BOOT_CONFIG_ABS}/ps7_config.tcl\n",
    "BOARD_CONSTRAINTS ?= ${BOOT_CONFIG_ABS}/constraints.xdc\n",
    "\n",
    "LINUX_CONFIG ?= ${BOOT_CONFIG_ABS}/kernel.config\n",
    "UBOOT_CONFIG ?= ${BOOT_CONFIG_ABS}/u-boot.config\n",
    "BOARD_DTSI ?= ${BOOT_CONFIG_ABS}/pynq.dtsi\n",
    "\n",
    "include ${BOOT_CONFIG_DIR}/../common/Zynq7000.makefile\n",
    "\n",
    "```\n",
    "\n",
    "The first two lines are boiler-plate code to allow us to access the current directory within the Makefile.\n",
    "\n",
    "The next two lines are the Linux kernel repository and commit to use. This corresponds to the 2016.4 PetaLinux release and we can keep this the same for our port.\n",
    "\n",
    "The next two lines are the u-boot repository to use. The Zybo is supported by the Xilinx repository so we can change this to point at the 2016.4 release of the u-boot from Xilinx, replacing the two lines with:\n",
    "\n",
    "```\n",
    "UBOOT_REPO ?= https://github.com/Xilinx/u-boot-xlnx.git\n",
    "UBOOT_COMMIT ?= 0b94ce5ed4a6c2cd0fec7b8337e776b03e387347\n",
    "```\n",
    "\n",
    "Next we have the `BOARD` variable which  will be used when installing the PYNQ software and appear in the image as an environment variable. This gets changed to `Zybo`. The `BOARD_PART` variable also needs to be updated to `xc7z010clg400-1`\n",
    "\n",
    "There is one other variable that we should add which says which boot bitstream should be used (`BOOT_BITSTREAM`). By default the Makefile will look for the base bitstream of the board and as we don't have one we should give it something else. In this case we'll tell it to use `empty.bit` - a bitstream we'll create later.\n",
    "\n",
    "The rest of the file is just referencing other files in the directory so we will take each one in turn and the last line imports the main Zynq-7000 Makefile which builds the files.\n",
    "\n",
    "The end result is a file that looks like:\n",
    "\n",
    "```\n",
    "BOOT_CONFIG_DIR := $(dir $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))\n",
    "BOOT_CONFIG_ABS = $(CURDIR)/${BOOT_CONFIG_DIR}\n",
    "\n",
    "LINUX_REPO ?= https://github.com/Xilinx/linux-xlnx.git\n",
    "LINUX_COMMIT ?= 4e93098735caeb862042d6bf601503666cdc0b69\n",
    "\n",
    "UBOOT_REPO ?= https://github.com/Xilinx/u-boot-xlnx.git\n",
    "UBOOT_COMMIT ?= 0b94ce5ed4a6c2cd0fec7b8337e776b03e387347\n",
    "\n",
    "BOARD = Zybo\n",
    "BOARD_PART = xc7z010clg400-1\n",
    "PS_CONFIG_TCL ?= ${BOOT_CONFIG_ABS}/ps7_config.tcl\n",
    "BOARD_CONSTRAINTS ?= ${BOOT_CONFIG_ABS}/constraints.xdc\n",
    "\n",
    "LINUX_CONFIG ?= ${BOOT_CONFIG_ABS}/kernel.config\n",
    "UBOOT_CONFIG ?= ${BOOT_CONFIG_ABS}/u-boot.config\n",
    "BOARD_DTSI ?= ${BOOT_CONFIG_ABS}/pynq.dtsi\n",
    "BOOT_BITSTREAM := ${BOOT_CONFIG_ABS}/empty.bit\n",
    "\n",
    "include ${BOOT_CONFIG_DIR}/../common/Zynq7000.makefile\n",
    "```\n",
    "\n",
    "### ps7_config.tcl\n",
    "\n",
    "This file contains the configuration of the processing system and is used for generating the First stage bootloader and device tree. To create it, create an empty project for the board, add the processing system and run block automation if necessary. You should have a design with just the processing system. All AXI interfaces on the PS should be disabled. Double click on the processing system, click presets on the toolbar and then Save Configuration. The configuration can be named anything and the resulting tcl file becomes ps7_config.tcl. While the project is open, we can build a bitstream to create empty.bit\n",
    "\n",
    "### constraints.xdc\n",
    "\n",
    "This isn't needed for the Zybo and can be empty.\n",
    "\n",
    "### kernel.config\n",
    "\n",
    "This file is the Linux kernel configuration to use. In this case we can re-use the same config as the PYNQ-Z1 board but in general the configuration can be obtained by following the instructions provided with the board. Normally this involves cloning a Linux repository and running `make ARCH=arm xilinx_zynq_defconfig`. This will create a plain configuration with all of the devices needed for the chip. The PYNQ framework requires that a couple of additional drivers also be added: the xlnk and uio platform drivers. These can be enabled by being in the Linux source directory and running `make ARCH=arm menuconfig` and enabling Device Drivers->Staging drivers->Xilinx APF Accelerator driver and Device Drivers->Userspace I/O drivers->Userspace I/O platform driver with generic IRQ handling.\n",
    "\n",
    "Once you have a kernel configuration copy .config in the source tree to kernel.config in the boot configuration folder.\n",
    "\n",
    "### u-boot.config\n",
    "\n",
    "This is made in a similar way by cloning the u-boot repository and running `make zynq_zybo_defconfig`. The resulting .config can be copied to u-boot.config. If additional configuration is required it can be done inside the u-boot repository.\n",
    "\n",
    "### pynq.dtsi\n",
    "\n",
    "This file adds the additional drivers needed for the PYNQ software framework. It can be copied from the PYNQ-Z1 configuration.\n",
    "\n",
    "## Root file system\n",
    "\n",
    "The only thing we need to change from the PYNQ-Z1 is the boot_leds script which will not work on Zybo. To create a new rootfs configuration we can copy the rootfs_configs/Pynq-Z1-Wily to rootfs_configs/Zybo-Wily and remove boot_leds from the STAGE3_PACKAGES variable. More details of root filesystem configuration can be found in the packages directory.\n",
    "\n",
    "## Release configuration\n",
    "\n",
    "The final thing we need is a release which is in the releases folder. This is a combination of a boot configuration and rootfs configuration. For the Zybo we will have the Zybo-Wily.config with the two lines\n",
    "\n",
    "```\n",
    "BOOT_CONFIG=Zybo-defconfig\n",
    "ROOTFS_CONFIG=Zybo-Wily\n",
    "```\n",
    "\n",
    "## Building\n",
    "\n",
    "The final stage is to build the whole thing by running `make RELEASE=Zybo-Wily`. This will take several hours and result in a rootfs.img file ready for loading on to an SD card. The boot files can be made separately by running `make RELEASE=Zybo-Wily boot_files` with the files ending up in .build/boot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}