Build the BSP

Build the 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-AM64x 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-AM64x 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-AM64x 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

Yocto development requires certain packages to be installed on the host machine to satisfy various dependencies. Run the following commands to ensure these are installed:

Host (Ubuntu)

sudo apt-get update
sudo apt-get install build-essential autoconf automake bison flex libssl-dev bc u-boot-tools python diffstat texinfo gawk chrpath dos2unix wget unzip socat doxygen libc6:i386 libncurses5:i386 libstdc++6:i386 libz1:i386 g++-multilib git python3-distutils

PHYTEC’s phyLinux script (used further down in this guide for setting up the BSP) requires that python be aliased to python3 specifically. Ubuntu 20.04 will have python=python2 by default so we must also make changes to satisfy this dependency:

Host (Ubuntu)

which python                  # confirm where python is installed, should return “/usr/bin/python”
ls -l /usr/bin/python*        # 'python' is a symlink to python2 in ubuntu 20.04, this needs to be updated to python3

# create new symlinks in /usr/local/bin/ to override (this is higher up in $PATH)
sudo update-alternatives --install /usr/local/bin/python python /usr/bin/python2.7 2
sudo update-alternatives --install /usr/local/bin/python python /usr/bin/python3.8 3       # set python3 with higher priority

source /etc/environment       # source new terminal environment for the change to take effect

python --version              # should return "python3.x" now

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:

Host (Ubuntu)

git config --global user.email "[email protected]"
git config --global user.name "Your Name"
git config --global http.sslcainfo /etc/ssl/certs/ca-certificates.crt

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:

Host (Ubuntu)

mkdir ~/BSP-Yocto-Ampliphy-AM64x-PD23.2.0
cd ~/BSP-Yocto-Ampliphy-AM64x-PD23.2.0

Download the BSP Meta Layers

Yocto based Linux BSPs are comprised of many meta-layers, each containing recipes for fetching, building and packaging various components destined for the bootable software image you intend to build. Some meta-layers are provided by the Linux community, such as meta-python for example. Other meta-layers are more platform specific and are made available by PHYTEC or the silicon vendor (in the case of the phyCORE-AM64x, the silicon vendor is Texas Instruments). All the meta-layers required for this PHYTEC Linux BSP can be setup using the phyLinux tool:

Host (Ubuntu)

wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux
chmod +x phyLinux
./phyLinux init

The above will launch an interactive session that walks you through the BSP setup. Use the following guide to help you navigate through the interactive prompts:

phyLinux Interactive session

# SoC Platform : am64x
# Release      : BSP-Yocto-Ampliphy-AM64x-PD23.2.0
# MACHINE      : phyboard-electra-am64xx-2

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):

Host (Ubuntu)

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:

Host (Ubuntu)

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 Release Notes for an overview of the supported MACHINEs in the BSP-Yocto-Ampliphy-AM64x-PD23.2.0 release.

  • Once you have built a custom carrier board around the phyCORE-AM64x 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-AM64x Linux BSP:

Host (Ubuntu)

cd $BUILDDIR
bitbake phytec-headless-image

This command instructs bitbake to run all the tasks associated with the phytec-headless-image build target, which is the default image used by PHYTEC to validate the BSP-Yocto-Ampliphy-AM64x-PD23.2.0 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/images/phyboard-electra-am64xx-2/ directory.

Note

• Technically, images built for a given MACHINE configuration are deployed to $BUILDDIR/deploy/images/<MACHINE>/ If you followed this guide exactly then MACHINE should have been set to phyboard-electra-am64xx-2, which corresponds to the standard phyCORE-AM64x 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-headless-image-phyboard-electra-am64xx-2.wic.xz	Complete SD Card image in compressed format, can be flashed directly to boot media once uncompressed.
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-am642-phyboard-electra-rdk.dtb	Base Kernel Device Tree Blob (DTB)
Root filesystem	phytec-headless-image-phyboard-electra-am64xx-2.tar.xz	Compressed root filesystem

Source Locations

During the build process, the source repositories for all the individual components that make up the SD Card image are unpacked locally in the build directory. The kernel and bootloader sources, for example, can be found at the following locations:

Kernel: $BUILDDIR/tmp/work/phyboard_electra_am64xx_2-phytec-linux/linux-ti/6.1.33-phy3-r0.0/git

• The main device tree file for the phyCORE-AM64x development kit within the Linux kernel source: arch/arm64/boot/dts/ti/k3-am642-phyboard-electra-rdk.dts

• The phyCORE-AM64x kernel defconfigs can be found at: arch/arm64/configs/

U-Boot: $BUILDDIR/tmp/work/phyboard_electra_am64xx_2-phytec-linux/u-boot-ti/1_v2023.04+gitAUTOINC+21272226f7-r0/git

• Board file is located at: board/phytec/phycore_am64x/phycore-am64x.c

• Device tree file: arch/arm/dts/k3-am642-phyboard-electra-rdk.dts

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:

Host (Ubuntu)

bitbake phytec-headless-image -c populate_sdk

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

Note

For technical support, please visit PHYTEC’s Support Portal!