.. SPDX-License-Identifier: Apache-2.0 .. .. _chapter-devicetree: The Devicetree ============== .. _chapter-devicetree: デバイスツリー ============== .. Overview 概要 -------- .. |spec| specifies a construct called a *devicetree* to describe system hardware. A boot program loads a devicetree into a client program’s memory and passes a pointer to the devicetree to the client. |spec| システムハードウェアを記述するための *デバイスツリー* と呼ばれる構造を指定します。 ブートプログラムは、デバイスツリーをクライアントプログラムのメモリにロードし、デバイスツリーへのポインタをクライアントに渡します。 .. This chapter describes the logical structure of the devicetree and specifies a base set of properties for use in describing device nodes. :numref:`Chapter %s ` specifies certain device nodes required by a |spec|-compliant devicetree. :numref:`Chapter %s ` describes the |spec|-defined device bindings -- the requirements for representing certain device types or classes of devices. :numref:`Chapter %s ` describes the in-memory encoding of the devicetree. この章では、デバイスツリーの論理構造について説明し、デバイスノードの説明に使用するプロパティの基本セットを指定します。 :numref:`第 %s 章 ` は、 |spec| 準拠のデバイスツリーに必要な特定のデバイスノードを指定します。 :numref:`第 %s 章 ` は、 |spec| で定義されたデバイスバインディング（特定のデバイスタイプまたはデバイスのクラスを表すための要件）について説明しています。 :numref:`第 %s 章 ` は、デバイスツリーのメモリ内エンコーディングについて説明しています。 .. A devicetree is a tree data structure with nodes that describe the devices in a system. Each node has property/value pairs that describe the characteristics of the device being represented. Each node has exactly one parent except for the root node, which has no parent. デバイスツリーは、システム内のデバイスを記述するノードを持つツリーデータ構造です。 各ノードには、表現されているデバイスの特性を説明するプロパティと値のペアがあります。 親がないルートノードを除いて、各ノードには1つの親があります。 .. A |spec|-compliant devicetree describes device information in a system that cannot necessarily be dynamically detected by a client program. For example, the architecture of PCI enables a client to probe and detect attached devices, and thus devicetree nodes describing PCI devices might not be required. However, a device node is required to describe a PCI host bridge device in the system if it cannot be detected by probing. |spec| 準拠のデバイスツリーは、クライアントプログラムによって必ずしも動的に検出されるとは限らないシステム内のデバイス情報を記述します。 たとえば、PCIのアーキテクチャにより、クライアントは接続されたデバイスを探索および検出できるため、PCIデバイスを記述するデバイスツリーノードは必要ない場合があります。 ただし、探索で検出できない場合は、システム内のPCIホストブリッジデバイスを記述するためにデバイスノードが必要です。 .. **Example** **例** .. :numref:`example-simple-devicetree` shows an example representation of a simple devicetree that is nearly complete enough to boot a simple operating system, with the platform type, CPU, memory and a single UART described. Device nodes are shown with properties and values inside each node. :numref:`example-simple-devicetree` は、プラットフォームタイプ、CPU、メモリ、および一つのUARTが記述された、単純なオペレーティングシステムを起動するのにほぼ完全な単純なデバイスツリーの表現例を示しています。 デバイスノードは、各ノード内のプロパティと値とともに表示されます。 .. _example-simple-devicetree: .. digraph:: tree :caption: Devicetree Example rankdir = LR; ranksep = equally; size = "6,8" node [ shape="Mrecord"; width="3.5"; fontname = Courier; ]; "/" [ label = "\N | model=\"fsl,mpc8572ds\"\l compatible=\"fsl,mpc8572ds\"\l #address-cells=\<1\>\l #size-cells=\<1\>\l"] "cpus" [ label="\N | #address-cells=\<1\>\l #size-cells=\<0\>\l"] "cpu@0" [ label="\N | device_type=\"cpu\"\l reg=\<0\>\l timebase-frequency=\<825000000\>\l clock-frequency=\<825000000\>\l"] "cpu@1" [ label="\N | device_type=\"cpu\"\l reg=\<1\>\l timebase-frequency=\<825000000\>\l clock-frequency=\<825000000\>\l"] "memory@0" [ label="\N | device_type=\"memory\"\l reg=\<0 0x20000000\>\l"] "uart@fe001000" [ label="\N | compatible=\"ns16550\"\l reg=\<0xfe001000 0x100\>\l"] "chosen" [ label="\N | bootargs=\"root=/dev/sda2\"\l"] "aliases" [ label="\N | serial0=\"/uart@fe001000\"\l"] "/":e -> "cpus":w "cpus":e -> "cpu@0":w "cpus":e -> "cpu@1":w "/":e -> "memory@0":w "/":e -> "uart@fe001000":w "/":e -> "chosen":w "/":e -> "aliases":w .. Devicetree Structure and Conventions デバイスツリーの構造と規則 ------------------------------------ .. _sect-node-names: .. Node Names ノード名 ~~~~~~~~~~ .. Node Name Requirements ノード名の要件 ^^^^^^^^^^^^^^^^^^^^^^ .. Each node in the devicetree is named according to the following convention: デバイスツリーの各ノードには、次の規則に従って名前が付けられます。 ``node-name@unit-address`` .. The *node-name* component specifies the name of the node. It shall be 1 to 31 characters in length and consist solely of characters from the set of characters in :numref:`node-name-characters`. *node-name* コンポーネントは、ノードの名前を指定します。 長さは1〜31文字で、:numref:`node-name-characters` の文字セットの文字のみで構成されるものとします。 .. tabularcolumns:: | c p{8cm} | .. _node-name-characters: .. table:: Valid characters for node names ========= ================ Character Description ========= ================ ``0-9`` digit ``a-z`` lowercase letter ``A-Z`` uppercase letter ``,`` comma ``.`` period ``_`` underscore ``+`` plus sign ``-`` dash ========= ================ .. The *node-name* shall start with a lower or uppercase character and should describe the general class of device. *node-name* は小文字または大文字で始まるものとし、デバイスの一般的なクラスを説明する必要があります。 .. The *unit-address* component of the name is specific to the bus type on which the node sits. It consists of one or more ASCII characters from the set of characters in :numref:`node-name-characters`. The unit-address must match the first address specified in the *reg* property of the node. If the node has no *reg* property, the *@unit-address* must be omitted and the *node-name* alone differentiates the node from other nodes at the same level in the tree. The binding for a particular bus may specify additional, more specific requirements for the format of *reg* and the *unit-address*. 名前の *unit-address* コンポーネントは、ノードが置かれているバスタイプに固有です。 これは、 :numref:`node-name-characters` の文字セットからの1つ以上のASCII文字で構成されます。 unit-address は、ノードの *reg* プロパティで指定された最初のアドレスと一致する必要があります。 ノードに *reg* プロパティがない場合は、 *@unit-address* を省略し、 *node-name* だけで、ツリー内の同じレベルにある他のノードとノードを区別します。 特定のバスのバインディングでは、*reg* の形式と *unit-address* に関する追加のより具体的な要件を指定できます。 .. In the case of *node-name* without an *@unit-address* the *node-name* shall be unique from any property names at the same level in the tree. *@unit-address* のない *node-name* の場合、 *node-name* は、ツリー内の同じレベルにあるすべてのプロパティ名から一意である必要があります。 .. The root node does not have a node-name or unit-address. It is identified by a forward slash (/). ルートノードには、ノード名またはユニットアドレスがありません。スラッシュ（/）で識別されます。 .. _example-nodenames: .. digraph:: tree :caption: Examples of Node Names rankdir = LR; ranksep = equally; size = "6,8" node [ shape="Mrecord"; width="2.5"; fontname = Courier; ]; "/":e -> "cpus":w "cpus":e -> "cpu@0":w "cpus":e -> "cpu@1":w "/":e -> "memory@0":w "/":e -> "uart@fe001000":w "/":e -> "ethernet@fe002000":w "/":e -> "ethernet@fe003000":w In :numref:`example-nodenames`: .. * The nodes with the name ``cpu`` are distinguished by their unit-address values of 0 and 1. * The nodes with the name ``ethernet`` are distinguished by their unit-address values of ``fe002000`` and ``fe003000``. * ``cpu`` という名前のノードは、0と1のユニットアドレス値によって区別されます。 * ``ethernet`` という名前のノードは、ユニットアドレス値 ``fe002000`` および ``fe003000`` によって区別されます。 .. Generic Names Recommendation 一般名の推奨事項 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. The name of a node should be somewhat generic, reflecting the function of the device and not its precise programming model. If appropriate, the name should be one of the following choices: ノードの名前は、正確なプログラミングモデルではなく、デバイスの機能を反映して、ある程度一般的なものにする必要があります。 必要に応じて、名前は次のいずれかの選択肢になります。 .. FIXME should describe when each node name is appropriate .. hlist:: :columns: 3 * adc * accelerometer * air-pollution-sensor * atm * audio-codec * audio-controller * backlight * bluetooth * bus * cache-controller * camera * can * charger * clock * clock-controller * co2-sensor * compact-flash * cpu * cpus * crypto * disk * display * dma-controller * dsi * dsp * eeprom * efuse * endpoint * ethernet * ethernet-phy * fdc * flash * gnss * gpio * gpu * gyrometer * hdmi * hwlock * i2c * i2c-mux * ide * interrupt-controller * iommu * isa * keyboard * key * keys * lcd-controller * led * leds * led-controller * light-sensor * lora * magnetometer * mailbox * mdio * memory * memory-controller * mmc * mmc-slot * mouse * nand-controller * nvram * oscillator * parallel * pc-card * pci * pcie * phy * pinctrl * pmic * pmu * port * ports * power-monitor * pwm * regulator * reset-controller * rng * rtc * sata * scsi * serial * sound * spi * spmi * sram-controller * ssi-controller * syscon * temperature-sensor * timer * touchscreen * tpm * usb * usb-hub * usb-phy * video-codec * vme * watchdog * wifi .. Path Names パス名 ~~~~~~~~~~ .. A node in the devicetree can be uniquely identified by specifying the full path from the root node, through all descendant nodes, to the desired node. デバイスツリー内のノードは、ルートノードからすべての子孫ノードを経由して目的のノードまでのフルパスを指定することで一意に識別できます。 .. The convention for specifying a device path is: デバイスパスを指定するための規則は次のとおりです。 ``/node-name-1/node-name-2/node-name-N`` .. For example, in :numref:`example-nodenames`, the device path to cpu #1 would be: たとえば、 :numref:`example-nodenames` では、CPU#1 へのデバイスパスは次のようになります。 ``/cpus/cpu@1`` .. The path to the root node is /. ルートノードへのパスは/です。 .. A unit address may be omitted if the full path to the node is unambiguous. ノードへのフルパスが明確な場合は、ユニットアドレスを省略できます。 .. If a client program encounters an ambiguous path, its behavior is undefined. クライアントプログラムがあいまいなパスに遭遇した場合、その動作は定義されていません。 .. Properties プロパティ ~~~~~~~~~~ .. Each node in the devicetree has properties that describe the characteristics of the node. Properties consist of a name and a value. デバイスツリーの各ノードには、ノードの特性を説明するプロパティがあります。 プロパティは、名前と値で構成されます。 .. Property Names プロパティ名 ^^^^^^^^^^^^^^ .. Property names are strings of 1 to 31 characters from the characters show in :numref:`property-name-characters` プロパティ名は、 :numref:`property-name-characters` に表示される文字の1〜31文字の文字列です。 .. tabularcolumns:: | c p{8cm} | .. _property-name-characters: .. table:: Valid characters for property names ========= ================ Character Description ========= ================ ``0-9`` digit ``a-z`` lowercase letter ``A-Z`` uppercase letter ``,`` comma ``.`` period ``_`` underscore ``+`` plus sign ``?`` question mark ``#`` hash ``-`` dash ========= ================ .. Nonstandard property names should specify a unique string prefix, such as a stock ticker symbol, identifying the name of the company or organization that defined the property. Examples: 非標準のプロパティ名では、プロパティを定義した会社または組織の名前を識別する、株式相場記号などの一意の文字列プレフィックスを指定する必要があります。 例： | ``fsl,channel-fifo-len`` | ``ibm,ppc-interrupt-server#s`` | ``linux,network-index`` .. _sect-property-values: .. Property Values プロパティ値 ^^^^^^^^^^^^^^^ .. A property value is an array of zero or more bytes that contain information associated with the property. プロパティ値は、プロパティに関連付けられた情報を含む0バイト以上の配列です。 .. Properties might have an empty value if conveying true-false information. In this case, the presence or absence of the property is sufficiently descriptive. 真偽の情報を伝達する場合、プロパティの値は空になる可能性があります。 この場合、プロパティの有無は十分に説明的です。 .. :numref:`property-values-table` describes the set of basic value types defined by the |spec|. :numref:`property-values-table` は、 |spec| で定義された基本的な値型のセットを記述します。 .. .. tabularcolumns:: | p{4cm} p{12cm} | .. _property-values-table: .. table:: Property values :class: longtable ======================== ================================================================== Value Description ======================== ================================================================== ```` Value is empty. Used for conveying true-false information, when the presence or absence of the property itself is sufficiently descriptive. ```` A 32-bit integer in big-endian format. Example: the 32-bit value 0x11223344 would be represented in memory as: :: address 11 address+1 22 address+2 33 address+3 44 ```` Represents a 64-bit integer in big-endian format. Consists of two ```` values where the first value contains the most significant bits of the integer and the second value contains the least significant bits. Example: the 64-bit value 0x1122334455667788 would be represented as two cells as: ``<0x11223344 0x55667788>``. The value would be represented in memory as: :: address 11 address+1 22 address+2 33 address+3 44 address+4 55 address+5 66 address+6 77 address+7 88 ```` Strings are printable and null-terminated. Example: the string "hello" would be represented in memory as: :: address 68 'h' address+1 65 'e' address+2 6C 'l' address+3 6C 'l' address+4 6F 'o' address+5 00 '\0' ```` Format is specific to the property. See the property definition. ```` A ```` value. A *phandle* value is a way to reference another node in the devicetree. Any node that can be referenced defines a phandle property with a unique ```` value. That number is used for the value of properties with a phandle value type. ```` A list of ```` values concatenated together. Example: The string list "hello","world" would be represented in memory as: :: address 68 'h' address+1 65 'e' address+2 6C 'l' address+3 6C 'l' address+4 6F 'o' address+5 00 '\0' address+6 77 'w' address+7 6f 'o' address+8 72 'r' address+9 6C 'l' address+10 64 'd' address+11 00 '\0' ======================== ================================================================== .. tabularcolumns:: | p{4cm} p{12cm} | .. _property-values-table: .. table:: プロパティ値 :class: longtable ======================== ================================================================== 値 説明 ======================== ================================================================== ```` 値は空です。 プロパティ自体の有無が十分に説明的である場合に、真偽の情報を伝達するために使用されます。 ```` ビッグエンディアン形式の32ビット整数。 例: 32ビット値0x11223344は、メモリ内で次のように表されます。 :: address 11 address+1 22 address+2 33 address+3 44 ```` ビッグエンディアン形式の64ビット整数を表します。 2つの ```` 値で構成され、最初の値には整数の最上位ビットが含まれ、2番目の値には最下位ビットが含まれます。 例: 64ビット値0x1122334455667788は、2つのセルとして ``<0x11223344 0x55667788>`` として表されます。 値はメモリ内で次のように表されます。 :: address 11 address+1 22 address+2 33 address+3 44 address+4 55 address+5 66 address+6 77 address+7 88 ```` 文字列はプリント可能で、null終端させます。 例: 文字列 "hello" は、メモリ内で次のように表されます。 :: address 68 'h' address+1 65 'e' address+2 6C 'l' address+3 6C 'l' address+4 6F 'o' address+5 00 '\0' ```` 形式はプロパティに固有です。 プロパティの定義を参照してください。 ```` ```` 値。 *phandle* 値は、デバイスツリー内の別のノードを参照する方法です。 参照できるノードはすべて、一意の ```` 値を持つ phandle プロパティを定義します。 その番号は、phandle 値タイプのプロパティの値に使用されます。 ```` 連結された ```` 値のリスト。 例: 文字列リスト "hello", "world" は、メモリ内で次のように表されます。 :: address 68 'h' address+1 65 'e' address+2 6C 'l' address+3 6C 'l' address+4 6F 'o' address+5 00 '\0' address+6 77 'w' address+7 6f 'o' address+8 72 'r' address+9 6C 'l' address+10 64 'd' address+11 00 '\0' ======================== ================================================================== .. _sect-standard-properties: .. Standard Properties 標準プロパティ ------------------- .. |spec| specifies a set of standard properties for device nodes. These properties are described in detail in this section. Device nodes defined by |spec| (see :numref:`Chapter %s `) may specify additional requirements or constraints regarding the use of the standard properties. :numref:`Chapter %s ` describes the representation of specific devices and may also specify additional requirements. |spec| はデバイスノードの標準プロパティのセットを指定します。 これらのプロパティについては、このセクションで詳しく説明します。 |spec| で定義されたデバイスノード（:numref:`第 %s 章 ` を参照）は、標準プロパティの使用に関する追加の要件または制約を指定する場合があります。 :numref:`第 %s 章 ` は、特定のデバイスの表現を説明し、追加の要件を指定する場合もあります。 .. .. note:: All examples of devicetree nodes in this document use the :abbr:`DTS (Devicetree Source)` format for specifying nodes and properties. .. note:: このドキュメントのデバイスツリーノードのすべての例では、ノードとプロパティを指定するために :abbr:`DTS (Devicetree Source)` 形式を使用しています。 .. _sect-standard-properties-compatible: compatible ~~~~~~~~~~ .. Property name: ``compatible`` プロパティ名: ``compatible`` .. Value type: ```` 値のタイプ: ```` .. Description: The *compatible* property value consists of one or more strings that define the specific programming model for the device. This list of strings should be used by a client program for device driver selection. The property value consists of a concatenated list of null terminated strings, from most specific to most general. They allow a device to express its compatibility with a family of similar devices, potentially allowing a single device driver to match against several devices. The recommended format is ``"manufacturer,model"``, where ``manufacturer`` is a string describing the name of the manufacturer (such as a stock ticker symbol), and ``model`` specifies the model number. The compatible string should consist only of lowercase letters, digits and dashes, and should start with a letter. A single comma is typically only used following a vendor prefix. Underscores should not be used. 説明: *compatible* プロパティ値は、デバイスの特定のプログラミングモデルを定義する1つ以上の文字列で構成されます。 この文字列のリストは、クライアントプログラムがデバイスドライバを選択するために使用する必要があります。 プロパティ値は、最も具体的なものから最も一般的なものまで、null終端文字列の連結リストで構成されます。 これらにより、デバイスは類似デバイスのファミリーとの互換性を表現できるため、単一のデバイスドライバーを複数のデバイスと照合できる可能性があります。 推奨される形式は ``"manufacturer,model"`` です。ここで、 ``manufacturer`` は製造元の名前（株式相場記号など）を説明する文字列であり、 ``model`` はモデル番号を指定します。 compatible の文字列は、小文字、数字、ダッシュのみで構成され、英文字で始まる必要があります。 単一のコンマは通常、ベンダープレフィックスの後にのみ使用されます。 下線は使用しないでください。 .. Example: ``compatible = "fsl,mpc8641", "ns16550";`` In this example, an operating system would first try to locate a device driver that supported fsl,mpc8641. If a driver was not found, it would then try to locate a driver that supported the more general ns16550 device type. 例: ``compatible = "fsl,mpc8641", "ns16550";`` この例では、オペレーティングシステムは、最初に fsl,mpc8641 をサポートするデバイスドライバーを見つけようとします。 ドライバーが見つからなかった場合は、より一般的な ns16550 デバイスタイプをサポートするドライバーを見つけようとします。 model ~~~~~ .. Property name: ``model`` プロパティ名: ``model`` .. Value type: ```` 値のタイプ: ```` .. Description: The model property value is a ```` that specifies the manufacturer’s model number of the device. The recommended format is: ``"manufacturer,model"``, where ``manufacturer`` is a string describing the name of the manufacturer (such as a stock ticker symbol), and model specifies the model number. 説明 モデルプロパティ値は、デバイスの製造元のモデル番号を指定する ```` です。 推奨される形式は ``"manufacturer,model"`` です。 ここで、 ``manufacturer`` は製造元の名前（株式相場記号など）を説明する文字列であり、modelはモデル番号を指定します。 Example: ``model = "fsl,MPC8349EMITX";`` .. _sect-standard-properties-phandle: phandle ~~~~~~~ .. Property name: ``phandle`` プロパティ名: ``phandle`` .. Value type: ```` 値のタイプ: ```` .. Description: The *phandle* property specifies a numerical identifier for a node that is unique within the devicetree. The *phandle* property value is used by other nodes that need to refer to the node associated with the property. 説明: 説明： *phandle* プロパティは、デバイスツリー内で一意のノードの数値識別子を指定します。 *phandle* プロパティ値は、プロパティに関連付けられたノードを参照する必要がある他のノードによって使用されます。 .. Example: See the following devicetree excerpt: .. code-block:: dts pic@10000000 { phandle = <1>; interrupt-controller; reg = <0x10000000 0x100>; }; A *phandle* value of 1 is defined. Another device node could reference the pic node with a phandle value of 1: .. code-block:: dts another-device-node { interrupt-parent = <1>; }; 例: 次のデバイスツリーの抜粋を参照してください。 .. code-block:: dts pic@10000000 { phandle = <1>; interrupt-controller; reg = <0x10000000 0x100>; }; phandle値に 1 が定義されています。 別のデバイスノードは、 *phandle* 値が1のpicノードを参照できます。 .. code-block:: dts another-device-node { interrupt-parent = <1>; }; .. .. note:: Older versions of devicetrees may be encountered that contain a deprecated form of this property called ``linux,phandle``. For compatibility, a client program might want to support ``linux,phandle`` if a ``phandle`` property is not present. The meaning and use of the two properties is identical. .. note:: ``linux,phandle`` と呼ばれるこのプロパティの廃止された形式を含む古いバージョンのデバイス ツリーが検出される場合があります。 互換性のために、 ``phandle`` プロパティが存在しない場合、クライアント プログラムは ``linux,phandle`` をサポートする必要がある場合があります。 2 つのプロパティの意味と使用法は同じです。 .. note:: Most devicetrees in :abbr:`DTS (Device Tree Syntax)` (see Appendix A) will not contain explicit phandle properties. The DTC tool automatically inserts the ``phandle`` properties when the DTS is compiled into the binary DTB format. status ~~~~~~ .. Property name: ``status`` プロパティ名: ``status`` .. Value type: ```` 値のタイプ: ```` .. Description: The ``status`` property indicates the operational status of a device. The lack of a ``status`` property should be treated as if the property existed with the value of ``"okay"``. Valid values are listed and defined in :numref:`table-prop-status-values`. 説明: ``status`` プロパティは、デバイスの動作ステータスを示します。 ``status`` プロパティの欠如は、プロパティが ``"okay"`` の値で存在するかのように扱われる必要があります。 有効な値は、 :numref:`table-prop-status-values` にリストされて定義されています。 .. .. tabularcolumns:: | l J | .. _table-prop-status-values: .. table:: Values for status property ============== ============================================================== Value Description ============== ============================================================== ``"okay"`` Indicates the device is operational. -------------- -------------------------------------------------------------- ``"disabled"`` Indicates that the device is not presently operational, but it might become operational in the future (for example, something is not plugged in, or switched off). Refer to the device binding for details on what disabled means for a given device. -------------- -------------------------------------------------------------- ``"reserved"`` Indicates that the device is operational, but should not be used. Typically this is used for devices that are controlled by another software component, such as platform firmware. -------------- -------------------------------------------------------------- ``"fail"`` Indicates that the device is not operational. A serious error was detected in the device, and it is unlikely to become operational without repair. -------------- -------------------------------------------------------------- ``"fail-sss"`` Indicates that the device is not operational. A serious error was detected in the device and it is unlikely to become operational without repair. The *sss* portion of the value is specific to the device and indicates the error condition detected. ============== ============================================================== .. tabularcolumns:: | l J | .. _table-prop-status-values: .. table:: ステータスプロパティの値 ============== ============================================================== 値 説明 ============== ============================================================== ``"okay"`` デバイスが動作可能であることを示します。 -------------- -------------------------------------------------------------- ``"disabled"`` デバイスが現在動作していないが、将来動作する可能性があることを示します（たとえば、何かが接続されていないか、スイッチがオフになっています）。 特定のデバイスの無効化の意味の詳細については、デバイスバインディングを参照してください。 -------------- -------------------------------------------------------------- ``"reserved"`` デバイスが動作可能であることを示しますが、使用しないでください。 通常、これは、プラットフォームファームウェアなどの別のソフトウェアコンポーネントによって制御されるデバイスに使用されます。 -------------- -------------------------------------------------------------- ``"fail"`` デバイスが動作していないことを示します。 デバイスで重大なエラーが検出されたため、修復せずに動作する可能性はほとんどありません。 -------------- -------------------------------------------------------------- ``"fail-sss"`` デバイスが動作していないことを示します。 デバイスで重大なエラーが検出されたため、修復せずに動作する可能性はほとんどありません。 値の *sss* 部分はデバイスに固有であり、検出されたエラー状態を示します。 ============== ============================================================== .. #address-cells and #size-cells #address-cells と #size-cells ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. Property name: ``#address-cells``, ``#size-cells`` プロパティ名: ``#address-cells``, ``#size-cells`` .. Value type: ```` 値のタイプ: ```` .. Description: The *#address-cells* and *#size-cells* properties may be used in any device node that has children in the devicetree hierarchy and describes how child device nodes should be addressed. The *#address-cells* property defines the number of ```` cells used to encode the address field in a child node's *reg* property. The *#size-cells* property defines the number of ```` cells used to encode the size field in a child node’s *reg* property. The *#address-cells* and *#size-cells* properties are not inherited from ancestors in the devicetree. They shall be explicitly defined. A |spec|-compliant boot program shall supply *#address-cells* and *#size-cells* on all nodes that have children. If missing, a client program should assume a default value of 2 for *#address-cells*, and a value of 1 for *#size-cells*. 説明: *#address-cells* プロパティと *#size-cells* プロパティは、デバイスツリー階層に子があり、子デバイスノードのアドレス指定方法を説明する任意のデバイスノードで使用できます。 *#address-cells* プロパティは、子ノードの *reg* プロパティのアドレスフィールドをエンコードするために使用される ```` セルの数を定義します。 *#size-cells* プロパティは、子ノードの *reg* プロパティのサイズフィールドをエンコードするために使用される ```` セルの数を定義します。 *#address-cells* プロパティと *#size-cells* プロパティは、デバイスツリーの祖先から継承されません。 それらは明示的に定義されなければなりません。 |spec| 準拠のブートプログラムは、子を持つすべてのノードに *#address-cells* と *#size-cells* を提供する必要があります。 欠落している場合、クライアントプログラムはデフォルト値として *#address-cells* に値 2 を、*#size-cells* に値 1 を想定する必要があります。 .. Example: See the following devicetree excerpt: .. code-block:: dts soc { #address-cells = <1>; #size-cells = <1>; serial@4600 { compatible = "ns16550"; reg = <0x4600 0x100>; clock-frequency = <0>; interrupts = <0xA 0x8>; interrupt-parent = <&ipic>; }; }; In this example, the *#address-cells* and *#size-cells* properties of the ``soc`` node are both set to 1. This setting specifies that one cell is required to represent an address and one cell is required to represent the size of nodes that are children of this node. The serial device *reg* property necessarily follows this specification set in the parent (``soc``) node—the address is represented by a single cell (0x4600), and the size is represented by a single cell (0x100). 例: 次のデバイスツリーの抜粋を参照してください。 .. code-block:: dts soc { #address-cells = <1>; #size-cells = <1>; serial@4600 { compatible = "ns16550"; reg = <0x4600 0x100>; clock-frequency = <0>; interrupts = <0xA 0x8>; interrupt-parent = <&ipic>; }; }; この例では、 ``soc`` ノードの *#address-cells* プロパティと *#size-cells* プロパティの両方が 1 に設定されています。 この設定は、このノードの子は、アドレスを表すために1つのセルが必要であり、ノードのサイズを表すために1つのセルが必要であることを指定します。 シリアルデバイスの *reg* プロパティは、親 (``soc``) ノードで設定されたこの仕様に従う必要があります。 アドレスは単一のセル (0x4600) で表され、サイズは単一のセル (0x100) で表されます。 reg ~~~ .. Property name: ``reg`` プロパティ名: ``reg`` .. Property value: ```` encoded as an arbitrary number of (*address*, *length*) pairs. プロパティ値: 任意の数の（*アドレス*、*長さ*）のペアとしてエンコードされた ```` .. Description: The *reg* property describes the address of the device’s resources within the address space defined by its parent bus. Most commonly this means the offsets and lengths of memory-mapped IO register blocks, but may have a different meaning on some bus types. Addresses in the address space defined by the root node are CPU real addresses. The value is a **, composed of an arbitrary number of pairs of address and length, *
*. The number of ** cells required to specify the address and length are bus-specific and are specified by the *#address-cells* and *#size-cells* properties in the parent of the device node. If the parent node specifies a value of 0 for *#size-cells*, the length field in the value of *reg* shall be omitted. 説明: *reg* プロパティは、親バスによって定義されたアドレス空間内のデバイスのリソースのアドレスを記述します。 最も一般的には、これはメモリマップドIOレジスタブロックのオフセットと長さを意味しますが、一部のバスタイプでは異なる意味を持つ場合があります。 ルートノードによって定義されたアドレス空間のアドレスは、CPUの実アドレスです。 値は ** であり、アドレスと長さの任意の数のペア *
* で構成されます。 アドレスと長さを指定するために必要な ** セルの数はバス固有であり、デバイスノードの親の *#address-cells* プロパティと *#size-cells* プロパティによって指定されます。 親ノードが *#size-cells* に値0を指定する場合、 *reg* の値の長さフィールドは省略されます。 .. Example: Suppose a device within a system-on-a-chip had two blocks of registers, a 32-byte block at offset 0x3000 in the SOC and a 256-byte block at offset 0xFE00. The *reg* property would be encoded as follows (assuming *#address-cells* and *#size-cells* values of 1): ``reg = <0x3000 0x20 0xFE00 0x100>;`` 例: システムオンチップ内のデバイスに2つのレジスタブロックがあり、SOCのオフセット0x3000に32バイトのブロックがあり、オフセット0xFE00に256バイトのブロックがあるとします。 *reg* プロパティは次のようにエンコードされます（*#address-cells* と *#size-cells* の値が 1 であると想定）。 ``reg = <0x3000 0x20 0xFE00 0x100>;`` .. _sect-standard-properties-virtual-reg: virtual-reg ~~~~~~~~~~~ .. Property name: ``virtual-reg`` プロパティ名: ``virtual-reg`` .. Value type: ```` 値のタイプ: ```` .. Description: The *virtual-reg* property specifies an effective address that maps to the first physical address specified in the *reg* property of the device node. This property enables boot programs to provide client programs with virtual-to-physical mappings that have been set up. 説明: *virtual-reg* プロパティは、デバイスノードの *reg* プロパティで指定された最初の物理アドレスにマップする実効アドレスを指定します。 このプロパティにより、ブートプログラムは、設定された仮想から物理へのマッピングをクライアントプログラムに提供できます。 .. _sect-standard-properties-ranges: ranges ~~~~~~ .. Property name: ``ranges`` プロパティ名: ``ranges`` .. Value type: ```` or ```` encoded as an arbitrary number of (*child-bus-address*, *parent-bus-address*, *length*) triplets. 値のタイプ: ```` または、任意の数の（子バスアドレス、親バスアドレス、長さ）のトリプレットとしてエンコードされた ```` .. Description: The *ranges* property provides a means of defining a mapping or translation between the address space of the bus (the child address space) and the address space of the bus node’s parent (the parent address space). The format of the value of the *ranges* property is an arbitrary number of triplets of (*child-bus-address*, *parent-bus-address*, *length*) * The *child-bus-address* is a physical address within the child bus' address space. The number of cells to represent the address is bus dependent and can be determined from the *#address-cells* of this node (the node in which the *ranges* property appears). * The *parent-bus-address* is a physical address within the parent bus' address space. The number of cells to represent the parent address is bus dependent and can be determined from the *#address-cells* property of the node that defines the parent’s address space. * The *length* specifies the size of the range in the child’s address space. The number of cells to represent the size can be determined from the *#size-cells* of this node (the node in which the *ranges* property appears). If the property is defined with an ```` value, it specifies that the parent and child address space is identical, and no address translation is required. If the property is not present in a bus node, it is assumed that no mapping exists between children of the node and the parent address space. 説明: *ranges* プロパティは、バスのアドレス空間（子アドレス空間）とバスノードの親のアドレス空間（親アドレス空間）の間のマッピングまたは変換を定義する手段を提供します。 *ranges* プロパティの値の形式は、任意の数の（*子バスアドレス*、*親バスアドレス*、*長さ*）のトリプレットです。 * *子バスアドレス* は、子バスのアドレス空間内の物理アドレスです。 アドレスを表すセルの数はバスに依存し、このノード（*ranges* プロパティが表示されるノード）の *#address-cells* から決定できます。 * *親バスアドレス* は、親バスのアドレス空間内の物理アドレスです。 親アドレスを表すセルの数はバスに依存し、親のアドレス空間を定義するノードの *#address-cells* プロパティから決定できます。 * *長さ* は、子のアドレス空間の範囲のサイズを指定します。 サイズを表すセルの数は、このノード（*ranges* プロパティが表示されるノード）の *#size-cells* から決定できます。 プロパティが ```` 値で定義されている場合、親と子のアドレススペースが同一であり、アドレス変換は不要であることを指定します。 プロパティがバスノードに存在しない場合、ノードの子と親アドレス空間の間にマッピングが存在しないと見なされます。 .. Address Translation Example: .. code-block:: dts soc { compatible = "simple-bus"; #address-cells = <1>; #size-cells = <1>; ranges = <0x0 0xe0000000 0x00100000>; serial@4600 { device_type = "serial"; compatible = "ns16550"; reg = <0x4600 0x100>; clock-frequency = <0>; interrupts = <0xA 0x8>; interrupt-parent = <&ipic>; }; }; The ``soc`` node specifies a *ranges* property of ``<0x0 0xe0000000 0x00100000>;`` This property value specifies that for a 1024 KB range of address space, a child node addressed at physical 0x0 maps to a parent address of physical 0xe0000000. With this mapping, the ``serial`` device node can be addressed by a load or store at address 0xe0004600, an offset of 0x4600 (specified in *reg*) plus the 0xe0000000 mapping specified in *ranges*. アドレス変換の例: .. code-block:: dts soc { compatible = "simple-bus"; #address-cells = <1>; #size-cells = <1>; ranges = <0x0 0xe0000000 0x00100000>; serial@4600 { device_type = "serial"; compatible = "ns16550"; reg = <0x4600 0x100>; clock-frequency = <0>; interrupts = <0xA 0x8>; interrupt-parent = <&ipic>; }; }; ``soc`` ノードは次の範囲プロパティを指定します。 ``<0x0 0xe0000000 0x00100000>;`` このプロパティ値は、1024 KBの範囲のアドレス空間に対して、物理 0x0 でアドレス指定された子ノードが物理 0xe0000000 の親アドレスにマップされることを指定します。 このマッピングを使用すると、シリアルデバイスノードは、アドレス 0xe0004600 、オフセット 0x4600 (*reg* で指定)、および *ranges* で指定された 0xe0000000 マッピングでロードまたはストアによってアドレス指定できます。 dma-ranges ~~~~~~~~~~ .. Property name: ``dma-ranges`` プロパティ名: ``dma-ranges`` .. Value type: ```` or ```` encoded as an arbitrary number of (*child-bus-address*, *parent-bus-address*, *length*) triplets. 値のタイプ: ```` または任意の数の (*child-bus-address*, *parent-bus-address*, *length*) トリプレットとしてエンコードされた ```` 。 .. Description: The *dma-ranges* property is used to describe the direct memory access (DMA) structure of a memory-mapped bus whose devicetree parent can be accessed from DMA operations originating from the bus. It provides a means of defining a mapping or translation between the physical address space of the bus and the physical address space of the parent of the bus. The format of the value of the *dma-ranges* property is an arbitrary number of triplets of (*child-bus-address*, *parent-bus-address*, *length*). Each triplet specified describes a contiguous DMA address range. * The *child-bus-address* is a physical address within the child bus' address space. The number of cells to represent the address depends on the bus and can be determined from the *#address-cells* of this node (the node in which the *dma-ranges* property appears). * The *parent-bus-address* is a physical address within the parent bus' address space. The number of cells to represent the parent address is bus dependent and can be determined from the *#address-cells* property of the node that defines the parent’s address space. * The *length* specifies the size of the range in the child’s address space. The number of cells to represent the size can be determined from the *#size-cells* of this node (the node in which the dma-ranges property appears). 説明: *dma-ranges* プロパティは、バスに由来するDMA操作からデバイスツリーの親にアクセスできるメモリマップドバスのダイレクトメモリアクセス (DMA) 構造を記述するために使用されます。 これは、バスの物理アドレス空間とバスの親の物理アドレス空間の間のマッピングまたは変換を定義する手段を提供します。 *dma-ranges* プロパティの値の形式は、 (*child-bus-address*, *parent-bus-address*, *length*) の任意の数のトリプレットです。 指定された各トリプレットは、連続する DMA アドレス範囲を表します。 * *child-bus-address* は、子バスのアドレス空間内の物理アドレスです。 アドレスを表すセルの数はバスによって異なり、このノード (*dma-ranges* プロパティが表示されるノード) の *#address-cells* から決定できます。 * *parent-bus-address* は、親バスのアドレス空間内の物理アドレスです。 親アドレスを表すセルの数はバスに依存し、親のアドレス空間を定義するノードの *#address-cells* プロパティから決定できます。 * *length* は、子のアドレス空間の範囲のサイズを指定します。 サイズを表すセルの数は、このノード (*dma-ranges* プロパティが表示されるノード) の *#size-cells* から決定できます。 dma-coherent ~~~~~~~~~~~~ .. Property name: ``dma-coherent`` プロパティ名: ``dma-coherent`` .. Value type: ```` 値のタイプ: ```` .. Description: For architectures which are by default non-coherent for I/O, the *dma-coherent* property is used to indicate a device is capable of coherent DMA operations. Some architectures have coherent DMA by default and this property is not applicable. 説明: デフォルトで I/O に対して非コヒーレントであるアーキテクチャの場合、 *dma-coherent* プロパティは、デバイスがコヒーレントDMA操作が可能であることを示すために使用されます。 一部のアーキテクチャにはデフォルトでコヒーレントDMAがあり、このプロパティは適用されません。 name (deprecated) ~~~~~~~~~~~~~~~~~ Property name: ``name`` Value type: ```` Description: The *name* property is a string specifying the name of the node. This property is deprecated, and its use is not recommended. However, it might be used in older non-|spec|-compliant devicetrees. Operating system should determine a node’s name based on the *node-name* component of the node name (see :numref:`sect-node-names`). device_type (deprecated) ~~~~~~~~~~~~~~~~~~~~~~~~ Property name: ``device_type`` Value type: ```` Description: The *device\_type* property was used in IEEE 1275 to describe the device’s FCode programming model. Because |spec| does not have FCode, new use of the property is deprecated, and it should be included only on ``cpu`` and ``memory`` nodes for compatibility with IEEE 1275–derived devicetrees. .. _sect-interrupts: .. Interrupts and Interrupt Mapping 割り込みと割り込みマッピング -------------------------------- .. |spec| adopts the interrupt tree model of representing interrupts specified in *Open Firmware Recommended Practice: Interrupt Mapping, Version 0.9* [b7]_. Within the devicetree a logical interrupt tree exists that represents the hierarchy and routing of interrupts in the platform hardware. While generically referred to as an interrupt tree it is more technically a directed acyclic graph. |spec| は *Open Firmware Recommended Practice: Interrupt Mapping, Version 0.9* [b7]_ で指定された割り込みを表す割り込みツリーモデルを採用しています。 デバイスツリー内には、プラットフォームハードウェアの割り込みの階層とルーティングを表す論理割り込みツリーが存在します。 一般的に割り込みツリーと呼ばれますが、より技術的には有向非巡回グラフです。 .. The physical wiring of an interrupt source to an interrupt controller is represented in the devicetree with the *interrupt-parent* property. Nodes that represent interrupt-generating devices contain an *interrupt-parent* property which has a *phandle* value that points to the device to which the device’s interrupts are routed, typically an interrupt controller. If an interrupt-generating device does not have an *interrupt-parent* property, its interrupt parent is assumed to be its devicetree parent. 割り込みソースから割り込みコントローラへの物理的な配線は、 *interrupt-parent* プロパティを持つデバイスツリーで表されます。 割り込み生成デバイスを表すノードには、デバイスの割り込みがルーティングされるデバイス（通常は割り込みコントローラー）を指す *phandle* 値を持つ *interrupt-parent* プロパティが含まれています。 割り込み生成デバイスに割り込み親プロパティがない場合、その割り込み親はデバイスツリーの親であると見なされます。 .. Each interrupt generating device contains an *interrupts* property with a value describing one or more interrupt sources for that device. Each source is represented with information called an *interrupt specifier*. The format and meaning of an *interrupt specifier* is interrupt domain specific, i.e., it is dependent on properties on the node at the root of its interrupt domain. The *#interrupt-cells* property is used by the root of an interrupt domain to define the number of ```` values needed to encode an interrupt specifier. For example, for an Open PIC interrupt controller, an interrupt-specifer takes two 32-bit values and consists of an interrupt number and level/sense information for the interrupt. 各割り込み生成デバイスには、そのデバイスの1つ以上の割り込みソースを説明する値を持つ *interrupts* プロパティが含まれています。 各ソースは、 *interrupt specifier* と呼ばれる情報で表されます。 *interrupt specifier* の形式と意味は、割り込みドメイン固有です。 つまり、割り込みドメインのルートにあるノードのプロパティに依存します。 *#interrupt-cells* プロパティは、割り込みドメインのルートによって使用され、割り込み指定子をエンコードするために必要な ```` 値の数を定義します。 たとえば、Open PIC割り込みコントローラの場合、割り込み指示子は2つの32ビット値を取り、割り込み番号と割り込みのレベル/センス情報で構成されます。 .. An interrupt domain is the context in which an interrupt specifier is interpreted. The root of the domain is either (1) an interrupt controller or (2) an interrupt nexus. 割り込みドメインは、割り込み指定子が解釈されるコンテキストです。 ドメインのルートは、 (1) 割り込みコントローラーまたは (2) 割り込みネクサスのいずれかです。 .. #. An *interrupt controller* is a physical device and will need a driver to handle interrupts routed through it. It may also cascade into another interrupt domain. An interrupt controller is specified by the presence of an *interrupt-controller* property on that node in the devicetree. #. *割り込みコントローラー* は物理デバイスであり、それを介してルーティングされる割り込みを処理するためのドライバーが必要になります。 また、別の割り込みドメインにカスケードされる場合もあります。 割り込みコントローラーは、デバイスツリー内のそのノードに *interrupt-controller* プロパティが存在することによって指定されます。 .. #. An *interrupt nexus* defines a translation between one interrupt domain and another. The translation is based on both domain-specific and bus-specific information. This translation between domains is performed with the *interrupt-map* property. For example, a PCI controller device node could be an interrupt nexus that defines a translation from the PCI interrupt namespace (INTA, INTB, etc.) to an interrupt controller with Interrupt Request (IRQ) numbers. #. *割り込みネクサス* は、ある割り込みドメインと別の割り込みドメイン間の変換を定義します。 変換は、ドメイン固有の情報とバス固有の情報の両方に基づいています。 ドメイン間のこの変換は、 *interrupt-map* プロパティを使用して実行されます。 たとえば、PCIコントローラーデバイスノードは、PCI割り込みネームスペース (INTA、INTBなど) から割り込み要求 (IRQ) 番号を持つ割り込みコントローラーへの変換を定義する割り込みネクサスである可能性があります。 .. The root of the interrupt tree is determined when traversal of the interrupt tree reaches an interrupt controller node without an *interrupts* property and thus no explicit interrupt parent. 割り込みツリーのルートは、割り込みツリーのトラバースが *interrupts* プロパティなしで割り込みコントローラーノードに到達したときに決定されます。 したがって、明示的な割り込みの親はありません。 .. See :numref:`example-interrupt-tree` for an example of a graphical representation of a devicetree with interrupt parent relationships shown. It shows both the natural structure of the devicetree as well as where each node sits in the logical interrupt tree. 割り込みの親関係が示されているデバイスツリーのグラフィック表現の例については、:numref:`example-interrupt-tree` を参照してください。 これは、デバイスツリーの自然な構造と、各ノードが論理割り込みツリーのどこにあるかを示しています。 .. _example-interrupt-tree: .. digraph:: tree :caption: Example of the interrupt tree rankdir = LR ranksep = "1.5" size = "6,8" edge [ dir="none" ] node [ shape="Mrecord" width="2.5" ] subgraph cluster_devices { label = "Devicetree" graph [ style = dotted ] "soc" [ ] "device1" [ label = "device1 | interrupt-parent=\<&open-pic\>" ] "device2" [ label = "device2 | interrupt-parent=\<&gpioctrl\>" ] "pci-host" [ label = "pci-host | interrupt-parent=\<&open-pic\>" ] "slot0" [ label = "slot0 | interrupt-parent=\<&pci-host\>" ] "slot1" [ label = "slot1 | interrupt-parent=\<&pci-host\>" ] "simple-bus" [ label = "simple-bus" ] "gpioctrl" [ label = "gpioctrl | interrupt-parent=\<&open-pic\>" ] "device3" [ label = "device3 | interrupt-parent=\<&gpioctrl\>" ] edge [dir=back color=blue] "soc":e -> "device1":w "soc":e -> "device2":w "soc":e -> "open-pic":w "soc":e -> "pci-host":w "soc":e -> "simple-bus":w "pci-host":e -> "slot0":w "pci-host":e -> "slot1":w "simple-bus":e -> "gpioctrl":w "simple-bus":e -> "device3":w } subgraph cluster_interrupts { label = "Interrupt tree" graph [ style = dotted ] "i-open-pic" [ label = "open-pic | Root of Interrupt tree" ] "i-pci-host" [ label = "pci-host | Nexus Node" ] "i-gpioctrl" [ label = "gpioctrl | Nexus Node" ] "i-device1" [ label = "device1" ] "i-device2" [ label = "device2" ] "i-device3" [ label = "device3" ] "i-slot0" [ label = "slot0" ] "i-slot1" [ label = "slot1" ] edge [dir=back color=green] "i-open-pic":e -> "i-device1":w "i-open-pic":e -> "i-pci-host":w "i-open-pic":e -> "i-gpioctrl":w "i-pci-host":e -> "i-slot0":w "i-pci-host":e -> "i-slot1":w "i-gpioctrl":e -> "i-device2":w "i-gpioctrl":e -> "i-device3":w } subgraph { edge [color=red, style=dotted, constraint=false] "open-pic" -> "i-open-pic" "gpioctrl":w -> "i-gpioctrl" "pci-host" -> "i-pci-host" "slot0":e -> "i-slot0":e "slot1":e -> "i-slot1":e "device2":e -> "i-device2":w "device3":e -> "i-device3":e } In the example shown in :numref:`example-interrupt-tree`: * The ``open-pic`` interrupt controller is the root of the interrupt tree. * The interrupt tree root has three children—devices that route their interrupts directly to the ``open-pic`` * device1 * PCI host controller * GPIO Controller * Three interrupt domains exist; one rooted at the ``open-pic`` node, one at the ``PCI host bridge`` node, and one at the ``GPIO Controller`` node. * There are two nexus nodes; one at the ``PCI host bridge`` and one at the ``GPIO controller``. .. Properties for Interrupt Generating Devices 割り込み生成デバイスのプロパティ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ interrupts ^^^^^^^^^^ .. Property: ``interrupts`` プロパティ: ``interrupts`` .. Value type: ```` encoded as arbitrary number of interrupt specifiers 値のタイプ: 任意の数の割り込み指定子としてエンコードされた ```` .. Description: The *interrupts* property of a device node defines the interrupt or interrupts that are generated by the device. The value of the *interrupts* property consists of an arbitrary number of interrupt specifiers. The format of an interrupt specifier is defined by the binding of the interrupt domain root. *interrupts* is overridden by the *interrupts-extended* property and normally only one or the other should be used. 説明: デバイスノードの *interrupts* プロパティは、デバイスによって生成される1つまたは複数の割り込みを定義します。 *interrupts* プロパティの値は、任意の数の割り込み指定子で構成されます。 割り込み指定子の形式は、割り込みドメインルートのバインディングによって定義されます。 *interrupts* は *interrupts-extended* プロパティによってオーバーライドされ、通常はどちらか一方のみを使用する必要があります。 .. Example: A common definition of an interrupt specifier in an open PIC–compatible interrupt domain consists of two cells; an interrupt number and level/sense information. See the following example, which defines a single interrupt specifier, with an interrupt number of 0xA and level/sense encoding of 8. 例: オープンなPIC互換割り込みドメインでの割り込み指定子の一般的な定義は、割り込み番号とレベル/センス情報という2つのセルで構成されます。 次の例を参照してください。 この例では、割り込み番号が 0xA でレベル/センスエンコーディングが8の単一の割り込み指定子を定義しています。 ``interrupts = <0xA 8>;`` interrupt-parent ^^^^^^^^^^^^^^^^ .. Property: ``interrupt-parent`` プロパティ: ``interrupt-parent`` .. Value type: ```` 値のタイプ: ```` .. Description: Because the hierarchy of the nodes in the interrupt tree might not match the devicetree, the *interrupt-parent* property is available to make the definition of an interrupt parent explicit. The value is the phandle to the interrupt parent. If this property is missing from a device, its interrupt parent is assumed to be its devicetree parent. 説明: 割り込みツリー内のノードの階層がデバイスツリーと一致しない可能性があるため、 *interrupt-parent* プロパティを使用して、割り込みの親の定義を明示的にすることができます。 値は、割り込みの親へのphandleです。このプロパティがデバイスにない場合、その割り込みの親はデバイスツリーの親であると見なされます。 interrupts-extended ^^^^^^^^^^^^^^^^^^^ .. Property: ``interrupts-extended`` プロパティ: ``interrupts-extended`` .. Value type: `` `` 値のタイプ: `` `` .. Description: The *interrupts-extended* property lists the interrupt(s) generated by a device. *interrupts-extended* should be used instead of *interrupts* when a device is connected to multiple interrupt controllers as it encodes a parent phandle with each interrupt specifier. 説明: *interrupts-extended* プロパティは、デバイスによって生成された割り込みを一覧表示します。 割り込み-デバイスが複数の割り込みコントローラーに接続されている場合は、各割り込み指定子で親phandleをエンコードするため、*interrupts* の代わりに *interrupts-extended* を使用する必要があります。 .. Example: This example shows how a device with two interrupt outputs connected to two separate interrupt controllers would describe the connection using an *interrupts-extended* property. ``pic`` is an interrupt controller with an *#interrupt-cells* specifier of 2, while ``gic`` is an interrupt controller with an *#interrupts-cells* specifier of 1. ``interrupts-extended = <&pic 0xA 8>, <&gic 0xda>;`` 例: この例は、2つの割り込み出力が2つの別々の割り込みコントローラーに接続されているデバイスが、*interrupts-extended* プロパティを使用して接続を記述する方法を示しています。 ``pic`` は *#interrupt-cells* 指定子が 2 の割り込みコントローラーであり、 ``gic`` は *#interrupts-cells* 指定子が 1 の割り込みコントローラーです。 ``interrupts-extended = <&pic 0xA 8>, <&gic 0xda>;`` .. The *interrupts* and *interrupts-extended* properties are mutually exclusive. A device node should use one or the other, but not both. Using both is only permissible when required for compatibility with software that does not understand *interrupts-extended*. If both *interrupts-extended* and *interrupts* are present then *interrupts-extended* takes precedence. *interrupts* と *interrupts-extended* プロパティは相互に排他的です。 デバイスノードはどちらか一方を使用する必要がありますが、両方を使用することはできません。 両方の使用は、 *interrupts-extended* を理解しないソフトウェアとの互換性のために必要な場合にのみ許可されます。 *interrupts-extended* と *interrupts* の両方が存在する場合は、割り込み拡張が優先されます。 .. Properties for Interrupt Controllers 割り込みコントローラのプロパティ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #interrupt-cells ^^^^^^^^^^^^^^^^ Property: ``#interrupt-cells`` Value type: ```` Description: The *#interrupt-cells* property defines the number of cells required to encode an interrupt specifier for an interrupt domain. interrupt-controller ^^^^^^^^^^^^^^^^^^^^ Property: ``interrupt-controller`` Value type: ```` Description: The presence of an *interrupt-controller* property defines a node as an interrupt controller node. Interrupt Nexus Properties ~~~~~~~~~~~~~~~~~~~~~~~~~~ An interrupt nexus node shall have an *#interrupt-cells* property. interrupt-map ^^^^^^^^^^^^^ Property: ``interrupt-map`` Value type: ```` encoded as an arbitrary number of interrupt mapping entries. Description: An *interrupt-map* is a property on a nexus node that bridges one interrupt domain with a set of parent interrupt domains and specifies how interrupt specifiers in the child domain are mapped to their respective parent domains. The interrupt map is a table where each row is a mapping entry consisting of five components: *child unit address*, *child interrupt specifier*, *interrupt-parent*, *parent unit address*, *parent interrupt specifier*. child unit address The unit address of the child node being mapped. The number of 32-bit cells required to specify this is described by the *#address-cells* property of the bus node on which the child is located. child interrupt specifier The interrupt specifier of the child node being mapped. The number of 32-bit cells required to specify this component is described by the *#interrupt-cells* property of this node—the nexus node containing the *interrupt-map* property. interrupt-parent A single ** value that points to the interrupt parent to which the child domain is being mapped. parent unit address The unit address in the domain of the interrupt parent. The number of 32-bit cells required to specify this address is described by the *#address-cells* property of the node pointed to by the interrupt-parent field. parent interrupt specifier The interrupt specifier in the parent domain. The number of 32-bit cells required to specify this component is described by the *#interrupt-cells* property of the node pointed to by the interrupt-parent field. Lookups are performed on the interrupt mapping table by matching a unit-address/interrupt specifier pair against the child components in the interrupt-map. Because some fields in the unit interrupt specifier may not be relevant, a mask is applied before the lookup is done. This mask is defined in the *interrupt-map-mask* property (see :numref:`sect-interrupt-map-mask`). .. note:: Both the child node and the interrupt parent node are required to have *#address-cells* and *#interrupt-cells* properties defined. If a unit address component is not required, *#address-cells* shall be explicitly defined to be zero. .. _sect-interrupt-map-mask: interrupt-map-mask ^^^^^^^^^^^^^^^^^^ Property: ``interrupt-map-mask`` Value type: ```` encoded as a bit mask Description: An *interrupt-map-mask* property is specified for a nexus node in the interrupt tree. This property specifies a mask that is ANDed with the incoming unit interrupt specifier being looked up in the table specified in the *interrupt-map* property. #interrupt-cells ^^^^^^^^^^^^^^^^ Property: ``#interrupt-cells`` Value type: ```` Description: The *#interrupt-cells* property defines the number of cells required to encode an interrupt specifier for an interrupt domain. Interrupt Mapping Example ~~~~~~~~~~~~~~~~~~~~~~~~~ The following shows the representation of a fragment of a devicetree with a PCI bus controller and a sample interrupt map for describing the interrupt routing for two PCI slots (IDSEL 0x11,0x12). The INTA, INTB, INTC, and INTD pins for slots 1 and 2 are wired to the Open PIC interrupt controller. .. _example-interrupt-mapping: .. code-block:: dts soc { compatible = "simple-bus"; #address-cells = <1>; #size-cells = <1>; open-pic { clock-frequency = <0>; interrupt-controller; #address-cells = <0>; #interrupt-cells = <2>; }; pci { #interrupt-cells = <1>; #size-cells = <2>; #address-cells = <3>; interrupt-map-mask = <0xf800 0 0 7>; interrupt-map = < /* IDSEL 0x11 - PCI slot 1 */ 0x8800 0 0 1 &open-pic 2 1 /* INTA */ 0x8800 0 0 2 &open-pic 3 1 /* INTB */ 0x8800 0 0 3 &open-pic 4 1 /* INTC */ 0x8800 0 0 4 &open-pic 1 1 /* INTD */ /* IDSEL 0x12 - PCI slot 2 */ 0x9000 0 0 1 &open-pic 3 1 /* INTA */ 0x9000 0 0 2 &open-pic 4 1 /* INTB */ 0x9000 0 0 3 &open-pic 1 1 /* INTC */ 0x9000 0 0 4 &open-pic 2 1 /* INTD */ >; }; }; One Open PIC interrupt controller is represented and is identified as an interrupt controller with an *interrupt-controller* property. Each row in the interrupt-map table consists of five parts: a child unit address and interrupt specifier, which is mapped to an *interrupt-parent* node with a specified parent unit address and interrupt specifier. * For example, the first row of the interrupt-map table specifies the mapping for INTA of slot 1. The components of that row are shown here | child unit address: ``0x8800 0 0`` | child interrupt specifier: ``1`` | interrupt parent: ``&open-pic`` | parent unit address: (empty because ``#address-cells = <0>`` in the open-pic node) | parent interrupt specifier: ``2 1`` * The child unit address is ``<0x8800 0 0>``. This value is encoded with three 32-bit cells, which is determined by the value of the *#address-cells* property (value of 3) of the PCI controller. The three cells represent the PCI address as described by the binding for the PCI bus. * The encoding includes the bus number (0x0 << 16), device number (0x11 << 11), and function number (0x0 << 8). * The child interrupt specifier is ``<1>``, which specifies INTA as described by the PCI binding. This takes one 32-bit cell as specified by the *#interrupt-cells* property (value of 1) of the PCI controller, which is the child interrupt domain. * The interrupt parent is specified by a phandle which points to the interrupt parent of the slot, the Open PIC interrupt controller. * The parent has no unit address because the parent interrupt domain (the open-pic node) has an *#address-cells* value of ``<0>``. * The parent interrupt specifier is ``<2 1>``. The number of cells to represent the interrupt specifier (two cells) is determined by the *#interrupt-cells* property on the interrupt parent, the open-pic node. * The value ``<2 1>`` is a value specified by the device binding for the Open PIC interrupt controller (see :numref:`sect-bindings-simple-bus`). The value ``<2>`` specifies the physical interrupt source number on the interrupt controller to which INTA is wired. The value ``<1>`` specifies the level/sense encoding. In this example, the interrupt-map-mask property has a value of ``<0xf800 0 0 7>``. This mask is applied to a child unit interrupt specifier before performing a lookup in the *interrupt-map* table. To perform a lookup of the open-pic interrupt source number for INTB for IDSEL 0x12 (slot 2), function 0x3, the following steps would be performed: * The child unit address and interrupt specifier form the value ``<0x9300 0 0 2>``. * The encoding of the address includes the bus number (0x0 << 16), device number (0x12 << 11), and function number (0x3 << 8). * The interrupt specifier is 2, which is the encoding for INTB as per the PCI binding. * The interrupt-map-mask value ``<0xf800 0 0 7>`` is applied, giving a result of ``<0x9000 0 0 2>``. * That result is looked up in the *interrupt-map* table, which maps to the parent interrupt specifier ``<4 1>``. .. _sect-nexus: Nexus Nodes and Specifier Mapping --------------------------------- Nexus Node Properties ~~~~~~~~~~~~~~~~~~~~~ A nexus node shall have a *#-cells* property, where is some specifier space such as 'gpio', 'clock', 'reset', etc. -map ^^^^^^^^^^^^^^^ Property: ``-map`` Value type: ```` encoded as an arbitrary number of specifier mapping entries. Description: A *-map* is a property in a nexus node that bridges one specifier domain with a set of parent specifier domains and describes how specifiers in the child domain are mapped to their respective parent domains. The map is a table where each row is a mapping entry consisting of three components: *child specifier*, *specifier parent*, and *parent specifier*. child specifier The specifier of the child node being mapped. The number of 32-bit cells required to specify this component is described by the *#-cells* property of this node—the nexus node containing the *-map* property. specifier parent A single ** value that points to the specifier parent to which the child domain is being mapped. parent specifier The specifier in the parent domain. The number of 32-bit cells required to specify this component is described by the *#-cells* property of the specifier parent node. Lookups are performed on the mapping table by matching a specifier against the child specifier in the map. Because some fields in the specifier may not be relevant or need to be modified, a mask is applied before the lookup is done. This mask is defined in the *-map-mask* property (see :numref:`sect-specifier-map-mask`). Similarly, when the specifier is mapped, some fields in the unit specifier may need to be kept unmodified and passed through from the child node to the parent node. In this case, a *-map-pass-thru* property (see :numref:`sect-specifier-map-pass-thru`) may be specified to apply a mask to the child specifier and copy any bits that match to the parent unit specifier. .. _sect-specifier-map-mask: -map-mask ^^^^^^^^^^^^^^^^^^^^ Property: ``-map-mask`` Value type: ```` encoded as a bit mask Description: A *-map-mask* property may be specified for a nexus node. This property specifies a mask that is ANDed with the child unit specifier being looked up in the table specified in the *-map* property. If this property is not specified, the mask is assumed to be a mask with all bits set. .. _sect-specifier-map-pass-thru: -map-pass-thru ^^^^^^^^^^^^^^^^^^^^^^^^^ Property: ``-map-pass-thru`` Value type: ```` encoded as a bit mask Description: A *-map-pass-thru* property may be specified for a nexus node. This property specifies a mask that is applied to the child unit specifier being looked up in the table specified in the *-map* property. Any matching bits in the child unit specifier are copied over to the parent specifier. If this property is not specified, the mask is assumed to be a mask with no bits set. #-cells ^^^^^^^^^^^^^^^^^^ .. Property: ``#-cells`` プロパティ: ``#-cells`` .. Value type: ```` 値のタイプ: ```` .. Description: The *#-cells* property defines the number of cells required to encode a specifier for a domain. 説明: *#-cells* プロパティは、ドメインの指定子をエンコードするために必要なセルの数を定義します。 .. Specifier Mapping Example 指定子マッピングの例 ~~~~~~~~~~~~~~~~~~~~~~~~~ .. The following shows the representation of a fragment of a devicetree with two GPIO controllers and a sample specifier map for describing the GPIO routing of a few gpios on both of the controllers through a connector on a board to a device. The expansion device node is on one side of the connector node and the SoC with the two GPIO controllers is on the other side of the connector. 以下は、2つのGPIOコントローラーを備えたデバイスツリーのフラグメントの表現と、ボード上のコネクターを介してデバイスへの両方のコントローラー上のいくつかのgpiosのGPIOルーティングを記述するための指定子マップのサンプルを示しています。 拡張デバイスノードはコネクタノードの片側にあり、2つのGPIOコントローラを備えたSoCはコネクタの反対側にあります。 .. _example-specifier-mapping: .. code-block:: dts soc { soc_gpio1: gpio-controller1 { #gpio-cells = <2>; }; soc_gpio2: gpio-controller2 { #gpio-cells = <2>; }; }; connector: connector { #gpio-cells = <2>; gpio-map = <0 0 &soc_gpio1 1 0>, <1 0 &soc_gpio2 4 0>, <2 0 &soc_gpio1 3 0>, <3 0 &soc_gpio2 2 0>; gpio-map-mask = <0xf 0x0>; gpio-map-pass-thru = <0x0 0x1>; }; expansion_device { reset-gpios = <&connector 2 GPIO_ACTIVE_LOW>; }; .. Each row in the gpio-map table consists of three parts: a child unit specifier, which is mapped to a *gpio-controller* node with a parent specifier. gpio-map テーブルの各行は、3 つの部分で構成されています。 子ユニット指定子は、親指定子を使用して *gpio-controller* ノードにマップされます。 .. * For example, the first row of the specifier-map table specifies the mapping for GPIO 0 of the connector. The components of that row are shown here | child specifier: ``0 0`` | specifier parent: ``&soc_gpio1`` | parent specifier: ``1 0`` * The child specifier is ``<0 0>``, which specifies GPIO 0 in the connector with a *flags* field of ``0``. This takes two 32-bit cells as specified by the *#gpio-cells* property of the connector node, which is the child specifier domain. * The specifier parent is specified by a phandle which points to the specifier parent of the connector, the first GPIO controller in the SoC. * The parent specifier is ``<1 0>``. The number of cells to represent the gpio specifier (two cells) is determined by the *#gpio-cells* property on the specifier parent, the soc_gpio1 node. * The value ``<1 0>`` is a value specified by the device binding for the GPIO controller. The value ``<1>`` specifies the GPIO pin number on the GPIO controller to which GPIO 0 on the connector is wired. The value ``<0>`` specifies the flags (active low, active high, etc.). * 例えば、specifier-mapテーブルの最初の行は、コネクタの GPIO 0 のマッピングを指定します。 その行のコンポーネントをここに示します | 子指定子: ``0 0`` | 指定子の親: ``&soc_gpio1`` | 親指定子: ``1 0`` * 子指定子は ``<0 0>`` であり、 *flags* フィールドが ``0`` のコネクタで GPIO 0 を指定します。 これは、子指定子ドメインであるコネクタノードの *#gpio-cells* プロパティで指定された2つの32ビットセルを取ります。 * 指定子の親は、コネクタの指定子の親、つまりSoCの最初の GPIO コントローラーを指す phandle によって指定されます。 * 親指定子は ``<1 0>`` です。 gpio 指定子（2つのセル）を表すセルの数は、指定子の親である soc_gpio1 ノードの *#gpio-cells* プロパティによって決定されます。 * 値 ``<1 0>`` は、GPIO コントローラーのデバイスバインディングによって指定された値です。 値 ``<1>`` は、コネクタの GPIO 0 が配線されている GPIO コントローラの GPIO ピン番号を指定します。 値 ``<0>`` は、フラグ（アクティブロー、アクティブハイなど）を指定します。 .. In this example, the *gpio-map-mask* property has a value of ``<0xf 0>``. This mask is applied to a child unit specifier before performing a lookup in the *gpio-map* table. Similarly, the *gpio-map-pass-thru* property has a value of ``<0x0 0x1>``. This mask is applied to a child unit specifier when mapping it to the parent unit specifier. Any bits set in this mask are cleared out of the parent unit specifier and copied over from the child unit specifier to the parent unit specifier. この例では、*gpio-map-mask* プロパティの値は ``<0xf0>`` です。 このマスクは、 *gpio-map* テーブルでルックアップを実行する前に子ユニット指定子に適用されます。 同様に、 *gpio-map-pass-thru* プロパティの値は ``<0x0 0x1>`` です。 このマスクは、子ユニット指定子を親ユニット指定子にマッピングするときに適用されます。 このマスクに設定されたビットはすべて、親ユニット指定子からクリアされ、子ユニット指定子から親ユニット指定子にコピーされます。 .. To perform a lookup of the connector's specifier source number for GPIO 2 from the expansion device's reset-gpios property, the following steps would be performed: 拡張デバイスの reset-gpios プロパティから GPIO 2 のコネクタの指定元ソース番号のルックアップを実行するには、次の手順を実行します。 * The child specifier forms the value ``<2 GPIO_ACTIVE_LOW>``. * The specifier is encoding GPIO 2 with active low flags per the GPIO binding. * The *gpio-map-mask* value ``<0xf 0x0>`` is ANDed with the child specifier, giving a result of ``<0x2 0>``. * The result is looked up in the *gpio-map* table, which maps to the parent specifier ``<3 0>`` and &soc_gpio1 *phandle*. * The *gpio-map-pass-thru* value ``<0x0 0x1>`` is inverted and ANDed with the parent specifier found in the *gpio-map* table, resulting in ``<3 0>``. The child specifier is ANDed with the *gpio-map-pass-thru* mask, forming ``<0 GPIO_ACTIVE_LOW>`` which is then ORed with the cleared parent specifier ``<3 0>`` resulting in ``<3 GPIO_ACTIVE_LOW>``. * The specifier ``<3 GPIO_ACTIVE_LOW>`` is appended to the mapped *phandle* &soc_gpio1 resulting in ``<&soc_gpio1 3 GPIO_ACTIVE_LOW>``.