これまで devicetree の binding を示すドキュメントは単純テキストで記載されていました。このテキストは LKML でレビューされるものの、フォーマットが統一されていないばかりかドキュメント通りに devicetree を書かなくてもチェックすることができず、問題になっていたようです。
そこで以前より、ドキュメントを統一フォーマットに則ってYAML 形式で記述する方針となり、チェックする仕組みである DT Schema が導入されてきました。YAML 形式への移行はドキュメントの maintainer の判断に委ねられているため完全に移行したわけではありませんが、バージョンが上がるごとに移行が進んでいます。常にチェックが実施できるため、仕様に沿わないドキュメントや devicetree を発見することができます。
Devicetree の binding ドキュメント
devicetree を記述する方なら必ずドキュメントを参照するかと思います。ドキュメントは Linux ソースツリーの Documentation/devicetree/binding 以下にあります。拡張子が .yaml となっているのが今回の対象となる YAML 形式のドキュメントです。
DT Schema の仕組み
上記の LPC2018 での Rob Herring 氏の資料によると、YAML で記述されたドキュメントを Schema に照らし合わせることで文法チェックを行い、その結果と devicetree の YAML 変換したものとを照合することで devicetree 自身が正しく書かれているかをチェックしています。この一連のチェックの仕組みが DT Schema になります。
DT Schema のインストール
Driver の contribution を行わない限り binding ドキュメントを書く機会はないかもしれませんが、contributor が使っている仕組みを実際に動かしてみるのも興味深いです。
まず、必要なパッケージをインストールします。Python ベースのツールなのでこれは必須です。
sudo apt install libyaml-dev python3 pip3 yamllint swigpip3 (Python パッケージ管理ツール) を使って DT Schema 本体をインストールします。ここではユーザ側にインストールすることにしています。
pip3 install --user git+https://github.com/devicetree-org/dt-schema.git@masterユーザごとのディレクトリにインストールするので、インストール先は ~/.local になります。そのため環境変数 PATH に ~/.local/bin を加えておく必要があります。
export PATH=${PATH}:${HOME}/.local/binDT Schema は実行時にバージョンをチェックするため、古いバージョンのままだとチェック時に受け付けてくれません。以下のようにして最新版に保っておきます。
pip3 install --user --upgrade git+https://github.com/devicetree-org/dt-schema.git@masterDT Schema によるドキュメントチェック
binding ドキュメントのチェックは Linux ツリーにて以下のコマンドで行います。
make dt_binding_check上記は全てのドキュメントをチェックするため時間が掛かります。単一ドキュメントをチェックしたい場合は以下のように DT_SCHEMA_FILES でドキュメントを指定することで時間を節約できます。
make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/xxx/yyy.yamldevicetree のチェックは以下で行います。dt_binding_check が実行されていなければ先行して実施されます。このチェックは単一ファイルを指定できないため、ARCH で指定したツリー上のすべての dts ファイルに対してチェックを行います。
make ARCH=arm64 defconfig
make ARCH=arm64 dtbs_check
補足
python ライブラリの依存関係は上記のインストール手順で解決するはずですが、環境によってはうまくいかないこともあるようです。手元で遭遇したのは ruamel.yaml のエラーでした。別途 upgrade して解決しています。
pip3 install -U ruamel.yaml
kernel v5.13 以降では YAML 書式の厳密なチェックができるようになっています。dt_binding_check 実行時にオプション "DT_CHECKER_FLAGS=-m" を追加します(実施には yamllint のインストールが必要です)。
make dt_binding_check DT_CHECKER_FLAGS=-m DT_SCHEMA_FILES=Documentation/devicetree/bindings/xxx/yyy.yaml
コメント