device-tree

デバイスツリー（Devicetree）

目的

Linux デバイスツリーソース（DTS）の構文、バインディング、phandle、オーバーレイ、およびカーネルの OF（Open Firmware）レイヤーがハードウェア記述を platform_device インスタンスとして解析する仕組みについて、エージェントをガイドします。

使用する場面

• プラットフォームドライバーがプローブされない — DT の不整合
• 新しいボード用の .dts またはフラグメントオーバーレイを追加する
• compatible、reg、interrupts、clocks プロパティを理解する
• ハードウェアを skills/kernel-dev/platform-device-model と照合する

ワークフロー

1. DTS の構造

/dts-v1/;
#include "soc.dtsi"

/ {
    model = "My Board";
    compatible = "vendor,my-board", "vendor,soc-family";

    soc {
        uart0: serial@40011000 {
            compatible = "vendor,uart";
            reg = <0x40011000 0x400>;
            interrupts = <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&clk_uart0>;
            status = "okay";
        };
    };
};

2. 主なプロパティ

プロパティ	意味
compatible	ドライバーのマッチ文字列（最も具体的なものを先に記述）
reg	MMIO アドレス＋長さ（ #address-cells、#size-cells ）
interrupts	IRQ 指定子（セル数は割り込み親が定義）
clocks / clock-names	クロックプロバイダーへの phandle
status	"disabled" の場合、プローブをスキップします

3. Phandle

clk_uart0: clock-uart {
    compatible = "vendor,clk";
    #clock-cells = <0>;
};

serial@... {
    clocks = <&clk_uart0>;  /* phandle reference */
};

4. カーネルによる解析

OF core reads DTB at boot
├── of_platform_populate() creates platform_devices
└── driver `.of_match_table` matches `compatible`

static const struct of_device_id my_of_match[] = {
    { .compatible = "vendor,uart" },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_match);

5. コンパイルと確認

dtc -I dts -O dtb -o board.dtb board.dts
dtc -I fs -O dts /proc/device-tree 2>/dev/null | less
ls /sys/firmware/devicetree/base/

バインディングは devicetree.org にあります。コミットでは、必ずバインディング名を記載してください。

6. オーバーレイ（configfs）

# Runtime overlay apply (when CONFIG_OF_OVERLAY)
mkdir -p /config/device-tree/overlays/my-overlay
cat my-overlay.dtbo > /config/device-tree/overlays/my-overlay/dtbo

7. エージェントでの使用

/device-tree Write DTS fragment for I2C sensor on i2c1 with interrupt on GPIO5

よくある問題

症状	原因	修正方法
ドライバーがバインドされない	compatible の誤記	ドライバーの of_match_table と一致させます
MMIO が誤っている	#address-cells の不一致	SoC の .dtsi に従います
IRQ が発生しない	割り込み親またはセル数が誤っている	動作するボードの DTS からコピーします
プローブが defer ループに入る	クロック／レギュレーターがない	DT に -EPROBE_DEFER の供給元を指定します
オーバーレイが失敗する	シンボルを解決できない	__fixups__ / ラベルのエクスポート

関連スキル

• skills/kernel-dev/platform-device-model — プローブと sysfs
• skills/kernel/device-drivers — devm_of_iomap
• skills/baremetal/datasheet-and-refmanual-reading — HW から DT へのマッピング
• skills/embedded/zephyr — Zephyr のデバイスツリー（ツールは異なります）
• skills/kernel-dev/bus-drivers-i2c-spi — バスノードの子ノード