Difference between revisions of "Xilinx ZCU102"

Revision as of 00:37, 25 September 2020

Xilinx ZCU102 Board Setup

Zynq UltraScale+™ MPSoC device has a quad-core ARM® Cortex-A53, dual-core Cortex-R5 real-time processors, and a Mali-400 MP2 graphics processing unit based on Xilinx's 16nm FinFET+ programmable logic fabric. The Xilinx ZCU102 supports all major peripherals and interfaces enabling development for a wide range of applications. The boot image can be put into Flash or SD card and in this tutorial we describe the steps for booting from SD card. The board configuration has to be switch for SD boot as shown in the following picture (for more details please refer to the section "ZCU102 board setup " of the Xilinx manual).

Xilinx ZCU102 evaluation board.

Configuration for SD boot.

Prebuilded SD images can be found in the Xilinx repository and the SD card setup can be performed as follows:

1. Mount the SD card on your host machine.
2. Flash the downloaded image into the SD card:
   $ dd if=<file image> of=/dev/sdX bs=8M && sync

The SD card will contain two partitions:

• the first partition, referred to as ROOT, contains the bootloader, u-boot, device-tree and kernel image. More in detail, the boot images (i.e., BOOT.BIN and uImage.ub) will be installed in the root directory of the BOOT partition.
• the second partition, referred to as ROOT1, stores the system root filesystem.

Compilation tools setup

PetaLinux tool

Xilinx provides the tools in order to customize, build and deploy embedded Linux solutions on Xilinx processing systems. Such tools consists a set of pre-configured binary bootable images, fully customizable Linux for the Xilinx devices, and PetaLinux/Xilinx Vivado SDK. The Xilinx Vivado (with SDK) is used to define the hardware design of the related board, whereas the PetaLinux SDK includes tools and utilities to automate complex tasks across configuration, build, and deployment. The PetaLinux tools aim to configure, build and deploy a booting image for the Xilinx board on the basis of the hardware design file (HDF) or Board Support Packages (BSP).

Download the Petalinux 2019.1 installer from https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html.

PetaLinux requires a number of standard development tools and libraries to be installed on the host workstation. Install the libraries and tools listed in the Petalinux tool reference guide. It follows the commands used to install a subset of the Petalinux 2019.1 dependencies.

  $ sudo apt install bash zlib1g:i386 gcc-multilib socat chrpath
  $ sudo apt install autoconf libtool-bin texinfo zlib1g-dev
  $ sudo unlink /bin/sh
  $ sudo ln -s /bin/bash /bin/sh

PetaLinux installation is very straight-forward. Without any options, PetaLinux tools will be installed into a subdirectory of the current working directory. Alternatively, an installation path may be specified. Example of PetaLinux tools 2017.2 installation in the /opt/pkg directory:

$ mkdir /opt/pkg
$ ./petalinux-v2019.1-final-installer.run /opt/pkg

In order to setup the PetaLinux working environment, it is required to source the appropriate settings script (e.g., from a bash shell):

$ source /opt/pkg/2019.1/settings.sh

Cross-compiler

TODO

Linux kernel build

In the following part of the section, we give an overview on how to create a new PetaLinux project and build the kernel and the boot image for the referred board.

Petalinux project

Download the Board Support Packages (BSP) for Petalinux 2019.1 xilinx-zcu102-v2019.1-final.bsp

Create a PetaLinux project for the referred BSP:

$ petalinux-create -t project -s <path/to/the/bsp>/xilinx-zcu102-v2019.1-final.bsp
$ cd xilinx-zcu102-2019.1

Launch the top system configuration menu by running the following command:

$ petalinux-config

Enable the SD boot `Root filesystem type (SD card)`

Image Packaging Configuration--->Root filesystem type-->SD card

Configure Linux

In order to run Jailhouse module, the Linux kernel needs to be configured as follows. Launch the kernel configuration menu by running the following command:

$ petalinux-config -c kernel

Include all symbols in kallsyms (CONFIG_KALLSYMS_ALL):

 General setup --> Configure standard kernel features (expert users) --> Load all symbols for debugging/ksymoops --> Include all symbols in kallsyms

Enable the Device Tree overlays (CONFIG_OF_OVERLAY):

 Device Drivers --> Device Tree and Open Firmware support (OF [=y]) --> Device Tree overlays

Build the kernel

Build and create the boot image:

$ petalinux-build
$ petalinux-package --boot --fsbl images/linux/zynqmp_fsbl.elf --u-boot images/linux/u-boot.elf --force

