OpenAMP Project Build Process

Owned by Mukta.Darekar (Deactivated), created
Last updated: Aug 19, 2022

This page provides general guidance for using the OpenAMP Application Building process using PetaLinux.

Table of Contents

Introduction

This document describes the process to build linux application using PetaLinux. This also covers booting up your board as well as how to run demo test applications. There is a faster way to test your hardware by using prebuilt images from PetaLinux BSP which is also covered in this document.

PetaLinux - Overview

PetaLinux is an embedded Linux Software Development Kit (SDK) targeting FPGA-based system on a chip (SoC) designs. PetaLinux SDK is a Xilinx development tool that contains everything necessary to build, develop, test, and deploy embedded Linux systems.

The PetaLinux tool contains:

  • Yocto Extensible SDK (eSDK)

  • XSCT (Xilinx Software Command-Line Tool), including XSDB and toolchains

  • PetaLinux CLI tools

PetaLinux needs to be installed first before use - refer to UG1144 - PetaLinux Tools Documentation for the Installation steps and setting up PetaLinux Environment

Building Linux Distribution using PetaLinux including OpenAMP demos

This section covers steps to be followed in order to modify created PetaLinux BSP as per user requirements.

Creating PetaLinux BSP

Create the PetaLinux master project in a suitable directory without any spaces.

$ petalinux-create -t project -s <PATH_TO_PETALINUX_PROJECT_BSP> -n <plnx-user-proj-root>

This will create directory named default project name same as BSP, indicating here as <plnx-user-proj-root>, in the current directory.

Navigate to the directory:

$ cd <plnx-user-proj-root>

PetaLinux Images Quick Try: Prebuilt images are present at <plnx-user-proj-root>/pre-built/linux/images which can directly be used to boot up hardware without doing any further steps. This can be helpful to verify hardware. You can also run demo tests with this prebuilt image.

Include a remote application in the PetaLinux project (Optional)

This step is needed only if you want to add your developed Firmware separately into PetaLinux BSP. Refer to section Building Firmware using PetaLinux.

Enable all of the modules and applications in the RootFS

Open the RootFS configuration menu:

petalinux-config -c rootfs

Select below to ensure OpenAMP applications and RPMsg modules are included

Select below to include default demo test firmware files

Setting up Device Tree Binary

The PetaLinux reference BSP includes a DTB (Device Tree Binary) for OpenAMP located at:

<plnx-user-proj-root>/pre-built/linux/images/openamp.dtb

The device tree setting for the shared memory and the kernel remoteproc is demonstrated in:

<plnx-user-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/files/openamp.dtsi

The openamp.dtb and openamp.dtsi files are provided for reference only. You can refer to the contents from these files to edit the system-user.dtsi file to include the content from openamp.dtsi for your project. Either you can copy paste the contents of openamp.dtsi in the system-user.dtsi or you can update system-user.dtsi to include openamp.dtsi (or any other reference dtsi file) as follows:

Append below line in system-user.dtsi:

/include/ "openamp.dtsi" or /include/ "<your-updated-dtsi-filename>.dtsi"

If you do above “include file step” then you will also have to give reference to this file to append device tree recipe as follows:

bbappend file to be updated can be found at:

<plnx-user-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend

Update below line to include openamp.dtsi

SRC_URI:append = " file://config file://system-user.dtsi"

to

SRC_URI:append = " file://config file://system-user.dtsi file://openamp.dtsi"

For OpenAMP version 2022.1 onwards use “:” i.e. SRC_URI:append. For versions 2021.2 and older releases use “_” i.e. SRC_URI_append.

Building the Application and Linux Project

Ensure that you are in the PetaLinux project root directory: <plnx-user-proj-root>

Build PetaLinux: petalinux-build

Clean project:

  • petalinux-build -x distclean - Clean up the project build. Removes tmp files and sstate cache files.

  • petalinux-build -x mrproper - Clean up the project build and the generated bootable images.

Removes <plnx-user-proj-root>/build , <plnx-user-proj-root>/images , <plnx-user-proj-root>/components/plnx_workspace , <plnx-user-proj-root>/components/yocto/workspace

Building Custom Firmware using PetaLinux

This step is needed while Building Linux Application if you have developed and built a remote application (for example, with Xilinx SDK) or you want to add any user application. It must be included in the PetaLinux project so that it is available from the Linux filesystem for remoteproc.

Create a PetaLinux application inside the components/apps/ directory, using the following command:

Adding firmware from Xilinx SDK

Copy the firmware (that is, the .elf file) built with Xilinx SDK for the remote processor into this directory:

Modify the <plnx-user-proj-root>/project-spec/meta-user/recipes-apps/<app-name>/<app-name>.bb to install the remote processor firmware in the RootFS.

for <app-name>.bb example,

Building Firmware or User Applications

Make sure you are in <plnx-user-proj-root> Petalinux project root directory

  • To rebuild system image along with new application <app-name> : $ petalinux-build

  • To rebuild the selected user application: $ petalinux-build -c <app-name>

Demo Tests Firmware

There are three demo tests available to verify RPMsg interface, Echo test, Matrix Multiply test, and Proxy Application test.

  • Individual demo tests specific code can be found at

https://github.com/OpenAMP/open-amp/tree/main/apps/examples

  • All three demo tests have common source code as follows,

https://github.com/OpenAMP/open-amp/tree/main/apps/machine/zynqmp_r5

