コグノスケ

ZephyrのDevice Tree Overlayと独自のbindings

目次: Zephyr

前回の続きです。ZephyrのDevice Tree Overlay（2022年1月3日の日記参照）で独自のbindingsを定義（compatibleやプロパティの定義）する方法を紹介します。

前回はこんなノードを追加しました。

/* samples/hello_world/boards/qemu_riscv64.overlay */

/ {
	resources {
		compatible = "test-overlay";
		value1 = <1>;
		value2 = <10>;
	};
};

ノードを追加しただけではエラーにはなりませんが、コードからvalue1の値を参照しようとするとビルドエラーになって怒られます。

詳細はZephyrのDevice Tree APIマニュアル（Devicetree API - Zephyr Project Documentation）が参考になります。

// samples/hello_world/src/main.c

#include <zephyr.h>
#include <sys/printk.h>

void main(void)
{
	printk("Hello World! %s\n", CONFIG_BOARD);

	printk("value1:%d\n", DT_PROP(DT_INST(0, test_overlay), value1));
	printk("value2:%d\n", DT_PROP(DT_INST(0, test_overlay), value2));
}

$ ninja
...

zephyr/include/generated/devicetree_unfixed.h:308:34: error: 'DT_N_S_resources_P
_value1' undeclared (first use in this function); did you mean 'DT_N_S_resources
_PATH'?
  308 | #define DT_N_INST_0_test_overlay DT_N_S_resources
      |                                  ^~~~~~~~~~~~~~~~

このあとも大量に怒られる……。

Zephyrはコード内でデバイスツリーの値を参照すると、ビルド時に全て解決される仕組みです。そのためデバイスツリーに不都合な点があるとビルド時に猛烈に怒られます。Zephyrのデバイスツリー処理はPythonとマクロマジックが駆使されていて、コンパイルエラーのメッセージからエラーの原因がすぐにわからないのが難点ですね……。

Linuxは実行時に参照、書き換えが可能なので、ZephyrとLinuxの大きく異なる部分と言えましょう。

デバイスツリー定義yamlファイル

問題の解決にはdts/*.yamlを追加する必要があります。ファイル名はcompatible名.yamlになります。このファイルもOverlayファイル同様に追加するだけでビルドシステムが勝手に感知して処理してくれます。便利ですね。

samples/hello_world/
├──CMakeLists.txt
├──README.rst
├──boards
│   └──qemu_riscv64.overlay
├──dts
│   └──bindings
│       └──test-overlay.yaml    ★これ★
├──prj.conf
├──sample.yaml
└──src
    └──main.c

# samples/hello_world/dts/bindings/test-overlay.yaml


description: |
    This binding provides AAA and BBB, something for CCC application in Zephyr.

compatible: "test-overlay"

properties:
    value1:
        type: int
        required: true
        description: |
          Identity of AAA of something. This is ...

    value2:
        type: int
        required: true
        description: |
          Identity of BBB of something. This is ...

追加したyamlファイルは非常にシンプルで、compatibleの名前と、value1, value2というint型のプロパティが必須だよ、ということを定義しただけです。

その他のbindingsの定義については、Zephyrのマニュアル（Devicetree bindings - Zephyr Project Documentation）をご覧ください。

ファイルを追加したら改めてビルド＆実行しましょう。

$ ninja
...

[123/123] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
             RAM:       23700 B       256 MB      0.01%
        IDT_LIST:          0 GB         2 KB      0.00%


$ ninja run

[0/1] To exit from QEMU enter: 'CTRL+a, x'[QEMU] CPU: riscv64
*** Booting Zephyr OS build v2.7.99-3416-g7dac931e3662  ***
Hello World! qemu_riscv64
value1:1
value2:10

うまく行きました。Device Tree Overlayとbindingsは同じCコードでボードごとに設定だけ変えたい場合に有用です。

この仕組みはtests下にあるコードでよく使われています。例えばGPIOのテストがわかりやすいでしょう。2つのポートが通信できるか？割り込みが正常に入るか？などがGPIOテストの内容です。

実際に動作させるにはボードごとに配線やピン設定が違いますから、ボードAはピン10と11を使う、ボードBは21と22を使う、というようにボードごとに違う設定を与える必要があります。

設定はコードに書かずにDevice Tree Overlayに逃がして、コードはテストしたい内容のみを記述することで設定もコードもすっきりする、ってわけです。