Qualcomm Linux deb images

A collection of recipes to build Qualcomm Linux images for deb based operating systems.

The main goal of this project is to provide mainline-centric images for Qualcomm® IoT platforms as to demonstrate the state of upstream open source software, help developers getting started, and support continuous development and testing efforts.

Initially, this repository provides debos recipes based on Debian trixie for boards such as:

• Qualcomm RB1 (QRB2210)
• Qualcomm RB3 Gen 2 (QCS6490)
• ...and more!

We are also working towards providing ready-to-use, pre-built images – stay tuned!

CI Status

Requirements

debos is required to build the debos recipes. Recent debos packages should be available in Debian and Ubuntu repositories; there are debos installation instructions on the project's page, notably for Docker images and to build debos from source. Make sure to use at least version 1.1.5 which supports setting the sector size.

qdl is typically used for flashing. While recent versions are available in Debian and Ubuntu, make sure to use at least version 2.1 as it contains important fixes.

Steps

(optional) Build and flash U-Boot

U-Boot is needed for the RB1 board. If you are not targeting this board, you can go to the next section.

Building U-Boot for the RB1 requires the following extra build-dependencies:

apt -y install git crossbuild-essential-arm64 make bison flex bc libssl-dev gnutls-dev xxd coreutils gzip mkbootimg

To build U-Boot for the RB1, run:

scripts/build-u-boot-rb1.sh

(optional) Build custom kernel

By default the image recipes will install the kernel provided by Debian.

Build a custom kernel if you want to run qcom-next, the kernel which the CI images use and recommended for maximum hardware compatibility, mainline or linux-next. See the Kernel section for the build-dependencies and the build instructions, then come back here.

Build the image

Building the image requires the following build-dependencies:

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

To build flashable assets for all supported boards, follow these steps:

1. build tarballs of the root filesystem and DTBs

   make rootfs.tar
   
   # (optional) if you've built a local kernel, copy it to `debos-recipes/local-debs/`
   # and run this instead:
   #EXTRA_DEBOS_OPTS="-t localdebs:local-debs/ -t kernelpackages:none" make rootfs.tar
   

2. build disk and filesystem images from the root filesystem tarball

   # the default is to build a UFS image
   make disk-ufs.img
   
   # (optional) if you want SD card images or support for eMMC boards, run
   # this as well:
   make disk-sdcard.img
   

3. build flashable assets from downloaded boot binaries, the DTBs, and pointing at the UFS/SD card disk images

   make flash
   
   # (optional) if you've built U-Boot for the RB1, run this instead:
   #EXTRA_DEBOS_OPTS="-t u_boot_rb1:u-boot/rb1-boot.img" make flash
   
   # (optional) build only a subset of boards:
   #EXTRA_DEBOS_OPTS="-t target_boards:qcs615-ride,qcs6490-rb3gen2-vision-kit" make flash
   

4. enter Emergency Download Mode (see section below) and flash the resulting images with QDL

   # for RB3 Gen2 Vision Kit or UFS boards in general
   cd flash_qcs6490-rb3gen2-vision-kit_ufs
   qdl --storage ufs prog_firehose_ddr.elf rawprogram[0-9].xml patch[0-9].xml
   
   # for RB1 or eMMC boards in general
   cd flash_qrb2210-rb1_emmc
   qdl --allow-missing --storage emmc prog_firehose_ddr.elf rawprogram[0-9].xml patch[0-9].xml
   

Debos tips

By default, debos will try to pick a fast build backend. It will prefer to use its KVM backend (-b kvm) when available, and otherwise a UML environment (-b uml). If none of these work, a solid backend is QEMU (-b qemu). Because the target images are arm64, building under QEMU can be really slow, especially when building from another architecture such as amd64.

To build large images, the debos resource defaults might not be sufficient. Consider raising the default debos memory and scratchsize settings. This should provide a good set of minimum defaults:

debos --fakemachine-backend qemu --memory 1GiB --scratchsize 6GiB debos-recipes/qualcomm-linux-debian-image.yaml

Options for debos recipes

A few options are provided in the debos recipes; for the root filesystem recipe:

