# 内核开发

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

---

# 目标与适用范围

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

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

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

```bash
source quectel_build/compile/build.sh
```

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

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

```bash
buildconfig QSM565DWF QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X STD
```

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

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

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

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

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

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

## 打开内核编译开关

```bash
setopenkernel
```

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

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

```bash
buildkernel
```

说明：

- 该命令在SDK环境中触发内核构建，并生成启动所需的内核产物 ***efi.bin***。

- **产物输出目录**：构建完成后，*efi.bin* 会出现在：  
    - *Pi-H1-Linux-SDK/quectel_build/output/efi.bin*

- **烧录包替换原则**：*output/* 下的 *efi.bin* 需要被 **拷贝覆盖** 到 *buildpackage* 生成的固件包目录中，作为最终交付/烧录使用的内核文件（见下面“第7步”）。

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

```bash
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/*** 下的新产物覆盖固件包目录中的对应文件。

```bash
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*

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

```bash
# 进入 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*