Build the BSP

Build the Linux BSP!

Note

The video linked here is a little out of date now but it is still a good introduction to building software images with Yocto. For release-specific commands, refer to the guide.

PHYTEC’s Linux BSPs are built using The Yocto Project, which is a powerful tool that allows OEMs to create production ready software images for custom hardware built around the phyCORE-AM62x System on Module (SOM). Depending on the needs of your end application and the design of your system, you will require custom modifications to the Linux kernel and/or the packages included in the root filesystem. The Yocto Project is one way to manage those changes.

This guide will walk through the setup and build process of the Yocto BSP in order to generate default software images for the phyCORE-AM62x development kit. Once the BSP is built, it can serve as a starting point for product development.

If you don’t need to build custom software images, or just want to quickly evaluate the default phyCORE-AM62x development kit out-of-the-box, feel free to download a Pre-Built Image instead. These can be found on the Pre-Built Binaries page.

Requirements

The following system requirements are necessary to successfully follow this BSP Development Guide. Deviations from these requirements may or may not have other workarounds:

• Ubuntu 20.04+ LTS, 64-bit Host Machine with root permission.

  • If using a virtual machine, VMWare Workstation, VMWare Player, and VirtualBox are all viable solutions.

• At least 100GB disk space free

• At least 8GB of RAM

• At least 4x processing cores available to the Host Machine

• Active Internet connection

The above minimum build resources (RAM/CPUs) should result in a build time of ~3.5 hours.

Host Setup

PHYTEC provides a Podman container that includes all necessary packages and dependencies. However, some additional tools must still be installed on the host system. Run the following commands to ensure these tools are available:

sh-host:~$ sudo apt-get update
sh-host:~$ sudo apt-get install podman

Note

Podman may not be available for Ubuntu 20.04 by default. Refer to this Guide for instructions on obtaining it from alternative sources.

Git Setup

If you have not yet configured your git environment on the Host Machine, please execute the following commands to set your user name and email address:

sh-host:~$ git config --global user.email "[email protected]"
sh-host:~$ git config --global user.name "Your Name"

Note

New to git? See here for more information about getting started with git: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup

Yocto Build Steps

Firstly, dedicate a directory on your Host Machine for housing the BSP and navigate there:

sh-host:~$ mkdir -p ~/BSP-Yocto-Ampliphy-AM62x-PD24.1.1/yocto
sh-host:~$ cd ~/BSP-Yocto-Ampliphy-AM62x-PD24.1.1/yocto

Podman

As mentioned earlier, PHYTEC provides a ready-to-use container image with all required packages pre-installed. For more details, visit the official phyBUILDER GitHub page. Use the following command to pull the image:

sh-host:~$ podman pull docker.io/phybuilder/yocto-ubuntu-22.04

To start the container, run:

sh-host:~$ podman run --rm=true -v /home:/home -e USER=$USER --userns=keep-id --workdir=$PWD -it docker.io/phybuilder/yocto-ubuntu-22.04 bash

Starting the container may take a few seconds, but once it’s ready, you’ll notice a change in the prompt. Remember to run this command each time you start a new shell session.

Note

Type exit to leave the container.

Download the BSP Meta Layers

Yocto-based Linux BSPs consist of multiple meta-layers, each containing recipes to fetch, build, and package components for the bootable software image you plan to create. Some meta-layers, like meta-python, are provided by the Linux community. Others are platform-specific and supplied by PHYTEC or the silicon vendor (for the phyCORE-AM62x, the silicon vendor is Texas Instruments). All required meta-layers for this PHYTEC Linux BSP can be set up using the phyLinux tool:

sh-container:~$ phyLinux init -p am62x -r BSP-Yocto-Ampliphy-AM62x-PD24.1.1

Note

Notice the prompt change. This indicates that the commands should be run inside the phyBUILDER container image, not on the host system.

Running the command above starts an interactive session to guide you through BSP setup. Since the platform (phyCORE-AM62x) and release (BSP-Yocto-Ampliphy-AM62x-PD24.1.1) are preselected, you won’t need to specify them. However, you will be prompted to choose the machine, distribution, and image.

The default BSP kit uses the following values, but you can select alternative options to explore other distributions or images.

x: phyboard-lyra-am62xx-3: PHYTEC phyBOARD-Lyra AM62x
                           ...
                           ...
                           distro: ampliphy
                           target: phytec-qt6demo-image

Note

Each MACHINE configuration will correspond to a specific SOM variant (phyLinux also combines the supported Target Linux Distributions with the MACHINE options), be sure you select the appropriate option for the hardware you have.

Initialize the BSP Environment

Source the build environment (a build directory and the $BUILDDIR environment variable will be automatically setup):

sh-container:~$ source sources/poky/oe-init-build-env

Configure the Build

The default build configuration is automatically setup based on your phyLinux selections so changing it is not required, but we’ll go over some key parts of it together here in this section of the guide.

Open the build’s configuration file using your favorite text editor. This guide will use ‘vi’ in order to modify the file directly in the terminal:

