OpenCPI Xilinx ZCU102 Getting Started Guide

Document Revision History

Table 1: OpenCPI ZCU102 Getting Started Guide: Revision History

OpenCPI Version

Description of Change

Date

v2.1

Initial Release

4/2021

v2.4

Convert to RST, revise for integration with OpenCPI v2.4

7/2022

How to Use This Document

This document provides installation information that is specific to the OpenCPI Xilinx® Zynq® UltraScale+™ ZCU102.

Use this document when configuring the ZCU102 hardware for OpenCPI and when performing the tasks described in the chapter “Enabling OpenCPI Development for Embedded Systems” in the OpenCPI Installation Guide. This document supplies details about enabling OpenCPI development on the ZCU102 that can be applied to the procedures described in the referenced OpenCPI Installation Guide chapter. The recommended method is to have the OpenCPI Installation Guide and this document open in separate windows and refer to this document for any platform-specific details while following the OpenCPI setup tasks described in the Installation Guide.

The following documents can also be used as references for the tasks described in this document:

Note that the OpenCPI Glossary is also contained in both the OpenCPI Installation Guide and the OpenCPI User Guide.

This document assumes a basic understanding of the Linux command line (or “shell”) environment.

Overview

The Xilinx ZCU102 is a Zynq UltraScale+ Multiprocessor System-on-Chip (MPSoC). See the product brief at https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html for detailed information about the ZCU102.

In OpenCPI, the ZCU102 is called the zcu102 HDL platform.

Installation Prerequisites

The following items are required for OpenCPI ZCU102 system installation and setup:

  • Xilinx ZCU102

  • 12V power supply

  • micro-USB to USB-A cable

  • micro-USB to female-USB-A adapter

  • microSD card: use the one that comes with the product kit or provide a different one (OpenCPI ZCU102 setup has been tested using a 16GB microSD card)

These items are typically provided with the ZCU102 product kit.

Note

Ignore any quick start cards or instructions that come with the product kit. This getting started guide and the OpenCPI Installation Guide provide the necessary instructions for setting up the ZCU102 for OpenCPI.

The following items are optional:

  • 1-Gigabit Ethernet cable

  • Analog Devices FMCOMMS2 or FMCOMMS3 daughtercard

Installation Summary

To set up the ZCU102 system for OpenCPI development, perform the following steps:

Setting up the ZCU102 Hardware

This section describes how to set up the ZCU102 hardware for OpenCPI.

Note

Be sure to perform these steps before applying power to the ZCU102.

Configuring the ZCU102 to Boot from an SD Card

By default, the boot mode switch on the ZCU102 is set to boot from the Quad Serial Peripheral Interface (QSPI). Set this switch (SW6[4:1]) to the positions shown in Figure 1: so that the ZCU102 will boot from the SD card. See the section “MPSoC Device Configuration” in the ZCU102 User Guide at https://www.xilinx.com/support/documents/boards_and_kits/zcu102/ug1182-zcu102-eval-bd.pdf for details.

Figure 1: Xilinx ZCU102: Top View with SD Card Boot Mode Switch Settings

Connecting FMC Daughtercards (Optional)

The ZCU102 has two FPGA Mezzanine Card (FMC) High Pin Count (HPC) slots that can be used to connect FMC plug-in modules or daughtercards, as shown in Figure 2:. OpenCPI currently supports two daughtercards that can be installed on the ZCU102:

Figure 2: Xilinx ZCU102: Installed FMCOMMS2

Enabling OpenCPI Development for the ZCU102

This section gives information about the ZCU102 to use when following the instructions in the chapter “Enabling OpenCPI Development for Embedded Systems” of the OpenCPI Installation Guide.

Note

The instructions in the next sections assume that the basic OpenCPI installation for the development host has already been done. If it hasn’t, follow the instructions in the chapter “Installing OpenCPI on Development Hosts” of the OpenCPI Installation Guide before proceeding to follow the instructions in these sections.

