Building a Yocto Filesystem¶

The filesystem included with the MitySOM-AM62 Development Kit is derived from the scripts TI uses to generate their Processor SDK. The scripts use the Yocto Project to describe the contents of the filesytem, U-Boot, and Kernel needed for the dev kit's features.

In most cases, you can use the devkit's filesystem along with your U-Boot and kernel customizations needed to support your own baseboard.

If you want to generate your own filesystem or if you wish to customize the filesystem we provide, you will need to understand the Yocto build.

If you are new to Linux, building and understanding Yocto can be difficult. We recommend starting with our provided setup so you can confirm your build environment is working before you make your customizations. You may contact Critical Link for help with your Yocto build or if you want us to customize it for you.

Before We Begin¶

We recommend using a Linux-based host PC for your Yocto build. The exact version you use (Ubuntu, Fedora, etc.) is not critical as long as it supports Docker. At Critical Link, we typically recommend using an Ubuntu LTS release for your host PC.

Please use our forums if you have questions about installing Docker.

Alternate operating systems like MS Windows or Mac OSX also support Docker, so they could be tried in dire situations.

A Yocto build will heavily stress your build PC. You will likely need 500+GB of storage. 2GB of free RAM per cpu core is recommended by Yocto, if you have less you should reduce the PARALLEL_MAKE and/or BB_NUMBER_THREADS jobs. Depending on the speed of your machine, a build could require 4-5 hours of build time, depending on the options you select. Storage and Memory speed will have a significant impact on build time. The Yocto build environment will cache many build results so subsequent builds with minor changes will not require as much time.

Download the Critical Links oe-layersetup and meta-layers¶

A Yocto build uses build instructions, called recipes, to generate a filesytem. Various recipes are collected into meta-layers that provide related recipes for a specific purpose. For instance, meta-ti contains recipes that support various TI hardware. Critical Link also has its own meta-layer, meta-mitysom, that contains Yocto modifications for our various product lines (including the MitySOM-AM62).

Standard yocto builds require downloading a list of meta-layers from different git repos. TI has created a tool (oe-layersetup) that captures this setup into a script and some config files. We've expanded on this tool to add the customizations needed to run our module.

Note: These instructions use a special docker image that has been designed to contain everything needed for a Yocto build, crops/poky:ubuntu-18.04. The crops project has multiple docker images that support various Yocto releases. While you can roll your own docker image or even run the build directly on a Linux install, we have found that using a stable docker image keeps builds consistent over a long period of time.

The docker-poky.sh script automates launching the docker and executing the following command inside the docker. It mounts your current working directory as /work inside the docker and changes to the /work directory before running the command so it appears seemless.

Note: If you run the setup or build commands using the docker and then forget the docker commands the next time, you will get a lot of errors since the path to the meta layers will have changed. If you get stuck, you may need to delete the build directory and start again, though usually retrying with the docker command again is sufficient.

• Download the oe-layersetup repo
  

  git clone https://support.criticallink.com/git/oe-layersetup.git
  cd oe-layersetup
  

• Run the setup script to download any necessary tools and to sync the meta-layers, which will be stored in the sources directory.
  

  ./docker-poky.sh ./62x-setup.sh # Please use ./62ax-setup.sh for the MitySOM-AM62A module
  

The above steps don't need to be run for every build

Building the Filesystem Images¶

Run the build script:

./docker-poky.sh ./62x-build.sh # Please use ./62ax-build.sh for the MitySOM-AM62A module

By default, {62x,62ax}-build.sh script builds two filesystem images: tisdk-base-image tisdk-default-image. Filesystem images describe the software that is included in the filesystem. The default image defined by TI is a good target for your first build and the base image is good if you don't need a lot of tools and want a minimal filesystem. For the MitySOM-AM62A build, the build script builds the tisdk-edgeai-image instead of the tisdk-default-image. The EdgeAI image includes multiple demos and test utilities that are directly related to MitySOM-AM62A features.

Note: The build and setup scripts are simple wrappers around the steps needed for the build, it is expected that you familiarize yourself with the commands they are running as you may need to tweak them during your development. As well as knowing how to run the bitbake command yourself will speed up development when you need to diagnose build failures.

Collecting the Outputs¶

After you run these commands successfully, the various binaries will be in the build/deploy-ti/images/mitysom-am62x/ directory (note that the MitySOM-AM62A ouputs will be in mitysom-am62ax directory).

