Difference between revisions of "Device Tree Source Undocumented"
(→conditional node compilation: add initial content to the section) |
m (: typo: s/explaination/explanation/) |
||
(6 intermediate revisions by the same user not shown) | |||
Line 14: | Line 14: | ||
Note that no whitespace is allowed between '{' and '}'. | Note that no whitespace is allowed between '{' and '}'. | ||
− | For a more complete | + | For a more complete explanation of how this is used, see |
[[Device_Tree_Mysteries#explain_some_more]]. | [[Device_Tree_Mysteries#explain_some_more]]. | ||
Line 22: | Line 22: | ||
Properties can be deleted with the /delete-property/ directive. | Properties can be deleted with the /delete-property/ directive. | ||
+ | |||
+ | '''Deletes in overlays''' | ||
+ | |||
+ | If a delete is specified in an overlay source file, the delete only | ||
+ | impacts the files compiled in association with the overlay source | ||
+ | file. The delete does not result in an opcode in the resulting | ||
+ | .dtb, thus '''applying the overlay will not delete the node or''' | ||
+ | '''property in the base tree'''. | ||
Examples of syntax in a source file and resulting output from dtc are: | Examples of syntax in a source file and resulting output from dtc are: | ||
<pre> | <pre> | ||
− | $ cat | + | $ cat test_delete_syntax_A.dts |
/dts-v1/; | /dts-v1/; | ||
Line 71: | Line 79: | ||
/delete-node/ &node_5_label; | /delete-node/ &node_5_label; | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
Line 102: | Line 101: | ||
<pre> | <pre> | ||
− | $ cat | + | $ cat test_delete_syntax_B.dts |
/dts-v1/; | /dts-v1/; | ||
Line 147: | Line 146: | ||
/delete-node/ &node_5_label; | /delete-node/ &node_5_label; | ||
+ | |||
+ | / { | ||
+ | |||
+ | node-4@4 { | ||
+ | node-4-pc = "stu"; | ||
+ | node-4-pd = "vwx"; | ||
+ | }; | ||
+ | |||
+ | }; | ||
Line 188: | Line 196: | ||
The node names that begin with an underscore should be considered | The node names that begin with an underscore should be considered | ||
− | to be internal implentation of overlay information | + | to be internal implentation of overlay information <s>and should not |
− | be hand coded in a dts source file. They | + | be hand coded</s> Do not hand code node names that begin with an |
+ | underscore in a dts source file. They will be automatically | ||
generated by the dtc compiler. | generated by the dtc compiler. | ||
− | Some of them do currently appear in dts source files since the | + | <s>Some of them do currently appear in dts source files since the |
dtc compiler has not fully implemented the features needed to | dtc compiler has not fully implemented the features needed to | ||
− | avoid the hand coding. | + | avoid the hand coding.</s> |
− | + | The overlay related syntax requires | |
the dtc compiler in Linux 4.12 or later, with the "-@" option. | the dtc compiler in Linux 4.12 or later, with the "-@" option. | ||
− | + | In the future, dtc may be modified to disallow node names | |
− | + | beginning with an underscore in device tree source files, | |
− | + | or possibly use a command line flag to allow or disallow | |
− | + | node names beginning with an underscore. | |
− | |||
− | in device tree source | ||
− | |||
− | beginning with an underscore | ||
== conditional node compilation == | == conditional node compilation == | ||
Line 246: | Line 251: | ||
Resulting trimmed devicetree: | Resulting trimmed devicetree: | ||
− | $dtc -O dts tests/omit-no-ref.dts | + | $ dtc -O dts tests/omit-no-ref.dts |
/dts-v1/; | /dts-v1/; | ||
Line 268: | Line 273: | ||
commit 4038fd90056e81f9a9dc107570431e4e20e526bd | commit 4038fd90056e81f9a9dc107570431e4e20e526bd | ||
− | |||
Date: Thu May 3 22:27:26 2018 +0200 | Date: Thu May 3 22:27:26 2018 +0200 | ||
Latest revision as of 13:32, 18 February 2021
Contents
< &{/path/to/node} >
A phandle reference does not require a label on the target node. An example of referring to a node directly is
interrupt-parent = < &{/soc/pic@10000000} >;
Note that no whitespace is allowed between '{' and '}'.
For a more complete explanation of how this is used, see Device_Tree_Mysteries#explain_some_more.
Deleting nodes and properties
Node can be deleted with the /delete-node/ directive.
Properties can be deleted with the /delete-property/ directive.
Deletes in overlays
If a delete is specified in an overlay source file, the delete only impacts the files compiled in association with the overlay source file. The delete does not result in an opcode in the resulting .dtb, thus applying the overlay will not delete the node or property in the base tree.
Examples of syntax in a source file and resulting output from dtc are:
$ cat test_delete_syntax_A.dts /dts-v1/; / { node-1@1 { node-1-pa = "abc"; }; node-2@2 { node-2-pa = "def"; }; node-3@3 { node-3-pa = "ghi"; node-3-pb = "jkl"; }; node-4@4 { node-4-pa = "mno"; }; node_5_label: node-5@5 { node-5-pa = "pqr"; }; }; / { node-2@2 { /delete-property/ node-2-pa; }; node-3@3 { /delete-property/ node-3-pa; }; /delete-node/ node-4@4; }; /delete-node/ &node_5_label; $ dtc -O dts test_delete_syntax_A.dts /dts-v1/; / { node-1@1 { node-1-pa = "abc"; }; node-2@2 { }; node-3@3 { node-3-pb = "jkl"; }; };
$ cat test_delete_syntax_B.dts /dts-v1/; / { node-1@1 { node-1-pa = "abc"; }; node-2@2 { node-2-pa = "def"; }; node-3@3 { node-3-pa = "ghi"; node-3-pb = "jkl"; }; node-4@4 { node-4-pa = "mno"; }; node_5_label: node-5@5 { node-5-pa = "pqr"; }; }; / { node-2@2 { /delete-property/ node-2-pa; }; node-3@3 { /delete-property/ node-3-pa; }; /delete-node/ node-4@4; }; /delete-node/ &node_5_label; / { node-4@4 { node-4-pc = "stu"; node-4-pd = "vwx"; }; }; $ dtc -O dts test_delete_syntax_B.dts /dts-v1/; / { node-1@1 { node-1-pa = "abc"; }; node-2@2 { }; node-3@3 { node-3-pb = "jkl"; }; node-4@4 { node-4-pc = "stu"; node-4-pd = "vwx"; }; };
Overlays
Overlay support in the dtc compiler and in the Linux kernel is under development and may change from what appears here.
Things that may be currently visible in out of tree locations are:
Some overlay related syntax is:
- /plugin/ directive
- __overlay__ node
- __symbols__ node
- __fixups__ node
- __local_fixups__ node
The node names that begin with an underscore should be considered
to be internal implentation of overlay information and should not
be hand coded Do not hand code node names that begin with an
underscore in a dts source file. They will be automatically
generated by the dtc compiler.
Some of them do currently appear in dts source files since the
dtc compiler has not fully implemented the features needed to
avoid the hand coding.
The overlay related syntax requires the dtc compiler in Linux 4.12 or later, with the "-@" option.
In the future, dtc may be modified to disallow node names beginning with an underscore in device tree source files, or possibly use a command line flag to allow or disallow node names beginning with an underscore.
conditional node compilation
This feature is not available in the Linux kernel version of dtc as of 4.16. It will probably be present starting in 4.18.
The '/omit-if-no-ref/' keyword is used to inform dtc to delete a node from the output devicetree if there are no references to the node.
Example usage from the dtc testcase tests/omit-no-ref.dts:
/dts-v1/; / { test-phandle = <&node3>; test-path = &node4; /omit-if-no-ref/ node1: node1 { bar = <0xdeadbeef>; }; node2: node2 { foo = <0x42>; }; node3: node3 { test = "test"; }; node4: node4 { test; }; }; /omit-if-no-ref/ &node2; /omit-if-no-ref/ &node3; /omit-if-no-ref/ &node4;
Resulting trimmed devicetree:
$ dtc -O dts tests/omit-no-ref.dts /dts-v1/; / { test-phandle = <0x1>; test-path = "/node4"; node3: node3 { test = "test"; phandle = <0x1>; }; node4: node4 { test; }; };
From the commit message:
commit 4038fd90056e81f9a9dc107570431e4e20e526bd Date: Thu May 3 22:27:26 2018 +0200 dtc: add ability to make nodes conditional on them being referenced A number of platforms have a need to reduce the number of DT nodes, mostly because of two similar constraints: the size of the DT blob, and the time it takes to parse it. As the DT is used in more and more SoCs, and by more projects, some constraints start to appear in bootloaders running from SRAM with an order of magnitude of 10kB. A typical DT is in the same order of magnitude, so any effort to reduce the blob size is welcome in such an environment. Some platforms also want to reach very fast boot time, and the time it takes to parse a typical DT starts to be noticeable. Both of these issues can be mitigated by reducing the number of nodes in the DT. The biggest provider of nodes is usually the pin controller and its subnodes, usually one for each valid pin configuration in a given SoC. Obviously, a single, fixed, set of these nodes will be used by a given board, so we can introduce a node property that will tell the DT compiler to drop the nodes when they are not referenced in the tree, and as such wouldn't be useful in the targetted system.