qdl: Flashing over EDL Mode

EDL mode là gì#

EDL (Emergency Download) là chế độ boot đặc biệt có sẵn trên các SoC Qualcomm, cho phép truy cập mức thấp để nạp firmware và cứu máy. Chế độ này đi vòng qua quá trình boot thông thường, nên vẫn nạp được firmware cả khi thiết bị không boot lên nữa hoặc bootloader đang bị khoá.

Cách đưa board vào EDL mode khác nhau tuỳ thiết bị, phải xem tài liệu của board. Với RB5, xem lại bài Linaro: Flash Bootloader, Boot Image và Rootfs.

Build#

1
sudo apt install libxml2-dev libusb-1.0-0-dev libzip-dev meson ninja-build help2man
2
meson setup build
3
meson compile -C build

1
brew install libxml2 libusb libzip meson ninja help2man
2
meson setup build
3
meson compile -C build

1
sudo port install libxml2 libusb libzip meson ninja help2man
2
meson setup build
3
meson compile -C build

1
pacman -S base-devel --needed
2
pacman -S git
3
pacman -S help2man
4
pacman -S mingw-w64-x86_64-gcc
5
pacman -S mingw-w64-x86_64-meson
6
pacman -S mingw-w64-x86_64-ninja
7
pacman -S mingw-w64-x86_64-libusb
8
pacman -S mingw-w64-x86_64-libxml2
9
pacman -S mingw-w64-x86_64-libzip

1
meson setup build
2
meson compile -C build

1
meson setup build -Dzip-container=disabled

Flash cơ bản#

Chạy qdl --help để xem đầy đủ cách dùng. Ví dụ flash một bản build dạng FLAT:

1
qdl prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Nếu máy host đang cắm nhiều board, chỉ định số serial của board cần flash bằng --serial:

1
qdl --serial=0AA94EFD prog_firehose_ddr.elf rawprogram*.xml patch*.xml

1
qdl flash <installer.zip>

1
qdl flash flashmap.json

1
qdl flash installer.zip::layout1/ufs

1
qdl flash contents.xml

1
qdl flash contents.xml::ufs,safe_rtos

1
qdl create-zip installer.zip contents.xml

1
qdl create-zip installer-ufs.zip contents.xml::ufs

Chạy thử không cần thiết bị (dry run)#

Tuỳ chọn --dry-run chạy qdl mà không kết nối hay flash thiết bị nào. Cách này hữu ích để kiểm tra file XML descriptor và tham số programmer, hoặc để sinh bảng digest cho VIP:

1
qdl --dry-run prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Đọc và ghi binary trực tiếp#

Ngoài việc flash theo mô tả XML, qdl còn đọc ghi binary trực tiếp:

1
qdl prog_firehose_ddr.elf [read | write] [address specifier] <binary>...

Có thể đưa nhiều lệnh read và write trong cùng một lần chạy. Address specifier nhận các dạng sau:

Validated Image Programming (VIP)#

qdl hỗ trợ chế độ VIP, chế độ này được kích hoạt khi target bật Secure Boot. VIP kiểm soát những packet nào được phép gửi tới target: nó băm toàn bộ dữ liệu nhận được rồi so từng digest với mục kế tiếp trong một bảng digest đã nạp sẵn. Digest khớp thì packet được chấp nhận; không khớp thì packet bị từ chối và target dừng lại.

Muốn dùng VIP, phải sinh bảng digest trước khi flash. Chạy qdl với tuỳ chọn --create-digests kèm đường dẫn lưu bảng VIP. Lưu ý --create-digests tự bật luôn chế độ dry-run, nên không cần kết nối thiết bị:

1
mkdir vip
2
qdl --create-digests=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Kết quả sinh ra ba loại file:

• DIGEST_TABLE.bin — chứa bảng digest SHA256 của mọi Firehose packet sẽ gửi tới target. Đây là bảng trung gian, chỉ dùng để sinh tiếp DigestsToSign.bin và các file ChainedTableOfDigests<n>.bin, bản thân qdl không dùng trực tiếp khi flash VIP.
• DigestsToSign.bin — gồm 53 digest đầu tiên cộng với hash SHA256 của ChainedTableOfDigests0.bin. File này phải được chuyển sang định dạng MBN rồi ký bằng sectools:

1
sectools mbn-tool generate --data DigestsToSign.bin --mbn-version 6 --outfile DigestsToSign.bin.mbn
2
sectools secure-image --sign DigestsToSign.bin.mbn --image-id=VIP

Xem security profile của SoC đang dùng để biết cần phiên bản định dạng MBN nào.

• ChainedTableOfDigests<n>.bin — chứa phần digest còn lại, chia thành nhiều file, mỗi file tối đa 255 digest. File nào chưa phải cuối cùng thì được nối thêm hash SHA256 của bảng chained kế tiếp. File cuối cùng được nối thêm một byte 0 để kích thước không phải bội số của sector size.

Khi flash board ở chế độ VIP, chỉ ra nơi lưu các bảng đã sinh và đã ký bằng --vip-table-path:

1
qdl --vip-table-path=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Hai tuỳ chọn --vip-table-path và --create-digests loại trừ nhau, không dùng cùng lúc được.

1
qdl --dry-run --vip-table-path=./vip prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Target cần nhiều programmer#

Một số target cần nạp nhiều file mới vào được Firehose programmer; những target này yêu cầu nhiều image qua Sahara. qdl có ba cách cung cấp các image đó.

Cách 1: tham số dòng lệnh. Tham số programmer nhận một danh sách các cặp “id” và “filename”, cặp ngăn nhau bằng dấu phẩy, còn id và filename ngăn nhau bằng dấu hai chấm. Mỗi filename ứng với Sahara image của id tương ứng:

1
qdl 13:prog_firehose_ddr.elf,42:the-answer rawprogram.xml

Cách 2: file XML cấu hình Sahara. Các bản META dạng flattened có sẵn các image cần nạp để vào Firehose mode, kèm một file XML sahara_config định nghĩa Sahara image id cho từng image. Nếu programmer được chỉ định là một file XML cấu hình Sahara, qdl sẽ phân tích file đó rồi nạp và phục vụ các file được tham chiếu khi thiết bị yêu cầu:

1
qdl sahara_programmer.xml rawprogram.xml

Cách 3: programmer archive. Việc liệt kê tay danh sách id và filename vừa rườm rà vừa dễ sai, nên qdl chấp nhận một “programmer archive” để dùng công cụ y như với target chỉ cần một programmer. Archive này chứa các Sahara image, mỗi image gắn với Sahara id mà target cần.

qdl tạo được archive từ chính các dạng mô tả programmer mà nó nhận khi flash. Từ danh sách Sahara image trên dòng lệnh:

1
qdl create-sahara-archive programmer.bin 13:prog_firehose_ddr.elf,42:the-answer

Từ file XML cấu hình Sahara:

1
qdl create-sahara-archive programmer.bin sahara_programmer.xml

Từ file contents XML:

1
qdl create-sahara-archive programmer.bin contents.xml

Khi contents XML mô tả nhiều tổ hợp storage hoặc flavor, chọn đúng một tổ hợp bằng cú pháp ::specifier giống như với flash:

1
qdl create-sahara-archive programmer.bin contents.xml::ufs

Sau đó truyền programmer.bin cho qdl, các image bên trong sẽ được phục vụ theo thứ tự để vào Firehose mode.

Thu thập crash dump#

Khi một target Qualcomm bị crash hoặc bị ép vào chế độ crash dump, bootloader sẽ liệt kê lại thiết bị qua USB với Product ID 900e và cung cấp các vùng nhớ để thu thập qua giao thức Sahara.

Có thể kích hoạt một kernel crash trên target bằng:

1
echo c > /proc/sysrq-trigger

Trên máy host, dùng qdl ramdump để thu thập dump:

1
qdl ramdump -o ./ramdump

Mỗi vùng nhớ được cung cấp sẽ ghi thành một file riêng trong ./ramdump. Muốn lấy một số vùng nhất định, truyền thêm bộ lọc ngăn nhau bằng dấu phẩy:

1
qdl ramdump -o ./ramdump OCIMEM,CODERAM

Sahara kickstart cho thiết bị flashless (qdl ks)#

Lệnh con qdl ks (kickstart) dùng giao thức Sahara để nạp image từ host xuống thiết bị. Nó nhắm tới các thiết bị boot kiểu flashless như Qualcomm Cloud AI 100, loại lấy firmware từ host mỗi lần boot thay vì lưu sẵn trên thiết bị.

