PetaLinux is brand name used by Xilinx, it is based on Yocto and pretty decent mainstream kernel, what Petalinux adds is the HSI (Hardware Software Interface from Vivado) and special tools for boot image creation.

Online version of this manual and other related documents can be found at https://wiki.trenz-electronic.de/display/PD/PetaLinux+KICKstart


Table of Content



Petalinux Project Creation- Short HOWTO

Getting Linux working on Zynq is very simple, following steps are required

  1. Vivado/SDK/PetaLinux 20xx.x installed (important do not mix versions!)
  2. Create Vivado Project, configure PS, Export HDF (XSA for 19.2 and newer)
  3. Ceate new PetaLinux project
  4. Import HDF(XSA for 19.2 and newer) into project
  5. petalinux-build
  6. copy boot.bin and image.ub to SD Card (only 2 files no more)

This is generic how-to, everything is setup for your by the Vivado->PetaLinux flow. Note, the boot.bin generated by PetaLinux may not always work, in such case it is recommended to make the boot.bin with SDK-GUI or command line tools manually.

There is no need to install anything else, or to fetch anything from any github repos, etc.

PetaLinux 2020.2

PetaLinux Installation

  • (optional) Create new VM with supported Linux OS.

    • Attention: Use English as OS language for your Linux System (Keyboard language can be any language). Other languages may cause errors on PetaLinux build process.

      • with OracleVM:

        • VM Setup:

          • RAM: >= 8GB

          • CPU:  >= 4

          • HDD: 200GB dynanically

            • ubuntu-18.04-desktop-amd64.iso

            • install vm guest additions

            • update to 18.04.5 was done

          • Network: network bridge

          • optional: add shared folder, enable drag and drop

  • Download PetaLinux  from Xilinx Website: http://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html

    • Choose  a PetaLinux Version, that's corresponding to the installed Vivado and SDK Version.

      • Example: Use Vitis (SDK+Vivado) 2020.2 with PetaLinux 2020.2

  • Use UG1144 "PetaLinux Tools Documentation - Reference Guide" that's corresponding with your PetaLinux Version

    1. Use bash as terminal:

      1. $ sudo dpkg-reconfigure dash 

        1. → press no

    2. Check "PetaLinux Tools Installation Requirements" chapter and install missing tool/libraries

      1.  https://www.xilinx.com/support/answers/73296.html

        1. download plnx-env-setup.sh and run

      2. $ sudo apt-get update

      3. $ sudo apt-get install iproute2 gawk python3 python build-essential gcc git make net-tools libncurses5-dev tftpd zlib1g-dev libssl-dev flex bison libselinux1 gnupg wget git-core diffstat chrpath socat xterm autoconf libtool tar unzip texinfo zlib1g-dev gcc-multilib automake zlib1g:i386 screen pax gzip cpio python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 -y

        1. This is necessary because lnx-env-setup.sh seems to be not install all packages correctly
    3. Install petalinux (Note: do not start from shared folder, copy installer into home directory)

      1. $ mkdir -p ~/petalinux/2020.2

      2. copy  petalinux-v2020.2-final-installer.run into ~/petalinux/2020.2
      3. $ ./petalinux-v2020.2-final-installer.run

    4. source enviroment

      1. $ source ~/petalinux/2020.2/settings.sh

    5. Deactivate Webtalk:

      1. $ petalinux-util --webtalk off

  • Note:

    • There is no need to install anything else, or to fetch anything from any github repos, etc.

    • It is recommended to test the installation by creating a dummy template project and building it.

      • Download one of the BSP Examples from Xilinx Website (Only to test your installation)

      • Install:$ petalinux-create -t project -s <path-to-bsp>

      • Build: $ petalinux-build

Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two. Basic Note to TE Petalinux Templates, see: PetaLinux TE-Template#Template-PetaLinux2019.2

  1. PetaLinux Working Environment (see UG1144)
    • PetaLinux Tools Installation is completed.
    • (Note: do not create project from shared folder, use home directory)
    • "/bin/sh" is bash

    • Set Working Environment:
      • $ source <path-to-installed-PetaLinux>/settings.sh
  2. (optional to create project from scretch instead of Trenz Templates) Create a New Project (see UG1144): 
    1. $ petalinux-create --type project --template <CPU_TYPE> --name <PROJECT_NAME>

      • <CPU_TYPE>: zynqMP, zynq, microblaze
      • <PROJECT_NAME>:The name of the project you are building
  3. Import Hardware Configuration (see UG1144):
    • Export Hardware Definition File (*.xsa) from the Vivado Project into the PetaLinux root folder "<plnx-proj-root>":
      • change to PetaLinux root folder:
      • Run:$ petalinux-config --get-hw-description
  4. (optional) Configure your PetaLinux:
    • While anywhere in the project folder tree:
    • Run:$ petalinux-config
    • Run:$ petalinux-config -c u-boot
    • Run:$ petalinux-config -c kernel
    • Run:$ petalinux-config -c rootfs
  5. Build System Image (see UG1144):
    • While anywhere in the project folder tree:
    • Run:$ petalinux-build
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" for BOOT.BIN generation.  It is recommended to create the FSBL and PMU Firmware (ZynqMP only) with Vitis tools.

