Create device tree overlays

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 91 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 Yocto consider the overlay as an image artifact worth copying to the deploy directory, add the overlay filename to the KERNEL_DEVICETREE variable in your project’s conf/local.conf file:

conf/local.conf

KERNEL_DEVICETREE:append = " digi/_ov_custom_foo.dtbo"

Note the required white space when appending a value to an array variable using the :append override syntax.

This not only copies the compiled device tree overlay blob to the deploy directory, but it also adds the file to the *.boot.vfat image, together with the rest of device tree files for the platform.

Deploy the device tree overlay

There are two ways to deploy the device tree overlay blob to the target:

Copy the file to the linux partition
Program the full artifact image to the linux partition

Copy the file to the linux partition

From U-Boot

Put the .dtbo file in your TFTP exposed folder. Then use the updatefile command to copy it to the linux partition:

=> updatefile linux tftp _ov_custom_foo.dtbo

From the operating system

On your target, re-mount the linux partition as read-write. (It is mounted as read-only by default.)
```
# mount -o remount,rw /mnt/linux
```
Copy the file from the host to the target inside the re-mounted folder.

Program the image artifact to the linux partition

For instructions on updating the full image artifact, see Program images from U-Boot.

Enable the device tree overlay

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

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
```
Run the dboot command to boot from the eMMC:
```
=> dboot linux mmc
```

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