|
|
| Line 18: |
Line 18: |
| == Device Tree Source (DTS) basics == | | == Device Tree Source (DTS) basics == |
|
| |
|
| Here is a very simple DTS file to explain the basics of what you might see in a device tree source file:
| | The following is a simple DTS file to demonstrate the DTS syntax. For a more in-depth syntax guide, see [[Devicetree/DTS syntax]]. |
|
| |
|
| {{SyntaxHighlight header|foo.dts}} | | {{SyntaxHighlight header|foo.dts}} |
| Line 52: |
Line 52: |
| }; | | }; |
| }; | | }; |
| };
| |
| </syntaxhighlight>
| |
|
| |
| In this example, we define an empty DTS; in its root node (<code>/</code>), we place three nodes: a node named "node1" with a label "my_node" at address 0x1000, a node named "node2" at address 0x2000, and a node named "i2c-controller" at address 0x3000.
| |
|
| |
| A node contains:
| |
| * A <code>compatible</code> value (here <code>"vendor,foo"</code>). This specifies what kind of component it is; Linux uses this information to load the correct driver.
| |
| * A <code>reg</code> value. In this case, the first parameter is the base address in memory (<code>0x1000</code>), and the second is the size it occupies (<code>0x54</code>). The amount of cells for the address and size are specified by the <code>#address-cells</code> and <code>#size-cells</code> properties of the root node, respectively.
| |
| ** You might notice that the i2c-controller node defines another set of these <code>#address-cells</code> and <code>#size-cells</code> properties - this is because I2C devices contain their own subdevices with addresses ranging from 0x08 to 0x7f (todo verify), and they do not use a size.
| |
| * A custom vendor-specific property, <code>vendor,bar-factor</code>, which takes a number.
| |
|
| |
| On node 2 there is also a property, <code>vendor,baz-companion</code>, which takes a pointer to another node - here the one we labeled "my_node".
| |
|
| |
| === Inclusion ===
| |
|
| |
| Very often you'll see <code>#include</code> directives; these can either include header files (which usually contain constants defined with <code>#define</code>, similarly to C) or other DTSes. DTS files meant for inclusion are called '''DTS includes''' and use the '''.dtsi''' file extension.
| |
|
| |
| Usually, an SoC will have a common DTS include with all of the relevant nodes for that SoC. A board's DTS will then include the SoC DTSI.
| |
|
| |
| As an example, here's a very bare-bones DTSI for a fictional "FOO1234" SoC:
| |
|
| |
| {{SyntaxHighlight header|foo1234.dtsi}}
| |
| <syntaxhighlight lang="dts" line>
| |
| /*
| |
| * Common DTSI for Foobar FOO1234 System-on-a-Chip.
| |
| */
| |
| /dts-v1/;
| |
|
| |
| / {
| |
| #address-cells = <1>;
| |
| #size-cells = <1>;
| |
|
| |
| cpus {
| |
| #address-cells = <1>;
| |
| #size-cells = <0>;
| |
|
| |
| cpu0: cpu@0 {
| |
| device_type = "cpu";
| |
| compatible = "arm,cortex-a7";
| |
| reg = <0>;
| |
| clock-frequency = <1000000000>;
| |
| };
| |
| };
| |
|
| |
| soc {
| |
| /* ... */
| |
|
| |
| i2c1: i2c@3000 {
| |
| compatible = "vendor,foobar-i2c";
| |
| reg = <0x3000 0x800>;
| |
| status = "disabled";
| |
| };
| |
|
| |
| i2c2: i2c@4000 {
| |
| compatible = "vendor,foobar-i2c";
| |
| reg = <0x4000 0x800>;
| |
| status = "disabled";
| |
| };
| |
|
| |
| i2c3: i2c@5000 {
| |
| compatible = "vendor,foobar-i2c";
| |
| reg = <0x5000 0x800>;
| |
| status = "disabled";
| |
| };
| |
|
| |
| /* ... */
| |
| };
| |
| };
| |
| </syntaxhighlight>
| |
|
| |
| Here is a DTS for a fictional device named "Quox Haystack" that uses the FOO1234 SoC:
| |
|
| |
| {{SyntaxHighlight header|foo1234-quox-haystack.dts}}
| |
| <syntaxhighlight lang="dts" line>
| |
| /*
| |
| * Device tree source for Quox Haystack based on FOO1234 SoC
| |
| */
| |
| /dts-v1/;
| |
|
| |
| #include "foo1234.dtsi"
| |
|
| |
| / {
| |
| compatible = "quox,haystack", "foobar,foo1234";
| |
|
| |
| memory@80000000 {
| |
| device_type = "memory";
| |
| reg = <0x80000000 0x40000000>;
| |
| };
| |
| };
| |
|
| |
| &i2c1 {
| |
| clock-frequency = <400000>;
| |
| status = "okay";
| |
|
| |
| sensor@10 {
| |
| compatible = "foobar,baz-sensor";
| |
| reg = <0x10>;
| |
| };
| |
| };
| |
| </syntaxhighlight>
| |
|
| |
| Some interesting things to look out for:
| |
|
| |
| * The board DTS includes the SoC DTSI with a <code>#include "foo1234.dtsi"</code> directive.
| |
| * We re-define the root <code>/</code> node, and inside of it we place a <code>memory</code> node. This node, as well as the <code>compatible</code>, will be merged into the root node of the included DTSI.
| |
| * Outside of the root node, there is a node with a name starting with an ampersand (<code>&i2c1</code>); this signifies a pointer to a labeled node (see node labels in the previous example). Like with the root node above, the contents of this node will be merged with the contents of the node with this label in the SoC DTSI.
| |
| ** A similar effect could be achieved by overriding the <code>i2c1</code> node under the root node, where it's located in the SoC DTSI (though the preferred way is to do it with a label - we do it here for demonstration purposes):
| |
| *: {{SyntaxHighlight header|foo1234-quox-haystack.dts}}<syntaxhighlight lang="dts" line start="3">
| |
| / {
| |
| compatible = "quox,haystack", "foobar,foo1234";
| |
|
| |
| /* ... */
| |
|
| |
| i2c1: i2c@3000 {
| |
| clock-frequency = <400000>;
| |
| status = "okay";
| |
|
| |
| sensor@10 {
| |
| compatible = "foobar,baz-sensor";
| |
| reg = <0x10>;
| |
| };
| |
| };
| |
| };
| |
| </syntaxhighlight>
| |
|
| |
| For a more visual example - the merged version of these two files would look something like this:
| |
|
| |
| <syntaxhighlight lang="dts" line>
| |
| /dts-v1/;
| |
|
| |
| / {
| |
| #address-cells = <1>;
| |
| #size-cells = <1>;
| |
|
| |
| compatible = "quox,haystack", "foobar,foo1234";
| |
|
| |
| memory@80000000 {
| |
| device_type = "memory";
| |
| reg = <0x80000000 0x40000000>;
| |
| };
| |
|
| |
| cpus {
| |
| #address-cells = <1>;
| |
| #size-cells = <0>;
| |
|
| |
| cpu0: cpu@0 {
| |
| device_type = "cpu";
| |
| compatible = "arm,cortex-a7";
| |
| reg = <0>;
| |
| clock-frequency = <1000000000>;
| |
| };
| |
| };
| |
|
| |
| soc {
| |
| /* ... */
| |
|
| |
| i2c1: i2c@3000 {
| |
| compatible = "vendor,foobar-i2c";
| |
| reg = <0x3000 0x800>;
| |
| clock-frequency = <400000>;
| |
| status = "okay";
| |
|
| |
| sensor@10 {
| |
| compatible = "foobar,baz-sensor";
| |
| reg = <0x10>;
| |
| };
| |
| };
| |
|
| |
| i2c2: i2c@4000 {
| |
| compatible = "vendor,foobar-i2c";
| |
| reg = <0x4000 0x800>;
| |
| status = "disabled";
| |
| };
| |
|
| |
| i2c3: i2c@5000 {
| |
| compatible = "vendor,foobar-i2c";
| |
| reg = <0x5000 0x800>;
| |
| status = "disabled";
| |
| };
| |
|
| |
| /* ... */
| |
| };
| |
| }; | | }; |
| </syntaxhighlight> | | </syntaxhighlight> |