device tree summary

// Typically dts files are compiled using a makefile which will run them
// through the C Preprocessor, which means you can use things like #include
// and #define just like in C.  Include files use the suffix .dtsi, except that
// include files that only contain constants/macros for the c preprocessor are
// sometimes given the .h suffix.

// Required at the top of a top-level device-tree source (dts).
// Never present in an include-file (dtsi).
/dts-v1/;

// The device tree is a datastructure very similar to a filesystem, except
// directories are called "nodes" and files are called "properties".  You can
// actually inspect a filesystem-representation of the current device-tree
// in /proc/device-tree.


// A device-tree source file consists of fragments that modify the content of
// some existing node by adding, changing, or deleting properties and/or child
// nodes, thus incrementally building the final device tree.

// Modify the root node:
/ {
    // Add or replace a property:
    some-property = "some value";

    // Add or modify a child node:
    some-node {
        some-property = "another value";

        // You can give a node a global label to reference it from
        // anywhere in the dts.  Unlike node names, a label must be a
        // valid C identifier.
        some_global_label: another-node {
        };
    };
    // Don't forget the semicolon after each block!
};

// Modify an existing node referenced by path:
&{/some-node/another-node} {
    // An empty property (i.e. one whose value consists of no bytes)
    // can be created like this.  This is useful since booleans are
    // typically represented by the presence or absence of a property.
    some-bool;

    // Within a node block, child nodes have to come *after* the property
    // declarations (if any).  You cannot intersperse the two.
    foo {
    };
};

// Modify an existing node referenced by label:
&some_global_label {
    // You can also delete previously declared properties or child nodes,
    // but beware that this doesn't work in overlays:
    /delete-property/ some-bool;

    /delete-node/ foo;
};


/ {
    // The value of a property is ultimately just an array of bytes (just
    // like the contents of a file), but the device tree source format lets
    // you specify them in a variety of ways.
    //
    // The property value is a comma-separated list of items (which are
    // simply concatenated), each of which is one of:
    //
    //  "..."       C-string
    //  [...]       bytes in hex format (whitespace ignored)
    //  /bits/ N <...>  array of N-bit integers (N = 8, 16, 32, 64)
    //  <...>       array of 32-bit integers
    //  &foo        full path of labeled node as C-string
    //
    // Array contents (inside the <>) is a whitespace-separated list of
    // values, each of which is one of:
    //
    //  123     decimal integer
    //  0x123       hexadecimal integer
    //  &foo        phandle of labeled node
    //  &{/path}    phandle of node at given path
    //  (...)       expression
    //
    // Integers are encoded in big-endian format.

    // The following properties all have the same (empty) value:
    property-0-0;
    property-0-1 = <>;
    property-0-2 = [];

    // The following properties all have the same 8-byte value:
    property-1-0 = "foo", "bar";
    property-1-1 = "foo", [62 61 72], "";
    property-1-2 = [66 6f 6f 00], [62 61 72 00];
    property-1-3 = [66 6f 6f 00 62 61 72 00];
    property-1-4 = <0x666f6f00>, <0x62617200>;
    property-1-5 = <0x666f6f00 0x62617200>;
    property-1-6 = /bits/ 32 <0x666f6f00 0x62617200>;
    property-1-7 = /bits/ 64 <0x666f6f0062617200>;
    property-1-8 = /bits/ 64 <( 0x666f6f << 40 | 0x626172 << 8 )>;
    property-1-9 = /bits/ 8 <0x66 0x6f 0x6f 0
                             0x62 0x61 0x72 0>;
};


#include "gpio.h"
#include "irq.h"

/ {
    // plumbing devices together -- i.e. how to reference interrupts,
    // gpios, and other types of resources a device might expose.

    // NOTE: "cell" means (32-bit) word.

    gpio0: my-gpio-controller {
        // indicate this device is a gpio controller.
        gpio-controller;
        // gpios of this controller need 2 words to describe them
        #gpio-cells = <2>;  // gpio-index, gpio-flags

        // it is also an interrupt controller
        interrupt-controller;
        #interrupt-cells = <2>; // gpio-index, irq-flags

        // (I have no clue why gpio- and interrupt-controllers need to
        // be marked as such with boolean properties.  This isn't the
        // case for other stuff.)

        // it is also a pwm controller
        #pwm-cells = <3>;   // gpio-index, period, pwm-flags
    };

    my-needy-device {
        // each gpio spec consists of:
        // 1. a reference to a gpio controller node
        // 2. as many additional words as indicated in the gpio
        //    controller's #gpio-cells property.
        enable-gpios = <&gpio0 0 ACTIVE_HIGH>;
        reset-gpios = <&gpio0 1 ACTIVE_HIGH>;
        // even if only one gpio is allowed in each of these properties
        // it is conventional to still use "gpios" rather than "gpio"
        // in the property name.

        // pwms is similar, but uses a different convention for naming
        pwms = <&gpio0 2 50000 0>, <&gpio0 3 50000 0>;
        pwm-names = "backlight", "frontlight";
        // using pwm-names seems to be relatively rare.

        // interrupts has some history, and traditionally uses a
        // different property for the controller and its arguments:
        interrupt-parent = <&gpio0>;  // inherited from parent if not specified
        interrupts = <4 IRQ_TYPE_EDGE_FALLING>,
                     <5 IRQ_TYPE_EDGE_FALLING>;
        // which implies that all irqs of the device have to use the
        // same irq controller.   nowadays you can replace it with
        interrupts-extended = <&gpio0 4 IRQ_TYPE_EDGE_FALLING>,
                              <&gpio0 5 IRQ_TYPE_EDGE_FALLING>;
        // and as usual you can name interrupts
        interrupt-names = "rx", "tx";
    };
};