Tutorial: Developing Embedded Linux Systems With Yocto For Zynq UltraScale+ MPSoCs

In our recent webinar “An Introduction to Yocto for Zynq UltraScale+ MPSoCs”, we gave an introduction to the Yocto Project showed how easily specific vendor support could be utilized to build a system for a Zynq UltraScale+ MPSoC device.

Want to learn how to develop embedded Linux systems with Yocto for Zynq UltraScale+ MPSoCs? This tutorial will go over the demonstration from our webinar and show you how to start building and modifying Linux images using Yocto’s graphical interface Toaster. This interface will help new users get familiar with several Yocto concepts before diving into more advanced usage of the Yocto Project.

Background Information

PetaLinux and Yocto Project

The PetaLinux Tools offers everything necessary to customize, build and deploy Embedded Linux solutions on Xilinx processing systems. Source: Xilinx

PetaLinux lets developers modify and rebuild key components of an embedded Linux system, such as the kernel and root file-system, specifically for Xilinx devices using a simple set of commands. Additionally, being more than just a build tool, PetaLinux also simplifies testing and/or debugging on either emulated or real Xilinx hardware. Yocto, on the other hand, is a project that offers a generic build system with a lot of flexibility on how an image is built (while having Xilinx auxiliary tools absent).

Yocto and Toaster

Toaster is a web interface to the Yocto Project’s OpenEmbedded build system. The interface enables you to configure and run your builds. Information about builds is collected and stored in a database. Source: Toaster Manual

The Yocto build framework operates on a “layer” system concept; these layers are controlled by configuration files referred to as “recipes”. The Yocto framework can perform many tasks, such as building a whole (shippable) image and building a single recipe (usually representing a single application, but sometimes multiple packages). It is even possible to run a single task from within a recipe (e.g., fetching sources, running menuconfg, etc.).
Many Yocto concepts are not implemented in the GUI, but Toaster’s interface declutters and simplifies the build process. Toaster also replaces the older Hob non-web interface.

Tutorial Goals

This tutorial will present the following concepts.

1. Building an InitRAMFS image with Toaster for Xilinx’s ZCU102 evaluation kit (which runs a Xilinx Zynq UltraScale+ MPSoC) to imitate the results generated by PetaLinux tools.
2. Adding software from another layer (in this tutorial 7zip).
3. Using QEMU (provided through PetaLinux by Xilinx) to boot the OS and verify that changes were applied.

Instructions

Requirements

Before beginning the tutorial, the build environment must be setup.
The tutorial requires:

• A Linux machine or virtual machine with enough disk space to run builds (25+ GB).
  Note: Network accessible disks/shared folders will not work.
• A copy of Poky (this tutorial uses 2.1/Korgoth) with the dependencies installed.
  See Yocto documentation for further information.
• A 2016.1 or 2016.2 installation of PetaLinux with the environment setup sourced.
  See Xilinx documentation for further information. Note: PetaLinux does not require a license.
• Copies of extra files (found here) on hand and in a known path.

Once Poky is downloaded, a build folder is generated. You then need to:

1. Start Toaster (as described in Toaster documentation),
2. Open your browser to the Toaster Web interface.

Tutorial

1. Create a new project. In this tutorial, we use
   hardent_webinar.
   Select release 2.1 Korgoth of the Yocto Project.

2. From the project dashboard, add the meta-xilinx layer to the project.

• Toaster knows of certain layers available through the “OpenEmbedded Metadata Index”.
• Toaster will fetch the latest Korgoth sources for these layers.
• You can import your own layers into Toaster.

3. Select the zcu102-zynqmp from the machine menu to build Linux for Xilinx’s Zynq UltraScale+ MPSoC ZCU102 board.

4. Go to the “Bitbake variables” screen to add some additional variables.

• Add a variable named INITRAMFS_IMAGE with the value core-image-minimal.
• Add a variable named INITRAMFS_IMAGE_BUNDLE with the value 1.
  • This enables the generation of a single binary file containing the kernel and the rootFS.
    Note: There exists an image, core-image-minimal-initramfs, that should do this automatically for the core-image-minimal image, however, it does not work for the ARM 64-bit architecture.
• Also under Bitbake variables, set the IMAGE_FSTYPES to just cpio.gz.
  This file format can be used by QEMU to emulate running the generated image.

