.. SPDX-License-Identifier: Apache-2.0

..
        .. _chapter-devicetree-source-format:

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

.. _chapter-devicetree-source-format:

デバイスツリーソース (DTS) フォーマット (バージョン 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.
デバイスツリーソース（DTS）形式は、カーネルが期待する形式のバイナリデバイスツリーにdtcで処理できる形式のデバイスツリーのテキスト表現です。
次の説明は、DTSの正式な構文定義ではありませんが、デバイスツリーを表すために使用される基本的な構成について説明しています。 

..
        The name of DTS files should end with ".dts".
DTSファイルの名前は「.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.
他のソースファイルは、DTSファイルから含めることができます。
インクルードファイルの名前は「.dtsi」で終わる必要があります。
含まれるファイルには、追加のファイルを含めることができます。

::

    /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.
ソース形式を使用すると、デバイスツリー内の任意のノードまたはプロパティ値にラベルを付けることができます。
phandle値またはノードへのフルパスを明示的に指定する代わりに、ラベルを参照することにより、phandleおよびpath参照を自動的に生成できます。
ラベルはデバイスツリーソース形式でのみ使用され、DTBバイナリにエンコードされません。

..
        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.
ラベルの長さは1〜31文字で、セット :numref:`label-characters` の文字のみで構成され、数字で始めることはできません。

..
        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
        ========= ================

.. tabularcolumns:: | c p{8cm} |
.. _label-characters:
.. table:: DTSラベルの有効な文字 

   ========= ================
   文字       説明
   ========= ================
   ``0-9``   数字
   ``a-z``   小文字
   ``A-Z``   大文字
   ``_``     アンダースコア
   ========= ================
..
        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.
プロパティ値は、32ビット整数セルの配列、null終端文字列、バイト文字列、またはこれらの組み合わせとして定義できます。

..
        -  Arrays of cells are represented by angle brackets surrounding a space
           separated list of C-style integers. Example:
-  セルの配列は、スペースで区切られたCスタイルの整数のリストを囲む山かっこで表されます。
   例：

::

        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
::

    ビット演算子

    &    and
    |    or
    ^    exclusive or
    ~    not
    <<  左シフト
    >>  右シフト

..
        ::

        Logical operators

        &&   and
        ||   or
        !    not
::

    論理演算子

    &&   論理積
    ||   論理和
    !    否定

..
        ::

        Relational operators

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

    関係演算子

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

..
        ::

        Ternary operators

        ?:   (condition ? value_if_true : value_if_false)
::

    三項演算子

    ?:   (条件 ? value_if_true : value_if_false)

..
        -  A 64-bit value is represented with two 32-bit cells. Example:
-  64ビット値は、2つの32ビットセルで表されます。例:

::

        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:
-  null終端文字列値は、二重引用符を使用して表されます（プロパティ値には、NULL終端文字が含まれていると見做されます）。例:

::

        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:
-  バイト文字列は角かっこ [ ] で囲まれ、各バイトは2桁の16進数で表されます。
   各バイト間のスペースはオプションです。例:

::

        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:**
**バージョン1のDTSファイルの全体的なレイアウトは次のとおりです。**

::

    /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).
``/dts-v1/;`` はファイルをバージョン1 DTSとして識別するために存在する必要があります
（このタグのないdtsファイルは、dtcによって、他の小さいが互換性のない変更に加えて、
整数に異なる形式を使用する廃止されたバージョン0にあるものとして扱われます）。

..
        Memory reservations (see :numref:`sect-fdt-memory-reservation-block`)
        are represented by lines in the form::
メモリ予約（:numref:`sect-fdt-memory-reservation-block` を参照）は、次の形式の行で表されます。

   /memreserve/ <address> <length>;

..
        Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g.,
ここで、 ``<address>`` と ``<length>`` は64ビットのCスタイルの整数です。例:

.. 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.
Cスタイル (``/* ... \*/``) およびC++スタイル (``//``) のコメントがサポートされています。