Petalinux 2018.2 for Xilinx

1 Overview

​ Petalinux is an embedded Linux development kit launched by Xilinx, which includes Linux Kernel, u-boot, device-tree, rootfs and other source code, libraries, and Yocto recipes, allowing customers to easily generate, configure, compile and customize . Petalinux supports Zynq UltraScale+ MPSoC, Zynq-7000 all-programmable SoC, and MicroBlaze, and can work with Xilinx hardware design tool Vivado, which greatly simplifies the development of Linux systems.

​ Using PetaLinux tools, developers can customize u-boot, Linux kernel or Linux applications. Developers can also add new kernels and device drivers to the attached full system emulator (QEMU) or physical hardware via network or JTAG , Applications and libraries, and start and test the software protocol stack, complete all operations from system startup to execution. The PetaLinux tools provided on the host side include:

• Command line interface
• Applications, device drivers, library generators, and development templates
• Bootable system image generator
• Debug agent
• GCC toolset
• Integrated QEMU full system simulator
• Automation tool
• Support Xilinx system debugger

2. Install Petalinux

2.1 Installation requirements

​ Petalinux is a large-scale software, which requires relatively high computer hardware configuration. Petalinux tool user document UG1144 (v2018.2) Page 9 makes a recommendation for the installation environment:

