# qualcomm/qdlrs architecture

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

- Interactive diagram: https://gitdiagram.com/qualcomm/qdlrs
- Repository: https://github.com/qualcomm/qdlrs

## Overview

#### Purpose and workspace shape
This Rust workspace implements Qualcomm EDL (“9008”) host tooling: Sahara bootrom communication, Firehose programmer operations, storage flashing, and crash RAM-dump collection. Workspace/package composition is defined in `Cargo.toml`, with the reusable protocol library in `qdl/` and two binaries in `cli/` and `qramdump/`.

#### Executable entry points
`cli/src/main.rs` is the `qdl-rs` command entry point. It parses transport, loader, storage, reset, and command options, then drives device initialization and operations such as dump, GPT inspection, partition write/erase, reset, and flashing. `qramdump/src/main.rs` is a separate recovery-oriented executable that connects to a crashed EDL device and receives selected memory regions.

#### Protocol core: Sahara bootstrap
The library API begins in `qdl/src/lib.rs`. Sahara protocol state and message exchange live in `qdl/src/sahara.rs`, while protocol data structures are centralized in `qdl/src/types.rs`. This stage communicates with the boot ROM, handles the initial handshake, and transfers the supplied programmer/loader so the device can transition to Firehose-capable operation.

#### Transport boundary
Host/device I/O is abstracted behind serial and USB implementations: `qdl/src/serial.rs` and `qdl/src/usb.rs`. CLI tools select a backend and device path or USB serial number; platform driver availability determines whether serial or direct USB is usable. Above this boundary, Sahara and Firehose logic should operate independently of the physical transport.

#### Firehose operations and data parsing
The library’s Firehose-facing operations and XML/response handling are exposed through `qdl/src/lib.rs` and parsing support in `qdl/src/parsers.rs`. The operational boundary is the device-resident Firehose programmer loaded by Sahara: host commands become Firehose requests for storage initialization, raw reads/writes, erase, GPT access, memory peek, reset, and device logging. Storage behavior is parameterized by media type (eMMC/UFS/NVMe/NAND), physical partition/LUN, slot, and sector size.

#### Flashing pipeline
The high-level flash workflow is implemented in `cli/src/flasher.rs`. It consumes Qualcomm `rawprogram*.xml` and optional `patch*.xml` manifests, resolves referenced image files, and applies their programming/patch instructions through the initialized Firehose session. `cli/src/programfile.rs` models or processes program-file input used by this workflow. Manifest-provided LUN information is an important distinction from direct storage commands, which require an explicit physical-partition index.

#### Safety and lifecycle controls
`cli/src/main.rs` exposes destructive direct operations separately from manifest flashing, with options for bypassing storage writes, packet hashing, read-back verification, and storage-init control. Loader upload and Flash operations occur before reset; reset mode controls whether the target returns to EDL, powers off, or boots the system. Shared CLI-side support is in `cli/src/util.rs`.

#### Runtime and external dependencies
All components are native Rust executables built with Cargo; CI workflows are under `.github/workflows/build.yml` and `.github/workflows/qcom-preflight-checks.yml`. The only runtime service is a physically connected Qualcomm device in EDL mode, accessed via a USB/serial driver and requiring a device/platform-specific Firehose programmer binary supplied by the operator.

