# qualcomm-linux/meta-qcom architecture

> Architecture diagram of the GitHub repository qualcomm-linux/meta-qcom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qualcomm-linux/meta-qcom
- Repository: https://github.com/qualcomm-linux/meta-qcom

## Overview

##### Project Type and Purpose
- This is a Yocto/OpenEmbedded hardware-enablement meta-layer (“meta-qcom”) that provides machine configurations, BSP recipes, kernel recipes, firmware packages, and tooling for Qualcomm-based platforms.
- It is not a runtime application but a collection of build metadata (recipes, classes, configs) plugged into a BitBake build system to produce embedded Linux images.

##### High‐Level File Structure Analysis
- Top level:
- .github/ – CI workflows for GitHub Actions (build-on-push, nightly, tests).
- ci/ – KAS CI config files and LAVA test definitions.
- classes-recipe/ & classes/ – Custom BitBake classes for image types and boot artifacts.
- conf/ – layer.conf (registers this layer with BitBake) and machine/ (per-board .conf and .inc files).
- dynamic-layers/ – on-the-fly meta-layer fragments applied against OE-core or meta-oe.
- recipes-*/* – organized by domain:
– recipes-bsp: firmware, u-boot, packagegroups, partition tables, initramfs images.
– recipes-kernel: linux-yocto kernel recipes, patches, device-tree overlays, generic drivers.
– recipes-graphics: Mesa/Wayland tweaks for Qualcomm GPUs.
– recipes-devtools: QDL, partition-utils, debug tools.
– recipes-support: run-time support utilities (rpc, initrd scripts, bootctl, etc.).
– recipes-test: test images, diagnostics utilities.
- scripts/ – helper scripts and canned WIC (disk-image) layouts.
- Additional indicators: COPYING.MIT, README.md, SECURITY.md for governance and licensing.

##### README Insights
- Describes layer dependencies (OE-core, optional meta-oe).
- Points to ‘ci/*.yml’ for example KAS builds.
- Outlines flash workflow (using QDL tool).
- Machine support via conf/machine/*.conf.

##### Components
a. Developer/CI Environment
- Host machine (Linux) with BitBake and optionally KAS tool installed.
- Source repositories: meta-qcom (this layer), openembedded-core, (optional) meta-openembedded, KAS config files.
- GitHub Actions (push, PR, nightly workflows) and LAVA test farm integration.
b. Build Orchestration
- KAS (or manual setup) reads a .yml (e.g. ci/qcs6490-rb3gen2-core-kit.yml) and generates build environment.
- BitBake engine loads:
- layer.conf from each layer
- .bb and .bbappend recipe metadata
- classes (.bbclass), dynamic-layers fragments
- machine and distro configuration
- BitBake resolves dependencies and executes tasks (fetch → unpack → patch → configure → compile → package).
c. Metadata Layers
- meta-qcom: holds domain-specific recipes (BSP, kernel, graphics, devtools, support, test).
- OE-core: base classes, core recipes.
- meta-oe: optional extra recipes (connectivity, devtools, navigation).
- dynamic-layers: applied patches/overlays on OE-core or meta-oe.
d. Build Output
- Deployed images: core-image, initramfs, firmware archives, SDK, SDK-image.
- Artifacts staged under deploy/images/<machine>.
e. Flash/Test Workflow
- QDL tool (from recipes-devtools) used to flash image to hardware.
- LAVA test definitions (ci/lava/<board>/boot.yaml) define how tests run on hardware farm.

##### Key Architectural Patterns & Design Principles
- Layered architecture: each meta-layer encapsulates domain (core, board-support, devtools).
- Extend‐over‐override: .bbappend and dynamic-layers override core behavior.
- Declarative configuration: machine .conf and .inc files define board features.
- Reusability: classes (.bbclass) shared across recipes.

##### Technologies & Frameworks
- BitBake build engine
- Yocto Project / OpenEmbedded metadata model
- KAS for environment orchestration
- GitHub Actions + LAVA for CI/CD and hardware validation
- Shell/Python scripts for image layout (wic), CI helpers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & CI Environment
    subgraph "Developer & CI Environment"
        Dev["Developer Host (Linux)"]:::infra
        GitHub["GitHub Actions Workflows"]:::infra
        KAS["KAS CI Configs"]:::infra
        LAVA["LAVA Test Definitions"]:::infra
        Dev -->|push code| GitHub
        GitHub -->|runs workflows| KAS
        GitHub -->|triggers tests| LAVA
    end

    %% Build Orchestration
    subgraph "Build Orchestration"
        BitBake["BitBake Engine"]:::infra
        LayerConf["conf/layer.conf"]:::infra
        MachineConf["conf/machine/*.conf & include/*.inc"]:::infra
        ClassImage["classes-recipe/image_types_qcom.bbclass"]:::infra
        ClassBoot["classes/linux-qcom-bootimg.bbclass"]:::infra
        ClassDTB["classes/linux-qcom-dtbbin.bbclass"]:::infra
        ClassUKI["classes/uki-esp-image.bbclass"]:::infra
        DynLayers["dynamic-layers"]:::infra

        KAS -->|generates build env| BitBake
        BitBake -->|loads layer.conf| LayerConf
        BitBake -->|loads machine configs| MachineConf
        BitBake -->|loads image type class| ClassImage
        BitBake -->|loads boot artifact classes| ClassBoot
        BitBake -->|loads DTB classes| ClassDTB
        BitBake -->|loads UKI class| ClassUKI
        BitBake -->|applies fragments| DynLayers
    end

    %% Metadata Layers
    subgraph "Metadata Layers"
        OEcore["OE-core"]:::layer
        MetaOE["meta-oe (optional)"]:::layer
        subgraph "meta-qcom" 
            BSP["recipes-bsp"]:::layer
            Kernel["recipes-kernel"]:::layer
            Graphics["recipes-graphics"]:::layer
            Devtools["recipes-devtools"]:::layer
            Support["recipes-support"]:::layer
            Test["recipes-test"]:::layer
        end
    end

    BitBake -->|"uses metadata"| OEcore
    BitBake -->|"uses metadata"| MetaOE
    BitBake -->|"uses metadata"| BSP
    DynLayers -->|"overrides"| OEcore
    MetaOE -->|"extends"| meta-qcom

    %% Build Output
    subgraph "Build Output"
        Images["deploy/images/<machine> (core-image, SDK, firmware)"]:::output
    end
    BSP -->|executes recipes| Images
    Kernel -->|executes recipes| Images
    Graphics -->|executes recipes| Images
    Devtools -->|executes recipes| Images
    Support -->|executes recipes| Images
    Test -->|executes recipes| Images

    %% Flash & Test Workflow
    subgraph "Flash & Test Workflow"
        Board["Hardware Board"]:::output
        QDL["QDL Flash Tool"]:::tool
        LAVA -->|collects results| GitHub
        Images -->|flash via QDL| Board
        Board -->|runs tests| LAVA
    end

    %% Click Events
    click GitHub "https://github.com/qualcomm-linux/meta-qcom/blob/master/.github/workflows/*.yml"
    click KAS "https://github.com/qualcomm-linux/meta-qcom/blob/master/ci/qcs6490-rb3gen2-core-kit.yml"
    click LAVA "https://github.com/qualcomm-linux/meta-qcom/blob/master/ci/lava/qcs6490-rb3gen2-core-kit/boot.yaml"
    click LayerConf "https://github.com/qualcomm-linux/meta-qcom/blob/master/conf/layer.conf"
    click MachineConf "https://github.com/qualcomm-linux/meta-qcom/tree/master/conf/machine"
    click ClassImage "https://github.com/qualcomm-linux/meta-qcom/blob/master/classes-recipe/image_types_qcom.bbclass"
    click ClassBoot "https://github.com/qualcomm-linux/meta-qcom/blob/master/classes/linux-qcom-bootimg.bbclass"
    click ClassDTB "https://github.com/qualcomm-linux/meta-qcom/blob/master/classes/linux-qcom-dtbbin.bbclass"
    click ClassUKI "https://github.com/qualcomm-linux/meta-qcom/blob/master/classes/uki-esp-image.bbclass"
    click DynLayers "https://github.com/qualcomm-linux/meta-qcom/tree/master/dynamic-layers/openembedded-layer/recipes-*"
    click BSP "https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-bsp"
    click Kernel "https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-kernel"
    click Graphics "https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-graphics"
    click Devtools "https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-devtools"
    click Support "https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-support"
    click Test "https://github.com/qualcomm-linux/meta-qcom/tree/master/recipes-test"
    click QDL "https://github.com/qualcomm-linux/meta-qcom/blob/master/recipes-devtools/qdl/qdl_git.bb"
    click Board "https://github.com/qualcomm-linux/meta-qcom/blob/master/scripts/lib/wic/canned-wks/dragonboard410c-sd.wks"

    %% Styles
    classDef infra fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef layer fill:#98FB98,stroke:#333,stroke-width:1px
    classDef output fill:#FFA500,stroke:#333,stroke-width:1px
    classDef tool fill:#D3D3D3,stroke:#333,stroke-width:1px
```