Note that the built images BOOT.BIN and uImage.ub are saved in <petalinux-project-root>/images/linux.

Install boot images and modules

Flash the SD with the prebuilt Ubuntu image, overwriting image.ub and BOOT.BIN with the copies available in images/linux/

$ cp -v images/linux/BOOT.BIN images/linux/image.ub  /media/ida/ROOT/

Install the modules:

$ sudo cp -av build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.19-xilinx-v2019.1+gitAUTOINC+9811303824-r0/image/lib/* /media/ida/ROOT1/lib/

Jailhouse hypervisor

As for jailhouse installation on Xilinx ZCU102, we refer to Jailhouse v0.7 on the GitHub repository. The commands to checkout at such version are the following:

$ git clone https://github.com/siemens/jailhouse 
$ cd jailhouse
$ git checkout v0.7 -b xilinx_jailhouse

For building and installing Jailhouse, first setup the environment by simply setting the PetaLinux working environment:

$ source /opt/pkg/2017.2/settings.sh

Furthermore, Jailhouse compilation requires a copy of the compiled Linux kernel with all object files. We refer to the path of such folder as <path to compiled kernel> that is typically stored in the petalinux project (e.g., <petalinux project>/build/tmp/work/plnx_aarch64-xilinx-linux/linux-xlnx/4.9-xilinx-v2017.2+git999-r0/linux-xlnx-4.9-xilinx-v2017.2+git999/).

Create the configuration file for the ZCU102 board (e.g., jailhouse-config-xilinx-zcu102.h):

#define CONFIG_TRACE_ERROR             1
#define CONFIG_ARM_GIC_V2              1
#define CONFIG_MACH_ZYNQMP_ZCU102      1

Copy the file into <jailhouse directory>/hypervisor/include/jailhouse directory and rename it to config.h

Build and install jailhouse as follows:

$ make clean
$ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- KDIR=<path to compiled kernel> DESTDIR=<destination directory> install

where <path to compiled kernel> is the path of folder containing the compiled kernel in the petalinux project and <destination path> is typically the file-system root of the SD card.

In order to enable jailhouse, copy the zcu102 root cell (i.e., <jailhouse directory>/configs/zynqmp-zcu102.cell) on the SD card file-system.

Build ERIKAv3 for Jailhouse

The main steps to create and build ERIKA v3 jailhouse inmate are the following:

• download and install RT_DRUID that includes ERIKA v3 as Eclipse plugin.
• create and build a new RT-Druid v3 Oil and C/C++ project containing the main application running on ERIKA v3 (i.e., source files and the oil file containing the configuration for the referred board)
• install the generated binaries into the board

RT-Druid can be downloaded using the download web page. Notice that to download RT-Druid, you have to accept the RT-Druid and the ERIKA v3 licenses. The ERIKA v3 license is a GPL v2, whereas the RT-Druid license is a proprietary license that allows you to use the provided version of RT-Druid at no cost.

RT-Druid requires Java Standard Edition version 8, or newer.

RT-Druid is provided as a compressed archive, which can be unpacked in your user directories. RT-Druid has ERIKA v3 source code as Eclipse plugin and the default path is <RT-Druid folder>/eclipse/plugins/com.eu.evidence.ee3_<version number>/ee_files/. However, it is possible to change the RT-Druid configuration in order to refer to another ERIKA 3 source code. For more details about RT-Druid configuration, see the RT-Druid configuration wiki page.

Before starting RT-Druid, setup the environment by setting the variables JAILHOUSE_DIR and JAILHOUSE_AARCH64_GCCPREFIX as follows:

$ export JAILHOUSE_DIR=<path of the jailhouse directory>
$ export JAILHOUSE_AARCH64_GCCPREFIX=aarch64-linux-gnu-

Furthermore since we refer to Jailhouse v0.7 for Xilinx ZCU102, set the environment variable JAILHOUSE_VERSION as follows:

$ export JAILHOUSE_VERSION=0.7

Finally, in order to cross-compile setup the PetaLinux working environment:

$ source /opt/pkg/2017.2/settings.sh

Then, launch eclipse application located into the eclipse folder extracted from the RT-Druid Package.

As for example, we create a simple "helloworld" application consisting of two tasks printing on the serial interface.

1. Run the RT-Druid tool as explained above.
2. Create a new project by clicking on New → RT-Druid v3 Oil and C/C++ Project as shown in the next Figure:
   

   Figure 1: Create a new RT-Druid project.
3. In the RT-Druid C/C++ Project Wizard name the new project (e.g., mytest) and select the Cross-GCC as shown in the next Figure:
   

   Figure 2: Naming the new RT-Druid project.
4. Check the box for using an existing template and select aarch64 → Jailhouse → Helloworld OSEK demo on Jailhouseas shown in the next Figure:
   

   Figure 3: Selecting the Helloworld template.
5. Eclipse will then show the new project, and RT-Druid will generate the configuration files, as shown in the next Figure:
   

   Figure 4: New Helloworld project created.
6. Modify the conf.oil file as follows:
   

   line 69: /* SOC_DATA = NVIDIA_TEGRA_X1; */
   line 70: SOC_DATA = XILINX_ZYNQ_ULTRASCALE_PLUS;
   