• 8 GB RAM (recommended minimum for Xilinx tools)
• 2 GHz CPU clock or equivalent (minimum of 8 cores
• 100 GB free HDD space
• Supported OS:

• Red Hat Enterprise Workstation/Server 7.2, 7.3, 7.4 (64-bit)
• CentOS 7.2, 7.3, 7.4 (64-bit)
• Ubuntu Linux 16.04.3 (64-bit)

​ To install Petalinux, we need 8GB of RAM, 2GB of CPU, 100GB of hard disk, and a Linux system that can run normally.

​ Next, we will install and use Petalinux on Ubuntu 16.04.6 LTS (Xenial Xerus) desktop version. For other version systems, some commands or configurations may not be compatible, please refer to the relevant system documentation.

2.2 Install dependent libraries

​ The operation of Petalinux relies on some libraries. According to Table 2-1: Packages and Linux Workstation Environments in the Petalinux tool user document UG1144 (v2018.2) Page 9, the libraries that need to be installed are sorted out and an automatic installation is made. Script install_petalinux201802_lib.sh:

#!/bin/bash
sudo apt -y install tofrodos  iproute2 gawk
sudo apt -y install gcc git make
sudo apt -y install xvfb
sudo apt -y install net-tools  libncurses5-dev  tftpd
sudo apt -y install zlib1g-dev zlib1g-dev:i386 libssl-dev  flex bison libselinux1
sudo apt -y install gnupg wget diffstat chrpath socat xterm
sudo apt -y install autoconf libtool tar unzip texinfo zlib1g-dev gcc-multilib build-essential libsdl1.2-dev libglib2.0-dev
sudo apt -y install screen pax gzip tar

​ It is recommended to update the system and its libraries before installing dependent libraries to ensure that all software is in the latest state.

2.3 Install TFTP software

​ TFTP software is used to update the system, software, etc. online through the network, we will use it when debugging the motherboard. The following is the automatic installation script instll_tftp.sh for TFTP:

#!/bin/bash

configfile="/etc/default/tftpd-hpa"
sudo apt install -y tftpd-hpa tftp-hpa
sudo cp ${configfile} /etc/default/tftpd-hpa.bck
sudo sed -i '/^TFTP_OPTION/d' ${configfile}
sudo sed -i '$a TFTP_OPTION=\"--secure --create\"' ${configfile}
sudo chown -R tftp /var/lib/tftpboot/
echo "export TFTP_DIRECTORY=\`cat /etc/default/tftpd-hpa | grep TFTP_DIRECTORY | cut -d \"\\\"\" -f 2\`" | sudo tee -a /etc/bash.bashrc >/dev/null
sudo systemctl enable tftpd-hpa
sudo systemctl restart tftpd-hpa

2.4 Download the installation file

​ Petalinux can be downloaded for free on Xilinx official website , but you need to register an account before downloading. The installation package size is 6.15G.

​ To ensure that the downloaded installation package is complete, please verify its md5:

#/bin/bash
echo "686edec30123bacf94102f2bc6ed70ff  petalinux-v2018.2-final-installer.run" > petalinux-v2018.2-final-installer.md5
md5sum -c petalinux-v2018.2-final-installer.md5

​ The above verification, the system terminal will output verification ok information:

petalinux-v2018.2-final-installer.run: OK

2.5 Installation

​ According to the requirements in the Petalinux tool user document UG1144 (v2018.2) Page 12:

Note: You cannot install the tool with the root user, instead the permissions for
/opt/pkg/petalinux should be 755. It is not mandatory to install tool in /opt/pkg/petalinux
directory. You can install at any desired location that has the 755 permissions.

​ We need to install Petalinux as a non-root user. It is recommended to install Petalinux to the personal user directory, for example, to install to the ~/bin/petalinux201802 directory, we use the terminal to enter the folder where petalinux-v2018.2-final-installer.run is located, and execute the following command:

mkdir -p ~/bin/petalinux201802
chmod +x petalinux-v2018.2-final-installer.run
./petalinux-v2018.2-final-installer.run ~/bin/petalinux201802

​ During the installation, there will be a PetaLinux End User License Agreement (EULA) prompt, you need to press the keyboard q, then press y to confirm the agreement license.

2.6 Environment configuration

2.6.1 Configure environment variables

​ After Petalinux is installed, you need to configure its startup environment:

source ~/bin/petalinux201802/settings.sh

​ But this command only takes effect in the current terminal. After restarting the terminal, you still need to execute this command again. To avoid this situation, we can also write it into the user configuration information under Ubuntu system:

echo "source ~/bin/petalinux201802/settings.sh" >> ~/.bashrc

​ Note: 1. In CentOS, it cannot be written into user configuration information, otherwise it may cause system exceptions when logging in users;

​ 2. This command has not been tested in Red Hat;

​ After the Petalinux environment variable takes effect, we can use the following command to verify the installation of Petalinux:

echo $PETALINUX

​ The system will output the installation directory of Petalinux, indicating that the installation is successful:

/home/<user>/bin/petalinux201802

​ Among them, <user> is the current user name for installing petalinux.

2.6.2 Close webtalk function

​ By default, enable the webtalk option to send tool usage statistics back to Xilinx. We can turn off the webtalk function by running the petalinux-util --webtalk command:

petalinux-util --webtalk off

​ The system will output the following information in the terminal, which means that the webtalk function has been closed successfully:

INFO: Turn off webtalk feature!

2.6.3 Modify the default shell to bash

​ The default shell of Ubuntu is dash, and in the Petalinux tool user document UG1144(v2018.2) Page 14, it requires:

This section assumes that the following prerequisites have been satisfied:

• ...
• "/bin/sh" is bash

​ So we need to adjust our /bin/sh to bash, and execute the following commands:

sudo rm /bin/sh
sudo ln -s /bin/bash /bin/sh

​ To confirm whether the modification is successful, we can execute the following commands:

ls -l /bin/sh

​ The system will output a message containing the following fields to confirm that the shell has been modified successfully:

/bin/sh -> /bin/bash

3. Use of Petalinux

3.1 Create a project

​ According to Chapter 3 Creating a Project in the Petalinux tool user document UG1144 (v2018.2) Page 17, there are two ways to create a project in Petalinux, namely:

• Project creation based on existing BSP files

• Project creation based on hardware description file generated by Vivado

  Below, we explain the specific instructions for these two methods:

3.1.1 Project creation based on existing BSP files

​ To create a project based on an existing BSP file, you need to download the corresponding BSP package of the SoC from the Xilinx official website , or obtain the corresponding BSP package from elsewhere.

​ When we get the BSP package, we can start to create our project. For example, if we create a project in the /home/user/project directory, we can use the following command:

cd ~/project
petalinux-create -t project -n <PROJECT-NAME> -s <PATH-TO-BSP>

​ Among them,

• <PROJECT-NAME> is the project name, which can be omitted;
• <PATH-TO-BSP> is the directory path of the BSP package;

3.1.2 Project creation based on the hardware description file generated by Vivado

​ To create a project based on the hardware description file generated by Vivado, you need to first export the corresponding hardware description file from Vivado. The specific operations are:

​ 1. Use Vivado to open the corresponding project;

​ 2. Select File -> Export -> Export Hardware in the option bar, check the ☑️Include bitstream option, and then click OK;

​ The Vivado hardware description file will be generated in the <VIVADO-PROJECT-NAME>.sdk directory of the Vivado project. We can use the following commands to create the project:

petalinux-create --t project --template <CPU-TYPE> -n <PROJECT-NAME>

​ Among them,

• <CPU-TYPE> is the CPU type, the specific value can be: zynqMP (for UltraScale+ MPSoC) , zynq (for Zynq) , microblaze (for MicroBlaze) ;

• <PROJECT-NAME> is the project name;

  After the project is successfully created, we need to use petalinux-config to configure the project according to the Vivado hardware description file:

petalinux-config --get-hw-description=<PATH-TO-HDF/DSA-DIRECTORY>

​ Among them, <PATH-TO-HDF/DSA-DIRECTORY> is the directory path where the Vivado hardware description file is located;

​ After using petalinux-config to configure the project according to the Vivado hardware description file, we also need to configure the SoC model CONFIG_SUBSYSTEM_MACHINE_NAME: petalinux-config -> DTG Settings ---> (template) MACHINE_NAME, the value can be:

• ac701-full
• ac701-lite
• kc705-full
• kc705-lite
• kcu105
• zc1254-reva
• zc1275-REVA
• zc1275-revb
• zc1751-dc1
• zc1751-dc2
• zc702
• zc706
• avnet-ultra96-rev1
• zcu100-REVA
• zcu100-revb
• zcu100-revc
• zcu102-rev1.0
• zcu102-reva
• zcu102-revb
• zcu104-reva
• zcu104-revc
• zcu106-REVA
• zcu111-reva
• zedboard

3.2 Configuration project

​ After the Petalinux project is created, we need to configure the project according to the specific situation. The specific instructions are:

• Global configuration: petalinux-config
• 配置Kernel：petalinux-config -c kernel
• Configure rootfs: petalinux-config -c rootfs

3.3 Compile the project

​ After the configuration is completed, we can perform compilation work on the project, the specific instructions are:

petalinux-build

petalinux-build instructions may include parameters specific reference documentation UG1157 the PetaLinux the Command Line Reference Page 12 is the Table 1-6: the Command Line petalinux-build the Options content.

3.4 Packaging files

​ After the compilation is complete, we can pack some files, such as the startup file BOOT.bin, pre-built files and other files for testing.

3.4.1 Package the startup file BOOT.bin

​ The boot file BOOT.bin can be burned into the flash and will run when the SoC starts from the flash. According to different SoCs, we choose different instructions.

​ for Zynq-7000：

petalinux-package --boot --fsbl <FSBL-image> --fpga <FPGA-bitstream> --u-boot

​ for MicroBlaze：

petalinux-package --boot --fpga <FPGA-bitstream> --u-boot --kernel

​ for Zynq UltraScale+ MPSoC：

petalinux-package --boot --format BIN --fsbl <FSBL-image> --u-boot <u-boot-image> --pmufw <pmufw-image> --fpga <FPGA-bitstream>

3.4.2 Pack pre-built files

​ Pre-built files, used for Jtag or QEMU testing. To pack pre-built files, we can use the following commands:

petalinux-package --prebuilt --fpga <FPGA-bitstream>

3.5 Debug

​ After the pre-built files are packaged, we can use the petalinux-boot instruction to use Jtag online debugging, or start from QEMU for debugging.

3.5.1 Startup level

​ For petalinux-boot instruction, there is an optional option --prebuild <BOOT_LEVEL> parameter, the value of <BOOT_LEVEL> can be 1, 2, 3, and their meanings are:

• Level 1: Download the prebuilt FPGA bitstream.

It will also boot FSBL for Zynq-7000 and, FSBL and PMU firmware for Zynq UltraScale+ MPSoC.

• Level 2: Download the prebuilt FPGA bitstream and boot the prebuilt U-Boot.

For Zynq-7000: It will also boot FSBL before booting U-Boot.

For Zynq UltraScale+ MPSoC: It will also boot PMU firmware, FSBL, and ATF before booting U-Boot.

• Level 3:

For MicroBlaze: Downloads the prebuilt FPGA bitstream and boot the prebuilt kernel image on target.

For Zynq-7000: Downloads the prebuilt FPGA bitstream and FSBL and boot the prebuilt U-Boot and boot the prebuilt kernel on target.

For Zynq UltraScale+ MPSoC: Downloads PMU Firmware, prebuilt FSBL, prebuilt kernel, prebuilt FPGA bitstream, linux-boot.elf and the prebuilt ATF on target.

3.5.2 Online debugging with Jtag

​ After connecting the motherboard, debugger and computer, we can use the following instructions to debug online:

petalinux-boot --jtag --prebuild 3

3.5.3 Debug with QEMU

​ QEMU is a set of analog processors integrated in the Petalinux tool set. It can be tested without a hardware environment, but the test results are for reference only and may not match the actual environment.

​ We can use the following instructions to debug QEMU:

petalinux-boot --qemu --prebuilt 3

3.6 Custom system

​ In the Petalinux project, we can add the files we need, such as libraries, applications, self-starting programs, modules or custom device trees, etc., and add them to our Petalinux system.

3.6.1 Add library

​ For adding a library, we need to create a library application first:

petalinux-create -t apps --template install --name <LIB-NAME> --enable

​ The directory path of the library is: <plnx-proj-root>/project-spec/meta-user/recipes-apps/<LIB-NAME>.

​ We can copy the source files of our library or pre-compiled library files to the files directory under the directory path where the library is located, and then edit the <LIB-NAME>.bb file under the directory path where the library is located, and change the files directory Add the required files to the SRC_URI field. Such as adding source files lib.c, lib.h, Makefile files:

#
# This file is the libs recipe.
#

SUMMARY = "Simple libs application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

S = "${WORKDIR}"

TARGET_CC_ARCH += "${LDFLAGS}"

SRC_URI = "file://lib.c \
    file://lib.h \
    file://Makefile \
    "

do_compile() {
    oe_runmake
}

do_install() {
    install -d ${D}${libdir}
    install -m 0655 ${S}/<LIB-NAME>.so ${D}${libdir}
}

FILES_${PN} += "${libdir}"
FILES_SOLIBSDEV = ""

​ Or add the pre-compiled library file <LIB-NAME>.so:

#
# This file is the libs recipe.
#

SUMMARY = "Simple libs application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

S = "${WORKDIR}"

TARGET_CC_ARCH += "${LDFLAGS}"

SRC_URI = "file://<LIB-NAME>.so \
    "

do_install() {
    install -d ${D}${libdir}
    install -m 0655 ${S}/<LIB-NAME>.so ${D}${libdir}
}

FILES_${PN} += "${libdir}"
FILES_SOLIBSDEV = ""

3.6.2 Add application

​ For adding an application, we need to create an application first:

petalinux-create -t apps --template install --name <APPS-NAME> --enable

​ The directory path of the application is: <plnx-proj-root>/project-spec/meta-user/recipes-apps/<APPS-NAME>.

​ We can copy the source files of our application or pre-compiled application files to the files directory under the directory path where the library is located, and then edit the <APPS-NAME>.bb file under the directory path where the application is located, Add the required files in the files directory to the SRC_URI field. Such as adding source files apps.c, apps.h, Makefile files:

#
# This file is the apps recipe.
#

SUMMARY = "Simple apps application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

S = "${WORKDIR}"

SRC_URI = "file://apps.c \
    file://apps.h \
    file://Makefile \
    "

do_compile() {
    oe_runmake
}

do_install() {
    install -d ${D}${bindir}
    install -m 0755 ${S}/<APPS-NAME> ${D}${bindir}
}

​ Or add pre-compiled application file <APPS-NAME>:

#
# This file is the arp recipe.
#

SUMMARY = "Simple apps application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

SRC_URI = "file://<APPS-NAME> \
                    "

S = "${WORKDIR}"
INSANE_SKIP_${PN} = "ldflags"
INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
INHIBIT_PACKAGE_STRIP = "1"

do_install() {
    install -d ${D}/${bindir}
    install -m 0755 ${S}/<APPS-NAME> ${D}/${bindir}
}

3.6.3 Add a self-starting script

​ For adding a self-starting script, we need to create a script program first:

petalinux-create -t apps --template install --name <SCRIPT-NAME> --enable

​ The directory path of the script is: <plnx-proj-root>/project-spec/meta-user/recipes-apps/<SCRIPT-NAME>.

​ We add script files, such as autorun-script, in the files directory under the directory path where the script is located:

#!/bin/sh

DAEMON=/usr/bin/autorun-script

start ()
{
    echo " Starting autorun-script"
    start-stop-daemon -S -o --background -x $DAEMON
}

stop () 
{
    echo " Stoping autorun-script"
    start-stop-daemon -K -x $DAEMON
}

restart()
{
    stop
    start
}

[ -e $DAEMON ] || exit 1
    case "$1" in
        start)
            start; ;;
        stop)
            stop; ;;
        restart)
            restart; ;;
        *)
            exit 1
            echo "Usage: $0 {start|stop|restart}"
    esac
