You can use Device Tree Compiler (DTC) to compile the Device Tree Source files. However, before applying the overlay DT on the target main DT, you should also verify the result by simulating the behavior of DTO.
When using dtc
to compile .dts
, you must add
option -@
to add a __symbols__
node in the
resulting .dtbo
. The __symbols__
node contains a
list of all nodes that are marked with a label, which the DTO library can use
for references.
Sample command to build main DT .dts
:
dtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts
Sample command to build the overlay DT .dts
:
dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts
Verification can help you identify errors that might occur when placing
the overlay DT on the main DT. Before updating the target, you can verify the
result of overlaying DT on the host by simulating the behavior of DTO using
/include/
in .dts
.
/include/
to simulate
DTO on the host.dts
. In the copy, remove the
first line header. Example:
/dts-v1/; /plugin/;Save the file as
my_overlay_dt_wo_header.dts
(or any
filename you want).
.dts
. In the copy, after the
last line, append the include syntax for the file you created in step 1.
For example:
/include/ "my_overlay_dt_wo_header.dts"Save the file as
my_main_dt_with_include.dts
(or any
filename you want).
dtc
to compile
my_main_dt_with_include.dts
to get the merged DT, which should
be the same result as DTO. For example:
dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts
dtc
to dump my_merged_dt.dto
.
dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb
Android {{ androidPVersionNumber}} requires a Device Tree Blob Overlay (DTBO) partition. To add nodes or make changes to the properties in the SoC DT, the bootloader must dynamically overlay a device specific DT over the SoC DT.
To enable the
Vendor Test Suite (VTS) to assess the correctness of overlay
application, vendors must add a new kernel command line parameter
androidboot.dtbo_idx
that indicates the overlays selected from
the DTBO partition. For example, the parameter androidboot.
dtbo_idx=x,y,z
reports x
, y
and
z
as the zero-based indices of the Device Tree Overlays (DTOs)
from the DTBO partition applied (in that order) by the bootloader to the base
Device Tree (DT).
Overlays can apply to nodes from the main device tree or add new nodes, but cannot refer to a node added in a previous overlay. This restriction is necessary because the overlay application does not merge the overlay symbol table with the main DT symbol table (not merging avoids conflicts in symbol names and complication of dependencies between overlays).
In this example, overlay_2.dts
refers to node
e
, which was added by
overlay_1.dts
. After overlay_1
is applied to the
main DT, if an attempt is made to apply overlay_2
to the
resultant DT, the overlay application will fail with an error that the symbol
e
is not present in the symbol table for the
base DT.
main.dts | overlay_1.dts | overlay_2.dts |
---|---|---|
[main.dts] /dts-v1/; / { a: a {}; b: b {}; c: c {}; }; |
[overlay_1.dts] /dts-v1/; /plugin/; &b { ref1 = <&a>; e: e { prop = <0x0a>; phandle = <0x04>; }; }; |
[overlay_2.dts] /dts-v1/; /plugin/; /* invalid! */ &e { prop = <0x0b>; }; |
In this example, overlay_2.dts
refers only to node
b
from the main DTS. When
overlay_1
is applied to the base DT, then followed by the
application of overlay_2
, the value of property
prop
in node e
(set by overlay_1.dts
) is overwritten by the value set by
overlay_2.dts
.
main.dts | overlay_1.dts | overlay_2.dts |
---|---|---|
[final.dts] /dts-v1/; / { a: a {}; b: b {}; c: c {}; }; |
[overlay_1.dts] /dts-v1/; /plugin/; &b { ref1 = <&a>; e { prop = <0x0c>; }; }; |
[overlay_2.dts] /dts-v1/; /plugin/; /* valid */ &b { ref1 = <&c>; e { prop = <0x0d>; }; }; |
To implement the required DTBO partition, ensure the bootloader can do the following:
androidboot.dtbo_idx
parameter to the kernel
command line.
For details on the structure of the DTBO partition, refer to Device Tree Overlays on source.android.com.
You can use VTS to verify the following:
androidboot.dtbo_idx
(by checking that Init
has
automatically set up the corresponding ro.boot.dtbo_idx
system
property).ro.boot.dtbo_idx
system property (by
checking that the property specifies at least one valid DTBO image
index).For example, in the following overlays and final DT, adding
androidboot.dtbo_idx=5,3
to the kernel command line passes
validation but adding androidboot.dtbo_idx=3,5
to the kernel
command line does not pass validation.
Overlay DT at index 3 | Overlay DT at index 5 |
---|---|
[overlay_1.dts] /dts-v1/; /plugin/; &c { prop = <0xfe>; }; |
[overlay_2.dts] /dts-v1/; /plugin/; &c { prop = <0xff>; }; |
Final DT |
---|
/dts-v1/; / { a { phandle = <0x1>; }; b { phandle = <0x2>; }; c { phandle = <0x3>; prop = <0xfe>; }; __symbols__ { a = "/a"; b = "/b"; c = "/c"; }; }; |