QFIL 核心功能：Flat Build 与 Sparse Image、分区写入、备份与恢复
QFIL（Qualcomm Flash Image Loader）是 QPST 套件中最核心的烧录工具，负责将镜像文件通过 EDL（Emergency Download）模式写入设备存储。理解 Flat Build 与 Sparse Image 的区别、掌握分区写入与备份恢复操作，是进行设备固件维护与调试的基础。
3.1 Flat Build 与 Sparse Image 的加载机制
QFIL 在加载镜像时，会根据镜像本身的格式采用不同的处理路径。目前高通平台主要使用两种镜像格式：Flat Build 和 Sparse Image。两者的核心差异在于存储方式和烧录策略。
| 特性 | Flat Build | Sparse Image |
|---|---|---|
| 文件结构 | 一个二进制文件包含整个分区内容，包含未使用的空洞（用 0 填充）。 | 采用稀疏格式，只存储实际数据块，通过头部元数据描述数据布局。 |
| 文件大小 | 与分区大小完全一致，浪费空间。 | 压缩有效数据，文件大小通常远小于分区大小。 |
| 加载速度 | 慢，因为传输大量无意义填充数据。 | 快，只传输有效数据块。 |
| 适用场景 | 本地研发、快速验证，常用于体积较小的 bootloader 分区。 | 生产烧录、OTA 更新、大容量分区（如 system、userdata）。 |
QFIL 在加载镜像时，会自动检测镜像头部标记。如果检测到 0xED26FF3A（Sparse 格式魔数），则按 Sparse 协议解析；否则按 Flat Build 模式处理。实际操作中，用户只需在 QFIL 的 Select Build Type 下拉框中选择 Flat Build 或 Sparse Image，工具将自动适配。
rawprogram0.xml 时，务必确认 xml 中每个 <program> 标签的 Sparse 属性与实际镜像格式一致。例如：<program SECTOR_SIZE_IN_BYTES="512" file_sector_offset="0" filename="system.img" label="system" num_partition_sectors="512000" sparse="true" start_byte="0" start_sector="0">sparse="true" 但镜像为 Flat Build，QFIL 将报错 Sparse header magic error。
3.2 分区写入：从 xml 解析到 Flash 编程
QFIL 的分区写入流程完全由烧录配置文件（rawprogram0.xml 和 patch0.xml）驱动。整个过程分为四个阶段：
- 加载配置文件：QFIL 读取
rawprogram0.xml，解析出每个分区的物理地址、大小、镜像文件路径。 - 建立连接：通过 USB 发送 EDL 握手包，获取设备存储设备 ID 和分区信息。
- 逐分区写入：对 xml 中的每个 <program> 节点，执行擦除（Erase）→ 编程（Program）→ 验证（Verify）三步操作。
- 写入完成：发送
reset指令重启设备。
典型的写入日志片段如下：
2025-03-15 14:32:01.123 [INFO] 开始烧录 partition: 0:system
2025-03-15 14:32:01.125 [INFO] 擦除 sector 0 到 512000
2025-03-15 14:32:03.456 [INFO] 擦除完成，耗时 2.33 秒
2025-03-15 14:32:03.458 [INFO] 开始编程 system.img (Sparse)
2025-03-15 14:32:10.789 [INFO] 编程完成，写入 256 MB
2025-03-15 14:32:10.791 [INFO] 验证分区数据...
2025-03-15 14:32:12.012 [INFO] 验证通过，CRC32 校验匹配如果编程过程中出现校验失败，日志会提示：
2025-03-15 14:33:01.456 [ERROR] 验证失败：分区 system sector 4096 数据不一致
2025-03-15 14:33:01.457 [ERROR] 建议：重新执行擦除并再次编程，或检查镜像文件完整性bootloader 或 partition 分区前，务必确认镜像固件适用于当前设备型号。错误写入可能导致设备变砖，必须通过硬件短接或 JTAG 恢复。
3.3 备份与恢复：分区级与整片级操作
QFIL 提供了两种备份恢复模式：单分区备份恢复 和 整片备份恢复。备份的本质是读取存储设备指定扇区范围的数据，保存为 .img 或 .bin 文件。
3.3.1 单分区备份（指定分区读取）
在 QFIL 的 Tools 菜单下选择 Partition Manager，可列出所有分区及其起始扇区、大小。选中分区后点击 Read，指定保存路径即可备份。该操作常用于抓取损坏分区的原始数据用于离线分析。
备份命令等效于通过 QFIL 的底层 API 调用：
QFIL::ReadPartition( partition_name: "persist", start_sector: 4096, num_sectors: 2048, output: "./persist_backup.img" )
3.3.2 整片备份（全 Flash 读取）
整片备份用于设备完全变砖前的完整固件导出。操作步骤如下：
- 设备进入 EDL 模式。
- 在 QFIL 主界面选择 Tools → QFIL Tool → Read Flash。
- 设置输出文件路径，点击 Read。
- QFIL 将依次读取每个扇区，最终生成一个容量等于 Flash 总大小的
.bin文件。
3.3.3 恢复操作（分区写入）
恢复备份文件本质上是将备份的 .img 文件通过 QFIL 的分区写入功能写回。如果备份的是整片 Flash，需要在 rawprogram0.xml 中将所有分区指向备份文件中的对应扇区；或者通过 QFIL 的 Write Flash 功能直接指定 .bin 文件覆盖整片存储。
恢复整片备份的日志片段：
2025-03-15 15:01:23.456 [INFO] 开始整片写入：备份文件 full_flash_backup.bin
2025-03-15 15:01:23.458 [INFO] 目标设备存储容量: 8 GB (16777216 扇区)
2025-03-15 15:01:25.789 [INFO] 正在写入扇区 0-4095 (bootloader 区域)
2025-03-15 15:02:10.123 [INFO] 正在写入扇区 4096-8191 (persist 区域)
...
2025-03-15 16:35:45.678 [INFO] 整片写入完成，总计写入 8 GB，CRC32 整体校验通过3.4 错误排查与验证
| 常见错误 | 原因分析 | 解决方案 |
|---|---|---|
Sparse header magic error |
xml 中 sparse="true" 但实际为 Flat Build 镜像。 |
修改 xml 中对应的 sparse 属性为 false。 |
Device not in EDL mode |
设备未正确进入紧急下载模式。 | 按住 音量上 + 音量下 插入 USB，或使用 adb reboot edl 强制进入。 |
Partition write failed: sector out of range |
xml 中 num_partition_sectors 超过实际分区大小。 |
检查分区表，调整 start_sector 和 num_partition_sectors 参数。 |
Verification error: data mismatch |
镜像文件损坏或存储设备坏块。 | 重新下载镜像源文件，检查 USB 线缆，更换端口重试。 |
fc /b 或 diff）。如果差异出现在已知非关键区域（如 userdata 分区的日志），可忽略；若出现在 boot 或 system 分区，必须重新烧录。
3.5 性能优化：缩短烧录时间
对于大规模生产或频繁调试的场景，烧录时间直接影响效率。以下优化措施可显著缩短烧录周期：
- 使用 Sparse Image：相比 Flat Build，传输数据量可减少 60%~80%。
- 跳过空分区：在 xml 中删除未使用分区的
<program>节点，避免不必要的擦写。 - 禁用验证（生产环境）：在 QFIL 配置文件中设置
VerifyAfterProgram="0"，节省验证时间。但研发阶段建议保留验证。 - 升级 USB 速率：确保使用 USB 3.0 接口和高品质线缆，QFIL 支持 Bulk Transfer 模式，USB 3.0 理论速率可达 5 Gbit/s。
优化后的烧录时间对比：
优化前（Flat Build + 验证开启）：总耗时 183 秒
优化后（Sparse Image + 验证关闭）：总耗时 72 秒
优化比率：60.7%