To build an RT-Druid Project, right-click on your project, as example mytest, shown in the Eclipse Project Explorer panel, and then click on Build Project context-menu entry. The compilation process will generate the following directories:

• erika - It stores all the files related to ERIKA v3
• out - It stores all the files related to the application, included the final binaries

In particular, the out directory will contain the following files:

• applSignature.oil - the application OIL signature, which is basically the OIL file re-exported by the tool
• ee_applcfg. - the application configuration generated by RT-Druid
• makefile - the main application makefile
• erika_inmate.bin/elf - the ERIKA v3 binary containing the application

Note that to completely clean the project by removing either generated and compiled files (i.e., erika and out folders), right-click on your project, as example mytest, shown in the Eclipse Project Explorer panel, and then click on Clean Erika context-menu entry.

In order to install ERIKA v3 cell on the ZCU102, copy the following file on the SD card file-system (i.e., on the root /):

• zcu102 cell contained in the jailhouse directory (i.e, <jailhouse directory>/configs/zynqmp-zcu102-gic-demo.cell).
• ERIKA v3 binary stored in the out of the RT-Druid project (i.e., /erika_inmate.bin).

Run ERIKAv3 as Jailhouse inmate

In order to run ERIKA v3 as Jailhouse inmate, the SD card for the ZCU102 should contain the following files (see Jailhouse and ERIKA v3 cell installation):

• Jailhouse kernel modules
• zcu102 root cell (i.e., /zynqmp-zcu102.cell)
• zcu102 cell (i.e., /zynqmp-gic-demo.cell)
• Erika v3 binary (i.e., /erika_inmate.bin)

The hypervisor requires a contiguous piece of RAM for itself and each additional cell. This currently has to be pre-allocated during boot-up. On ARM platforms this is usually achieved by reducing the amount of memory seen by the Linux kernel. You therefore need to modify the kernel boot arguments by resizing the kernel memory. Since the hypervisor requires a contiguous piece of RAM for itself and each additional cell, the amount of memory seen by the Linux kernel has to be reduced.

In order to modify the kernel boot arguments by adding mem=<new value>, reboot the board and stop the execution at the u-boot prompt (typically by pressing any key at the boot). Change the bootargs as follows:

u-boot prompt> setenv bootargs '<previous values> mem=1536M'

Save the environment so that the kernel memory will be set to the desired value also for the next reboots and then restart the execution:

u-boot prompt> saveenv 
u-boot prompt> run bootcmd

At the kernel start, update the list of module dependencies:

 xlnx-linux prompt> sudo depmod -a

Note that the kernel boot argument has to be modified with the value mem=<new value> in order to reduce the available kernel memory (see Board setup).

Since in the example ERIKA v3 cell will take the console for printing the application messages, use an ssh connection to send the commands to the board.

Once the boot arguments has been modified, insert jailhouse.ko kernel module:

 xlnx-linux prompt> sudo modprobe jailhouse

Enable jailhouse by specifing the zcu102 root cell path:

 xlnx-linux prompt> sudo jailhouse enable /zynqmp-zcu102.cell

Create the jailhouse cell:

 xlnx-linux prompt> sudo jailhouse cell create /zynqmp-gic-demo.cell

Load the ERIKA v3 binary:

 xlnx-linux prompt> sudo jailhouse cell load gic-demo /erika-inmate.bin

Start ERIKA v3:

 xlnx-linux prompt> sudo jailhouse cell start gic-demo

The ERIKA v3 cell has to print the following output:

Figure 6: Output of the helloworld example.

Libc support

If the application on ERIKA needs to use services provided by the libc library (e.g. memcpy()) please refer to the "Libc support" section on the wiki page about Jailhouse for building the Jailhouse inmate library (and also ERIKA) using a bare-metal toolchain.