定位并修改设备树 - Qualcomm Dragonwing Documentation

每个 Qualcomm^® Linux 开发板的设备树源文件位于 arch/arm64/boot/dts/qcom/ 目录中，遵循 SoC/开发板两层结构。下文提供平台详情、对应的设备树，以及平台移植（bring-up）中常见的定制模式。

设备树源文件位置

所有 Qualcomm^® DTS 和 DTSI 文件位于内核源码树的以下目录下：

arch/arm64/boot/dts/qcom/

文件命名约定遵循与 Yocto 机器配置相同的 <SoC>-<board>-<variant> 模式。有关各目标平台的 DTS 文件列表，请参阅下方的定位目标平台的 DTS 文件。

定位目标平台的 DTS 文件

conf/machine/<SoC>-<board>-<variant>.conf 中的 KERNEL_DEVICETREE 变量决定构建和打包哪些 DTB：

KERNEL_DEVICETREE = " \
                     qcom/<SoC>-<board>-<variant>.dtb \
                     "

QCS6490
IQ-9075
IQ-8275
IQ-615

表：Qualcomm 设备树源 — Dragonwing^™ RB3 Gen 2

设备树源	详情
`arch/arm64/boot/dts/qcom/sc7280.dtsi`	QCS6490 SoC 派生自 SC7280 SoC。
`arch/arm64/boot/dts/qcom/qcs6490-rb3gen2.dts`	QCS6490 Dragonwing™ RB3 Gen 2 开发套件的设备树源。
`arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-vision-mezzanine.dts`	QCS6490 Dragonwing™ RB3 Gen 2 视觉夹层板（Mezzanine）开发套件。
`arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-industrial-mezzanine.dts`	QCS6490 Dragonwing™ RB3 Gen 2 工业夹层板（Mezzanine）开发套件。

表：Qualcomm 设备树源 — Dragonwing™ IQ-9075

设备树源	详情
`arch/arm64/boot/dts/qcom/lemans.dtsi`	Dragonwing^™ IQ-9075 SoC 派生自 Lemans。
`arch/arm64/boot/dts/qcom/lemans-el2.dtso`	应用于所有 IQ-9075 开发板变体、面向 KVM 环境的 EL2 叠加层。
`arch/arm64/boot/dts/qcom/lemans-ride-common.dtsi`	基于 Lemans 的 Qualcomm Linux 开发套件的通用 DTSI。
`arch/arm64/boot/dts/qcom/qcs9100-ride.dts` 和 `qcs9100-ride-r3.dts`	面向 Dragonwing^™ IQ-9075 ride 的 Qualcomm Linux 开发套件。
`arch/arm64/boot/dts/qcom/lemans-evk.dts`	面向 Dragonwing^™ IQ-9075 EVK 的 Qualcomm Linux 开发套件。

表：Qualcomm 设备树源 — Dragonwing™ IQ-8275

设备树源	详情
`arch/arm64/boot/dts/qcom/qcs8300.dtsi`	Dragonwing^™ IQ-8275 SoC 派生自 QCS8300（Monaco）。
`arch/arm64/boot/dts/qcom/monaco-el2.dtso`	应用于所有 IQ-8275 开发板变体、面向 KVM 环境的 EL2 叠加层。
`arch/arm64/boot/dts/qcom/qcs8300-ride.dts`	面向 Dragonwing^™ IQ-8275 ride 的 Qualcomm Linux 开发套件。
`arch/arm64/boot/dts/qcom/monaco-evk.dts`	面向 Dragonwing^™ IQ-8275 EVK 的 Qualcomm Linux 开发套件。
`arch/arm64/boot/dts/qcom/monaco-staging.dtso`	承载尚未进入上游 Monaco DTSI 的节点的 staging 叠加层。
`arch/arm64/boot/dts/qcom/monaco-evk-camx.dtso`	面向 IQ-8275 EVK 的 CAMX 相机叠加层。

表：Qualcomm 设备树源 — Dragonwing™ IQ-615

设备树源	详情
`arch/arm64/boot/dts/qcom/qcs615.dtsi`	Dragonwing IQ-615 SoC 的基础配置文件。
`arch/arm64/boot/dts/qcom/qcs615-ride.dts`	Dragonwing IQ-615 ride 的基础配置文件。

在内核 v6.19 及更高版本中，SoC DTSI 名称已更新以反映实际的 SoC 名称：sc7280.dtsi → kodiak.dtsi、qcs8300.dtsi → monaco.dtsi、qcs615.dtsi → talos.dtsi。

