> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build configuration and image packaging

Set up and control the process of building, configuring, and packaging MCU images so they run correctly on the target platform. Understand how configuration choices, toolchain alignment, and image preparation affect boot success, debug visibility, and interface validation. This helps you produce consistent, reproducible builds, validate a working baseline quickly, and ensure the image integrates cleanly with platform requirements before expanding to additional features.

## 8.1 Build MCU firmware

### 8.1.1 Environment setup

**OS Version:** Ubuntu 22.04

These steps are verified with Ubuntu 22.04. Other Ubuntu releases may also work but have not been verified. These steps have not been verified on Windows.

#### Required host packages

```bash theme={null}
sudo apt install --no-install-recommends \
git cmake ninja-build gperf ccache dfu-util \
device-tree-compiler wget python3-dev python3-pip \
python3-setuptools python3-tk python3-wheel \
python3-venv xz-utils file make gcc gcc-multilib \
g++-multilib libsdl2-dev libmagic1 libyaml-dev \
flex bison
```

> Compiling on Windows is currently not supported.

**Python version:** 3.12.10

Install the following Python packages:

```bash theme={null}
pip3 install pyelftools pyyaml colorama anytree packaging pyfatfs jsonschema
```

> **Note:** There have been reports of inconsistent behavior when different binary versions of Python are installed in the same `bin/` directory. A workaround is to add a symbolic link of the required Python version into a scratch directory and update the `PATH` environment variable to use it.

```bash theme={null}
mkdir ~/.local/scratch
ln -fs /usr/local/bin/python3.12 ~/.local/scratch/python3
ln -fs /usr/local/bin/python3.12 ~/.local/scratch/python
export PATH=~/.local/scratch:$PATH
```

#### Zephyr OS setup

1. Create a folder at your preferred location for downloading and installing all Zephyr dependencies.

```bash theme={null}
mkdir <local-path>/zephyrproject
```

2. For maintaining a consistent build environment, it is recommended to use a Python virtual environment.

```bash theme={null}
python3 -m venv <local-path>/zephyrproject/.venv
source <local-path>/zephyrproject/.venv/bin/activate
```

3. From the virtual environment, install and initialize Zephyr:

```bash theme={null}
pip install west

west init <local-path>/zephyrproject
west update
west zephyr-export
west packages pip --install
```

4. Verify the Zephyr versions.

* Zephyr version: 3.7 LTS
* Zephyr SDK version: 0.16.x

5. Check the Zephyr compatibility matrix:

[https://github.com/zephyrproject-rtos/sdk-ng/wiki/Zephyr-SDK-Version-Compatibility-Matrix](https://github.com/zephyrproject-rtos/sdk-ng/wiki/Zephyr-SDK-Version-Compatibility-Matrix)

6. Create the SDK directory:

```bash theme={null}
mkdir -p <local-path>/zephyr_sdk
```

7. Download and set up the required Zephyr SDK version (0.16.x).

```bash theme={null}
tar xvf zephyr-sdk-0.16.0_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.0
./setup.sh
```

#### Zephyr troubleshooting resources

**Install dependencies**

[https://docs.zephyrproject.org/latest/develop/getting\_started/index.html#select-and-update-os](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#select-and-update-os)

**Zephyr SDK and Python dependencies**

[https://docs.zephyrproject.org/latest/develop/getting\_started/index.html#get-zephyr-and-install-python-dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)

**Install the Zephyr SDK**

[https://docs.zephyrproject.org/latest/develop/getting\_started/index.html#install-the-zephyr-sdk](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#install-the-zephyr-sdk)

**Troubleshooting**

[https://docs.zephyrproject.org/latest/develop/getting\_started/index.html#troubleshooting-installation](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#troubleshooting-installation)

### 8.1.2 LLVM setup

1. Download and install RISC-V Snapdragon LLVM from QPM3.

   Current supported version:

   * Snapdragon LLVM (RISC-V): 21.1.1

2. To install QPM3 and LLVM, download the package on a Windows host from:

   [https://www.qpm.qualcomm.com](https://www.qpm.qualcomm.com)

   Then copy the package to the Ubuntu host.

3. Skip this step if QPM3 and the RISC-V toolchain are already installed.

```bash theme={null}
sudo dpkg -i QualcommPackageManager3.3.0.119.1.Linux-x86.deb
```

4. Install QIKService3 from:

```text theme={null}
/opt/qcom/QIKService3/bin
```

5. From the QPM3 UI, install the **Snapdragon LLVM RISCV Toolchain OEM** toolchain.

   Current version: **21.1.1**

### 8.1.3 Device tree compiler installation

1. Install the Device Tree Compiler (DTC).

Download source from:

[https://git.kernel.org/pub/scm/utils/dtc/dtc.git](https://git.kernel.org/pub/scm/utils/dtc/dtc.git)

Example steps:

```bash theme={null}
git clone https://git.kernel.org/pub/scm/utils/dtc/dtc.git

cd dtc

git tag -l
# Pick the latest version tag

git reset --hard v1.7.2

make
```

### 8.1.4 Compile subsystem

#### Environment variables

```bash theme={null}
export ZEPHYR_SDK_INSTALL_DIR=<local-path>/zephyr_sdk/zephyr-sdk-0.16.0

export RISCV_TOOLS_ROOT=/opt/qcom/Qualcomm_Snapdragon_RISCV_Toolchain_OEM/21.1.1

export SECTOOLS=<meta_root>/common/sectoolsv2/ext/Linux/sectools

export DTC_PATH=<local-path>/dtc
```

#### Run compilation

Navigate to:

```bash theme={null}
cd <target_root>/<subsystem>/<subsystem>_proc/build/ms
```

Use the commands from the following table.

| Subsystem | Command                                                       |
| --------- | ------------------------------------------------------------- |
| MCU       | Build: `python ./build_variant.py shikra.lpaicp.prod`         |
| MCU       | Clean: `python ./build_variant.py shikra.lpaicp.prod --clean` |

## 8.2 Configuration, image generation, and boot flow

1. Track logging and console choices explicitly so the first-success path has clear output.
2. Enable only the buses you need initially, such as serial or I2C.
3. Turn on DMA or GPI only after the simpler path is stable.
4. Generate the ELF file, memory map, and packaged MCU image.
5. Load the image using the platform-approved programming flow and validate