PetaLinux Tools Ation: Reference Guide (UG1144) Ug1144

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 104 [warning: Documents this large are best viewed by clicking the View PDF Link!]

PetaLinux Tools
Documentation
Reference Guide
UG1144 (v2016.4) December 14, 2016
Reference Guide 2
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Revision History
The following table shows the revision history for this document.
Date Version Revision
12/14/2016 2016.4 Updated for PetaLinux Tools 2016.4 release
10/25/2016 2016.3 Updated for PetaLinux Tools 2016.3 release
06/08/2016 2016.2 Updated for PetaLinux Tools 2016.2 release
05/06/2016 2016.1 Updated for PetaLinux Tools 2016.1 release
Reference Guide 3
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Table of Contents
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Chapter 1: PetaLinux Tools Documentation
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Installation Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
PetaLinux Working Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
PetaLinux BSP Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Create Hardware Platform with Vivado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Export Hardware Platform to PetaLinux Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Create a New PetaLinux Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Import Hardware Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Build System Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Generate Boot Image for Zynq Family Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Generate Boot Image for Zynq UltraScale+ MPSoC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Generate Boot Image for MicroBlaze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Package Prebuilt Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Using petalinux-boot Command with Prebuilt Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Boot a PetaLinux Image on QEMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Boot a PetaLinux Image on Hardware with SD Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Boot a PetaLinux Image on Hardware with JTAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Boot a PetaLinux Image on Hardware with TFTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BSP Packaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Firmware Version Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Root file system Type Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Boot Images Storage Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Primary Flash Partition Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Base Root File System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Managing Image Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring INITRAMFS Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Configure TFTP Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Configuring NFS Boot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Reference Guide 4
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Configuring SD Card ext filesystem Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Including Prebuilt Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Including Prebuilt Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Adding Custom Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Adding Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Building User Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Testing User Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Building User Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
PetaLinux Auto Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Application Auto Run at Startup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Debugging the Linux Kernel in QEMU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Debugging Applications with TCF Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Debugging Zynq UltraScale+ MPSoC Applications with GDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Configuring Out-of-tree Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Devicetree Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
U-Boot Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Kernel and U-boot Configuration flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 2: Yocto Features
Adding Patches to Source Repo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Accessing BitBake in a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Adding a Recipe from the Layers in SDk which are not in petalinux-image.bb . . . . . . . . . . . . . . . . 82
Adding Package Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Shared sstate-cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Reference Guide 5
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix A: PetaLinux Project Structure
Appendix B: Generating First Stage Bootloader Within Project
Appendix C: Auto Config Settings
Appendix D: QEMU Virtual Networking Modes
Appendix E: Xilinx IP Models Supported by QEMU
Appendix F: XEN Zynq Ultrascale+ MPSoC Example
Appendix G: Obsolete Features
Appendix H: Common Errors and Recovery
Appendix I: Additional Resources and Legal Notices
Xilinx Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Solution Centers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Please Read: Important Legal Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Reference Guide 6
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1
PetaLinux Tools Documentation
Introduction
PetaLinux is an Embedded Linux System Development Kit specifically targeting FPGA-based
System-on-Chip designs. This guide helps the reader to familiarize with the tool enabling
overall usage of PetaLinux.
Note: The reader of this document is assumed to have basic Linux knowledge, such as how to run
Linux commands. The reader should also be aware of OS and Host system features such as OS bit
version, Linux Distribution and Security Privileges.
The new PetaLinux tool contains the following:
1. Yocto Extensible SDK
Table 1-1 details the 4 Extensible SDK’s installed.
Table 1-1: Extensible SDK’s
Path Architecture
$PETALINUX/components/yocto/source/aarch64 for Zynq® Ultrascale+™
MPSoC
$PETALINUX/components/yocto/source/arm for Zynq
$PETALINUX/components/yocto/source/microblaze_full for MicroBlaze™ full designs
$PETALINUX/components/yocto/source/microblaze_lite for MicroBlaze lite designs
Reference Guide 7
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
The e-SDK consists of:
a. Layers - This contains all the layers for an architecture. The e-SDk had poky,meta-oe
and other popular layers.
For example, for Zynq Ultrascale+ MPSoC:
$PETALINUX/components/yocto/source/aarch64/layers
b. sstate-cache - By design, the OpenEmbedded build system builds everything from
scratch unless BitBake can determine that parts do not need to be rebuilt.
Fundamentally, building from scratch is attractive as it means all parts are built fresh
and there is no possibility of stale data causing problems.
The Yocto Project implements shared state code that supports incremental builds. It
stores all task intermediate build artifacts and reuses them if there is no change in
input taks , hence reduces the build time
For example: The sstate-cache of Zynq Ultrascale+ MPSoC is at:
$PETALINUX/components/yocto/source/aarch64/sstate-cache
c. sysroot - This contains sysroot for host and the target
For example: The sysroot of Zynq Ultrascale+ MPSoC is at:
$PETALINUX/components/yocto/source/aarch64/sysroot
2. Minimal downloads
BitBake checks pre-mirrors before looking upstream for any source files. Pre-mirrors are
appropriate when you have a shared directory that is not a directory defined by the
DL_DIR variable. A Pre-mirror points to a shared directory that is in tool. All projects of
the tool use these pre-mirrors and fetch the source code from them.
The pre-mirror in tool points to: $PETALINUX/components/yocto/downloads.
The downloads directory will have tar balls of source code for linux kernel, uboot and
other minimal utilities.
Table 1-2: Layers from Xilinx
Layer Recipes
meta-xilinx Contains recipes of linux kernel, uboot and ATF
meta-xilinx-tools Contains recipes of all embeddedSW apps: fsbl, pmufw, fsboot, device-tree
meta-petalinux Contains distro recipes and package groups
petalinux-minimal --> minimal feature set
petalinux-image ---> Full feature set
Reference Guide 8
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. XSCT and tool chains
The PetaLinux tool uses XSCT underneath for all embeddedSW apps. It also contains
tool chains of all architectures.
4. PetaLinux Commands
This contains all the petalinux commands which you require.
Installation Requirements
The PetaLinux Tools Installation requirements are:
• Minimum workstation requirements:
°4 GB RAM (recommended minimum for Xilinx tools)
°Pentium 4 2GHz CPU clock or equivalent (minimum of 4 cores)
°100 GB free HDD space
°Supported OS:
- RHEL 6.6/6.7/7.1/7.2 (64-bit)
- CentOS 7.1 (64-bit)
- SUSE Enterprise 12.0 (64-bit)
- Ubuntu 16.04 (64 bit)
• You need to have root access to perform some operations.
• PetaLinux requires a number of standard development tools and libraries to be
installed on your Linux host workstation. Install the libraries and tools listed in the
following table on your host Linux. All of the listed Linux Workstation Environments
below have the 32-bit libraries needed by the PetaLinux tool. If any addition tool chains
are packages needing 32-bit libs on host are needed, install the same before issuing
petalinux-build. Table 1-3 below describes the required packages, and how to install
them on different Linux workstation environments.
Table 1-3: Packages and Linux Workstation Environments
Tool /
Library CentOS7.1 RHEL6.6 RHEL6.7 RHEL7.1 RHEL7.2 SUSE 12.0 Ubuntu 16.04
python python:
2.7.3
python:
2.7.3
python:
2.7.3
python:
2.7.3
python:
2.7.3
python:
2.7.3
python: 2.7.3
dos2unix dos2unix
6.0.3
dos2unix
3.1-37
dos2unix
3.1-37
dos2unix
6.0.3
dos2unix
6.0.3
dos2unix
6.0.4
tofrodos
1.7.13
Reference Guide 9
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
ip iproute
3.10.0
iproute
2.6.32
iproute
2.6.32
iproute
3.10.0
iproute
3.10.0
iproute2 iproute2
gawk gawk 4.0.2 gawk 3.1.7 gawk 3.1.7 gawk 4.0.2 gawk 4.0.2 gawk 4.1.0 gawk 4.0.1
xvfb-run xvfb-run xvfb-run xvfb-run xvfb-run xvfb-run xvfb-run xvfb-run
gcc gcc 4.8.3 gcc 4.4.7 gcc 4.4.7 gcc 4.8.3 gcc 4.8.5 gcc 4.8 gcc 4.8
git git 1.8.3 git 1.7.1 git 1.7.1 git 1.8.3 git 1.8.3 git 1.7.1 or
above
git 1.7.1 or
above
make make 3.81 make 3.81 make 3.81 make 3.82 make 3.82 make 4.0 make 3.81
netstat net-tools
2.0
net-tools
1.60
net-tools
1.60
net-tools
2.0
net-tools
2.0
net-tools net-tools
ncurses
devel
ncurses
-devel
5.9-13
ncurses
-devel
5.7-3
ncurses
-devel
5.7-4
ncurses
-devel
5.9-13
ncurses
-devel
5.9-13
ncurses
-devel
libncurses5
-dev
tftp
server
tftp-server tftp-server tftp-server tftp-server tftp-server atftp or
yast2
-tftp-server
tftpd
zlib devel zlib-devel
1.2.7
zlib-devel
1.2.3
zlib-devel
1.2.3
zlib-devel
1.2.7
zlib-devel
1.2
zlib-devel zlib1g-dev
openssl
devel
openssl
-devel 1.0
openssl
-devel 1.0
openssl
-devel 1.0
openssl
-devel 1.0
openssl
-devel 1.0
libopenssl
-devel
libssl
-dev
flex flex 2.5.37 flex 2.5.35 flex 2.5.35 flex 2.5.37 flex 2.5.37 flex flex
bison bison-2.7 bison-2.4.1 bison-2.4.1 bison-2.7.4 bison-2.7.4 bison bison
libselinux libselinux
2.2.2
libselinux
2.0.94
libselinux
2.0.94
libselinux
2.2.2
libselinux
2.2.2
libselinux
2.3.2
libselinux1
gpg gpg gpg gpg gpg gpg gpg gpg
wget wget wget wget wget wget wget wget
diffstat diffstat diffstat diffstat diffstat diffstat diffstat diffstat
chrpath chrpath chrpath chrpath chrpath chrpath chrpath chrpath
socat socat socat socat socat socat socat socat
xterm xterm xterm xterm xterm xterm xterm xterm
autoconf autoconf autoconf autoconf autoconf autoconf autoconf autoconf
libtool libtool libtool libtool libtool libtool libtool libtool
tar tar:1.24 tar:1.24 tar:1.24 tar:1.24 tar:1.24 tar:1.24 tar:1.24
unzip unzip unzip unzip unzip unzip unzip unzip
texinfo texinfo texinfo texinfo texinfo texinfo texinfo texinfo
zlib1g-de
v
------zlib1g-dev
Table 1-3: Packages and Linux Workstation Environments
Tool /
Library CentOS7.1 RHEL6.6 RHEL6.7 RHEL7.1 RHEL7.2 SUSE 12.0 Ubuntu 16.04
Reference Guide 10
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
CAUTION! Consult your system administrator if you are not sure about the correct procedures for host
system package management.
IMPORTANT: PetaLinux tools require your host system "/bin/sh" is bash. If you are using Ubuntu
distribution and your "/bin/sh" is dash, you can consult your system administrator to change your
default with sudo dpkg-reconfigure dash command.
IMPORTANT: PetaLinux v2016.4 works with Vivado 2016.4.
Installation Steps
Prerequisites
The prerequisites to install the PetaLinux tools are:
• PetaLinux Tools Installation Requirements is completed. Refer to the Installation
Requirements section.
• PetaLinux release package is downloaded. You can download PetaLinux installer from
PetaLinux Downloads.
gcc-multil
ib
------gcc-multilib
build-ess
ential
------build-essentia
l
libsdl1.2-
dev
------libsdl1.2-dev
libglib2.0
-dev
------libglib2.0-dev
SDL-devel SDL-devel SDL-devel SDL-devel SDL-devel SDL-devel SDL-devel -
glibc-dev
el
glibc-devel glibc-devel glibc-devel glibc-devel glibc-devel glibc-devel -
glib2-dev
el
glib2-devel glib2-devel glib2-devel glib2-devel glib2-devel glib2-devel -
automake automake automake automake automake automake automake -
Table 1-3: Packages and Linux Workstation Environments
Tool /
Library CentOS7.1 RHEL6.6 RHEL6.7 RHEL7.1 RHEL7.2 SUSE 12.0 Ubuntu 16.04
Reference Guide 11
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Run PetaLinux Tools Installer
PetaLinux Tools installation is very straight-forward. Without any options, PetaLinux Tools
will be installed into the current working directory. Alternatively, an installation path may be
specified.
For example: To install PetaLinux Tools under "/opt/pkg/petalinux":
$ mkdir -p /opt/pkg/petalinux
$ ./petalinux-v2016.4-final-installer.run /opt/pkg/petalinux
This will install the PetaLinux Tools into "/opt/pkg/petalinux" directory.
IMPORTANT: Once installed you cannot move or copy the installed directory. In the above example you
cannot move or copy /opt/pkg/petalinux.
Reading and agreeing to the PetaLinux End User License Agreement (EULA) is a required
and integral part of the PetaLinux Tools installation process. Users can read the license
agreement prior to running the installation. If you wish to keep the license for your records,
the licenses are available in plain ASCII text in the following files:
•$PETALINUX/etc/license/petalinux-license.txt. EULA specifies in detail
the rights and restrictions that apply to the PetaLinux.
•$PETALINUX/etc/license/Third_Party_Software_End_User_License_Agree
ment.txt. The third party license agreement specifies in details the licenses of the
distributable and non-distributable components in PetaLinux tools.
Note: PetaLinux tools do not require a license to install or run.
By default, the webtalk option is enabled to send tools usage statistics back to Xilinx. You
can turn off the webtalk feature by running the petalinux-util --webtalk command:
IMPORTANT: Before running the PetaLinux command, you will need to source PetaLinux settings first.
Refer to section PetaLinux Working Environment Setup.
$ petalinux-util --webtalk off
Reference Guide 12
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
This section describes some common issues you may experience while installing the
PetaLinux Tools. If the PetaLinux Tools installation fails, the file
"$PETALINUX/post-install.log" will be generated in your PetaLinux installation
directory.
Table 1-4: PetaLinux Installation Troubleshooting
Problem / Error Message Description and Solution
WARNING: You have less than
1 Gbyte free space on the
installation drive
Problem Description:
This warning message indicates that installation drive is almost full. You
may not have enough free space to develop your hardware project
and/or software project after the installation.
Solution:
• Clean up the installation drive to clear some more free space.
Alternatively,
• Move PetaLinux installation to another hard disk drive.
WARNING: No tftp server
found
Problem Description:
This warning message indicates that you do not have a TFTP service
running on your workstation. Without a TFTP service, you cannot
download Linux system images to your target system using u-boot’s
network/TFTP capabilities. This warning can be ignored for other boot
modes.
Solution:
Enable the TFTP service on your workstation. If you are unsure how to
enable this service, contact your system administrator.
ERROR: GCC is not installed -
unable to continue. Please
install and retry
Problem Description:
This error message indicates that you do not have gcc installed on your
workstation.
Solution:
Install gcc using your Linux work-station’s package management
system. If you are unsure how to do this, contact your system
administrator.
Reference Guide 13
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
PetaLinux Working Environment Setup
After the installation, the remaining setup is completed automatically by sourcing the
provided "settings" scripts.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• PetaLinux Tools Installation is completed. Refer to section Installation Steps.
• "/bin/sh" is bash.
ERROR: You are missing the
following system tools
required by PetaLinux:
missing-tools-list
or
ERROR: You are missing these
development libraries
required by PetaLinux:
missing-library-list
Problem Description:
This error message indicates that you do not have the required tools or
libraries listed in the "missing-tools-list" or "missing-library-list".
Solution:
Install the packages of the missing tools. Refer to section Installation
Requirements for details.
Failed to open PetaLinux lib. Problem Description:
This error message indicates that a PetaLinux library failed to load. The
possible reasons are:
• The PetaLinux "settings.sh" has not been loaded.
• The Linux Kernel you are running has SELinux configured. This can
cause issues with regards to security context and loading libraries.
Solution:
1. Source the "settings.sh" script from the top-level PetaLinux
directory. Refer to section PetaLinux Working Environment Setup for
more details.
2. If you have SELinux enabled, determine if SELinux is in ’enforcing
mode’.
If SELinux is configured in ’enforcing mode’, eithe reconfigure SELinux
to ’permissive mode’ (refer to SELinux manual), or change the security
context of the libraries to allow access (see below for details).
$ cd $PETALINUX/tools/common/petalinux/lib
$ chcon -R -t textrel_shlib_t lib
Table 1-4: PetaLinux Installation Troubleshooting (Cont’d)
Problem / Error Message Description and Solution
Reference Guide 14
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps to Setup PetaLinux Working Environment
1. Source the appropriate settings script:
• For Bash as user login shell:
$ source <path-to-installed-PetaLinux>/settings.sh
• For C shell as user login shell:
$ source <path-to-installed-PetaLinux>/settings.csh
Below is an example of the output when sourcing the setup script for the first time:
PetaLinux environment set to 'opt/pkg/petalinux'
INFO: Checking free disk space
INFO: Checking installed tools
INFO: Checking installed development libraries
INFO: Checking network and other services
WARNING: No tftp server found - please refer to "PetaLinux SDK Installation Guide"
for its impact and solution
2. Verify that the working environment has been set:
$ echo $PETALINUX
/opt/pkg/petalinux
Environment variable "$PETALINUX" should point to the installed PetaLinux path. Your
output may be different from this example, based on the PetaLinux installation path.
Troubleshooting
This section describes some common issues you may experience while setting up PetaLinux
Working Environment.
Table 1-5: PetaLinux Working Environment Troubleshooting
Problem / Error Message Description and Solution
WARNING: /bin/sh is not bash Problem Description:
This warning message indicates that your default shell is linked to
dash.
Solution:
See Ubuntu Forum and follow the steps.
Reference Guide 15
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
PetaLinux BSP Installation
PetaLinux reference board support packages (BSPs) are reference designs for you to start
working with and customize for your own projects. These are provided in the form of
installable BSP files, and includes all necessary design and configuration files, pre-built and
tested hardware and software images, ready for downloading on your board or for booting
in the QEMU system emulation environment.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• PetaLinux BSP is downloaded. You can download PetaLinux BSP from PetaLinux
Downloads.
• PetaLinux Working Environment Setup is completed. Refer to section PetaLinux
Working Environment Setup.
PetaLinux BSP Installation Steps
Follow the below steps to install a BSP:
1. Change to the directory under which you want PetaLinux projects to be created. For
example, if you want to create projects under /home/user:
$ cd/home/user
2. Run petalinux-create command on the command console:
petalinux-create -t project -s <path-to-bsp>
The board being referenced is based on the BSP installed. You will see the output, similar
to the below output:
INFO: Create project:
INFO: Projects:
INFO: * xilinx-zcu102-v2016.4-final.bsp
INFO: has been successfully installed to /home/user/
INFO: New project successfully created in /home/user/
If the specified location is on NFS, it changes the TMPDIR to
/tmp/<projname_timestamp>. If /tmp/<projname_timestamp> is also on NFS, it
will throw an error.
In the above example, upon execution of petalinux-create command, the projects extracted
from BSP and being installed are listed on the display console. If you run ls from
"/home/user", you will see the installed projects.
Reference Guide 16
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
This section describes some common issues you may experience while installing PetaLinux
BSP.
BSP Naming
Unlike earlier, there are multiple revisions of silicon and board that are being shipped.
Table 1-7 lists the supported BSPs that can be downloaded, for Zynq UltraScale family.
Click here to download the BSPs.
Create Hardware Platform with Vivado
This section describes how to configure a hardware platform ready for PetaLinux Project.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• Vivado® Design Suite is installed. You can download Vivado Design Suite from Vivado
Design Tool Downloads.
• You have setup Vivado Tools Working Environment. If you have not, source the
appropriate settings scripts as follows.
$ source <path-to-installed-Xilinx-Vivado>/settings64.sh
• You know how to use Xilinx Vivado and SDK tools.
Table 1-6: PetaLinux BSP Installation Troubleshooting
Problem / Error Message Description and Solution
petalinux-create: command
not found
Problem Description:
This message indicates that it is unable to find "petalinux-create"
command, hence it can’t proceed with BSP installation.
Solution:
You have to setup your environment for PetaLinux Tools. Refer to section
PetaLinux Working Environment Setup to set it up.
Table 1-7: BSP Naming
Platform Silicon Version Board Version PetaLinux BSP Name
ZCU102 1.0 Silicon (DA7)
Rev-B
xilinx-zcu102-v2016.4-final.bspRev-C
Rev-D
3.0 Silicon (DA7-ES2) Rev-1.0 xilinx-zcu102-zu9-es2-rev1.0-v2016.4-final.bsp
Reference Guide 17
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Configure a Hardware Platform for Linux
You can create your own hardware platform with Vivado. Regardless of how the hardware
platform is created and configured, there are a small number of hardware IP and software
platform configuration changes required to make the hardware platform Linux ready. These
are described below:
Zynq UltraScale+ MPSoC
The following is a list of hardware requirements for a Zynq® UltraScale+™ MPSoC hardware
project to boot Linux:
1. External memory controller with at least 64 MB of memory (Required)
2. UART (Optional, but required for serial console)
IMPORTANT: If soft IP is used, ensure the interrupt signal is connected
3. Non-volatile memory (Optional) e.g., QSPI Flash, SD/MMC
4. Ethernet (Optional, essential for network access)
IMPORTANT: If soft IP with interrupt or external PHY device with interrupt is used, ensure the interrupt
signal is connected
Zynq-7000
The following is a list of hardware requirements for a Zynq-7000 hardware project to boot
Linux:
1. One Triple Timer Counter (TTC) (Required).
IMPORTANT: If multiple TTCs are enabled, the Zynq-7000 Linux kernel uses the first TTC block from the
device tree. Please make sure the TTC is not used by others.
2. External memory controller with at least 32 MB of memory (Required)
3. UART (Optional, but required for serial console)
IMPORTANT: If soft IP is used, ensure the interrupt signal is connected.
4. Non-volatile memory (Optional) e.g., QSPI Flash, SD/MMC
5. Ethernet (Optional, essential for network access)
IMPORTANT: If soft IP with interrupt or external PHY device with interrupt is used, ensure the interrupt
signal is connected.
Reference Guide 18
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
MicroBlaze (AXI)
The following is a list of requirements for a MicroBlaze™ hardware project to boot Linux:
1. IP core check list:
°External memory controller with at least 32 MB of memory (Required)
°Dual channel timer with interrupt connected (Required)
°UART with interrupt connected (Optional, but required for serial console)
°Non-volatile memory such as Linear Flash or SPI Flash (Optional)
°Ethernet with interrupt connected (Optional, but required for network access)
2. MicroBlaze CPU configuration:
°MicroBlaze with MMU support by selecting either Linux with MMU or Low-end
Linux with MMU configuration template in the MicroBlaze configuration wizard.
IMPORTANT: Do not disable any instruction set related options that are enabled by the template,
unless you understand the implications of such a change.
°The MicroBlaze initial bootloader, called FS-BOOT, has a minimum BRAM
requirement. 4K Byte is required for Parallel flash and 8K Byte for SPI flash when the
system boots from non-volatile memory
Export Hardware Platform to PetaLinux Project
This section describes how to export hardware platform to PetaLinux Project.
Prerequisites
This section assumes that a hardware platform is created with the Vivado design suite. Refer
to section Create Hardware Platform with Vivado for more information.
Exporting Hardware Platform
After you have configured your hardware project, build the hardware bitstream. The
PetaLinux project requires a hardware description file (.hdf file) with information about
the processing system. You can get the hardware description file by running "Export
Hardware" from Vivado.
PetaLinux tools can generate a device tree source file, u-boot config header files, and
enable some Xilinx IP kernel drivers based on the hardware description file. This will be
described in later sections.
Reference Guide 19
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
For Zynq UltraScale+ MPSoC platform, you need to boot with the Power Management Unit
(PMU) firmware. You will also need to build the PMU firmware with XSDK. Refer to Zynq
Ultrascale+ MPSoC Software Developer Guide (UG1137) [Ref 3], for details on how to build
the PMU firmware with XSDK.
Create a New PetaLinux Project
This section describes how to create a new PetaLinux project.
Prerequisites
This section assumes that the PetaLinux Working Environment Setup is complete. Refer to
section PetaLinux Working Environment Setup for more details.
Create New Project
The petalinux-create command is used to create a new PetaLinux project:
$ petalinux-create --type project --template <CPU_TYPE> --name
<PROJECT_NAME>
The parameters are as follows:
•--template <CPU_TYPE> - The supported CPU types are Zynq Ultrascale+ MPSoC,
Zynq and MicroBlaze.
•--name <PROJECT_NAME> - The name of the project you are building.
This command will create a new PetaLinux project folder from a default template. Later
steps customize these settings to match the hardware project created previously.
TIP: For details of PetaLinux project structure, refer to Appendix A, PetaLinux Project Structure.
CAUTION! When a PetaLinux project is created on NFS, it changes the TMPDIR to
/tmp/<projname_timestamp>. If /tmp/<projname_timestamp> is also on NFS, it will throw an error. If
you want to change the TMPDIR to a local storage use petalinux-config --> Yocto-settings --> TMPDIR.
Reference Guide 20
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Version Control
This section details about version management/control in PetaLinux project.
Prerequisites
This section assumes that the you have created a new PetaLinux project or have an existing
PetaLinux project. Refer to section Create a New PetaLinux Project for more information on
creating the PetaLinux project.
Version Control
You can have version control over your PetaLinux project directory "<plnx-proj-root>"
excluding the following:
• "<plnx-proj-root>/.petalinux"
• "<plnx-proj-root>/build/"
• "<plnx-proj-root>/images/"
Import Hardware Configuration
This Section explains how to update an existing/newly created PetaLinux project with a new
hardware configuration. This enables you to make PetaLinux Tools’ software platform ready
for building a Linux system, customized to your new hardware platform.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have exported the hardware platform and .hdf file is generated. Refer to section
Exporting Hardware Platform.
• You have created a new PetaLinux project or have an existing PetaLinux project. Refer to
section Create a New PetaLinux Project for more information on creating the PetaLinux
project.
Reference Guide 21
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps to Import Hardware Configuration
Steps to import hardware configuration are:
1. Change into the directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Import the hardware description with petalinux-config command, by giving the
path of the directory containing the.hdf file (For example:
hwproject/hwproject.sdk/hwproject_design_wrapper_hw_platform_0) as follows:
$ petalinux-config
--get-hw-description=<path-to-directory-which-contains-hardwaredescription- file>
This launches the top system configuration menu when petalinux-config
--get-hw-description runs first time for the PetaLinux project or the tool detects there
is a change in the system primary hardwares candidates:
Linux Components Selection --->
Auto Config Settings --->
-*- Subsystem AUTO Hardware Settings --->
Kernel Bootargs --->
ARM Trusted Firmware Compilation Configuration --->
u-boot Configuration --->
Image Packaging Configuration --->
Firmware Version Configuration --->
Yocto Settings --->
Make sure "Subsystem AUTO Hardware Settings --->” is selected, and go into the
menu which is similar to the following:
--- Subsystem AUTO Hardware Settings
System Processor (psu_cortexa53_0) --->
Memory Settings --->
Serial Settings --->
Ethernet Settings --->
Flash Settings --->
SD/SDIO Settings --->
RTC Settings --->
[*] Advanced bootable images storage Settings --->
"Subsystem AUTO Hardware Settings --->" menu allows customizing system wide
hardware settings.
This step may take a few minutes to complete. This is because the tool will parse the
hardware description file for hardware information required to update the device tree,
PetaLinux u-boot configuration files and the kernel config files based on the "Auto
Config Settings --->" and "Subsystem AUTO Hardware Settings --->"
settings.
For example, if ps7_ethernet_0 as the Primary Ethernet is selected and user enables
auto update for kernel config and u-boot config, the tool will automatically enable its
Reference Guide 22
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
kernel driver and also updates the u-boot configuration headers for u-boot to use the
selected ethernet controller.
Note: For more details on Auto Config Settings menu, refer to Appendix C, Auto Config
Settings.
Build System Image
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system, customized to your hardware platform. Refer to section Import Hardware
Configuration for more details.
Steps to Build PetaLinux System Image
1. Change into the directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Run petalinux-build to build the system image:
$ petalinux-build
The console shows the compilation progress. For example:
[INFO] building project
[INFO] sourcing bitbake
INFO: bitbake petalinux-user-image
Loading cache: 100%
|##################################################################################
#####################################################| ETA: 00:00:00
Loaded 2927 entries from dependency cache.
Parsing recipes: 100%
|##################################################################################
###################################################| Time: 00:00:02
Parsing of 2315 .bb files complete (2278 cached, 37 parsed). 2931 targets, 193
skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 901 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 2442 tasks of which 2006 didn't need to be rerun and
all succeeded.
Summary: There were 16 WARNING messages shown.
INFO: generating FIT Image
INFO: bitbake petalinux-user-image -c do_image_xilinx_fitimage -R
/home/user/xilinx-zcu102-v2016.4/build/conf/fit-image.conf
Parsing recipes: 100%
|##################################################################################
###################################################| Time: 00:00:13
Reference Guide 23
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Parsing of 2315 .bb files complete (0 cached, 2315 parsed). 2931 targets, 193
skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 113 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 1971 tasks of which 1956 didn't need to be rerun and
all succeeded.
Summary: There were 2 WARNING messages shown.
INFO: Copying Images from deploy to images
INFO: Creating images/linux directory
[INFO] successfully built project
The full compilation log "build.log" is stored in the build subdirectory of your PetaLinux
project. The Linux software images and the device tree are generated in the
images/linux subdirectory of your PetaLinux project.
IMPORTANT: By default, besides the kernel, rootfs and u-boot, the PetaLinux project is configured to
generate and build the first stage bootloader. Refer to Appendix B, Generating First Stage Bootloader
Within Project for more details on the auto generated first stage bootloader.
Generate uImage
When you run petalinux-build, it will generate FIT image for Zynq family devices and
MicroBlaze platforms and RAM disk image urootfs.cpio.gz will also be generated. If
you want to use uImage instead, you can use "petalinux-package --image" instead.
For example:
$ petalinux-package --image -c kernel --format uImage
The uImage will be generated to images/linux subdirectory of your PetaLinux project.
You will then need to configure your u-boot to boot with uImage. If you have selected
"PetaLinux u-boot config" as your u-boot config target, you can modify
"<plnx-proj-root>/project-spec/meta-user/recipes-bsp/u-boot/files/p
latform-top.h" of your PetaLinux project to overwrite the
CONFIG_EXTRA_ENV_SETTINGS macro to define your u-boot boot command to boot
with uImage.
Reference Guide 24
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
This section describes some common issues you may experience while building PetaLinux
system images.
Generate Boot Image for Zynq Family Devices
This section is for Zynq family devices only and describes how to generate BOOT.BIN.
Prerequisites
This section assumes that you have built PetaLinux system image. Refer to section Build
System Image for more information.
Generate Boot Image
Before executing this step, ensure you have built the hardware bitstream. The boot image
can be put into Flash or SD card. When you power on the board, it can boot from the boot
image. A boot image usually contains a first stage bootloader image, FPGA bitstream, PMU
firmware and u-boot.
Follow the step below to generate the boot image in ".bin" format.
$ petalinux-package --boot --fsbl <FSBL image> --fsbl <FSBL image> --pmufw
<PATH_TO_PMU_FW_ELF> --u-boot
For detailed usage, refer to the --help option or PetaLinux Tools Documentation: PetaLinux
Command Line Reference (UG1157) [Ref 4].
Table 1-8: Build System Image Troubleshooting
Problem / Error Message Description and Solution
[ERROR]
<path-to-installed-PetaLinux
> /etc/build/common.mk:17:
*** "No architecture is
defined!". Stop.
Problem Description:
This error message indicates that petalinux-build process cannot
be completed because PetaLinux tools cannot understand hardware
architectural definition.
Solution:
You have to choose board and device appropriately in Vivado Hardware
Project and import hardware description. Refer to section Import
Hardware Configuration.
Reference Guide 25
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Generate Boot Image for Zynq UltraScale+ MPSoC
This section is for Zynq UltraScale+ MPSoC only and describes how to generate BOOT.BIN
for Zynq UltraScale+ MPSoC. Skip this section for MicroBlaze and Zynq targets.
Prerequisites
This section assumes that you have built PetaLinux system image. For more information,
refer Build System Image.
Generate Boot Image
Before executing this step, ensure you have built the hardware bitstream. The boot image
can be put into Flash or SD card. When you power on the board, it can boot from the boot
image. A boot image usually contains a first stage bootloader image, FPGA bitstream and
u-boot.
Follow the step below to generate the boot image in ".bin" format.
$ petalinux-package --boot --fsbl <FSBL image> --fpga <FPGA bitstream> --u-boot
For detailed usage, refer to the --help option or PetaLinux Tools Documentation: PetaLinux
Command Line Reference (UG1157) [Ref 4].
Generate Boot Image for MicroBlaze
This section is for MicroBlaze only and describes how to generate MCS file for MicroBlaze.
Prerequisites
This section assumes that you have built the PetaLinux system image. For more information,
refer Build System Image.
Generate Boot Image
Execute the following command to generate MCS boot file for MicroBlaze.
$ petalinux-package --boot --fpga <FPGA bitstream> --u-boot --kernel
It will generate boot.mcs in your working directory and it will be copied to the
<plnx-proj-root>/<proj>/images/linux/ directory. With the above command, the
MCS file contains fpga bit, fs-boot, u-boot and kernel image image.ub.
Reference Guide 26
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Command to generate .mcs file with fs-boot and fpga only:
$ petalinux-package --boot --fpga <FPGA bitstream>
Command to generate .mcs file with fpga, fs-boot and u-boot:
$ petalinux-package --boot --fpga <FPGA bitstream> --u-boot
For detailed usage, refer to the --help option or document PetaLinux Tools
Documentation: PetaLinux Command Line Reference (UG1157) [Ref 4].
Package Prebuilt Image
This section describes how to package newly built images into prebuilt directory.
Note: This step helps in making use of prebuilt capability to boot with JTAG/QEMU. This step is not
mandatory to boot with JTAG/QEMU.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• For Zynq family devices, you have generated boot image. For more information, refer
to Generate Boot Image for Zynq Family Devices.
• For MicroBlaze, you have generated system image, refer to Build System Image.
Steps to Package Prebuilt Image
1. Change into the root directory of your project.
$ cd <plnx-proj-root>
2. Use petalinux-package --prebuilt to package the prebuilt images:
$ petalinux-package --prebuilt --fpga <FPGA bitstream>
For detailed usage, refer to the --help option or document PetaLinux Tools Documentation:
PetaLinux Command Line Reference (UG1157) [Ref 4].
Reference Guide 27
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Using petalinux-boot Command with Prebuilt
Images
Booting a PetaLinux Image is achieved with the petalinux-boot command, along with
--qemu option to boot the image under software emulation (QEMU) and --jtag on a
hardware board. This section describes different boot levels for prebuilt option.
Prerequisites
This section assumes that you have packaged prebuilt images. Refer to Package Prebuilt
Image.
Boot Levels for Prebuilt Option
--prebuilt <BOOT_LEVEL> boots prebuilt images (override all settings). Supported
boot level is 1 to 3.
• Level 1: Download the prebuilt FPGA bitstream
°It will also boot FSBL for Zynq-7000 and 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 FSBL, PMU firmware and then Arm
Trusted Firmware (ATF) before booting u-boot.
•Level 3:
°For MicroBlaze: Download the prebuilt FPGA bitstream and boot the prebuilt kernel
image on target.
°For Zynq-7000: Download the prebuilt FPGA bitstream and FSBL and boot the
prebuilt u-boot and boot the prebuilt kernel on target.
°For Zynq UltraScale+ MPSoC: Download the prebuilt FPGA bitstream, the prebuilt
FSBL, the prebuilt PMUFW, the prebuilt ATF and the prebuilt kernel on target.
Example to show the usage of boot level for prebuilt option:
$ petalinux-boot --jtag --prebuilt 3
Reference Guide 28
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Boot a PetaLinux Image on QEMU
This section describes how to boot a PetaLinux image under software emulation (QEMU)
environment.
Note: For the details on Xilinx IP models supported by QEMU, refer to Appendix E Xilinx IP models
supported by QEMU.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have a PetaLinux system image by either installing a PetaLinux BSP (refer to section
PetaLinux BSP Installation) or by building your own PetaLinux project (refer to Build
System Image).
• If you are going to use --prebuilt option for QEMU boot, you will also need to have
prebuilt images packaged, refer to Package Prebuilt Image.
IMPORTANT: Unless otherwise indicated, the PetaLinux tool command must be run within a project
directory ("<plnx-proj-root>").
Steps to Boot a PetaLinux Image on QEMU
PetaLinux provides QEMU support to enable testing of PetaLinux software image in a
simulated environment without any hardware.
To test the PetaLinux reference design with QEMU, follow these steps:
1. Change to your project directory and boot the prebuilt linux kernel image:
$ petalinux-boot --qemu --prebuilt 3
Note: If you do not wish to use prebuilt capability for QEMU boot, refer to Additional Options for
Booting on QEMU.
°The --qemu option tells petalinux-boot to boot QEMU, instead of real hardware
via JTAG, and the --prebuilt 3 boots the linux kernel.
TIP: To know more about different boot levels for prebuilt option, refer to Using petalinux-boot
Command with Prebuilt Images.
The example of the kernel boot log messages displayed on the serial console during
successful petalinux-kernel, is shown below:
[ 13.425611] Freeing unused kernel memory: 13508K (ffffff8008b3f000 -
ffffff8009870000)
[ 35.313611] random: dd urandom read with 2 bits of entropy available
Reference Guide 29
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
[ 38.295984] IPv6: ADDRCONF(NETDEV_UP): eth0: link is not ready
[ 40.197703] macb ff0e0000.ethernet eth0: unable to generate target frequency:
25000000 Hz
[ 40.198986] macb ff0e0000.ethernet eth0: link up (100/Full)
[ 40.200116] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
PetaLinux 2016.4 plnx_aarch64 /dev/ttyPS0
plnx_aarch64 login: root
(ctrl+A then X)
root@plnx_aarch64:~# QEMU: Terminated
2. Login to PetaLinux with the default user name root and password root.
TIP: To exit QEMU, press Ctrl+A together, release and then press X.
Additional Options for Booting on QEMU
• To download newly built <plnx-proj-root>/images/linux/u-boot.elf with QEMU:
$ petalinux-boot --qemu --u-boot
°For MicroBlaze and Zynq-7000, it will boot
<plnx-proj-root>/images/linux/u-boot.elf with QEMU.
°For Zynq UltraScale+ MPSoC, it loads the
<plnx-proj-root>/images/linux/u-boot.elf and boots the ATF image
<plnx-proj-root>/images/linux/bl31.elf with QEMU, and the ATF will
then boot the loaded u-boot image.
• To download newly built kernel with qemu:
$ petalinux-boot --qemu --kernel
° For MicroBlaze, it will boot <plnx-proj-root>/images/linux/image.elf
with QEMU.
° For Zynq-7000, it will boot <plnx-proj-root>/images/linux/zImage with
QEMU.
° For Zynq UltraScale+ MPSoC, it loads the kernel image
<plnx-proj-root>/images/linux/Image and boots the ATF image
<plnx-proj-root>/images/linux/bl31.elf with QEMU, and the ATF will
then boot the loaded kernel image.
• Direct Boot a Linux Image with Specific DTB:
Device Trees (DTB files) are used to describe the hardware architecture and address map to
the Linux kernel. The PetaLinux system emulator also uses DTB files to dynamically
configure the emulation environment to match your hardware platform.
If no DTB file option is provided, petalinux-boot extracts the DTB file from the given
image.elf for Microblaze and from
Reference Guide 30
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
"<plnx-proj-root>/images/linux/system.dtb" for Zynq-7000 and Zynq
UltraScale+ MPSoC. Alternatively, you can use the --dtb option as follows:
$ petalinux-boot --qemu --image ./images/linux/zImage --dtb
./images/linux/system.dtb
Note: QEMU version has been upgraded to 2.6. The old options are deprecated in new version, they
functionally operational. PetaLinux tools still use old options, therefore it gets warning messages,
which can be ignored.
Warning message for Zynq UltraScale+ MPSoC:
qemu-system-aarch64: -tftp /ssd/yocto/4-1210/xilinx-zc702-2016.4/images/linux: The
-tftp option is deprecated. Please use '-netdev user,tftp=...' instead.g
Boot a PetaLinux Image on Hardware with SD Card
This section describes how to boot a PetaLinux image on Hardware with SD Card.
Note: This section is for Zynq-7000 and Zynq UltraScale+ MPSoC only, since they allow you to boot
from SD card.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have installed PetaLinux Tools on the Linux workstation. If you have not installed,
refer to section Installation Steps.
• You have installed PetaLinux BSP on the Linux workstation. If you have not installed,
refer to section PetaLinux BSP Installation.
• A serial communication program such as minicom/kermit/gtkterm has been installed;
the baud rate of the serial communication program has been set to 115200 bps.
Steps to Boot a PetaLinux Image on Hardware with SD Card
1. Mount the SD card on your host machine.
2. Copy the following files from <plnx-proj-root>/pre-built/linux/images/
into the root directory of the first partition which is in FAT32 format in the SD card:
°BOOT.BIN
°image.ub
3. Connect the serial port on the board to your workstation.
Reference Guide 31
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
4. Open a console on the workstation and start the preferred serial communication
program (For example: kermit, minicom, gtkterm) with the baud rate set to 115200 on
that console.
5. Power off the board.
6. Set the boot mode of the board to SD boot. Refer to the board documentation for
details.
7. Plug the SD card into the board.
8. Power on the board.
9. Watch the serial console, you will see the boot messages similar to the following:
Freeing unused kernel memory: 460K (ffffff8008b3d000 - ffffff8008bb0000)
INIT: version 2.88 booting
[ 4.912645] FAT-fs (mmcblk0p1): Volume was not properly unmounted. Some data may be
corrupt. Please run fsck.
[ 5.235523] random: dd urandom read with 8 bits of entropy available
Wed Nov 2 21:27:25 UTC 2016
INIT: Entering runlevel: 5
Configuring network interfaces... ifconfig: SIOCGIFFLAGS: No such device
Starting system message bus: dbus.
Starting Dropbear SSH server: Generating key, this may take a while...
Public key portion is:
ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABAQCkDXPr7c3jsZwUtYEwu6RV/GPvESt+cBNGpGXmoG22FAixS686RcJbWO
24NQ1qPntPsCar0uqilLEwjSdYdr3wDkHonrWFJCF65XT2YbhAU78ZxjldEGC//KkYjkEIW0e/mtesAjDaoPZa
XuvvK7ikSY813Ibq8lAfyK4J3OsW2UBd/5lOOX7TS0SEArQlW5rJaoIYx+0ZpZHI1U146Y9TODhyD5GlRnAGyx
WOzZikaFEeb6dTgCqZQEV4wS4d49yCYN6AKFNY3+ASZJTF+GfdQehUh2bht+dT3x459oMOPVumf+ysXz4QGRjG
bqtkW4Kj9UL/Em2FN5jcog+srWeV root@plnx_aarch64
Fingerprint: md5 85:62:c1:64:1e:f0:b4:dd:71:b0:fb:6f:9e:b1:6f:5e
dropbear.
Starting rpcbind daemon...done.
Starting syslogd/klogd: done
* Starting Avahi mDNS/DNS-SD Daemon: avahi-daemon
...done.
PetaLinux 2016.4 plnx_aarch64 /dev/ttyPS0
plnx_aarch64 login: root
root@plnx_aarch64:~#
TIP: If you wish to stop auto-boot, hit any key when you see the messages similar to the following on
the console: Hit any key to stop autoboot:
10. Type user name root and password root on the serial console to log into the PetaLinux
system.
Reference Guide 32
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
This section describes some common issues you may experience while booting a PetaLinux
image on hardware with SD card.
TIP: To know more about u-boot options, use the command:$ U-Boot-PetaLinux> printenv
Boot a PetaLinux Image on Hardware with JTAG
This section describes how to boot a PetaLinux image on hardware with JTAG.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have a PetaLinux system image by either installing a PetaLinux BSP (refer to section
PetaLinux BSP Installation) or by building your own PetaLinux project (refer to section
Build System Image).
• This is optional and only needed if you wish to make use of prebuilt capability for JTAG
boot. You have packaged prebuilt images, refer to section Package Prebuilt Image.
Table 1-9: PetaLinux Image on Hardware Troubleshooting
Problem / Error Message Description and Solution
Wrong Image Format for boot
command.
ERROR: Can’t get kernel
image!
Problem Description:
This error message indicates that the u-boot bootloader is unable to
find kernel image. This is likely because bootcmd environment variable
is not set properly.
Solution:
To see the default boot device, print bootcmd environment variable
using the following command in u-boot console.
U-Boot-PetaLinux> print bootcmd
If it is not boot from SD card by default, there are a few options as
follows,
• Without rebuild PetaLinux, set bootcmd to boot from your desired
media, use setenv command. For SD card boot, set the environment
variable as follows.
U-Boot-PetaLinux> setenv bootcmd ’run sdboot’ ;
saveenv
•Run petalinux-config to set to load kernel image from SD card.
Refer to section Boot Images Storage Configuration. Rebuild
PetaLinux and regenerate BOOT.BIN with the rebuilt u-boot, and
then use the new BOOT.BIN to boot the board. Refer to section
Generate Boot Image for Zynq Family Devices on how to generate
BOOT.BIN.
Reference Guide 33
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
• A serial communication program such as minicom/kermit/gtkterm has been installed;
the baud rate of the serial communication program has been set to 115200bps.
• Appropriate JTAG cable drivers have been installed. You can download drivers from
Digilent Adept Downloads.
Steps to Boot a PetaLinux Image on Hardware with JTAG
1. Power off the board.
2. Connect the JTAG port on the board with the JTAG cable to your workstation.
3. Connect the serial port on the board to your workstation.
4. If your system has ethernet, also connect the Ethernet port on the board to your local
network.
5. For Zynq family device boards, ensure that the mode switches are set to JTAG mode.
Refer to the board documentation for details.
6. Power on the board.
7. Open a console on your workstation and start with preferred serial communication
program (For example, kermit, minicom) with the baud rate set to 115200 on that
console.
8. Run the petalinux-boot command as follows on your workstation:
$ petalinux-boot --jtag --prebuilt 3
Note: If you wish not to use prebuilt capability for JTAG boot, refer to Additional options for booting
with JTAG.
The --jtag option tells petalinux-boot to boot on hardware via JTAG, and the
--prebuilt 3 option boots the linux kernel. Wait for the appearance of the shell prompt
on the command console to indicate completion of the command.
Note: To know more about different boot levels for prebuilt option, refer to Using petalinux-boot
Command with Prebuilt Images.
The example of the message on the workstation command console for successful
petalinux-boot is:
$ petalinux-boot --jtag --prebuilt 3
INFO: Launching XSDB for file download and boot.
INFO: This may take a few minutes, depending on the size of your image.
INFO: Configuring the FPGA...
INFO: Downloading bitstream to the target.
INFO: Downloading ELF file to the target.
INFO: Downloading ELF file to the target.
INFO: Downloading ELF file to the target.
INFO: Downloading ELF file to the target.
Reference Guide 34
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
The example of the message on the serial console for successful petalinux-boot is:
[ 6.463766] Freeing unused kernel memory: 13508K (ffffff8008b3d000 - ffffff80
0986e000)
[ 6.691711] mmc0: new high speed SDHC card at address 0007
[ 6.702259] mmcblk0: mmc0:0007 SD04G 3.68 GiB
[ 6.707767] mmcblk0: p1
[ 7.672348] random: dd urandom read with 8 bits of entropy available
[ 7.758876] IPv6: ADDRCONF(NETDEV_UP): eth0: link is not ready
[ 9.738520] macb ff0e0000.ethernet eth0: link up (1000/Full)
[ 9.744128] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
PetaLinux 2016.4 plnx_aarch64 /dev/ttyPS0
plnx_aarch64 login:
By default, network settings for PetaLinux reference designs are configured using DHCP. The
output you see may be slightly different from the above example, depending on the
PetaLinux reference design being tested.
9. Type user name root and password root on the serial console to log into the
PetaLinux system.
10. Determine the IP address of the PetaLinux by running ifconfig on the system console.
Additional options for booting with JTAG
• To download a bitstream to target board:
$ petalinux-boot --jtag --fpga --bitstream <BITSTREAM>
• To download newly built <plnx-proj-root>/images/linux/u-boot.elf to
target board:
$ petalinux-boot --jtag --u-boot
• To download newly built kernel to target board:
$ petalinux-boot --jtag --kernel
°For MicroBlaze, this will boot <plnx-proj-root>/images/linux/image.elf
on target board.
°For Zynq-7000, this will boot <plnx-proj-root>/images/linux/zImage on
target board.
°For Zynq UltraScale+ MPSoC, this will boot
<plnx-proj-root>/images/linux/Image on target board.
• To Download a image with a bitstream with --fpga --bitstream <BITSTREAM> option:
$ petalinux-boot --jtag --u-boot --fpga --bitstream <BITSTREAM>
The above command will download the bitstream and then download the U-Boot image.
Reference Guide 35
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
• To see the verbose output of jtag boot with -v option:
$ petalinux-boot --jtag --u-boot -v
• To download PMU firmware to target board with U-Boot:
$ petalinux-boot --jtag --pmufw <PATH_TO_PMUFW_ELF> --u-boot
Logging Tcl/XSDB for JTAG Boot
Use the following command to take log of XSDB commands used during JTAG boot. It
dumps tcl script (which in turn invokes the xsdb commands) data to test.txt.
$ cd <plnx-proj-root>
$ petalinux-boot --jtag --prebuilt 3 --tcl test.txt
Troubleshooting
This section describes some common issues you may experience while booting a PetaLinux
image on hardware with JTAG.
Table 1-10: PetaLinux Image on Hardware with JTAG Troubleshooting
Problem / Error Message Description and Solution
ERROR: This tool requires
’xsdb’ and it is missing. Please
source Xilinx Tools settings
first.
Problem Description:
This error message indicates that PetaLinux tools can not find the xsdb
tool that is a part of the Xilinx Vivado or SDK tools.
Solution:
You have to setup Vivado Tools Working Environment. Refer to
PetaLinux Working Environment Setup.
Cannot see any console
output when trying to boot
U-Boot or kernel on hardware
but boots correctly on QEMU.
Problem Description:
This problem is usually caused by one or more of the following:
• The serial communication terminal application is set with the wrong
baud rate.
• Mismatch between hardware and software platforms.
Solution:
• Ensure your terminal application baud rate is correct and matches
your hardware configuration.
• Ensure the PetaLinux project is built with the right hardware platform.
°Import hardware configuration properly, refer to section Import
Hardware Configuration.
°Check the "Subsystem AUTO Hardware Settings --->" submenu to
make sure it matches the hardware platform.
°Check the "Serial settings --->" submenu under "Subsystem AUTO
Hardware Settings --->" to ensure stdout, stdin are set to the
correct UART IP core.
°Rebuild system images, refer to Build System Image.
Reference Guide 36
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Boot a PetaLinux Image on Hardware with TFTP
This section describes how to boot a PetaLinux image using Trivial File Transfer Protocol
(TFTP).
TIP: TFTP boot saves a lot of time because it is much faster than booting through JTAG and you do not
have to flash the image for every change in kernel source.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• Host environment with TFTP server is setup and PetaLinux Image is built for TFTP boot.
Refer to section Configure TFTP Boot.
• You have packaged prebuilt images, refer to section Package Prebuilt Image.
• A serial communication program such as minicom/kermit/gtkterm has been installed;
the baud rate of the serial communication program has been set to 115200 bps.
• Ethernet connection is setup properly between Host and Linux Target.
• Appropriate JTAG cable drivers have been installed. You can download drivers from
Digilent Adept Downloads.
Steps to Boot a PetaLinux Image on Hardware with TFTP
1. Power off the board.
2. Connect the JTAG port on the board to the workstation using a JTAG cable with the JTAG
cable.
3. Connect the serial port on the board to your workstation.
4. Connect the Ethernet port on the board to the local network via a network switch.
5. For Zynq family device boards, ensure that the mode switches are set to JTAG mode.
Refer to the board documentation for details.
6. Power on the board.
7. Open a console on your workstation and start with preferred serial communication
program (For example, kermit, minicom) with the baud rate set to 115200 on that
console.
8. Run the petalinux-boot command as follows on your workstation.
$ petalinux-boot --jtag --prebuilt 2
Reference Guide 37
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
The --jtag option tells petalinux-boot to boot on hardware via JTAG, and the
--prebuilt 2 option will download the prebuilt bitstream (and FSBL for Zynq) to target
board, and then boot prebuilt u-boot on target board.
9. When autoboot starts, hit any key to stop it.
The example of a Workstation console output for successful u-boot download is:
U-Boot 2016.07 (Nov 02 2016 - 15:24:58 -0600) Xilinx ZynqMP ZCU102
I2C: ready
DRAM: 4 GiB
EL Level: EL2
Chip ID: xczuunknown
MMC: sdhci@ff170000: 0
SF: Detected N25Q512A with page size 512 Bytes, erase size 128 KiB, total 128 MiB
*** Warning - bad CRC, using default environment
In: serial
Out: serial
Err: serial
Bootmode: JTAG_MODE
Net: ZYNQ GEM: ff0e0000, phyaddr 12, interface rgmii-id
eth0: ethernet@ff0e0000
U-BOOT for
ethernet@ff0e0000 Waiting for PHY auto negotiation to complete....... done
BOOTP broadcast 1
BOOTP broadcast 2
BOOTP broadcast 3
DHCP client bound to address 10.10.70.2 (1256 ms)
Hit any key to stop autoboot: 0
Device: sdhci@ff170000
Manufacturer ID: 27
OEM: 5048
Name: SD04G
Tran Speed: 50000000
Rd Block Len: 512
SD version 3.0
High Capacity: Yes
Capacity: 3.7 GiB
Bus Width: 4-bit
Erase Group Size: 512 Bytes
reading image.ub
ZynqMP>
10. Check whether the TFTP server IP address is set to the IP Address of the host where the
image resides. This can be done using the following command.
U-Boot-PetaLinux> print serverip
11. Set the server IP address to the host IP address using the following commands.
U-Boot-PetaLinux> set serverip <HOST IP ADDRESS>; saveenv
12. Boot the kernel using the following command.
U-Boot-PetaLinux> run netboot
Reference Guide 38
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
BSP Packaging
BSPs are useful for distribution in general and allude to Xilinx Worldwide Technical Support
as a specific use case. Xilinx WTS requires a bare minimum design packaged as a
Petalinux BSP to get a testcase for further debugging and support. This section
explains, with an example, how to package a BSP with PetaLinux project.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps for BSP Packaging
Steps on how to package a project for submission to WTS for debug are as follows:
1. You can go outside the PetaLinux project directory to run petalinux-package
command.
2. Use the following commands to package the bsp.
$ petalinux-package --bsp -p <plnx-proj-root> --output MY.BSP
3. This will generate MY.BSP including the following elements from the specified project:
°<plnx-proj-root>/project-spec/
°<plnx-proj-root>/config.project
°<plnx-proj-root>/.petalinux/
°<plnx-proj-root>/pre-built/
°all selected components
Table 1-11: PetaLinux Image on Hardware with TFTP
Problem / Error Message Description and Solution
Error: "serverip" not defined. Problem Description:
This error message indicates that u-boot environment variable
serverip is not set. You have to set it to IP Address of the host where
the image resides.
Solution:
Use the following command to set the serverip:
U-Boot-PetaLinux> set serverip <HOST IP
ADDRESS>;saveenv
Reference Guide 39
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Additional BSP Packaging Options
1. BSP packaging with hardware source.
$ petalinux-package --bsp -p <plnx-proj-root> \
--hwsource <hw-project-root> --output MY.BSP
It will not modify the specified PetaLinux project <plnx-proj-root>. It will put the
specified hardware project source to <plnx-proj-root>/hardware/ inside MY.BSP
archive.
2. BSP packaging with external sources.
The support for search path is obsolete. It is your responsibility to copy the external
sources under components/ext_sources. Refer to Using External Kernel and U-boot With
PetaLinux for more details. The BSP has to be packaged.
Firmware Version Configuration
This section explains how to do firmware version configuration using petalinux-config
command.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. For more information, refer to Import
Hardware Configuration.
Steps for Firmware Version Configuration
1. Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select Firmware Version Configuration.
4. Select Host Name, Product Name, Firmware Version as per the requirement to edit
them.
5. Exit the menu and select <Yes> when asked Do you wish to save your new
configuration?:
Do you wish to save your new configuration ? <ESC><ESC>
to continue.
< Yes > < No >
Reference Guide 40
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Root file system Type Configuration
This section details configuration of RootFS type using petalinux-config command.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps for Root file system Type Configuration
1. Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select Image Packaging Configuration.
4. Select Root file System type.
5. Select INITRAMFS/INITRD/JFFS2/NFS/SD card as per the requirement.
6. Save Configuration settings.
Boot Images Storage Configuration
This section provides details about configuration of the Boot Device e.g. Flash, SD/MMC
using petalinux-config command.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Reference Guide 41
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps for Boot Images Storage Configuration
1. Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select Subsystem AUTO Hardware Settings.
4. Select Advanced Bootable Images Storage Settings.
5. Select boot image settings.
6. Select Image Storage Media.
7. Select boot device as per the requirement. To set flash as the boot device select
primary flash. To make SD card as the boot device select primary sd.
8. Under the Advanced Bootable Images Storage Settings submenu, select
kernel image settings.
9. Select Image Storage Media.
10. Select storage device as per the requirement. To set flash as the boot device select
primary flash. To make SD card as the boot device select primary sd.
11. Save Configuration settings.
TIP: To select a menu/submenu which was deselected before, press the down arrow key (ë) to scroll
down the menu or the up arrow key (") to scroll up the menu.Once the cursor is on the menu, then press
"y". To deselect a menu/submenu, follow the same process and press "n" at the end.
Troubleshooting
This section describes some common issues you may experience while working with boot
device configuration.
Table 1-12: Boot Images Storage Troubleshooting
Problem / Error Message Description and Solution
ERROR: Failed to config
linux/kernel!
Problem Description:
This error message indicates that it is unable to configure the
linux-kernel component with menuconfig.
Solution:
Check whether all required libraries/packages are installed properly.
Refer to section Installation Requirements.
Reference Guide 42
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Primary Flash Partition Configuration
This sections provides details on how to configure flash partition with PetaLinux
menuconfig.
1. Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select Subsystem AUTO Hardware Settings.
4. Select Flash Settings.
5. Select a flash device as the Primary Flash.
6. Set the name and the size of each partition.
Note: The PetaLinux tools uses the boot, bootenv (it is for u-boot environment variables) and kernel
partitions to generate the u-boot commands:
The PetaLinux tools uses the start address for parallel flash or start offset for SPI flash and
the size of the above partitions to generate the following u-boot commands:
•update_boot if the boot image, which is a u-boot image for MicroBlaze, a BOOT.BIN
image for Zynq family devices, is selected to be stored in the primary flash.
•update_kernel, and load_kernel if the kernel image which is the FIT image
image.ub, is selected to be stored in the flash.
Base Root File System Configuration
This section talks about Base Root File System Configuration.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Reference Guide 43
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps for Base Root File System Configuration
1. Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select linux Components Selection
4. Select petalinux-rootfs as rootfs.
Managing Image Size
In an embedded environment, it is very important to reduce the size of the kernel image
stored in flash and the static size of kernel image in RAM. This section describes impact of
config item on kernel size and RAM usage.
FIT image is the default bootable image format. By default the FIT image is composed of
kernel image, DTB and rootfs image.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps for Managing Image Size
FIT Image size can be reduced using the following methods:
1. Launch the RootFS configuration menu using the following command:
$ cd <plnx-proj-root>
$ petalinux-config -c rootfs
Select Filesystem Packages. Under this submenu, you can find the list of options
corresponding to RootFS packages. If your requirement does not need some of these
packages, you can shrink the size of RootFS image by disabling them.
2. Launch the kernel configuration menu using the following command:
$ cd <plnx-proj-root>
$ petalinux-config -c kernel
Reference Guide 44
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Select General Setup. Under this submenu, you can find options to set the config items.
Any item that is not mandatory to have in the system can be disabled to reduce the kernel
image size. For example, CONFIG_SHMEM, CONFIG_AIO, CONFIG_SWAP,
CONFIG_SYSVIPC. For more details, refer Linux kernel documentation.
CAUTION! Note that disabling of some config items may lead to unsuccessful boot. So it is expected
that the user has knowledge of config items before disabling them.
TIP: Inclusion of extra config items and Filesystem packages lead to increase in the kernel image size
and RootFS size respectively.
Note: If kernel size is more, you need to enable BOOTLEN flag in platform-top.h of u-boot.
Configuring INITRAMFS Boot
INITRAMFS, abbreviated as initial RAM File System, is the successor of initrd. It is a cpio
archive of the initial file system that gets loaded into memory during the PetaLinux startup
process. The Linux kernel mounts it as RootFS and starts the initialization process.
This section describes how to configure INITRAMFS boot.
Prerequisites
This section assumes that you have created a new PetaLinux project (refer to section Create
a New PetaLinux Project) and imported the hardware platform (refer to section Import
Hardware Configuration).
Steps to Configure INITRAMFS Boot
1. Set the RootFS type to INITRAMFS. Refer to Root file system Type Configuration.
2. Build the system image. Refer to Build System Image.
3. Use one of the following methods to boot the system image.
a. Boot a PetaLinux Image on QEMU, refer to section Boot a PetaLinux Image on QEMU.
b. Boot a PetaLinux Image on Hardware with SD Card, refer to section Boot a PetaLinux
Image on Hardware with SD Card.
c. Boot a PetaLinux Image on Hardware with JTAG, refer to section Boot a PetaLinux
Image on Hardware with JTAG.
IMPORTANT: The default RootFS for PetaLinux is INITRAMFS.
Reference Guide 45
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Configure TFTP Boot
This section describes how to configure the Host and the PetaLinux image for Trivial File
Transfer Protocol (TFTP) boot.
TIP: TFTP boot saves a lot of time because it is much faster than booting through JTAG and you do not
have to flash the image for every change in kernel source.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have created a new PetaLinux project (refer to section Create a New PetaLinux
Project) and imported the hardware platform (refer to section Import Hardware
Configuration).
• You have TFTP server running on your host.
PetaLinux Configuration and Build System Image
Steps to configure PetaLinux for TFTP boot and build the system image are:
1. Change to root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select "Image Packaging Configuration".
4. Select "Copy final images to tftpboot" and set "tftpboot directory".
5. Save Configuration settings and build system image as explained in Build System Image.
Configuring NFS Boot
One of the most important components of a Linux system is the root file system. A good
development root file system provides the developer with all the useful tools that can help
him/her on his/her work. Such a root file system can become very big in size, so it is hard
to store it in flash memory.
Reference Guide 46
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
The most convenient thing is to mount the entire root file system from the network,
allowing the host system and the target to share the same files. The root file system can be
modified quickly and also on the fly (meaning that the file system can be modified while
the system is running). The most common way to setup a system like the one described is
through NFS.
TIP: In case of NFS, no manual refresh is needed for new files.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have created a new PetaLinux project (refer to section Create a New PetaLinux
Project) and imported the hardware platform (refer to section Import Hardware
Configuration).
• You have Linux file and directory permissions.
• You have NFS server setup on your host.
PetaLinux Configuration and Build System Image
Steps to configure the PetaLinux for NFS boot and build the system image are as follows:
1. Change to root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
3. Select Image Packaging Configuration.
4. Select Root filesystem type.
5. Select NFS as the RootFS type.
6. Select Location of NFS root directory and set it to /home/NFSshare.
7. Exit menuconfig and save configuration settings. The bootargs in the auto generateid
DTSI will be updated with the PetaLinux loading rootfs from SD card default settings.
You can check
"<plnx-proj-root>/components/plnx_workspace/device-tree-generatio
n/system-conf.dtsi".
8. Build the system image. Refer to section Build System Image.
Reference Guide 47
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Booting with NFS
In case of NFS Boot, RootFS is mounted through the NFS. But bootloader (fsbl, bitstream,
u-boot) and kernel can be downloaded using various methods as mentioned below.
1. JTAG: In this case, bootloader and kernel will be downloaded on to the target through
JTAG. Refer to Boot a PetaLinux Image on Hardware with JTAG.
TIP: If you want to make use of prebuilt capability to boot with JTAG, package images into prebuilt
directory. Refer to Package Prebuilt Image.
2. TFTPBOOT: In this case, bootloader will be downloaded through JTAG and kernel will be
downloaded on to the target through TFTPBOOT. Refer to Boot a PetaLinux Image on
Hardware with TFTP.
3. SD card: In this case, bootloader (BOOT.BIN) and kernel image (image.ub) will be
copied to SD card and will be downloaded from SD card. Refer to Boot a PetaLinux
Image on Hardware with SD Card.
Configuring SD Card ext filesystem Boot
This section describes how to configure SD Card ext filesystem boot.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have created a new PetaLinux project (refer to section Create a New PetaLinux
Project) and imported the hardware platform (refer to section Import Hardware
Configuration).
• An SD memory card with at least 4 GB of storage space. It is recommended to use a
card with speed-grade 6 or higher to achieve optimal file transfer performance.
Preparing the SD card
Steps to prepare the SD card for PetaLinux SD card ext filesystem boot:
1. The SD card is formatted with two partitions using a partition editor such as gparted.
2. The first partition should be at least 40 MB in size and formatted as a FAT32 filesystem.
Ensure that there is 4MB of free space preceding the partition. The first partition will
contain the bootloader, devicetree and kernel images. Label this partition as BOOT.
Reference Guide 48
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. The second partition should be formatted as an ext4 filesystem and can take up the
remaining space on the SD card. This partition will store the system root filesystem.
Label this partition as rootfs.
TIP: For optimal performance make sure that the SD card partitions are 4 MB aligned.
PetaLinux Configuration and Build System Image
Steps to configure PetaLinux for SD card ext filesystem boot and build the system image are
as follows:
1. Change to root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch top level system configuration menu.
$ petalinux-config
3. Select Image Packaging Configuration.
4. Select Root filesystem type.
5. Select SD card as the RootFS type.
6. Exit menuconfig and save configuration settings. The bootargs in the auto generated
DTSI will be updated with the PetaLinux loading rootfs from SD card default settings.
You can check
"<plnx-proj-root>/components/plnx_workspace/device-tree-generatio
n/system-conf.dtsi".
7. Build PetaLinux images. For more information, refer to Build System Image.
8. Generate boot image. For more information, refer to section Generate Boot Image for
Zynq Family Devices.
9. The generated rootfs.cpio file will be present in images/linux directory.
Copying Image Files
This section explains how to copy image files to SD card partitions.
1. Change to root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Copy BOOT.BIN and image.ub to BOOT partition of SD card. The image.ub file will
have device tree and kernel image files.
$ cp images/linux/BOOT.BIN /media/BOOT/
$ cp images/linux/image.ub /media/BOOT/
Reference Guide 49
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. Copy rootfs.cpio file to rootfs partition of SD card and extract the file system.
$ cp images/linux/rootfs.cpio /media/rootfs/
$ cd /media/rootfs
$ sudo pax -rvf rootfs.cpio
In order to boot this SD card ext image, refer to section Boot a PetaLinux Image on
Hardware with SD Card.
Troubleshooting
Including Prebuilt Applications
If an application is developed outside PetaLinux (for example, through Xilinx SDK), you may
just want to add the application binary in the PetaLinux root file system. In this case, an
application template is created to allow copying of the existing content to target filesystem.
This section explains how to include pre-compiled applications to PetaLinux root file
system.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps to Include Prebuilt Applications
If your prebuilt application name is myapp, including this into PetaLinux root file system is
explained in following steps.
1. Ensure that the pre-compiled code has been compiled for your PetaLinux target
architecture (For example, MicroBlaze, ARM etc.).
2. Create an application with the following command.
$ petalinux-create -t apps --template install --name myapp --enable
Table 1-13: Configuring SD Card ext Filesystem Boot
Problem / Error Message Description and Solution
EXT4-fs (mmcblk0p2):
mounted filesystem with
ordered data mode. Opts:
(null) Kernel panic - not
syncing: No working init
found.
Problem Description:
This message indicates that the Linux kernel is unable to mount EXT4
File System and unable to find working init.
Solution:
Extract RootFS in rootfs partition of SD card. Refer to Extract RootFS for
more details
Reference Guide 50
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. Change to the newly created application directory.
$ cd <plnx-proj-root>/project-spec/meta-user/recipes-apps/myapp/files/
4. Remove existing myapp app and copy the prebuilt myapp.
$ rm myapp
$ cp <path-to-prebuilt-app> .
IMPORTANT: You need to ensure that the binary data being installed into the target file system by an
install template application is compatible with the underlying hardware implementation of your
system.
Including Prebuilt Modules
If you have pre-compiled kernel modules, you may just want to add the module into
PetaLinux root file system. This section explains how to include pre-compiled Modules to
PetaLinux root file system.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps to Include Prebuilt Modules
If your prebuilt module name is mymodule, including this into PetaLinux root file system is
explained in following steps:
1. Ensure that the pre-compiled kernel module has been compiled for your PetaLinux
target architecture (For example, MicroBlaze, ARM etc.).
2. To create a module project, use the following command.
$ petalinux-create -t apps --template install --name mymodule --enable
3. Change to the newly created module directory.
$ cd <plnx-proj-root>/project-spec/meta-user/recipes-modules//mymodule/files
4. Place the pre-built library mymodule
$ cp <path-to-prebuilt-module>
Reference Guide 51
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
5. Open the mymodule.bb file.
#
# This file is the mymodule recipe.
#
SUMMARY = "Simple mymodule application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM =
"file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
SRC_URI = "file://mymodule.ko \
"
S = "${WORKDIR}"
do_install() {
install -d ${D}${base_libdir}/modules/${KERNEL_VERSION}/extra/
install -m 0644 ${S}/mymodule.ko
${D}${base_libdir}/modules/${KERNEL_VERSION}/extra/
}
FILES_${PN} = "${base_libdir}/modules/"
Adding Custom Applications
This section explains how to add custom applications to PetaLinux root file system.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps to Add Custom Applications
The basic steps are as follows:
1. Create a user application by running petalinux-create -t apps from inside a PetaLinux
project on your workstation:
$ cd <plnx-proj-root>
$ petalinux-create -t apps [--template TYPE] --name <user-application-name> --enable
For example, to create a user application called myapp in C (the default):
$ petalinux-create -t apps --name myapp --enable
or:
$ petalinux-create -t apps --template c --name myapp --enable
Reference Guide 52
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
To create a C++ application template, pass the --template c++ option, as follows:
$ petalinux-create -t apps --template c++ --name myapp --enable
To create an autoconf application template, pass the --template autoconf option, as
follows:
$ petalinux-create -t apps --template autoconf --name myapp --enable
The new application created can be found in the
"<plnx-proj-root>/project-spec/meta-user/recipes-apps/myapp" directory.
2. Change to the newly created application directory.
$ cd <plnx-proj-root>/project-spec/meta-user/recipes-apps/myapp
You will see the following PetaLinux template-generated files:
Note: If you want to use the build artifacts for debugging with the third party utilities, add the
following line:
RM_WORK_EXCLUDE += “myapp”
3. myapp.c/myapp.cpp file can be edited or replaced with the real source code for your
application. Later if you want to modify your custom user application, this file should be
edited.
CAUTION! You can delete the app directory if it is no longer required. Apart from deleting the app
directory, you have to remove the line: IMAGE_INSTALL_append= “myapp” from
<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/images/petalinux-image.bbappend.
Deleting the directory by keeping the mentioned line will throw an error.
Table 1-14: Adding Custom Applications Template Generated Files
Template Description
<plnx-proj-root>/project-
spec/meta-plnx-generated/
recipes-core/images/petal
inux-image.bbappend
Configuration file template - This file controls the integration of
your application into the PetaLinux rootfs menu configuration. It
also allows you select or de-select the app and its dev, dbg
packages into the target root file system
Makefile Compilation file template - This is a basic Makefile containing
targets to build and install your application into the root filesystem.
This file needs to be modified when you add additional source code
files to your project.
README A file to introduce how to build the user application.
myapp.c for C;
myapp.cpp for C++
Simple application program in either C or C++, depending upon
your choice.
Reference Guide 53
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Adding Custom Modules
This section explains how to add custom kernel modules to PetaLinux root file system.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps to Add Custom Modules
1. Create a user module by running petalinux-create -t modules from inside a PetaLinux
project on your workstation:
$ cd <plnx-proj-root>
$ petalinux-create -t modules --name <user-module-name> --enable
For example, to create a user module called mymodule in C (the default):
$ petalinux-create -t modules --name mymodule --enable
or:
$ petalinux-create -t modules --name mymodule --enable
You can use -h or --help to see the usage of the petalinux-create -t modules. The
new module you have created can be found in the
<plnx-proj-root>/project-spec/meta-user/recipes-modules/mymodule
directory.
2. Change to the newly created module directory.
$ cd
<plnx-proj-root>/project-spec/meta-user/recipes-modules/mymodule
You will see the following PetaLinux template-generated files:
Table 1-15: Adding Custom Modules Template-Generated Files
Template Description
Makefile Compilation file template - This is a basic Makefile containing
targets to build and install your module into the root filesystem.
This file needs to be modified when you add additional source code
files to your project.
README A file to introduce how to build the user module.
Reference Guide 54
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. mymodule.c file can be edited or replaced with the real source code for your module.
Later if you want to modify your custom user module, you should edit this file.
Note: If you want to use the build artifacts for debugging with the third party utilities, add the
following line in myapp.bb:
RM_WORK_EXCLUDE += "myapp"
CAUTION! You can delete the module directory if it is no longer required. Apart from deleting the
module directory, you have to remove the line: IMAGE_INSTALL_append= “mymodule” from
<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/images/petalinux-image.bbappend.
Deleting the directory by keeping the mentioned line in petalinux-image.bbappend will throw an error.
Building User Applications
This section explains how to build and install pre-compiled/custom user applications to
PetaLinux root file system.
Prerequisites
This section assumes that you have included pre-compiled applications to PetaLinux root
file system (refer to section Including Prebuilt Applications) or added custom applications
to PetaLinux root file system (refer to section Adding Custom Applications).
Steps to Build User Applications
Running petalinux-build in the project directory "<plnx-proj-root>" will rebuild
the system image including the selected user application myapp. (The output directory for
this build process is
"<TMPDIR>/work/{ARCH}-xilinx-linux-gnueabi/myapp/1.0-r0")
$ petalinux-build
mymodule.c Simple kernel module in C.
<plnx-proj-root>/project-
spec/meta-plnx-generated/
recipes-core/images/petal
inux-image.bbappened
Configuration file template - This file controls the integration of
your application into the petalinux rootfs menu configuration
system. It also allows you to select or de-select the app and its dev,
dbg packages into the target root file system.
Table 1-15: Adding Custom Modules Template-Generated Files (Cont’d)
Template Description
Reference Guide 55
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
To build myapp into an existing system image:
$ cd <plnx-proj-root>
$ petalinux-build -c rootfs -x do_gen_sysroot
$ petalinux-build -c myapp
$ petalinux-build -x package
Note: do_gen_sysroot is to generate the sysroot based on the selected prebuilt packages
options from the menuconfig. You do not have to always run do_gen_sysroot before building the
application, but you need to run it at least once before you build the application.
Other petalinux-build options are explained with --help. Some of the build options
are:
• To clean the selected user application:
$ petalinux-build -c myapp -x do_clean
• To rebuild the selected user application:
$ petalinux-build -c myapp -x build
This will just compile the application, the compiled executable files will be in
${TMPDIR}/work/{ARCH}-xilinx-linux-gnueabi/myapp/1.0-r0/
directory.
Note: If you want to use the build artifacts for debugging with the third party utilities, add the
line: RM_WORK_EXCLUDE += “myapp” in <plnx-proj-root>/build/conf/local.conf. Without
this line the flag will remove all the executables after building.
To see all list of tasks for myapp: petalinux-build -c myapp -x list_tasks.
• To install the selected user application:
$ petalinux-build -c rootfs/myapp -x do_install
This will install the application into the target rootfs host copy:
<plnx-proj-root>/build/tmp/work/{MACHINE}-linux-gnueabi/petalinu
x-user-image/1.0-r0/rootfs/.
Note: TMPDIR can be found in petalinux-config->Yocto-settings --> TMPDIR. If the project is on
local storage, TMPDIR is <plnx-proj-root>/build/tmp/.
For Zynq Ultrascale+ MPSoC:
ARCH: aarch64
MACHINE: plnx_aarch64s
Reference Guide 56
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Testing User Application
This section describes how to test a user application.
Prerequisites
This section assumes that you have built and installed pre-compiled/custom user
applications. Refer to section Building User Applications.
Steps to Test User Application
1. Boot the newly created system image.
2. Confirm that your user application is present on the PetaLinux system, by running the
following command on the target system login console:
# ls /usr/bin
Unless you have changed the location of user application through its Makefile, the user
application will be put in to "/usr/bin" directory.
3. Run your user application on the target system console. For example, to run user
application myapp:
# myapp
4. Confirm that the result of the application is as expected.
If the new application is missing from the target filesystem, ensure that you have completed
the petalinuxbuild -x package step as described in the previous section. This ensures
that your application binary is copied into the root filesystem staging area, and that the
target system image is updated with this new filesystem.
Building User Modules
This section explains how to build and install pre-compiled/custom user kernel modules to
PetaLinux root file system.
Prerequisites
This section assumes that you have included pre-compiled applications to PetaLinux root
file system (refer to section Including Prebuilt Modules) or added custom modules to
PetaLinux root file system (refer to section Adding Custom Modules).
Reference Guide 57
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps to Build User Modules
Running petalinux-build in the project directory "<plnx-proj-root>" will rebuild
the system image including the selected user module mymodule. (The output directory for
this build process is
<TMPDIR>/work/{ARCH}-xilinx-linux-gnueabi/mymodule/1.0-r0/)
$ petalinux-build
To build mymodule into an existing system image:
$ cd <plnx-proj-root>
$ petalinux-build -c mymodule
$ petalinux-build -x package
Other petalinux-build options are explained with --help. Some of the build options
are:
• To clean the selected user module:
$ petalinux-build -c mymodule -x do_clean
• To rebuild the selected user module:
$ petalinux-build -c mymodule -x do_build
This will just compile the module, the compiled executable files will be in
<TMPDIR>/work/{ARCH}-xilinx-linux-gnueabi/mymodule/1.0-r0/
directory.
To see all list of tasks for this module: petalinux-build -c mymodule -x
list_tasks.
• To install the selected user module:
$ petalinux-build -c mymodule -x do_install
This will install the module into the target rootfs host copy:
<plnx-proj-root>/build/tmp/work/{MACHINE}-linux-gnueabi/petalinu
x-user-image/1.0-r0/rootfs/.
Note: TMPDIR can be found in petalinux-config->Yocto-settings --> TMPDIR. If the project is on
local storage, TMPDIR is <plnx-proj-root>/build/tmp/.
For Zynq Ultrascale+ MPSoC:
ARCH: aarch64
MACHINE: plnx_aarch64s
Reference Guide 58
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
PetaLinux Auto Login
This section explains how to login directly from boot without having to enter login
credentials.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Steps for PetaLinux Auto Login
1. Open <plnx-proj-root>/build/conf/local.conf. and add
EXTRA_IMAGE_FEATURES=”debug-tweaks”
2. Open
<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/i
mages/petalinux-user-image.bb. and delete the line: “inherit extrausers”
3. Delete the line: “EXTRA_USERS_PARAMS = “usermod -P rrot root;”
petalinux-build”
CAUTION! <plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/images/petalinux-user-i
mage.bb file will be regenerated for every petalinux-config and petalinux-config -c rootfs. Auto login
will be provided as an option in rootfs menu config for the next release.
Application Auto Run at Startup
This section explains how to add applications that run automatically at system startup.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Reference Guide 59
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps for Application Auto Run at Startup
If you have a prebuilt or newly created custom user application mystartup located in your
PetaLinux project at
<plnx-proj-root>/project-spec/meta-user/recipes-apps/, you may want to
execute it at system startup. The steps to enable that are:
TIP: If you have prebuilt application and you have not included in PetaLinux Root file system, refer to
IIncluding Prebuilt Applications.
If you want to create custom application and install it in PetaLinux Root file system, refer to Adding
Custom Applications.
If your auto run application is a blocking application which will never exit, launch this application as
a daemon.
1. Change to the application directory.
<plnx-proj-root>/project-spec/meta-user/recipes-apps/mystartups/mystartup
2. Create mystartup.sh file with the following:
#!/bin/sh
start ()
{
echo " Start Hello PetaLinux."
# add your app
}
stop ()
{
echo " Stop Hello PetaLinux."
}
restart()
{
stop
start
}
case "$1" in
start)
start; ;;
stop)
stop; ;;
restart)
restart; ;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
esac
exit $?
Reference Guide 60
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. Change to project-spec/meta-user/recipes-apps/mystartup/.Open
mystartup.bb and add the following lines:
#
# This file is the mystartup recipe.
#
SUMMARY = "Simple mystartup application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM =
"file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
SRC_URI = "file://mystartup.c \
file://Makefile \
file://mystartup.sh \
"
INITSCRIPT_NAME = "mystartup"
INITSCRIPT_PARAMS = "defaults"
S = "${WORKDIR}"
inherit update-rc.d
do_compile() {
oe_runmake
}
do_install() {
install -d ${D}${bindir}
install -m 0755 mystartup ${D}${bindir}
install -d ${D}${sysconfdir}/init.d/
install -m 0755 mystartup.sh ${D}${sysconfdir}/init.d/mystartup
}
Debugging the Linux Kernel in QEMU
This section describes how to debug the Linux Kernel inside QEMU, using the GDB
debugger. Note that this function is only tested with Zynq family devices platform.
Prerequisites
This section assumes that you have built PetaLinux system image. Refer to section Build
System Image for more information.
Reference Guide 61
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Steps to Debug the Linux Kernel in QEMU
1. Launch QEMU with the currently built Linux by running the following command:
$ petalinux-boot --qemu --kernel
2. Watch the qemu console, you should see the details of the QEMU command, get the
GDB TCP port from -gdb tcp:<TCP_PORT>.
3. Open another command console (ensuring the PetaLinux settings script has been
sourced), and change to the Linux directory:
$ cd "<plnx-proj-root>/images/linux"
4. Start GDB on the vmlinux kernel image in command mode:
$ petalinux-util --gdb vmlinux
You should see the gdb prompt. For example:
GNU gdb (Sourcery CodeBench Lite 2013.11-53) 7.6.50.20130726-cvs
GNU gdb (Linaro GDB 2016.08) 7.11.1.20160801-git
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-unknown-linux-gnu
--target=aarch64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from vmlinux...done.
5. Attach to the QEMU target in GDB by running the following GDB command:
(gdb) target remote :9000
6. To let QEMU continue execution:
(gdb) continue
7. You can use Ctrl+C to interrupt the kernel and get back the GDB prompt.
8. You can set break points and run other GDB commands to debug the kernel.
CAUTION! If another process is using port 9000, petalinux-boot will attempt to use a different port.
Look at the output of petalinux-boot to determine what port was used. In the following example port
9001 was used.
INFO: qemu-system-arm ... -gdb tcp::9001 ...
Reference Guide 62
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
TIP: It may be helpful to enable kernel debugging in the kernel configuration menu (petalinux-config
--kernel > Kernel hacking > Kernel debugging), so that kernel debug symbols are present in the image.
Troubleshooting
This section describes some common issues you may experience while debugging the Linux
kernel in QEMU.
Debugging Applications with TCF Agent
This section talks about debugging user applications with the Eclipse TCF (Target
Communication Framework) Agent. This section describes the basic debugging procedure
for Zynq user application myapp.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• Working knowledge with Xilinx Software Development Kit (XSDK) tool.
• The Vivado Tools Working Environment is properly set. Refer to section PetaLinux
Working Environment Setup.
• You have created a user application and built the system image including the selected
user application. Refer to section Building User Applications.
Preparing the build system for debugging
1. Change to the project directory:
$ cd <plnx-proj-root>
2. Run petalinux-config -c rootfs on the command console:
$ petalinux-config -c rootfs
Table 1-16: Debugging the Linux Kernel in QEMU Troubleshooting
Problem / Error Message Description and Solution
(gdb) target remote
W.X.Y.Z:9000:9000:
Connection refused.
Problem Description:
GDB failed to attach the QEMU target. This is most likely because the
port 9000 is not the one QEMU is using.
Solution:
• Check your QEMU console to make sure QEMU is running.
• Watch the Linux host command line console. It will show the full
QEMU commands, you should be able to see which port is used by
QEMU.
Reference Guide 63
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. Scroll down the linux/rootfs Configuration menu to Filesystem Packages, followed by
the base sub-menu:
[ ] Advanced Package Selection
[*] base-system-default
base --->
baseutils --->
benchmark --->
console --->
devel --->
doc --->
kernel -->
libs --->
misc --->
multimedia -->
net -->
network -->
optional -->
x -->
xll -->
4. Select base ---> submenu, and then click into misc ---> submenu:
base --->
baseutils --->
benchmark --->
console --->
devel --->
fonts --->
kernel -->
libs --->
misc --->
multimedia -->
net -->
network -->
optional -->
x -->
xll -->
5. Packages are in alphabetical order. Navigate to the letter ‘t’, as shown below:
tbb -->
tcf-agent -->
tiff -->
util-macros -->
v4l-utils -->
videoproto -->
vte -->
x264 -->
xauth -->
xcb-util-image -->
xcb-util-keysyms -->
xcb-util-renderutil -->
xcb-util-wm -->
xcmiscproto -->
xdpyinfo -->
Reference Guide 64
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
6. Ensure that tcf-agent is enabled.
[*] tcf-agent
[ ] tcf-agent-dev
[ ] tcf-agent-dbg
7. Select console/network ---> submenu, and then click into dropbear --->
submenu. Ensure "dropbear-openssh-sftp-server" is enabled.
[*] dropbear-openssh-sftp-server
8. Exit the menu and select <Yes> to save the configuration.
9. Rebuild the target system image including myapp. Refer to section Build System Image.
Performing a Debug Session
1. Boot your board (or QEMU) with the new image.
2. The boot log should indicate that tcf-agent has started. The following message should
be seen:
Starting tcf-agent: OK
3. Launch Xilinx SDK, and create a workspace.
4. Add a Hardware Platform Specification by selecting File > New > Project.
5. In the pop-up window select Xilinx > Hardware Platform Specification.
6. Give the Hardware Project a name. For example, ZC702
7. Locate the system.hdf for your target hardware. This can be found in
<plnx-proj-root>/project-spec/hw-description/system.hdf.
8. Open the Debug Launch Configuration window by selecting Run > Debug
Configurations.
9. Create a new Xilinx C/C++ application (System Debugger) and launch
configuration:
Reference Guide 65
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
10. The Debug Type should be set to Linux Application Debug.
11. Select the New option to enter the Connection details.
12. Give the Target Connection a name, and specify the Host (IP address for the target).
13. Set the port of tcf-agent and select OK.
X-Ref Target - Figure 1-1
Figure 1-1: XSDK Debug Configurations
X-Ref Target - Figure 1-2
Figure 1-2: XSDK Debug New Target Configuration
Reference Guide 66
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
IMPORTANT: If debugging on QEMU, refer to Appendix D QEMU Virtual Networking Modes for
information regarding IP and port redirection when testing in non-root (default) or root mode. For
example, if testing in non-root mode, you will need to use localhost as the target IP in the subsequent
steps.
14. Switch to the Application Tab.
15. Enter the Local File Path to your compiled application in the project directory. For
example,
<TMPDIR>/{ARCH}--xilinx-linux-gnueabi/myapp/1.0-r0/image/usr/bin
/.
Note: While creating the app, you need to add RM_WORK_EXCLUDE == “myapp”, otherwise the
images will not be available for debugging.
16. The Remote File Path on the target file system should be the location where the
application can be found. For example, /usr/bin/myapp.
17. Select Debug to Apply the configuration and begin the Debug session. (If asked to
switch to Debug Perspective, accept).
18. Standard XSDK debug flow is ready to start:
X-Ref Target - Figure 1-3
Figure 1-3: XSDK Debug Configurations
Reference Guide 67
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
TIP: To analyze the code and debug you can use the following short keys:
Step Into (F5)
Step Over (F6)
Step Return (F7)
Resume (F8)
X-Ref Target - Figure 1-4
Figure 1-4: XSDK Debug
Reference Guide 68
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Debugging Zynq UltraScale+ MPSoC Applications
with GDB
PetaLinux supports debugging Zynq UltraScale+ MPSoC user applications with GDB. This
section describes the basic debugging procedure.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• The Vivado Tools Working Environment is properly set. Refer to section PetaLinux
Working Environment Setup.
• You have created a user application and built the system image including the selected
user application. Refer to section Building User Applications.
Preparing the build system for debugging
1. Change to the project directory:
$ cd <plnx-proj-root>
2. Run petalinux-config -c rootfs on the command console:
$ petalinux-config -c rootfs
3. Scroll down the linux/rootfs Configuration menu to Debugging:
Filesystem Packages --->
Libs --->
Apps --->
Modules --->
PetaLinux RootFS Settings --->
4. Select Apps -->myapp -->
[ ] myapp
[X] myapp-dbg
[ ] myapp-dev
Select myapp-dbg. Exit the myapp sub-menu.
5. Exit the App sub-menu, and select the Filesystem Packages, followed by the base
sub-menu:
misc
6. Select the gdb sub-menu option, and ensure gdbserver is enabled:
selecting_gdb server
7. Exit the menu and select <Yes> to save the configuration.
Reference Guide 69
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
8. Rebuild the target system image. Refer to section Build System Image.
Performing a Debug Session
1. Boot your board (or QEMU) with the new image created above.
2. Run gdbserver with the user application on the target system console (set to listening
on port 1534):
root@plnx_aarch64:~# gdbserver host:1534 /usr/bin/myapp
Process /bin/myapp created; pid = 73
Listening on port 1534
1534 is the gdbserver port - it can be any unused port number
3. On the workstation, navigate to the compiled user application’s directory:
$ cd <plnx-proj-root>/build/linux/rootfs/apps/myapp
4. Run GDB client.
$ petalinux-util --gdb myapp
5. The GDB console will start:
...
GNU gdb (crosstool-NG 1.18.0) 7.6.0.20130721-cvs
...
(gdb)
6. In the GDB console, connect to the target machine using the command:
a. Use the IP address of the target system, for example: 192.168.0.10. If you are not sure
about the IP address, run ifconfig on the target console to check.
b. Use the port 1534. If you select a different gdbserver port number in the earlier step,
use that value instead.
IMPORTANT: If debugging on QEMU, refer to the QEMU Virtual Networking Modes for information
regarding IP and port redirection when testing in non-root (default) or root mode. For example, if
testing in non-root mode, you will need to use localhost as the target IP in the subsequent steps.
(gdb) target remote 192.168.0.10:1534
The GDB console will attach to the remote target. Gdbserver on the target console will
display the following confirmation, where the host IP is displayed:
Remote Debugging from host 192.168.0.9
7. Before starting the execution of the program, create some breakpoints. Using the GDB
console you can create breakpoints throughout your code using function names and
line numbers. For example, create a breakpoint for the main function:
(gdb) break main
Breakpoint 1 at 0x10000444: file myapp.c, line 10.
Reference Guide 70
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
8. Run the program by executing the continue command in the GDB console. GDB will
begin the execution of the program.
(gdb) continue
Continuing.
Breakpoint 1, main (argc=1, argv=0xbffffe64) at myapp.c:10
10 printf("Hello, PetaLinux World!\n");
9. To print out a listing of the code at current program location, use the list command.
(gdb) list
5 */
6 #include <stdio.h>
7
8 int main(int argc, char *argv[])
9 {
10 printf("Hello, PetaLinux World!\n");
11 printf("cmdline args:\n");
12 while(argc--)
13 printf("%s\n",*argv++);
14
10. Try the step, next and continue commands. Breakpoints can be set and removed
using the break command. More information on the commands can be obtained using
the GDB console help command.
11. When the program finishes, the GDB server application on the target system will exit.
Here is an example of messages shown on the console:
Hello, PetaLinux World!
cmdline args:
/usr/bin/myapp
Child exited with status 0
GDBserver exiting
root@plnx_aarch64:~#
TIP: A .gdbinit file will be automatically created, to setup paths to libraries. You may add your own
GDB initialization commands at the end of this file.
Going Further With GDB
Visit www.gnu.org, for more information on general usage of GDB, refer to the GDB project
documentation:
Reference Guide 71
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
This section describes some common issues you may experience while debugging
applications with GDB.
Configuring Out-of-tree Build
PetaLinux has the ability to automatically download up-to-date kernel/u-boot source code
from a Git repository. This section describes how this features works and how it can be
used in system-level menu config. It describes two ways of doing the out-of-tree builds.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have PetaLinux Tools software platform ready for building a Linux system
customized to your hardware platform. Refer to section Import Hardware Configuration
for more information.
• Internet connection with git access is available.
Steps to Configure out-of-tree Build
Steps to configure UBOOT/Kernel out-of-tree build:
1. Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
2. Launch the top level system configuration menu.
$ petalinux-config
Table 1-17: Debugging Zynq Ultrascale+ MPSoC Applications with GDB Troubleshooting
Problem / Error Message Description and Solution
GDB error message: <IP
Address>:<port>: Connection
refused. GDB cannot connect
to the target board using
<IP>: <port>
Problem Description:
This error message indicates that the GDB client failed to connect to the
GDB server.
Solution:
• Check whether the gdbserver is running on the target system.
• Check whether there is another GDB client already connected to the
GDB server. This can be done by looking at the target console. If you
can see:
Remote Debugging from host <IP>
It means there is another GDB client connecting to the server.
• Check whether the IP address and the port are correctly set.
Reference Guide 72
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
3. Select "linux Components Selection --->" sub-menu.
°For kernel, select "linux-kernel () --->" and then select remote
( ) linux-xlnx
( ) ext-local-src
(X) remote
°For U-boot, select " u-boot () --->” and then select remote
( ) u-boot-plnx
(X) remote
( )ext-local-src
4. For kernel, select "Remote linux-kernel settings --->", select Remote linux-kernel git URL
and enter git URL for linux-kernel.
For example: git://github.com/Xilinx/linux-xlnx.git
For u-boot, select "Remote u-boot settings --->", select Remote u-boot git URL and
enter git URL for u-boot. For example:
git://github.com/Xilinx/u-boot-xlnx.git
Note: Only git:// has to be entered.
Set a git tag as "Remote git TAG/commit ID".
You have to set any of the following values to this setting, otherwise an error message
appears.
1 - To point to HEAD of repo
${AUTOREV}
2 - To point to any tag
petalinux-v2016.4-final
3 - To point to any commit id:
commit id sha key
5. Exit the menu, and save your settings.
Reference Guide 73
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Using External Kernel and U-boot With PetaLinux
PetaLinux includes kernel source and u-boot source. However, you can build your own
kernel and u-boot with PetaLinux.
Petalinux supports local sources for kernel, Uboot and ATF
For external sources create a directory <plnx-proj-root>/components/ext_sources/
1. Copy the kernel source directory to
<plnx-proj-root>/components/ext_sources/<MY-KERNEL>
2. Copy the u-boot source directory to
<plnx-proj-root>/components/ext_sources/<MY-U-BOOT>
3. Run petalinux-config, and go into "linux Components Selection --->" sub-menu,
°For kernel, select "linux-kernel () --->" and then select ext-local-src
( ) linux-xlnx
(X) ext-local-src
( ) remote
°For U-boot, select " u-boot () --->” and then select ext-local-src
( ) u-boot-plnx
( ) remote
(X) ext-local-src
4. For kernel, select "External linux-kernel local source settings ---> "
5. Enter the path:
${TOPDIR}/../components/ext_sources/<MY-KERNEL>
6. For uboot, select "External u-boot local source settings --->”. Enter the path:
${TOPDIR}/../components/ext_sources/<MY-U-BOOT>
${TOPDIR} --> is the yocto variable pointing to <plnx-proj-root>/build directory
You can give an absolute path for the source, but you must make sure you change the path
while using the BSP with the source. It is your responsibility to change the source path. The
sources can be placed outside the project as well.
Note: When creating a BSP with external sources in project, it is your responsibility to copy the
sources into the project and do the packing. Please refer to BSP Packaging section for more details.
Reference Guide 74
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Troubleshooting
This section describes some common issues you may experience while configuring
out-of-tree build.
Devicetree Configuration
This section describes which files are safe to modify for the device tree configuration and
how to add new information into the device tree.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Configuring Devicetree
PetaLinux device tree configuration is associated with following config files that are located
at <plnx-projroot>/components/plnx_workspace/device-tree-generation/
and <plnx-proj-root>/project-spec/meta-user/recipes-dt/device-tree/.
•pcw.dtsi
• plnx_aarch64-system.dts
• system.dts
• system-conf.dtsi
Table 1-18: Configuring Out-of-Tree Build Troubleshooting
Problem / Error Message
fatal: The remote end hung up
unexpectedly ERROR: Failed
to get linux-kernel
Problem Description:
This error message indicates that system is unable to download the
source code (Kernel/UBOOT) using remote git URL and hence can not
proceed with petalinux-build.
Solution:
• Check whether entered remote git URL is proper or not.
• If above solution does not solve the problem, Cleanup the
build with the following command:
$ petalinux-build -x mrproper
Above command will remove following directories.
°< plnx-proj-root>/images/
°<plnx-proj-root>/build/
Re build the system image. Refer to section Build System Image.
Reference Guide 75
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
• system-top.dts
•zynqmp-clk.dtsi, for Zynq UltraScale+ MPSoC
•zynqmp.dtsi, for Zynq UltraScale+ MPSoC
CAUTION! All the above mentioned dtsi files are generated by the tool. Editing any of these files is not
recommended.
The <plnx-projroot>/project-spec/meta-user/recipes-dt/device-tree
holds the device-tree bbappend and files directory. The files directory holds the
system-top.dts which can be modified.
For more details on device-tree files, refer to Appendix A, PetaLinux Project Structure.
CAUTION! DTSI files listed above *.dtsi are automatically generated; user is not supposed to edit
these files.
If you wish to add information, like the Ethernet PHY information, this should be included in
the system-top.dts file. In this case, device tree should include the information relevant
for your specific platform as information (here, Ethernet PHY information) is board level and
board specific.
Note: The need for this manual interaction is because some information is "board level" and the
tools do not have a way of predicting what should be here. Refer to the Linux kernel Device Tree
bindings documents (Documentation/devicetree/bindings from the root of the kernel source) for the
details of bindings of each device.
An example of a well-formed Device-tree node for the system-top.dts is below.
/dts-v1/;
/include/ "system-conf.dtsi"
/ {
};
&gem0 {
phy-handle = <&phy0>;
ps7_ethernet_0_mdio: mdio {
phy0: phy@7 {
compatible = "marvell,88e1116r";
device_type = "ethernet-phy";
reg = <7>;
};
};
};
IMPORTANT: Ensure that the device tree node name, MDIO address, and compatible strings correspond
to the naming conventions used in your specific system.
You can add the custom dtsi files. All modified or new dtsi files should be placed in
<plnx_proj_root>/project-spec/meta-user/recipes-dt/device-tree.
Reference Guide 76
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
You can add your custom dtsi files. All modifications or new dtsi files should be placed in
<plnx_proj_root>/project-spec/meta-user/recipes-dt/device-tree
The following example demonstrates adding sample-user-1.dtsi and
sample-user-2.dtsifile:
SRC_URI_append ="\
file://system-top.dts \
file://sample-user-1.dtsi \
file://sample-user-2.dtsi \
"
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
do_compile_prepend () {
install -m 644 ${WORKDIR}/sample-user-1.dtsi ${dts_dir}/
install -m 644 ${WORKDIR}/sample-user-2.dtsi ${dts_dir}/
}
changes in system-top.dts
/dts-v1/;
/include/ "system-conf.dtsi"
/include/ "sample-user-1.dtsi.dtsi"
/include/ "sample-user-2.dtsi.dtsi"
It is not recommended to change anything in
<plnx-proj-root>/coponents/plnx_workspace/device-tree-generation/
All the changes have to be made in meta-user only. For example, if you want to change
anything, you can do in meta-user by rewriting the entire node with your changes in
meta-user layer.
U-Boot Configuration
This section describes which files are safe to modify for the U-Boot configuration and
discusses about the U-Boot CONFIG_ options/settings.
Prerequisites
This section assumes that you have PetaLinux Tools software platform ready for building a
Linux system customized to your hardware platform. Refer to section Import Hardware
Configuration for more information.
Reference Guide 77
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
Configuring U-Boot
Universal Bootloader (U-Boot) Configuration is usually done using C pre-processor defines:
• Configuration _OPTIONS_:
These are selectable by the user and have names beginning with "CONFIG_".
• Configuration _SETTINGS_:
These depend on the hardware etc. They have names beginning with "CONFIG_SYS_".
TIP: Detailed explanation on CONFIG_ options/settings documentation and README on U-Boot can
be found at Denx U-Boot Guide.
PetaLinux u-boot configuration is associated with config.mk and platform-auto.h
configuration files which are located at <plnxproj_root>/project-spec/
meta-plnx-generated/recipes-bsp/u-boot/configs and platform-top.h
located at <plnxproj_root>/project-spec/meta-user/recipes-bsp/
u-boot/files/.
For setting u-boot environment variables, edit CONFIG_EXTRA_ENV_SETTINGS variable in
platform-auto.h. Note that platform-auto.h is regenerated each time user
"petalinux-config" is run.
CAUTION! config.mk and platform-auto.h files are automatically generated; do not edit these
files.
PetaLinux does not currently automate U-Boot configuration with respect to CONFIG_
options/settings. The user can add these CONFIG_ options/settings into
platform-top.h file.
Steps to add CONFIG_ option (For example, CONFIG_CMD_MEMTEST) to
platform-top.h:
• Change into the root directory of your PetaLinux project.
$ cd <plnx-proj-root>
• Open the file platform-top.h
$ vi project-spec/meta-user/recipes-bsp/u-boot/files/platform-top.h
• If you want to add CONFIG_CMD_MEMTEST option, add the following line to the file.
Save the changes.
#define CONFIG_CMD_MEMTEST
Reference Guide 78
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
TIP: Defining CONFIG_CMD_MEMTEST enables the Monitor Command "mtest", which is used for
simple RAM test.
• Build the U-Boot image.
$ petalinux-build -c u-boot
• Generate BOOT.BIN using the following command.
$ petalinux-package --boot --fsbl <FSBL image> --fpga <FPGA bitstream> --u-boot
• Boot the image either on hardware or QEMU and stop at U-Boot stage.
• Enter the "mtest" command in the U-Boot console as follows:
U-Boot-PetaLinux> mtest
• Output on the U-Boot console should be similar to the following:
Testing 00000000 ... 00001000:
Pattern 00000000 Writing... Reading...Iteration: 20369
IMPORTANT: If CONFIG_CMD_MEMTEST is not defined, output on U-Boot console will be as follows:
U-Boot-PetaLinux> mtest
Unknown command ’mtest’ - try ’help’
Kernel and U-boot Configuration flow
Previously, the tool maintained full configuration for kernel and u-boot under
<plnx-proj-root>/subsystems/linux/kernel and
<plnx-proj-root>/subsystems/linux/uboot
Now, with the new tool, the configuration approach has been changed. Yocto provides
methodology of configuration fragments (.cfg). You can apply this configuration fragment
on the top of defconfig from main line. With this, you need not maintain full config for your
projects.
The PetaLinux tool for Kernel and u-boot takes defconfig from the main line and the
configuration fragments with respect to HDF, bsp and user are applied on top of it.
defconfig + [HDF cfg] + [bsp cfg] + [user cfg's] = full config (.config) Equation 1-1
For example: You can apply your own CFG’s by adding the following line in corresponding
bbappend:
SRC_URI_append = " myconfig.cfg"
Custom full defconfig: You can provide your own custom config.
Reference Guide 79
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 1: PetaLinux Tools Documentation
For example: For kernel
1. Copy the config file to
<plnx-proj-root>/project-spec/meta-user/recipes-kernel/linux/lin
ux-xlnx/
2. Rename the file to defconfig in
project-spec/meta-user/recipes-kernel/linux/linux-xlnx/
3. Edit
<plnx-proj-root>/project-spec/meta-user/recipes-kernel/linux/lin
ux-xlnx_%.bbappend
4. Add a new line
SRC_URI_append = " file://defconfig"
Note: Any variable with _append should have space in the beginning. Yocto works with file name
extensions, hence it is mandatory to provide a configuration fragment with .cfg extension and a
config file with defconfig.
Reference Guide 80
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 2
Yocto Features
This chapter gives all the information regarding the various features provided by Yocto.
Adding Patches to Source Repo
If the sources of a component is a git repo, you can apply patches on top of the repo.
An example to add patches for u-boot and to apply mypatch.patch is given below:
1. Copy the mypatch.patch to
<plnx-proj-root>/project-spec/meta-user/recipes-bsp/u-boot/files
/
2. Open
<plnx-proj-root>/project-spec/meta-user/recipes-bsp/u-boot/u-boo
t-xlnx_%.bbappend and add the following line:
SRC_URI_append = " file://mypatch.patch"
If there is no bbappend for a utility, you have to create bbappend for that utility on the
similar lines. An example for sample utility with mypatch.patch is shown below:
a. Create directory
<plnx-proj-root>/project-spec/meta-user/recipes-apps/sampleuti
lity/files/
b. Copy mypatch.patch to
<plnx-proj-root>/project-spec/meta-user/recipes-apps/sampleuti
lity/files/
c. Open
<plnx-proj-root>/project-spec/meta-user/recipes-apps/sampleuti
lity/sampleutility_%.bbappend and add the following line:
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
Yocto will apply the patch on the fetched git repo.
Reference Guide 81
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 2: Yocto Features
Accessing BitBake in a Project
BitBake is available only in the bash shell.
Steps to get the BitBake utility for Zynq Ultrascale+ MPSoC:
1. You should run petalinux-config or petalinux-config --oldconfig at least
once after creating the project, so that the required environment is setup.
2. Source the PetaLinux tools script:
source /opt/pkg/petalinux/settings.sh
3. Source the Yocto e-SDK:
source /opt/pkg/petalinux/components/yocto/source/aarch64/environment
-setup-aarch64-xilinx-linux
4. Source the environment setup script:
source
/opt/pkg/petalinux/components/yocto/source/aarch64/layers/poky/oe-init-build-env
5. After the above step, you will be redirected to the build directory. Stay in the build
directory to run bitbake.
6. Export XSCT:
export PATH=/opt/pkg/petalinux/tools/hsm/bin:$PATH
7. Parse PETALINUX variable to recipes:
export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE PETALINUX"
8. To test if the bitbake is available, run:
bitbake fsbl -c cleansstate
bitbake fsbl
The generated images will be placed in the deploy directory. You have to copy the
generated images into <plnx-proj-root>/images/linux directory to work with the
other commands.
Reference Guide 82
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 2: Yocto Features
Adding a Recipe from the Layers in SDk which are
not in petalinux-image.bb
The rootfs menuconfig is populated based on petalinux-image. The petalinux-image target
is supported by Xilinx.
An example to add alsa-utils is shown below:
1. The recipes can be found in yocto e-SDK:
layers/poky/meta/recipes-multimedia/alsa/
2. Open
<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/i
mages/petalinux-image.bbappend and add the following line:
IMAGE_INSTALL_append = " alsa-utils"
3. Run petalinux-config -c rootfs
Select “Filesystem Packages -->”
Select “console -->”
Select “utils -->”
and then select “alsa-utils”
Enable it, save and exit
4. Run petalinux-build
Note: It is your responsibility to add the recipes in the layers available in petalinux tools, apart
from petalinux-image.
Note: Whenever “_append” is used, there should exist an initial space after = “.
Adding Package Group
One of the best approaches for customizing images is to create a custom package group,
that will be used to build the images. Some of the package group recipe is shipped with the
PetaLinux tools.
For example:
$PETALINUX/components/yocto/source/aarch64/layers/meta-petalinux/recipes-core/packa
gegroups/packagegroup-petalinux-x11.bb
We can add custom package group, for example, an ALSA package group would be:
DESCRIPTION = "PetaLinux ASLA supported Packages"
inherit packagegroup
Reference Guide 83
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Chapter 2: Yocto Features
ALSA_PACKAGES = " \
alsa-lib \
alsa-plugins \
alsa-tools \
alsa-utils \
alsa-utils-scripts \
pulseaudio \
"
RDEPENDS_${PN}_append_zynqmp += " \
${ALSA_PACKAGES} \
"
This can be added to
<plnx-proj-root>/meta-user/recipes-core/packagegroups/packagegroup-
petalinux-alsa.bb
Add this package group in
<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/peta
linux-image.bbappend to reflect in menuconfig.
Shared sstate-cache
Yocto e-SDK contains minimal shared sstate-cache. Xilinx hosts the full petalinux-image
shared sstate-cache at http://petalinux.xilinx.com/sswreleases/rel-v2016.4/<architecture>/.
During petalinux-build, bitbake will search for sstate cache in the petalinux tool, that is the
minimal set. If the sstate cache is not found in this location, bitbake then searches for the
same in www.xilinx.com. Yet, if the sstate cache is not found, bitbake will build from scratch.
Reference Guide 84
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix A
PetaLinux Project Structure
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 bootloader (optional)
• u-boot
• Linux kernel
• rootfs. rootfs 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. Users can run petalinux-config to
modify them. Here is an example of a PetaLinux project:
<plnx-proj-root>
-components
-plnx_workspace
-device-tree-generation
-system.dts
-zynqmp-clk.dtsi
-pcw.dtsi
-plnx_aarch64-system.dts
-system-conf.dtsi
-system-top.dts
-zynqmp.dtsi
-fsbl
-fsbl_bsp
-fsbl_hwproj
-pmu-firmware
-pmu-firmware_bsp
-pmu-firmware_hwproj
-SDK.log
-xsctlock
-config.project
-hardware
Reference Guide 85
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix A: PetaLinux Project Structure
-pre-built
-linux
-etc/
-images/
-implementation/
-project-spec
-attributes
-configs/
rootfs_config
config
-hw-description/
-meta-plnx-generated/
-meta-user/
Table A-1: PetaLinux Project Description
File / Directory in a PetaLinux
Project Description
"<plnx-proj-root>/.petalinux
/"
Directory to hold tools usage and WebTalk data.
"<plnx-proj-root>/config.pro
ject/"
Project configuration file.
"<plnx-proj-root>/project-sp
ec"
Project specification of the project.
"<plnx-proj-root>/project-sp
ec/hw-description"
Hardware description imported from Vivado.
"<plnx-projroot>/project-spe
c/configs"
Configuration files of top level config and rootfs config
"<plnx-proj-root>/project-sp
ec/configs/config"
Configuration file used store user setiings
"<plnx-proj-root>/project-sp
ec/configs/rootfs_config"
Configuration file used for root filesystem.
"<plnx-proj-root>/components
/plnx_workspace/device-tree-
generation/"
Device tree files used to build device tree. The following files
are auto generated by petalinux-config:
•skeleton.dtsi (Zynq-7000 only)
•zynq-7000.dtsi (Zynq-7000 only)
•zynqmp.dtsi (Zynq UltraScale+ MPSoC only)
•pcw.dtsi (Zynq-7000 and Zynq UltraScale+MPSoC only)
• pl.dtsi
• system-conf.dtsi
It is not recommended to edit these files, as these files are
regenerated by the tools.
"<plnx-proj-root>/project-sp
ec/meta-user/recipes-dt/devi
ce-tree/files/”
system-top.dts 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 bbappend by adding your dtsi file.
Reference Guide 86
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix A: PetaLinux Project Structure
When the project is built, two directories will be 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.
Here is an example:
<plnx-proj-root>
-build
-bitbake.lock
-build.log
-config.log
-cache/
-conf/
-downloads/
-misc/
-config/
-plnx-generated/
-rootfs_config/
-sstate-cache/
-tmp/
-components
-plnx_workspace/
-config.project
"<plnx-projroot>/project-spe
c/meta-plnx-generated/recipe
s-bsp/u-boot/configs"
U-Boot PetaLinux configuration files. The following files are
auto generated by petalinux-config:
•config.mk for MicroBlaze only
• platform-auto.h
• config.cfg
platform-top.h will not be modified by any PetaLinux tools.
When U-Boot builds, these files are copied into U-Boot build
directory build/linux/u-boot/src/<U_BOOT_SRC>/ as
follows:
• config is the u-boot kconfig file.
• config.mk is copied to board/xilinx/microblaze-generic/ for
MicroBlaze.
<plnx-projroot>/project-spec
/meta-user/recipes-bsp/u-boo
t/files/platform-top.h
•platform-auto.h and platform-top.h is copied to
include/configs/ directory.
"<plnx-proj-root>/components
/"
Directory for embeddedSW workspace and place to hold
external sources while packing BSP. You can also manually copy
components into this directory. Here is the rule to place a
external component:
"<plnx-proj-root>/components/ext_source/<COMPONENT>"
Table A-1: PetaLinux Project Description (Cont’d)
File / Directory in a PetaLinux
Project Description
Reference Guide 87
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix A: PetaLinux Project Structure
-hardware
-images
-linux/
-pre-built
-linux/
-project-spec
-attributes
-configs/
-config
-rootfs_config
-hw-description/
-meta-plnx-generated/
-meta-user/
CAUTION! "<plnx-proj-root>/build/" are automatically generated. Do not manually edit files
in this directory. Contents in this directory will get updated when you run petalinux-config or
petalinuxbuild.
"<plnx-proj-root>/images/" are also automatically generated. Files in this directory will get
updated when you run petalinux-build.
The table below is an example for Zynq Ultrascale+ MPSoC.
Table A-2: Build Directory in a PetaLinux Project
Build Directory in a aPetaLinux Project Description
"<plnx-proj-root>/build/build.l
og"
Logfile of the build
"<plnx-proj-root>/build/misc/co
nfig/"
Directory to hold files related to the linux subsystem build
"<plnx-proj-root>/build/misc/ro
otfs_config/"
Directory to hold files related to the rootfs build
"<plnx-projroot>/build/tmp/work
/plnx_aarch64-xilinx-linux/peta
linux-ser-image/1.0-r0/rootfs
Target rootfs host copy
"<plnx-projroot>/tmp/plnx_aarch
64"
Stage directory to hold the libs and header files required to
build user apps/libs
"<plnx-proj-root>/build/tmp/wor
k/plnx_aarch64-xilinx-linux/lin
ux-xlnx"
Directory to hold files related to the kernel build
"<plnx-proj-root>/build/tmp/wor
k/plnx_aarch64-xilinx-linux/u-b
oot-xlnx"
Directory to hold files related to the u-boot build
"<plnx-proj-root>/components/pl
nx_workspace/device-tree-genera
tion"
Directory to hold files related to the device-tree build
"<plnx-projroot>/components/pln
x_workspace/fsbl"
Directory to hold files related to the bootloader build
Reference Guide 88
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix A: PetaLinux Project Structure
Project Layers
The PetaLinux project has two following layers under
<proj-plnx-root>/project-spec
1. meta-plnx-generated
2. meta-user
meta-plnx-generated:
This layer holds all bbappends and configuration fragment (cfg) for all components. All files
in this layer are generated by the tool based on HDF and user configuration. The files in this
layer should not be updated manually, as it is regenerated for petalinux-config and
petalinux-build commands.
meta-user:
This layer is a place holder for all user-specific changes. You can add your own bbappend
and configuration files in this layer.
Priority of the layers:
By default, meta-plnx-generated layer has the highest priority as the tool does not allow
tainting of the system based on user-configuration. If you want to taint the system, change
the priority of the meta-user to higher than meta-plnx-generated.
By default, meta-plnx-generated is at priority 6 and meta-user is at priority 4.
If you want higher priority for your changes, set meta-user priority to 7.
Note: Changing the meta-user priority is tainting of system. It is user responsibility for stability of
system.
Steps to change priority of meta-user layer to 7
1. Open
<plnx-proj-plnx-root>/project-spec/meta-user/conf/layer.conf.
2. Change BBFILE_PRIORITY_meta-user value from 4 to 7.
3. The meta-user priority is now changed to 7.
BBFILE_PRIORITY_meta-user = "7"
Table A-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
Reference Guide 89
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix B
Generating First Stage Bootloader Within
Project
This is optional. By default, the top level system settings are set to generate the first stage
bootloader.
CAUTION! If you do not want the PetaLinux build FSBL/FS-BOOT, then you will need to manually build
it on your own. Else, your system will not boot properly.
If you had disabled first stage bootloader from menuconfig previously, You can configure
the project to build first stage bootloader as follows:
1. Launch top level system settings configuration menu and configure:
$ petalinux-config
a. Click "linux Components Selection --->" sub-menu.
b. Select “First Stage Bootloader” option.
[*] First Stage Bootloader
c. Exit the menu and save the change.
This operation will generate the FSBL (First Stage Bootloader) source into
components/bootloader/ inside your PetaLinux project root directory if it does not
already exist. For Zynq® UltraScale+™ MPSoC, it will be:
components/plnx_workspace/fsbl/zynqmp_fsbl
For Zynq-7000, it will be:
components/plnx_workspace/fsbl/zynq_fsbl
For MicroBlaze, it will be:
components/plnx_workspace/fsbl/fs-boot
FSBL should be in the local project directory.
Reference Guide 90
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix B: Generating First Stage Bootloader Within Project
2. Launch petalinux-build to build the FSBL:
Build the FSBL when building the project:
$ petalinux-build
Build the FSBL only:
$ petalinux-build -c bootloader
The bootloader ELF file will be installed as zynqmp_fsbl.elf for Zynq UltraScale+
MPSoC, zynq_fsbl.elf for Zynq-7000 and fs-boot.elf for MicroBlaze in
images/linux inside the project root directory.
TIP: zynq_fsbl_bsp, zynqmp_fsbl_bsp will be auto updated when you run
petalinux-config.
Arm Trusted Firmware (ATF)
This is for Zynq UltraScale+ MPSoC only. This is mandatory. By default, the top level system
settings are set to generate the ATF.
You can set the ATF configurable options as follows:
1. Launch top level system settings configuration menu and configure:
$ petalinux-config
a. Click into “ARM Trusted Firmware Compilation Configuration” ---> submenu.
b. Enter your settings.
c. Exit the menu and save the change.
2. Build the ATF when building the project:
$ petalinux-build
Build the ATF only:
$ petalinux-build -c arm-trusted-firmware
The ATF ELF file will be installed as bl31.elf for Zynq UltraScale+ MPSoC in
images/linux inside the project root directory.
Reference Guide 91
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix B: Generating First Stage Bootloader Within Project
PMU Firmware (PMUFW)
This is for Zynq UltraScale+ MPSoC only. This is Optional. By default, the top level system
settings are set to generate the PMUFW.
CAUTION! If the user wishes not to have PetaLinux build the PMUFW, then you will need to manually
build it on your own. Else, your system will not boot properly.
You can configure the project to build PMUFW as follows:
1. Launch top level system settings configuration menu and configure:
$ petalinux-config
a. Click “linux Components Selection --->" sub-menu.
b. Select “PMU Firmware” option.
[*] PMU Firmware
c. Exit the menu and save the change.
2. Build the PMUFW when building the project:
$ petalinux-build
Build the PMUFW only:
$ petalinux-build -c pmufw
The PMUFW ELF file will be installed as pmufw.elf for Zynq UltraScale+ MPSoC in
images/linux inside the project root directory.
FS-Boot For MicroBlaze Platform Only
FS-Boot in PetaLinux is a first stage bootloader demo for MicroBlaze platform only. It is to
demonstrate how to load images from flash to the memory and jump to it. If you want to try
FS-Boot, you will need 8K Bytes BRAM at least.
FS-Boot supports Parallel flash and SPI flash in standard SPI mode only. If you are using
axi_quad_spi, it only works with X1 mode.
In order for FS-Boot to know where in the flash should get the image, macro
CONFIG_FS_BOOT_START needs to be defined. This is done by the PetaLinux tools.
PetaLinux tools set this macro automatically from the boot partition settings in the
menuconfig primary flash partition table settings. For parallel flash, it is the start address of
boot partition. For SPI flash, it is the start offset of boot partition.
The image in the flash requires a wrapper header followed by a BIN file. FS-Boot gets the
target memory location from wrapper. The wrapper needs to contain the following
information:
Reference Guide 92
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix B: Generating First Stage Bootloader Within Project
FS-Boot ignores other fields in the wrapper header. PetaLinux tools generate the wrapper
header to wrap around the u-boot BIN file.
Table B-1: Wrapper Information
Offset Description Value
0×0 FS-Boot bootable image magic code 0×b8b40008
0×4 BIN image size User defined
0×100 FS-Boot bootable image target memory
address
User defined. PetaLinux tools automatically
calculate it from the u-boot text base address
offset from the Memory Settings from the
menuconfig.
0×10c Where the BIN file start None
Reference Guide 93
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix C
Auto Config Settings
When you run petalinux-config, you will see the "Auto Config Settings"
sub-menu. If you click in the sub-menu, you will see the list of components which PetaLinux
can do auto config based on the top level system settings. If a component is selected to
enable autoconfig, when petalinux-config is run, its config files will be auto updated.
Table C-1: Auto Config Settings
Component in the
Menu Files impacted when autoconfig is enabled
Device tree • <plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/skeleton.dtsi (Zynq-7000 only)
•<plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/zynq-7000.dtsi (Zynq-7000 only)
•<plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/zynqmp.dtsi (Zynq UltraScale+ MPSoC only)
•<plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/zynqmp-clk.dtsi (Zynq UltraScale+ MPSoC only)
•<plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/pcw.dtsi (Zynq-7000 and Zynq UltraScale+ MPSoC)
•<plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/pl.dtsi (Microblaze only)
• <plnx-proj-root>/components/plnx_workspace/device-tree-gener
ation/system-conf.dtsi
kernel <plnx-proj-root>/project-spec/meta-plnx-generated/recipes-ke
rnel/linux/configs/plnx_kernel.cfg
u-boot • <plnx-proj-root>/project-spec/meta-plnx-generated/recipes-b
sp/u-boot/configs/config.cfg
•<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-b
sp/u-boot/configs/platform-auto.h
fsbl <plnx-proj-root>/components/plnx_workspace/fsbl
pmufw <plnx-proj-root>/components/plnx_workspace/pmu-firmware
fsboot <plnx-proj-root>/components/plnx_workspace/fs-boot
Reference Guide 94
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix D
QEMU Virtual Networking Modes
There are two execution modes in QEMU: non-root (the default) and root (requires sudo or
root permission). The difference in the modes relates to virtual network configuration.
In non-root mode QEMU sets up an internal virtual network which restricts network traffic
passing from the host and the guest. This works similar to a NAT router. You can not access
this network unless you redirect tcp ports.
In root mode QEMU creates a subnet on a virtual Ethernet adapter, and relies on a DHCP
server on the host system.
The following sections detail how to use the modes, including redirecting the non-root
mode so it is accessible from your local host.
Redirecting ports in non-root mode
If running QEMU in the default non-root mode, and you wish to access the internal (virtual)
network from your host machine (e.g.to debug with either GDB or TCF Agent), you will need
to forward the emulated system ports from inside the QEMU virtual machine to the local
machine. The petalinux-boot --qemu command utilizes the --qemu-args option to
perform this redirection. The following table outlines some example redirection arguments.
This is standard QEMU functionality, refer to the QEMU documentation for more details.
Table D-2: Redirection Arguments
QEMU Options
Switch Purpose Accessing guest from host
-tftp
<path-to-directory>
Sets up a TFTP server at the specified
directory, the server is available on the
QEMU internal IP address of 10.0.2.2.
-redir tcp:10021:
10.0.2.15:21
Redirects port 10021 on the host to port 21
(ftp) in the guest
host> ftp localhost 10021
-redir tcp:10023:
10.0.2.15:23
Redirects port 10023 on the host to port 23
(telnet) in the guest
host> telnet localhost 10023
Reference Guide 95
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix D: QEMU Virtual Networking Modes
The following example shows the command line used to redirect ports:
$ petalinux-boot --qemu --kernel --qemu-args "-redir tcp:1534::1534"
This document assumes the use of port 1534 for gdbserver and tcf-agent, but it is possible
to redirect to any free port. The internal emulated port can also be different from the port
on the local machine:
$ petalinux-boot --qemu --kernel --qemu-args "-redir tcp:1444::1534"
Specifying the QEMU Virtual Subnet
By default, PetaLinux uses 192.168.10.* as the QEMU virtual subnet in --root mode.
If it has been used by your local network or other virtual subnet, you may wish to use
another subnet. You can configure PetaLinux to use other subnet settings for QEMU by
running petalinux-boot as follows on the command console:
CAUTION! This feature requires sudo access on the local machine, and must be used with the --root
option.
$ petalinux-boot --qemu --root --u-boot --subnet <subnet gateway IP>/
<number of the bits of the subnet mask>
For example, to use subnet 192.168.20.*:
$ petalinux-boot --qemu --root --u-boot --subnet 192.168.20.0/24
-redir tcp:10080:
10.0.2.15:80
Redirects port 10080 on the host to port 80
(http) in the guest
Type
http://localhost:10080 in
the web browser
-redir tcp:10022:
10.0.2.15:22
Redirects port 10022 on the host to port 22
(ssh) in the guest
Run ssh -P 10022
localhost on the host to
open a SSH session to the target
Table D-2: Redirection Arguments (Cont’d)
QEMU Options
Switch Purpose Accessing guest from host
Reference Guide 96
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix E
Xilinx IP Models Supported by QEMU
The QEMU emulator shipped in PetaLinux tools supports the following Xilinx IP models:
• Zynq-7000 ARM Cortex-A9 CPU
• Zynq UltraScale+ MPSoC ARM Cortex-A53 MPCore
• Zynq UltraScale+ MPSoC Cortex-R5
• MicroBlaze CPU (little-endian AXI)
• Xilinx Zynq-7000/Zynq UltraScale+ MPSoC DDR Memory Controller
• Xilinx Zynq UltraScale+ MPSoC DMA Controller
• Xilinx Zynq UltraScale+ MPSoC SD/SDIO Peripheral Controller
• Xilinx Zynq UltraScale+ MPSoC Gigabit Ethernet Controller
• Xilinx Zynq UltraScale+ MPSoC NAND Controller
• Xilinx Zynq UltraScale+ MPSoC UART Controller
• Xilinx Zynq UltraScale+ MPSoC QSPI Controller
• Xilinx Zynq UltraScale+ MPSoC I2C Controller
• Xilinx Zynq UltraScale+ MPSoC USB Controller (Host support only)
• Xilinx Zynq-7000 Triple Timer Counter
• Xilinx Zynq-7000 DMA Controller
• Xilinx Zynq-7000 SD/SDIO Peripheral Controller
• Xilinx Zynq-7000 Gigabit Ethernet Controller
• Xilinx Zynq-7000 USB Controller (Host support only)
• Xilinx Zynq-7000 UART Controller
• Xilinx Zynq-7000 SPI Controller
• Xilinx Zynq-7000 QSPI Controller
• Xilinx Zynq-7000 I2C Controller
• Xilinx AXI Timer and Interrupt controller peripherals
• Xilinx AXI External Memory Controller connected to parallel flash
Reference Guide 97
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix E: Xilinx IP Models Supported by QEMU
• Xilinx AXI DMA Controller
• Xilinx AXI Ethernet
• Xilinx AXI Ethernet Lite
• Xilinx AXI UART 16650 and Lite
IMPORTANT: By default, QEMU will disable any devices for which there is no model available. For this
reason it is not possible to use QEMU to test your own customized IP Cores (unless you develop C/C++
models for them according to QEMU standard).
For more information refer to Zynq Ultrascale+ MPSoC Quick Emulator User Guide (UG1169)
[Ref 5].
Reference Guide 98
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix F
XEN Zynq Ultrascale+ MPSoC Example
This section details on the XEN Zynq® Ultrascale+™ MPSoC example. It describes how to
get Linux to boot as dom0 on top of XEN on Zynq Ultrascale+ MPSoC.
Prerequisites
This section assumes that the following prerequisites have been satisfied:
• You have PetaLinux Tools software platform ready for building a Linux system
customized to your hardware platform. Refer to section Import Hardware Configuration
for more information.
• You have created a PetaLinux project from the ZCU102 reference BSP.
°There are XEN related prebuilts in the pre-built/linux/images directory,
which are xen.dtb, xen.ub, xen-image and xen-rootfs.cpio.gz.u-boot.
Boot prebuilt Linux as dom0
1. Copy prebuilt XEN images and Linux Kernel image to your tftp directory so that you can
load them from u-boot with tftp.
$ cd <plnx-proj-root>
$ cp pre-built/linux/images/xen.dtb <tftpboot>/
$ cp pre-built/linux/images/xen.ub <tftpboot>/
$ cp pre-built/linux/images/xen-Image <tftpboot>/
$ cp pre-built/linux/images/xen-rootfs.cpio.gz.u-boot <tftpboot>/
2. Boot prebuilt u-boot image on the board with either jtag boot or boot from SD card.
3. Setup tftp server IP from u-boot
U-Boot-PetaLinux> setenv serverip <TFTP SERVERIP>
4. Load XEN images and kernel images from u-boots
U-Boot-PetaLinux> tftpboot D80000 xen.dtb
U-Boot-PetaLinux> tftpboot 80000 xen-Image
U-Boot-PetaLinux> tftpboot 1000000 xen.ub
U-Boot-PetaLinux> tftpboot 2000000 xen-rootfs.cpio.gz.u-boot
U-Boot-PetaLinux> bootm 1000000 2000000 D80000
Reference Guide 99
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix F: XEN Zynq Ultrascale+ MPSoC Example
Kernel Configuration Requirement
In order to run Linux kernel as dom0, the following options are required to be on:
•CONFIG_XEN
•CONFIG_HVC_DRIVER
•CONFIG_HVC_XEN
•CONFIG_XEN_NETDEV_BACKEND
The reference PetaLinux project has already enabled them by default.
XEN Device Tree Requirements
You can see the project-spec/meta-user/recipes-dt/device-tree/files/
xen-overlay.dtsi for how the XEN configuration should be in a DTS. Note that DTS for
QEMU platform is different from hardware. Use
xen-qemu.dts/xen-qemu-overlay.dts when running on QEMU.
The DTS file for XEN, should be the same as for plain Linux, with a few entries added to the
chosen node. The xen,dom0-bootargs corresponds to the Linux Kernel command line. Here
is an example:
chosen {
#address-cells = <0x2>;
#size-cells = <0x1>;
xen,xen-bootargs = "console=dtuart dtuart=serial0 dom0_mem=512M bootscrub=0
maxcpus=1 timer_slop=0";
xen,dom0-bootargs = "console=hvc0 earlycon=xen earlyprintk=xen maxcpus=1";
dom0 {
compatible = "xen,linux-zimage", "xen,multibootmodule";
reg = <0x0 0x00080000 0x3100000>;
};
};
If you want to try XEN on QEMU, you will need to disable the other CPUs except CPU0 in the
DTS, otherwise, QEMU will run very slow since it is a single threaded application:
cpus {
cpu@1 {
device_type = "none";
};
cpu@2 {
device_type = "none";
};
cpu@3 {
device_type = "none";
};
};
Reference Guide 100
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix F: XEN Zynq Ultrascale+ MPSoC Example
The steps to create xen-qemu.dtb (similar to hardware) are detailed below:
1. Copy xen-qemu.dts as system-top.dts in
project-spec/meta-user/recipes-dt/device-tree/files/
2. Change the device-tree append in meta-user as follows:
SRC_URI_append = " \
file://system-top.dts \
file://xen-qemu-overlay.dtsi \
file://xen-overlay.dtsi \
"
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
do_compile_prepend () {
install -m 644 ${WORKDIR}/xen-overlay.dtsi ${dts_dir}/
install -m 644 ${WORKDIR}/xen-qemu-overlay.dtsi ${dts_dir}/
}
3. Build petalinux-build -c device-tree.
The system.dtb will be updated after the above command.
Rebuild XEN
Assuming your PetaLinux project is created from the Zynq Ultrascale + MPSoC PetaLinux
reference BSP. XEN built from the Yocto recipe, you can rebuild the xen.ub as follows:
• Add EXTRA_IMAGE_FEATURES = "debug-tweaks" to
<plnx-proj-root>/build/conf/local.conf
•Build XEN:
$ petalinux-build -c xen-image-minimal
• Follow the example mentioned above to generate the device tree.
• The build artifacts will be in <TMPDIR>/deploy/images/plnx_aarch64.
xen-image-minimal-plnx_aarch64.cpio,
xen-image-minimal-plnx_aarch64.cpio.gz.u-boot and
plnx_aarch64-system.dtb and xen.ub with the XEN configuration.
You have to copy the required images to images/linux.
• Copy the images from the deploy directory to images/linux.
Note: By default, the petalinux-build command does not build XEN. The default root file system
does not contain the XEN tools. You have to use XEN rootfs.
Reference Guide 101
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix G
Obsolete Features
This section details the obsolete features/options in the PetaLinux Commands.
1. petalinux-create
a. -t libs: You have to use the apps methodology to develop or install libraries.
b. -t libs --priority: This option is no longer supported.
c. -t generic: Generic components are no longer supported
2. petalinux-config
a. --search: The entire search path implementation and all its sub options are no longer
supported.
3. petalinux-build
a. --makeenv - You have to provide your flags in the corresponding bbappends or in
Makefile
4. petalinux-package
a. --bsp --no-extern: You have to explicitly copy the local external components.
b. --bsp --no-local: This option is no longer supported.
c. --firmware: This option is no longer supported.
d. --image -c rootfs: You have to choose the type of File system from petalinux-config
5. petalinux-boot
a. --qemu --qemu-gdb: You can directly use --qemu-args option to ask qemu to
launch gdb.
6. petalinux-util
a. --update-sdcard: You have to update the sdcard manually. For more details, refer to
Configuring SD Card ext filesystem Boot.
Reference Guide 102
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix H
Common Errors and Recovery
This section details the common errors that appear, while working with the PetaLinux
commands, and also lists their recovery steps in detail.
The common errors and their recovery methods are:
1. TMPDIR on NFS
“ERROR: OE-core's config sanity checker detected a potential misconfiguration”
Either fix the cause of this error or disable the checker at your own risk (see sanity.conf).
Following is the list of potential problems / advisories:
The TMPDIR: /home/user/xilinx-kc705-axi-full-2016.4/build/tmp cannot be located on NFS.
The TMPDIR cannot be on NFS, therefore, it will throw an error while parsing. You have
to change it from petalinux-config and then provide any local storage.
Yocto-settings --> TMPDIR
2. Bitbake cannot run always.
Only one instance of bitbake runs for one project. If the previous build is exited abruptly,
there are chances for bitbake exiting non-gracefully for the current build.
to reciver: rm -rf <plnx-proj-root>/build/bitbake.lock
3. App/module name having ‘ _ ‘
If the app name is "plnx_myapp", bitbake throws an error. A version number has to be
entered after ‘ _ ‘.
For example, myapp_1 is an accurate app/module name.
To recover, you have delete the app created and also delete the line in
<plnx-proj-root>/project-spec/meta-plnx-generated/recipes-core/i
mages/petalinux-image.bbappend
IMAGE_INSTALL_append = " plnx_myapp"
Reference Guide 103
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix I
Additional Resources and Legal Notices
Xilinx Resources
For support resources such as Answers, Documentation, Downloads, and Forums, see Xilinx
Support.
Solution Centers
See the Xilinx Solution Centers for support on devices, software tools, and intellectual
property at all stages of the design cycle. Topics include design assistance, advisories, and
troubleshooting tips.
References
1. PetaLinux Documentation (www.xilinx.com/petalinux)
2. Xilinx Answer Record (55776)
3. Ultrascale+ MPSoC Software Developer Guide (UG1137)
4. PetaLinux Tools Documentation: Command Line Reference (UG1157)
5. Zynq Ultrascale+ MPSoC Quick Emulator User Guide (UG1169)
Reference Guide 104
UG1144 (v2016.4) December 14, 2016 www.xilinx.com
Appendix I: Additional Resources and Legal Notices
Please Read: Important Legal Notices
The information disclosed to you hereunder (the “Materials”) is provided solely for the selection and use of Xilinx products. To the
maximum extent permitted by applicable law: (1) Materials are made available "AS IS" and with all faults, Xilinx hereby DISCLAIMS
ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE; and (2) Xilinx shall not be liable (whether
in contract or tort, including negligence, or under any other theory of liability) for any loss or damage of any kind or nature related
to, arising under, or in connection with, the Materials (including your use of the Materials), including for any direct, indirect, special,
incidental, or consequential loss or damage (including loss of data, profits, goodwill, or any type of loss or damage suffered as a
result of any action brought by a third party) even if such damage or loss was reasonably foreseeable or Xilinx had been advised
of the possibility of the same. Xilinx assumes no obligation to correct any errors contained in the Materials or to notify you of
updates to the Materials or to product specifications. You may not reproduce, modify, distribute, or publicly display the Materials
without prior written consent. Certain products are subject to the terms and conditions of Xilinx’s limited warranty, please refer to
Xilinx’s Terms of Sale which can be viewed at http://www.xilinx.com/legal.htm#tos; IP cores may be subject to warranty and support
terms contained in a license issued to you by Xilinx. Xilinx products are not designed or intended to be fail-safe or for use in any
application requiring fail-safe performance; you assume sole risk and liability for use of Xilinx products in such critical applications,
please refer to Xilinx’s Terms of Sale which can be viewed at http://www.xilinx.com/legal.htm#tos.
AUTOMOTIVE APPLICATIONS DISCLAIMER
AUTOMOTIVE PRODUCTS (IDENTIFIED AS "XA" IN THE PART NUMBER) ARE NOT WARRANTED FOR USE IN THE DEPLOYMENT OF
AIRBAGS OR FOR USE IN APPLICATIONS THAT AFFECT CONTROL OF A VEHICLE ("SAFETY APPLICATION") UNLESS THERE IS A
SAFETY CONCEPT OR REDUNDANCY FEATURE CONSISTENT WITH THE ISO 26262 AUTOMOTIVE SAFETY STANDARD ("SAFETY
DESIGN"). CUSTOMER SHALL, PRIOR TO USING OR DISTRIBUTING ANY SYSTEMS THAT INCORPORATE PRODUCTS, THOROUGHLY
TEST SUCH SYSTEMS FOR SAFETY PURPOSES. USE OF PRODUCTS IN A SAFETY APPLICATION WITHOUT A SAFETY DESIGN IS FULLY
AT THE RISK OF CUSTOMER, SUBJECT ONLY TO APPLICABLE LAWS AND REGULATIONS GOVERNING LIMITATIONS ON PRODUCT
LIABILITY.
© Copyright 2016 Xilinx, Inc. Xilinx, the Xilinx logo, Artix, ISE, Kintex, Spartan, Virtex, Vivado, Zynq, and other designated brands
included herein are trademarks of Xilinx in the United States and other countries. All other trademarks are the property of their
respective owners.

Navigation menu