By Toradex 胡珊逢
1). 简介
目前较新的 Linux 内核都支持Device Tree 来管理外设，这对嵌入式设备来说显得尤为重要。通过单独的 Device Tree 文件，可以有效减少因外设更改而重新编译 Linux 内核的工作量。而随着 SoC 的复杂程度与日俱增，Device Tree 本身也开始变得复杂。Device Tree Overlays （DTO）则提供一种简洁的方式来更改 Device Tree 。下面我们将在Apalis iMX8QM 计算机模块上介绍如何针对 Toradex Linux BSP v5.0 配置 Device Tree Overlays。
本文就基于NXP最新的iMX8 SoC（基于Cortex-A72+A53和Coretex-M4架构）ARM平台介绍如何配置 Device Tree Overlays。演示平台来自于Toradex 基于iMX8QM的Apalis iMX8QM ARM嵌入式模块平台。
2). 测试流程
首先我们需要下载所需的编译工具和 Linux 内核源码，具体的方法参考我们开发者中心的网页，如果想要在 Windows 上使用 WSL 进行编译，也可以阅读该博文。
使用 git 下载 Linux 内核源码
--------------------------
git clone -b toradex_5.4-2.1.x-imx git://git.toradex.cn/linux-toradex.git
--------------------------
我们还提供了适用于一些外设如 LVDS 显示屏、电容触摸屏控制器等现成 Device Tree Overlays 文件，这可以作为学习 Device Tree Overlays 的开始。
--------------------------
git clone -b toradex_5.4-2.1.x-imx git://git.toradex.cn/device-tree-overlays.git
--------------------------
Device Tree Overlay 的使用分为三个步骤，编写 Device Tree Overlay 文件 dts，将 dts 文件编译生成 dtbo 文件，部署 dtbo 文件。我们将用 Apalis iMX8QM 的一个 SD 接口为例，将 SD_DATA0 和 SD_DATA1 配置 GPIO。
首先根据 Apalis iMX8QM datasheet 确定使用的引脚，MXM3_186 和 MXM3_188，其对应的 GPIO 为 LSIO.GPIO5.IO26 和 LSIO.GPIO5.IO27。
然后开始编译 test_overlay.dts 文件。
--------------------------
/dts-v1/;
/plugin/;
/ {
compatible = "toradex,apalis-imx8";
};
--------------------------
compatible 属性指定该device tree overlay 文件适用的硬件，对应于 imx8qm-apalis-eval.dts 。
在默认配置中 MXM3_186 和 MXM3_188 用于 4-bit SD 通道，因此需要将该功能禁用。在 device tree 中，该 4-bit SD 通道对应的名字为 usdhc3。
--------------------------
&usdhc3 {
status = "disabled";
};
--------------------------
在 iMX8QM 上 iomuxc 单元管理引脚复用的配置。Apalis iMX8QM 默认配置中已经有8 个GPIO，但是部分被用于其他设备如风扇电源控制等。我们这里增加两个新的 GPIO ，pinctrl_gpio9 和 pinctrl_gpio10。在 test_overlay.dts 增加，这里的iomuxc/pinctrl-0 属性将会覆盖原来的配置。
--------------------------
--------------------------
接下来需要把 MXM3_186 和 MXM3_188 配置为 GPIO 模式。在上面我们已经知道 MXM3_186 和 MXM3_188对应的 GPIO 为 LSIO.GPIO5.IO26 和 LSIO.GPIO5.IO27，Ball name 为 USDHC2_DATA0 和 USDHC2_DATA1。根据这个写信息，在 pads-imx8qm.h 中找对引脚对应的表示名称，IMX8QM_USDHC2_DATA0_LSIO_GPIO5_IO26 和 IMX8QM_USDHC2_DATA1_LSIO_GPIO5_IO27。在 test_overlay.dts 的 iomuxc 节点中添加
--------------------------
--------------------------
至此，test_overlay.dts 文件已经完成，完整文件可以从这里下载。将 test_overlay.dts 复制到刚才下载的 device-tree-overlays/ overlays 目录下。
--------------------------
$ tree -L 2
.
├── device-tree-overlays
│ └── overlays
└── linux-toradex
--------------------------
然后执行下面两条命令生成test_overlay.dtbo文件。这里使用 -I 和 -i 参数指定 Linux 内核源码相关目录。
--------------------------
cpp -nostdinc -I ../../linux-toradex/arch/arm64/boot/dts/freescale -I ../../linux-toradex/include -undef -x assembler-with-cpp test_overlay.dts test_overlay.dts.preprocessed
dtc -@ -Hepapr -I dts -O dtb -i ../../linux-toradex/arch/arm64/boot/dts/freescale/ -o test_overlay.dtbo test_overlay.dts.preprocessed
--------------------------
最后需要把 test_overlay.dtbo 部署到 Apalis iMX8QM。将该文件复制到 /media/mmcblk0p1/overlays 目录中，然后修改 /media/mmcblk0p1/overlays.txt 文件。执行 reboot 命令重启系统。
--------------------------
fdt_overlays=overlays/test_overlay.dtbo
--------------------------
启动后可以在串口日志中发现 overlays/test_overlay.dtbo 被读取并应用到系统。
--------------------------
## Executing script at 83100000
102464 bytes read in 19 ms (5.1 MiB/s)
Loading hdp firmware from 0x000000009c000000 offset 0x0000000000002000
Loading hdp firmware Complete
162517 bytes read in 23 ms (6.7 MiB/s)
40 bytes read in 16 ms (2 KiB/s)
Applying Overlay: overlays/test_overlay.dtbo
272 bytes read in 29 ms (8.8 KiB/s)
9805442 bytes read in 316 ms (29.6 MiB/s)
Uncompressed size: 23144960 = 0x1612A00
## Flattened Device Tree blob at 83000000
Booting using the fdt blob at 0x83000000
Loading Device Tree to 00000000fd603000, end 00000000fd64dfff ... OK
--------------------------
进入系统后可以对这两个引脚进行操作。在 Linux 系统中会使用对应的 GPIO 编号来访问引脚，对应的关系可以参考这里。LSIO.GPIO05.IO26（MXM3_186）和 LSIO.GPIO05.IO27（MXM3_188）分别对应 346 和 347。然后执行下面将其配置为输出模式。
--------------------------
root@apalis-imx8:~# echo 346 > /sys/class/gpio/export
root@apalis-imx8:~# echo 347 > /sys/class/gpio/export
root@apalis-imx8:~# echo "out" > /sys/class/gpio/gpio346/direction
root@apalis-imx8:~# echo "out" > /sys/class/gpio/gpio347/direction
root@apalis-imx8:~# cat /sys/kernel/debug/gpio
gpio-346 (MXM3_186 |sysfs ) out lo
gpio-347 (MXM3_188 |sysfs ) out lo
--------------------------
以下命令可以在对应引脚上设置高/低电平。
--------------------------
root@apalis-imx8:~# echo 1 > /sys/class/gpio/gpio346/value
root@apalis-imx8:~# echo 1 > /sys/class/gpio/gpio347/value
root@apalis-imx8:~# echo 0 > /sys/class/gpio/gpio346/value
root@apalis-imx8:~# echo 0 > /sys/class/gpio/gpio347/value
--------------------------
Device tree 是 Linux 内核的重要文件，如果配置不当有可能导致系统启动失败。一旦出现这种情况，可以将 Apalis iMX8QM 的 USB OTG 连接到电脑，然后在 U-boot 中执行下面命令后会将 Apalis iMX8QM 启动文件挂载到电脑，删除 overlays.txt 文件中配置的参数。保存后可以使用默认的 device tree 启动系统。
--------------------------
ums 0 mmc 0
--------------------------
4). 总结
Device tree 可以使用户以较少配置更改来使用新的外设，避免编译整个 device tree。
参考：
https://developer.toradex.cn/device-tree-overlays-linux#Deploying_a_Device_Tree_Overlay
https://developer.toradex.cn/knowledge-base/device-tree-overlays
https://www.raspberrypi.org/documentation/configuration/device-tree.md
