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:
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
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>;
};
};
};
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 nodefoo
, with several properties, to the root node/
. -
fragment@1
is modifying the node with aliasbar
, 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 8M Nano 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:
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.