You can use device tree compiler (DTC) to compile the device tree source (DTS) files. However, before applying the overlay device tree (DT) on the target main DT, you should also verify the result by simulating the behavior of the device tree overlay (DTO).
Compile with DTC
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
Verify DTO results on the host
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
.
Figure 1. Use syntax /include/ to simulate DTO on the host.
- Create a copy of the overlay
.dts
. In the copy, remove the first line header. Example: Save the file as/dts-v1/; /plugin/;
my_overlay_dt_wo_header.dts
(or any filename you want). - Create a copy of the main
.dts
. In the copy, after the last line, append the include syntax for the file you created in step 1. For example: Save the file as/include/ "my_overlay_dt_wo_header.dts"
my_main_dt_with_include.dts
(or any filename you want). - Use
dtc
to compilemy_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
- Use
dtc
to dumpmy_merged_dt.dto
.dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb
Verify DTO in Android 9
Android 9 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.
Indicate applied overlays
To enable the
Vendor Test Suite (VTS) to assess the correctness of overlay
app, vendors must add a new kernel command line parameter
androidboot.dtbo_idx
that indicates the overlays selected from
the DTBO partition. In Android 12 using kernel version
5.10 or greater, this parameter passes through bootconfig.
For example, the parameter androidboot.dtbo_idx=x,y,z
reports
x
, y
and z
as the zero-based indices of
the DTOs from the DTBO partition applied (in that order)
by the bootloader to the base DT.
Overlays can apply to nodes from the main DT or add new nodes, but can't refer to a node added in a previous overlay. This restriction is necessary because the overlay app doesn't merge the overlay symbol table with the main DT symbol table (not merging avoids conflicts in symbol names and complication of dependencies between overlays).
Example: Invalid 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 app fails with an error that the symbol
e
isn't 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>; }; |
Example: Valid overlays
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
app 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>; }; }; |
Implement the DTBO partition
To implement the required DTBO partition, ensure the bootloader can do the following:
- Identify the board it is running on and select the corresponding overlays to be applied.
- Append the
androidboot.dtbo_idx
parameter to the kernel command line.- The parameter must indicate, the zero-based indices of the DTOs from the DTBO partition image it applied to the base DT (in the same order).
- The indices must refer to the position of the overlay in the DTBO partition.
For details on the structure of the DTBO partition, refer to Device tree overlays.
Validate the DTBO partition
You can use VTS to verify the following:
- Existence of the kernel command line parameter
androidboot.dtbo_idx
(by checking thatInit
has automatically set up the correspondingro.boot.dtbo_idx
system property). - Validity of the
ro.boot.dtbo_idx
system property (by checking that the property specifies at least one valid DTBO image index). - Validity of the DTBO partition (also verifies the overlays in the DTBO partition that are applied to the base DT).
- Additional nodes or property changes in the resulting DT are presented to the Linux kernel.
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 doesn't 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"; }; }; |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-12-16 UTC.