Getting Started with the Genesys ZU

Unboxing


Upon opening the box, the MIPI CSI-2 IP Voucher can be found on top of the Genesys ZU, which is placed in an anti-static bag.

The IEC cables, USB cables, JTAG HS1 product kit, and microSD card case can be found underneath the piece of cardboard placed underneath the board (1).

The power supply can be found in the box next to the board (2).

The microSD card can be found in the Genesys ZU's microSD card slot.

What comes in the box?
  • Genesys ZU-3EG (4)
  • 12V, 8A power supply (8)
  • IEC cable with European plug (1)
  • IEC cable with US plug (5)
  • USB A to micro B programming cable (2)
  • USB A to Type C cable (3)
  • JTAG HS1 programmer and cable (6) *
  • microSD card with the Out-of-Box Petalinux Image (loaded into the Genesys ZU's microSD card slot), with a case (7)
  • Voucher for license for Xilinx's MIPI CSI-2 IP cores (not pictured here).

* There is an on-board USB-JTAG controller for which Vivado support is expected in version 2020.1. Once Vivado support is available the JTAG HS1 will not be bundled anymore.


Using the Out-of-Box Image

Sources for the Out of Box demo can be found on Github:

Table 1. Supported Peripherals.

First Boot

Note: At time of manufacturing, the programming mode select jumper is set to “SD”, and the microSD card with the Out-of-Box Petalinux image is placed in the microSD card slot.

  1. Connect the power supply.
  2. Connect a computer to the USB/PROG port via the provided MicroUSB cable.
  3. Flip the POWER switch to the ON position.
  4. Connect a serial terminal to the serial port associated with the board with a baud rate of 115200.
  5. Wait for the boot sequence to complete. If the serial terminal wasn't connected until after the board fully booted, the serial terminal will be blank. In this case, press enter to see the login prompt.
  6. Log into the board with the username and password “root”.

At this point, a command shell with root privileges has been opened into the Out-of-Box demo's PetaLinux OS.

Note: If desired, an SSH connection can be established with the board by connecting it to a router via an ethernet cable. The IP address of the board can be determined by using the command 'ip a' in the serial terminal.

Important

When finished using the Genesys ZU, make sure to safely shut down the OS through the shell.


Running Test Scripts

Several test scripts are built into the OS. These can be found in the /usr/bin directory, and are listed below:

Table 2. Test Scripts

Test Name Description
DP-bist Displays a test pattern over DisplayPort
DP-bist-wrapper Wraps DP-bist to allow it to run in the background
network-bist Tests the network connections through eth0 and wlan0 by bringing the interface up, requesting an IP address through DHCP and pinging the default gateway DHCP gives us. The first argument is the interface to test, `eth0` or `wlan0`. For `wlan0` two more arguments need to be provided, the SSID and PSK of the access point to associate with.
pci-bist Checks whether a specific device (Qualcomm QCA6174) is installed in the Mini PCIe slot.
rtc-test Tests the Real Time Clock
sim-bist Querries the gammu utility for the presence of a SIM card. Needs a cellular modem installed in the Mini PCIe slot.
sysmon Checks the temperature of the FPGA PL or the voltage on the power rails
type-c-dir Displays the orientation of the attached USB Type C cable.
uio-test Tests several AXI GPIO peripherals tied to PL User IOs (LEDs, RGB LEDs, buttons, switches)
usb-bist Tests onboard USB devices to see if they are being enumerated and brought up correctly
usb-reset Resets all connected USB devices by unbinding and binding their drivers. This should also provide a hardware reset to the devices.
wifi-bist Used by the network-bist script.
zuca-test-suite Wraps the other test scripts for testing in manufacturing. Requires modification to be run by a user.

Further information on these tests can be found by reviewing the test scripts on the board with a built-in text editor, or by viewing their sources on GitHub: zuca-test-suite files.


UIO Test Example

The image to the right is the result of running the following command in the serial terminal, which turns on each of the five PL LEDs in sequence:

for i in {0..4}; do uio-test -t led -i $i -v 1; done


Rebuilding the Out-of-Box Image

In order to get access to bugfixes or changes made to the Out-of-Box demo and test scripts, or to view or change the demo, the corresponding repositories must be cloned and rebuilt.

Note: This guide does not discuss the details involved in making changes to the out-of-box projects. Users should refer to the appropriate documentation for the tools and IP used in these designs.

Inventory

Important: For more information on supported Linux distributions, required dependencies, and other additional requirements, see Xilinx UG1144, linked above.


Building the Hardware Design

1. Clone the Vivado Project

Using a terminal, or your git application of choice, clone the Hardware repository (linked in the Inventory section, above) from Digilent's Github.

git clone https://github.com/Digilent/<repo>

Change directory into the cloned repository's directory:

cd <repo>

Next, find and check out the -master <branch> that matches the variant of your board, and initialize and update the repository's submodules:

git branch -a
git checkout <branch>
git submodule update --init --recursive

Note: Digilent uses submodules to bring in additional scripts, sources, and libraries for our repositories. The –recursive switch can be specified when cloning to bring in these submodules, however, if the submodules differ between branches, they must be recursively updated whenever switching branches.


2. Launch Vivado

Launch the Vivado GUI. On Linux, this requires using the terminal to source the settings64.sh script, found in Vivado's installation directory, followed by invoking the `vivado` command:

source <vivado install directory>/settings64.sh
vivado


3. Create the Vivado Project

In the TCL console at the bottom of the Vivado window, use the following command to recreate the Vivado project from its sources, where <repo path> represents the full path to the cloned repository:

source <repo path>/proj/create_project.tcl

Note: An additional script, cleanup.sh, has been been placed in the proj directory of the repository. This script can be used to delete project files to return the proj directory to a state where the project can be recreated from source again.


4. Build the Vivado Project

With the project created and open, the Vivado IP Integrator design that defines the hardware can be explored.

To rebuild the design, click the Generate Bitstream button, found at the bottom of the Flow Navigator.

In the No Implementation Results Available dialog, click Yes to launch Synthesis and Implementation.

In the Launch Runs dialog, choose a number of jobs to use, and click OK.

Note: The number of jobs specifies how much of the system's resources will be dedicated to the build. The more jobs used, the faster the build will be completed.

Wait for the runs to be completed. When finished, the indicator at the top right corner of the window will display “write_bitstream completed”. This process may take some time.


5. Export Build Outputs

Lastly, the build outputs must be exported from Vivado for use by Petalinux. In the menu at the top of the window, select File → Export → Export Hardware.

In the dialog that pops up, choose a directory to export the Hardware Definition File (HDF) to, make sure to include the bitstream, then click OK. Take note of the directory the HDF has been placed within, as it can optionally be imported into the Petalinux project.


Configuring and Building the Petalinux Project

1. Clone the Petalinux Project

Using a terminal, or your git application of choice, clone the Petalinux project repository linked in the Inventory section above, from Digilent's Github:

git clone https://github.com/Digilent/<repo>

Change directory into the cloned repository's directory:

cd <repo>

Check out the -master <branch> that matches the variant of your board. The available remote branches can be listed through the use of `git branch -a`.

get checkout <branch>


2. Initialize Petalinux

In the terminal, set up Petalinux using the command below, where <petalinux install directory> represents the directory that Petalinux was installed into:

source <petalinux install directory>/settings.sh

Note: Running this command is required in any terminal session where Petalinux will be used. If desired, it is possible to add this command to the system's bash initialization scripts, as can be seen in the screenshot to the right.


3. Petalinux Project Configuration (Optional)

Important: The information presented in this step briefly details some petalinux commands that may be helpful. None of these commands are required to build the image.

A newly generated HDF file can be loaded into the project with this command, where <hdf directory> represents the directory that the HDF file was exported into from Vivado:

petalinux-config --get-hw-description=<hdf directory>

While building, the Petalinux project writes the necessary files into the tftpboot directory. This allows tftp (Trivial File Transfer Protocol) to be used to boot the board over a UART connection with minimal user effort. It should be noted that if TFTP is not installed on the system, some warning messages may be generated during the build process.

Any changes in Vivado to the set of IP connected to the processor over AXI require that the system-user.dtsi file be edited to associate the connected IP with compatible drivers.

Additional information on what can be changed and how can be found in Xilinx's Petalinux Tools Documentation (UG1144).


4. Build the Petalinux Project

Once any necessary changes have been made, run the following command to build the project:

petalinux-build

This process may take some time; 15-60 minutes depending on the computer used.


5. Package the Build Outputs

Once the project has been built, the FSBL, FPGA bitstream, PMU firmware, and U-Boot must be packaged into a single binary which can be used to boot the board. This binary is named “BOOT.bin” and can be generated with the following command:

petalinux-package --boot --force --fsbl images/linux/zynqmp_fsbl.elf --fpga images/linux/system.bit --u-boot

BOOT.bin is placed within the project's `images/linux` directory when the packaging command has finished running. The other file required for boot, image.ub, can be found in the same directory.


Running the Rebuilt Image on the Board

A microSD card used to boot Petalinux must first be formatted with a FAT32 filesystem, and the build outputs BOOT.bin and image.ub must be placed within the first partition. A variety of techniques can be used to accomplish this, for example, the dd command command can be used to format the card.

Once the SD card has been installed, the board can be booted as seen in the Using the Out-of-Box Image seciton of this guide. Make sure that the programming mode select jumper has been set to “SD”, power on the board, and connect a serial terminal to it through it's USBUART interface.


Final Thoughts

More information on the Genesys ZU can be found in its Resource Center, on this wiki.

For technical support, please visit the Programmable Logic section of the Digilent Forums, and its Embedded Linux subsection.