This topic explains how to create, build, and deploy a device tree overlay. For an introduction to device tree overlays, see Device tree files and overlays.

Device tree overlays format

A device tree overlay contains modifications that can be applied to an existing device tree blob. The format of device tree overlays is slightly different than the regular .dts and .dtsi files:

Sample device tree overlay
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#include <dt-bindings/gpio/gpio.h>

/dts-v1/;
/plugin/;

/ {
	fragment@0 {
		target-path = "/";
		__overlay__ {
			foo {
				compatible = "custom,foo";
				status = "okay";
				gpio = <&gpio3 14 GPIO_ACTIVE_HIGH>;
			};
		};
	};

	fragment@1 {
		target = <&bar>;
		__overlay__ {
			my-boolean-property;
			status = "okay";
		};
	};
};

Let’s examine the different parts:

Device tree header

#include <dt-bindings/gpio/gpio.h>

/dts-v1/;
/plugin/;

Device tree overlays are built standalone, without any connection to the device tree they will modify. For this reason, they must include headers and specifiers just like a regular device tree file.

Root node and fragments

 6
 7
 8
 9
10
11
12
13
14
15
16
/ {
	fragment@0 {
		[...]
	};

	fragment@1 {
		[...]
	};

	...
};

Device tree overlays must have a root node. Within the root node, you must insert fragments: one fragment for each node of the original device tree that you want to modify.

Structure of a fragment

Fragment with absolute path
 7
 8
 9
10
11
12
13
14
15
16
fragment@0 {
	target-path = "/";
	__overlay__ {
		foo {
			compatible = "custom,foo";
			status = "okay";
			gpio = <&gpio3 14 GPIO_ACTIVE_HIGH>;
		};
	};
};
Fragment with relative path
18
19
20
21
22
23
24
fragment@1 {
	target = <&bar>;
	__overlay__ {
		my-boolean-property;
		status = "okay";
	};
};

Each fragment has two elements:

  • One of these two properties:

    • target-path with the absolute path to the node that the fragment is going to modify, or

    • target with the relative path to the node alias (prefixed with an ampersand symbol) that the fragment is going to modify.

  • A node overlay with the modifications to apply to the referred node. Such modifications can be:

    • New nodes (they are added)

    • New properties (they are added)

    • Existing properties (they are overridden with the new value)

      Overlays can only perform constructive changes such as adding or modifying nodes or properties. They cannot be used to perform destructive changes such as deleting nodes or properties.

In the examples above:

  • fragment@0 is adding the node foo, with several properties, to the root node /.

  • fragment@1 is modifying the node with alias bar, with several properties that can be new or existing ones.

Create the device tree overlay

Create a device tree overlay inside the Linux kernel source tree, where the regular device tree files are located. For ConnectCore 8X this is arch/arm64/boot/dts/digi. In this example, the device tree overlay file name is _ov_custom_foo.dts. For Digi device tree overlay naming conventions, see File naming conventions.

Build the device tree overlay

To have the Linux kernel build the device tree overlay, add it to arch/arm64/boot/dts/digi/Makefile with the extension dtbo:

dtb-y += _ov_custom_foo.dtbo

To have Digi Embedded for Android consider the overlay and include it at file dtbo-imx8x.img image, add the overlay filename to the TARGET_BOARD_DTS_CONFIG variable in the device/digi/imx8q/BoardConfig.mk:

device/digi/imx8q/BoardConfig.mk
[...]
TARGET_BOARD_DTS_CONFIG := \
	ccimx8x-sbc-pro.dtb \
	... \
	_ov_som_bt_ccimx8x.dtbo \
	_ov_som_wifi_ccimx8x.dtbo \
	_ov_custom_foo.dtbo
[...]

Then build the firmware and program it in the module.

For instructions on building the firmware, see Build your development images.

It is highly recommended that you clean the images from previous builds to guarantee that you generate images with the new changes. To do so, issue this command in the root of your Android sources:

$ m installclean

This adds the compiled device tree overlay blob to the dtbo-imx8x.img image, together with the rest of device tree files for the platform.

Deploy the device tree overlay

To deploy the device tree overlay blob to the target, program the DTBO artifact in the corresponding partition.

For instructions on updating the image artifact, see [{XREF_android_t_program-fw}].

Enable the device tree overlay

To use the device tree overlay, perform the following steps in U-Boot:

  1. Add the overlay filename to the comma-separated list in U-Boot variable overlays. (It may be initially empty):

    => env edit overlays
edit: _ov_custom_foo.dtbo

For more information on the Digi device tree overlays mechanism, see Device tree overlays mechanism.