Skip to main content
Qualcomm® Linux 内核使用分层的设备树（DT）架构，将平台特定的硬件 描述与 SoC 级配置分离。在启动时，UEFI 固件通过将硬件检测到的标识符与 compatible 字符串进行匹配，从 FIT 镜像中选择正确的 DTB。

​
DTS 和 DTSI 文件结构

设备树源文件位于内核源码树的 arch/arm64/boot/dts/qcom/ 目录下。 表：设备树文件类型

​
开发板与 SoC 分层

Qualcomm Linux 遵循严格的两层分层约定：
  1. SoC DTSI（例如 qcs6490.dtsi），定义时钟、电源域、中断控制器以及 使用该 SoC 的所有开发板通用的核心外设。
  2. 开发板 DTS（例如 qcs6490-rb3gen2.dts），包含 SoC DTSI 并添加 开发板特定的节点：GPIO 分配、稳压器数值、板载传感器和显示面板。
典型的开发板 DTS 以如下内容开头：

​
基于 FIT 的 DTB 打包

Qualcomm Linux 在单个软件发布版本中支持多个 SoC 和开发板。DTB 被打包成 一个扁平化镜像树（FIT）镜像（qclinux_fit.img），存储在 dtb_a 分区中。 UEFI 固件在启动时通过将硬件检测到的标识符与每个 FIT 配置条目的 compatible 字符串进行匹配来选择正确的 DTB。 FIT 镜像由镜像树源（.its）文件描述，并使用 mkimage 构建。它有两个 顶层部分：
  • images，声明每个二进制 blob：DTB、DTBO 和元数据二进制文件。
  • configurations，声明每个平台配置，每个配置引用一个或多个镜像。
一个最小的 ITS 骨架：

​
Qualcomm DTB 元数据

qcom-dtb-metadata 项目提供：
  • qcom-metadata.dts 编译为元数据 DTB，固件用它将硬件标识符映射到 FIT 配置的 compatible 字符串。
  • qcom-next-fitimage.its 是用于独立构建的 ITS 模板。
元数据 DTS 将允许的 compatible 字符串后缀标记按节点分组： soc、soc-sku、socver、board、boardrev、board-subtype-*、softsku 和 oem。

​
启动时的 DTB 选择流程

  1. UEFI 从 dtb_a 分区加载 qclinux_fit.img。
  2. 解析内嵌的 qcom-metadata.dtb，构建一张将硬件数字 ID 映射到 compatible 字符串中所用符号标记名称的表。
  3. 读取硬件标识符：SoC 芯片 ID/版本、来自配置数据表（CDT）的开发板类型 和版本、存储类型以及 DDR 大小。
  4. 按顺序遍历 FIT 配置（conf-1、conf-2、…）。
  5. 对于每个配置，将其 compatible 字符串中的每个标记与硬件推导出的值 进行精确匹配。选择所有标记都匹配的第一个配置。
  6. 加载所选配置的 DTB，并通过 EFI 引导传递给操作系统。
  7. 如果没有配置匹配，则启动失败。有关诊断步骤，请参阅 常见 DT 问题及修复。

​
Compatible 字符串格式

每个 FIT 配置的 compatible 字符串将平台标识编码为以连字符分隔的标记：
省略某个标记会使该维度不受约束，即它匹配该字段的任何硬件值。在 configurations 块中，更具体的字符串应出现在通用字符串之前。 示例：

​
将 DTB 接入 FIT 镜像（Yocto）

Yocto 构建根据两个输入生成 FIT 镜像：
  • KERNEL_DEVICETREE 和 LINUX_QCOM_KERNEL_DEVICETREE 表示要打包到 images 部分的 DTB 和 DTBO 列表。
  • conf/machine/include/fit-dtb-compatible.inc 中的 FIT_DTB_COMPATIBLE 条目枚举 configurations 部分的条目，将 DTB（或 DTB+DTBO 组合）映射到 UEFI 在启动时将匹配的硬件 compatible 字符串。

​
FIT_DTB_COMPATIBLE 条目

