Device Tree Source Undocumented

From eLinux.org
Revision as of 18:13, 6 May 2018 by Frowand (talk | contribs) (conditional node compilation: minor formatting fixes)
Jump to: navigation, search


Top Device Tree page

< &{/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 explaination 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.

Examples of syntax in a source file and resulting output from dtc are:

$ 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_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_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_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 in a dts source file. They should 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.

These items require an out of tree dtc compiler the dtc compiler in Linux 4.12 or later, with the "-@" option.

Pantelis Antoniou has created dtc patches to allow "syntax sugar". This syntax allows the device tree source file to contain a reference to a node and dtc automatically creates the __*__ nodes.

If the "syntax sugar" is available, then the need to allow node names in device tree source to begin with an underscore is removed, and hopefully dtc will be further modified to disallow node names beginning with an underscore in device tree source files.

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.