Difference between revisions of "Xilinx ZCU102"

From ERIKA WIKI
Jump to: navigation, search
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Introduction ==
+
== Xilinx ZCU102 Board Setup ==
−
The ERIKA v3 RTOS can be run as a guest OS of the [https://github.com/siemens/jailhouse Jailhouse hypervisor] on the [https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html Xilinx ZCU102].
+
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 [https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html 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 [http://www.wiki.xilinx.com/Zynq+UltraScale%EF%BC%8B+MPSoC+Ubuntu+part+2+-+Building+and+Running+the+Ubuntu+Desktop+From+Sources Xilinx manual]).
 +
[[File:ZCU102-evaluation-board.jpg|thumb|center|Xilinx ZCU102 evaluation board.]]
 +
[[File:Zcu102-sd-boot-setup.jpg|thumb|center|Configuration for SD boot.]]
  
−
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 ZCU102 supports all major peripherals and interfaces enabling development for a wide range of applications.
+
Prebuilded SD images can be found in the Xilinx repository and the SD card setup can be performed as follows:
−
[[File:ZCU102-evaluation-board.jpg|thumb|center|Figure: Xilinx ZCU102 evaluation board.]]
+
<ol>
−
Here are the steps to run ERIKA v3 as Jailhouse cell:
+
<li>Download and extract the image available here: https://www.xilinx.com/member/forms/download/xef.html?filename=Ubuntu_Desktop_Release_2018_3_1.zip</li>
 +
<li>Mount the SD card on your host machine.</li>
 +
<li>Flash the downloaded [https://www.xilinx.com/member/forms/download/xef.html?filename=Ubuntu_Desktop_Release_2018_3_1.zip image] into the SD card:<br>
 +
<code>$ sudo dd if=Ubuntu_Desktop_Release_2018_3/Ready_to_test_images/ZCU102_UbuntuDesktop_2018_3.img of=/dev/sdb bs=4M status=progress && sync</code>
 +
</li>
 +
</ol>
 +
 
 +
The SD card will contain two partitions:
 
<ul>
 
<ul>
−
<li>Build and install Linux kernel v4.7+ on the Xilinx ZCU102</li>
+
<li>the first partition, referred to as ''ROOT'', contains the boot images (i.e., <tt>BOOT.BIN</tt> and <tt>uImage.ub</tt>).</li>
−
<li>Build and install Jailhouse using the built kernel</li>
+
<li>the second partition, referred to as ''ROOT1'', stores the system root filesystem.</li>  
−
<li>Create an ERIKA v3 Jailhouse inmate</li>
 
−
<li>Load and run the ERIKA v3 Jailhouse inmate</li>
 
 
</ul>
 
</ul>
  
−
== Linux kernel v4.7+ on Xilinx ZCU102 ==
+
== Compilation tools setup ==
 
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.  
 
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 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).
  
−
According to the Jailhouse documentation for ARM64 the required minimum Linux kernel version is 4.7. Starting from release 2017.1, the Xilinx kernel in PetaLinux has been upgraded from version 4.6 to version v.9 and thus the referred PetaLinux/Vivado SDK tool release has to be 2017.1 and further ([https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html download page]). In the following part of the section, we refer, without loss of generality, to '''PetaLinux tools 2017.2 release'''.
+
In this tutorial we use <b>Petalinux tool</b> to configure, build and package the Linux kernel for the ZCU102 board, whereas we use GNU Arm Embedded Toolchain, that includes the <b>GNU Compiler (GCC) for aarch64</b>, to compile either the Jailhouse hypervisor and the ERIKAv3 inmate.
  
−
=== The compilation environment: PetaLinux tool ===
+
=== PetaLinux setup===
−
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). 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.
+
Download the Petalinux 2019.1 installer from https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html.
  
−
Example of PetaLinux tools 2017.2 installation in the <code>/opt/pkg</code> directory:
+
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 [https://www.xilinx.com/support/documentation/sw_manuals/xilinx2019_1/ug1144-petalinux-tools-reference-guide.pdf Petalinux tool reference guide].
−
  $ mkdir /opt/pkg
+
It follows the commands used to install a subset of the Petalinux 2019.1 dependencies.
−
  $ ./petalinux-v2017.2-final-installer.run /opt/pkg
+
$ 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
  
−
In order to setup the PetaLinux working environment, it is required to source the appropriate settings script (e.g., from a bash shell):
+
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.
−
$ source /opt/pkg/2017.2/settings.sh
+
Example of PetaLinux tools 2019.1 installation in the <code>/opt/petalinux</code> directory:
−
A detailed instruction of the PetaLinux tools is in the reference user guide ([https://www.xilinx.com/support/documentation/sw_manuals/xilinx2016_4/ug1144-petalinux-tools-reference-guide.pdf link to manual]).
+
$ sudo mkdir -p /opt/petalinux
−
In the following part of the section, we give an overview on how to create a new PetaLinux project and build the boot image for the referred board.  
+
$ sudo chown <user>:<user> /opt/petalinux
 +
$ chmod +x petalinux-v2019.1-final-installer.run
 +
$ ./petalinux-v2019.1-final-installer.run /opt/petalinux
  
−
==== Create a New PetaLinux Project ====
+
=== Setup of the GNU Compiler for aarch64 ===
−
In order to create a new PetaLinux project for the referred board, run the following command from the command console (e.g. bash):
+
Download the GNU Arm Embedded Toolchain that includes the GNU Compiler (GCC) for aarch64. More in detail, download the [https://developer.arm.com/-/media/Files/downloads/gnu-a/8.2-2019.01/gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz?revision=21270570-4ec0-4bad-a9e1-09707614066a&la=en&hash=AFEDF645AF5B94336DB4E1E608806CEC87A02B8A gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu] archive
−
$ petalinux-create -t project -n <name> --template zynqMP
+
and unzip the downloaded file.
−
where <tt>name</tt> is the chosen project name.
+
In the following part of the tutorial, we refers to the folder containing the binary files for cross-compiling as  <tt><path for the aarch64 cross-compiler></tt> (i.e.,<code>gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu/bin</code>).
  
−
After creating the project, the hardware configuration should be imported in order to build a Linux system for a customized hardware platform. Examples of hardware design file can be found in the PetaLinux installation path (e.g., <code>/opt/pkg/2017.2/tools/hsm/data/embeddedsw/lib/hwplatform_templates/ZCU102_hw_platform/system.hdf</code>) or in the Xilinx repository ([https://github.com/Xilinx/hdf-examples/tree/master/zcu102-zynqmp zcu102 hdf example]), whereas customized hardware design files can be created by means of Xilinx Vivado SDK. Run the following command to import the hardware description file:
+
== Linux kernel build for Jailhouse==
−
$ petalinux-config --get-hw-description=<path to ''directory'' containing hardware description file>
+
Since Jailhouse compilation requires a copy of the compiled Linux kernel with all object files, we give an overview on how to build the kernel and the boot image.
−
Such command will import the hardware description of the .hdf file given as input. Then, it will launch the top system configuration menu when it runs first time for the PetaLinux project or the tool detects there is a change in the system primary hardware candidates.
+
The main steps to build a kernel for the referred board using Petalinux 2019.1 are the following:
 +
* Create a Petalinux project.
 +
* Configure the kernel and DTS
 +
* Build and install the kernel, the boot image and the modules
  
−
In order to change the configuration of the system by launching the top system configuration menu, run the following command:  
+
==== Petalinux project ====
−
  $ petalinux-config
+
Setup the PetaLinux working environment by sourcing the appropriate settings script:
−
This command is used to define the sets of components (e.g., u-boot, arm-trusted-firmware, kernel and rootfs) and the board configuration  such as the hardware settings (e.g., system processor, memory, Serial port, Ethernet and so forth).<br>
+
  $ source /opt/petalinux/settings.sh
−
Furthermore , the <code>petalinux-config</code> command allows to configure a single component (e.g., u-boot, kernel or rootfs) as follows:
 
  
−
* Kernel configuration:
+
Download the Board Support Packages (BSP) for Petalinux 2019.1 [https://www.xilinx.com/member/forms/download/xef.html?filename=xilinx-zcu102-v2019.1-final.bsp xilinx-zcu102-v2019.1-final.bsp].
−
$ petalinux-config -c kernel
 
−
* U-boot configuration:
 
−
$ petalinux-config -c u-boot
 
  
−
==== Build the boot image ====
+
Create a PetaLinux project for the referred BSP:  
−
In order to build and create the boot image, the PetaLinux 2017.2 tool provides the following commands:
+
  $ petalinux-create -t project -s <path to the bsp>/xilinx-zcu102-v2019.1-final.bsp
−
  $ petalinux-build
+
$ cd xilinx-zcu102-2019.1
−
The <code>petalinux-build</code> command is used to build the system image. As for the <code>petalinux-config</code> command, it is possible to rebuild a single component instead of the entire system with the <tt>-c <component></tt> option.  
 
  
−
Finally, the <code>petalinux-package</code> command is used to build various image format, firmware, prebuilt and bsps.
+
Launch the top system configuration menu by running the following command:
−
  $ petalinux-package --boot|--bsp|--firmware|--image|--prebuilt [options]
+
  $ petalinux-config
−
The boot image for the ZynqMP contains a first stage bootloader image, FPGA bitstream and u-boot. It will be contained in a file referred to as <tt>BOOT.BIN</tt>, whereas the Linux kernel image will contained in a separated file, referred to as <tt>uImage.ub</tt>.
+
Enable the SD boot `Root filesystem type (SD card)`
 +
CONFIG_SUBSYSTEM_ROOTFS_SD := Image Packaging Configuration--->Root filesystem type-->SD card
  
−
For creating the boot image <tt>BOOT.BIN</tt>, the command line is the following:
+
==== Configure Linux ====
−
  $ petalinux-package --boot --u-boot <path of the u-boot elf file> --fpga <path of the bitstream file>
+
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:  
−
where the default path of u-boot elf file and bitstream file is <code><petalinux-project-root>/images/linux</code> where <tt><petalinux-project-root></tt> is the path of the referred PetaLinux project.
+
  $ petalinux-config -c kernel
  
−
For creating only the Linux kernel image <tt>uImage.ub</tt>, the command line is the following:
+
Include all symbols in kallsyms:
−
  $ petalinux-package --image -c kernel --format uImage
+
  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
  
−
Note that the built images <tt>BOOT.BIN</tt> and <tt>uImage.ub</tt> are saved in <code><petalinux-project-root>/images/linux</code> where <tt><petalinux-project-root></tt> is the path of the referred PetaLinux project.
+
==== Linux device tree ====
 +
The ZCU102 second UART is typically used by the no-root Jailhouse inmate. The second UART can show nothing due to a problem between the DTB and                                          
 +
Jailhouse. In order to fix that, apply the following patch to the Petalinux YOCTO system user DTS.
  
−
==== Install the boot image ====
+
  --- a/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
−
The boot image can be put into Flash or SD card. This section refers to the steps for booting from SD card and the 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 [http://www.wiki.xilinx.com/Zynq+UltraScale%EF%BC%8B+MPSoC+Ubuntu+part+2+-+Building+and+Running+the+Ubuntu+Desktop+From+Sources Xilinx manual]):
+
  +++ b/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
−
[[File:Zcu102-sd-boot-setup.jpg|thumb|center|Figure: Configuration for SD boot.]]
+
 
 +
  /include/ "system-conf.dtsi"
 +
  /{
 +
  +       amba {
 +
  +               serial@ff010000 {
 +
  +                       status = "disabled";
 +
  +               };
 +
  +       };
 +
  +
 +
  +       aliases {
 +
  +               /delete-property/ serial1;
 +
  +       };
 +
  };
 +
  +/delete-node/ &uart1;
 +
  +/delete-node/ &pinctrl_uart1_default;
 +
  +
 +
  &i2c1 {
 +
 +
/* FIXME PL i2c via PCA9306 - u45 */
  
−
The SD card has to contain two partitions:
+
==== Build the kernel ====
−
<ul>
+
Build:
−
<li>the first partition, referred to as ''BOOT'', contains the bootloader, u-boot, device-tree and kernel image. More in detail, the boot images created in PetaLinux project (i.e., <tt>BOOT.BIN</tt> and <tt>uImage.ub</tt>) will be installed in the root directory of the ''BOOT'' partition.</li>
+
$ petalinux-build
−
<li>the second partition, referred to as ''rootfs'', stores the system root filesystem.</li>
+
Create the boot image:
−
</ul>
+
$ petalinux-package --boot --fsbl images/linux/zynqmp_fsbl.elf --u-boot images/linux/u-boot.elf --force
−
The SD card partitions can be built by flashing prebuilded SD images or from scratch.
 
  
−
Prebuilded SD images can be found in the Xilinx repository and the SD card setup can be performed as follows:
+
Note that the built images <tt>BOOT.BIN</tt> and <tt>uImage.ub</tt> are saved in <code><petalinux-project-root>/images/linux</code>.
−
<ol>
 
−
<li>Mount the SD card on your host machine.</li>
 
−
<li>Flash the downloaded [https://www.xilinx.com/member/forms/download/xef.html?filename=Ubuntu_Desktop_Release_2017_4.zip&akdm=1 image] into the SD card:<br>
 
−
<code>$ dd if=<file image> of=/dev/sdX bs=8M && sync</code>
 
−
</li>
 
−
</ol>
 
−
In case of the SD card partitions built from scratch, the SD card setup can be performed as follows:
 
−
<ol>
 
−
<li>Mount the SD card on your host machine.</li>
 
−
<li>Format the SD card in two partitions (using <tt>gparted</tt> or <tt>fdisk</tt>):
 
−
<ul>
 
−
<li>The <tt>BOOT</tt> partition should be at least 40MB in size and formatted as a FAT32 filesystem. Ensure that there is 4MB of free space preceding the partition.</li>
 
−
<li>The <tt>rootfs</tt> partition should be formatted as an ext4 file-system and can take up the remaining space on the SD card.</li>
 
−
</ul>
 
−
<li>Copy <tt>BOOT.BIN</tt> and <tt>uImage.ub</tt> from <code><petalinux-project-root>/images/linux</code> into the root directory of the ''BOOT'' partition.
 
−
<li>Extract the file-system archive into the ''rootfs'' partition.<br>
 
−
</ol>
 
  
−
==== Build and install kernel modules ====
+
==== Install boot images and modules ====
−
In order to build and install the kernel modules, run the following command:
+
Modify the prebuilt Ubuntu image (i.e., ZCU102_UbuntuDesktop_2018_3.img) flashed into the SD card, by overwriting image.ub and BOOT.BIN contained in the boot partition, as follows:
−
  $ make -C <path to compiled kernel> ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- INSTALL_MOD_PATH=<destination path> modules_install
+
  $ cp -v images/linux/BOOT.BIN images/linux/image.ub <ROOT>
−
where <tt><path to compiled kernel></tt> is the path of folder containing the compiled kernel in the petalinux project and <tt><destination path></tt> is typically the root of the filesystem on the SD card.
 
  
−
== Jailhouse for Xilinx ZCU102==
+
Install the kernel modules on the SD root file-system:
−
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.
+
$ sudo cp -av build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.19-xilinx-v2019.1+gitAUTOINC+9811303824-r0/image/lib/* <ROOT1>/lib/
  
−
=== Jailhouse repository ===
+
== Jailhouse hypervisor ==
−
As for jailhouse installation on Xilinx ZCU102, we refer to Jailhouse v0.7 on the GitHub repository.
+
For jailhouse on Xilinx ZCU102, we refer to Jailhouse v0.12 on the GitHub repository.
 
The commands to checkout at such version are the following:
 
The commands to checkout at such version are the following:
−
  $ git clone https://github.com/siemens/jailhouse  
+
  $ git clone https://github.com/siemens/jailhouse.git
 
  $ cd jailhouse
 
  $ cd jailhouse
−
  $ git checkout v0.7 -b xilinx_jailhouse
+
  $ git checkout v0.12 -b jailhouse_xilinx
−
Jailhouse directory contains the following subdirectories:
 
−
<ul>
 
−
<li>Documentation
 
−
<li>ci - configuration files for different platforms.</li>
 
−
<li>configs - cell configuration files.</li>
 
−
<li>driver - jailhouse.ko kernel module code.</li>
 
−
<li>hypervisor - hypervisor code.</li>
 
−
<li>inmates - inmates demos. It also contains code for ti_app inmate example.</li>
 
−
<li>scripts </li>
 
−
<li>tools - jailhouse management utility.</li>
 
−
</ul>
 
  
−
=== Jailhouse build and installation ===
+
Create the configuration file for the ZCU102 board <code>ci/jailhouse-config-xilinx-zcu102.h</code>). The content of such configuration file is the following:
−
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 <tt><path to compiled kernel></tt> that is typically stored in the petalinux project (e.g, <code><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/</code>).
 
−
 
 
−
Create the configuration file for the ZCU102 board (e.g., <tt>jailhouse-config-xilinx-zcu102.h</tt>):
 
 
  #define CONFIG_TRACE_ERROR            1
 
  #define CONFIG_TRACE_ERROR            1
 
  #define CONFIG_ARM_GIC_V2              1
 
  #define CONFIG_ARM_GIC_V2              1
 
  #define CONFIG_MACH_ZYNQMP_ZCU102      1
 
  #define CONFIG_MACH_ZYNQMP_ZCU102      1
−
Copy the <code>jailhouse-config-xilinx-zcu102.h</code> file into <code><jailhouse directory>/hypervisor/include/jailhouse</code> directory and rename it to <code>config.h</code>
 
  
−
Build and install jailhouse as follows:
+
Copy the configuration file into <code><jailhouse directory>/include/jailhouse/config.h</code>
−
$ make clean
+
$ cp ci/jailhouse-config-xilinx-zcu102.h include/jailhouse/config.h
−
$ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- KDIR=<path to compiled kernel> DESTDIR=<destination directory> install
 
−
where <tt><path to compiled kernel></tt> is the path of folder containing the compiled kernel in the petalinux project and <tt><destination path></tt> is typically the file-system root of the SD card.
 
  
−
In order to enable jailhouse, copy the zcu102 root cell (i.e., <code><jailhouse directory>/configs/zynqmp-zcu102.cell</code>) on the SD card file-system.
+
Jailhouse compilation requires a copy of the compiled Linux kernel with all object files. We refer to the path of such folder as <tt><path to compiled kernel></tt> that is typically stored in the petalinux project (e.g., <code><petalinux project>/build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.19-xilinx-v2019.1+gitAUTOINC+9811303824-r0/linux-zcu102_zynqmp-standard-build/</code>). Furthermore, we refer to the path of the folder containing the binary for cross-compilation as <tt><path or the aarch64 cross-compiler></tt>.
  
−
=== Board setup ===
+
Build jailhouse:
−
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.
+
$ make ARCH=arm64 CROSS_COMPILE=<path or the aarch64 cross-compiler>/aarch64-linux-gnu- KDIR=<path to compiled kernel>
  
−
In order to modify the kernel boot arguments by adding <code>mem=<new value></code>, 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:
+
Install jailhouse on the SD card:
−
u-boot prompt> setenv bootargs '<previous values> mem=1536M'
+
$ sudo make ARCH=arm64 CROSS_COMPILE=<path or the aarch64 cross-compiler>/aarch64-linux-gnu- KDIR=<path to compiled kernel> DESTDIR=<ROOT1> install
−
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
 
  
−
== Build and install ERIKA v3 as Jailhouse inmate ==
+
Copy the zcu102 root cell and in-mate demo cell on the SD card file-system.
 +
$ cp configs/arm64/zynqmp-zcu102.cell configs/arm64/zynqmp-zcu102-inmate-demo.cell <ROOT1>
 +
 
 +
== Build ERIKAv3 for Jailhouse ==
 
The main steps to create and build ERIKA v3 jailhouse inmate are the following:
 
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.  
 
* download and install RT_DRUID that includes ERIKA v3 as Eclipse plugin.  
Line 158: Line 153:
 
* install the generated binaries into the board
 
* install the generated binaries into the board
  
−
=== Downloading and installing ERIKA v3 and RT-Druid ===
+
==== Setup ERIKAv3 RT-Druid ====
−
RT-Druid can be downloaded using the [http://www.erika-enterprise.com/index.php/download/erika-v3-download.html download web page].  
+
Download the RT-Druid archive from [http://www.erika-enterprise.com/index.php/download/erika-v3-download.html ERIKAv3 download web page] and more specifically the [http://www.erika-enterprise.com/erika3-builds/gh65/eclipse-rtdruid3-photon-linux-gtk-x86_64_20190524_gh65.tar.gz GH65] release.
−
Notice that to download RT-Druid, you have to accept [http://www.erika-enterprise.com/index.php/erika3/licensing.html 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.
+
 
 +
Notice that to download RT-Druid, you have to accept [http://www.erika-enterprise.com/index.php/erika3/licensing.html the RT-Druid and the ERIKAv3 licenses]. The ERIKAv3 license is a GPLv2, 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 ERIKAv3 source code as Eclipse plugin and the default path is <code><RT-Druid folder>eclipse/plugins/com.eu.evidence.ee3_3.0.1.20190524_gh65/ee_files</code>. However, it is possible to change the RT-Druid configuration in order to refer to another ERIKAv3 source code. For more details about RT-Druid configuration, see the [[RT-Druid_configuration|RT-Druid configuration wiki page]].
  
−
''RT-Druid requires Java Standard Edition version 8, or newer.''
+
Unzip the downloaded archives. Since the referred RT-Druid release (e.g., GH65) manages a previous version of Jailhouse, apply the following patch:
  
−
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 <code><RT-Druid folder>/eclipse/plugins/com.eu.evidence.ee3_<version number>/ee_files/</code>. 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|RT-Druid configuration wiki page]].
+
  --- a/eclipse/plugins/com.eu.evidence.ee3_3.0.1.20190524_gh65/ee_files/pkg/arch/aarch64/jailhouse/ee_arch_compiler_gcc.mk
 +
  +++ b/eclipse/plugins/com.eu.evidence.ee3_3.0.1.20190524_gh65/ee_files/pkg/arch/aarch64/jailhouse/ee_arch_compiler_gcc.mk
 +
  @@ -83,7 +83,8 @@ endif
 +
  INCLUDE_PATH += $(JAILHOUSE_DIR)/hypervisor/arch/arm-common/include
 +
  INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib/arm64/include
 +
  INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib/arm-common/include
 +
  -
 +
  +INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib
 +
  +INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib/include
 +
 
 +
  JAILHOUSE_AARCH64_GCCPREFIX ?=
  
−
=== Starting RT-Druid ===
+
Before starting RT-Druid, setup the environment by exporting the variables <code>JAILHOUSE_DIR</code> and <code>JAILHOUSE_AARCH64_GCCPREFIX</code> as follows:
−
Before starting RT-Druid, setup the environment by setting the variables <code>JAILHOUSE_DIR</code> and <code>JAILHOUSE_AARCH64_GCCPREFIX</code> as follows:
 
 
  $ export JAILHOUSE_DIR=<path of the jailhouse directory>
 
  $ export JAILHOUSE_DIR=<path of the jailhouse directory>
−
  $ export JAILHOUSE_AARCH64_GCCPREFIX=aarch64-linux-gnu-
+
  $ export JAILHOUSE_AARCH64_GCCPREFIX=<path or the aarch64 cross-compiler>/aarch64-linux-gnu-
−
Furthermore since we refer to Jailhouse v0.7 for Xilinx ZCU102, set the environment variable <code>JAILHOUSE_VERSION</code> as follows:
+
where <path of the jailhouse directory> is the folder containing Jaihlouse and <tt><path or the aarch64 cross-compiler></tt> is the path of the folder containing the binary for cross-compilation.
−
  $ export JAILHOUSE_VERSION=0.7
+
 
−
Finally, in order to cross-compile setup the PetaLinux working environment:
+
Furthermore since we refer to Jailhouse v0.12 for Xilinx ZCU102, set the environment variable <code>JAILHOUSE_VERSION</code> as follows:
−
$ source /opt/pkg/2017.2/settings.sh
+
  $ export JAILHOUSE_VERSION=0.12
−
In order to start RT-Druid, launch <code>eclipse</code> application located into the <tt>eclipse</tt> folder extracted from the RT-Druid Package.
 
  
−
=== Creating a new RT-Druid project ===
+
Launch <code>eclipse</code> application located into the <code>eclipse</code> folder extracted from the RT-Druid Package.
−
Create a new project by clicking on ''File->New->RT-Druid v3 Oil and C/C++ Project'' menu entry. In the ''RT-Druid C/C++ Project Wizard'' type the name of the project in the ''Project name'' text-box (i.e, ''mytest'' for example). Then, select the ''Cross GCC'' toolchain and click on the ''Next'' button.
+
  $ ./eclipse &
  
−
[[File:ZCU102 rtdruid new project.png|thumb|center|Figure: RT-Druid C/C++ Project Wizard.]]
+
==== Hello world example ====
  
−
Create a new file <code>main.c</code> file by clicking on ''File->New->Source file'' with the following content:
+
As for example, we create a simple "helloworld" application consisting of two tasks printing on the serial interface.
 +
<ol>
 +
<li> Create a new project by clicking on <code>New</code> &rarr; <code>RT-Druid v3 Oil and C/C++ Project</code> as shown in the next Figure:
 +
[[File:Eclipse_new_project1.jpg|thumb|center|Figure 1: Create a new RT-Druid project.]]
 +
<li> In the ''RT-Druid C/C++ Project Wizard'' name the new project (e.g., <code>mytest</code>) and select the Cross-GCC as shown in the next Figure:
 +
[[File:Eclipse_new_project2.jpg|thumb|center|Figure 2: Naming the new RT-Druid project.]]
 +
<li> Check the box for using an existing template and select <code>aarch64</code> &rarr; <code>Jailhouse</code> &rarr; <code>Helloworld OSEK demo on Jailhouse</code>as shown in the next Figure:
 +
[[File:Eclipse_new_project3.jpg|thumb|center|Figure 3: Selecting the Helloworld template.]]
 +
<li> Eclipse will then show the new project, and RT-Druid will generate the configuration files, as shown in the next Figure:
 +
[[File:Eclipse_new_project4.jpg|thumb|center|Figure 4: New Helloworld project created.]]
 +
<li> Modify the <code>conf.oil</code> file as follows:<br>
 
<pre>
 
<pre>
−
#include "ee.h"
+
line 69: /* SOC_DATA = NVIDIA_TEGRA_X1; */
−
#include <inmate.h>
+
line 70: SOC_DATA = XILINX_ZYNQ_ULTRASCALE_PLUS;
−
 
 
−
static volatile u32 counter = 0;
 
−
 
 
−
DeclareTask(Task1);
 
−
DeclareTask(Task2);
 
−
 
 
−
/* First task */
 
−
TASK(Task1)
 
−
{
 
−
        GetResource(SharedUartResource);
 
−
        printk("Hello world from Task1! (%lu)\n", counter);
 
−
        counter++;
 
−
        ReleaseResource(SharedUartResource);
 
−
        TerminateTask();
 
−
}
 
−
 
 
−
/* Second task */
 
−
TASK(Task2)
 
−
{
 
−
        GetResource(SharedUartResource);
 
−
        printk("Hello world from Task2! (%lu)\n", counter);
 
−
        counter++;
 
−
        ReleaseResource(SharedUartResource);
 
−
        TerminateTask();
 
−
}
 
−
 
 
−
void idle_hook(void);
 
−
void idle_hook(void)
 
−
{
 
−
        /* endless loop*/
 
−
        while(1) {
 
−
                asm volatile("wfi": : : "memory");
 
−
        }
 
−
}
 
−
 
 
−
int main(void)
 
−
{
 
−
        printk("Starting OS...\n");
 
−
        StartOS(OSDEFAULTAPPMODE);
 
−
        return 0;
 
−
}
 
 
</pre>  
 
</pre>  
 +
</li>
 +
</ol>
  
−
Modify the <code>conf.oil</code> file with the following content:
 
−
<pre>
 
−
CPU mySystem {
 
−
 
−
  OS myOs {
 
−
 
−
    /* EE_OPT = "OS_EE_VERBOSE"; */
 
−
    EE_OPT = "OSEE_DEBUG";
 
−
    EE_OPT = "OS_EE_APPL_BUILD_DEBUG";
 
−
    EE_OPT = "OS_EE_BUILD_DEBUG";
 
−
    EE_OPT = "OSEE_ASSERT";
 
−
 
−
    CPU_DATA = AARCH64 {
 
−
      MULTI_STACK = TRUE;
 
−
      COMPILER = GCC;
 
−
      IDLEHOOK = TRUE {
 
−
        HOOKNAME = "idle_hook";
 
−
      };
 
−
    };
 
−
 
−
    SOC_DATA = XILINX_ZYNQ_ULTRASCALE_PLUS;
 
−
 
−
    KERNEL_TYPE = OSEK {
 
−
      CLASS = ECC1;
 
−
    };
 
−
  };
 
−
 
−
  COUNTER SystemTimer {
 
−
    MINCYCLE = 1;
 
−
    MAXALLOWEDVALUE = 2147483647;
 
−
    TICKSPERBASE = 1;
 
−
    TYPE = HARDWARE {
 
−
      SYSTEM_TIMER = TRUE;
 
−
      PRIORITY    = 1;
 
−
      DEVICE      = "GTIMER";
 
−
    };
 
−
    SECONDSPERTICK = 0.001;
 
−
  };
 
−
 
−
  ALARM AlarmTask1 {
 
−
    COUNTER = SystemTimer;
 
−
    ACTION = ACTIVATETASK {
 
−
      TASK = Task1;
 
−
    };
 
−
    AUTOSTART = TRUE {
 
−
      ALARMTIME = 500;
 
−
      CYCLETIME = 100;
 
−
    };
 
−
  };
 
−
 
−
  ALARM AlarmTask2 {
 
−
    COUNTER = SystemTimer;
 
−
    ACTION = ACTIVATETASK {
 
−
      TASK = Task2;
 
−
    };
 
−
    AUTOSTART = TRUE {
 
−
      ALARMTIME = 500;
 
−
      CYCLETIME = 100;
 
−
    };
 
−
  };
 
−
 
−
  TASK Task1 {
 
−
    PRIORITY = 1;
 
−
    STACK = PRIVATE {
 
−
      SIZE = 1024;
 
−
    };
 
−
    SCHEDULE = FULL;
 
−
    APP_SRC = "main.c";
 
−
    RESOURCE = SharedUartResource;
 
−
  };
 
−
 
−
  TASK Task2 {
 
−
    PRIORITY = 2;
 
−
    STACK = PRIVATE {
 
−
      SIZE = 1024;
 
−
    };
 
−
    SCHEDULE = FULL;
 
−
    RESOURCE = SharedUartResource;
 
−
  };
 
−
 
−
  RESOURCE SharedUartResource { RESOURCEPROPERTY = STANDARD; };
 
−
};
 
−
</pre>
 
−
 
−
=== Building the RT-Druid project ===
 
 
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.
 
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:
 
The compilation process will generate the following directories:
−
* <tt>erika</tt> - It stores all the files related to ERIKA v3
+
* <tt>erika</tt> - It stores all the files related to ERIKAv3
 
* <tt>out</tt> - It stores all the files related to the application, included the final binaries
 
* <tt>out</tt> - It stores all the files related to the application, included the final binaries
 
In particular, the <tt>out</tt> directory will contain the following files:
 
In particular, the <tt>out</tt> directory will contain the following files:
Line 321: Line 213:
 
* <tt>ee_applcfg.</tt> - the application configuration generated by RT-Druid
 
* <tt>ee_applcfg.</tt> - the application configuration generated by RT-Druid
 
* <tt>makefile</tt> - the main application makefile
 
* <tt>makefile</tt> - the main application makefile
−
* <tt>erika_inmate.bin</tt> - the ERIKA v3 binary containing the application
+
* <tt>erika_inmate.bin/elf</tt> - the ERIKAv3 binary containing the application
  
−
Note that to completely clean the project by removing either generated and compiled files (i.e., <tt>erika</tt> and <tt>out</tt> 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.
+
Copy the ERIKAv3 binary on the SD card file-system.
 +
$ cp <RT-Druid workspace>/mytest/out/erika_inmate.bin <ROOT1>
  
−
=== Installing ERIKA v3 cell ===
+
== Run ERIKAv3 as Jailhouse inmate ==
−
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 /):
+
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.  
−
* zcu102 cell contained in the jailhouse directory (i.e, <code><jailhouse directory>/configs/zynqmp-zcu102-gic-demo.cell</code>).
 
−
* ERIKA v3 binary stored in the <tt>out</tt> of the RT-Druid project.  
 
  
−
== Run ERIKA v3 on Jailhouse ==
+
==== Board boot ====
−
In order to run ERIKA v3 as Jailhouse inmate, the SD card for the ZCU102 should contain the following files (see [[Xilinx_ZCU102#Jailhouse_build_and_installation | Jailhouse]] and [[Xilinx_ZCU102#Installing ERIKA v3 cell | ERIKA v3 cell]] installation):
+
Setup the serial terminal connected to /dev/ttyUSB0 for primary UART (Linux) with baud rate 115200. At the board start, modify the kernel boot arguments by stopping the execution at the u-boot prompt (typically by pressing any key at the boot) as follows:
−
* Jailhouse kernel modules
+
ZynqMP> setenv bootargs "earlycon clk_ignore_unused console=ttyPS0,115200 mem=1536M root=/dev/mmcblk0p2 rw rootwait"
−
* zcu102 root cell (i.e., <code>/zynqmp-zcu102.cell</code>)
+
ZynqMP> setenv uenvcmd "fatload mmc 0 0x3000000 Image && fatload mmc 0 0x2A00000 system.dtb && booti 0x3000000 - 0x2A00000"
−
* zcu102 cell (i.e., <code>/zynqmp-gic-demo.cell</code>)
+
Save the new environment variables for the next reboots and then continue the booting:
−
* Erika v3 binary (i.e., <code>/erika_inmate.bin</code>)
+
ZynqMP> saveenv
 +
ZynqMP> boot
  
−
=== Jailhouse run ===
+
==== Running Jailhouse and ERIKAv3 ====
−
Once the boot arguments has been modified and the machine rebooted, insert <code>jailhouse.ko</code> kernel module:
+
Once Linux is running, update the list of module dependencies:
−
   xlnx-linux prompt> sudo modprobe jailhouse
+
  # depmod -a
 +
Insert <code>jailhouse.ko</code> kernel module:
 +
   # modprobe jailhouse
 
Enable jailhouse by specifing the zcu102 root cell path:  
 
Enable jailhouse by specifing the zcu102 root cell path:  
−
   xlnx-linux prompt> sudo jailhouse enable /zynqmp-zcu102.cell
+
   # jailhouse enable /zynqmp-zcu102.cell
−
 
 
−
=== Run ERIKA v3 on Jailhouse ===
 
−
Since ERIKA v3 will take the console for printing the application messages, send the following commands through the ssh connection.
 
 
Create the jailhouse cell:  
 
Create the jailhouse cell:  
−
   xlnx-linux prompt> sudo jailhouse cell create /zynqmp-gic-demo.cell
+
   # jailhouse cell create /zynqmp-zcu102-inmate-demo.cell
−
Load the ERIKA v3 binary:
+
Load the ERIKAv3 binary:
−
   xlnx-linux prompt> sudo jailhouse cell load gic-demo /erika-inmate.bin
+
   # jailhouse cell load inmate-demo /erika_inmate.bin
−
Start ERIKA v3:
+
Start ERIKAv3:
−
   xlnx-linux prompt> sudo jailhouse cell start gic-demo
+
   # jailhouse cell start inmate-demo
−
The ERIKA v3 cell has to print the following output:
 
−
  Starting OS...
 
−
  Hello world from Task2! (0)
 
−
  Hello world from Task1! (1)
 
−
  Hello world from Task2! (2)
 
−
  Hello world from Task1! (3)
 
−
  Hello world from Task2! (4)
 
−
  ...
 
  
 +
Setup the serial terminal connected to /dev/ttyUSB1 for secondary UART (Jailhouse no-root cell) with baud rate 115200.
 +
Second UART will show the following output:
 +
[[File:Helloworld_output_xilinx.png|thumb|center|Figure 6: Output of the helloworld example.]]
  
 +
== Notes on ERIKAv3 ==
 +
==== Libc support ====
 +
In case the application running on ERIKAv3 needs to use services provided by the libc library (e.g. <code>memcpy()</code>),
 +
please refer to
 +
[http://www.erika-enterprise.com/wiki/index.php?title=ERIKA3_on_the_Jailhouse_hypervisor#Libc_support  the "Libc support" section on the wiki page about Jailhouse]
 +
for building the Jailhouse inmate library (and also ERIKAv3) using a bare-metal toolchain.
  
 +
==== Current release ====
 +
In this tutorial we refers to the latest ERIKAv3 release available (i.e., [http://www.erika-enterprise.com/index.php/download/erika-v3-download.html ERIKAv3 download web page] and more specifically the [http://www.erika-enterprise.com/erika3-builds/gh65/eclipse-rtdruid3-photon-linux-gtk-x86_64_20190524_gh65.tar.gz GH65]). It is worthwhile to notice that <b>this release does NOT support the generation of Software Generated Interrupts (SGIs) on the aarch64 platform yet</b>.
 
[[Category:Boards]]
 
[[Category:Boards]]
 +
[[Category:Tutorial]]

Latest revision as of 15:23, 28 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. Download and extract the image available here: https://www.xilinx.com/member/forms/download/xef.html?filename=Ubuntu_Desktop_Release_2018_3_1.zip
  2. Mount the SD card on your host machine.
  3. Flash the downloaded image into the SD card:
    $ sudo dd if=Ubuntu_Desktop_Release_2018_3/Ready_to_test_images/ZCU102_UbuntuDesktop_2018_3.img of=/dev/sdb bs=4M status=progress && sync

The SD card will contain two partitions:

  • the first partition, referred to as ROOT, contains the boot images (i.e., BOOT.BIN and uImage.ub).
  • the second partition, referred to as ROOT1, stores the system root filesystem.

Compilation tools setup

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

In this tutorial we use Petalinux tool to configure, build and package the Linux kernel for the ZCU102 board, whereas we use GNU Arm Embedded Toolchain, that includes the GNU Compiler (GCC) for aarch64, to compile either the Jailhouse hypervisor and the ERIKAv3 inmate.

PetaLinux setup

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 2019.1 installation in the /opt/petalinux directory: 

$ sudo mkdir -p /opt/petalinux
$ sudo chown <user>:<user> /opt/petalinux
$ chmod +x petalinux-v2019.1-final-installer.run
$ ./petalinux-v2019.1-final-installer.run /opt/petalinux

Setup of the GNU Compiler for aarch64

Download the GNU Arm Embedded Toolchain that includes the GNU Compiler (GCC) for aarch64. More in detail, download the gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu archive and unzip the downloaded file. In the following part of the tutorial, we refers to the folder containing the binary files for cross-compiling as <path for the aarch64 cross-compiler> (i.e.,gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu/bin).

Linux kernel build for Jailhouse

Since Jailhouse compilation requires a copy of the compiled Linux kernel with all object files, we give an overview on how to build the kernel and the boot image. The main steps to build a kernel for the referred board using Petalinux 2019.1 are the following:

  • Create a Petalinux project.
  • Configure the kernel and DTS
  • Build and install the kernel, the boot image and the modules

Petalinux project

Setup the PetaLinux working environment by sourcing the appropriate settings script: 

$ source /opt/petalinux/settings.sh

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)` 

CONFIG_SUBSYSTEM_ROOTFS_SD := 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

Linux device tree

The ZCU102 second UART is typically used by the no-root Jailhouse inmate. The second UART can show nothing due to a problem between the DTB and Jailhouse. In order to fix that, apply the following patch to the Petalinux YOCTO system user DTS. 

 --- a/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
 +++ b/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
 
  /include/ "system-conf.dtsi"
  /{
 +        amba {
 +                serial@ff010000 {
 +                        status = "disabled";
 +                };
 +        };
 +
 +        aliases {
 +                /delete-property/ serial1;
 +        };
  };
 +/delete-node/ &uart1;
 +/delete-node/ &pinctrl_uart1_default;
 +
  &i2c1 {

	/* FIXME PL i2c via PCA9306 - u45 */

Build the kernel

Build: 

$ petalinux-build

Create the boot image: 

$ 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

Modify the prebuilt Ubuntu image (i.e., ZCU102_UbuntuDesktop_2018_3.img) flashed into the SD card, by overwriting image.ub and BOOT.BIN contained in the boot partition, as follows: 

$ cp -v images/linux/BOOT.BIN images/linux/image.ub  <ROOT>

Install the kernel modules on the SD root file-system: 

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

Jailhouse hypervisor

For jailhouse on Xilinx ZCU102, we refer to Jailhouse v0.12 on the GitHub repository. The commands to checkout at such version are the following: 

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

Create the configuration file for the ZCU102 board ci/jailhouse-config-xilinx-zcu102.h). The content of such configuration file is the following: 

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

Copy the configuration file into <jailhouse directory>/include/jailhouse/config.h 

$ cp ci/jailhouse-config-xilinx-zcu102.h include/jailhouse/config.h

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/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.19-xilinx-v2019.1+gitAUTOINC+9811303824-r0/linux-zcu102_zynqmp-standard-build/). Furthermore, we refer to the path of the folder containing the binary for cross-compilation as <path or the aarch64 cross-compiler>.

Build jailhouse: 

$ make ARCH=arm64 CROSS_COMPILE=<path or the aarch64 cross-compiler>/aarch64-linux-gnu- KDIR=<path to compiled kernel>

Install jailhouse on the SD card: 

$ sudo make ARCH=arm64 CROSS_COMPILE=<path or the aarch64 cross-compiler>/aarch64-linux-gnu- KDIR=<path to compiled kernel> DESTDIR=<ROOT1> install

Copy the zcu102 root cell and in-mate demo cell on the SD card file-system. 

$ cp configs/arm64/zynqmp-zcu102.cell configs/arm64/zynqmp-zcu102-inmate-demo.cell <ROOT1>

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

Setup ERIKAv3 RT-Druid

Download the RT-Druid archive from ERIKAv3 download web page and more specifically the GH65 release.

Notice that to download RT-Druid, you have to accept the RT-Druid and the ERIKAv3 licenses. The ERIKAv3 license is a GPLv2, 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 ERIKAv3 source code as Eclipse plugin and the default path is <RT-Druid folder>eclipse/plugins/com.eu.evidence.ee3_3.0.1.20190524_gh65/ee_files. However, it is possible to change the RT-Druid configuration in order to refer to another ERIKAv3 source code. For more details about RT-Druid configuration, see the RT-Druid configuration wiki page.

Unzip the downloaded archives. Since the referred RT-Druid release (e.g., GH65) manages a previous version of Jailhouse, apply the following patch: 

 --- a/eclipse/plugins/com.eu.evidence.ee3_3.0.1.20190524_gh65/ee_files/pkg/arch/aarch64/jailhouse/ee_arch_compiler_gcc.mk
 +++ b/eclipse/plugins/com.eu.evidence.ee3_3.0.1.20190524_gh65/ee_files/pkg/arch/aarch64/jailhouse/ee_arch_compiler_gcc.mk
 @@ -83,7 +83,8 @@ endif
  INCLUDE_PATH += $(JAILHOUSE_DIR)/hypervisor/arch/arm-common/include
  INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib/arm64/include
  INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib/arm-common/include
 -
 +INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib
 +INCLUDE_PATH += $(JAILHOUSE_DIR)/inmates/lib/include
  
  JAILHOUSE_AARCH64_GCCPREFIX ?=

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

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

where <path of the jailhouse directory> is the folder containing Jaihlouse and <path or the aarch64 cross-compiler> is the path of the folder containing the binary for cross-compilation.

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

$ export JAILHOUSE_VERSION=0.12

Launch eclipse application located into the eclipse folder extracted from the RT-Druid Package. 

 $ ./eclipse &

Hello world example

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 ERIKAv3
  • 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 ERIKAv3 binary containing the application

Copy the ERIKAv3 binary on the SD card file-system. 

$ cp <RT-Druid workspace>/mytest/out/erika_inmate.bin <ROOT1>

Run ERIKAv3 as Jailhouse inmate

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.

Board boot

Setup the serial terminal connected to /dev/ttyUSB0 for primary UART (Linux) with baud rate 115200. At the board start, modify the kernel boot arguments by stopping the execution at the u-boot prompt (typically by pressing any key at the boot) as follows: 

ZynqMP> setenv bootargs "earlycon clk_ignore_unused console=ttyPS0,115200 mem=1536M root=/dev/mmcblk0p2 rw rootwait"
ZynqMP> setenv uenvcmd "fatload mmc 0 0x3000000 Image && fatload mmc 0 0x2A00000 system.dtb && booti 0x3000000 - 0x2A00000"

Save the new environment variables for the next reboots and then continue the booting: 

ZynqMP> saveenv 
ZynqMP> boot

Running Jailhouse and ERIKAv3

Once Linux is running, update the list of module dependencies: 

 # depmod -a

Insert jailhouse.ko kernel module: 

 # modprobe jailhouse

Enable jailhouse by specifing the zcu102 root cell path: 

 # jailhouse enable /zynqmp-zcu102.cell

Create the jailhouse cell: 

 # jailhouse cell create /zynqmp-zcu102-inmate-demo.cell

Load the ERIKAv3 binary: 

 # jailhouse cell load inmate-demo /erika_inmate.bin

Start ERIKAv3: 

 # jailhouse cell start inmate-demo

Setup the serial terminal connected to /dev/ttyUSB1 for secondary UART (Jailhouse no-root cell) with baud rate 115200. Second UART will show the following output:

Figure 6: Output of the helloworld example.

Notes on ERIKAv3

Libc support

In case the application running on ERIKAv3 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 ERIKAv3) using a bare-metal toolchain.

Current release

In this tutorial we refers to the latest ERIKAv3 release available (i.e., ERIKAv3 download web page and more specifically the GH65). It is worthwhile to notice that this release does NOT support the generation of Software Generated Interrupts (SGIs) on the aarch64 platform yet.

Retrieved from "http://www.erika-enterprise.com/wiki/index.php?title=Xilinx_ZCU102&oldid=1339"