2021年8月【Variscite】VarisciteのSystem On Module向けデバイスツリーに付いて解説します。

Varisciteデバイスツリー入門

序章

System On Module用カスタムキャリアボードを設計した後、最初に行う
ソフトウェアタスクの1つは、Linuxカーネルに「サポート」を追加することです。
これらは次のもので構成されます。

1． Linuxカーネルに新しいデバイスツリーを追加
2． 各デバイスをそのデバイスツリーへ追加
3． 各々のデバイスドライバーをカーネル構成で有効化

このガイドでは、新しいデバイスツリーファイルを追加し、デバイスツリーで
新しいデバイスを構成する方法を説明します。
カーネル構成でドライバーを有効化する方法については、Varisciteのカーネル構成ガイド
をご覧ください。

デバイスツリーとは何でしょうか？

デバイスツリーは、システムハードウェアをLinuxカーネルに記述するノード構造です。
ブートプロセス中に、U-Bootはデバイスツリーをファイルシステムからメモリにロードします。
そしてLinuxカーネルは、実行時にデバイスツリーを解析し、最終的に各ドライバーの
プローブ関数を呼び出します。

デバイスツリーには、自動的に検出できないデバイスのみが含まれます。
例えば、デバイスツリーはSoC USBコントローラーを定義する必要がありますが、
カーネルは実行時にUSBデバイスを検出できます。

Varisciteデバイスツリーファイル

Variscite i.MX8デバイスツリーファイルは、Linuxソースツリーの
arch/arm64/boot/dts/freescaleディレクトリにあり、
NXP SoC、Variscite SoM、およびVarisciteキャリアボードファイルの
組み合わせを使用して構築されています。
各キャリアボードには、Varisciteの関連するSoMデバイスツリーを含む
ユニークなデバイスツリーが必要です。
以下の図1は、VarisciteのVAR-SOM-MX8M-MINIおよびDART-MX8M-MINI評価
キットのデバイスツリーファイルの例を示しています。

arch/arm64/boot/dts/freescale/
…
imx8mm.dtsi
…
imx8mm-var-dart.dtsi
imx8mm-var-dart-dt8mcustomboard.dts
…
imx8mm-var-som.dtsi
imx8mm-var-som-symphony.dts

新しいデバイスツリーファイルの追加

カスタムキャリアボード用の新しいデバイスツリーを作成することをお勧めします。
Varisciteのデバイスツリーを直接変更することは可能ですが、そうすると、
マージ競合が発生する可能性があるため、変更を新しいLinuxリリースに
移植することがより困難になります。
新しいデバイスツリーファイルを作成する場合、2つのアプローチがあります。

1．VarisciteのSOMレベルのデバイスツリーを含め、必要なすべてのノードを追加します。
このアプローチは、キャリアボードがVarisciteの評価キットと大幅に異なる場合に最適です。
例えば：

arch/arm64/boot/dts/freescale/imx8mm-var-som-customer.dts

/dts-v1/;
#include “imx8mm-var-som.dtsi”
…

2．VarisciteのEVKデバイスツリーを含め、それを拡張して、キャリアボードの
デバイスを追加および削除します。
このアプローチは、キャリアボードがVarisciteのEVKに類似している場合に最適です。
例えば：

arch/arm64/boot/dts/freescale/imx8mm-var-som-customer.dts

/dts-v1/;
#include “imx8mm-var-som-symphony.dts”
…

次に、新しいデバイスツリーをMakefileに追加して、「dtbs」Makeターゲットに
よってビルドされるようにします。

arch/arm64/boot/dts/freescale/Makefile

dtb-$(CONFIG_ARCH_MXC) += imx8mm-var-som-customer.dtb

新しいデバイスの追加

以下は、新しいデバイスノードをデバイスツリーに追加するための一般的なプロセスです。

1.デバイスツリーバインディングを見つける

新しいデバイスノードを追加する場合、最初に使用するリソースは、カーネルドキュメント
のデバイスツリー・バインディングです。
カーネルによって認識されるデバイスツリー・バインディングは、
Documentation/devicetree/bindingsに記載されています。

デバイスのデバイスツリー・バインディングを見つける1つの方法は、
デバイスモデルのDocumentationフォルダーを grep（Unixコマンド）することです。
以下の例は、一部のVariscite評価キットで使用されている
DS1337リアルタイムクロックのドキュメントを見つける方法を示しています。

linux-imx$ grep ds1337 -lr ./Documentation/

./Documentation/devicetree/bindings/rtc/rtc-ds1307.txt

2.デバイスツリーにデバイスノードを追加します