The outputs include:

• U-Boot files (e.g. u-boot.img, u-boot-spl.bin, tiboot3.bin, tispl.bin)
• Kernel files (e.g. modules, devicetree, kernel binary)
• Filesystem files (e.g. tisdk-base-image-mitysom-am62x-*.rootfs.tar.xz)
• SD Card Images (e.g. tisdk-base-image-mitysom-am62x.wic)

Note that the TI SDK Toolchain (and installable .sh file, e.g. arago-2021.09-aarch64-linux-tisdk.sh) can be found in build/deploy-ti/sdk/.

Manually Setting Up Yocto Environment¶

To build individual packages within Yocto, enter Docker and setup the build environment:

./docker-poky.sh bash
export MACHINE=mitysom-am62x # Or MACHINE=mitysom-am62ax
pushd build
source conf/setenv
bitbake <package>

(please note that the first few lines that setup the build environment are copied from the 62x-build.sh script)

Troubleshooting¶

Fedora Linux¶

Users running Fedora will need to install docker and add their username to the docker group. You may need to logout and log back into your account to receive your new permissions in the docker group.

sudo dnf install docker
sudo usermod -aG docker username

A Note about Yocto Errors¶

A full Yocto build will stress your CPU, RAM, and disk space. This can sometimes cause errors that are difficult to troubleshoot.

If you get an error in a recipe that you did not modify, and you are certain there is not a RAM or disk space problem, you can usually clear the offending error by running the build command again.

If the error persists, you can try building the package independently. For example:

... <Various status and output from each recipe> ...
NOTE: recipe vlib-c66x-3_2_1_0-r0: task do_populate_lic: Started
WARNING: vlib-c66x-3_2_1_0-r0 do_populate_lic: Could not copy license file /work/build/arago-tmp-external-arm-toolchain/work/armv7at2hf-neon-linux-gnueabi/vlib-c66x/3_2_1_0-r0/vlib_c66x_3_2_1_0/docs/VLIB_Software_Manifest.html to /work/build/arago-tmp-external-arm-toolchain/work/armv7at2hf-neon-linux-gnueabi/vlib-c66x/3_2_1_0-r0/license-destdir/vlib-c66x/VLIB_Software_Manifest.html: [Errno 2] No such file or directory: '/work/build/arago-tmp-external-arm-toolchain/work/armv7at2hf-neon-linux-gnueabi/vlib-c66x/3_2_1_0-r0/vlib_c66x_3_2_1_0/docs/VLIB_Software_Manifest.html'
ERROR: vlib-c66x-3_2_1_0-r0 do_populate_lic: QA Issue: vlib-c66x: LIC_FILES_CHKSUM points to an invalid file: /work/build/arago-tmp-external-arm-toolchain/work/armv7at2hf-neon-linux-gnueabi/vlib-c66x/3_2_1_0-r0/vlib_c66x_3_2_1_0/docs/VLIB_Software_Manifest.html [license-checksum]
ERROR: vlib-c66x-3_2_1_0-r0 do_populate_lic: Fatal QA errors found, failing task.
ERROR: vlib-c66x-3_2_1_0-r0 do_populate_lic: Function failed: populate_lic_qa_checksum
ERROR: Logfile of failure stored in: /work/build/arago-tmp-external-arm-toolchain/work/armv7at2hf-neon-linux-gnueabi/vlib-c66x/3_2_1_0-r0/temp/log.do_populate_lic.32041
NOTE: recipe vlib-c66x-3_2_1_0-r0: task do_populate_lic: Failed
ERROR: Task (/work/sources/meta-ti/recipes-ti/vlib/vlib-c66x_3.2.1.0.bb:do_populate_lic) failed with exit code '1'

In this case, the build was stopped due to an error in the vlib-c66x-3_2_1_0-r0. The error is complaining that it can't find "VLIB_Software_Manifest.html." Instead of just restarting the build, you can run the following commands to reset the vlib-c66x recipe and build it independently (Yocto setup):

bitbake -c cleansstate vlib-c66x
bitbake vlib-c66x
exit

(please note that the first few lines that setup the build environment are copied from the 62x-build.sh script)

If that succeeds, the result will be cached and you can re-run the build command (./docker-poky.sh ./62x-build.sh ) after you exit the docker image.

Packages that seem to fail frequently: vlib-c66x, vulkan-cts, opengl*, nodejs*