#Device Treeとは
Device TreeはLinuxで採用されており、ARMで複雑化するデバイス構成を一元管理できるように考案されたもの(らしい)です。
なかなかジャストな説明を見つけるのは難しいですが、このあたりとか参考になりそうな気がします。
なお、本家はこちらですがZephyrのDTSはDeviceTreeを踏襲しているというだけで仕様まで完全に同じというわけではなさそうです。
あとこちらも
#なぜDevice Treeを読めるようにならないといけないか
自分が何を書いているか分からなくなったからです(笑)
ほら、サンプルプロジェクトをなんとなくコピーすると動くんだけどさ、DT_GPIO_PIN()とかDT_GPIO_LABEL()とかが実体として何をやっているか全く分からない、って思いませんか？
僕がはっきりとそう感じたのはGPIOとGPIOTEの時でした。
このままではITドカタと同レベルですよ、ええ(笑)
#いや、だけどさ
その程度のことは検索すれば分かるんだよ！でも読むのめんどくせぇんだよ！
分かります(笑)、だって僕も読むのめんどくさいですから。
だから簡単にまとめてくれている人を探すんですよね、分かりますとも(笑)
ということで・・・。
#とその前に
私が自分自身で試行錯誤して理解している範囲では、ZephyrにおいてDTSというのはあくまでもオプション的扱いだと受け止めています。超汎用仕様で様々なCPU/Boardで動くようなファームウェアを設計するのであれば話は別ですが、99.9%のファームウェア開発においてはそんなことはありえなく、弊社専用(笑)のガチガチの仕様のものが1個あるだけです。
そのような状況下においてDTSから読み込んでI/Oピンその他の設定をするというのはとてもお行儀のよい設計ではありますが、一方でDTSなんかガン無視してベタ書き(例えばPIN10はLEDを制御)であっても特に問題は起こらないわけです。なぜなら汎用のものを作っているわけではないから。
部品がディスコンになってリメイクするときに少々問題が発生するかも知れませんが、それだって修正はたかが知れています。
ただ、それを差し引いてもDTSが読めないよりは読めたほうがいいんじゃないかとは思います。
#Nordic評価ボードのデバイスツリーを読み解く
実際に評価ボードのDTSファイルを使って説明していこうと思いますが、記述を説明すると非常に長くなってキリがないので、DTS上にある記述をどうやってファームウェア側で読み取ればよいのかという視点で見ていこうと思います。
(非常に長いのでデフォルトで折りたたんでいます)
nRF52832DKのDTS
52832.dts
/*
* Copyright (c) 2017 Shawn Nock <shawn@monadnock.ca>
* Copyright (c) 2017 Linaro Limited
*
* SPDX-License-Identifier: Apache-2.0
*/
/dts-v1/;
#include <nordic/nrf52832_qfaa.dtsi>
/ {
model = "Nordic nRF52 DK NRF52832";
compatible = "nordic,nrf52-dk-nrf52832";
chosen {
zephyr,console = &uart0;
zephyr,shell-uart = &uart0;
zephyr,uart-mcumgr = &uart0;
zephyr,bt-mon-uart = &uart0;
zephyr,bt-c2h-uart = &uart0;
zephyr,sram = &sram0;
zephyr,flash = &flash0;
zephyr,code-partition = &slot0_partition;
};
leds {
compatible = "gpio-leds";
led0: led_0 {
gpios = <&gpio0 17 GPIO_ACTIVE_LOW>;
label = "Green LED 0";
};
led1: led_1 {
gpios = <&gpio0 18 GPIO_ACTIVE_LOW>;
label = "Green LED 1";
};
led2: led_2 {
gpios = <&gpio0 19 GPIO_ACTIVE_LOW>;
label = "Green LED 2";
};
led3: led_3 {
gpios = <&gpio0 20 GPIO_ACTIVE_LOW>;
label = "Green LED 3";
};
};
pwmleds {
compatible = "pwm-leds";
pwm_led0: pwm_led_0 {
pwms = <&pwm0 17>;
};
};
buttons {
compatible = "gpio-keys";
button0: button_0 {
gpios = <&gpio0 13 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 0";
};
button1: button_1 {
gpios = <&gpio0 14 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 1";
};
button2: button_2 {
gpios = <&gpio0 15 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 2";
};
button3: button_3 {
gpios = <&gpio0 16 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 3";
};
};
arduino_header: connector {
compatible = "arduino-header-r3";
#gpio-cells = <2>;
gpio-map-mask = <0xffffffff 0xffffffc0>;
gpio-map-pass-thru = <0 0x3f>;
gpio-map = <0 0 &gpio0 3 0>, /* A0 */
<1 0 &gpio0 4 0>, /* A1 */
<2 0 &gpio0 28 0>, /* A2 */
<3 0 &gpio0 29 0>, /* A3 */
<4 0 &gpio0 30 0>, /* A4 */
<5 0 &gpio0 31 0>, /* A5 */
<6 0 &gpio0 11 0>, /* D0 */
<7 0 &gpio0 12 0>, /* D1 */
<8 0 &gpio0 13 0>, /* D2 */
<9 0 &gpio0 14 0>, /* D3 */
<10 0 &gpio0 15 0>, /* D4 */
<11 0 &gpio0 16 0>, /* D5 */
<12 0 &gpio0 17 0>, /* D6 */
<13 0 &gpio0 18 0>, /* D7 */
<14 0 &gpio0 19 0>, /* D8 */
<15 0 &gpio0 20 0>, /* D9 */
<16 0 &gpio0 22 0>, /* D10 */
<17 0 &gpio0 23 0>, /* D11 */
<18 0 &gpio0 24 0>, /* D12 */
<19 0 &gpio0 25 0>, /* D13 */
<20 0 &gpio0 26 0>, /* D14 */
<21 0 &gpio0 27 0>; /* D15 */
};
arduino_adc: analog-connector {
compatible = "arduino,uno-adc";
#io-channel-cells = <1>;
io-channel-map = <0 &adc 1>, /* A0 = P0.3 = AIN1 */
<1 &adc 2>, /* A1 = P0.4 = AIN2 */
<2 &adc 4>, /* A2 = P0.28 = AIN4 */
<3 &adc 5>, /* A3 = P0.29 = AIN5 */
<4 &adc 6>, /* A4 = P0.30 = AIN6 */
<5 &adc 7>; /* A5 = P0.31 = AIN7 */
};
/* These aliases are provided for compatibility with samples */
aliases {
led0 = &led0;
led1 = &led1;
led2 = &led2;
led3 = &led3;
pwm-led0 = &pwm_led0;
sw0 = &button0;
sw1 = &button1;
sw2 = &button2;
sw3 = &button3;
bootloader-led0 = &led0;
};
};
&adc {
status = "okay";
};
&gpiote {
status = "okay";
};
&gpio0 {
status = "okay";
};
arduino_serial: &uart0 {
status = "okay";
compatible = "nordic,nrf-uarte";
current-speed = <115200>;
tx-pin = <6>;
rx-pin = <8>;
rts-pin = <5>;
cts-pin = <7>;
};
arduino_i2c: &i2c0 {
compatible = "nordic,nrf-twi";
status = "okay";
sda-pin = <26>;
scl-pin = <27>;
};
&i2c1 {
compatible = "nordic,nrf-twi";
/* Cannot be used together with spi1. */
/* status = "okay"; */
sda-pin = <30>;
scl-pin = <31>;
};
&pwm0 {
status = "okay";
ch0-pin = <17>;
ch0-inverted;
};
&spi0 {
compatible = "nordic,nrf-spi";
/* Cannot be used together with i2c0. */
/* status = "okay"; */
sck-pin = <27>;
mosi-pin = <26>;
miso-pin = <28>;
};
&spi1 {
compatible = "nordic,nrf-spi";
status = "okay";
sck-pin = <31>;
mosi-pin = <30>;
miso-pin = <29>;
};
arduino_spi: &spi2 {
compatible = "nordic,nrf-spi";
status = "okay";
sck-pin = <25>;
mosi-pin = <23>;
miso-pin = <24>;
cs-gpios = <&arduino_header 16 GPIO_ACTIVE_LOW>; /* D10 */
};
&flash0 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
boot_partition: partition@0 {
label = "mcuboot";
reg = <0x00000000 0xc000>;
};
slot0_partition: partition@c000 {
label = "image-0";
reg = <0x0000C000 0x32000>;
};
slot1_partition: partition@3e000 {
label = "image-1";
reg = <0x0003E000 0x32000>;
};
scratch_partition: partition@70000 {
label = "image-scratch";
reg = <0x00070000 0xa000>;
};
storage_partition: partition@7a000 {
label = "storage";
reg = <0x0007a000 0x00006000>;
};
};
};
nRF52840-DKのDTS
52840.dts
/*
* Copyright (c) 2017 Linaro Limited
*
* SPDX-License-Identifier: Apache-2.0
*/
/dts-v1/;
#include <nordic/nrf52840_qiaa.dtsi>
/ {
model = "Nordic nRF52840 DK NRF52840";
compatible = "nordic,nrf52840-dk-nrf52840";
chosen {
zephyr,console = &uart0;
zephyr,shell-uart = &uart0;
zephyr,uart-mcumgr = &uart0;
zephyr,bt-mon-uart = &uart0;
zephyr,bt-c2h-uart = &uart0;
zephyr,sram = &sram0;
zephyr,flash = &flash0;
zephyr,code-partition = &slot0_partition;
};
leds {
compatible = "gpio-leds";
led0: led_0 {
gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
label = "Green LED 0";
};
led1: led_1 {
gpios = <&gpio0 14 GPIO_ACTIVE_LOW>;
label = "Green LED 1";
};
led2: led_2 {
gpios = <&gpio0 15 GPIO_ACTIVE_LOW>;
label = "Green LED 2";
};
led3: led_3 {
gpios = <&gpio0 16 GPIO_ACTIVE_LOW>;
label = "Green LED 3";
};
};
pwmleds {
compatible = "pwm-leds";
pwm_led0: pwm_led_0 {
pwms = <&pwm0 13>;
};
};
buttons {
compatible = "gpio-keys";
button0: button_0 {
gpios = <&gpio0 11 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 0";
};
button1: button_1 {
gpios = <&gpio0 12 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 1";
};
button2: button_2 {
gpios = <&gpio0 24 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 2";
};
button3: button_3 {
gpios = <&gpio0 25 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
label = "Push button switch 3";
};
};
arduino_header: connector {
compatible = "arduino-header-r3";
#gpio-cells = <2>;
gpio-map-mask = <0xffffffff 0xffffffc0>;
gpio-map-pass-thru = <0 0x3f>;
gpio-map = <0 0 &gpio0 3 0>, /* A0 */
<1 0 &gpio0 4 0>, /* A1 */
<2 0 &gpio0 28 0>, /* A2 */
<3 0 &gpio0 29 0>, /* A3 */
<4 0 &gpio0 30 0>, /* A4 */
<5 0 &gpio0 31 0>, /* A5 */
<6 0 &gpio1 1 0>, /* D0 */
<7 0 &gpio1 2 0>, /* D1 */
<8 0 &gpio1 3 0>, /* D2 */
<9 0 &gpio1 4 0>, /* D3 */
<10 0 &gpio1 5 0>, /* D4 */
<11 0 &gpio1 6 0>, /* D5 */
<12 0 &gpio1 7 0>, /* D6 */
<13 0 &gpio1 8 0>, /* D7 */
<14 0 &gpio1 10 0>, /* D8 */
<15 0 &gpio1 11 0>, /* D9 */
<16 0 &gpio1 12 0>, /* D10 */
<17 0 &gpio1 13 0>, /* D11 */
<18 0 &gpio1 14 0>, /* D12 */
<19 0 &gpio1 15 0>, /* D13 */
<20 0 &gpio0 26 0>, /* D14 */
<21 0 &gpio0 27 0>; /* D15 */
};
arduino_adc: analog-connector {
compatible = "arduino,uno-adc";
#io-channel-cells = <1>;
io-channel-map = <0 &adc 1>, /* A0 = P0.3 = AIN1 */
<1 &adc 2>, /* A1 = P0.4 = AIN2 */
<2 &adc 4>, /* A2 = P0.28 = AIN4 */
<3 &adc 5>, /* A3 = P0.29 = AIN5 */
<4 &adc 6>, /* A4 = P0.30 = AIN6 */
<5 &adc 7>; /* A5 = P0.31 = AIN7 */
};
/* These aliases are provided for compatibility with samples */
aliases {
led0 = &led0;
led1 = &led1;
led2 = &led2;
led3 = &led3;
pwm-led0 = &pwm_led0;
sw0 = &button0;
sw1 = &button1;
sw2 = &button2;
sw3 = &button3;
bootloader-led0 = &led0;
};
};
&adc {
status = "okay";
};
&gpiote {
status = "okay";
};
&gpio0 {
status = "okay";
};
&gpio1 {
status = "okay";
};
&uart0 {
compatible = "nordic,nrf-uarte";
status = "okay";
current-speed = <115200>;
tx-pin = <6>;
rx-pin = <8>;
rx-pull-up;
rts-pin = <5>;
cts-pin = <7>;
cts-pull-up;
};
arduino_serial: &uart1 {
status = "okay";
current-speed = <115200>;
rx-pin = <33>;
rx-pull-up;
tx-pin = <34>;
};
arduino_i2c: &i2c0 {
compatible = "nordic,nrf-twi";
status = "okay";
sda-pin = <26>;
scl-pin = <27>;
};
&i2c1 {
compatible = "nordic,nrf-twi";
/* Cannot be used together with spi1. */
/* status = "okay"; */
sda-pin = <30>;
scl-pin = <31>;
};
&pwm0 {
status = "okay";
ch0-pin = <13>;
ch0-inverted;
};
&spi0 {
compatible = "nordic,nrf-spi";
/* Cannot be used together with i2c0. */
/* status = "okay"; */
sck-pin = <27>;
mosi-pin = <26>;
miso-pin = <29>;
};
&spi1 {
compatible = "nordic,nrf-spi";
status = "okay";
sck-pin = <31>;
mosi-pin = <30>;
miso-pin = <40>;
};
&spi2 {
compatible = "nordic,nrf-spi";
status = "disabled";
sck-pin = <19>;
mosi-pin = <20>;
miso-pin = <21>;
};
&qspi {
status = "okay";
sck-pin = <19>;
io-pins = <20>, <21>, <22>, <23>;
csn-pins = <17>;
mx25r64: mx25r6435f@0 {
compatible = "nordic,qspi-nor";
reg = <0>;
/* MX25R64 supports only pp and pp4io */
writeoc = "pp4io";
/* MX25R64 supports all readoc options */
readoc = "read4io";
sck-frequency = <8000000>;
label = "MX25R64";
jedec-id = [c2 28 17];
sfdp-bfp = [
e5 20 f1 ff ff ff ff 03 44 eb 08 6b 08 3b 04 bb
ee ff ff ff ff ff 00 ff ff ff 00 ff 0c 20 0f 52
10 d8 00 ff 23 72 f5 00 82 ed 04 cc 44 83 68 44
30 b0 30 b0 f7 c4 d5 5c 00 be 29 ff f0 d0 ff ff
];
size = <67108864>;
has-dpd;
t-enter-dpd = <10000>;
t-exit-dpd = <35000>;
};
};
arduino_spi: &spi3 {
status = "okay";
sck-pin = <47>;
miso-pin = <46>;
mosi-pin = <45>;
cs-gpios = <&arduino_header 16 GPIO_ACTIVE_LOW>; /* D10 */
};
&flash0 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
boot_partition: partition@0 {
label = "mcuboot";
reg = <0x000000000 0x0000C000>;
};
slot0_partition: partition@c000 {
label = "image-0";
reg = <0x0000C000 0x00067000>;
};
slot1_partition: partition@73000 {
label = "image-1";
reg = <0x00073000 0x00067000>;
};
scratch_partition: partition@da000 {
label = "image-scratch";
reg = <0x000da000 0x0001e000>;
};
/*
* The flash starting at 0x000f8000 and ending at
* 0x000fffff is reserved for use by the application.
*/
/*
* Storage partition will be used by FCB/LittleFS/NVS
* if enabled.
*/
storage_partition: partition@f8000 {
label = "storage";
reg = <0x000f8000 0x00008000>;
};
};
};
zephyr_udc0: &usbd {
compatible = "nordic,nrf-usbd";
status = "okay";
};
leds {
compatible = "gpio-leds";
led0: led_0 {
gpios = <&gpio0 17 GPIO_ACTIVE_LOW>;
label = "Green LED 0";
};
・・・
#プロパティを取得する
実際には使うことはないかも知れませんが、上記LEDに記載されているlabelの内容を取得したい場合にはDT_PROP()およびDT_NODELABEL()マクロを使用します。ここで引数として与えられているled0はled_0に付けられているラベルを指しています。
/*
* Copyright (c) 2012-2014 Wind River Systems, Inc.
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <zephyr.h>
#include <sys/printk.h>
void main(void)
{
printk("Label is %s\n", DT_PROP(DT_NODELABEL(led0), label));
}
DTSにおいては、ノード名を直接指定して何かすることはできません。(少なくとも僕が現時点で理解している範囲では)
操作したいノードには必ずラベルが必要です。
また、上記のled_0については以下の記述でも同様の結果を得られます。
/*
* Copyright (c) 2012-2014 Wind River Systems, Inc.
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <zephyr.h>
#include <sys/printk.h>
void main(void)
{
printk("Label is %s\n", DT_PROP(DT_ALIAS(led0), label));
}
ただし、ここで指定しているled0は先ほどのled0ではなくエイリアスのled0になります。エイリアスのled0とは、もう少し下の方に記述がありますが、
/* These aliases are provided for compatibility with samples */
aliases {
led0 = &led0;
led1 = &led1;
led2 = &led2;
led3 = &led3;
pwm-led0 = &pwm_led0;
sw0 = &button0;
sw1 = &button1;
sw2 = &button2;
sw3 = &button3;
bootloader-led0 = &led0;
};
のことを指します。これは標準で記述されているDTSファイルがよろしくないのですが、ラベルとエイリアスが同じled0なのでちゃんと理解できていないと混乱することになります。試しにエイリアスの方をledled0とか違う名前に変えてみると理解できると思います。
##存在しないラベルやエイリアスはコンパイルエラーになる
ところでこのラベル、どうやって判定しているのかというと実はCMakeでコンパイルするときにDTSファイルを展開して#defineを作っているようです。
なので、存在しないラベルやエイリアスを指定したり、間違ったマクロを使ったりするとコンパイル時に#defineが存在していないためコンパイルエラーになります。例えばpwm_led0のDTSに対して
printk("Label is %s\n", DT_PROP(DT_NODELABEL(pwm_led0), label));
と記述してコンパイルしようとするとエラーで止まってしまいます。理由はDTSファイル内のノードがlabelプロパティを持っていないからですね。
pwmleds {
compatible = "pwm-leds";
pwm_led0: pwm_led_0 {
pwms = <&pwm0 17>;
};
};
ですので、このpwm_led0にlabelプロパティを持たせてあげるとコンパイルが通るようになります。
pwmleds {
compatible = "pwm-leds";
pwm_led0: pwm_led_0 {
pwms = <&pwm0 17>;
label = "PWM for LED 0";
};
};