====== Getting Started with the Genesys ZU ======


===== Unboxing =====
{{:reference:programmable-logic:genesys-zu:unboxing-box.png?600|}}

----

<WRAP group> <WRAP column half>
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:
[[programmable-logic/genesys-zu/reference-manual]]
</WRAP> <WRAP column half>
{{:reference:programmable-logic:genesys-zu:unboxing-hideaways.png?400|}}
</WRAP> </WRAP>

<WRAP group> <WRAP column half>
== 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).
</WRAP> <WRAP column half>
{{:reference:programmable-logic:genesys-zu:unboxing-mis-en-place.png?400|}}
</WRAP>
* 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.)</WRAP>
----
===== Using the Out-of-Box Image =====

Sources for the Out of Box demo can be found on Github:
  * [[https://github.com/Digilent/Genesys-ZU/tree/3eg/oob/master|3EG Out-of-Box]]
  * [[https://github.com/Digilent/Genesys-ZU/tree/5ev/oob/master|5EV Out-of-Box]]


==== 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 [[programmable-logic/genesys-zu/reference-manual|reference manual]].//

  - Connect the power supply.
  - Connect a computer to the USB/PROG port via the provided MicroUSB cable.
  - 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.)
  - Flip the POWER switch to the ON position.
  - Wait for the boot sequence to complete.
  - 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.//

<WRAP round important 660px>
==Important== 
When finished using the Genesys ZU, make sure to safely shut down the OS through the shell. The following command can be used:
<code> shutdown -h now </code>
</WRAP>

----
==== 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//
|<75% 20% 80%>|
^ 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 [[https://www.epochconverter.com/|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: [[https://github.com/Digilent/Genesys-ZU-OS/tree/3eg/oob/master/project-spec/meta-user/recipes-apps/zuca-test-suite/files|zuca-test-suite files]].

----
=== UIO Test Example ===
<WRAP GROUP> <WRAP COLUMN HALF>
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:

<code>for i in {0..4}; do uio-test -t led -i $i -v 1; done</code>
</WRAP> <WRAP COLUMN HALF>
{{:reference:programmable-logic:genesys-zu:oob-uio-test-result.png?400|}}
</WRAP> </WRAP>
----
==== 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 ===
  * Computer running Linux with the following software installed:
    * Vivado 2020.1 with Digilent Board Files:
      * //Installation instructions can be found in this Wiki's [[vivado:installing-vivado:start|Installing Vivado, Xilinx SDK, and Digilent Board Files]] guide.//
      * Make sure that the installation includes support for Zynq Ultrascale parts.
    * Petalinux 2020.1:
      * //Installation instructions can be found in Chapter 2 of Xilinx's [[https://docs.xilinx.com/v/u/2020.1-English/ug1144-petalinux-tools-reference-guide|Petalinux Tools Documentation (UG1144)]]//
  * Github repositories for the Hardware and Software components of the Out-of-Box demo. \\ **Note:** //How to clone these repositories is discussed in further detail below.//
    * [[https://github.com/Digilent/genesys-zu]]
**Important:** //For more information on supported Linux distributions, required dependencies, and other additional requirements, see Xilinx UG1144, linked above.//

  * The original sources used to produce the image found on the SD card shipped with the Genesys ZU-3EG rev B can be found in the commits tagged "3eg-oob_v1.1" in the Genesys-ZU-OOB-hw and Genesys-ZU-OOB-os repositories, linked below:
    * [[https://github.com/Digilent/Genesys-ZU-OOB-hw/tree/3eg-oob_v1.1|Genesys-ZU-OOB-hw (3eg-oob_v1.1)]]
    * [[https://github.com/Digilent/Genesys-ZU-OOB-os/tree/3eg-oob_v1.1|Genesys-ZU-OOB-os (3eg-oob_v1.1)]]
  * The original sources used to produce the image found on the SD card shipped with the Genesys ZU (both variants) rev D can be found under tag "<variant/oob/release/v2.2" in the Genesys ZU repositories, linked below:
    * [[https://github.com/Digilent/Genesys-ZU/tree/3eg/oob/release/v2.2|Genesys-ZU (3eg/oob/release/v2.2)]]
    * [[https://github.com/Digilent/Genesys-ZU/tree/5ev/oob/release/v2.2|Genesys-ZU (5ev/oob/release/v2.2)]]

----
=== Building the Hardware Design ===
<WRAP group> <WRAP column half>
== 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.
<code>git clone https://github.com/Digilent/<repo></code>
Change directory into the cloned repository's directory:
<code>cd <repo></code>
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:
<code>git branch -a
git checkout <branch/tag>
git submodule update --init --recursive
</code>
**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.//
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:clone-hardware.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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:
<code>
source <vivado install directory>/settings64.sh
vivado
</code>
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:create_project.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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:
<code>
source <repo path>/digilent-vivado-scripts/digilent_vivado_checkout.tcl
</code>

</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:generate-bitstream.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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.
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:launch-vivado.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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.
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:export-hardware.png?nolink&600 |}}
</WRAP> </WRAP>
----
=== Configuring and Building the Petalinux Project ===
<WRAP group> <WRAP column half>
== 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:
<code>git clone https://github.com/Digilent/<repo></code>
Change directory into the cloned repository's directory:
<code>cd <repo></code>
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`.
<code>get checkout <branch>
git submodule update --init --recursive</code>
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:os-clone.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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:
<code>source <petalinux install directory>/settings.sh</code>
**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.//
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:petalinux-settings.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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:
<code>petalinux-config --get-hw-description=<hdf directory></code>

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 [[https://docs.xilinx.com/v/u/2020.1-English/ug1144-petalinux-tools-reference-guide|Petalinux Tools Documentation (UG1144)]].
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:petalinux-config.png?nolink&600 |}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 4. Build the Petalinux Project ==
Once any necessary changes have been made, run the following command to build the project:
<code>petalinux-build</code>

This process may take some time; 15-60 minutes depending on the computer used.
</WRAP> <WRAP column half>
{{:reference:programmable-logic:genesys-zu:linux-complete.png?600|}}
</WRAP> </WRAP>
----
<WRAP group> <WRAP column half>
== 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:
<code>petalinux-package --boot --force --fsbl images/linux/zynqmp_fsbl.elf --fpga images/linux/system.bit --u-boot</code>

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.
</WRAP> <WRAP column half>
{{ :reference:programmable-logic:genesys-zu:petalinux-package.png?nolink&600 |}}
</WRAP> </WRAP>
----
=== Running the Rebuilt Image on the Board ===
<WRAP group> <WRAP column half>
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|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.
</WRAP> <WRAP column half>
{{:reference:programmable-logic:genesys-zu:sd-card-slot.png?600|}}
</WRAP> </WRAP>

----
===== 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:
    * [[https://github.com/Digilent/Genesys-ZU/releases/tag/3eg%2Foob%2Frelease%2Fv2.2|Genesys-ZU (3eg/oob/release/v2.2)]]
    * [[https://github.com/Digilent/Genesys-ZU/releases/tag/5ev%2Foob%2Frelease%2Fv2.2|Genesys-ZU (5ev/oob/release/v2.2)]]
 * Instructions for Windows:
  - Click on the link corresponding to your board version, and download the genesys-zu-version.img.gz file, and uncompress it.
  - Download a tool, like [[https://sourceforge.net/projects/sdimager/|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.
  - 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.
  - Select your SD card as SD drive, your uncompressed image file as Image file, and click on the Write button.
  - Wait for the SD Imager to terminate the write, then click on the Exit button.
  - Eject the SD card, unplug it, and put it back into the SD card slot of the board.
* Instructions for Linux:
  - Click on the link corresponding to your board version, and download the genesys-zu-version.img.gz file, and uncompress it.
  - 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.
  - Your card must appear in the /dev/ folder.
  - Copy the uncompressed image file with the dd command:<code>sudo dd if=./genesys-zu-version.img of=/dev/sdc</code>In the command replace sdc with your SD card, and version with your board version.
  - 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 [[start|Resource Center]], on this wiki.

For technical support, please visit the [[https://forum.digilent.com/forum/4-fpga/|Programmable Logic]] section of the Digilent Forums, and its [[https://forum.digilent.com/forum/27-embedded-linux/|Embedded Linux]] subsection.