OpenCPI Xilinx ZCU104 Getting Started Guide

Document Revision History

Table 4: OpenCPI ZCU104 Getting Started Guide: Revision History

OpenCPI Version

Description of Change

Date

v2.1

Initial Release

2/2025

How to Use This Document

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

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

In OpenCPI, the ZCU104 is called the zcu104 HDL platform.

Installation Prerequisites

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

  • Xilinx ZCU104

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

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

The following items are optional:

  • 1-Gigabit Ethernet cable

  • Analog Devices FMCOMMS2 or FMCOMMS3 daughtercard

Installation Summary

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

Setting up the ZCU104 Hardware

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

Note

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

Configuring the ZCU104 to Boot from an SD Card

By default, the boot mode switch on the ZCU104 is set to boot from the Quad Serial Peripheral Interface (QSPI). Set this switch (SW6[4:1]) to the positions shown in Figure 13: so that the ZCU104 will boot from the SD card. See the section “MPSoC Device Configuration” in the ZCU104 User Guide at https://docs.amd.com/v/u/en-US/ug1267-zcu104-eval-bd for details.

Figure 13: Xilinx ZCU104: Top View with SD Card Boot Mode Switch Settings

Connecting FMC Daughtercards (Optional)

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

Figure 14: Xilinx ZCU104: Installed FMCOMMS2

Enabling OpenCPI Development for the ZCU104

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

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

Table 5: Supported OpenCPI Platforms for the ZCU104 and their Dependencies

OpenCPI

Platform Name

Description

OpenCPI

Project/Repo

Required Third-Party/

Vendor Tools

xilinx24_1_aarch64

Xilinx Linux

from 2024Q1 (2024.1)

for Zynq-Ultra

ocpi.core

built-in

Xilinx Vitis™ SDK 2024.1

Xilinx Binary Zynq Release 2024.1

Xilinx Zynq Headers 2024.1

zcu104

Xilinx Zynq

UltraScale+

MPSoC

ocpi.platform

Xilinx Vivado® licensed

Notes about the OpenCPI platforms listed in the table:

  • xilinx24_1_aarch64 is the primary RCC platform for the ZCU104.

  • The xilinx24_1_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 5:.

Note

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

Note

The ZCU104 system requires the Xilinx Binary Zynq Release 2024.1 (see Table 5:). Download the OpenCPI Xilinx OSP for the ZCU104 using the following link: Prebuilt SD Card Artifacts This package is to be placed in the /tools/Xilinx/ZynqReleases/2024.1/ (or /opt/Xilinx/ZynqReleases/2024.1/) 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.

Download the OpenCPI Xilinx RCC Platform Kernel Headers using the following link: 2024.1 Kernel Headers place the kernel headers package in /tools/Xilinx/ZynqHeaders/2024.1/ (or /opt/Xilinx/ZynqReleases/2024.1/)

Installing and Building the OpenCPI Platforms for the ZCU104

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 xilinx24_1_aarch64 and zcu104 platforms for the ZCU104 system.

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

ocpiadmin install platform xilinx24_1_aarch64

ocpiadmin --package-id=ocpi.platform install platform zcu104

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 xilinx24_1_aarch64 platform is also used by other systems. If the xilinx24_1_aarch64 platform has already been installed and built for another supported system, it does not have to be reinstalled/rebuilt for the ZCU104.

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

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

Figure 15: Xilinx ZCU104: Ethernet Port

Note

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

Setting up the SD Card for the ZCU104

Note

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

Note

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

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

The bootable SD card slot is located below the pushbuttons, as shown in Figure 16:

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

Establishing a Serial Console Connection for the ZCU104

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

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

Figure 17: Xilinx ZCU104: micro-USB Serial Port

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

The ZCU104 serial USB port operates at 115200 baud.

Configuring the Runtime Environment on the ZCU104

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

To boot the ZCU104:

  • Ensure that:

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

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

  • Apply power to the ZCU104.

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

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