OP-TEE · Qualcomm Platforms

Quick Start

Initialize the workspace with repo, sync all source trees, and build the toolchains and components. Complete the common setup below, then pick a bootflow to build the images and flash the board.

📱 Best viewed on a desktop. The command blocks are hidden on small screens — open this Quick Start on a larger display to copy the commands.

Common setup · every bootflow

Get the sources and build the stack

These three steps are shared by every bootflow. Do them once, then pick a bootflow below for the flow-specific image build and flashing.

1 Initialize the workspace — Qualcomm SA8775P / QCS9075 EVK

# create the sandbox and pull the manifest
mkdir sandbox.lemans && cd sandbox.lemans
repo init -u https://github.com/ldts/qcom-manifest -m lemans.xml

2 Sync all source trees

repo sync -j4 --no-clone-bundle

3 Build toolchains and all components

cd build
make -j8 toolchains
make -j8 all         # linux-firmware is fetched automatically by buildroot

Local or remote flash

4 Build the two flashable images — no Yocto needed

make bootimage       # tz.mbn + uefi.elf — the signed boot chain
make efi             # efi.bin — kernel UKI + Buildroot rootfs

Flashing · on the build machine

Flash over USB — board plugged into this host, qdl on PATH

The board is in EDL (9008) mode on the same Linux host you built on, with qdl on the PATH. These targets are flash-only — the images were already built in step 4 — so they just push bits to the device over USB.

For the full Linux procedure — installing qdl, putting the board into EDL mode, and provisioning the UFS — follow Qualcomm's official Flash over QLI guide.

First flash — full boot chain + kernel

# fetch the Qualcomm boot-chain blobs the flash targets need
# (xbl, aop, cpucp, cdt, GPT + rawprogram XMLs) — no Yocto build needed
make fetch-blobs

# flash the full boot chain (LUNs 1–5) once, then the kernel (LUN 0)
make flash-loader
make flash-kernel

Kernel-only iteration — afterwards

# reflash just efi.bin — no loader re-flash needed
make flash-kernel

Flashing · from a separate machine

Package for off-server flashing — board not on the build server

If the EVK lives on a different machine — typically a Windows box running Qualcomm's PCATApp or QFIL — the build server can't reach it over USB. Instead, package the images into a single self-contained directory here, copy it across, and flash from there. The edl-* targets assemble the package but flash nothing, so no device needs to be connected while building. File lookup mirrors the flash targets: input/ → Yocto deploy dir → blobs/, so make fetch-blobs is enough to populate a package.

edl-package — full-system package (all 6 LUNs)

# build the images (steps 3–4) and fetch the boot-chain blobs first
make fetch-blobs

# assemble everything PCATApp/QFIL needs into one flat directory:
#   prog_firehose_ddr.elf, all rawprogram*/patch* XMLs, GPT bins,
#   firmware MBNs/ELFs, tz.mbn, uefi.elf, efi.bin, qupv3fw.elf
make edl-package     # output: lemans/output/edl-package/

# the target pre-selects the safe XML variants (originals kept as
# *.xml.backup): rawprogram4 with qupfw_a/b populated (avoids GENI
# SE boot storms) and rawprogram0 with rootfs.img stripped out.

edl-bootloader — bootloaders only (LUN1–4), fast re-flash

# only XBL, CDT, tz.mbn, uefi.elf + supporting FW — no efi.bin/rootfs.
# the path to take when only OP-TEE / U-Boot changed. OP-TEE is built
# with full debug logging (LOG_LEVEL=4) for this package, then the
# quiet production build is restored so lemans/output/ stays clean.
make edl-bootloader  # output: lemans/output/edl-bootloader/

On the Windows machine — PCATApp / QFIL

# copy the whole directory across (scp, USB stick, share, …)
scp -r lemans/output/edl-package user@winbox:C:/edl-package

# put the board in EDL (9008) mode, then in the tool:
#   Programmer:  prog_firehose_ddr.elf
#   XMLs:        rawprogram0.xml … rawprogram5.xml + patch0.xml (full)
#                rawprogram1–4.xml + patch1–4.xml   (bootloader-only)

