Building Linux Images Using Yocto

Table of Contents

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.

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

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

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.

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:

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:~$