PetaLinux Project Structure - 2023.2 English

PetaLinux Tools Documentation: Reference Guide (UG1144)

Document ID
UG1144
Release Date
2023-10-18
Version
2023.2 English

This section provides a brief introduction to the file and directory structure of a PetaLinux project. A PetaLinux project supports development of a single Linux system development at a time. A built Linux system is composed of the following components:

  • Device tree
  • First stage boot loader (optional)
  • U-Boot
  • Linux kernel
  • The root file system is composed of the following components:
    • Prebuilt packages
    • Linux user applications (optional)
    • User modules (optional)

A PetaLinux project directory contains configuration files of the project, the Linux subsystem, and the components of the subsystem. The petalinux-build command builds the project with those configuration files. You can run petalinux-config to modify them. The following is an example of a PetaLinux project:

project-spec
   hw-description
   configs
   meta-user
pre-built
   linux
      implementation
      images 
      xen    
hardware
  <project-name>
components
   plnx_workspace
      device-tree
config.project
README
Table 1. PetaLinux Project Description
File / Directory in a PetaLinux Project Description
/.petalinux/ Directory to hold tools usage.
/config.project/ Project configuration file.
/project-spec Project specification.
/project-spec/hw-description Hardware description imported from AMD Vivado™ design tools.
/project-spec/configs Configuration files of top level config and RootFS config.
/project-spec/configs/config Configuration file used to store user settings.
/project-spec/configs/rootfs_config Configuration file used for root file system.
/project-spec/configs/busybox Configuration file for busybox.
/project-spec/configs/init-ifupdown Configuration file for Ethernet.
/components/plnx_workspace/device-tree/device-tree/

Device tree files used to build device tree. The following files are auto generated by petalinux-config:

  • skeleton.dtsi (Zynq 7000 devices only)
  • zynq-7000.dtsi (Zynq 7000 devices only)
  • zynqmp.dtsi (Zynq UltraScale+ MPSoC only)
  • pcw.dtsi (Zynq 7000 devices and Zynq UltraScale+ MPSoC only)
  • pl.dtsi
  • system-conf.dtsi
  • system-top.dts
  • <bsp name>.dtsi
  • versal.dtsi for Versal

It is not recommended to edit these files, as these files are regenerated by the tools.

/project-spec/meta-user/recipes-bsp/device-tree/files/ system-user.dtsi is not modified by any PetaLinux tools. This file is safe to use with revision control systems. In addition, you can add your own DTSI files to this directory. You have to edit the <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend by adding your DTSI file.
/project-spec/meta-user/recipes-bsp/u-boot/files/platform-top.h (only for MicroBlaze processors) platform-top.h is copied to include/configs/ directory in the U-Boot source
/project-spec/meta-user/conf/petalinuxbsp.conf This configuration file contains all the local user configurations for your build environment. It is a substitute for local.conf in the Yocto meta layers.
  1. All the paths are relative to <plnx-proj-root>.

When the project is built, three directories are auto generated:

  • <plnx-proj-root>/build for the files generated for build.
  • <plnx-proj-root>/images for the bootable images.
  • <plnx-proj-root>/build/tmp for the files generated by Yocto. This directory is configurable through petalinux-config.
  • <plnx-proj-root>/components/yocto has Yocto eSDK. This file is generated when execute petalinux-config/petalinux-build.
  • When petalinux-package --prebuilt is run, it creates a pre-built/directory in <PROJECT>/ and copies the build image files from the <PROJECT>/images/linux directory to the <PROJECT>/pre-built/linux/images/ directory.

Here is an example:

├── build
│   ├── bitbake-cookerdaemon.log
│   ├── build.log
│   ├── cache
│   ├── conf
│   ├── downloads
│   ├── misc
│   ├── sstate-cache
│   └── tmp
├── components
│   ├── plnx_workspace
│   └── yocto
├── config.project
├── hardware
│   └── project-name
├── images
│   └── linux
├── pre-built
│   └── linux
├── project-spec
│   ├── attributes
│   ├── configs
│   ├── hw-description
│   └── meta-user
└── README
Note: <plnx-proj-root>/build/ are automatically generated. Do not manually edit files in this directory. Contents in this directory are updated when you run petalinux-config or petalinux-build. <plnx-proj-root>/images/ are also automatically generated. Files in this directory are updated when you run petalinux-build.

The following table is an example for AMD Zynq™ UltraScale+™ MPSoC.

By default the build artifacts are removed to preserve space after petalinux-build. To preserve the build artifacts, you have to add the INHERIT:remove = "rm_work" in <plnx-proj-root>/project-spec/meta-user/conf/petalinuxbsp.conf, but it increases the project space.

Table 2. Build Directory in a PetaLinux Project
Build Directory in a PetaLinux Project Description
<plnx-proj-root>/build/build.log Logfile of the build.
<plnx-proj-root>/build/misc/config/ Directory to hold files related to the Linux subsystem build.
<plnx-proj-root>/build/misc/rootfs_config/ Directory to hold files related to the RootFS build.
${TMPDIR}/work/zynqmp_generic-xilinx-linux/petalinux-image-minimal/1.0-r0/rootfs RootFS copy of target. This is the staging directory.
${TMPDIR}/zynqmp_generic-xilinx-linux Stage directory to hold the libs and header files required to build user apps/libs.
${TMPDIR}/work/zynqmp_generic-xilinx-linux/linux-xlnx/ Directory to hold files related to the kernel build.
${TMPDIR}/work/zynqmp_generic-xilinx-linux/u-boot-xlnx Directory to hold files related to the U-Boot build.
<plnx-proj-root>/components/plnx_workspace/device-tree/device-tree" Directory to hold files related to the device tree build.
<plnx-proj-root>/components/yocto Directory to hold Yocto eSDK content.
Table 3. Image Directory in a PetaLinux Project
Image Directory in a PetaLinux Project Description
<plnx-proj-root>/images/linux/ Directory to hold the bootable images for Linux subsystem
<plnx-proj-root>/images/linux Directory to hold the bootable images for xen hyperviser