内核开发

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

目标与适用范围

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

  • 适用平台：Quectel Pi H1（基于Pi-H1 Linux SDK）。

  • 适用系统：Debian 13。

前置准备

开发环境要求

  • 可用的Linux宿主机环境（Ubuntu/ Debian系均可，具体以SDK要求为准）。

  • 建议预留不少于200 GB空闲磁盘空间（用于源码sources、downloads、sstate-cache、build-qcom-wayland 构建目录、prebuild根文件系统与打包产物）。

  • 必须使用Bash执行SDK脚本：quectel_build/compile/build.sh 为 #!/bin/bash 脚本，内部使用数组、[[ ]]、source 等Bash特性。Ubuntu等发行版默认将 /bin/sh 软链接到 dash，若以 sh 方式执行会解析报错；请确认 /bin/sh 指向 bash（ls -l /bin/sh），或直接在Bash终端中执行本文命令。

获取/ 准备SDK

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

  • 内核版本/ 模块版本不一致导致驱动加载失败。

  • 设备树二进制文件（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、buildkernel、builddtb、buildpackage 命令都将在此目录下执行。

选择编译配置

buildconfig QSM565DWF SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X STD

备注

QSM565DWF：目标平台/ 产品族配置（选择正确的平台非常关键，影响内核配置、设备树、打包规则等）。
SG565DWFPARL1A01_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  = SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X
Current QUECTEL_CUSTOM_NAME  = STD

打开内核编译开关

setopenkernel

备注

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

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

buildkernel

备注

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

单项构建DTB（生成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 生成固件包目录（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

产物说明

本节帮助用户快速识别需要替换的文件：

  • efi.bin：整个EFI系统分区（ESP）的分区镜像，对应GPT分区表中标签为 efi 的分区（类型GUID C12A7328-F81F-11D2-BA4B-00A0C93EC93B，容量500 MB，FAT16文件系统）。

    • 镜像内包含systemd-boot引导器（/EFI/BOOT/bootaa64.efi）、启动项配置（/boot/loader/loader.conf、/boot/loader/entries/*.conf）以及统一内核镜像UKI（/EFI/Linux/linux-qcm6490-idp.efi，由内核 Image、initramfs 与内核命令行打包而成）。

    • 加载规则：由XBL/ ABL（UEFI）阶段按ESP分区类型直接加载该分区内的 /EFI/BOOT/bootaa64.efi，再由systemd-boot加载UKI中的内核；它不是Debian根文件系统 /boot 目录下的普通内核文件，替换时须按分区镜像烧录。

  • dtb.bin：dtb 分区的分区镜像，对应GPT分区表中标签为 dtb_a 的分区（容量64 MB，FAT文件系统）。镜像内为合并后的设备树 combined-dtb.dtb。

    • 加载规则：该分区不由Debian系统加载，而是在XBL/ ABL（UEFI）阶段由引导程序读取并传递给内核；替换设备树必须重新烧录 dtb 分区，而不是替换根文件系统中的文件。

  • package：SDK的汇总产物，建议作为交付物，内部通常包含 efi.bin、dtb.bin 及必要的附属文件（实际结构以 package 内容为准）。

验证与回滚

验证

建议至少进行以下两类验证：

  • 内核版本验证：在板端执行 uname -r 核对内核版本号（如 6.6.116-qli-1.7-ver.1.1，以本次编译产物为准）；执行 uname -a 查看版本号后的编译时间戳，或 cat /proc/version 查看编译时间与编译器信息，确认运行的是本次重新编译的内核，而不是旧内核。

  • 功能点验证：针对定制的驱动/ 配置项进行最小闭环测试（例如外设枚举、驱动加载、dmesg 关键字等）。

回滚

建议采用以下回滚策略：

  • 始终保留一份可启动的旧内核/ 旧DTB（文件级备份或双启动项）。

  • 本平台启动链路为XBL/ ABL（UEFI）+ systemd-boot，不使用extlinux/ grub；ESP（efi 分区）中的 /boot/loader/entries/*.conf 即启动项，可通过新增启动项（由 loader.conf 的 default 指定默认项）的方式验证新内核，确认稳定后再覆盖正式文件。

常见问题

  • 执行build命令提示找不到：检查是否已执行 source quectel_build/compile/build.sh。

  • buildkernel/ builddtb无产物：检查是否已通过 buildconfig 选择正确的配置，并执行 setopenkernel。

  • 镜像替换后无法启动：优先回滚到备份文件；检查启动项引用的内核/ DTB路径是否与实际一致。

  • DTB修改未生效：设备树由 dtb 分区（标签 dtb_a）在ABL阶段加载，请先确认已将新的 dtb.bin 覆盖到固件包目录并重新烧录该分区。判定是否生效：

    • 在板端执行 cat /proc/device-tree/model（应与本次编译的DTS中 model 属性一致）和 cat /proc/device-tree/compatible。

    • 或找到被改动的节点后读取对应属性（用 ls /proc/device-tree/ 逐级定位节点，再 cat 该节点下的属性文件），与源码中的改动逐项核对。

  • 内核模块版本不匹配：确认 /lib/modules/<kernel_version>/ 与 uname -r 一致，并执行 depmod -a。