Recovery · partitions broken by a bad flash

Re-provision the UFS — last resort after a firmware upgrade gone wrong

The board must be in EDL (9008) mode with qdl on the PATH. The target downloads the CodeLinaro provision.zip, loads the DDR firehose programmer (resolved just like the flash targets: input/ → Yocto deploy dir → blobs/), and applies a provision layout over qdl --storage ufs. See Qualcomm's Flash over QLI guide for the full UFS provisioning procedure.

flash-ufs-provision — rewrite the LUN layout

# default layout grows HLOS LUN 0 (provision_1_2.xml) — LUN 0 is
# where this build writes efi.bin + rootfs.img
make flash-ufs-provision

# then rebuild the device from a clean slate
make flash-loader
make flash-kernel

Pick a different layout

# provision_1_1.xml grows User LUN 7 instead; larger NHLOS LUNs
make flash-ufs-provision UFS_PROVISION_XML=provision_1_1.xml

Iterate on a single component

After the first full build, you rarely rebuild everything. Edit one tree (OP-TEE OS, TF-A, U-Boot or Linux), rebuild just that component, repackage, and reflash. Builds are incremental — only the changed source is recompiled — so the edit → flash loop is seconds to a couple of minutes, not the hour a full build takes.

Boot-chain change — OP-TEE OS, TF-A or U-Boot

# rebuild just the component you touched (incremental — seconds–minutes)
make optee-os        # or:  make u-boot  /  make spl
make bootimage       # repackage the signed boot image (tz.mbn + uefi.elf)
make flash-loader    # reflash the boot chain

Kernel change — Linux

# rebuild the kernel (incremental — typically ~1–2 min)
make linux
make efi             # repackage the EFI image / UKI (efi.bin)
make flash-kernel    # reflash the kernel partition only — firmware untouched

Lemans: SPL is signed locally via qtestsign (open-source, no CASS required) — signing runs automatically as part of make bootimage / make spl.

make fetch-blobs pulls the Qualcomm boot binaries and CDT directly from the public Qualcomm / CodeLinaro URLs, so a full Yocto BSP build is not required. The flash targets look for inputs in input/ → Yocto deploy dir → blobs/, so the blobs fetched in step 3 are used automatically.

Local flash only

Build & flash the stock Yocto release

Build and flash the released, unmodified Qualcomm BSP as a known-good reference — nothing from the manifest is substituted. This flow flashes over USB from the build host only; there is no off-server package for it. Not required for a normal build — the Buildroot flow already gives you a bootable image.

Build the Yocto stack

# clones meta-qcom and builds via kas — several hours.
# flash-yocto reads the release straight from the Yocto deploy
# dir, so no manual copy into lemans/output/ is needed.
make yocto

Flash the full release (all 6 LUNs)

# flashes the pristine BSP: bootloader, firmware, efi.bin + rootfs.img.
make flash-yocto

# NOTE: this overwrites whatever flash-loader / flash-kernel installed.
# Re-run those afterward to restore your custom build.

Local flash only

Run your kernel on the on-disk Yocto rootfs

Wrap the locally-built kernel in a UKI that boots root=PARTLABEL=rootfs against the already-flashed Yocto rootfs, instead of the Buildroot initramfs. Only the efi.bin is reflashed — the rootfs is untouched.

Prerequisite: run the Yocto flow first — make efi-kernel-only errors out unless the Yocto efi.bin exists and the Yocto rootfs is flashed on the board.

Build the kernel-only UKI and reflash it

# wraps the freshly-built kernel in an efi.bin that boots the
# on-disk Yocto rootfs (root=PARTLABEL=rootfs).
make efi-kernel-only
make flash-kernel    # reflash efi.bin only — Yocto rootfs untouched

make efi-kernel-only builds the kernel for you — it depends on make linux, which generates .config from make linux-defconfig automatically on the first build and rebuilds incrementally afterwards. Run make linux-defconfig yourself only to clean and refresh the kernel config (it runs mrproper, forcing a full rebuild) — e.g. after bumping the kernel or changing enabled options.

Run make help in build/ for the full target list.