From 43086d35357202bab8c332032843833867d0ff6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Wed, 14 Apr 2021 15:50:52 -0700 Subject: [PATCH] doc: devicetree: improve 'writing property values' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Break it down in a table based on each supported type in the bindings language and add cross-references. Move the section higher up, to make it easier to find. Signed-off-by: Martí Bolívar --- doc/guides/dts/intro.rst | 166 ++++++++++++++++++++++++--------------- 1 file changed, 103 insertions(+), 63 deletions(-) diff --git a/doc/guides/dts/intro.rst b/doc/guides/dts/intro.rst index f40d39f5fdb..1d99ae8905c 100644 --- a/doc/guides/dts/intro.rst +++ b/doc/guides/dts/intro.rst @@ -339,6 +339,109 @@ interrupts .. _Devicetree Specification release v0.3: https://www.devicetree.org/specifications/ +.. highlight:: none + +.. _dt-writing-property-values: + +Writing property values +*********************** + +This section describes how to write property values in DTS format. The property +types in the table below are described in detail in :ref:`dt-bindings`. + +Some specifics are skipped in the interest of keeping things simple; if you're +curious about details, see the devicetree specification. + +.. list-table:: + :header-rows: 1 + :widths: 1 4 4 + + * - Property type + - How to write + - Example + + * - string + - Double quoted + - ``a-string = "hello, world!";`` + + * - int + - between angle brackets (``<`` and ``>``) + - ``an-int = <1>;`` + + * - boolean + - for ``true``, with no value (for ``false``, use ``/delete-property/``) + - ``my-true-boolean;`` + + * - array + - between angle brackets (``<`` and ``>``), separated by spaces + - ``foo = <0xdeadbeef 1234 0>;`` + + * - uint8-array + - in hexadecimal *without* leading ``0x``, between square brackets (``[`` and ``]``). + - ``a-byte-array = [00 01 ab];`` + + * - string-array + - separated by commas + - ``a-string-array = "string one", "string two", "string three";`` + + * - phandle + - between angle brackets (``<`` and ``>``) + - ``a-phandle = <&mynode>;`` + + * - phandles + - between angle brackets (``<`` and ``>``), separated by spaces + - ``some-phandles = <&mynode0 &mynode1 &mynode2>;`` + + * - phandle-array + - between angle brackets (``<`` and ``>``), separated by spaces + - ``a-phandle-array = <&mynode0 1 2 &mynode1 3 4>;`` + +Additional notes on the above: + +- Boolean properties are true if present. They should not have a value. + A boolean property is only false if it is completely missing in the DTS. + +- The ``foo`` property value above has three *cells* with values 0xdeadbeef, 1234, + and 0, in that order. Note that hexadecimal and decimal numbers are allowed and + can be intermixed. Since Zephyr transforms DTS to C sources, it is not + necessary to specify the endianness of an individual cell here. + +- 64-bit integers are written as two 32-bit cells in big-endian order. The value + 0xaaaa0000bbbb1111 would be written ``<0xaaaa0000 0xbbbb1111>``. + +- The ``a-byte-array`` property value is the three bytes 0x00, 0x01, and 0xab, in + that order. + +- Parentheses, arithmetic operators, and bitwise operators are allowed. The + ``bar`` property contains a single cell with value 64:: + + bar = <(2 * (1 << 5))>; + + Note that the entire expression must be parenthesized. + +- Property values refer to other nodes in the devicetree by their *phandles*. + You can write a phandle using ``&foo``, where ``foo`` is a :ref:`node label + `. Here is an example devicetree fragment: + + .. code-block:: DTS + + foo: device@0 { }; + device@1 { + sibling = <&foo 1 2>; + }; + + The ``sibling`` property of node ``device@1`` contains three cells, in this order: + + #. The ``device@0`` node's phandle, which is written here as ``&foo`` since + the ``device@0`` node has a node label ``foo`` + #. The value 1 + #. The value 2 + + In the devicetree, a phandle value is a cell -- which again is just a 32-bit + unsigned int. However, the Zephyr devicetree API generally exposes these + values as *node identifiers*. Node identifiers are covered in more detail in + :ref:`dt-from-c`. + .. _dt-alias-chosen: Aliases and chosen nodes @@ -531,66 +634,3 @@ These are created in your application's build directory. The preprocessed and concatenated DTS sources and overlays. This is an intermediate output file, which is used to create :file:`zephyr.dts` and :file:`devicetree_unfixed.h`. - -.. highlight:: none - -.. _dt-writing-property-values: - -Writing property values -*********************** - -Here are some example ways to write property values in DTS format. Some -specifics are skipped in the interest of keeping things simple; if you're -curious about details, see the devicetree specification. - -Arrays of 32-bit unsigned integers, or *cells*, can be written between angle -brackets (``<`` and ``>``) and separated by spaces:: - - foo = <0xdeadbeef 1234 0>; - -The ``foo`` property value is three cells with values 0xdeadbeef, 1234, and 0, -in that order. Note that hexadecimal and decimal numbers are allowed and can be -intermixed. Since Zephyr transforms DTS to C sources, it is not necessary to -specify the endianness of an individual cell here. - -64-bit integers are written as two 32-bit cells in big-endian order. The value -0xaaaa0000bbbb1111 would be written ``<0xaaaa0000 0xbbbb1111>``. - -Parentheses, arithmetic operators, and bitwise operators are allowed. The -``bar`` property contains a single cell with value 64:: - - bar = <2 * (1 << 5)>; - -Strings are double quoted:: - - a-string = "hello, world!"; - -String arrays are separated by commas:: - - a-string-array = "string one", "string two", "string three"; - -Arrays of bytes are written in hexadecimal *without* leading ``0x`` between -square brackets (``[`` and ``]``). Property ``a-byte-array`` is the three bytes -0x00, 0x01, 0xab, in that order:: - - a-byte-array = [00 01 ab]; - -Properties can refer to other nodes in the devicetree by their *phandles*. You -can write a phandle using ``&label``, like in this devicetree fragment: - -.. code-block:: DTS - - baz: device@0 { - /* ... */ - }; - device@1 { - sibling = <&baz 1 2>; - /* ... */ - }; - -The ``sibling`` property of node ``device@1`` contains three cells: - -- The ``device@0`` node's phandle. Each phandle occupies an entire cell. The - ``baz`` label is used to write the phandle ``&baz`` inside the ``sibling`` - property value. -- The values 1 and 2, each in its own cell, in that order.