• localdebs: path to a directory with local deb packages to install (NB: debos expects relative pathnames)
• xfcedesktop: install an Xfce desktop environment; default: console only environment
• gnomedesktop: install a GNOME desktop environment; default: console only environment
• westonsession: install a Weston session; default: console only environment
• multimedia: install the Qualcomm accelerated multimedia stack; default: don't install
• overlays: a ,-separated list of rootfs overlays to add from debos-recipes/overlays/. See the Supported overlays section below.
• kernelpackages: a ,-separated list of kernel packages to install from apt; defaults to linux-image-arm64. Set it to none when you are installing a local kernel package. See the Kernel section below for more information.
• kernelpackage: deprecated, superseded by kernelpackages; still accepted as a single package name for backwards compatibility.
• qliaptrepo: configure the Qualcomm Linux APT repository in the root filesystem; defaults to true. Set it to false to leave the image with no Qualcomm Linux APT sources.
• suite: Debian suite to use, defaults to trixie.
• snapshot: use snapshot apt archives for a reproducible build (YYYYMMDDTHHMMSSZ); logged to /etc/buildinfo as SNAPSHOT=<date>. Live mirrors are restored in the final image to allow upgrades. See docs/snapshot.md for full usage and internals.

For the image recipe:

• dtb: override the firmware provided device tree with one from the Linux kernel, e.g. qcom/qcs6490-rb3gen2.dtb; default: don't override
• imagetype: either ufs (the default) or sdcard; UFS images are named disk-ufs.img and use 4096-byte sectors and SD card images are named disk-sdcard.img and use 512-byte sectors
• imagesize: set the output disk image size; default: 6GiB

For the flash recipe:

• u_boot_rb1: prebuilt U-Boot binary for RB1 in Android boot image format -- see below (NB: debos expects relative pathnames)
• target_boards: comma-separated list of board names to build (default: all). Accepted values are the board names defined in the flash recipe, e.g. qcs615-ride, qcs6490-rb3gen2-vision-kit, qcs8300-ride, qcs9100-ride-r3, qrb2210-rb1.

Note: Boards whose required device tree (.dtb) is not present in dtbs.tar.gz are automatically skipped during flash asset generation.

Deprecated flash options:

• build_qcs615, build_qcm6490, build_qcs8300, build_qcs9100, build_rb1: these per-family/per-board toggles are deprecated and will be removed. Use target_boards instead to select which boards to build.

Here are some example invocations:

# build the root filesystem with Xfce
debos -t xfcedesktop:true debos-recipes/qualcomm-linux-debian-rootfs.yaml

# build an image where systemd overrides the firmware device tree with the one
# for RB3 Gen2
debos -t dtb:qcom/qcs6490-rb3gen2.dtb debos-recipes/qualcomm-linux-debian-image.yaml

# build an SD card image
debos -t imagetype:sdcard debos-recipes/qualcomm-linux-debian-image.yaml

# build flash assets for a subset of boards
# (see flash recipe for accepted board names)
debos -t target_boards:qcs615-ride,qcs6490-rb3gen2-vision-kit debos-recipes/qualcomm-linux-debian-flash.yaml

Note that these manual invocations may fail because the debos defaults, like scratchsize, are too small for some recipes. We encourage you to stick to the existing Makefile targets instead.

Under the hood, the Makefile just calls debos on recipes from the debos-recipes directory, notably to set large enough memory and scratchsize settings. To pass extra options to debos invocations, use EXTRA_DEBOS_OPTS, e.g.:

make EXTRA_DEBOS_OPTS="-t xfcedesktop:true" disk-ufs.img

Supported overlays

Multiple overlays are available to include additional files not provided by Debian packages into the image’s root file system. They are located in debos-recipes/overlays/.

By default, no overlays are used. Overlays can be selected with the -t overlays:<value> option; multiple overlays can be specified, separated by a comma (,).

Here is the list of supported overlays:

none

Special value to disable all overlays; this is the default.

Flash the image

The disk-sdcard.img disk image can simply be written to an SD card, albeit most Qualcomm boards boot from internal storage by default. With an SD card, the board will use boot firmware from internal storage (eMMC or UFS) and do an EFI boot from the SD card if the firmware can't boot from internal storage.

For UFS boards, if there is no need to update the boot firmware, the disk-ufs.img disk image can also be flashed on the first LUN of the internal UFS storage with qdl and the provided rawprogram-ufs.xml file.

Put the board in "emergency download mode" (EDL; see next section) and run:

qdl --storage ufs prog_firehose_ddr.elf rawprogram-ufs.xml

Make sure to use prog_firehose_ddr.elf for the target platform, such as this version from the QCM6490 boot binaries or this version from the RB1 rescue image.