The resource table is defined in rsc_table.c and rsc_table.h files that are built into the remote binary and is then parsed by the host application during Remoteproc ELF Load to establish RPMsg IPC. The platform_info.c and platform_info.h files which define platform specific data and implement API’s to set platform specific information for OpenAMP.

  • If you want to do any modifications in demo tests firmware code, then to get the source code from git url specified in meta-layers (as given above), run below command to create firmware specific workspace at <plnx-proj-root>/components/yocto :

petalinux-devtool modify <recipe-name>

for example,

Echo test: petalinux-devtool modify openamp-fw-echo-testd

Matrix multiply test: petalinux-devtool modify openamp-fw-mat-muld

Proxy application test: petalinux-devtool modify openamp-fw-rpc-demo

  • You can find source code files (rsc_table.c, rsc_table.h, platform_info.c, platform_info.h) at <plnx-proj-root>/components/yocto/workspace/sources/<recipe-name>/lib/sw_apps/<demo-test-name>/src/machine/<machine-name>/<filename>

For example, <plnx-proj-root>/components/yocto/workspace/sources/openamp-fw-echo-testd/lib/sw_apps/openamp_echo_test/src/machine/zynqmp_r5/rsc_table.c

  • In case of any changes in files, build Firmware with: petalinux-build -c openamp-fw-echo-testd

  • Verify firmware file is generated at <plnx-proj-root>/components/yocto/workspace/sources/<recipe-name>/<recipe-name>/<rpu-firmware>

For example, <plnx-proj-root>/components/yocto/workspace/sources/openamp-fw-echo-testd/openamp-fw-echo-testd/executable.elf

Booting the PetaLinux Project

You can boot up built-up image virtually from QEMU (Quick Emulator) or from hardware that is either SD card or through JTAG. You can use images from your built images directory i.e. <plnx-user-proj-root>/images/linux or you can also use prebuilt images from <plnx-user-proj-root>/pre-built/linux/images for quick try instead of building whole project.

Booting on QEMU

Ensure that you are in the PetaLinux project root directory: <plnx-user-proj-root>

Run PetaLinux boot:

  • petalinux-boot --qemu --kernel or

  • petalinux-boot --qemu --prebuilt 2 --tftp images/linux

prebuilt option 2 says Boot U-Boot only

directory to refer images from - <plnx-user-proj-root>/images/linux

  • As above both option doesn’t load rootfs, you will have to load it separately as follows.

On boot up it will show message “press any key to stop autoboot” - press any key to stop auto booting here and you can follow below steps,

dhcp

tftpb <memory-start-location-to-store-dtb> <dtb-file>

tftpb <memory-start-location-to-store-image> <Image-file>

tftpb <memory-start-location-to-store-rootfs-file> <rootfs-file>

for example,

For further explanation on PetaLinux boot you can run: petalinux-boot --help

Booting on Hardware with SD card

To boot up board from SD card copy the generated BOOT.BIN file (also copy BOOT.BIN, Image, boot.scr, rootfs.cpio.gz.u-boot files from <plnx-proj-root>/images/linux or <plnx-proj-root>/pre-built/linux/images/ ) into the boot directory in SD card and power ON board with that SD card.

For detail steps follow as mentioned in PetaLinux Tools Documentation: Reference Guide (UG1144) - Steps to Boot a PetaLinux Image on Hardware with SD Card

Creating a Boot.bin File

  • Create BIF file: bootgen.bif (can be located at <plnx-proj-root> or <plnx-proj-root>/images/linux/)

bootgen.bif example for Zync series:

bootgen.bif example for Versal series:

  • Generate BOOT.BIN

petalinux-package --boot --bif <bootgen.bif> --force

Running OpenAMP Demo Test Applications

After the system is up and running, log in with the username and password.

Username is “petalinux” from 2022.1 onwards and verison previous to that it is “root”. Keep simple password for example, “root”. In order to run demo applications you need to be root.

Make sure you have remoteproc driver loaded. If you have unloaded the remoteproc driver, you can load it as follows:

  • For the Zynq UltraScale+ MPSoC device: modprobe zynqmp_r5_remoteproc

  • For the Zynq-7000 SoC device: modprobe zynq_remoteproc

Running the Echo Test

For RPMsg in Kernel space

  • Load the Echo test firmware and RPMsg module:

echo image_echo_test > /sys/class/remoteproc/remoteproc0/firmware

echo start > /sys/class/remoteproc/remoteproc0/state

  • Run the test: echo_test The test starts.

  • Follow the on-screen instructions to complete the test.

  • After you have completed the test, unload the application:

echo stop > /sys/class/remoteproc/remoteproc0/state

For RPMsg in Userspace

Load Firmware and module, run the test, unload application - all is taken care of by running this application: rpmsg-echo-ping-shared

Running the Matrix Multiplication Test

For RPMsg in Kernel space

Load the Matrix Multiply test firmware and RPMsg module, Run the test and unload the application after test is done

echo image_matrix_multiply > /sys/class/remoteproc/remoteproc0/firmware

echo start > /sys/class/remoteproc/remoteproc0/state

mat_mul_demo

echo stop > /sys/class/remoteproc/remoteproc0/state

For RPMsg in Userspace

Load Firmware and module, run the test, unload application - all is taken care of by running this application: matrix_multiply-shared

Running the Proxy Application Test

For RPMsg in Kernel space

Load the Proxy Application test firmware and RPMsg module, Run the test and unload the application after test is done

echo image_rpc_demo > /sys/class/remoteproc/remoteproc0/firmware

echo start > /sys/class/remoteproc/remoteproc0/state

proxy_app

echo stop > /sys/class/remoteproc/remoteproc0/state

For RPMsg in Userspace

Load Firmware and module, run the test, unload application - all is taken care of by running this application: rpc_demod-shared

Related Links

 

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy