Technical FAQs - 2025.1 English - UG1144

PetaLinux Tools Documentation: Reference Guide (UG1144)

Document ID: UG1144
Release Date: 2025-05-29
Version: 2025.1 English

Overview
Introduction
Navigating Content by Design Process
Setting Up Your Environment
Installation Steps
Installation Requirements
Prerequisites
Installing the PetaLinux Tool
Installing a Preferred eSDK as part of the PetaLinux Tool
Troubleshooting
PetaLinux Working Environment Setup
Prerequisites
Steps to Set Up PetaLinux Working Environment
Troubleshooting
Design Flow Overview
Creating a Project
Creating a Project Using PetaLinux BSP
Prerequisites
Creating a Project from a BSP
Troubleshooting
Configuring a Hardware Platform with Vivado Design Suite
Configuring a Hardware Platform for Linux
Exporting a Hardware Platform to PetaLinux Project
Prerequisites
Exporting a Hardware Platform
Creating an Empty Project from a Template
Prerequisites
Creating an Empty Project
Configuring and Building
Version Control
Prerequisites
Version Control
Importing Hardware Configuration
Prerequisites
Importing a Hardware Configuration
Silentconfig
Building a System Image
Prerequisites
Building a PetaLinux System Image
Default Boot Images
Troubleshooting
System Devicetree flow to Build Images
Setting Up the System Devicetree
Building the project using Template Flow
Building the project using BSP Flow
Building multiconfig Applications
Build Optimizations
Packaging and Booting
Packaging Boot Image
Generate Boot Image for Versal Adaptive SoC
Prerequisites
Generate Boot Image
Generate MCS Image
Generate Boot Image for Zynq UltraScale+ MPSoC
Prerequisites
Generate Boot Image
Generate MCS Image
Generate Boot Image for Zynq 7000 Devices
Prerequisites
Generate Boot Image
Generate MCS Image
Generate Boot Image for MicroBlaze Processor
Prerequisites
Generate Boot Image
Modify Bitstream File for MicroBlaze Processor
Prerequisites
Modify Bitstream
Packaging Prebuilt Images
Prerequisites
Packaging Prebuilt Image
BSP Packaging
Prerequisites
BSP Packaging
Additional BSP Packaging Options
Booting PetaLinux Prebuilt Images
Prerequisites
Boot Levels for Prebuilt Option
Booting PetaLinux Image on QEMU
Prerequisites
Booting a PetaLinux Image on QEMU
Additional Options for Booting on QEMU
Booting PetaLinux Image on Hardware with an SD Card
Prerequisites
Booting a PetaLinux Image on Hardware with SD Card
Troubleshooting
Booting PetaLinux Image on Hardware with JTAG
Prerequisites
Booting a PetaLinux Image on Hardware with JTAG
Additional Options for Booting with JTAG
Logging Tcl/XSDB for JTAG Boot
Troubleshooting
Booting PetaLinux Image on Hardware with TFTP
Prerequisites
Booting a PetaLinux Image on Hardware with TFTP
Troubleshooting
Booting PetaLinux Image on Hardware with QSPI or OSPI
Prerequisites
Booting a PetaLinux Image on Hardware with QSPI or OSPI
Troubleshooting
Boot from HBM/Higher DDR/LPDDR
Upgrading the Workspace
Upgrading Between Minor Releases (2025.1 Tool with 2025.x Tool)
Upgrade PetaLinux Tool
Upgrade from Local File
Upgrade from Remote Server
Upgrade PetaLinux Project
Upgrade an Existing Project with the Upgraded Tool
Upgrading the Installed Tool with More Platforms
Upgrading the Installed Tool with your Customized Platform
Customizing the Project
Configuring Firmware Version
Prerequisites
Firmware Version Configuration
Configuring Root File System Type
Prerequisites
Steps for Root File System Type Configuration
Configuring U-Boot Boot Script (boot.scr)
Troubleshooting
Configuring Primary Flash Partition
Configuring INITRD Boot
Prerequisites
Configuring INITRD Boot
Configuring INITRAMFS Boot
Prerequisites
Configuring INITRAMFS Boot
Configuring TFTP/PXE Boot
Prerequisites
PetaLinux Configuration and Build System Image
Configuring NFS Boot
Prerequisites
PetaLinux Configuration and Build System Image
Booting with NFS
Configuring UBIFS Boot
Prerequisites
Configuring UBIFS Boot
Calculating the Arguments for mkfs.ubifs and ubinize
Configuring SD Card ext File System Boot
Prerequisites
Preparing the SD Card
PetaLinux Configuration and Build System Image
Copying Image Files
Troubleshooting
Managing Image Size
Prerequisites
Steps for Managing Image Size
Customizing the Root File System
Including Prebuilt Libraries
Prerequisites
Including Prebuilt Applications
Prerequisites
Including Prebuilt Applications
Creating and Adding Custom Libraries
Prerequisites
Creating Apps in PetaLinux Project
Prerequisites
Creating and Adding Custom Applications
Prerequisites
Adding Custom Applications
Creating and Adding Custom Kernel Modules
Prerequisites
Adding Custom Modules
Building User Applications
Prerequisites
Building User Applications
Testing User Applications
Prerequisites
Testing User Application
Building User Modules
Prerequisites
Building User Modules
PetaLinux Auto Login
Prerequisites
Steps to Enable Serial Auto Login
Application Auto Run at Startup
Prerequisites
Adding Layers
Adding an Existing Recipe into the Root File System
Adding a Package Group
Appending Root File System Packages
Debugging
Debugging the Linux Kernel in QEMU
Prerequisites
Steps to Debug the Linux Kernel in QEMU
Troubleshooting
Debugging Applications with TCF Agent
Prerequisites
Preparing the Build System for Debugging
Performing a Debug Session
Debugging Zynq UltraScale+ MPSoC and Versal Adaptive SoC Applications with GDB
Prerequisites
Preparing the Build System for Debugging
Performing a Debug Session
Going Further with GDB
Troubleshooting
Debugging Individual PetaLinux Components
PMU Firmware
FSBL
U-Boot
Linux
Advanced Configurations
Menuconfig Usage
PetaLinux Menuconfig System
Linux Components Selection
Auto Config Settings
Building Device Tree Overlays for PS
Subsystem AUTO Hardware Settings
DTG Settings
PMU Firmware Configuration for Zynq UltraScale+ MPSoC
FSBL Configuration for Zynq UltraScale+ MPSoC
Trusted Firmware-A Configuration for Zynq UltraScale+ MPSoC and Versal Adaptive SoC
FPGA Manager Configuration and Usage for Zynq 7000 Devices and Zynq UltraScale+ MPSoC
U-Boot Configuration
Building a Separate U-Boot DTB
Image Packaging Configuration
Firmware Version Configuration
Yocto Settings
Open Source Bootgen for On-target Use for Zynq Devices, Versal Adaptive SoC, and Zynq UltraScale+ MPSoC
Configuring Out-of-tree Build
Prerequisites
Configuring Out-of-tree Build
Using External Kernel and U-Boot with PetaLinux
Troubleshooting
Configuring Project Components
Device Tree Configuration
Prerequisites
Configuring Device Tree
U-Boot Configuration
Prerequisites
Configuring U-Boot
Yocto Features
SDK Generation (Target Sysroot Generation)
Building SDK
Installing SDK
Examples
Building an eSDK
Packaging Sources and Licenses
Accessing BitBake/Devtool in a Project
Steps to Access the BitBake Utility
Steps to Access the Devtool Utility
Shared State Cache
Sharing your State Cache
Downloading Mirrors
Machine Support
SoC Variant Support
Image Features
Filtering RootFS Packages Based on License
Creating and Adding Patches For Software Components within a PetaLinux Project
Known Issues for the Devtool Flow
Adding Extra Users to the PetaLinux System
Technical FAQs
Troubleshooting
TMPDIR on NFS
Recipe Name has ' _ ' or Uppercase Letters or Starts with an Uppercase Letter
Recover from Corrupted Terminal
Python Language Settings
Menuconfig Hang for Kernel and U-Boot
Menuconfig Not Seen for Kernel and U-Boot
Menuconfig Corruption for Kernel and U-Boot
External Source Configurations
do_image_cpio: Function Failed
Package Management
Common Tar Usage
Workaround for uid_map error on Ubuntu 24.04
Linux Boot Hang with Large INITRAMFS Image in Zynq 7000 Devices and Zynq UltraScale+ MPSoC
Detailed Component-based Logs
PetaLinux Environment Issues
Password Recovery
Open Source PetaLinux
Migration
PetaLinux Supported Dynamic Configuration
Dynamic Configuration Support in PetaLinux
FPGA Manager Full PL Programming
Zynq 7000
ZynqMP
Versal (Segmented Configuration Flow)
Dynamic Functional Exchange (DFX) Flow
Versal
ZynqMP
Dynamic Configuration with User Specified dtsi/dtbo Flow for Zynq/ZynqMP/Versal
Customizing the Generated Dynamic Configuration PL dtsi Files
Examples
Login Changes
Systemv to Systemd
Yocto Override Syntax Changes
Yocto Recipe Name Changes
U-Boot Image Changes
MCS File Support
BIF File Changes
Use Yocto Environment Variables in petalinux-config Option
Host GCC Version Upgrade
Removed config.project
Usage of uenv.txt
Renamed ARM Trusted Firmware Configuration
DTG Deprecation Message
PetaLinux to Create PL Applications and Install on Target
PetaLinux Project Structure
Project Layers
Generating Boot Components
Platform Loader and Manager Firmware (PLM)
Processing System Management Firmware (PSM)
Image Selector
First Stage Boot Loader for Zynq UltraScale+ and Zynq 7000 Devices
Trusted Firmware-A (TF-A)
PMU Firmware
FS-Boot for MicroBlaze Platform Only
QEMU Virtual Networking Modes
AMD IP Models Supported by QEMU
Xen Zynq UltraScale+ MPSoC and Versal Adaptive SoC Example
Prerequisites
Boot Prebuilt Linux as dom0
Rebuild Xen
Boot Built Linux as dom0
Booting Prebuilt OpenAMP
Partitioning and Formatting an SD Card
Auto-mounting an SD Card
Deprecated BSP Support
PetaLinux Commands
petalinux-create
petalinux-create Command Line Options
petalinux-create project
petalinux-create project Options
petalinux-create project Examples
petalinux-create apps/modules
petalinux-create apps Options
petalinux-create apps/modules Examples
petalinux-config
petalinux-config Command Line Options
petalinux-config --get-hw-description
petalinux-config --get-hw-description Examples
petalinux-config -c COMPONENT
petalinux-config -c COMPONENT Examples
petalinux-build
petalinux-build Command Line Options
petalinux-build --component
petalinux-build -c component options
petalinux-build --execute
Commands for petalinux-build -x
petalinux-build Examples
petalinux-boot
petalinux-boot Command Line Options
petalinux-boot jtag
petalinux-boot jtag Options
petalinux-boot jtag Examples
petalinux-boot qemu
petalinux-boot qemu Options
petalinux-boot qemu Examples
petalinux-package
petalinux-package Command Line Options
petalinux-package boot
petalinux-package boot Command Options
petalinux-package boot Examples
petalinux-package bsp
petalinux-package bsp Command Options
petalinux-package bsp Command Examples
petalinux-package prebuilt
petalinux-package prebuilt Command Options
petalinux-package prebuilt Command Examples
petalinux-package sysroot
petalinux-package sysroot Command Options
petalinux-package sysroot Command Examples
petalinux-package wic
petalinux-package wic Command Options
petalinux-package wic Command Examples
petalinux-util
petalinux-util gdb
petalinux-util gdb command Examples
petalinux-util dfu-util
petalinux-util dfu-util Command Examples
petalinux-util xsdb-connect
petalinux-util xsdb-connect Options
petalinux-util find-xsa-bitstream
petalinux-util find-xsa-bitstream Options
petalinux-util find-xsa-bitstream Examples
petalinux-upgrade
petalinux-upgrade Options
petalinux-devtool
petalinux-devtool Command Line Options
petalinux-devtool Examples
Additional Resources and Legal Notices
Finding Additional Documentation
Support Resources
Revision History
References
Please Read: Important Legal Notices

Back to home page