sh-container:~$ vi conf/local.conf

Note

vi/vim is perhaps the most popular command line text editor in Linux but it’s not the only way to modify text files. You could also try ‘nano’, which is a little more beginner friendly.

The vi text editor begins in “Command Mode” and you must first hit the ‘i’ key in order to enter “Insert Mode”. Using the arrow keys to navigate, make the necessary changes and then hit ESC to go back to “Command mode”. Now enter “:wq” to write the file and quit.

Optionally modify conf/local.conf after considering the following:

• The MACHINE variable being set in the conf/local.conf is used to define the machine configuration the software image will be built for, these typically correlate directly to a PHYTEC kit part number. See the BSP-Yocto-Ampliphy-AM62x-PD24.1.1 for an overview of the supported MACHINEs in the BSP-Yocto-Ampliphy-AM62x-PD24.1.1 release.

  • Once you have built a custom carrier board around the phyCORE-AM62x SOM, you can consolidate your modifications to your own custom meta-layer and build images for that system via a custom MACHINE configuration you can define yourself.

• The variables BB_NUMBER_THREADS and PARALLEL_MAKE can be used to limit the maximum number of parallel tasks and threads used by the build system. By default, these variables are not defined so Yocto will determine the resources available on the host and use them all.

  • Depending on your usage of the Host Machine, you may decide that it is best to limit the compute resources available to the build system and you can do this by adding the following to the conf/local.conf:

Optional code for conf/local.conf

# Parallelism options - based on cpu count
BB_NUMBER_THREADS ?= "4"
PARALLEL_MAKE ?= "-j 4"

• Remember to save any changes you do end up making before closing the build configuration file.

Start the Build

Use the following commands to navigate to the build directory (you should have been automatically placed there when you sourced the build environment) and start the build process for the phyCORE-AM62x Linux BSP:

sh-container:~$ cd $BUILDDIR
sh-container:~$ bitbake phytec-qt6demo-image

This command instructs bitbake to run all the tasks associated with the phytec-qt6demo-image build target, which is the default image used by PHYTEC to validate the BSP-Yocto-Ampliphy-AM62x-PD24.1.1 release.

Note

Depending on the resources available on the Host Machine, this build process can take a long time to complete the first time. Subsequent builds introducing incremental changes can be completed MUCH faster because the build system can intelligently re-build only what is necessary.

Ideally, the BSP is built on a dedicated build server with a high core/thread count and a lot of RAM.

Components of a Built BSP

All generated images deployed during the build can be found in the $BUILDDIR/deploy-ampliphy/images/phyboard-lyra-am62xx-3/ directory.

Note

• Technically, images built for a given MACHINE and DISTRO configuration are deployed to $BUILDDIR/deploy-<DISTRO>/images/<MACHINE>/ If you followed this guide exactly then MACHINE should have been set to phyboard-lyra-am62xx-3 and DISTRO to ampliphy, which corresponds to the standard phyCORE-AM62x Development Kit configuration.

• The SD Card image is a complete software image intended to be flashed directly to an SD Card, it therefore already contains your bootloader binaries, kernel images and root file system. These individual components are also deployed so that you can update/evaluate them individually throughout your development. To get started, you only need the SD Card image.

Deployed Artifacts

	Filename	Details
SD Image	phytec-qt6demo-image-phyboard-lyra-am62xx-3.rootfs.wic.xz	Complete SD Card image in compressed format, can be flashed directly to boot media once uncompressed.
Partup Image	phytec-qt6demo-image-phyboard-lyra-am62xx-3.rootfs.partup	Partup image to flash the eMMC.
Bootloader	tiboot3.bin	The first bootloader image, loaded by the boot ROM, contains both the Device Management & Security Controller (DMSC) firmware and the Cortex-R5F Secondary Bootloader (SBL).
Bootloader	tispl.bin	The second bootloader image, loaded by the R5 SBL, contains the ARM Trusted Firmware (ATF), Open Portable Trusted Execution Environment (OPTEE) and the Cortex-A53 SBL.
Bootloader	u-boot.image	Bootloader for Cortex-A53 Linux and for other software destined for the Cortex-R5F cores.
Kernel	Image	Linux Kernel Binary
Kernel Device Tree Blobs and Overlays	k3-am625-phyboard-lyra-rdk	Base Kernel Device Tree Blob (DTB)
Root filesystem	phytec-qt6demo-image-phyboard-lyra-am62xx-3.rootfs.tar.xz	Compressed root filesystem

Building the SDK Installer

Once you have successfully followed the steps outlined above for building the BSP, you can leverage the same build system to similarly build a SDK installer to begin application development in a cross-platform environment.

Build the SDK installer:

sh-container:~$ bitbake phytec-qt6demo-image -c populate_sdk

The SDK installer will be deployed to $BUILDDIR/deploy-ampliphy/sdk. For more information on setting up and using the SDK, head over to the Linux Application Development section of the wiki.

Note

For any technical questions, feel free to reach out to PHYTEC’s Support Portal!