Building Linux Images Using Yocto

These instructions are targeted at versions 2023.1 and later of the AMD tools and Yocto build environment. For notes relevant to previous versions, refer to Install and Build with Xilinx Yocto

1 Cloning Yocto Layers
- 1.1 Yocto Host Dependencies
- 1.2 Repo
- 1.3 Ensure git is configured with your user email and name
- 1.4 Fetch Manifest and Sources
2 Build with Xilinx Yocto
- 2.1 Source the Yocto Environment
- 2.2 Bitbake the Image
3 Create and install an SD card disk image
- 3.1 Booting the board

Cloning Yocto Layers

Yocto Host Dependencies

Install the standard Yocto dependencies for your host machine per the Yocto Reference Manual - Langdale - Required Packages for the Build Host.

Alternatively, if your Linux machine does not match the host dependencies, a docker image could potentially be used as the build environment - see Building Yocto Images using a Docker Container

Repo

Repo is a repository management tool that is built on top of Git. Repo unifies the many Git repositories when necessary, and automates parts of the development workflow.

Repo is not meant to replace Git, only to make it easier to work with Git in the context of development. The repo command is an executable Python script that you can put anywhere in your path. With a single Repo command you can download files from multiple repositories into your local working directory.

For more info about Repo, please see https://source.android.com/source/developing.html.

Repo is generally available from the OS Package manager, so it is preferred to install it using this method:

# Install repo from your package manager
$ sudo apt-get install repo
or
$ sudo yum install repo

However, if you do not have access rights to your Linux machine, or if the distribution does not support repo in this way, it can be installed manually using the instructions from https://source.android.com/docs/setup/download#installing-repo

# Download repo from Google
$ export REPO=$(mktemp /tmp/repo.XXXXXXXXX)
$ curl -o ${REPO} https://storage.googleapis.com/git-repo-downloads/repo

# Authenticate signature and install 
$ gpg --recv-keys 8BB9AD793E8E6153AF0F9A4416530D5E920F5C65
$ curl -s https://storage.googleapis.com/git-repo-downloads/repo.asc | gpg --verify - ${REPO} && mkdir -p ~/bin && install -m 755 ${REPO} ~/bin/repo

# Change repo to use python3 command directly instead of python
sed -i "1s/python/python3/" ~/bin/repo

# Test repo is working
$ export PATH=~/bin:$PATH
$ repo --help

Ensure git is configured with your user email and name

The repo tool uses git to clone and setup the local build environment. If you get the error "stderr: Committer identity unknown" this means that you have not yet configured your local git profile.

You can use the following commands to achieve this:

$ git config --global user.email "you@example.com"
$ git config --global user.name "Your Name"

Fetch Manifest and Sources

Repo uses a manifest which is an XML file that describes all the required repositories.

It can manage all of your git repositories so that they remain in sync. Use repo with the Xilinx yocto-manifest file for the desired release to fetch all required source files for a Yocto build:

# Fetch the manifest and checkout the target release version
$ repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2023.2

# Fetch all the source from the repositories in the manifest
$ repo sync 

# OPTIONAL: Create a development branch on each repo
$ repo start <name> --all

Replace rel-v2023.2 with the git release tag of interest, for example, rel-v2023.1, rel-v2023.2 etc.. The tags for the yocto-manifests can be found at https://github.com/Xilinx/yocto-manifests/branches/all. The instructions below assume that you are running the current release tag.

Build with Xilinx Yocto

Source the Yocto Environment

Setupsdk is a Xilinx script which configures the Xilinx Yocto environment. Essentially it is a wrapper for the familiar "oe-init-build-env" Yocto script.

$ source setupsdk

Bitbake the Image

Finally bitbake the target image "petalinux-image-minimal". You can pass the target machine on the command line or add it to your local.conf as the default machine. When the build is completes, your images are located in "build/tmp/deploy/images/<machine>". In this example we are building for the ZCU102 board.

$ MACHINE=zcu102-zynqmp bitbake petalinux-image-minimal

Other available machines, for example zcu706-zynqmp, ultra96-zynqmp, or zc706-zynq7 can be found under "sources/meta-xilinx/meta-xilinx-bsp/conf/machine"

Create and install an SD card disk image

Depending on the target machine, a wic file might have been created for direct copy onto a raw SD card. Check to see if there is a wic file generated:

$ ls tmp/deploy/images/<machine>/*.rootfs.wic

If there is no .wic file listed, we can add the "wic" filesystem type to our local configuration and explicitly generate one:

$ sed -i '/MACHINE ??=/a IMAGE_FSTYPES:append=" wic"' conf/local.conf # Add the line IMAGE_FSTYPES:append=" wic" to conf/local.conf
$ MACHINE=zcu102-zynqmp bitbake petalinux-image-minimal
$ ls tmp/deploy/images/zcu102-zynqmp/*.rootfs.wic
tmp/deploy/images/zcu102-zynqmp/petalinux-image-minimal-zcu102-zynqmp-20240209161346.rootfs.wic

Prior to inserting an SD card into your Linux machine, check the current list of connected block devices with "lsblk":

$ lsblk -d -o NAME,SIZE,TYPE,RM
NAME      SIZE TYPE RM
nvme1n1 465.8G disk  0
nvme0n1 931.5G disk  0

Now insert an SD card into your machine, and look at the difference to determine the mount path.

In this case, the SD card mount point is "/dev/example". However, on your machine, this may well be the first boot partition of your OS, so it is critical to get the correct name. Always double check this and do not assume it will always be static. The "RM" column indicates that this is a removable device, and the SIZE column should also be double-checked to check the mount point is of the correct size.

$ lsblk -d -o NAME,SIZE,TYPE,RM
NAME      SIZE TYPE RM
example   7.2G disk  1
nvme1n1 465.8G disk  0
nvme0n1 931.5G disk  0

In conclusion, we are convinced in this example that the mount point of this SD card is /dev/example, so we can proceed with writing the SD card image.

Ensure you are 100% sure about the SD card mount point before performing the following action. If this command is performed on the wrong device, you will lose data on that drive. This is not reversible without reverting from a full disk backup!

Write the SD card image with the following command, replacing the directory, wic file name and mount point as appropriate for your build:

$ sudo dd if=tmp/deploy/images/[machine]/petalinux-image-minimal-[machine]-[date].rootfs.wic of=/dev/[example] bs=1M
eg:
$ sudo dd if=tmp/deploy/images/zcu102-zynqmp/petalinux-image-minimal-zcu102-zynqmp-20240219145338.rootfs.wic of=/dev/example bs=1M
[sudo] password for username:
706+1 records in
706+1 records out
741001216 bytes (741 MB, 707 MiB) copied, 226.657 s, 3.3 MB/s

The dd command will take some time to complete. Once completed, the SD card can be ejected from the Once completed, the SD card can be ejected and removed from the machine and inserted into the target board.

$ sudo eject /dev/example

Booting the board

The method to boot the board will vary. However, in general, the SD card is inserted into the board, and the mode dipswitches will be checked to ensure that the boot mode is set to SD card.

The table below shows an extract from the user guide for common boards to specify the dip switch to set for SD boot:

Board	User Guide	Switch[bits:used]	Value

Board	User Guide	Switch[bits:used]	Value
vhk158	User Guide	sw1[1:4]	ON, OFF, OFF, OFF
vmk180	User Guide	sw1[4:1]	OFF, OFF, OFF, ON
vpk120	User Guide	sw1[1:4]	ON, OFF, OFF, OFF
vpk180	User Guide	sw1[1:4]	ON, OFF, OFF, OFF
zcu102	User Guide	sw6[4:1]	OFF, OFF, OFF, ON
zcu104	User Guide	sw6[4:1]	OFF, OFF, OFF, ON
zcu106	User Guide	sw6[4:1]	OFF, OFF, OFF, ON
zcu111	User Guide	sw6[4:1]	OFF, OFF, OFF, ON
zcu1275	User Guide	J163,164,166,165	0,1,0,1(0=open, 1=closed)
zcu1285	User Guide	J163,164,166,165	0,1,0,1 (0=open, 1=closed)
zcu208	User Guide	sw2[4:1]	OFF, OFF, OFF, ON
zcu216	User Guide	sw2[4:1]	OFF, OFF, OFF, ON
zcu670	User Guide	sw2[4:1]	OFF, OFF, OFF, ON
vck190	User Guide	sw1[4:1]	OFF, OFF, OFF, ON
vek280	User Guide	sw1[1:4]	ON, OFF, OFF, OFF

Then, the user will ensure that a USB cable is attached to the board to connect to the appropriate UART for console output and power on the board.

Boards can have up to four UARTs connected to one USB connection for various outputs. Check the documentation to find the correct one to view, or view all four to observe the output and any additional board diagnostics.

Once booted, the board can usually be logged into with the username "petalinux"

zcu102-zynqmp login: petalinux
You are required to change your password immediately (administrator enforced).
New password: fluffybunnies
Retype new password: fluffybunnies
zcu102-zynqmp:~$