后缀为 el2 的设备树文件支持 Linux 在异常级别 2（EL2）运行以用于 KVM。仅当 Linux 必须作为 KVM 虚拟机监控器（hypervisor）运行时，才使用 EL2 专用的 DTB。

常见定制模式

以下列出使用设备树进行的常见定制。

启用或禁用外设节点

要启用在 SoC DTSI 中已声明但被禁用的节点：

/* In your board DTS, override the status property */
&uart5 {
    status = "okay";
};

要禁用由 SoC DTSI 启用的节点，将其 status 标记为 disabled：

&gpu {
    status = "disabled";
};

添加新外设

要在开发板 DTS 中添加新的设备节点或扩展现有的总线节点，请遵循相应的设备树绑定指南。例如，为一个 i2c 设备添加以下内容：

&i2c2 {
    status = "okay";

    sensor@48 {
        compatible = "ti,tmp102";
        reg = <0x48>;
    };
};

始终在设备节点中包含所需的 clock、pinctrl 和 power-domain 引用。缺少依赖项会导致启动时探测（probe）被推迟。

将新的 DTB 加入内核构建

要将新平台的设备树集成到内核构建中，请在 Qualcomm 的 Makefile 中添加一个条目：

diff --git a/arch/arm64/boot/dts/qcom/Makefile b/arch/arm64/boot/dts/qcom/Makefile
--- a/arch/arm64/boot/dts/qcom/Makefile
+++ b/arch/arm64/boot/dts/qcom/Makefile
+dtb-$(CONFIG_ARCH_QCOM)        += qcs6490-my-board.dtb
 dtb-$(CONFIG_ARCH_QCOM)        += qcs6490-rb3gen2.dtb

将 DTB 加入机器配置

更新 meta-qcom/conf/machine/qcs6490-rb3gen2-core-kit.conf 以包含新的设备树 blob：

KERNEL_DEVICETREE = " \
                     qcom/qcs6490-rb3gen2.dtb \
                     qcom/qcs6490-my-board.dtb \
                     "

所有受支持 SoC 的机器配置文件位于 meta-qcom/conf/machine/*.conf。

配置 DTB 启动选择

默认情况下（QCOM_DTB_DEFAULT = "multi-dtb"），构建会生成一个包含所有 DTB 的 FIT 镜像。启动时，UEFI 通过将开发板的硬件 compatible 字符串与 fit-dtb-compatible.inc 中的条目进行比对来选择匹配的 DTB。有关更多信息，请参阅设备树架构。在以下场景中，基于 FIT 的选择无法工作：

您的开发板的 compatible 字符串在 FIT_DTB_COMPATIBLE 中没有匹配的条目。
您正在移植一块新开发板，且固件元数据在 qcom-metadata.dtb 中未描述您的 compatible 字符串。
您需要无条件强制使用某个特定 DTB，而不管固件报告什么。

在这些情况下，请在您的机器配置文件（例如 meta-qcom/conf/machine/my-board.conf）中重写 QCOM_DTB_DEFAULT：

QCOM_DTB_DEFAULT = "qcs6490-my-board"
KERNEL_DEVICETREE = "qcs6490-my-board.dtb"

qcs6490-my-board 是 DTB 的主干名（stem），即去掉 .dtb 扩展名的文件名。将 QCOM_DTB_DEFAULT 设置为 “multi-dtb” 以外的任何值都会禁用 FIT 镜像生成；构建只会为指定的 DTB 生成单个 VFAT 镜像。构建成功后，以下 DTB 相关文件会出现在 build/tmp/deploy/images/<MACHINE>/ 目录下： 表：设置 QCOM_DTB_DEFAULT 时的构建产物

文件	描述
`dtb-qcs6490-my-board-image.vfat`	包含 `combined-dtb.dtb` 的 VFAT 分区镜像。写入设备的 DTB 分区。
`dtb.bin`	位于 qcomflash 压缩包内。刷写到 DTB 分区的 VFAT 镜像的副本。

在迭代式移植期间，如需仅更新 DTB 分区：

fastboot flash dtb_a dtb.bin
fastboot reboot

下次启动时，UEFI 会从 FIT 镜像中选择 <SoC>-my-board.dtb。有关更多信息，请参阅 The Devicetree Specification 和 Linux and the Devicetree。

​设备树源文件位置

​定位目标平台的 DTS 文件

​常见定制模式

​启用或禁用外设节点

​添加新外设

​将新的 DTB 加入内核构建

​将 DTB 加入机器配置

​配置 DTB 启动选择

设备树源文件位置

定位目标平台的 DTS 文件

常见定制模式

启用或禁用外设节点

添加新外设

将新的 DTB 加入内核构建

将 DTB 加入机器配置

配置 DTB 启动选择