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, build, and deploy a device tree overlay

The instructions to create, build, and deploy a device tree overlay are the same ones as to create a regular device tree, with the only difference of the extension of the files. Device tree overlays source files have the extension .dtso, and the blobs (to include in the Makefile), the extension .dtbo.

Follow the instructions at Create your board device tree to create your device tree overlay.

Follow the instructions at Deploy kernel and/or device tree to deploy your device tree overlay.

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: myplatform-functionality.dtbo

  2. Let the target boot the default boot script or 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.