exit $?

​ Edit the <SCRIPT-NAME>.bb file in the directory where the script is located, and add the required files in the files directory to the SRC_URI field:

#
# This file is the script recipe.
#

SUMMARY = "Simple script application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

SRC_URI = "file://autorun-script \
    "

S = "${WORKDIR}"

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

inherit update-rc.d

INITSCRIPT_NAME = "autorun-script"
INITSCRIPT_PARAMS = "start 99 S ."

do_install() {
    install -d ${D}/${sysconfdir}/init.d
    install -m 0755 ${S}/autorun-script ${D}/${sysconfdir}/init.d/autorun-script
}

FILES_${PN} += "${sysconfdir}/*"

3.6.4 Add module

​ For adding modules, we need to create a module application first:

petalinux-create -t apps --template install --name <MODULE-NAME> --enable

​ The directory path of the library is: <plnx-proj-root>/project-spec/meta-user/recipes-apps/<MODULE-NAME>.

​ We can copy the source files or pre-compiled library files of our module to the files directory under the directory path where the module is located, and then edit the <MODULE-NAME>.bb file under the directory path where the module is located, and change the files directory Add the required files to the SRC_URI field. Such as adding source files module.c, module.h, Makefile files:

#
# This file is the module recipe.
#

SUMMARY = "Simple shivamod application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

