Skip to main content

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.

FeatureDescription
ContainerizedUses Docker (advrisc/u24.04-qcsubv1) to ensure a consistent and reproducible build environment.
YAML-based ConfigurationMachine, build parameters and kernel patch lists managed in configs/.
Kernel PatchesKernel changes kept as patch files in patches/ and applied by git am.
RT KernelOptional PREEMPT_RT kernel (RT=1) with a selectable default boot kernel.
Automatic LoggingBuild output automatically saved to timestamped files in logs/. Use NOLOG=1 to disable.
Debug / Release ModeSelectable via BUILD_MODE=DEBUG|RELEASE.
Fast Module DebuggingCompile 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 adv with HOST_UID/HOST_GID (default 1000:1000) at startup. Pass your own uid/gid, or adv cannot 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
OptionValuesDefaultDescription
BUILD_MODERELEASE, DEBUGRELEASEDEBUG also builds .ddeb files.
RT0, 1rt: in configs1 adds the qcom-rt kernel.
BOOT_FLAVOURqcom, qcom-rtboot_flavour: in configsKernel booted by default.

make <machine> applies the kernel patches to noble/ and saves the options in images/config.mk. To change an option, run make <machine> again.

Do not commit directly in noble/. It is reset to the base commit on make <machine>. See Kernel patches.

2. Build​

Build all components:

make all

Generate a flashable image:

make install

Output images: <workspace>/images/<machine>/qcom-ubuntu-image

Kernel .deb/.ddeb and vmlinux (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> or make revert, run make kernel (or make all) first. The next build cleans the kernel build directory, and make modules needs a complete kernel build.

make rootfs modifies images/<rootfs>.img in place. Delete the .img to 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, .ko files are automatically collected into images/modules/. With RT=1, they go to images/modules/qcom/ and images/modules/qcom-rt/. Add KFLAVOUR=qcom or KFLAVOUR=qcom-rt to 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:

  1. Edit GRUB_FLAVOUR_ORDER in /etc/default/grub.d/99-adv-kernel-flavour.cfg. The first one is the default.
  2. Run sudo update-grub and reboot.

Configuration reference​

globals: in configs/defaults.yaml:

KeyDescription
base_commitFull 40-character kernel SHA the patches apply on (no tags).
grub_cfggenerate: run update-grub (needed for RT=1). image: keep the image's.
cpu_usageShare of CPUs to use (0–1).
rootfs_imageUbuntu image in download/.

Machine keys in configs/<machine>.yaml:

KeyDescription
rttrue to build the RT kernel.
boot_flavourDefault boot kernel: qcom or qcom-rt.
platformqcs9100 or qcm6490.
patches, driver_patches, machine_patchesSee Patch lists.
nhlos_image, boot_binariesFirmware 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 to noble/.
  • 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​

WhatWhereSee
Kernel source changespatches/ + patch lists in configs/Kernel patches
Kernel confignoble/debian.qcom/config/annotations → patchKernel config
Device tree, driversnoble/ → patchDevice tree and drivers
Packages, files, servicestools/<machine>.mkRootfs
Kernel command lineKERNEL_CMDLINE in tools/<machine>.mkRootfs
New machineconfigs/, 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:

KeyFileContent
patches:defaults.yaml, patches.yamlCommon and platform patches
driver_patches:<machine>.yamlDrivers for this machine
machine_patches:<machine>.yamlDTS 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 revert before make <machine>. If git am fails, fix the patch and run make <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 failures if a value cannot be set, e.g. y for an option whose dependency is m.

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
VariableDescription
*_PKGSUbuntu packages to install.
EXTRACT_FILESFiles to copy, as <name>:<target dir>.
SERVICES_TARGETSSystem settings from tools-core/services/Makefile.
KERNEL_CMDLINEExtra kernel command line options.
EXTENSION_SIZESpace 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 *_PKGS list, and delete tools/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, ...) in tools/unzip/files/ is extracted. Any other name is a directory, copied from tools/unzip/dirs/<name>/ or tools-core/unzip/dirs/<name>/.

