.. 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/
; Where ``
`` and ```` 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.