Kernel development

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

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

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.

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 source d, 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.

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

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).

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).

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).

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 directorycd Pi-H1-Linux-SDK

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