内核开发

2026-02-25

Edit this page

目标与适用范围

本章节用于指导在进行定制化需求（驱动/配置/补丁等）后，重新编译内核与 DTB，并在 Debian 系统中完成替换。

适用平台：Quectel Pi-H1（基于 Pi-H1 Linux SDK）
适用系统：Debian

前置准备

开发环境要求（建议）

可用的 Linux 宿主机环境（Ubuntu/Debian 系均可，具体以 SDK 要求为准）
足够的磁盘空间（源码 + out 目录 + 打包产物）
能正常执行 SDK 脚本的 shell 环境（通常 bash）

获取/准备 SDK

请确保已获取 Pi-H1 Linux SDK，并使用与当前 Debian 镜像匹配的 SDK 版本（或同一 release/tag）。若 SDK 与镜像版本不匹配，可能出现：

内核版本/模块版本不一致导致驱动加载失败
DTB 设备树不匹配导致外设不可用或无法启动

编译命令流程（按需单项构建内核/DTB）

本章节主线是：在完成环境初始化与项目配置后，通过 SDK 提供的目标命令 按需单项构建内核与 DTB，用于 Debian 系统中的内核/DTB 替换。

1) 进入 SDK 目录

cd your/path/to/Pi-H1-Linux-SDK/

2) 构建环境：初始化编译环境

source quectel_build/compile/build.sh

说明：

该脚本会加载 SDK 的编译函数（例如 buildconfig/buildkernel/builddtb/buildpackage 等），并设置必要的环境变量。
若未 source，后续命令通常会提示 “command not found” 或缺少环境。
执行此命令后，终端会自动切换到 build-qcom-wayland 目录，这是正常现象。后续的 buildconfig、buildall、buildpackage 命令都将在此目录下执行。

3) 选择编译配置（步骤一）

buildconfig QSM565DWF QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X STD

说明：

QSM565DWF：目标平台/产品族配置（选择正确的平台非常关键，影响内核配置、设备树、打包规则等）。
QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X：项目版本/配置（示例）。实际请按提示的有效字段选择。
STD：标准构建配置（不同配置可能影响编译选项、调试符号、打包内容等）。

您可以根据提示输入用户定制的 project_name project_rev custom_name，从提示的 Valid Projects 和 Valid CUST_NAME 里面选择当前有效的字段进行用户定制。

配置成功后，您会看到当前的构建配置信息（示例）：

MACHINE    = qcm6490-idp
DISTRO     = qcom-wayland
BUILDTYPE  = default
BSP-TYPE   = qcom-custom-bsp

以及确认的项目配置（示例）：

Current QUECTEL_PROJECT_NAME = QSM565DWF
Current QUECTEL_PROJECT_REV  = QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X
Current QUECTEL_CUSTOM_NAME  = STD

4) 打开内核编译开关

setopenkernel

说明：

该步骤用于在 SDK 构建体系中启用内核相关构建流程（包含 kernel/dtb 及可能的 modules 打包）。
如果不执行此步骤，后续 buildkernel/builddtb/buildpackage 可能不会产出你期望的内核/DTB 文件，或走到默认的“闭源/预置产物”分支（具体以 SDK 规则为准）。

5) 单项构建内核：buildkernel（生成 efi.bin）

buildkernel

说明：

该命令在 SDK 环境中触发内核构建，并生成启动所需的内核产物 efi.bin。
产物输出目录：构建完成后，efi.bin 会出现在：
- Pi-H1-Linux-SDK/quectel_build/output/efi.bin
烧录包替换原则：output/ 下的 efi.bin 需要被拷贝覆盖到 buildpackage 生成的固件包目录中，作为最终交付/烧录使用的内核文件（见下面“第 7 步”）。

6) 单项构建 DTB：builddtb（生成 dtb.bin）

builddtb

说明：

该命令生成设备树产物 dtb.bin（可能包含多个 dtb 的打包/集合）。
产物输出目录：构建完成后，dtb.bin 会出现在：
- Pi-H1-Linux-SDK/quectel_build/output/dtb.bin
烧录包替换原则：output/ 下的 dtb.bin 需要被拷贝覆盖到 buildpackage 生成的固件包目录中，作为最终交付/烧录使用的 DTB 文件（见下面“第 7 步”）。

7) 生成固件包目录并替换内核/DTB：buildpackage + 覆盖文件

执行 buildpackage 生成固件包目录（TARGET_DIR），然后用 quectel_build/output/ 下的新产物覆盖固件包目录中的对应文件。

buildpackage

说明：

该步骤通常耗时 10~20 秒；成功后会生成固件包目录（示例）：
- Pi-H1-Linux-SDK/quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/
关键点：buildpackage 生成的目录是最终烧录包/交付包所在位置。客户定制内核/DTB 后，需要用以下文件进行覆盖替换：
- 来源：Pi-H1-Linux-SDK/quectel_build/output/efi.bin
- 来源：Pi-H1-Linux-SDK/quectel_build/output/dtb.bin
- 目标：Pi-H1-Linux-SDK/quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/ 目录中对应的 efi.bin、dtb.bin

示例（示意，实际以固件包目录内文件名为准）：

# 进入 SDK 根目录
cd Pi-H1-Linux-SDK

# 用单项构建产物覆盖固件包中的文件
cp -f quectel_build/output/efi.bin quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/efi.bin
cp -f quectel_build/output/dtb.bin quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/dtb.bin

产物说明（Debian 替换会用到什么）

本小节用于帮助客户快速识别“要替换的到底是哪一个文件”：

efi.bin：用于启动链路加载的内核镜像封装（Debian 侧通常在启动分区//boot 或 EFI 相关目录被引用）。
dtb.bin：设备树相关产物（可能是集合包）。Debian 侧最终会被启动链路加载（路径与配置取决于镜像的启动方案）。
package：SDK 汇总产物。建议把 package 作为交付物，内部通常包含 efi.bin/dtb.bin 及必要的附属文件（实际结构以 package 内容为准）。

验证与回滚

验证

建议至少做两类验证：

内核版本验证：确认已运行到新编译的内核
功能点验证：针对你定制的驱动/配置项做最小闭环测试（例如外设枚举、驱动加载、dmesg 关键字等）

回滚

建议回滚策略：

永远保留一份可启动的旧内核/旧 DTB（文件级备份或双启动项）
若启动链路支持多启动项（例如 extlinux/grub），优先用“新增一条启动项”的方式验证新内核，确认稳定后再覆盖旧文件

常见问题

执行 build 命令提示找不到：是否已执行 source quectel_build/compile/build.sh
buildkernel/builddtb 没产物：是否已 buildconfig 选择正确配置，并执行 setopenkernel
替换后无法启动：优先回滚到备份文件；检查启动项引用的内核/DTB 路径是否与实际一致
DTB 不生效：确认启动配置中引用的是哪个 dtb（或 dtb.bin），并核对替换的是同一个目标
模块版本不匹配：确认 /lib/modules/<kernel_version>/ 与 uname -r 一致，并执行 depmod -a

应用开发

Yocto Linux

Quectel Pi H1