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. For more details about the board check the reference manual: Genesys ZU Reference Manual

What comes in the box?
  • Genesys ZU-3EG (or -5EV) (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 (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).

* From version 2020.1 Vivado supports the board, and it can be used via the mini-USB port so the JTAG HS1 is removed from the box. (In older versions of Vivado the board was accessible with this.)


Using the Out-of-Box Image

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

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.

Note: Some boards may contain an empty SD card due to a manufacturing error. If after the 4.-th instruction the boot sequence doesn't start you are in this situation. In this case, please check the Getting the Out-of-Box image section at the end of the page. After doing those steps, you can continue here.

Note: For more information about the board, please check the reference manual.

  1. Connect the power supply.
  2. Connect a computer to the USB/PROG port via the provided MicroUSB cable.
  3. Connect a serial terminal to the serial port associated with the board with a baud rate of 115200. (There will be two serial ports associated with the board, connect to the first one. The second one is for debugging.)
  4. Flip the POWER switch to the ON position.
  5. Wait for the boot sequence to complete.
  6. Log into the board with the username “root” 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. The following command can be used:

 shutdown -h now 

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 1. 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. If the board was connected to internet via cable before trying to connect to wifi and the wlan has a different inet than the cable connection, the attempt to ping will fail because it will try to ping the the old inet(via cable).
pci-bist Checks whether a specific device (Qualcomm QCA6174) is installed in the Mini PCIe slot.
rtc-test Tests the Real Time Clock. Chech this link for the current time since epoch in seconds.
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. The chanels can be seen by listing the /sys/bus/iio/devices/iio\:device0
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. Returns zero in case of success, if the device is connected, otherwise returns a non-zero value and prints a message.
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. Associates the board with the wireless point. The wto parameters are the wifi ssid and password.
zuca-test-suite Wraps the other test scripts for testing in manufacturing. Requires modification to be run by a user. For internal use only.

Further information on these tests can be found by reviewing the test scripts on the board with a built-in text editor and 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 oob/master <branch> or release tag that matches the variant of your board (3eg/5ev), and initialize and update the repository's submodules:

git branch -a
git checkout <branch/tag>
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>/digilent-vivado-scripts/digilent_vivado_checkout.tcl


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 oob/master <branch> or release tag that matches the variant of your board (3eg/5ev). The available remote branches can be listed through the use of `git branch -a`.

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


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 its USB-UART interface.


Getting the Out-of-Box Image

* The Out-of-box image files can be found under tag “<variant/oob/release/v2.2” in the Genesys ZU repositories, linked below:

* Instructions for Windows:

  1. Click on the link corresponding to your board version, and download the genesys-zu-version.img.gz file, and uncompress it.
  2. Download a tool, like SD Imager to write the image file to the SD card. In case of SD Imager, you need to extract the downloaded .zip, and then run SDImager.exe.
  3. Plug in the SD card into your PC (for example via SD card adapter). The SD card is located in the SD card slot, which can be opened by pulling it slightly in the direction of the cooler.
  4. Select your SD card as SD drive, your uncompressed image file as Image file, and click on the Write button.
  5. Wait for the SD Imager to terminate the write, then click on the Exit button.
  6. Eject the SD card, unplug it, and put it back into the SD card slot of the board.

* Instructions for Linux:

  1. Click on the link corresponding to your board version, and download the genesys-zu-version.img.gz file, and uncompress it.
  2. Plug in the SD card into your PC (for example via SD card adapter). The SD card is located in the SD card slot, which can be opened by pulling it slightly in the direction of the cooler.
  3. Your card must appear in the /dev/ folder.
  4. Copy the uncompressed image file with the dd command:
    sudo dd if=./genesys-zu-version.img of=/dev/sdc

    In the command replace sdc with your SD card, and version with your board version.

  5. Eject the SD card, unplug it, and put it back into the SD card slot of the board.

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.