Emergency Download Mode (EDL)

In EDL mode, the board will receive a flashing program over its USB type-C cable, and that program will receive data to flash on the internal storage. This is a lower level mode than fastboot which is implemented by a higher-level bootloader.

To enter EDL mode:

1. remove power to the board
2. remove any cable from the USB type-C port
3. on some boards, it's necessary to set some DIP switches
4. press the F_DL button while turning the power on
5. connect a cable from the flashing host to the USB type-C port on the board
6. run qdl to flash the board

NB: It's also possible to run qdl from the host while the board is not connected, then start the board directly in EDL mode.

Boot the image

Login

Once the image has booted, you can log in as the debian user, with the default debian password. The image should then ask you to change this default password to a safe one.

Kernel

When building an image locally, by default the recipe will install the latest kernel from Debian.

All of the CI-built images instead install qcom-next, the Qualcomm Linux integration branch, which carries additional platform support.

Build it yourself to get the same kernel the CI images use.

Building a Linux kernel deb requires the following build-dependencies:

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

Note that to install libssl-dev:arm64 on a non-arm64 host, you will need to enable arm64 as a foreign architecture first by running dpkg --add-architecture arm64 && apt update.

Then build qcom-next with the recommended config fragments:

# CI pins an exact version with `--ref`; without one this builds the qcom-next
# branch tip.
scripts/build-linux-deb.py --qcom-next prune.config qcom.config kernel-configs/*.config

Other trees can be built for comparison, for instance to check whether a problem also affects upstream:

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

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

To build an image with a locally-built kernel, copy the resulting debs to debos-recipes/local-debs/ and disable the apt-installed kernel when building the root filesystem:

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

Prebuilt Qualcomm kernel packages are also available from the overlay apt repository, as an alternative to building one:

# the trailing plus sign is doubled because apt reads a single one in a package
# name as a request to install the package
EXTRA_DEBOS_OPTS="-t kernelpackages:linux-image-<version>-qcom1++" make rootfs.tar

Development

Want to join in the development? Changes welcome! See CONTRIBUTING.md file for step by step instructions.

Boot an image locally with QEMU (helper script)

Use the scripts/run-qemu.py helper to boot generated disk images under QEMU. It automatically:

• Detects your OS and locates an aarch64 UEFI firmware (Debian/Ubuntu: qemu-efi-aarch64; macOS Homebrew: edk2-aarch64).
• Presents the image via SCSI with the correct sector size (4096 for UFS, 512 for SD/eMMC).
• Creates a temporary qcow2 copy-on-write overlay by default (your base image remains unchanged).
• Provides GUI display by default (Gtk on Linux, Cocoa on macOS) and headless mode with --headless.

Dependencies:

• Debian/Ubuntu: sudo apt install qemu-efi-aarch64 qemu-system-arm qemu-utils
• macOS (Homebrew): brew install qemu

Basic usage:

# Auto-detects disk-ufs.img or disk-sdcard.img in the current directory
scripts/run-qemu.py

# Explicit storage type (sector size set accordingly)
scripts/run-qemu.py --storage ufs
scripts/run-qemu.py --storage sdcard

# Use a specific image path
scripts/run-qemu.py --image /path/to/disk-ufs.img

# Run headless (no GUI), with serial console on stdio
scripts/run-qemu.py --headless

# Disable the COW overlay to persist changes to the image
scripts/run-qemu.py --no-cow

# Pass extra QEMU arguments (example: 4 vCPUs and 4 GiB RAM)
scripts/run-qemu.py --qemu-args "-smp 4 -m 4096"

Notes:

• If neither disk-ufs.img nor disk-sdcard.img is found and --image is not provided, the script will exit with an error.
• On Linux, the script looks for /usr/share/qemu-efi-aarch64/QEMU_EFI.fd. On macOS with Homebrew, it uses share/qemu/edk2-aarch64-code.fd from the qemu formula.
• The overlay is cleaned up automatically when QEMU exits. Use --no-cow to make changes persistent on the base image.

Reporting Issues

We'd love to hear if you run into issues or have ideas for improvements. Report an Issue on GitHub to discuss, and try to include as much information as possible on your specific environment.

License

This project is licensed under the BSD-3-clause License. See LICENSE.txt for the full license text.

Footnotes

1. these builds compile the kernel, build an image and boot test the image in a single workflow, so the Kernel build reports all three. ↩ ↩²