Overview

This document describes the complete process of compiling the Linux kernel for Quectel Pi H1, packaging kernel images, and updating them to the device. Quectel Pi H1 uses a Yocto-based build system with a Qualcomm-customized Linux kernel (based on Linux 6.6).

Kernel Recipes Description

Qualcomm Linux kernel recipes are located in the /layers/meta-qcom-hwe/recipes-kernel/linux directory. This layer provides two kernel solutions:

Recipe File	Kernel Type	Source	Description
linux-qcom-custom_6.6.bb	Custom BSP	git.codelinaro.org	Qualcomm customized kernel (currently used)
linux-qcom-base_6.6.bb	Base BSP	git.kernel.org	Standard kernel

Currently Used: Custom kernel source solution

Directory Structure

Kernel-related files are mainly divided into two directories:

qcm6490-idp/
├── kernel-source/               # Kernel source directory
└── kernel-build-artifacts/      # Build artifacts directory

kernel-source/ Directory

Stores the complete source code of the Linux kernel, including:

• Kernel core code (arch/, drivers/, fs/, net/, etc.)
• Device tree source files (.dts/.dtsi, describing hardware configuration)
• Kernel configuration files (Kconfig)
• Build scripts (Makefile)

Source Directory Details

Directory/File	Description	Directory/File	Description
arch	Architecture-related code (ARM64, x86, etc.)	scripts	Build and configuration scripts
block	Block device subsystem	security	Security framework (SELinux, AppArmor, etc.)
certs	Kernel certificates and signatures	sound	Audio subsystem (ALSA)
crypto	Encryption API and algorithms	tools	Kernel-related tools
Documentation	Kernel documentation	usr	initramfs generation related
drivers	Device drivers	virt	Virtualization support (KVM)
fs	File system implementation	rust	Rust language support
include	Kernel header files	Makefile	Main build file
init	Kernel initialization code	Kbuild	Kernel build system configuration
ipc	Inter-process communication mechanisms	Kconfig	Kernel configuration interface definition
kernel	Kernel core functionality (scheduler, process management, etc.)	MAINTAINERS	Maintainer list
lib	Common library functions	CREDITS	Contributor list
mm	Memory management subsystem	COPYING	Copyright notice (GPL)
net	Network protocol stack
samples	Kernel programming example code

kernel-build-artifacts/ Directory

Stores kernel build artifacts after compilation, including:

• Kernel Image Files: Image (uncompressed) or Image.gz (compressed version)
• Device Tree Binary Files: .dtb files (compiled from .dts)
• Kernel Modules: .ko files (loadable driver modules)
• Configuration Files: .config, build.log, etc.

Compile Kernel

1. Configure Build Environment

Enter the code working directory and execute the following command to configure the build environment:

source quectel_build/compile/build.sh

2. Execute Compilation

Use Yocto's bitbake command to compile the kernel:

bitbake linux-qcom-custom

3. Build Artifact Paths

After compilation is complete, the kernel image is generated at the following location:

Temporary Working Directory:

build-qcom-wayland/tmp-glibc/work/qcm6490_idp-qcom-linux/linux-qcom-custom/6.6/deploy-linux-qcom-custom

Final Deployment Directory (automatically copied by Yocto):

build-qcom-wayland/tmp-glibc/deploy/images/qcm6490-idp/

Note: Yocto will automatically copy the kernel image from the working directory to the deployment directory. The subsequent packaging process will obtain the kernel image from the deployment directory.

Build Time Reference

• First Build: Approximately 30-60 minutes (depending on hardware configuration)
• Incremental Build: Approximately 5-15 minutes

Package Kernel and Device Tree Images

1. Install ukify Tool

First, install the Python dependencies required for packaging:

sudo pip install pefile

2. Execute Packaging Command

Run the following command to package the kernel image and device tree:

do_kernel_images

3. ukify Warning Description

During the packaging process, the following warning messages will appear, which can be ignored:

Kernel version not specified, starting autodetection .
Real-Mode Kernel Header magic not found
+ readelf --notes {TOPDIR}/quectel_build/alpha/tools/pack/image_temp/Image
readelf: Error: Not an ELF file - it has the wrong magic bytes at the start
Found uname version: 6.6.52-qli-1.3-ver.1.1
Wrote unsigned ${TOPDIR}/quectel_build/alpha/tools/pack/image_temp/uki.efi

Note: These warnings are caused by differences between ARM64 kernel format and EFI tool expected format, and do not affect the correctness of the final image.

4. Get Packaged Image

After packaging is complete, obtain the generated image file from the following path:

${TOPDIR}/quectel_build/alpha/output/pack/efi.bin

Update Image to Device

Method 1: Enter Fastboot via Debug Serial Port

1. Enter Fastboot Mode

Option A - Via Serial Port Command:

Connect the debug serial port and execute in the system:

reboot bootloader

Option B - Via ADB Command:

Ensure the device is connected via USB and ADB debugging is enabled, then execute:

adb shell
reboot bootloader

2. Verify Fastboot Mode

After the device enters Fastboot, run on the host:

fastboot devices

You should see the device list.

3. Flash Kernel Image

Use the fastboot command to flash the new kernel image:

fastboot flash efi efi.bin

4. Reboot Device

After flashing is complete, reboot the device:

fastboot reboot

Method 2: Automation Script (Optional)

If you need to frequently update the kernel, you can create an automation script:

#!/bin/bash
# update_kernel.sh

# Check if efi.bin exists
if [ ! -f "quectel_build/alpha/output/pack/efi.bin" ]; then
    echo "Error: efi.bin does not exist, please compile and package the kernel first"
    exit 1
fi

# Enter Fastboot
adb reboot bootloader
sleep 5

# Wait for Fastboot to be ready
fastboot devices

# Flash image
fastboot flash efi quectel_build/alpha/output/pack/efi.bin

# Reboot
fastboot reboot

echo "Kernel update complete!"

Usage:

chmod +x update_kernel.sh
./update_kernel.sh

Notes

1. Backup Important Data: Before updating the kernel, ensure important data is backed up
2. Sufficient Power: Ensure the device has sufficient power or is connected to power during flashing
3. Stable USB Connection: Use a good quality USB cable to avoid flashing interruption
4. Version Matching: Ensure the kernel version is compatible with other system components

Common Issues

Q1: bitbake Compilation Failed?

Possible Causes:

• Insufficient disk space
• Network connection issues
• Missing dependency packages

Solution:

# Clean build cache
bitbake -c cleanall linux-qcom-custom
# Recompile
bitbake linux-qcom-custom

Q2: fastboot devices Cannot See Device?

Solution:

• Check if USB drivers are correctly installed
• Try changing USB port or cable
• Confirm the device has correctly entered Fastboot mode (screen displays Fastboot text)

Q3: Cannot Boot After Flashing?

Solution:

• Use factory image to restore the system
• Check if there were errors during compilation
• Confirm device tree configuration is correct

Related Documents

• Device Tree Configuration
• Cross Compilation Toolchain

Device Tree File Description

Adding Applications and Third-Party Libraries