Example Project: Creating Linux Images Using PetaLinux - Example Project: Creating Linux Images Using PetaLinux - 2025.2 English - UG1305

Versal Adaptive SoC Embedded Design Tutorial (UG1305)
Document ID
UG1305
Release Date
2025-12-09
Version
2025.2 English

This section explains how to configure and build the Linux operating system for an Arm Cortex-A72 core-based APU on a Versal device. You can use the PetaLinux tool with the board-specific BSP to configure and build Linux images.

This example needs a Linux host machine. Refer to the PetaLinux Tools Documentation Reference Guide UG1144 for information on dependencies and installation procedure for the PetaLinux tool.

Important

This example uses the VPK180 PetaLinux BSP to create a PetaLinux project. Ensure that you have downloaded the respective BSP for PetaLinux (VPK180).

Board

QSPI/SD

OSPI

eMMC

VPK180 Production Board

xilinx-vpk180-v2024.1-05230256.bsp <https://www.xilinx.com/member/forms/download/xef.html?filename=xilinx-vpk180-v2024.1-05230256.bsp>

N/A

N/A

  1. Copy the respective board’s PetaLinux BSP to the current directory.

  2. Set up the PetaLinux environment

    $ source <petalinux-tools-path>/settings.csh

  3. Create a PetaLinux project using the following command.

    $ petalinux-create -t project -s xilinx-vpk180-vxxyy.z-final.bsp -n led_example

    Note

    • For VPK180 board, use xilinx-vpk180-vxxyy.z-final.bsp after the -s option in the command.

  4. Change to the PetaLinux project directory using the following command.

    $cd led_example

  5. Copy the hardware platform project XSA to the Linux host machine.

    Note

    For the VPK180 board, use the XSA file that you generated in the Design Example: Using AXI GPIO.

  6. Follow these commands to create the sdtout file using the XSA.

    1. Source the Vivado tool (2025.2 release version):

    $ source < vivado-tools-path >/settings64.sh

    1. Run the sdtgen command to generate the sdtout:

      $ sdtgen
sdtgen% set_dt_param -dir sdt_out -xsa <XSA_PATH> -board_dts versal-vpk180-reva
sdtgen% generate_sdt
sdtgen% exit

  7. Reconfigure the BSP using the following commands.

    $ petalinux-config --get-hw-description=<path till the directory containing the generated sdtout>

    This command opens the PetaLinux Configuration window. For this example, no need to change anything in this window.

  8. Click <Save> to save the above configuration and then <Exit> to exit the configuration wizard.

  9. Create a Linux application named gpiotest within the PetaLinux project using the following command.

    $petalinux-create -t apps --template install --name gpiotest --enable

  10. Copy application files from <design-package>/<vpk180>/linux/bootimages to the project using the following commands.

$cp <design-package>/ch7_system_design_example_source__files/apu/gpiotest_app/gpiotest/files/* <plnxproj-root>/project-spec/meta-user/recipes-apps/gpiotest/files/
$cp <design-package>/ch7_system_design_example_source__files/apu/gpiotest_app/gpiotest/gpiotest.bb <plnx-proj-root>/project-spec/meta-user/recipes-apps/gpiotest/gpiotest.bb
$cp <design-package>/ch7_system_design_example_source__files/apu/device_tree/system-user.dtsi <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi

  1. Enable GPIO support within kernel configuration.

    $petalinux-config -c kernel

    Note

    This command opens the kernel configuration wizard for the PetaLinux project.

  2. Navigate to Device drivers→ GPIO Support and enable it by pressing the <Y> key. Press Enter and enable the Debug GPIO calls and /sys/class/gpio/...(sysfs interface) entries by pressing the <Y> key as shown in the following figure.

    ../_images/ch7_gpio_debug.png

  3. To verify GPIO support and Zynq GPIO support are enabled, navigate to Memory mapped GPIO drivers and ensure GPIO support and Zynq GPIO support are enabled (press <Y> to enable) as shown in the following figure.

    ../_images/ch7_gpio_xilinx.png

  4. Click <Save> to save the above configuration and then <Exit> option to exit the configuration wizard.

  5. Configure ROOTFS to disable the AIE, STDC++, and Tcl options to reduce the rootfs size to fit into both SD and OSPI/QSPI Flash partitions.

    petalinux-config -c rootfs

  6. Navigate to User Packages and disable openamp-demo-notebooks by pressing <Y> key as shown in the following figure and ensure the following configurations are disabled: aie-notebooks, packagegroup-petalinux-jupyter, pm-notebooks, and python3-ipywidgets support.

    ../_images/ch7_rootfs_config_aie.png

  7. To verify libstdc++ is disabled, navigate to Filesystem Packages → misc → gcc-runtime and ensure libstdc++ support is disabled (Press <Y> to disable) as shown in the following figure.

    ../_images/ch7_rootfs_config_stdc++.png

  8. To verify tcl support is disabled, navigate to Filesystem Packages → devel → tcltk → tcl and ensure tcl support is disabled (Press <Y> to disable) as shown in the following figure.

    ../_images/ch7_rootfs_config_tcl.png

  9. Click <Save> to save the above configuration and then click <Exit> to exit the configuration wizard.

    Note

    Only SD and QSPI boot modes will work on VPK180 Production boards.

  10. Build the Linux images using the following command.

    $ petalinux-build

Note

Skipping steps 5 and 6 in the Synthesizing, Implementing, and Generating the Device Image section will result in PLM Error Status: 0x22220001 while booting PetaLinux.

After flashing the built images, all four LEDs which are connected to slave SLR will be turned on on the VPK180 board.