githubmirror/devicetree-specification

source/chapter6-source-language.rst
258 строк6 KB
Grant Likely
Trivial: Add SPDX tags to source files
17 сен 2020, 17:14
17 сен 2020, 17:14283a190
.. SPDX-License-Identifier: Apache-2.0

.. _chapter-devicetree-source-format:

Devicetree Source (DTS) Format (version 1)
================================================

The Devicetree Source (DTS) format is a textual representation of a
devicetree in a form that can be processed by dtc into a binary
devicetree in the form expected by the kernel. The following description is
not a formal syntax definition of DTS, but describes the basic
constructs used to represent devicetrees.

The name of DTS files should end with ".dts".

Compiler directives
-------------------

Other source files can be included from a DTS file.  The name of include
files should end with ".dtsi".  Included files can in turn include
additional files.

::

    /include/ "FILE"

Labels
------

The source format allows labels to be attached to any node or property value in the devicetree.
Phandle and path references can be automatically generated by referencing a label instead of
explicitly specifying a phandle value or the full path to a node.
Labels are only used in the devicetree source format and are not encoded into the DTB binary.

A label shall be between 1 to 31 characters in length,
be composed only of the characters in the set :numref:`label-characters`,
and must not start with a number.

Labels are created by appending a colon (':') to the label name.
References are created by prefixing the label name with an ampersand ('&').

.. tabularcolumns:: | c p{8cm} |
.. _label-characters:
.. table:: Valid characters for DTS labels

   ========= ================
   Character Description
   ========= ================
   ``0-9``   digit
   ``a-z``   lowercase letter
   ``A-Z``   uppercase letter
   ``_``     underscore
   ========= ================

Node and property definitions
-----------------------------

Devicetree nodes are defined with a node name and unit address with
braces marking the start and end of the node definition. They may be
preceded by a label.

::

    [label:] node-name[@unit-address] {
        [properties definitions]
        [child nodes]
    };

Nodes may contain property definitions and/or child node definitions. If
both are present, properties shall come before child nodes.

Previously defined nodes may be deleted.

::

    /delete-node/ node-name;
    /delete-node/ &label;

Property definitions are name value pairs in the form:

::

        [label:] property-name = value;

except for properties with empty (zero length) value which have the
form:

::

        [label:] property-name;

Previously defined properties may be deleted.

::

    /delete-property/ property-name;

Property values may be defined as an array of 32-bit integer cells, as
null-terminated strings, as bytestrings or a combination of these.

-  Arrays of cells are represented by angle brackets surrounding a space
   separated list of C-style integers. Example:

::

        interrupts = <17 0xc>;

-  values may be represented as arithmetic, bitwise, or logical expressions
   within parenthesis.

::

    Arithmetic operators

    +   add
    -   subtract
    *   multiply
    /   divide
    %   modulo

::

    Bitwise operators

    &    and
    |    or
    ^    exclusive or
    ~    not
    <<  left shift
    >>  right shift

::

    Logical operators

    &&   and
    ||   or
    !    not

::

    Relational operators

    <    less than
    >    greater than
    <=   less than or equal
    >=   greater than or equal
    ==   equal
    !=   not equal

::

    Ternary operators

    ?:   (condition ? value_if_true : value_if_false)

-  A 64-bit value is represented with two 32-bit cells. Example:

::

        clock-frequency = <0x00000001 0x00000000>;

-  A null-terminated string value is represented using double quotes
   (the property value is considered to include the terminating NULL
   character). Example:

::

        compatible = "simple-bus";

-  A bytestring is enclosed in square brackets [ ] with each byte
   represented by two hexadecimal digits. Spaces between each byte are
   optional. Example:

::

        local-mac-address = [00 00 12 34 56 78];

or equivalently:

::

        local-mac-address = [000012345678];

-  Values may have several comma-separated components, which are
   concatenated together. Example:

::

        compatible = "ns16550", "ns8250";
        example = <0xf00f0000 19>, "a strange property format";

-  In a cell array a reference to another node will be expanded to that
   node’s phandle. References may be & followed by a node’s label.
   Example:

::

        interrupt-parent = < &mpic >;

or they may be & followed by a node’s full path in braces. Example:

::

        interrupt-parent = < &{/soc/interrupt-controller@40000} >;

-  Outside a cell array, a reference to another node will be expanded to
   that node’s full path. Example:

::

        ethernet0 = &EMAC0;

-  Labels may also appear before or after any component of a property
   value, or between cells of a cell array, or between bytes of a
   bytestring. Examples:

::

        reg = reglabel: <0 sizelabel: 0x1000000>;
        prop = [ab cd ef byte4: 00 ff fe];
        str = start: "string value" end: ;

File layout
-----------

**Version 1 DTS files have the overall layout:**

::

    /dts-v1/;
    [memory reservations]
        / {
            [property definitions]
            [child nodes]
        };

``/dts-v1/;`` shall be present to identify the file as a version 1 DTS
(dts files without this tag will be treated by dtc as being in the
obsolete version 0, which uses a different format for integers in
addition to other small but incompatible changes).

Memory reservations (see :numref:`sect-fdt-memory-reservation-block`)
are represented by lines in the form::

   /memreserve/ <address> <length>;

Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g.,

.. code-block:: dts

   /* Reserve memory region 0x10000000..0x10003fff */
   /memreserve/ 0x10000000 0x4000;

The ``/ { ... };`` section defines the root node of the devicetree, and
all the device tree data is contained within it.

C style (``/* ... \*/``) and C++ style (``//``) comments are supported.