# linux-msm/qdl architecture

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

- Interactive diagram: https://gitdiagram.com/linux-msm/qdl
- Repository: https://github.com/linux-msm/qdl

## Overview

##### Main Components
a. Command-Line Interface (CLI) & Main Entry:
- The tool is invoked via the command “qdl”, so the qdl.c and qdl.h files form the CLI and core logic interface.
- The usage pattern “qdl <prog.mbn> [<program> <patch> …]” suggests that the executable accepts a primary flash image along with optional additional binaries.
b. USB Communication Module:
- The usb.c file directs communication with the USB device using libusb-1.0. This module is responsible for establishing USB connections, sending commands, and receiving data from the device.
c. Protocol / Loader Modules:
- Modules like sahara.c and firehose.c likely implement the different communication or flash-loading protocols used by Qualcomm devices.
- Other protocol-specific files such as ks.c, ramdump.c, and ufs.c/h might handle related operations such as device security, memory dumps, or file-system communications.
d. Flash & Program Handling:
- The program.c/program.h and patch.c/patch.h files denote functions to work with flash images and any required patches, managing the actual flashing process.
e. Utility & UX Components:
- util.c and ux.c likely provide general support routines, user feedback mechanisms, and logging or error handling.
- Files like read.c/read.h suggest functions for input (or reading files) related to the flashing process.

##### Relationships and Interactions
- “Program & Patch Manager” component (program.c, patch.c) as another core module, connected to the CLI and the communication components. This module is in charge of preparing and managing the image data that needs to be flashed.

##### Architectural Patterns and Principles
- The design follows a modular pattern. Each C-file (or group of files) represents a key functionality—which aids in maintainability and clarity.
- A separation of concerns, with distinct modules responsible for CLI processing, device communication, protocol handling, and flashing procedures.
- That the control flow is initiated by input from the CLI, processed through various protocol-specific modules, and ultimately interacts with the hardware via USB with a clearly delineated role for each component.

##### Additional Notes
- Every component’s role and dependency is explicitly represented. Avoid oversimplification.
- And annotate that the tool’s primary function is to flash images using various protocols over USB, highlighting the interplay between building the flash loader and executing the flash sequence.
- That being as granular as possible is best; separate out and label everything (each .c file mapped to its conceptual module).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Interface
    subgraph "CLI Interface"
        CLI["CLI (qdl)"]:::cli
    end

    %% USB Communication Module
    subgraph "USB Communication"
        USB["USB Communication (usb.c)"]:::module
    end

    %% Protocol Modules
    subgraph "Protocol Modules"
        Sahara["Sahara (sahara.c)"]:::protocol
        Firehose["Firehose (firehose.c)"]:::protocol
        KS["KS (ks.c)"]:::protocol
        Ramdump["Ramdump (ramdump.c)"]:::protocol
        UFS["UFS (ufs.c/h)"]:::protocol
    end

    %% Program & Patch Manager
    subgraph "Program & Patch Manager"
        Program["Program (program.c)"]:::module
        Patch["Patch (patch.c)"]:::module
    end

    %% Utilities & UX
    subgraph "Utilities & UX"
        Util["Utilities (util.c)"]:::util
        UX["UX (ux.c)"]:::util
        Read["Read (read.c)"]:::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Libusb["libusb-1.0"]:::external
        Libxml["libxml2"]:::external
    end

    %% Main flows from CLI
    CLI -->|"send_command/data"| USB
    CLI -->|"initiate_protocol"| Sahara
    CLI -->|"initiate_protocol"| Firehose
    CLI -->|"initiate_protocol"| KS
    CLI -->|"initiate_protocol"| Ramdump
    CLI -->|"initiate_protocol"| UFS
    CLI -->|"initiate_flash"| Program
    CLI -->|"initiate_flash"| Patch

    %% Flash Image Transfer
    Program -->|"transfer_flash"| USB
    Patch -->|"transfer_patch"| USB

    %% Protocol Modules interactions with USB Communication
    Sahara -->|"protocol_interact"| USB
    Firehose -->|"protocol_interact"| USB
    KS -->|"protocol_interact"| USB
    Ramdump -->|"protocol_interact"| USB
    UFS -->|"protocol_interact"| USB

    %% Utilities & UX supports all components (dashed links)
    CLI ---|"logs/errors"| Util
    USB ---|"logs/errors"| Util
    Program ---|"logs/errors"| Util
    Patch ---|"logs/errors"| Util
    Sahara ---|"logs/errors"| Util
    Firehose ---|"logs/errors"| Util
    KS ---|"logs/errors"| Util
    Ramdump ---|"logs/errors"| Util
    UFS ---|"logs/errors"| Util

    %% External Dependencies usage
    USB -->|"uses"| Libusb
    CLI -->|"config_XML"| Libxml

    %% Click Events
    click CLI "https://github.com/linux-msm/qdl/blob/master/qdl.c"
    click USB "https://github.com/linux-msm/qdl/blob/master/usb.c"
    click Sahara "https://github.com/linux-msm/qdl/blob/master/sahara.c"
    click Firehose "https://github.com/linux-msm/qdl/blob/master/firehose.c"
    click KS "https://github.com/linux-msm/qdl/blob/master/ks.c"
    click Ramdump "https://github.com/linux-msm/qdl/blob/master/ramdump.c"
    click UFS "https://github.com/linux-msm/qdl/blob/master/ufs.c"
    click Program "https://github.com/linux-msm/qdl/blob/master/program.c"
    click Patch "https://github.com/linux-msm/qdl/blob/master/patch.c"
    click Util "https://github.com/linux-msm/qdl/blob/master/util.c"
    click UX "https://github.com/linux-msm/qdl/blob/master/ux.c"
    click Read "https://github.com/linux-msm/qdl/blob/master/read.c"

    %% Style Classes
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef module fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef protocol fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef util fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