Installation Steps for the ZCU102

This section contains information to be applied to the tasks described in the section “Installation Steps for Platforms” of the OpenCPI Installation Guide.

Supported OpenCPI Platforms and Vendor Tools

Table 2: lists the OpenCPI software (RCC) and hardware (HDL) platforms used for the ZCU102 and the third-party/vendor tools on which they depend. The OpenCPI HDL platform name for the ZCU102 is zcu102.

Table 2: Supported OpenCPI Platforms for the ZCU102 and their Dependencies

OpenCPI

Platform Name

Description

OpenCPI

Project/Repo

Required Third-Party/

Vendor Tools

xilinx19_2_aarch64

Xilinx Linux

from 2019Q2 (2019.2)

for Zynq-Ultra

ocpi.core

built-in

Xilinx Vitis™ SDK 2019.2

Xilinx Binary Zynq Release 2019.2

Xilinx Linux git clone

Xilinx Linux tag: xilinx-v2019.2

zcu102

Xilinx Zynq

UltraScale+

MPSoC

ocpi.osp.xilinx

Xilinx Vivado® licensed

Notes about the OpenCPI platforms listed in the table:

  • xilinx19_2_aarch64 is the primary RCC platform for the ZCU102.

  • The xilinx19_2_aarch64 RCC platform is configured for DHCP.

Installing the Vendor Tools for the OpenCPI Platforms

Follow the instructions in the section “Installing Xilinx Tools” in the chapter “Installing Third-party/Vendor Tools” in the OpenCPI Installation Guide to install the Xilinx tools listed as platform dependencies in Table 2:.

Note

Perform this step first, before installing/building the OpenCPI platforms for the ZCU102.

Note

The ZCU102 system requires the Xilinx Binary Zynq Release 2019.2 (see Table 2:). As a convenience, the OpenCPI Xilinx OSP provides this package for the ZCU102 in the location <path-to-xilinx-osp>/hdl/platforms/zcu102/2019.2-zcu102-release.tar.xz. This package can be placed in the /tools/Xilinx/ZynqReleases/2019.2/ (or /opt/Xilinx/ZynqReleases/2019.2/) directory instead of downloading it from the Xilinx website as described in the section “Xilinx Binary Releases for Zynq-7000 and Zynq-Ultrascale Systems” in the OpenCPI Installation Guide.

Installing and Building the OpenCPI Platforms for the ZCU102

After installing the required vendor tools, follow the instructions in the section “Installation Steps for Platforms” in the OpenCPI Installation Guide to install and build the xilinx19_2_aarch64 and zcu102 platforms for the ZCU102 system.

Both these platforms must be installed and built with ocpiadmin install platform before proceeding to set up the SD card for the ZCU102. For example:

ocpiadmin install platform xilinx19_2_aarch64

ocpiadmin --package-id=ocpi.osp.xilinx install platform zcu102

Note

Specifying the --package-id option directs the command to download and build the OSP. See the ocpiadmin(1) man page for command usage details.

Note

The xilinx19_2_aarch64 platform is also used by other systems. If the xilinx19_2_aarch64 platform has already been installed and built for another supported system, it does not have to be reinstalled/rebuilt for the ZCU102.

Installation Steps for the ZCU102 After Its Platforms Have Been Installed

This section contains information to be applied to the tasks described in the section “Installation Steps for Embedded Systems After Their Platforms Have Been Installed” in the OpenCPI Installation Guide.

Connecting the ZCU102 to a DHCP-Supported Network (Optional)

OpenCPI allows three modes of operation on embedded systems: server mode, network mode, and standalone mode (see the beginning paragraphs in the section “Installation Steps for Systems after their Platforms are Installed” of the OpenCPI Installation Guide for details).

Using server mode or network mode for OpenCPI on the ZCU102 embedded system requires establishing an Ethernet connection from the ZCU102 to a network that supports DHCP.

