内核开发¶

目标与适用范围¶

本章节用于指导在进行定制化需求（驱动/配置/补丁等）后，重新编译内核与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替换。

进入SDK目录¶

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

构建环境：初始化编译环境¶

source quectel_build/compile/build.sh

备注

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

选择编译配置（步骤一）¶

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

打开内核编译开关¶

setopenkernel

备注

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

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

buildkernel

说明：

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

单项构建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步”）。

生成固件包目录并替换内核/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