Lines Matching +full:dts +full:- +full:bindings
1 .. _dt-syntax:
6 As the name indicates, a devicetree is a tree. The human-readable text format
7 for this tree is called DTS (for devicetree source), and is defined in the
22 Here is an example DTS file:
24 .. code-block:: devicetree
26 /dts-v1/;
29 a-node {
30 subnode_nodelabel: a-sub-node {
36 The ``/dts-v1/;`` line means the file's contents are in version 1 of the DTS
37 syntax, which has replaced a now-obsolete "version 0".
46 #. A node named ``a-node``, which is a child of the root node
47 #. A node named ``a-sub-node``, which is a child of ``a-node``
49 .. _dt-node-labels:
52 the labeled node. Above, ``a-sub-node`` has the node label
61 ``a-sub-node`` is ``/a-node/a-sub-node``.
68 array of what are called *cells*. A cell is just a 32-bit unsigned integer.
70 Node ``a-sub-node`` has a property named ``foo``, whose value is a cell with
72 angle brackets (``<`` and ``>``) in the DTS.
74 See :ref:`dt-writing-property-values` below for more example property values.
86 :figclass: align-center
93 The DTS would look something like this:
95 .. code-block:: devicetree
97 /dts-v1/;
101 i2c-bus-controller {
102 i2c-peripheral-1 {
104 i2c-peripheral-2 {
106 i2c-peripheral-3 {
119 Here's a tree representing the same example, but with real-world node
123 :figclass: align-center
125 I2C devicetree example with real-world names and properties.
129 This is the corresponding DTS:
131 .. code-block:: devicetree
133 /dts-v1/;
138 compatible = "nordic,nrf-twim";
157 .. _dt-unit-address:
162 In addition to showing more real-world names and properties, the above example
172 Memory-mapped peripherals
191 Memory-mapped flash
201 .. code-block:: devicetree
216 .. _dt-important-props:
233 :zephyr_file:`dts/bindings/vendor-prefixes.txt` contains a list of commonly
237 It is also sometimes a value like ``gpio-keys``, ``mmio-sram``, or
238 ``fixed-clock`` when the hardware's behavior is generic.
241 :ref:`bindings <dt-bindings>` for the node. Device drivers use
247 allow the system to match from most- to least-specific device drivers.
249 Within Zephyr's bindings syntax, this property has type ``string-array``.
261 - Devices accessed via memory-mapped I/O registers (like ``i2c@40003000``):
264 - I2C devices (like ``apds9960@39`` and its siblings):
267 - SPI devices: ``address`` is a chip select line number; there is no
279 ``"okay"``, ``"disabled"``, ``"reserved"``, ``"fail"``, and ``"fail-sss"``.
297 Zephyr's devicetree bindings language lets you give a name to each cell in
308 which is distinct from the standard :ref:`node label <dt-node-labels>`.
309 Use of the label *property* in new devicetree bindings, as well as use of
312 bindings and overlays, but should not be used in new bindings or device
315 .. _dt-writing-property-values:
320 This section describes how to write property values in DTS format. The property
321 types in the table below are described in detail in :ref:`dt-bindings`.
326 .. list-table::
327 :header-rows: 1
330 * - Property type
331 - How to write
332 - Example
334 * - string
335 - Double quoted
336 - ``a-string = "hello, world!";``
338 * - int
339 - between angle brackets (``<`` and ``>``)
340 - ``an-int = <1>;``
342 * - boolean
343 - for ``true``, with no value (for ``false``, use ``/delete-property/``)
344 - ``my-true-boolean;``
346 * - array
347 - between angle brackets (``<`` and ``>``), separated by spaces
348 - ``foo = <0xdeadbeef 1234 0>;``
350 * - uint8-array
351 - in hexadecimal *without* leading ``0x``, between square brackets (``[`` and ``]``).
352 - ``a-byte-array = [00 01 ab];``
354 * - string-array
355 - separated by commas
356 - ``a-string-array = "string one", "string two", "string three";``
358 * - phandle
359 - between angle brackets (``<`` and ``>``)
360 - ``a-phandle = <&mynode>;``
362 * - phandles
363 - between angle brackets (``<`` and ``>``), separated by spaces
364 - ``some-phandles = <&mynode0 &mynode1 &mynode2>;``
366 * - phandle-array
367 - between angle brackets (``<`` and ``>``), separated by spaces
368 - ``a-phandle-array = <&mynode0 1 2>, <&mynode1 3 4>;``
372 - The values in the ``phandle``, ``phandles``, and ``phandle-array`` types are
373 are described further in :ref:`dt-phandles`
375 - Boolean properties are true if present. They should not have a value.
376 A boolean property is only false if it is completely missing in the DTS.
378 - The ``foo`` property value above has three *cells* with values 0xdeadbeef, 1234,
380 can be intermixed. Since Zephyr transforms DTS to C sources, it is not
383 - 64-bit integers are written as two 32-bit cells in big-endian order. The value
386 - The ``a-byte-array`` property value is the three bytes 0x00, 0x01, and 0xab, in
389 - Parentheses, arithmetic operators, and bitwise operators are allowed. The
392 .. code-block:: devicetree
398 - Property values refer to other nodes in the devicetree by their *phandles*.
400 <dt-node-labels>`. Here is an example devicetree fragment:
402 .. code-block:: devicetree
416 In the devicetree, a phandle value is a cell -- which again is just a 32-bit
419 :ref:`dt-from-c`.
421 - Array and similar type property values can be split into several ``<>``
424 .. code-block:: devicetree
428 foo = <&label1 1 2>, <&label2 3 4>; // Okay for 'type: phandle-array'
431 logically grouped into blocks of sub-values.
433 .. _dt-alias-chosen:
438 There are two additional ways beyond :ref:`node labels <dt-node-labels>` to
444 .. code-block:: devicetree
446 /dts-v1/;
454 my-uart = &uart0;
467 Above, ``my-uart`` is an alias for the node with path ``/soc/serial@12340000``.
473 example, :zephyr:code-sample:`blinky` uses this to abstract the LED to blink via the
476 The ``/chosen`` node's properties are used to configure system- or
477 subsystem-wide values. See :ref:`devicetree-chosen-nodes` for more information.