Services, add target names from tools-core/services/Makefile to SERVICES_TARGETS:

TargetDescription
disable-wait-onlineDisable NetworkManager-wait-online.
disable-auto-updateHold the kernel packages.
enable-gdm3-auto-loginLog in to the desktop automatically.
disable-display-sleepTurn off screen blanking and lock.
enable-rc-localEnable /etc/rc.local.
set-kernel-cmdlineAdd 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-cmdline in SERVICES_TARGETS and grub_cfg: generate. It is written to /etc/default/grub.d/97-adv-kernel-cmdline.cfg on the target.

5. Add a new machine​

  • configs/<machine>.yaml: based on the platform default, and added to append: in defaults.yaml.
  • patches/<platform>/<machine>/: the board .dts and qcom/Makefile.advantech.
  • tools/<machine>.mk: packages, files and services for the rootfs.
  • boot-firmware/: boot binaries and partition.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​

PlatformDeviceManifest XML
IQ9075AFE-A503afea503a1_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

  1. Download Qualcomm Device Loader from below link https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader

  2. According your host mach to select OS type and which version you want qdl_downalod_page.png

  3. Unzip download file in any path

  4. Serach Edit the system environment variables (環境變數) to open Advanced system settings Also you can open Settings app → System → About → Advanced system settings → Advanced qdl_open_system_environment.png

  5. Select Environment Variables (環境變數) qdl_environment_variable.png

  6. Select Path then edit (編輯) qdl_edit_environment_path.png

  7. Select New (新增) and type the Qualcomm Device Loader path then select OK (確定) qdl_add_environment_path.png

  8. Search cmd to open Windows Terminal

qdl_cmd.png

  1. Type qdl and you can see the QDL usage now!! qdl_terminal.png

You can see the QDL_User_Guide.pdf for more details qdl_user_guide.png

winUSB Installation Guide

  1. Let board enter EDL mode

Please check Device Guides for more details

  1. Connect the EDL USB port to PC

  2. Search device manager (裝置管理員) qdl_open_device_manager.png

  3. Uninstall other drivers for the device qdl_remove_usb.png

  4. Open install_driver.bat in QDL path to install winUSB driver qdl_install_usb_driver_bat.png

  5. Press any key to close window qdl_usb_driver_install_success.png

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

  1. Add Qualcomm USB udev rules (one-time prerequisite)

    Add below line in /etc/udev/rules.d/51-qcom-usb.rules

    SUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0666", GROUP="plugdev"
  2. Restart udev service

    sudo systemctl restart udev
  3. Download Qualcomm Device Loader from below link https://softwarecenter.qualcomm.com/catalog/item/Qualcomm_Device_Loader

  4. According your host mach to select OS type and which version you want qdl_linux_download_page.png

  5. Unzip download file in any pah

    unzip QDL_2.7.1_Linux_x64.zip

    qdl_linux_unzip.png

  6. Change the qdl tools permission

    sudo chmod 755 QDL_2.7.1_Linux_x64/qdl*
  7. Install dependency packages

    sudo apt-get install libxml2 libzip-dev
  8. Type qdl and you can see the QDL usage now!! qdl_usage.png

    You can see the QDL_User_Guide.pdf for more details

  9. 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)

  1. Erase UFS
qdl prog_firehose_ddr.elf provision_1_2.xml

iq9075_flash_provision.png

Flash Safety Island

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

iq9075_flash_sail.png

  1. Back to the root path
cd ..

Flash root filesystem

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

iq9075_flash_image.png

Switch device to Normal Mode and power on device

Device Guides​

IQ9075​

SW3           1   2   
USB EDL Mode ON   ON   
Normal  Mode OFF OFF 
SW4 1   
ON   AT 
OFF ATX