There is one Ethernet port located on the ZCU102, as shown in Figure 3:. Use a 1-Gigabit Ethernet cable to connect this port to the DHCP-supported network.

Figure 3: Xilinx ZCU102: Ethernet Port

Note

Deploying multiple ZCU102s on an Ethernet network requires each ZCU102 to have a unique MAC address. See the OpenCPI Installation Guide for details.

Setting up the SD Card for the ZCU102

Note

The process of creating a bootable SD card for the ZCU102 system requires an SD card reader/writer to be connected to the development host. If you have not done so already, follow the instructions in the section “Using SD Card Reader/Writer Devices” of the OpenCPI Installation Guide to set up an SD card reader/writer before proceeding with this section.

The ZCU102 boots from an SD card. Enabling OpenCPI on the ZCU102 requires creating a bootable SD card that replaces the factory SD card supplied with the product kit.

Follow the instructions in the subsections “Preparing the SD Card Contents”, “Writing the SD Card”, and “SD Card OpenCPI Startup Script Setup” in the section “Installation Steps for Systems After Their Platforms are Installed” of the OpenCPI Installation Guide to create a bootable SD card that enables the ZCU102 for OpenCPI.

Note

The recommended method described in the OpenCPI Installation Guide applies to the ZCU102: make a raw copy of the factory-provided card to a new card, remove the factory-provided content (files and directories) from the raw copy, and then copy the OpenCPI-provided content to the raw copy. OpenCPI provides all of the necessary files for installation and deployment on the ZCU102.

Should you need to format an SD card for the ZCU102, it should be a single FAT32 partition.

The bootable SD card slot is located above the directional pushbuttons, as shown in Figure 4:

Figure 4: Xilinx ZCU102: microSD Card

Once you have finished with this procedure, eject the SD card from the card reader/writer on the development host and insert it into the ZCU102 SD card slot while the ZCU102 is powered off.

Establishing a Serial Console Connection for the ZCU102

Follow the instructions in the section “Establishing a Serial Console Connection” in the OpenCPI Installation Guide to set up a serial console connection between the ZCU102 and the development host.

On the ZCU102 system, the micro-USB serial port is located on the top side of the ZCU102 as shown in Figure 5: and is labeled USB/J83 on the board and USB UART in the vendor documentation.

Figure 5: Xilinx ZCU102: micro-USB Serial Port

Connect the micro-USB to USB-A cable from this port to the development host.

The ZCU102 serial USB port operates at 115200 baud.

Configuring the Runtime Environment on the ZCU102

Follow the instructions in the section “Configuring the Runtime Environment on the Embedded System” in the OpenCPI Installation Guide to verify the runtime environment on the ZCU102 embedded system before running any applications.

To boot the ZCU102:

  • Ensure that:

  • Insert the prepared SD card into the SD card slot on the ZCU102, as shown in Figure 4:.

  • Start a terminal emulator on the development host (usually with the screen command) at 115200 baud.

  • Apply power to the ZCU102.

  • After Linux boots successfully, log in using root for user name and password (note that the password must be supplied twice when using server mode or network mode).

After a successful login, follow the mode-specific instructions in the section to establish the OpenCPI environment. This step applies to network mode and standalone mode only. Server mode does not require the use of a setup script.

Running the Test Application on the ZCU102

The steps to build the platforms performed in Installing and Building the OpenCPI Platforms for the ZCU102 result in a single executable FPGA test application named bias that is ready to run. The bias test application is based on the testbias HDL assembly. Both bias and testbias reside in the ocpi.assets built-in project at applications/bias.xml and hdl/assemblies/testbias/ respectively.

Follow the steps in the section “Running the Test Application” in the OpenCPI Installation Guide that corresponds to the configured operation mode (server mode, network mode, or standalone mode) to run this application to verify the installation and any HDL assemblies of the Xilinx OSP itself.