5. Build the core-image-minimal image from the “Image recipes” screen.
   
   

7. You can monitor the build status from the builds screen.
   • Toaster also stores the Yocto build log, and you can watch it to determine at which stage the build is at by using the tail command on the file. The location is mentioned in the terminal which started toaster; that is, build-toaster-2/toaster_ui.log from within the Poky directory.
   • The first build may take quite some time as Yocto fetches all its sources and builds its toolchain.

8. Once the build is finished, the new build can be booted in QEMU.
   If PetaLinux is properly sourced, qemu-system-aarch64 should come up as a valid command.
   Note: this command has been tested for PetaLinux 2016.1 and 2016.2. For other versions of PetaLinux the command arguments may change.

qemu-system-aarch64 \
-L /path/to/petalinux-install/etc/qemu \
-M arm-generic-fdt \
-hw-dtb /path/to/downloadedfiles/zynqmp-qemu-arm.dtb \
-device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4 \
-serial mon:stdio \
-serial /dev/null \
-display none \
-gdb tcp::9000 \
-net nic \
-net nic \
-net nic \
-net nic,vlan=1 \
-net user,vlan=1 \
-tftp /tftpboot \
-device loader,file=build-toaster-2/tmp/deploy/images/zcu102-zynqmp/bl31-zcu102-zynqmp.elf,cpu=0 \
-device loader,file=build-toaster-2/tmp/deploy/images/zcu102-zynqmp/Image-initramfs-zcu102-zynqmp.bin,addr=0x00080000 \
-device loader,file=build-toaster-2/tmp/deploy/images/zcu102-zynqmp/Image-zynqmp-zcu102-revB.dtb,addr=0x04080000 \
-device loader,file=/path/to/downloadedfiles/linux-boot.elf


• Paths above will need to be modified to match your system.
  • The argument to the -L flag should point to the location where PetaLinux is installed.
  • The argument to the –hw-dtb flag should point to the location where files were downloaded. Zynqmp-qemu-arm.dtb is a device tree blob file used by QEMU to understand the device’s architecture.
  • The paths for the build products should match where Toaster has placed them. See the bitbake DEPLOY_DIR_IMAGE variable under the configuration screen of the completed build.
  • Linux-boot.elf should also be found in the folder where the extra files have been downloaded. It is a small application that jumps to the kernel once the ARM TrustZone application is done.
    
    

9. The kernel should boot and load the rootFS with it.
   • Log into Linux as root.
     Running 7za should result in an error as the program wasn’t built into the image.
10. Close QEMU with Ctrl + a and then x.

11. Return to Toaster and the “Compatible software recipes” screen.
    • Search for “p7zip”.
    • Add the layer it is in and build the recipe.
      • p7zip is neither in the minimal image, nor part of the existing project’s layers, so the layer it is part of needs to be added to the project.
      • Building the p7zip recipe makes toaster aware that it exists and that it can be included into an image.

12. Return to the “Image recipes” screen.
    • Select core-image-minimal from the images list by clicking on the name.
      Note: Do not click on the build button, just the name.
    • Create a custom image from core-image-minimal, name it core-image-minimal-with-p7zip.
13. From the “Custom images” screen select the new custom image, core-image-minimal-with-p7zip and then add p7zip to the image.
    • The p7zip recipe generated 6 packages.
      This step simply adds the base package containing the executable.

14. Return to the “Bitbake variables” screen and modify the Bitbake variable INITRAMFS_IMAGE to reflect new custom image name by replacing the value with the new custom image name, core-image-minimal-with-p7zip.

15. Build the custom image.
    Given that all packages are already fetched and compiled, the build should be faster. Yocto needs to repackage the rootFS.

16. Boot again with QEMU, updating file names as required.
    Once logged in, notice how 7za is now an available application.

Summary

This tutorial gave an overview of Toaster’s capabilities, including creating a custom image and adding software to it. The image was built as an initRAMFS for the ZCU102 and booted with QEMU.

Further Information On Yocto For Zynq UltraScale+ MPSoCs

• ***Free Webinar*** An Introduction to Yocto for Embedded Linux Projects
• Yocto Project & Open Embedded Development Training
• Embedded System Design for the Zynq UltraScale+ MPSoC Training
  
• Toaster Project page

Interested in learning more about using Yocto for Zynq UltraScale+ MPSoCs?