Kernel development

2026-02-25

Objectives and Scope

This section guides you through recompiling the kernel and DTB, and replacing them in the Debian system after implementing customization requirements (drivers/configurations/patches, etc.).

  • Applicable Platform: Quectel Pi-H1 (based on Pi-H1 Linux SDK)
  • Applicable System: Debian

Prerequisites

Development Environment Requirements (Recommended)

  • Available Linux host environment (Ubuntu/Debian-based systems are acceptable, subject to SDK requirements)
  • Sufficient disk space (source code + out directory + build artifacts)
  • Shell environment capable of executing SDK scripts (typically bash)

Obtaining/Preparing the SDK

Ensure you have obtained the Pi-H1 Linux SDK and are using an SDK version that matches the current Debian image (or the same release/tag). If the SDK version does not match the image version, the following issues may occur:

  • Kernel version/module version mismatch causing driver loading failures
  • DTB device tree mismatch causing peripherals to be unavailable or preventing boot

Build Command Workflow (On-Demand Individual Build of Kernel/DTB)

This section focuses on: after completing environment initialization and project configuration, building the kernel and DTB individually on-demand through SDK-provided target commands, for kernel/DTB replacement in the Debian system.

1) Navigate to SDK Directory

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

2) Build Environment: Initialize Build Environment

source quectel_build/compile/build.sh

Notes:

  • This script loads SDK build functions (such as buildconfig/buildkernel/builddtb/buildpackage, etc.) and sets necessary environment variables.
  • If not sourced, subsequent commands will typically prompt "command not found" or indicate missing environment.
  • After executing this command, the terminal will automatically switch to the build-qcom-wayland directory, which is normal. Subsequent buildconfig, buildall, and buildpackage commands will be executed in this directory.

3) Select Build Configuration (Step One)

buildconfig QSM565DWF QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X STD

Notes:

  • QSM565DWF: Target platform/product family configuration (selecting the correct platform is crucial, as it affects kernel configuration, device tree, packaging rules, etc.).
  • QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X: Project version/configuration (example). Please select from the valid fields prompted in practice.
  • STD: Standard build configuration (different configurations may affect build options, debug symbols, packaging content, etc.).

You can input user-customized project_name, project_rev, and custom_name based on prompts, selecting currently valid fields from the prompted Valid Projects and Valid CUST_NAME for user customization.

After successful configuration, you will see the current build configuration information (example):

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

And the confirmed project configuration (example):

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

4) Enable Kernel Build Switch

setopenkernel

Notes:

  • This step is used to enable kernel-related build processes in the SDK build system (including kernel/dtb and possibly modules packaging).
  • If this step is not executed, subsequent buildkernel/builddtb/buildpackage may not produce the expected kernel/DTB files, or may follow the default "closed-source/pre-built artifacts" branch (subject to SDK rules).

5) Individual Kernel Build: buildkernel (Generate efi.bin)

buildkernel

Notes:

  • This command triggers kernel build in the SDK environment and generates the boot-required kernel artifact efi.bin.
  • Artifact Output Directory: After build completion, efi.bin will appear at:
    • Pi-H1-Linux-SDK/quectel_build/output/efi.bin
  • Firmware Package Replacement Principle: The efi.bin under output/ needs to be copied and overwritten to the firmware package directory generated by buildpackage, as the kernel file for final delivery/flashing (see "Step 7" below).

6) Individual DTB Build: builddtb (Generate dtb.bin)

builddtb

Notes:

  • This command generates the device tree artifact dtb.bin (which may contain multiple dtb packages/collections).
  • Artifact Output Directory: After build completion, dtb.bin will appear at:
    • Pi-H1-Linux-SDK/quectel_build/output/dtb.bin
  • Firmware Package Replacement Principle: The dtb.bin under output/ needs to be copied and overwritten to the firmware package directory generated by buildpackage, as the DTB file for final delivery/flashing (see "Step 7" below).

7) Generate Firmware Package Directory and Replace Kernel/DTB: buildpackage + Overwrite Files

Execute buildpackage to generate the firmware package directory (TARGET_DIR), then overwrite the corresponding files in the firmware package directory with the new artifacts from quectel_build/output/.

buildpackage

Notes:

  • This step typically takes 10~20 seconds; after success, it will generate a firmware package directory (example):
    • Pi-H1-Linux-SDK/quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/
  • Key Point: The directory generated by buildpackage is where the final flashing package/delivery package is located. After customizing the kernel/DTB, you need to overwrite and replace with the following files:
    • Source: Pi-H1-Linux-SDK/quectel_build/output/efi.bin
    • Source: Pi-H1-Linux-SDK/quectel_build/output/dtb.bin
    • Target: The corresponding efi.bin and dtb.bin in the Pi-H1-Linux-SDK/quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/ directory

Example (illustrative, actual filenames subject to firmware package directory contents):

# Navigate to SDK root directory
cd Pi-H1-Linux-SDK

# Overwrite files in firmware package with individually built artifacts
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

Artifact Description (What Will Be Used for Debian Replacement)

This subsection helps customers quickly identify "which file exactly needs to be replaced":

  • efi.bin: Kernel image package used for boot chain loading (on the Debian side, typically referenced in the boot partition//boot or EFI-related directories).
  • dtb.bin: Device tree-related artifact (may be a collection package). On the Debian side, it will eventually be loaded by the boot chain (path and configuration depend on the image's boot scheme).
  • package: SDK aggregated artifact. It is recommended to use the package as the deliverable, which typically contains efi.bin/dtb.bin and necessary auxiliary files (actual structure subject to package contents).

Verification and Rollback

Verification

It is recommended to perform at least two types of verification:

  • Kernel Version Verification: Confirm that the newly compiled kernel is running
  • Feature Point Verification: Perform minimal closed-loop testing for your customized drivers/configuration items (e.g., peripheral enumeration, driver loading, dmesg keywords, etc.)

Rollback

Recommended rollback strategy:

  • Always keep a bootable old kernel/old DTB (file-level backup or dual boot entries)
  • If the boot chain supports multiple boot entries (e.g., extlinux/grub), prioritize verifying the new kernel by "adding a new boot entry", and only overwrite the old file after confirming stability

Common Issues

  • Build command prompts not found: Have you executed source quectel_build/compile/build.sh?
  • buildkernel/builddtb produces no artifacts: Have you selected the correct configuration with buildconfig and executed setopenkernel?
  • Cannot boot after replacement: Prioritize rolling back to backup files; check if the kernel/DTB path referenced by boot entries matches the actual path
  • DTB not taking effect: Confirm which dtb (or dtb.bin) is referenced in the boot configuration and verify that you are replacing the same target
  • Module version mismatch: Confirm that /lib/modules/<kernel_version>/ matches uname -r and execute depmod -a