S = "${WORKDIR}"

SRC_URI = "file://module.c \
    file://module.h \
    file://Makefile \
    "

do_compile() {
    oe_runmake
}

do_install() {
    install -d ${D}${base_libdir}/modules/${KERNEL_VERSION}/extra
    install -m 0755 ${S}/<MODULE-NAME>.ko ${D}${base_libdir}/modules/${KERNEL_VERSION}/extra
}

FILES_${PN} = "${base_libdir}/modules/"

​ Or add a pre-compiled module <MODULE-NAME>.ko:

#
# This file is the module recipe.
#

SUMMARY = "Simple shivamod application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

SRC_URI = "file://<MODULE-NAME>.ko \
    "

inherit module-base

S = "${WORKDIR}"

do_install() {
    install -d ${D}${base_libdir}/modules/${KERNEL_VERSION}/extra
    install -m 0755 ${S}/<MODULE-NAME>.ko ${D}${base_libdir}/modules/${KERNEL_VERSION}/extra
}

FILES_${PN} = "${base_libdir}/modules/"

3.6.5 Custom Device Tree

​ To customize the device tree based on the Petalinux default device tree file, you need to customize it in the <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/ directory. All related fields in the custom device tree under this path will be inserted or overwritten in the original default device tree.

​ The following is an example of adding Microchip's KSZ9897R network card chip device tree information to Zynq for demonstration:

