Yocto Scarthgap 5.0¶

Introduction¶

This guide walks through the process for building Variscite's reference Yocto image from source code. It is derived from TI's guide Overview Building the SDK with Yocto

Installing required packages¶

Note: Variscite provides Docker containers that can be used for a development environment as an alternative to using a virtual machine or a dedicated computer.

To learn more, please see Variscite's Docker Build Environment guide.

If you are using docker, you can skip this section.

Please make sure your host PC is running Ubuntu 22.04 64-bit and is up to date:

 sudo apt-get update && sudo apt-get dist-upgrade

For Ubuntu 22.04 64-bit:

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

sudo apt install python-is-python3

By default Ubuntu uses “dash” as the default shell for /bin/sh. You must reconfigure to use bash by running the following command:

sudo dpkg-reconfigure dash

Be sure to select “No” when you are asked to use dash as the default system shell.

Download Yocto Scarthgap and setup environment¶

Download the latest source code (recommended):

git clone https://github.com/varigit/oe-layersetup ~/var-ti-yocto

or

Download a release tag:

git clone https://github.com/varigit/oe-layersetup ~/var-ti-yocto -b am62-yocto-scarthgap-6.12.57_11.02.08.02-v1.0

Optional: Variscite provides Docker containers that can be used for a development environment as an alternative to using a virtual machine or a dedicated computer.

To learn more, please see Variscite's Docker Build Environment guide.

If you choose to use docker, launch a new container with the host build directory mounted to /workdir/build and the toolchains mounted to the home directory:

cd ~/var-ti-yocto

~/var-host-docker-containers/run.sh  -u 22.04 -w $(pwd)

Follow the remaining steps to build an image, replacing the path ~/var-ti-yocto/build with /workdir/build.

Download the source code dependencies

cd ~/var-ti-yocto
./oe-layertool-setup.sh -f configs/variscite/processor-sdk-scarthgap-chromium-11.02.08.02-config_var01.txt

Next, setup the environment. The above commands are only required for the very first build setup: whenever restarting a newer build session (from a different terminal or in a different time), you can skip the full setup and just run:

cd ~/var-ti-yocto/build
. conf/setenv

Build GUI demo image¶

MACHINE=am62x-var-som bitbake var-default-image

Build GUI demo image with Chromium web browser¶

MACHINE=am62x-var-som bitbake var-chromium-image

Build thin demo image¶

This image is based on var-default-image, but the size is strongly reduced removing the biggest packages (mainly LTP, multimedia, Qt6)

MACHINE=am62x-var-som bitbake var-thin-image

Create a bootable SD card¶

The wic image fully supports booting from an SD card. Use the command below to write it to an SD card:

sudo umount /dev/sdX*
zstdcat deploy-ti/images/am62x-var-som/var-default-image-am62x-var-som.wic.zst | sudo dd of=/dev/sdX bs=1M && sync

Replace sdX with the right device name. This can be obtained by "dmesg" command on your host Linux PC, after the SD card reader is inserted.

NOTE: The wic image does not support all features booting from eMMC. For example, /etc/fw_env.config is configured for the SD card (/dev/mmcblk1)

Create a Recovery SD card¶

As mentioned above, the wic image only supports booting from an SD card. To flash an image to eMMC, Variscite provides an image var-recovery-image, which inherits by default var-default-image and adds the following files needed for installing to eMMC:

/usr/bin/install_yocto.sh
/usr/bin/echos.sh
/opt/images/Yocto/
/opt/images/Yocto/boot
/opt/images/Yocto/boot/u-boot.img
/opt/images/Yocto/boot/tiboot3.bin
/opt/images/Yocto/boot/tispl.bin
/opt/images/Yocto/boot/uEnv.txt
/opt/images/Yocto/rootfs.tar.zst

By default, the image will be named am62_yocto-scarthgap-6.12.57_11.02.08.02-v1.0. It can be overridden adding the RECOVERY_SD_NAME variable to local.conf. For example:

VAR_RECOVERY_SD_NAME = "am62_yocto-scarthgap-6.12.57_11.02.08.02-v1.0"

By default, the recovery image boots and installs var-default-image. To embed a different target eMMC image, for example var-chromium-image, set the following variable in local.conf:

VAR_RECOVERY_TARGET_ROOTFS = "var-chromium-image"
VAR_RECOVERY_SD_IMAGE = "recipes-core/images/var-chromium-image.bb"

Build the image:

MACHINE=am62x-var-som bitbake var-recovery-image

Write it to an SD card:

sudo umount /dev/sdX*

zstdcat deploy-ti/images/am62x-var-som/var-recovery-image-am62x-var-som.wic.zst | sudo dd of=/dev/sdX bs=1M && sync

Or, if the image name was overridden with RECOVERY_SD_NAME:

zstdcat deploy-ti/images/am62x-var-som/am62_yocto-scarthgap-6.12.57_11.02.08.02-v1.0.wic.zst | sudo dd of=/dev/sdX bs=1M && sync

Replace sdX with the right device name. This can be obtained by "dmesg" command on your host Linux PC, after the SD card reader is inserted.

Build the Complete Release Package¶

If you want to generate the same top-level .tar.zst package structure used for Variscite releases, build the var-release-package recipe:

MACHINE=am62x-var-som bitbake var-release-package

This recipe collects the main Yocto deliverables into one package:

Item	Description
Recovery SD image	Bootable recovery image generated by `var-recovery-image`
SWUpdate artifacts	`var-image-swupdate-.rootfs.wic.zst`, `.bmap`, and `var-image-swu-.rootfs.swu`
Compliance/security	SBOM (`.spdx.tar.zst`) and CVE report

The package file name is derived from VAR_RECOVERY_SD_NAME. Overriding this variable also changes the base name of the final release package.

The VAR_RECOVERY_TARGET_ROOTFS variable is also reused here. In addition to selecting which target rootfs is embedded into var-recovery-image.

To be explicit:

VAR_RECOVERY_TARGET_ROOTFS changes the target rootfs used by the recovery SD image.
VAR_RECOVERY_SD_IMAGE changes the image that boots from the SD card.
VAR_RECOVERY_SD_NAME changes the base name used for the recovery image and, consequently, for the final var-release-package archive.

For example, the following configuration in local.conf keeps these roles separate while customizing all three outputs:

VAR_RECOVERY_SD_NAME = "am62_yocto-scarthgap-6.12.57_11.02.08.02-v1.0"
VAR_RECOVERY_SD_IMAGE = "recipes-core/images/var-chromium-image.bb"
VAR_RECOVERY_TARGET_ROOTFS = "var-chromium-image"

After the build completes, the final package is created in tmp/deploy/images/am62x-var-som/ as a .tar.zst archive named after VAR_RECOVERY_SD_NAME.

Recovery SD card and eMMC partition table¶

The Recovery SD card and eMMC partition table is as follows:

Device	Boot	Start (Sectors)	End (Sectors)	Start (MB)	Sectors	Size	Type
/dev/mmcblk1p1	*	2048	83967	1	81920	40	W95 FAT32 (LBA)
U-Boot Env		88064	90111	43	2048	1	U-Boot Raw
/dev/mmcblk1p2		90112	15239167	44	15149056	7397	Linux