Device Tree File Description

2025-11-28

Overview

This document introduces the device tree file structure, location, and modification methods for the Quectel Pi H1 platform. Device Tree is a data structure used by the Linux kernel to describe hardware configuration. Understanding the organizational structure of device tree files is crucial for kernel development.

Top-Level Device Tree

The top-level device tree file for Quectel Pi H1 is qcs6490-idp-pi.dts, which can be found in the following two locations:

  • Recommended modification location (outside kernel code, convenient for overlay):

    src/qcom-6.6-overlay/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts

  • Location within kernel source:

    sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts

Recommendation: For all device tree modifications, it is recommended to work on files in the src/qcom-6.6-overlay directory.

Common Device Tree Files

sc7280.dtsi

During development, the sc7280.dtsi file will be frequently viewed and used. This file contains the following common nodes:

  • GPIO (General Purpose Input/Output)
  • SPI (Serial Peripheral Interface)
  • I2C (I²C bus)
  • UART (Serial port)
  • CPU (Processor)
  • GPU (Graphics Processor)

File Path:

sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/sc7280.dtsi

External Device Tree Repositories

The Qualcomm platform separates drivers and device trees related to display, graphics, camera, video, etc. from the Linux kernel source code, forming independent code repositories.

View Repository Information

You can download the Yocto project source code according to Image Build, and obtain specific code repository information by viewing .bb files in the layers/meta-qcom-hwe directory.

Example: View Camera Device Tree Repository

Open the file layers/meta-qcom-hwe/recipes-multimedia/cameradtb/cameradtb_1.0.bb, you can see:

SRCPROJECT = "git://git.codelinaro.org/clo/le/platform/vendor/opensource/camera-devicetree.git;protocol=https"
SRCBRANCH  = "camera-kernel.qclinux.1.0.r1-rel"
SRCREV     = "08511ff747916576232cc26394bb9c5c6e0ab1f5"

Information Description:

Local Device Tree Sub-Repository Locations

For ease of compilation and use, Quectel Pi H1 places these independent device tree sub-repositories in the src/devicetree directory:

Module Path
Camera src/devicetree/camera-devicetree
Display src/devicetree/display-devicetree
Graphics src/devicetree/graphics-devicetree
Video src/devicetree/video-devicetree

Detailed Description of Device Tree for Each Module

1. Camera

Device Tree Files

  • Camera Main Configuration:

    src/devicetree/camera-devicetree/qcm6490-camera-rb3.dtsi

  • Camera Sensor Configuration:

    src/devicetree/camera-devicetree/qcm6490-camera-sensor-rb3.dtsi

  • Base Recipe:

    layers/meta-qcom-hwe/recipes-multimedia/cameradtb/cameradtb_1.0.bb

  • Extension Recipe:

    layers/meta-quectel/recipes-multimedia/cameradtb/cameradtb_1.0.bbappend

2. Display

Device Tree Files

  • 8-inch Screen Configuration:

    src/devicetree/display-devicetree/display/dsi-panel-waveshare-8inch-video.dtsi

  • SDE Display Main Configuration:

    src/devicetree/display-devicetree/display/qcm6490-sde-display-pi.dtsi

  • SDE Display Pin Configuration:

    src/devicetree/display-devicetree/display/qcm6490-sde-display-pinctrl.dtsi

  • SDE Display General Configuration:

    src/devicetree/display-devicetree/display/qcm6490-sde-display.dtsi

  • Top-Level Device Tree Reference:

    src/qcom-6.6-overlay/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts

  • Base Recipe:

    layers/meta-qcom-hwe/recipes-multimedia/display/qcom-displaydevicetree_git.bb

  • Extension Recipe:

    layers/meta-quectel/recipes-multimedia/display/qcom-displaydevicetree_git.bbappend

3. Graphics

Device Tree Files

  • GPU Configuration: 
    src/devicetree/graphics-devicetree/gpu/qcm6490-graphics.dtsi

  • Base Recipe:

    layers/meta-qcom-hwe/recipes-graphics/graphicsdevicetree/qcom-graphicsdevicetree_git.bb

  • Extension Recipe:

    layers/meta-quectel/recipes-graphics/graphicsdevicetree/qcom-graphicsdevicetree_git.bbappend

4. Video

Device Tree Files

  • Video Configuration: 
    src/devicetree/video-devicetree/qcm6490-video.dtsi

  • Base Recipe:

    layers/meta-qcom-hwe/recipes-multimedia/video/qcom-videodtb_1.0.bb

  • Extension Recipe:

    layers/meta-quectel/recipes-multimedia/video/qcom-videodtb_1.0.bbappend

Modification Recommendations

  1. Prioritize Overlay Modifications: When modifying device trees, prioritize working on files in the src/qcom-6.6-overlay and src/devicetree directories, avoiding direct modifications to kernel source code.

  2. Understand Dependencies: Before modifying device trees, it is recommended to understand the reference relationships between various .dtsi files.

  3. Synchronize Recipe Files: If you modify device tree repositories or add new device tree files, you need to synchronously update the corresponding .bb and .bbappend files.

  4. Version Control: It is recommended to use Git to manage all modifications for easy tracking and rollback.