Getting started with Xillinux for Zynq-7000 v2.0

3 Building Xillinux

3.1 Overview

The Xillinux distribution is intended as a development platform, and not just a demo: A ready-for-use environment for custom logic development and integration is built during its preparation for running on hardware. Accordingly, the preparation time for the first test run is a bit long (typically 30 minutes, most of which consist of waiting for AMD’s tools). However this long preparation shortens the cycle for integrating custom logic.

For a successful boot process of the Xillinux distribution from an (Micro)SD card, it must have two components:

• A FAT32 filesystem in the boot partition, consisting of boot loaders, a configuration bitstream for the FPGA part (known as PL), and the binary files for a boot of the Linux kernel.

• An ext4 root file system mounted by Linux.

The downloaded raw image of Xillinux has almost everything set up already. There are just three files missing in its boot partition, one of which needs to be generated with AMD’s tools, and two that are copied from the boot partition kit.

The various operations for preparing the (Micro)SD are detailed step by step in this section.

This procedure consists of the following steps, which must be done in the order outlined below.

• Unzipping the boot partition kit

• Running the implementation of the main PL (FPGA) project

• Writing the Xillinux image to the (Micro)SD card

• Copying three files into the (Micro)SD card’s boot partition

How to work with other boards is discussed in paragraph 5.2.

3.2 Unzipping the boot partition kit

Unzip the previously downloaded xillinux-eval-board-XXX.zip file into a working directory.

The bundle consists of the following directories (or some of them):

• verilog – Contains the project file for the main logic and some sources in Verilog (in the ’src’ subdirectory)

• vhdl – Contains the project file for the main logic and some sources files. The file in VHDL to edit is in the ’src’ subdirectory

• cores – Precompiled binaries of the Xillybus IP cores

• system – Directory for generating processor-related logic

• bootfiles – Contains two board-specific files, to be copied to the boot partition.

• vivado-essentials – Definition files and build directories for processor-related and general-purpose logic for use by Vivado.

There are bundles available for Z-Turn Lite, Zedboard, MicroZed and Zybo boards. If another board is used, the constraints file, vivado-essentials/xillydemo.xdc, must be edited accordingly, in addition to the issues listed in section 5.2.

Note that the vhdl directory contains Verilog files, but none of them should need editing by user.

The interface with the Xillybus IP core takes place in the xillydemo.v or xillydemo.vhd files in the respective ’src’ subdirectories. This is the file to edit in order to try Xillybus with your own data sources and data consumers.

3.3 Generating the bitstream file

3.3.1 Introduction

Vivado generates many intermediate files in a relatively complex structure, which makes it difficult to keep the project under control. In order to keep the file structure in the bundle compact, a script in Tcl is supplied for creating the Vivado project. This script creates a new subdirectory, “vivado”, and populates this directory with files as necessary.

The project relies on the files in the src/ subdirectory (no copies of these files are made). The processor, its interconnect and peripherals, as well as the FIFOs used by the logic are defined in vivado-essentials/, which is also populated with intermediate files by Vivado during the project’s implementation.

The implementation of the project can be based upon Verilog or VHDL.

3.3.2 Selecting the intended Zynq part (Z-Turn Lite only)

This step is required only with the demo bundle for Z-Turn Lite.

Open select_part.tcl in the bundle’s root directory with a text editor. The four last lines of this file are Tcl commands for setting the Zynq part for which the Vivado project is created. These four lines are commented out with a “#” character.

Uncomment one “#” character from one of these lines in order to select the Zynq part on your Z-Turn Lite board.

If you want to use another Zynq part later on, change the Vivado project’s setting accordingly and reimplement the project. select_part.tcl is referred to only during the project’s generation, so making changes to it afterwards has no effect.

3.3.3 Preparing xillydemo.vhd (VHDL project only)

This step is required only if:

• The project is in VHDL

• The demo bundle is intended for any board except Z-Turn Lite.

If both conditions are met, vhdl/src/xillydemo.vhd must be edited: Remove the following three lines in the beginning of Xillydemo’s entity port list:

    PS_CLK : IN std_logic;
    PS_PORB : IN std_logic;
    PS_SRSTB : IN std_logic;

Also, uncomment the following lines in the architecture definition (remove the “--” comment marks):

  -- signal PS_CLK : std_logic;
  -- signal PS_PORB : std_logic;
  -- signal PS_SRSTB : std_logic;

There is no need to make changes in any Verilog source file.

3.3.4 Generating the Vivado project

Start Vivado 2014.4 or later.

With no project open, pick Tools > Run Tcl Script... and choose xillydemo-vivado.tcl in the verilog/ or vhdl/ subdirectory, depending on your preference. A sequence of events takes place for less than a minute. The success of the project’s deployment can be verified by choosing the “Tcl Console” tab at the bottom of Vivado’s window, and verify that it says

INFO: Project created: xillydemo

If this is not the last line of the Tcl console’s output, something went wrong.

There can be Critical Warnings during this stage, but no errors. However if the project has already been generated (i.e. the script has been run already), attempting to run the script again will result in the following error:

ERROR: [Common 17-53] User Exception: Project already exists on disk,
   please use '-force' option to overwrite:

3.3.5 Implementation of the project

After the project has been created, run an implementation: Click “Generate Bitstream” on the Flow Navigator bar to the left.

A popup window, asking if it’s OK to launch synthesis and implementation, is likely to appear – pick “Yes”.

Vivado runs a sequence of processes. This takes normally takes a few minutes. Several warnings are issued, some of which may be classified critical. There should be no errors.

A popup window will appear, informing that the bitstream was generated successfully, giving choices of what to do next. Any option is fine, including picking “Cancel”.

The bitstream file, xillydemo.bit, can be found at vivado/xillydemo.runs/impl_1/.

The implementation is never expected to fail. There are however a few error conditions worth mentioning:

• The Placer fails with “IO placement is infeasible” on a VHDL design. If this happens on an implementation with VHDL, please make sure that xillydemo.vhd was edited as required above.

• write_bitstream fails with DRC errors complaining about PS_CLK, PS_PORB and PS_SRSTB being unspecified, unrouted and unconstrained, then again – please make sure that xillydemo.vhd was edited as required above.

• Error saying “Timing constraints weren’t met”. This can happen when custom logic has been integrated, causing the tools to fail meeting the timing requirements. This means that the design is syntactically correct, but needs corrections to make certain paths fast enough with respect to given clock rates and/or I/O requirements. The process of correcting the design for better timing is often referred to as timing closure.

  A timing constraint failure is commonly announced as a critical warning, allowing the user to produce a bitstream file with which the FPGA’s behavior is not guaranteed. To prevent the generation of such a bitstream, a timing failure is promoted to the level of an error by virtue of a small Tcl script, “showstopper.tcl”, which is automatically executed at the end of a run of route. To turn this safety measure off, click “Project Settings” under “Project Manager” in the Flow Navigator. Choose the “Implementation” button, and scroll down to the settings for “route_design”. Then remove showstopper.tcl from tcl.post.

• Any other error is most likely a result of changes made by the user, and should be handled per case.

3.4 Loading the (Micro)SD with the image

3.4.1 General

The purpose of this task is to write the image file to the (micro)SD card. This file’s name is xillinux-2.0a.img.gz, and it’s downloaded as a compressed file (in gzip format).

This image of the (Micro)SD card, is ready for boot, except for three files, which are added after writing it to the card.

This image should be uncompressed and then written to the (Micro)SD card’s first sector and on. There are several ways and tools to accomplish this. A few methods are suggested next.

The image contains a partition table, a partly populated FAT file system for placing initial boot files, and the Linux root file system of ext4 type. The second partition is ignored by almost all Windows computers, so the (Micro)SD card may appear to be very small in capacity (16 MB or so).

Writing a full disk image is not an operation intended for plain computer users, and therefore requires special software on Windows computers and extra care on Linux. The following paragraphs explain how to do this on either operating system.

If there’s no USB adapter for the (Micro)SD card (or a dedicated slot on a computer), the board itself can be used to write the image, as described in paragraph 3.4.4.

3.4.2 Loading the image (Windows)

On Windows, a special application is needed to copy the image, such as the USB Image Tool. This tool is suitable when a USB adapter is used to access the (Micro)SD card.

Some computers (laptops in particular) have an (Micro)SD slot built in, and may need to use another tool, e.g. Win32 Disk Imager. This may also be the case when running Windows 7.

Both tools are available free for download from various sites on the web. The following walkthrough assumes using the USB Image Tool.

For a Graphical interface, run “USB Image Tool.exe”. When the main window shows up, plug in the USB adapter, select the device icon which appears at the top left. Make sure that you’re in “Device Mode” (as opposed to “Volume Mode”) on the top left drop down menu. Click Restore and set the file type to “Compressed (gzip) image files”. Select the downloaded image file (xillinux-2.0a.img.gz). The whole process should take about 4-5 minutes. When finished, unmount the device (”safely remove hardware”) and unplug it.

On some machines, the GUI will fail to run with an error saying that the software initialization failed. In that case, the command line alternative can be used, or a Microsoft .NET framework component needs to be installed.

Alternatively, this can be done from the command line (which is a quick alternative if the attempt to run GUI fails). This is done in two stages. First, obtain the device’s number. On a DOS Window, change directory to where the application was unzipped to and go (typical session follows):

C:\usbimage>usbitcmd l

USB Image Tool 1.57
COPYRIGHT 2006-2010 Alexander Beug
http://www.alexpage.de

 Device | Friendly Name                     | Volume Name | Volume Path | Size
------------------------------------------------------------------------------
    2448 | USB Mass Storage Device |                           | E:\        | 4024 MB

(Note that the character after "usbitcmd" is the letter “l” and not the number “1”)

Now, when we have the device number, we can actually do the writing (”restore”):

C:\usbimage>usbitcmd r 2448 \path\to\xillinux-2.0a.img.gz /d /g

USB Image Tool 1.57
COPYRIGHT 2006-2010 Alexander Beug
http://www.alexpage.de