Petalinux Configuration

Most settings can be changed with menu-config*:

  • petalinux-config
  • petalinux-config -c u-boot
  • petalinux-config -c kernel
  • $  petalinux-config -c rootfs

* with 2020.2 kernel and u-boot changes must be exported to the user-layer with petalinux-devtool command.

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Boot
  • recipes-bsp/u-boot/files
  • recipes-bsp/u-boot/files/platform-top.h
  • changes with "petalinux-config -c u-boot" will be add in the yocto workspace 
  • force changes to the user layer run  "petalinux-devtool finish u-boot-xlnx ${PWD}/project-spec/meta-user/ -f"
  • optional overwrite, add UBoot settings on platform-top.h
Device Tree
  • recipes-bsp/device-tree/files/system-user.dtsi
  • recipes-bsp/device-tree/files/pl-custom.dtsi
overwrite, add device tree attributes
Kernel
  • recipes-kernel/linux/linux-xlnx/
  • changes with "petalinux-config -c kernel" will be add in the yocto workspace 
  • force changes to the user layer run  "petalinux-devtool finish linux-xlnx ${PWD}/project-spec/meta-user/ -f"
Apps
  • project-spec/meta-user/recipes-apps

add simple new app with "petalinux-create -t apps -n myapp --enable"

enable/disable with "petalinux-config -c rootfs"


Additional Descriptions

References

  1. PetaLinux Tools Documentation - Reference Guide (UG1144)
  2. PetaLinux Tools Documentation - PetaLinux Command Line Reference (UG1157)

  3. https://www.devicetree.org/
    1. https://www.devicetree.org/specifications/
  4. https://github.com/Xilinx/linux-xlnx/tree/master/Documentation/devicetree/bindings

PetaLinux 2019.2

PetaLinux Installation

Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two. Basic Note to TE Petalinux Templates, see: PetaLinux TE-Template#Template-PetaLinux2019.2

  1. PetaLinux Working Environment (see UG1144)
  2. (optional to create project from scretch instead of Trenz Templates) Create a New Project (see UG1144): 
    1. $ petalinux-create --type project --template <CPU_TYPE> --name <PROJECT_NAME>

      • <CPU_TYPE>: zynqMP, zynq, microblaze
      • <PROJECT_NAME>:The name of the project you are building
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" for BOOT.BIN generation.  It is recommended to create the FSBL and PMU Firmware (ZynqMP only) with Vitis tools.

Petalinux Configuration

Most settings can be changed with menu-config:

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Boot
  • recipes-bsp/u-boot/files/platform-top.h
overwrite, add UBoot settings
Device Tree
  • recipes-bsp/device-tree/files/system-user.dtsi
  • recipes-bsp/device-tree/files/pl-custom.dtsi
overwrite, add device tree attributes
Kernel
  • recipes-kernel/linux/linux-xlnx/

changes with "petalinux-config -c kernel" will be add here automatically

Apps
  • project-spec/meta-user/recipes-apps

add simple new app with "petalinux-create -t apps -n myapp --enable"

enable/disable with "petalinux-config -c rootfs"

PetaLinux 2018.3

PetaLinux Installation

Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two. Basic Note to TE Petalinux Templates, see: PetaLinux TE-Template#Template-PetaLinux2018.3

  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL and PMU Firmware (ZynqMP only) with SDK/HSI tools.

Petalinux Configuration

Most settings can be changed with menu-config:

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Bootrecipes-bsp/u-boot/files/platform-top.hoverwrite, add UBoot settings
Device Tree

recipes-bsp/device-tree/files/system-user.dtsi
recipes-bsp/device-tree/files/zynqmp-qemu-arm.dts

overwrite, add device tree attributes
Kernelrecipes-kernel/linux/linux-xlnx/

changes with "petalinux-config -c kernel" will be add here automatically

Appsproject-spec/meta-user/recipes-apps

add simple new app with "petalinux-create -t apps -n myapp --enable"

enable/disable with "petalinux-config -c rootfs"

PetaLinux 2018.2

PetaLinux Installation

Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two.

Some 18.2 designs include "./init_config.sh" to change directory path (CONFIG_TMP_DIR_LOCATION  on <plnx-proj-root>/project-spec/configs/config). This is not longer necessary with petalinux 2018.2. this files will be removed on later updates


  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL and PMU Firmware (ZynqMP only) with SDK/HSI tools.

Petalinux Configuration

Most settings can be changed with menu-config ($ petalinux-config, petalinux-config -c kernel, petalinux-config -c rootfs).

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Bootrecipes-bsp/u-boot/files/platform-top.hoverwrite, add UBoot settings
Device Tree

recipes-bsp/device-tree/files/system-user.dtsi
recipes-bsp/device-tree/files/zynqmp-qemu-arm.dts

overwrite, add device tree attributes
Kernelrecipes-kernel/linux/linux-xlnx/

changes with "petalinux-config -c kernel" will be add here automatically

PetaLinux 2017.4

PetaLinux Installation

Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two.

