OpenCPI Xilinx ZCU111 Getting Started Guide

Document Revision History

Table 3: OpenCPI ZCU111 Getting Started Guide: Revision History

OpenCPI Version

Description of Change

Date

v2.1

Initial Release

7/2021

v2.4

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+™ ZCU111.

Use this document when configuring the ZCU111 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 ZCU111 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 ZCU111 is a Zynq UltraScale+ Radio Frequency System-on-Chip (RFSoC). See the product brief at https://www.xilinx.com/products/boards-and-kits/zcu111.html for detailed information about the ZCU111.

In OpenCPI, the ZCU111 is called the zcu111 HDL platform.

Installation Prerequisites

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

  • Xilinx ZCU111

  • 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 ZCU111 setup has been tested using a 16GB microSD card)

These items are typically provided with the ZCU111 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 ZCU111 for OpenCPI.

The following items are optional:

  • 1-Gigabit Ethernet cable

  • Analog Devices FMCOMMS2 or FMCOMMS3 daughtercard

Installation Summary

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

Setting up the ZCU111 Hardware

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

Note

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

Configuring the ZCU111 to Boot from an SD Card

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

Figure 6: Xilinx ZCU111: Top View with SD Card Boot Mode Switch Settings

Connecting FMC Daughtercards (Optional)

The ZCU111 has one FPGA Mezzanine Card Plus (FMC+) slot that can be used to connect FMC plug-in modules or daughtercards, as shown in Figure 7:. OpenCPI currently supports two daughtercards that can be installed on the ZCU111:

Figure 7: Xilinx ZCU111: Installed FMCOMMS2

Enabling OpenCPI Development for the ZCU111

This section gives information about the ZCU111 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 ZCU111

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 4: lists the OpenCPI software (RCC) and hardware (HDL) platforms used for the ZCU111 and the third-party/vendor tools on which they depend. The OpenCPI HDL platform name for the ZCU111 is zcu111.

Table 4: Supported OpenCPI Platforms for the ZCU111 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

zcu111

Xilinx Zynq

UltraScale+

RFSoC

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 ZCU111.

  • 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 4:.

Note

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

Note

The ZCU111 system requires the Xilinx Binary Zynq Release 2019.2 (see Table 4:). As a convenience, the OpenCPI Xilinx OSP provides this package for the ZCU111 in the location <path-to-xilinx-osp>/hdl/platforms/zcu111/2019.2-zcu111-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 ZCU111

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 zcu111 platforms for the ZCU111 system.

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

ocpiadmin install platform xilinx19_2_aarch64

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

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 ZCU111.

Installation Steps for the ZCU111 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 ZCU111 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 ZCU111 embedded system requires establishing an Ethernet connection from the ZCU111 to a network that supports DHCP.

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

Figure 8: Xilinx ZCU111: Ethernet Port

Note

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

Setting up the SD Card for the ZCU111

Note

The process of creating a bootable SD card for the ZCU111 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 ZCU111 boots from an SD card. Enabling OpenCPI on the ZCU111 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 ZCU111 for OpenCPI.

Note

The recommended method described in the OpenCPI Installation Guide applies to the ZCU111: 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 ZCU111.

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

The bootable SD card slot is located next to the power switch and the micro-USB serial port, as shown in Figure 9:

Figure 9: Xilinx ZCU111: 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 ZCU111 SD card slot while the ZCU111 is powered off.

Establishing a Serial Console Connection for the ZCU111

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 ZCU111 and the development host.

On the ZCU111 system, the micro-USB serial port is located on the top side of the ZCU111 as shown in Figure 10: and is labeled USB JTAG UART/J83.

Figure 10: Xilinx ZCU111: micro-USB Serial Port

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

The ZCU111 serial USB port operates at 115200 baud.

Configuring the Runtime Environment on the ZCU111

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 ZCU111 embedded system before running any applications.

To boot the ZCU111:

  • Ensure that:

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

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

  • Apply power to the ZCU111.

  • 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 ZCU111

The steps to build the platforms performed in Installing and Building the OpenCPI Platforms for the ZCU111 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.