Restoring backup to "USB Mass Storage Device USB Device" (E:\)...ok

Again, this should take about 4-5 minutes. And of course, change the number 2448 to whatever device number you got in the first stage, and replace \path\to with the path to where the (Micro)SD card’s image is stored on your computer.

3.4.3 Loading the image (Linux)

As just mentioned, it’s important to detect the correct device as the (Micro)SD card. This is best done by plugging in the USB connector, and looking for something like this in the main log file (/var/log/messages or /var/log/syslog):

Sep 5 10:30:59 kernel: sd 1:0:0:0: [sdc] 7813120 512-byte logical blocks
Sep 5 10:30:59 kernel: sd 1:0:0:0: [sdc] Write Protect is off
Sep 5 10:30:59 kernel: sd 1:0:0:0: [sdc] Assuming drive cache: write through
Sep 5 10:30:59 kernel: sd 1:0:0:0: [sdc] Assuming drive cache: write through
Sep 5 10:30:59 kernel: sdc: sdc1
Sep 5 10:30:59 kernel: sd 1:0:0:0: [sdc] Assuming drive cache: write through
Sep 5 10:30:59 kernel: sd 1:0:0:0: [sdc] Attached SCSI removable disk
Sep 5 10:31:00 kernel: sd 1:0:0:0: Attached scsi generic sg0 type 0

The output may vary slightly, but the point here is to see what name the kernel gave the new disk. “sdc” in the example above.

Uncompress the image file:

# gunzip xillinux-2.0a.img.gz

Copying the image to the (Micro)SD card is simply:

# dd if=xillinux-2.0a.img of=/dev/sdc bs=512

You should point at the disk you found to be the flash drive, of course.

And verify

# cmp xillinux-2.0a.img /dev/sdc
cmp: EOF on xillinux-2.0a.img

Note the response: The fact that EOF was reached on the image file means that everything else compared correctly, and that the flash has more space than actually used. If cmp says nothing (which would normally be considered good) it actually means something is wrong. Most likely, a regular file “/dev/sdc” was generated rather than writing to the device.

3.4.4 Using the Zynq board for loading the image

Paragraph 3.4.3 above described how to load the image with a Linux machine and a USB adapter. The Zynq board itself can be used, running the sample Linux system that came with the board. Basically, the same instructions can be followed, using /dev/mmcblk0 as the destination device (instead of /dev/sdc).

This works fine when the boot process is done from the QSPI flash, as well as with the sample Linux system on an SD card (if such arrived with the board). This is because unlike Xillinux, it runs completely from RAM, and doesn’t use the SD card after boot has finished. So if an SD card was used for boot, it’s possible to pull it out, and insert another for writing the image to.

How to give the Zynq board access to the image of the (Micro)SD and the boot partition files is a matter of preference and Linux knowledge. There are several ways to do this over the network, but the simplest way is to write these files to a disk-on-key, and connect it to the USB OTG port. Mount the disk-on-key with

> mkdir /mnt/usb
> mount /dev/sda1 /mnt/usb

The files on the disk-on-key can then be read at /mnt/usb/.

On Zedboard, make sure that the JP2 jumper is installed, so that the USB port is fed with 5V power supply.

3.5 Copying the files into the boot partition

This final stage places the necessary files for boot:

• Copy boot.bin and devicetree.dtb from the boot partition kit’s bootfiles/ subdirectory, into the (Micro)SD card’s boot partition (the first partition).

• Copy xillydemo.bit that was generated in section 3.3 (from the verilog/ or vhdl/ subdirectory, whichever was chosen).

Before copying these files: If the (Micro)SD’s image was just written to the card, unplug the USB adapter and then connect it back to the computer. If the Zynq board was used for writing the raw image, pull the (Micro)SD card from its slot, and reinsert it.

This is necessary to make sure that the computer is up to date with the (Micro)SD card’s partition table.

On Linux systems, it may be necessary to manually mount the first partition (e.g /dev/sdb1). Most computers will do this automatically.

For example, when the Zynq board itself is used for this purpose, type

> mkdir /mnt/sd
> mount /dev/mmcblk0p1 /mnt/sd

and copy the files to /mnt/sd/.

On Windows systems, plugging in the (micro)SD card will reveal a single “disk”, with a single file, uImage. This is the correct destination to copy the files to.

When done, unmount the (Micro)SD card properly, and unplug it from the computer, e.g.

> umount /mnt/sd

or “remove the disk safely” on Windows.

3.6 The files in the boot partition

Before attempting a boot, please verify that the boot partition is populated as follows.

In order for the boot to be successful, four files need to exist in the (micro)SD card’s first partition (the boot partition):

• uImage – The Linux kernel binary. This is the only file in the boot partition after writing Xillinux’ (Micro)SD image to the card. The kernel is board-independent.

• boot.bin – The initial bootloader. This file contains the initial processor initializations and the U-boot utility, and is significantly different from board to board.

• devicetree.dtb – The Device Tree Blob file, which contains hardware information for the Linux kernel.

• xillydemo.bit – The PL (FPGA) programming file, which was generated in section 3.3