• The BSP default image was built according to the Quickstart BSP instructions for the desired module. Please visit the corresponding module documentation in this wiki.
• A custom Yocto layer (meta-custom in this guide) was created and added to conf/bblayers.conf as shown in the Yocto Build System guide which can be found in the How-To section in the corresponding module documentation.

../fitImage#conf-<base-devicetree>.dtb#conf-<base-devicetree>-<name>.dtbo

The overlay is a device tree overlay source (.dtso) that is added to the kernels device tree directory and compiled into a .dtbo.

For a first test it is good practice to use a “do-nothing” overlay with a marker node. This changes no hardware, but adds a identifiable node so you can prove afterwards that the overlay was applied.

Create the overlay source arch/arm64/boot/dts/ti/<base-devicetree>-test-noop.dtso:

/dts-v1/;
/plugin/;

/ {
	fragment@0 {
		target-path = "/";
		__overlay__ {
			tq-overlay-smoketest {
				compatible = "tq,overlay-smoketest";
				status = "okay";
			};
		};
	};
};

The kernel only builds an overlay if it is referenced from the device tree Makefile in the same directory. The convention used by the BSP is the kbuild overlay merge pattern. A <name>-dtbs := assignment declares the base device tree and the overlay as components and the merged device tree is added to dtb. Add the following to arch/arm64/boot/dts/ti/Makefile, next to the existing <base-devicetree>-* entries so it inherits the same Kconfig guard (make sure to add it to the section containing the dtb and dtbo files of the selected module).

Into the block with the *-dtbs := assignments:

<base-devicetree>-test-noop-dtbs := \
	<base-devicetree>.dtb <base-devicetree>-test-noop.dtbo

Into the block with the dtb-$(CONFIG_…) += lines (the merged .dtb, not the .dtbo):

dtb-$(CONFIG_ARCH_K3) += <base-devicetree>-test-noop.dtb

Packing the compiled .dtbo into the fitImage is controlled by KERNEL_DEVICETREE. Extend it in a kernel .bbappend in your custom layer.

Create meta-custom/recipes-kernel/linux/linux-ti-tq_%.bbappend:

KERNEL_DEVICETREE:append = " ti/<base-devicetree>-test-noop.dtbo"

This adds the configuration conf-<base-devicetree>-test-noop.dtbo to the fitImage.

A new boot menu entry is added by extending the tq-extlinux recipe. Create meta-custom/recipes-core/tq-bootconf/tq-extlinux.bbappend:

UBOOT_EXTLINUX_LABELS:append = " test-noop"
UBOOT_EXTLINUX_KERNEL_IMAGE_test-noop = "../fitImage#conf-<base-devicetree>.dtb#conf-<base-devicetree>-test-noop.dtbo"
UBOOT_EXTLINUX_MENU_DESCRIPTION_test-noop = "${DISTRO_NAME} on ${MACHINE} (overlay smoke test)"

To stack several overlays in one entry, append further #conf-<base-devicetree>-<name>.dtbo segments to the KERNEL_IMAGE line.

Initialize the build environment as described in the Quickstart BSP guide, then rebuild. The debug image is used here because reading the device tree later requires a console login.

cd ~/workspace/ci-meta-tq
source setup-environment <build-dir>
bitbake tq-image-weston-debug

Before flashing, confirm that the configuration was added. dumpimage is part of u-boot-tools:

dumpimage -l deploy-ti/images/<machine>/fitImage | grep test-noop

You should see both an fdt-<base-devicetree>-test-noop.dtbo image and a conf-<base-devicetree>-test-noop.dtbo configuration.

Write the image to an SD card and boot the target. During boot, U-Boot shows the boot menu including your new entry. For testing purposes, select it interactively.

The base device tree does not contain the marker node so its presence in the live device tree proves that the overlay was applied:

cat /proc/device-tree/tq-overlay-smoketest/compatible; echo
cat /proc/device-tree/tq-overlay-smoketest/status; echo

Expected output is tq,overlay-smoketest and okay. /proc/device-tree is a symlink to /sys/firmware/devicetree/base → the merged tree U-Boot handed to the kernel.