次に、バインディングのドキュメントを使用して、デバイスツリーに新しいノード
を追加します。
デバイスツリー・バインディング・ドキュメントには、デバイスの説明、
必須およびオプションのプロパティ、およびデバイスノードの例が記載されています。
例えば、DS1337リアルタイムクロック（5.4-2.3.x-imx_var01カーネルブランチから）
のドキュメントは次のとおりです。
https://github.com/varigit/linux-imx/blob/5.4-2.3.x-imx_var01/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt

同様のプラットフォーム上のノードなど、arch/arm64/boot/dtsで互換性の
ある文字列を検索することも役立ちます。

3.新しいデバイスツリーを構築、インストール、およびテストします

新しいデバイスノードを追加した後、デバイスツリーを再構築し、
ターゲットデバイスに展開して新しいデバイスをテストします。
まず、Yoctoが提供するSDKを使用して環境をセットアップします。

linux-imx$ source /opt/<sdk>/<sdk version>/environment-setup-aarch64-fslc-linux

注：SDKのインストール方法については、https://variwiki.comにアクセスし、
使用するSOMとYoctoリリースをクリックしてから、「Yoctoビルド以外の
ツールチェーンのインストール（Toolchain installation for out of
Yocto builds）」リンクをクリックしてください。

次に、デバイスツリーを構築します。

linux-imx$ make mrproper
linux-imx$ make imx8_var_defconfig
linux-imx$ make dtbs

イーサネットを使用して、デバイスツリーをターゲットデバイスに展開します。

linux-imx$ scp arch/arm64/boot/dts/freescale/imx8mn-var-som-customer.dtb root@<target ip address>:/boot/

最後に、新しいデバイスツリーを起動するようにターゲットデバイスを構成します。

root@imx8mm-var-dart:~# fw_setenv fdt_file imx8mn-var-som-customer.dtb
root@imx8mm-var-dart:~# reboot

注：カーネル構成でデバイスドライバーが有効になっていることも確認する必要があります。
詳細については、Varisciteカーネル構成ガイドを参照してください。

デバッグのヒント

デバイスツリーが起動しませんか？

デバイスツリーまたはドライバが正しく構成されていないと、システムが
起動しない可能性があります。このような状況に陥った場合は、次の
プロセスに従うと役立つ場合があります。

・デバイスノードを削除または無効にすることで起動する最小限のデバイスツリーから始めます
・一度にひとつのデバイスを追加してテストします
・小さな反復変更を行います
・新しいデバイスを追加してテストするときは、Gitを使用して変更を記録し、元に戻すための
デバイスツリーが機能するようにします

ドライバーがプロービングしませんか？

以下は、デバイスノードを追加した後にドライバーがプローブしていない場合の
デバッグのヒントです。

・カーネル構成でドライバーが有効になっていることを確認します
・デバイスツリーでデバイスが有効になっていることを確認します（ステータス=「OK」）
・デバイスのバインディングがドキュメントと一致することを確認します
・arch/arm64/boot/dtsで他の例を探してください
・ドライバーに関連するエラーがないかdmesgを確認してください

デバイスツリーを編集およびテストするためのワークフローは、数秒で実行できます。

1．デバイスツリーを編集する
2．$ make dtbs
3．$ scp arch/arm64/boot/dts/freescale/<device tree> root@<ip addr>:/boot/
4．ボードを再起動します

ワークフローが機能していて、更新されたデバイスツリーを起動していること
を確認するには、/sys/firmware/devicetreeを調べて、カーネルが更新された
デバイスツリーを正しく解析したことを確認すると便利です。

要約

デバイスツリーは、Linuxカーネルにハードウェアを記述する役割を果たします。
Varisciteは、各SOMおよび評価キットキャリアボードの
リファレンスデバイスツリーファイルを提供します。これらは、リファレンス
として使用したり、カスタムキャリアボード用に拡張したりできます。
追加のサポートについては、Varisciteのソフトウェアwikiにアクセスしてください。
Varisciteの各モジュールとサポートされているオペレーティングシステムの
詳細なガイドが提供されています。

関連リソース

ウェビナー：VarisciteSOMのデバイスツリー入門 （Getting Started with Device Tree on Variscite SOMs)
ブログ投稿：i.MXデバイスツリーのPinmux設定 （i.MX Device Tree Pinmux Settings)
ブログ投稿：Varisciteカーネル構成ガイド（Variscite Kernel Configuration Guide)
ブログ投稿：カスタムYoctoBSPレイヤーの作成 （Creating a Custom Yocto BSP Layer)