3. デバイスノードの要件¶
3.1. 基本デバイスノードタイプ¶
次のセクションでは、 DTSpec 準拠のデバイスツリーに必要なデバイスノードの基本セットの要件を指定します。
すべてのデバイスツリーにはルートノードがあり、次のノードがすべてのデバイスツリーのルートに存在する必要があります。
1つの
/cpus
ノード
少なくとも1つの
/memory
ノード
3.2. ルートノード¶
デバイスツリーには単一のルートノードがあり、他のすべてのデバイスノードはその子孫です。
ルートノードへのフルパスは /
です。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
ルートの子の reg プロパティのアドレスを表す |
|
R |
|
ルートの子の reg プロパティのサイズを表す |
|
R |
|
システム基板のモデルを一意に識別する文字列を指定します。 推奨される形式は "manufacturer,model-number" です。 |
|
R |
|
このプラットフォームと互換性のあるプラットフォームアーキテクチャのリストを指定します。 このプロパティは、オペレーティングシステムがプラットフォーム固有のコードを選択する際に使用できます。 プロパティ値の推奨される形式は次のとおりです。
例:
|
|
O |
|
デバイスのシリアル番号を表す文字列を指定します。 |
|
OR |
|
システムのフォームファクターを識別する文字列を指定します。 プロパティ値は次のいずれかになります。
|
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
他のすべての標準プロパティ (sect-standard-properties
) は許可されていますが、オプションです。
3.3. /aliases
ノード¶
デバイスツリーには、1つ以上のエイリアスプロパティを定義するエイリアスノード(/aliases
)が含まれる場合があります。
エイリアスノードはデバイスツリーのルートにあり、ノード名は /aliases
です。
/aliases
ノードの各プロパティは、エイリアスを定義します。
プロパティ名はエイリアス名を指定します。
プロパティ値は、デバイスツリー内のノードへのフルパスを指定します。
たとえば、プロパティ serial0 = "/simple-bus@fe000000/serial@llc500"
は、エイリアス serial0
を定義します。
エイリアス名は、次の文字セットの1〜31文字の小文字のテキスト文字列でなければなりません。
文字 |
説明 |
---|---|
0-9 |
数字 |
a-z |
小文字 |
- |
ダッシュ |
エイリアス値はデバイスパスであり、文字列としてエンコードされます。 値はノードへのフルパスを表しますが、パスはリーフノードを参照する必要はありません。
クライアントプログラムは、エイリアスプロパティ名を使用して、デバイスの完全なパスをその文字列値のすべてまたは一部として参照する場合があります。 クライアントプログラムは、文字列をデバイスパスと見なす場合、エイリアスを検出して使用する必要があります。
例
aliases {
serial0 = "/simple-bus@fe000000/serial@llc500";
ethernet0 = "/simple-bus@fe000000/ethernet@31c000";
};
エイリアス serial0
を指定すると、クライアント プログラムは /aliases
ノードを調べて、エイリアスがデバイス パス ``/simple-bus@fe000000/serial@llc500``0 を参照していると判断できます。
3.4. /memory
ノード¶
メモリデバイスノードはすべてのデバイスツリーに必要であり、システムの物理メモリレイアウトを記述します。 システムに複数のメモリ範囲がある場合は、複数のメモリノードを作成するか、単一のメモリノードの reg プロパティで範囲を指定できます。
ノード名の unit-name コンポーネント (sect-node-names
を参照) は memory
でなければなりません。
クライアントプログラムは、選択したストレージ属性を使用して、メモリ予約 (5.3 章 を参照)でカバーされていないメモリにアクセスできます。 ただし、実際のページへのアクセスに使用されるストレージ属性を変更する前に、クライアントプログラムは、キャッシュからの実際のページのフラッシュなど、アーキテクチャと実装に必要なアクションを実行する責任があります。 ブートプログラムは、ストレージ属性の変更に関連するアクションを実行せずに、クライアントプログラムが WIMG = 0b001x としてすべてのメモリ(メモリ予約でカバーされるメモリを含む)に安全にアクセスできるようにする責任があります。 あれは:
ライトスルーは必要ありません
キャッシング禁止ではありません
メモリコヒーレンス
保護されていないか保護されている必要があります
VLEストレージ属性がサポートされている場合、VLE=0。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
値は "memory" とするものとする |
|
R |
|
メモリ範囲の物理アドレスとサイズを指定する任意の数のアドレスとサイズのペアで構成されます。 |
|
O |
|
初期マップ領域のアドレスとサイズを指定します Is a prop-encoded-array consisting of a
triplet of (effective address, physical
address, size). The effective and physical
address shall each be 64-bit ( |
|
O |
|
このメモリが後で削除される可能性があるという明示的なヒントをオペレーティングシステムに指定します。 |
使用法の凡例: R=必須、O=オプション、OR=オプションだが推奨、SD=定義を参照 |
注釈
他のすべての標準プロパティ
(sect-standard-properties
) は許可されていますが、オプションです。
3.4.1. /memory
ノードと UEFI¶
[UEFI] 経由で起動する場合、システム メモリ マップは、[UEFI] § 7.2 で定義されている GetMemoryMap() UEFI 起動時サービスを介して取得されます。
存在する場合、OS は /memory
ノードを無視する必要があります。
3.4.2. /memory
の例¶
以下の物理メモリー・レイアウトを持つ 64 ビット Power システムがあるとします。
RAM: 開始アドレス 0x0, 長さ 0x80000000 (2 GB)
RAM: 開始アドレス 0x100000000, 長さ 0x100000000 (4 GB)
#address-cells = <2>
および #size-cells = <2>
と仮定すると、メモリ ノードは次のように定義できます。
Example #1
memory@0 {
device_type = "memory";
reg = <0x000000000 0x00000000 0x00000000 0x80000000
0x000000001 0x00000000 0x00000001 0x00000000>;
};
Example #2
memory@0 {
device_type = "memory";
reg = <0x000000000 0x00000000 0x00000000 0x80000000>;
};
memory@100000000 {
device_type = "memory";
reg = <0x000000001 0x00000000 0x00000001 0x00000000>;
};
reg
プロパティは、2 つのメモリ範囲のアドレスとサイズを定義するために使用されます。
2 GB の I/O 領域はスキップされます。
ルート ノードの #address-cells
プロパティと #size-cells
プロパティの値が 2 を指定していることに注意してください。
これは、メモリ ノードの reg
プロパティのアドレスと長さを定義するために 2 つの 32 ビット セルが必要であることを意味します。
3.5. /reserved-memory
ノード¶
予約メモリは、 /reserved-memory
ノードの下のノードとして指定されます。
オペレーティングシステムは、予約メモリを通常の使用から除外する必要があります。
特定の予約済み(通常の使用から除外される)メモリ領域を記述する子ノードを作成できます。
このようなメモリ領域は通常、さまざまなデバイスドライバによる特別な使用のために設計されています。
各メモリ領域のパラメータは、次のノードを使用してデバイスツリーにエンコードできます。
3.5.1. /reserved-memory 親ノード¶
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
ルートの子の |
|
R |
|
ルートの子の |
|
R |
|
|
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
#address-cells
と #size-cells
はルート ノードと同じ値を使用する必要があり、アドレス変換ロジックが正しく機能するように範囲を空にする必要があります。
3.5.2. /reserved-memory/ 子ノード¶
予約済みメモリノードの各子は、予約済みメモリの1つ以上の領域を指定します。
各子ノードは、 reg
プロパティを使用して予約済みメモリの特定の範囲を指定するか、オプションの制約を使用して size
プロパティを使用して動的に割り当てられたメモリブロックを要求できます。
総称名の推奨プラクティスに従って、ノード名はノードの目的(つまり、 "framebuffer" または "dma-pool")を反映する必要があります。
ノードが静的割り当ての場合は、名前にユニットアドレス(@<address>
)を追加する必要があります。
予約メモリノードには、静的割り当ての reg
プロパティ、または動的割り当ての size
プロパティが必要です。
動的割り当てでは、アライメントと alloc-ranges
プロパティを使用して、メモリの割り当て元を制限できます。
reg
と size
の両方が存在する場合、領域は reg
プロパティが優先される静的割り当てとして扱われ、 size
は無視されます。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O |
|
メモリ範囲の物理アドレスとサイズを指定する任意の数のアドレスとサイズのペアで構成されます。 |
|
O |
|
動的に割り当てられた領域用に予約するメモリのサイズ (バイト単位)。
このプロパティのサイズは、親ノードの |
|
O |
|
Address boundary for alignment of allocation.
Size of this property is based on parent node's
|
|
O |
|
Specifies regions of memory that are acceptable
to allocate from.
Format is (address, length pairs) tuples in
same format as for |
|
O |
|
May contain the following strings:
|
|
O |
|
If present, indicates the operating system must not create a virtual mapping of the region as part of its standard mapping of system memory, nor permit speculative access to it under any circumstances other than under the control of the device driver using the region. |
|
O |
|
The operating system can use the memory in this region with the limitation that the device driver(s) owning the region need to be able to reclaim it back. Typically that means that the operating system can use that region to store volatile or cached data that can be otherwise regenerated or migrated elsewhere. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
no-map
プロパティと reusable
プロパティは相互に排他的であり、両方を同じノードで一緒に使用することはできません。
Linux の実装に関する注意事項:
linux,cma-default
プロパティが存在する場合、Linux は連続メモリ アロケータのデフォルトプールにリージョンを使用します。
linux,dma-default
プロパティが存在する場合、Linux は一貫性のある DMA アロケータのデフォルト プールにリージョンを使用します。
3.5.3. 予約済みメモリへのデバイスノード参照¶
/reserved-memory
ノードの領域は、デバイス ノードに memory-region
プロパティを追加することで、他のデバイス ノードから参照できます。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O |
|
phandle、 |
|
O |
|
名前のリスト。 |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
3.5.4. /reserved-memory
and UEFI¶
When booting via [UEFI], static /reserved-memory
regions must
also be listed in the system memory map obtained via the GetMemoryMap()
UEFI boot time service as defined in [UEFI] § 7.2.
The reserved memory regions need to be included in the UEFI memory map to
protect against allocations by UEFI applications.
Reserved regions with the no-map
property must be listed in the memory
map with type EfiReservedMemoryType
.
All other reserved regions must be listed with type EfiBootServicesData
.
Dynamic reserved memory regions must not be listed in the [UEFI] memory map because they are allocated by the OS after exiting firmware boot services.
3.5.5. /reserved-memory
Example¶
This example defines 3 contiguous regions are defined for Linux kernel:
one default of all device drivers (named linux,cma
and 64MiB in size),
one dedicated to the framebuffer device (named framebuffer@78000000
, 8MiB), and
one for multimedia processing (named multimedia@77000000
, 64MiB).
/ {
#address-cells = <1>;
#size-cells = <1>;
memory {
reg = <0x40000000 0x40000000>;
};
reserved-memory {
#address-cells = <1>;
#size-cells = <1>;
ranges;
/* global autoconfigured region for contiguous allocations */
linux,cma {
compatible = "shared-dma-pool";
reusable;
size = <0x4000000>;
alignment = <0x2000>;
linux,cma-default;
};
display_reserved: framebuffer@78000000 {
reg = <0x78000000 0x800000>;
};
multimedia_reserved: multimedia@77000000 {
compatible = "acme,multimedia-memory";
reg = <0x77000000 0x4000000>;
};
};
/* ... */
fb0: video@12300000 {
memory-region = <&display_reserved>;
/* ... */
};
scaler: scaler@12500000 {
memory-region = <&multimedia_reserved>;
/* ... */
};
codec: codec@12600000 {
memory-region = <&multimedia_reserved>;
/* ... */
};
};
3.6. /chosen
Node¶
/chosen
ノードは、システム内の実際のデバイスを表すものではありませんが、実行時にシステムファームウェアによって選択または指定されたパラメーターを記述します。
ルートノードの子になります。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O |
|
クライアントプログラムのブート引数を指定する文字列。 ブート引数が不要な場合、値は潜在的に null 文字列になる可能性があります。 |
|
O |
|
ブートコンソール出力に使用されるデバイスを表すノードへのフルパスを指定する文字列。 値に文字 ":" が含まれている場合は、パスを終了します。 値はエイリアスである可能性があります。 stdin-path プロパティが指定されていない場合は、入力デバイスを定義するために stdout-path を想定する必要があります。 |
|
O |
|
ブートコンソール入力に使用されるデバイスを表すノードへのフルパスを指定する文字列。 値に文字 ":" が含まれている場合は、パスを終了します。 値はエイリアスである可能性があります。 |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
例
chosen {
bootargs = "root=/dev/nfs rw nfsroot=192.168.1.1 console=ttyS0,115200";
};
linux,stdout-path と呼ばれる非推奨の形式の stdout-path プロパティを含む古いバージョンのデバイスツリーが検出される場合があります。 互換性のために、 stdout-path プロパティが存在しない場合、クライアントプログラムは linux,stdout-path をサポートしたい場合があります。 2つのプロパティの意味と使用法は同じです。
3.7. /cpus
Node Properties¶
/cpus
ノードはすべてのデバイスツリーに必要です。
これは、システム内の実際のデバイスを表すものではありませんが、システムのCPUを表す子 cpu
ノードのコンテナーとして機能します。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
The value specifies how many cells each
element of the |
|
R |
|
Value shall be 0. Specifies that no size is
required in the |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
The /cpus
node may contain properties that are common across cpu
nodes.
See 3.8 章 for details.
For an example, see 3.8.4 章.
3.8. /cpus/cpu*
Node Properties¶
cpu
ノードは、他のオペレーティングシステムを実行している可能性のある他のCPUに干渉することなく、オペレーティングシステムを実行できるように、十分に独立したハードウェア実行ブロックを表します。
MMU を共有するハードウェアスレッドは、通常、1つの cpu
ノードで表されます。
他のより複雑なCPUトポグラフィが設計されている場合、CPUのバインディングは、トポグラフィ(MMU を共有しないスレッドなど)を記述する必要があります。
CPUとスレッドは、割り込みコントローラーのCPU/スレッドの番号付けと可能な限り一致する必要がある統一された番号スペースを介して番号付けされます。
cpu
ノード間で同じ値を持つプロパティは、代わりに /cpus
ノードに配置できます。
クライアントプログラムは最初に特定の cpu
ノードを調べる必要がありますが、期待されるプロパティが見つからない場合は、親の /cpus
ノードを調べる必要があります。
これにより、すべてのCPUで同一のプロパティの表現がより簡潔になります。
すべてのCPUノードのノード名は cpu
である必要があります。
3.8.1. /cpus/cpu*
ノードの一般的なプロパティ¶
次の表に、 cpu
ノードの一般的なプロパティを示します。
表 3.9 で説明されているプロパティの一部は、特定の適用可能な詳細を備えた選択された標準プロパティです。
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R
|
<string> |
値は |
|
R |
array |
CPUが複数のスレッド(つまり、複数の実行ストリーム)をサポートしている場合、 reg プロパティはスレッドごとに1つの要素を持つ配列です。 ``/cpus``ノードの #address-cells は、配列の各要素が取るセルの数を指定します。 ソフトウェアは、regのサイズを親ノードの #address-cells で割ることにより、スレッドの数を判別できます。 If a CPU/thread can be the target of an external interrupt the reg property value must be a unique CPU/thread id that is addressable by the interrupt controller. If a CPU/thread cannot be the target of an external interrupt, then reg must be unique and out of bounds of the range addressed by the interrupt controller If a CPU/thread's PIR (pending interrupt register) is modifiable, a client program should modify PIR to match the reg property value. If PIR cannot be modified and the PIR value is distinct from the interrupt controller number space, the CPUs binding may define a binding-specific representation of PIR values if desired. |
|
R
|
array
|
Specifies the current clock speed of the CPU
in Hertz. The value is a
|
|
R
|
array
|
Specifies the current frequency at which the timebase and decrementer registers are updated (in Hertz). The value is a <prop-encoded-array> in one of two forms:
|
|
SD |
|
CPUの状態を説明する標準プロパティ。
このプロパティは、対称型マルチプロセッシング(SMP)構成のCPUを表すノードに存在します。
CPUノードの場合、
静止CPUは、他のCPUの通常の動作に干渉できない状態にあり、静止CPUを有効または再度有効にする明示的な方法を除いて、他の実行中のCPUの通常の動作の影響を受けることもありません(enable-methodプロパティを参照)。 特に、実行中のCPUは、静止しているCPUに影響を与えることなく、ブロードキャストTLB無効化を発行できる必要があります。 Examples: A quiescent CPU could be in a spin loop, held in reset, and electrically isolated from the system bus or in another implementation dependent state. A CPU with |
|
SD
|
<stringlist> |
Describes the method by which a CPU in a
disabled state is enabled. This property is
required for CPUs with a status property with
a value of
Example: 注釈 Other methods may be added to later revisions of the DTSpec specification. |
|
SD
|
<u64> |
The cpu-release-addr property is required for
cpu nodes that have an enable-method property
value of |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O
|
<string> |
A string that specifies the numerical portion
of the Power ISA version string. For example,
for an implementation complying with Power ISA
Version 2.06, the value of this property would
be |
|
O
|
<empty> |
If the For example, if the power-isa-version property
exists and its value is |
|
SD
|
<u32> |
Specifies the block size in bytes upon which cache block instructions operate (e.g., dcbz). Required if different than the L1 cache block size. |
|
SD
|
<u32> |
Specifies the reservation granule size supported by this processor in bytes. |
|
O |
|
Specifies the CPU’s MMU type. Valid values are shown below:
|
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
Older versions of devicetree may be encountered that contain a bus-frequency property on CPU nodes. For compatibility, a client-program might want to support bus-frequency. The format of the value is identical to that of clock-frequency. The recommended practice is to represent the frequency of a bus on the bus node using a clock-frequency property.
3.8.2. TLB Properties¶
The following properties of a cpu node describe the translate look-aside buffer in the processor’s MMU.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
SD |
|
If present specifies that the TLB has a split configuration, with separate TLBs for instructions and data. If absent, specifies that the TLB has a unified configuration. Required for a CPU with a TLB in a split configuration. |
|
SD |
|
Specifies the number of entries in the TLB. Required for a CPU with a unified TLB for instruction and data addresses. |
|
SD |
|
Specifies the number of associativity sets in the TLB. Required for a CPU with a unified TLB for instruction and data addresses. |
|
SD |
|
Specifies the number of entries in the data TLB. Required for a CPU with a split TLB configuration. |
|
SD |
|
Specifies the number of associativity sets in the data TLB. Required for a CPU with a split TLB configuration. |
|
SD |
|
Specifies the number of entries in the instruction TLB. Required for a CPU with a split TLB configuration. |
|
SD |
|
Specifies the number of associativity sets in the instruction TLB. Required for a CPU with a split TLB configuration. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
3.8.3. Internal (L1) Cache Properties¶
The following properties of a cpu node describe the processor’s internal (L1) cache.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
SD |
|
If present, specifies the cache has a unified organization. If not present, specifies that the cache has a Harvard architecture with separate caches for instructions and data. |
|
SD |
|
Specifies the size in bytes of a unified cache. Required if the cache is unified (combined instructions and data). |
|
SD |
|
Specifies the number of associativity sets in a unified cache. Required if the cache is unified (combined instructions and data) |
|
SD |
|
Specifies the block size in bytes of a unified cache. Required if the processor has a unified cache (combined instructions and data) |
|
SD |
|
Specifies the line size in bytes of a unified cache, if different than the cache block size Required if the processor has a unified cache (combined instructions and data). |
|
SD |
|
Specifies the size in bytes of the instruction cache. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the number of associativity sets in the instruction cache. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the block size in bytes of the instruction cache. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the line size in bytes of the instruction cache, if different than the cache block size. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the size in bytes of the data cache. Required if the cpu has a separate cache for data. |
|
SD |
|
Specifies the number of associativity sets in the data cache. Required if the cpu has a separate cache for data. |
|
SD |
|
Specifies the block size in bytes of the data cache. Required if the cpu has a separate cache for data. |
|
SD |
|
Specifies the line size in bytes of the data cache, if different than the cache block size. Required if the cpu has a separate cache for data. |
|
SD |
|
If present, indicates that another level of cache exists. The value is the phandle of the next level of cache. The phandle value type is fully described in 2.3.3 章. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
注釈
All other standard properties
(sect-standard-properties
) are allowed but are optional.
Older versions of devicetrees may be encountered that contain a
deprecated form of the next-level-cache property called l2-cache
.
For compatibility, a client-program may wish to support l2-cache
if a next-level-cache property is not present.
The meaning and use of the two properties is identical.
3.8.4. Example¶
Here is an example of a /cpus
node with one child cpu node:
cpus {
#address-cells = <1>;
#size-cells = <0>;
cpu@0 {
device_type = "cpu";
reg = <0>;
d-cache-block-size = <32>; // L1 - 32 bytes
i-cache-block-size = <32>; // L1 - 32 bytes
d-cache-size = <0x8000>; // L1, 32K
i-cache-size = <0x8000>; // L1, 32K
timebase-frequency = <82500000>; // 82.5 MHz
clock-frequency = <825000000>; // 825 MHz
};
};