每个条目将一个 DTB 键（或使用 + 作为分隔符的 DTB+DTBO 键）映射到一个 或多个 compatible 字符串： 无 overlay 的单个 DTB：
DTB + DTBO 组合：
同一基础 DTB 的多种组合：
这些条目会在 FIT 镜像中生成一个 configurations 块，其中每个 conf-N 条目都带有相应的 compatible 字符串和 fdt 列表。UEFI 按顺序遍历这些 配置，并选择第一个匹配的配置。
在 configurations 块中，更具体的 compatible 字符串必须出现在通用 字符串之前。FIT 按顺序评估配置；第一个匹配即胜出。有关 compatible 字符串标记参考，请参阅 设备树架构。

​
在运行时应用设备树 overlay

Qualcomm Linux 在引导期间应用设备树 overlay，而不是在 Linux 运行时应用。UEFI 读取 VendorDtbOverlays EFI 变量，从 dtb.bin 中选择匹配的 overlay 集合，并在将控制权交给内核之前将其合并到设备树中。因此，对该变量的任何更改都会在下次引导时生效。
主线内核没有可用于向运行中的设备树应用 overlay 的用户空间接口。它仅将 of_overlay_fdt_apply() 作为内核内部 API 公开，并且 Qualcomm Linux 未启用基于 configfs 或 sysfs 的 overlay 加载器。因此，在此平台上无法使用将 .dtbo 文件写入 sysfs 或 configfs 节点的方法。有关内核内部 API 的信息，请参阅： Devicetree Overlay Notes。

​
选择 overlay 集合

VendorDtbOverlays EFI 变量接受以下值： 表：VendorDtbOverlays 的值 按照以下步骤应用 overlay 集合：
  1. 确认已挂载 efivarfs，以便该变量可写：
  2. 将 overlay 名称写入该变量。将 <overlay> 替换为上表中的某个值：
  3. 读回该变量以确认写入成功：
  4. 将写入刷新到存储并重启。该变量保存在基于 RPMB 的 EFI 变量存储中，未刷新的写入会在复位时丢失：
  5. 设备启动后，确认 UEFI 已读取并应用了该 overlay。UEFI 串口控制台上会出现以下内容：
  6. 通过检查 overlay 添加的节点，确认该 overlay 已传递到内核：

​
组合多个 overlay 集合

要应用多个 overlay 集合，请使用逗号分隔各个值：

​
恢复为默认设备树

删除该变量并重启系统。此后 UEFI 将跳过 overlay 应用，直接使用基础平台 DTB 引导：

​
用于 KVM 的 EL2 设备树

文件名中带有 el2 标记的设备树文件支持 Linux 在异常级别 2（EL2）运行 以支持 KVM。构建系统将 el2 overlay 应用于平台 DTB，以生成 EL2 DTB 变体。目标默认以 KVM 模式启动，但少数目标可能尚未支持 KVM。请参阅发行 说明以了解平台能力。有关更多详细信息，请参阅 启用虚拟化。

​
Staging 设备树 overlay

文件名中带有 staging 标记的设备树文件用于启用存在于内核源码树中但 尚未提交到上游的驱动。示例包括 SoC 级 TGU 节点（kodiak-staging.dtso、 lemans-staging.dtso、monaco-staging.dtso、talos-staging.dtso）以及 面向开发套件的开发板级 staging 以太网 PHY overlay。当 VendorDtbOverlays EFI 变量设置为 staging 时，构建系统会应用这些 overlay：
当需要 staging 下游特性时，请使用 staging DTB。

​
CAMX 相机设备树 overlay

文件名中带有 camx 标记的设备树文件用 Qualcomm® CAMX 专有相机框架 替换上游相机子系统（camss）。开发板级 CAMX overlay（例如 qcs6490-rb3gen2-vision-mezzanine-camx.dtso、lemans-evk-camx.dtso、 monaco-evk-camx.dtso）禁用上游 camss 节点并启用 CAMX 节点。当同时 需要 CAMX 和 KVM 时，会应用组合的 *-camx-el2.dtso overlay。当 VendorDtbOverlays EFI 变量设置为 camx 时，构建系统会应用 CAMX overlay：
仅在使用 Qualcomm 专有相机栈构建时才使用 CAMX DTB。在 CAMX 配置中， 上游 camss 驱动被禁用。