定位与修改设备树

每个 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 视觉夹层板开发套件。
`arch/arm64/boot/dts/qcom/qcs6490-rb3gen2-industrial-mezzanine.dts`	QCS6490 Dragonwing™ RB3 Gen 2 工业夹层板开发套件。

表: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 单板变体的 EL2 覆盖,用于 KVM 环境。
`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-9100 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/qcs8300-ride.dts`	Dragonwing IQ-8300 ride 的 Qualcomm Linux 开发套件。
`arch/arm64/boot/dts/qcom/monaco-evk.dtb`	Dragonwing^™ IQ-8275 EVK 的 Qualcomm Linux 开发套件。

表: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 延迟(probe deferral)。

将新的 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 启动选择

设备树源码位置

定位目标平台的 DTS 文件

常见定制模式

启用或禁用外设节点

添加新的外设

将新的 DTB 添加到内核构建

将 DTB 包含到机器配置中

配置 DTB 启动选择