Ubuntu 24.04 x15
Platform Summary
- Ubuntu 24.04 x15 (6.8.0-1089-qcom)
- Kernel 6.8.12
Qualcomm Ubuntu Build System (Ubuntu 24.04 x15)
This document describes how to work with the RISC and Qualcomm Ubuntu Board Support Package (BSP) release.
Introduction
A Makefile-based build system for Qualcomm Ubuntu projects, driven by YAML configuration for flexibility and automation.
| Feature | Description |
|---|---|
| Containerized | Uses Docker (advrisc/u24.04-qcsubv1) to ensure a consistent and reproducible build environment. |
| YAML-based Configuration | Machine, build parameters and kernel patch lists managed in configs/. |
| Kernel Patches | Kernel changes kept as patch files in patches/ and applied by git am. |
| RT Kernel | Optional PREEMPT_RT kernel (RT=1) with a selectable default boot kernel. |
| Automatic Logging | Build output automatically saved to timestamped files in logs/. Use NOLOG=1 to disable. |
| Debug / Release Mode | Selectable via BUILD_MODE=DEBUG|RELEASE. |
| Fast Module Debugging | Compile specific kernel subdirectories or out-of-tree modules via make modules M=.... |
Host machine requirements
- Ubuntu 22.04 or Ubuntu 24.04
- Intel Core-i7 Processor (>= 8 cores)
- 16+ GB RAM
- 350 GB free disk space (more is recommended and SSD is suggested for better performance)
- Docker version 29.1.4 or later (Docker Installation Guide for more details)
Host dependencies
Install helper tools on the host when you encounter Exec format error or similar issues:
sudo apt-get update
sudo apt-get install qemu-user-static repo
Download Latest BSP version
mkdir $HOME/<workspace>
cd $HOME/<workspace>
repo init -u https://dev.azure.com/AIM-Linux/risc_qcs_ubuntu/_git/manifest -b main -m <manifest_file_name>
repo sync -c -j$(nproc)
Example:
repo init -u https://dev.azure.com/AIM-Linux/risc_qcs_ubuntu/_git/manifest -b main -m afea503a1_ubuntu24.04-x15_v0.0.0_kernel-6.8.12_iq9075.xml
Pull docker images
sudo docker pull advrisc/u24.04-qcsubv1:20260727
Run docker example
(Option 1) Use default user in container:
sudo docker run -it --privileged -e HOST_UID=$(id -u) -e HOST_GID=$(id -g) -v=<workspace>:/home/adv/BSP -v=/dev:/dev --name=build_qcs_ubuntu advrisc/u24.04-qcsubv1:20260727
The container creates
advwithHOST_UID/HOST_GID(default 1000:1000) at startup. Pass your own uid/gid, oradvcannot write to<workspace>when your uid is not 1000.
(Option 2) Dynamically create a host user in container (Recommend):
sudo docker run -it \
--env UNAME=$USER \
--env HOST_UID=$(id -u) \
--env HOST_GID=$(id -g) \
--privileged \
--volume=$HOME/<workspace>:/home/$USER/<workspace> \
--volume=/dev:/dev \
--name=build_qcs_ubuntu \
advrisc/u24.04-qcsubv1:20260727
Build Instructions
1. Select machine
Select the target machine before building (required first step). Default build mode is RELEASE:
make <machine>
To build in DEBUG mode (also builds the kernel debug symbols .ddeb):
make <machine> BUILD_MODE=DEBUG
To build with or without the RT kernel, or change the default boot kernel:
make <machine> RT=1 BOOT_FLAVOUR=qcom-rt
Example:
make afea503a1
make afea503a1 BUILD_MODE=DEBUG
make afea503a1 RT=0
| Option | Values | Default | Description |
|---|---|---|---|
BUILD_MODE | RELEASE, DEBUG | RELEASE | DEBUG also builds .ddeb files. |
RT | 0, 1 | rt: in configs | 1 adds the qcom-rt kernel. |
BOOT_FLAVOUR | qcom, qcom-rt | boot_flavour: in configs | Kernel booted by default. |
make <machine>applies the kernel patches tonoble/and saves the options inimages/config.mk. To change an option, runmake <machine>again.
Do not commit directly in
noble/. It is reset to the base commit onmake <machine>. See Kernel patches.
2. Build
Build all components:
make all
Generate a flashable image:
make install
Output images:
<workspace>/images/<machine>/qcom-ubuntu-imageKernel
.deb/.ddebandvmlinux(not flashed):<workspace>/images/<machine>/qcom-ubuntu-artifact
(Optional) [Host machine] Build individual components:
make kernel
make dtb
make modules M=<path_to_subdir_or_ext_module>
make rootfs
make install
After
make <machine>ormake revert, runmake kernel(ormake all) first. The next build cleans the kernel build directory, andmake modulesneeds a complete kernel build.
make rootfsmodifiesimages/<rootfs>.imgin place. Delete the.imgto rebuild from scratch.
For make modules, use a path relative to noble/ or an absolute path inside the workspace:
make modules M=drivers/net/ethernet/stmicro
make modules M=$HOME/<workspace>/<ext_module>
For
make modules,.kofiles are automatically collected intoimages/modules/. WithRT=1, they go toimages/modules/qcom/andimages/modules/qcom-rt/. AddKFLAVOUR=qcomorKFLAVOUR=qcom-rtto build for one kernel only.
(Optional) [Target machine] Replace existing modules:
# Get module path
modinfo -n <module_name>
# Replace module (the existing file may be <module_name>.ko.zst)
sudo rm -f <existing_module_path>
sudo cp <module_name>.ko $(dirname <existing_module_path>)/
# Update module dependencies
sudo depmod -a
# Update initramfs
sudo update-initramfs -u -k $(uname -r)
# Reboot
sudo reboot
3. Clean
Remove kernel build artifacts and the machine selection:
make clean
4. Other Commands
Show help and supported machines
make
Show current configuration:
make printenv
Edit kernel config:
make menuconfig
Mount/unmount Ubuntu root filesystem (requires .img file in images/):
make mount
make unmount
Reset noble/ to the base commit:
make revert
Switch kernel on the target
With RT=1, both kernels are in GRUB under Advanced options for Ubuntu.
Boot the other kernel once:
# List GRUB entries
sudo grep -E "menuentry '" /boot/grub/grub.cfg | cut -d"'" -f2
# Boot the RT kernel on next reboot
sudo grub-reboot "Advanced options for Ubuntu>Ubuntu, with Linux <version>-qcom-rt"
sudo reboot
Change the default kernel:
- Edit
GRUB_FLAVOUR_ORDERin/etc/default/grub.d/99-adv-kernel-flavour.cfg. The first one is the default. - Run
sudo update-gruband reboot.
Configuration reference
globals: in configs/defaults.yaml:
| Key | Description |
|---|---|
base_commit | Full 40-character kernel SHA the patches apply on (no tags). |
grub_cfg | generate: run update-grub (needed for RT=1). image: keep the image's. |
cpu_usage | Share of CPUs to use (0–1). |
rootfs_image | Ubuntu image in download/. |
Machine keys in configs/<machine>.yaml:
| Key | Description |
|---|---|
rt | true to build the RT kernel. |
boot_flavour | Default boot kernel: qcom or qcom-rt. |
platform | qcs9100 or qcm6490. |
patches, driver_patches, machine_patches | See Patch lists. |
nhlos_image, boot_binaries | Firmware for make install. |
Directory Structure
manifest/: Repo manifest files for project synchronization.boot-firmware/: Storage partition tables and NHLOS images for each project.configs/: YAML configuration files for machines, build parameters and kernel patch lists.download/: Reference board boot firmware, Ubuntu root filesystem, and rootfs partition table.noble/: Ubuntu kernel source code (base commit + patches).patches/: Kernel patches applied tonoble/.scripts/: Build scripts and Makefiles.tools/: Per-machine rootfs content such as pre-install Debian packages, files and services.tools-core/: Rootfs tools and services shared by all machines.logs/: Timestamped build logs.images/: Build output directory.
Customization
| What | Where | See |
|---|---|---|
| Kernel source changes | patches/ + patch lists in configs/ | Kernel patches |
| Kernel config | noble/debian.qcom/config/annotations → patch | Kernel config |
| Device tree, drivers | noble/ → patch | Device tree and drivers |
| Packages, files, services | tools/<machine>.mk | Rootfs |
| Kernel command line | KERNEL_CMDLINE in tools/<machine>.mk | Rootfs |
| New machine | configs/, patches/, tools/, boot-firmware/ | Add a new machine |
1. Kernel patches
Patch directories
patches/
├── common/ # all platforms
├── qcs9100/
│ ├── common/ # QCS9075 / QCS9100 machines
│ └── afea503a1/ # one machine
└── qcm6490/
└── common/ # QCS6490 machines
A patch is looked up in common/ → <platform>/common/ → <platform>/<machine>/.
Do not use the same file name in two of these directories.
Patch lists
Patches are applied in this order, each list in YAML order:
| Key | File | Content |
|---|---|---|
patches: | defaults.yaml, patches.yaml | Common and platform patches |
driver_patches: | <machine>.yaml | Drivers for this machine |
machine_patches: | <machine>.yaml | DTS and board files |
To drop an inherited patch, set it to false:
afea503a1:
<<: *qcs9100_default
patches:
<<: *qcs9100_driver_patches
0002-Driver-camera-Fix-per-port-stream-group-release.patch: false
Add or modify a patch
Apply the patches and commit your change in noble/ (or amend / rebase an existing patch commit):
make <machine>
cd noble
git commit -s
Export it into the right patches/ directory, and add a new patch to the list in configs/:
git format-patch -1 <commit> -o ../patches/qcs9100/<machine>/
Check that all patches apply from the base commit, then commit the patches and configs repos:
cd ..
make revert
make <machine>
Each commit subject must be unique. Changed a patch but not its subject? Run
make revertbeforemake <machine>. Ifgit amfails, fix the patch and runmake <machine> FORCE=1.
2. Kernel config
Edit debian.qcom/config/annotations in noble/ (use 'arm64-qcom-rt' as the key for an RT-only value):
CONFIG_USB_SERIAL_CH341 policy<{'arm64': 'n'}>
CONFIG_USB_SERIAL_CH341 note<'Not used on this board'>
Or edit it with make menuconfig, which writes the changes back to annotations.
Build and check:
make kernel
grep CH341 noble/debian/build/build-qcom/.config
The build stops with
config-check failuresif a value cannot be set, e.g.yfor an option whose dependency ism.
Commit and export it as a patch, see Add or modify a patch.
3. Device tree and drivers
Edit the source in noble/, e.g. arch/arm64/boot/dts/qcom/<board>.dts, then build:
make dtb
make modules M=drivers/<subdir>
Commit and export it as a patch, see Add or modify a patch.
4. Rootfs
Edit tools/<machine>.mk, then rebuild the rootfs:
rm images/*.img
make rootfs
make install
| Variable | Description |
|---|---|
*_PKGS | Ubuntu packages to install. |
EXTRACT_FILES | Files to copy, as <name>:<target dir>. |
SERVICES_TARGETS | System settings from tools-core/services/Makefile. |
KERNEL_CMDLINE | Extra kernel command line options. |
EXTENSION_SIZE | Space added to the rootfs partition. |
Packages, add the package name to one of the *_PKGS lists:
GENERAL_PKGS = \
net-tools \
tree \
Packages are downloaded once into
tools/local_debs/debs/and installed from there. For your own.deb, copy it there, add its name to a*_PKGSlist, and deletetools/local_debs/Packages*to regenerate the package index.
Files, add <name>:<target dir> to EXTRACT_FILES:
EXTRACT_FILES = \
my-app:/opt/my-app \
An archive (
.tar.gz,.tgz,.tzst, ...) intools/unzip/files/is extracted. Any other name is a directory, copied fromtools/unzip/dirs/<name>/ortools-core/unzip/dirs/<name>/.
Services, add target names from tools-core/services/Makefile to SERVICES_TARGETS:
| Target | Description |
|---|---|
disable-wait-online | Disable NetworkManager-wait-online. |
disable-auto-update | Hold the kernel packages. |
enable-gdm3-auto-login | Log in to the desktop automatically. |
disable-display-sleep | Turn off screen blanking and lock. |
enable-rc-local | Enable /etc/rc.local. |
set-kernel-cmdline | Add KERNEL_CMDLINE to GRUB. |
Settings for debug images only:
ifeq ($(BUILD_MODE),DEBUG)
SERVICES_TARGETS += disable-display-sleep
endif
Kernel command line:
KERNEL_CMDLINE = pci=hpmemsize=32M <your options>
It needs
set-kernel-cmdlineinSERVICES_TARGETSandgrub_cfg: generate. It is written to/etc/default/grub.d/97-adv-kernel-cmdline.cfgon the target.
5. Add a new machine
configs/<machine>.yaml: based on the platform default, and added toappend:indefaults.yaml.patches/<platform>/<machine>/: the board.dtsandqcom/Makefile.advantech.tools/<machine>.mk: packages, files and services for the rootfs.boot-firmware/: boot binaries andpartition.zip.
Makefile.advantech registers the board dtb, e.g.:
dtb-$(CONFIG_ARCH_QCOM) += <board>-ovl.dtb
<board>-ovl-dtbs := <board>.dtb <overlay>.dtbo ...
Support List for Latest Manifest
| Platform | Device | Manifest XML |
|---|---|---|
| IQ9075 | AFE-A503 | afea503a1_ubuntu24.04-x15_v0.0.0_kernel-6.8.12_iq9075.xml |
Download and build specific BSP version
Please use BSP Launcher
Flash local image
Using Qualcomm Device Loader (QDL) tool to flash software images to the device.
Windws x86 QDL User and Installation Guide
Overview
Qualcomm Device Loader (QDL ) is a software tool that communicates with Qualcomm USB devices to upload a flash loader and flash software images.
Installation Guide
-
Download Qualcomm Device Loader from below link https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader
-
According your host mach to select OS type and which version you want

-
Unzip download file in any path
-
Serach Edit the system environment variables (環境變數) to open Advanced system settings Also you can open Settings app → System → About → Advanced system settings → Advanced

-
Select Environment Variables (環境變數)

-
Select Path then edit (編輯)

-
Select New (新增) and type the Qualcomm Device Loader path then select OK (確定)

-
Search cmd to open Windows Terminal

- Type qdl and you can see the QDL usage now!!

You can see the QDL_User_Guide.pdf for more details
winUSB Installation Guide
- Let board enter EDL mode
Please check Device Guides for more details
-
Connect the EDL USB port to PC
-
Search device manager (裝置管理員)

-
Uninstall other drivers for the device

-
Open install_driver.bat in QDL path to install winUSB driver

-
Press any key to close window

Linux x86 QDL User and Installation Guide
Overview
Qualcomm Device Loader (QDL ) is a software tool that communicates with Qualcomm USB devices to upload a flash loader and flash software images.
Installation Guide
-
Add Qualcomm USB udev rules (one-time prerequisite)
Add below line in
/etc/udev/rules.d/51-qcom-usb.rulesSUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0666", GROUP="plugdev" -
Restart
udevservicesudo systemctl restart udev -
Download Qualcomm Device Loader from below link https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader
-
According your host mach to select OS type and which version you want

-
Unzip download file in any pah
unzip QDL_2.7.1_Linux_x64.zip
-
Change the qdl tools permission
sudo chmod 755 QDL_2.7.1_Linux_x64/qdl* -
Install dependency packages
sudo apt-get install libxml2 libzip-dev -
Type qdl and you can see the QDL usage now!!

You can see the QDL_User_Guide.pdf for more details
-
Move qdl tools to global path
sudo mv QDL_2.7.1_Linux_x64/qdl* /usr/local/bin/
Let device in EDL mode and connect the EDL USB Port to HOST.
Please check Device Guides for more details
Open terminal and enter the image folder
cd <workspace>/images/<machine>/qcom-ubuntu-image
Choosing the platform to flashing image.
IQ9075
IQ9075 Platform Flashing Guide
Flash provision (Once only)
- Erase UFS
qdl prog_firehose_ddr.elf provision_1_2.xml

Flash Safety Island
- Enter sail_nor folder
cd sail_nor
- Flash sail_nor
qdl --storage spinor prog_firehose_ddr.elf rawprogram0.xml patch0.xml

- Back to the root path
cd ..
Flash root filesystem
qdl prog_firehose_ddr.elf rawprogram*.xml patch*.xml

Switch device to Normal Mode and power on device
Device Guides
IQ9075
- AFE-A503
| SW3 | 1 | 2 |
|---|---|---|
| USB EDL Mode | ON | ON |
| Normal Mode | OFF | OFF |
| SW4 | 1 |
|---|---|
| ON | AT |
| OFF | ATX |
