Starting March 27, 2025, we recommend using android-latest-release
instead of aosp-main
to build and contribute to AOSP. For more information, see Changes to AOSP.
DTO syntax
Stay organized with collections
Save and categorize content based on your preferences.
Device tree source (DTS) format is a textual representation of a device tree (DT).
The device tree compiler (DTC) processes this format into a binary DT,
which is the form expected by the Linux kernel.
Use references
The DTC
(device Tree compiler + overlay patches) project describes the DTS format in
dtc-format.txt
and
manual.txt.
DTO format and rules are described in
dt-object-internal.txt.
These documents describe how to update the main DT using node
fragment@x
and syntax __overlay__
in overlay DT. For
example:
/ {
fragment@0 {
target = <&some_node>;
__overlay__ {
some_prop = "okay";
...
};
};
};
However, Google strongly recommends you do not use
fragment@x
and syntax __overlay__
, and instead use the
reference syntax. For example:
&some_node {
some_prop = "okay";
...
};
Reference syntax is compiled by dtc
into the same object as the
above using syntax __overlay__
. This syntax doesn't force you to
number the fragments, enabling you to read and write overlay DTS easily. If your
dtc
doesn't support this syntactic sugar, use the
dtc
in AOSP.
Use labels
To allow undefined references to nodes not present at compilation time, the
overlay DT .dts
file must have a tag /plugin/
in its
header. For example:
/dts-v1/;
/plugin/;
From here you can target the nodes to be overlaid using a reference, which is
an absolute node path prefixed with an ampersand (&). For example, for
node@0
in the main DT:
Define labels in the main DT ... |
... then use the labels. |
[my_main_dt.dts]
/dts-v1/;
/ {
my_node: node@0 {
status = "disabled";
my_child: child@0 {
value = <0xffffffff>;
};
};
};
|
[my_overlay_dt.dts]
/dts-v1/;
/plugin/;
&my_node {
status = "okay";
};
&my_child {
value = <0x1>;
};
|
Override
If the reference target property exists in the main DT, it is overridden
after DTO; otherwise, it is appended. For example:
main.dts |
overlay.dts |
Merged Result |
[my_main_dt.dts]
/dts-v1/;
/ {
compatible = "corp,foo";
my_node: node@0 {
status = "disabled";
};
};
|
[my_overlay_dt.dts]
/dts-v1/;
/plugin/;
&my_node {
status = "okay";
};
|
/dts-v1/;
/ {
compatible = "corp,foo";
...
node@0 {
linux,phandle = <0x1>;
phandle = <0x1>;
status = "okay";
};
};
|
Append
If the reference target property doesn't exist in the main DT, it is
appended after DTO. For example:
main.dts |
overlay.dts |
Merged Result |
[my_main_dt.dts]
/dts-v1/;
/ {
compatible = "corp,foo";
my_node: node@0 {
status = "okay";
};
};
|
[my_overlay_dt.dts]
/dts-v1/;
/plugin/;
&my_node {
new_prop = "bar";
};
|
/dts-v1/;
/ {
compatible = "corp,foo";
...
node@0 {
linux,phandle = <0x1>;
phandle = <0x1>;
status = "okay";
new_prop = "bar";
};
};
|
Child nodes
Examples of child node syntax:
main.dts |
overlay.dts |
Merged Result |
[my_main_dt.dts]
/dts-v1/;
/ {
compatible = "corp,foo";
my_nodes: nodes {
compatible = "corp,bar";
node@0 {
status = "disabled";
};
};
};
|
[my_overlay_dt.dts]
/dts-v1/;
/plugin/;
&my_nodes {
new_prop1 = "abc";
node@0 {
status = "okay";
new_prop2 = "xyz";
};
};
|
/dts-v1/;
/ {
compatible = "corp,foo";
...
nodes {
linux,phandle = <0x1>;
phandle = <0x1>;
compatible = "corp,bar";
new_prop1 = "abc";
node@0 {
linux,phandle = <0x2>;
phandle = <0x2>;
status = "okay";
new_prop2 = "xyz";
};
};
};
|
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 2025-06-18 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-18 UTC."],[],[],null,["# DTO syntax\n\nDevice tree source (DTS) format is a textual representation of a device tree (DT).\nThe device tree compiler (DTC) processes this format into a binary DT,\nwhich is the form expected by the Linux kernel.\n\nUse references\n--------------\n\nThe [DTC](https://github.com/pantoniou/dtc)\n(device Tree compiler + overlay patches) project describes the DTS format in\n[dtc-format.txt](https://android.googlesource.com/platform/external/dtc/+/refs/heads/android16-release/Documentation/dts-format.txt)\nand\n[manual.txt](https://android.googlesource.com/platform/external/dtc/+/refs/heads/android16-release/Documentation/manual.txt).\nDTO format and rules are described in\n[dt-object-internal.txt](https://android.googlesource.com/platform/external/dtc/+/refs/heads/android16-release/Documentation/dt-object-internal.txt).\nThese documents describe how to update the main DT using node\n`fragment@x` and syntax `__overlay__` in overlay DT. For\nexample: \n\n```objective-c\n/ {\n fragment@0 {\n target = \u003c&some_node\u003e;\n __overlay__ {\n some_prop = \"okay\";\n ...\n };\n };\n};\n```\n\nHowever, Google strongly recommends you do **not** use\n`fragment@x` and syntax `__overlay__`, and instead use the\nreference syntax. For example: \n\n```scdoc\n&some_node {\n some_prop = \"okay\";\n ...\n};\n```\n\nReference syntax is compiled by `dtc` into the same object as the\nabove using syntax `__overlay__`. This syntax doesn't force you to\nnumber the fragments, enabling you to read and write overlay DTS easily. If your\n`dtc` doesn't support this syntactic sugar, use the\n[dtc\nin AOSP](https://android.googlesource.com/platform/external/dtc).\n\nUse labels\n----------\n\nTo allow undefined references to nodes not present at compilation time, the\noverlay DT `.dts` file must have a tag `/plugin/` in its\nheader. For example: \n\n```text\n/dts-v1/;\n/plugin/;\n```\n\nFrom here you can target the nodes to be overlaid using a reference, which is\nan absolute node path prefixed with an ampersand (\\&). For example, for\n`node@0` in the main DT:\n\n| Define labels in the main DT ... | ... then use the labels. |\n|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|\n| ```ini [my_main_dt.dts] /dts-v1/; / { my_node: node@0 { status = \"disabled\"; my_child: child@0 { value = \u003c0xffffffff\u003e; }; }; }; ``` | ```ini [my_overlay_dt.dts] /dts-v1/; /plugin/; &my_node { status = \"okay\"; }; &my_child { value = \u003c0x1\u003e; }; ``` |\n\nOverride\n--------\n\nIf the reference target property exists in the main DT, it is overridden\nafter DTO; otherwise, it is appended. For example:\n\n| main.dts | overlay.dts | Merged Result |\n|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|\n| ```ini [my_main_dt.dts] /dts-v1/; / { compatible = \"corp,foo\"; my_node: node@0 { status = \"disabled\"; }; }; ``` | ```ini [my_overlay_dt.dts] /dts-v1/; /plugin/; &my_node { status = \"okay\"; }; ``` | ```objective-c /dts-v1/; / { compatible = \"corp,foo\"; ... node@0 { linux,phandle = \u003c0x1\u003e; phandle = \u003c0x1\u003e; status = \"okay\"; }; }; ``` |\n\nAppend\n------\n\nIf the reference target property doesn't exist in the main DT, it is\nappended after DTO. For example:\n\n| main.dts | overlay.dts | Merged Result |\n|-------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ```ini [my_main_dt.dts] /dts-v1/; / { compatible = \"corp,foo\"; my_node: node@0 { status = \"okay\"; }; }; ``` | ```ini [my_overlay_dt.dts] /dts-v1/; /plugin/; &my_node { new_prop = \"bar\"; }; ``` | ```objective-c /dts-v1/; / { compatible = \"corp,foo\"; ... node@0 { linux,phandle = \u003c0x1\u003e; phandle = \u003c0x1\u003e; status = \"okay\"; new_prop = \"bar\"; }; }; ``` |\n\nChild nodes\n-----------\n\nExamples of child node syntax:\n\n| main.dts | overlay.dts | Merged Result |\n|------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ```ini [my_main_dt.dts] /dts-v1/; / { compatible = \"corp,foo\"; my_nodes: nodes { compatible = \"corp,bar\"; node@0 { status = \"disabled\"; }; }; }; ``` | ```ini [my_overlay_dt.dts] /dts-v1/; /plugin/; &my_nodes { new_prop1 = \"abc\"; node@0 { status = \"okay\"; new_prop2 = \"xyz\"; }; }; ``` | ```objective-c /dts-v1/; / { compatible = \"corp,foo\"; ... nodes { linux,phandle = \u003c0x1\u003e; phandle = \u003c0x1\u003e; compatible = \"corp,bar\"; new_prop1 = \"abc\"; node@0 { linux,phandle = \u003c0x2\u003e; phandle = \u003c0x2\u003e; status = \"okay\"; new_prop2 = \"xyz\"; }; }; }; ``` |"]]