​ 1. Hardware connection:

• Control the I2C interface of KSZ9897R through Zynq's I2C1;
• Connect to Port7 of KSZ9897R through gem1 of Zynq;

​ 2. In the <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/files directory, add the relevant device tree information file ksz9897r-conf-i2c.dtsi of KSZ9897R, the following is Its specific content:

/ {
    amba: amba {
        gem1: ethernet@e000c000 {
            fixed-link {
                speed = <1000>;
                full-duplex;
            };
        };

        i2c1: i2c@e0005000 {
            clock-frequency = <38000>;
            ksz9897r: ksz9897r@0 {
                reg = <0x5f>;
            };
        };
    };
};

​ 3. Modify the system-user.dtsi file in the <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/files directory, and add ksz9897r-conf-i2c.dtsi related fields:

/include/ "system-conf.dtsi"
/include/ "ksz9897r-conf-i2c.dtsi"
/ {
};

​ 4. Modify the device-tree.bbappend file in the <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/ directory, and add ksz9897r-conf-i2c.dtsi related fields:

SRC_URI += "file://system-user.dtsi \
    file://ksz9897r-conf-i2c.dtsi \
    "

4. Petalinux system optimization

4.1 speed optimization of u-boot reading kernel

​ When the system starts, the speed at which u-boot reads the kernel file from the QSPI flash is the default. According to the QSPI flash used, we can adjust its reading speed.

