Qcom Deb Build Image

Build a Qualcomm Linux Debian image with debos

Builds the Debian (trixie) images from qcom-deb-images the way the project's CI does: debos recipes driven by the repo's Makefile, which sets the memory/scratchsize that the recipes need. Prefer the Makefile targets over calling debos by hand — the raw defaults are too small for these recipes.

Prerequisites

• A qcom-deb-images checkout (git clone https://github.com/qualcomm-linux/qcom-deb-images).
• debos ≥ 1.1.5 (needs the sector-size support). If debos is not on PATH, the Makefile auto-falls back to running the ghcr.io/go-debos/debos:latest container via Docker (USE_CONTAINER=auto); force it either way with USE_CONTAINER=yes|no.
• Image build-deps on the host (native builds):

  sudo apt -y install debian-archive-keyring make mmdebstrap mtools python3-pexpect \
      python3-pytest qemu-efi-aarch64 qemu-system-arm xmlstarlet python3-defusedxml
  

• A fast debos backend. The Makefile picks --fakemachine-backend kvm when /dev/kvm exists, else qemu. Building arm64 under QEMU emulation on an x86 host is slow — expect a long first build.
• Tens of GB of free disk plus network access to the Debian archive and to Qualcomm/CodeLinaro boot-binary downloads (fetched during make flash).

Build stages

The build is three ordered Makefile targets. Run them from the checkout root.

1. Root filesystem + DTB tarballs — make rootfs.tar

Produces rootfs.tar and dtbs.tar.gz from debos-recipes/qualcomm-linux-debian-rootfs.yaml.

make rootfs.tar

Common rootfs options, passed via EXTRA_DEBOS_OPTS="-t key:value":

To fold in a locally built kernel (see step 0 below), drop the .debs in debos-recipes/local-debs/ and disable the apt kernel:

EXTRA_DEBOS_OPTS="-t localdebs:local-debs/ -t kernelpackages:none" make rootfs.tar

2. Disk images — make disk-ufs.img / make disk-sdcard.img

Builds a partitioned disk image from rootfs.tar via debos-recipes/qualcomm-linux-debian-image.yaml.

# default: UFS image, 4096-byte sectors
make disk-ufs.img

# SD card / eMMC boards: 512-byte sectors
make disk-sdcard.img

Image options (EXTRA_DEBOS_OPTS): imagetype:ufs|sdcard (the Makefile sets sdcard for you on the sdcard target), imagesize:<size> (default 6GiB), dtb:qcom/<board>.dtb to have systemd override the firmware-provided device tree (e.g. qcom/qcs6490-rb3gen2.dtb).

make all builds both disk-ufs.img and disk-sdcard.img.

3. Flashable assets — make flash

Downloads the per-board boot binaries + CDT, combines them with dtbs.tar.gz and the disk images, and writes one flash_<board>_<storage>/ directory per supported board (from debos-recipes/qualcomm-linux-debian-flash.yaml).

make flash

# only some boards (comma-separated; see the board list below):
EXTRA_DEBOS_OPTS="-t target_boards:qcs615-ride,qcs6490-rb3gen2-vision-kit" make flash

# include a locally built RB1 U-Boot (see step 0):
EXTRA_DEBOS_OPTS="-t u_boot_rb1:u-boot/rb1-boot.img" make flash

Boards whose .dtb is absent from dtbs.tar.gz are silently skipped, so confirm the directory for the board you want actually appears.

Optional pre-steps

0a. Local kernel deb — scripts/build-linux-deb.py

sudo apt -y install git crossbuild-essential-arm64 make flex bison bc libdw-dev \
    libelf-dev libssl-dev libssl-dev:arm64 dpkg-dev debhelper-compat kmod python3 rsync coreutils
# on a non-arm64 host, enable the foreign arch for libssl-dev:arm64 first:
#   sudo dpkg --add-architecture arm64 && sudo apt update

scripts/build-linux-deb.py kernel-configs/*.config              # mainline
scripts/build-linux-deb.py --linux-next kernel-configs/*.config # linux-next
scripts/build-linux-deb.py --qcom-next kernel-configs/*.config  # qcom-next

--qcom-next tracks the qualcomm-linux/kernel qcom-next branch (latest qcom-next-* tag) — often the most useful kernel for these boards, as it carries the Qualcomm platform patches ahead of mainline. --repo/--ref override the source for any other tree.

Then feed the resulting .debs into step 1 via localdebs: + kernelpackages:none.

0b. U-Boot for RB1 — scripts/build-u-boot-rb1.sh

The RB1 (qrb2210-rb1) is the board that needs U-Boot built from this repo and passed into make flash. (Other U-Boot-based boards such as the Arduino UNO Q get their U-Boot from the downloaded boot binaries, so they need no separate build step here.) Build it, then pass u_boot_rb1:u-boot/rb1-boot.img to make flash.

sudo apt -y install git crossbuild-essential-arm64 make bison flex bc libssl-dev \
    gnutls-dev xxd coreutils gzip mkbootimg
scripts/build-u-boot-rb1.sh

Supported boards (target_boards names)

target_boards accepts the board names from the flash recipe; the storage suffix on the output directory follows the board's ptool platform:

This covers most QLI PoR boards and all the Arduino Qualcomm boards. Board names, SoCs and storage change over time — always read debos-recipes/qualcomm-linux-debian-flash.yaml for the authoritative, current list rather than assuming from this table.

Locate the artifacts

All outputs land in the checkout root:

• rootfs.tar, dtbs.tar.gz — from step 1.
• disk-ufs.img (4096-byte sectors) / disk-sdcard.img (512-byte sectors) — from step 2.
• flash_<board>_<storage>/ — from step 3, each holding prog_firehose_ddr.elf, rawprogram[0-9].xml, patch[0-9].xml and the partition images. This is what qcom-deb-flash-boot consumes.

Report the disk image(s) and the flash_* directories that were produced, with timestamps, so a fresh build is distinguishable from a stale one.

Hand off

• To flash a board or boot the image under QEMU, use the qcom-deb-flash-boot skill.
• To validate a flashed board reaches a login shell over serial, use qcom-boot-validate — but note it cannot perform the first login on a fresh image. The debian account ships expired (chage --lastday 0), so the first login forces a password change, and the validator sends only one username + password before waiting for a shell prompt. Complete the password change once by hand over the console, then run qcom-boot-validate with --username debian --password '<new password>' (not the Yocto root credentials, and not the spent debian password) — see qcom-deb-flash-boot for the exact prompt flow.

Notes / gotchas

• Report debos failures verbatim (failing recipe + action) rather than retrying blindly; a plain retry is only worth it for transient archive/download errors.
• make flash reaches out to Qualcomm Software Center / CodeLinaro for boot binaries; a 404 or auth wall there is an upstream-URL problem, not a recipe bug — re-check the URLs in the flash recipe.
• make clean removes the disk images and tarballs; make clean-debos removes the .debos-* scratch dirs. Neither touches the flash_* dirs.
• The Makefile honours http_proxy (from the environment or apt config) to speed up repeated archive fetches.
• These are mainline-centric Debian trixie images; they are not the Yocto/QLI images — do not cross bundles or credentials with qcom-yocto-*.