PetaLinux 17.4 is using one absolute path in "<plnx-proj-root>/project-spec/configs/config
Change path of CONFIG_TMP_DIR_LOCATION variable to your project path "<plnx-proj-root>/build/tmp" manually or use provided "./init_config.sh" to change path variable automatically. If missing, change execution rights for init_config.sh with chmod


  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL and PMU Firmware (ZynqMP only) with SDK/HSI tools.
  7. Note: uboot need also boot.scr from the  "<plnx-proj-root>/images/linux" folder. This can be put on SD card or must be included into Boot.bin for QSPI boot without SD usage.

Petalinux Configuration

Most settings can be changed with menu-config ($ petalinux-config, petalinux-config -c kernel, petalinux-config -c rootfs).

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Bootrecipes-bsp/u-boot/files/platform-top.hoverwrite, add UBoot settings
Device Tree

recipes-bsp/device-tree/files/system-user.dtsi
recipes-bsp/device-tree/files/zynqmp-qemu-arm.dts

overwrite, add device tree attributes
Kernelrecipes-kernel/linux/linux-xlnx/

changes with "petalinux-config -c kernel" will be add here automatically

PetaLinux 2017.2

PetaLinux Installation

Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two.

PetaLinux 17.2 is using one absolute path in "<plnx-proj-root>/project-spec/configs/config
Change path of CONFIG_TMP_DIR_LOCATION variable to your project path "<plnx-proj-root>/build/tmp" manually or use provided "init_config.sh" to change path variable automatically.


  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL and PMU Firmware (ZynqMP only) with SDK/HSI tools.

Petalinux Configuration

Most settings can be changed with menu-config ($ petalinux-config, petalinux-config -c kernel, petalinux-config -c rootfs).

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Bootrecipes-bsp/u-boot/files/platform-top.hoverwrite, add UBoot settings
Device Tree

recipes-bsp/device-tree/files/system-user.dtsi
recipes-bsp/device-tree/files/zynqmp-qemu-arm.dts

overwrite, add device tree attributes
Kernelrecipes-kernel/linux/linux-xlnx/changes with "petalinux-config -c kernel" will be add here automatically

PetaLinux 2017.1

PetaLinux Installation


Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two.

PetaLinux 17.1 is using one absolute path in "<plnx-proj-root>/project-spec/configs/config
Change path of CONFIG_TMP_DIR_LOCATION variable to your project path "<plnx-proj-root>/build/tmp" manually.



  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub,  bl31.elf (ZynqMP only) and pmufw.elf (ZynqMP only) from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL with SDK/HSI tools.

Petalinux Configuration

Most settings can be changed with menu-config ($ petalinux-config, petalinux-config -c kernel, petalinux-config -c rootfs).

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Bootrecipes-bsp/u-boot/files/platform-top.hoverwrite, add UBoot settings
Device Treerecipes-bsp/device-tree/files/system-user.dtsioverwrite, add device tree attributes
Kernelrecipes-kernel/linux/linux-xlnx/changes with "petalinux-config -c kernel" will be add here automatically

PetaLinux 2016.4

PetaLinux Installation


Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two.

PetaLinux 16.4 is using one absolute path in "<plnx-proj-root>/project-spec/configs/config
Change path of CONFIG_TMP_DIR_LOCATION variable to your project path "<plnx-proj-root>/build/tmp" manually.



  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf,  image.ub and bl31.elf (zynqMP only) from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL with SDK/HSI tools.

Petalinux Configuration

Most settings can be changed with menu-config ($ petalinux-config, petalinux-config -c kernel, petalinux-config -c rootfs).

Manual changes can be done in the subfolder "<plnx-proj-root>/project-spec/meta-user/"

U-Bootrecipes-bsp/u-boot/files/platform-top.hoverwrite, add UBoot settings
Device Treerecipes-dt/device-tree/files/system-top.dtsoverwrite, add device tree attributes
Kernelrecipes-kernel/linux/linux-xlnx/changes with "petalinux-config -c kernel" will be add here automatically

PetaLinux 2016.2

PetaLinux Installation


Creating a Project from Vivado Project

Some reference designs contains a preconfigured PetaLinux project as template. This can be used instead of creating a new project described on step two.

  1. PetaLinux Working Environment (see UG1144)
  2. Create a New Project (see UG1144):
  3. Import Hardware Configuration (see UG1144):
  4. (optional) Configure your PetaLinux:
  5. Build System Image (see UG1144):
  6. Take u-boot.elf and image.ub from "<plnx-proj-root>/images/linux" and make BOOT.BIN.  It is recommended to create the FSBL with SDK/HSI tools.

Petalinux Configuration

Most settings can be changed with menu-config ($ petalinux-config).

There are 3 more files that user can edit, they are

FileDescriptionLocation
system-top.dtsDevice tree changes are to be applied here<petalinux-project>/subsystems/linux/configs/device-tree
platform-top.hU-boot changes are to be applied here<petalinux-project>/subsystems/linux/configs/u-boot
fsbl_hooks.cFSBL changes are to be applied hereSDK/HSI FSBL-Template

There should be no reason to modify any other files by editing them (most of them are generated and would be overwritten).