Main entry points: [`qdl/src/lib.rs`](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/lib.rs) (Firehose session), [`qdl/src/sahara.rs`](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/sahara.rs) (Sahara bootstrap), [`cli/src/main.rs`](https://github.com/qualcomm/qdlrs/blob/main/cli/src/main.rs) (qdl-rs CLI), [`qramdump/src/main.rs`](https://github.com/qualcomm/qdlrs/blob/main/qramdump/src/main.rs) (qramdump)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tools["Host executables"]
  node_cli["qdl-rs CLI<br/>command binary<br/>[main.rs]"]
  node_ramdump["qramdump<br/>recovery binary<br/>[main.rs]"]
  node_cli_util["CLI support<br/>[util.rs]"]
  node_flasher["Flash workflow<br/>flash pipeline<br/>[flasher.rs]"]
  node_programfile["Program-file input<br/>manifest model<br/>[programfile.rs]"]
end

subgraph group_core["Protocol library"]
  node_library_api["qdl library API<br/>protocol facade<br/>[lib.rs]"]
  node_sahara["Sahara bootstrap<br/>bootrom protocol<br/>[sahara.rs]"]
  node_protocol_types["Protocol types<br/>protocol data<br/>[types.rs]"]
  node_firehose["Firehose session<br/>device operation protocol<br/>[lib.rs]"]
  node_parsers["XML and responses<br/>parser<br/>[parsers.rs]"]
  node_serial["Serial transport<br/>transport backend<br/>[serial.rs]"]
  node_usb["USB transport<br/>transport backend<br/>[usb.rs]"]
end

subgraph group_device["Target device"]
  node_edl_device{{"Qualcomm EDL device<br/>physical target"}}
  node_programmer["Firehose programmer<br/>operator-supplied binary"]
  node_storage[("Target storage and RAM<br/>device resources")]
end

node_workspace["Cargo workspace<br/>Rust workspace<br/>[Cargo.toml]"]

node_workspace -->|"builds"| node_cli
node_workspace -->|"builds"| node_ramdump
node_cli -->|"uses"| node_cli_util
node_cli -->|"initializes and commands"| node_library_api
node_ramdump -->|"uses"| node_library_api
node_cli -->|"runs flash mode"| node_flasher
node_flasher -->|"reads manifests"| node_programfile
node_flasher -->|"programs and patches"| node_firehose
node_library_api -->|"bootstraps"| node_sahara
node_library_api -->|"exposes"| node_firehose
node_sahara -->|"uses messages"| node_protocol_types
node_sahara -->|"uses transport"| node_serial
node_sahara -->|"uses transport"| node_usb
node_firehose -->|"parses XML"| node_parsers
node_firehose -->|"uses transport"| node_serial
node_firehose -->|"uses transport"| node_usb
node_serial -->|"device I/O"| node_edl_device
node_usb -->|"device I/O"| node_edl_device
node_sahara -->|"uploads"| node_programmer
node_programmer -->|"enables session"| node_firehose
node_firehose -->|"reads, writes, erases, dumps"| node_storage
node_ramdump -->|"receives memory regions"| node_storage

click node_workspace "https://github.com/qualcomm/qdlrs/blob/main/Cargo.toml"
click node_cli "https://github.com/qualcomm/qdlrs/blob/main/cli/src/main.rs"
click node_ramdump "https://github.com/qualcomm/qdlrs/blob/main/qramdump/src/main.rs"
click node_cli_util "https://github.com/qualcomm/qdlrs/blob/main/cli/src/util.rs"
click node_flasher "https://github.com/qualcomm/qdlrs/blob/main/cli/src/flasher.rs"
click node_programfile "https://github.com/qualcomm/qdlrs/blob/main/cli/src/programfile.rs"
click node_library_api "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/lib.rs"
click node_sahara "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/sahara.rs"
click node_protocol_types "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/types.rs"
click node_firehose "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/lib.rs"
click node_parsers "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/parsers.rs"
click node_serial "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/serial.rs"
click node_usb "https://github.com/qualcomm/qdlrs/blob/main/qdl/src/usb.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_ramdump,node_cli_util,node_flasher,node_programfile toneBlue
class node_library_api,node_sahara,node_protocol_types,node_firehose,node_parsers,node_serial,node_usb toneAmber
class node_edl_device,node_programmer,node_storage toneMint
class node_workspace toneNeutral
```

## Components

### Host executables

- [qdl-rs CLI](https://github.com/qualcomm/qdlrs/blob/main/cli/src/main.rs): command binary · General EDL management, storage, and flashing entry point. · `cli/src/main.rs`
- [qramdump](https://github.com/qualcomm/qdlrs/blob/main/qramdump/src/main.rs): recovery binary · Collects selected RAM regions from crashed EDL devices. · `qramdump/src/main.rs`
- [CLI support](https://github.com/qualcomm/qdlrs/blob/main/cli/src/util.rs): shared CLI support · `cli/src/util.rs`
- [Flash workflow](https://github.com/qualcomm/qdlrs/blob/main/cli/src/flasher.rs): flash pipeline · Applies manifest programming and patch instructions. · `cli/src/flasher.rs`
- [Program-file input](https://github.com/qualcomm/qdlrs/blob/main/cli/src/programfile.rs): manifest model · `cli/src/programfile.rs`

### Protocol library

- [qdl library API](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/lib.rs): protocol facade · Exposes Sahara and Firehose-facing operations. · `qdl/src/lib.rs`
- [Sahara bootstrap](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/sahara.rs): bootrom protocol · Handshakes with boot ROM and uploads the programmer. · `qdl/src/sahara.rs`
- [Protocol types](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/types.rs): protocol data · `qdl/src/types.rs`
- [Firehose session](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/lib.rs): device operation protocol · Issues storage, GPT, memory, reset, and logging requests. · `qdl/src/lib.rs`
- [XML and responses](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/parsers.rs): parser · Parses Firehose XML and device responses. · `qdl/src/parsers.rs`
- [Serial transport](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/serial.rs): transport backend · `qdl/src/serial.rs`
- [USB transport](https://github.com/qualcomm/qdlrs/blob/main/qdl/src/usb.rs): transport backend · `qdl/src/usb.rs`

### Target device

- **Qualcomm EDL device**: physical target · Boot ROM communicates over USB or serial in 9008 mode.
- **Firehose programmer**: operator-supplied binary · Device-specific loader uploaded before Firehose operations.
- **Target storage and RAM**: device resources · Media, LUNs, partitions, GPT, and crash memory regions.

### Other components

- [Cargo workspace](https://github.com/qualcomm/qdlrs/blob/main/Cargo.toml): Rust workspace · Builds the library and both native executables. · `Cargo.toml`

## Connections

- Cargo workspace → qdl-rs CLI: builds
- Cargo workspace → qramdump: builds
- qdl-rs CLI → CLI support: uses
- qdl-rs CLI → qdl library API: initializes and commands
- qramdump → qdl library API: uses
- qdl-rs CLI → Flash workflow: runs flash mode
- Flash workflow → Program-file input: reads manifests
- Flash workflow → Firehose session: programs and patches
- qdl library API → Sahara bootstrap: bootstraps
- qdl library API → Firehose session: exposes
- Sahara bootstrap → Protocol types: uses messages
- Sahara bootstrap → Serial transport: uses transport
- Sahara bootstrap → USB transport: uses transport
- Firehose session → XML and responses: parses XML
- Firehose session → Serial transport: uses transport
- Firehose session → USB transport: uses transport
- Serial transport → Qualcomm EDL device: device I/O
- USB transport → Qualcomm EDL device: device I/O
- Sahara bootstrap → Firehose programmer: uploads
- Firehose programmer → Firehose session: enables session
- Firehose session → Target storage and RAM: reads, writes, erases, dumps
- qramdump → Target storage and RAM: receives memory regions