​ In <plnx-proj-root>/project-spec/meta-plnx-generated/recipes-bsp/u-boot/configs/platform-auto.h, add the reading speed in cp_kernel2ram:

cp_kernel2ram=sf probe 0 <SPEED_HZ> & ...

​ Among them, the value of <SPEED_HZ> is calculated in Hz. It is advisable to select an appropriate value according to the QSPI flash related parameters. If it is too small, the reading speed is too slow, and if it is too large, it will cause errors in the read data;

​ But the above optimization may be modified after petalinux-config is executed. If the QSPI flash we use is the same flash, we can modify the u-boot_bsp.tcl file in the Petalinux installation directory (file path file path <petalinux-path>/etc/hsm/scripts/libs/) line 483 about:

...

"kernel" {
    append data "\n" { "cp_kernel2ram=sf probe 0 <SPEED_HZ> && sf read ${netstart} ${kernelstart} ${kernelsize}\0" \ }
}

...

​ We will use this read speed configuration as the default configuration for our future Petalinux project. When petalinux-config is executed in the project, this configuration will modify the original platform-auto.h file in the project.

4.2 Turn off ssh-dropbear function

​ dropbear is a relatively small SSH server and client. Under normal circumstances, we do not need to use this feature, you can turn off this feature.

​ We enter the rootfs configuration environment, first turn off the package group-core-ssh-dropbear function: petalinux-config -c rootfs —> Filesystem Packages —> misc —> packagegroup-core-ssh-dropbear, remove packagegproup-core-ssh -dropbear, and then add a line at the end of the <plnx-proj-root>/project-spec/meta-user/conf/petalinuxbsp.conf file:

PACKAGE_EXCLUDE += " packagegroup-core-ssh-dropbear"