Khác với flash thông thường, kickstart dừng lại ngay khi Sahara xong: không nạp Firehose programmer và không ghi gì vào storage.

Bắt buộc có một tham số: -s id:path để đăng ký một ánh xạ image. Tham số này lặp lại được, mỗi dòng cho một Sahara image id mà thiết bị có thể yêu cầu.

Mặc định thiết bị được tìm qua đúng các backend mà những lệnh con khác dùng, nên --backend và --serial chọn thiết bị y như khi flash:

1
qdl ks -s 13:prog_firehose_ddr.elf

Với thiết bị được kernel driver phơi ra dưới dạng một node, chẳng hạn các Sahara endpoint của MHI, dùng -p. Tuỳ chọn này làm việc bằng các thao tác open/read/write thông thường chứ không qua backend:

1
qdl ks -p /dev/mhi0_QAIC_SAHARA \
2
       -s 1:/opt/qti-aic/firmware/fw1.bin \
3
       -s 2:/opt/qti-aic/firmware/fw2.bin

Vì -p đã chỉ thẳng transport nên không dùng chung được với --serial hay --backend.

Các file được ánh xạ không cần tồn tại ngay lúc chạy lệnh. Nếu qdl ks không mở được file được yêu cầu, thiết bị sẽ tự quyết định bước tiếp theo. Nhờ vậy có thể gắn qdl ks vào một udev rule duy nhất phục vụ nhiều cấu hình thiết bị, ví dụ một image huấn luyện DDR tuỳ chọn chỉ có mặt trên vài hệ thống.

Flash từ WSL2 bằng usbipd-win#

Trên Windows, qdl chạy được bên trong một bản phân phối WSL2, nhưng WSL2 mặc định không thấy thiết bị USB: phải chuyển tiếp thiết bị từ phía Windows bằng usbipd-win. Cài nó ở phía Windows (winget install usbipd), rồi chuyển tiếp thiết bị EDL vào WSL.

Thiết bị EDL xuất hiện với Vendor ID 05c6 và Product ID 9008 (Firehose), 900e (crash dump), 90db (diag dump) hoặc 901d. Từ terminal Windows, liệt kê thiết bị đang cắm và ghi lại BUSID của thiết bị EDL:

1
usbipd list

Mỗi thiết bị phải được bind một lần trước khi attach. Bước bind cần PowerShell chạy quyền Administrator, nhưng nó tồn tại qua các lần khởi động lại, nên mỗi thiết bị chỉ làm một lần:

1
usbipd bind --busid <BUSID>

Bước attach thì không cần quyền Administrator và gọi được từ trong WSL bằng cách chạy file thực thi phía Windows:

1
usbipd.exe attach --wsl --busid <BUSID>

Attach xong, thiết bị xuất hiện trong WSL (kiểm tra bằng lsusb, tìm 05c6:9008) và qdl flash được như bình thường.

1
BUSID=$(usbipd.exe list | grep -iE '9008|900e|901d|90db' |
2
        awk '{print $1}' | tr -d '\r')
3
usbipd.exe attach --wsl --busid "$BUSID"

nbdkit plugin#

Ngoài chương trình qdl, còn build được một nbdkit plugin. Plugin này nạp firehose programmer rồi phơi một physical partition (LUN) ra host dưới dạng block device, nhờ vậy sửa được bảng phân vùng và mount được các partition bằng công cụ thông thường. Xem docs/nbd.md để biết cách build và ví dụ sử dụng.

Chạy test và sinh man page#

Chạy bộ integration test bằng meson với tham số test:

1
meson test -C build

Nếu lúc configure có sẵn cmocka, Meson cũng build và chạy bộ unit test, trong đó có các test về đường dẫn của program_load_xml. Chạy riêng unit test bằng:

1
meson test -C build --suite unit

Sinh man page bằng target manpages:

1
meson compile manpages -C build

Tham khảo#

1. linux-msm/qdl trên GitHub — README, đối chiếu ngày 23/09/2026 (v2.8).
2. CONTRIBUTING.md — coding style, checkpatch, markdown-lint và cách gửi pull request.
3. Qualcomm EDL mode — giới thiệu chung về EDL.