> ## 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.

# 构建配置与镜像打包

搭建并掌控 MCU 镜像的构建、配置和打包流程，使其能在目标平台上正确运行。理解配置选择、工具链对齐和镜像准备如何影响启动成功率、调试可见性和接口验证。这有助于您产出一致、可复现的构建，快速验证可用的基线，并确保镜像在扩展更多功能之前能与平台要求干净地集成。

## 8.1 构建 MCU 固件

### 8.1.1 环境设置

**操作系统版本：** Ubuntu 22.04

这些步骤已在 Ubuntu 22.04 上验证。其他 Ubuntu 版本可能也可行，但未经验证。这些步骤未在 Windows 上验证。

#### 所需主机软件包

```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
```

> 目前不支持在 Windows 上编译。

**Python 版本：** 3.12.10

安装以下 Python 软件包：

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

> **注意：** 有报告称在同一 `bin/` 目录中安装不同二进制版本的 Python 会导致行为不一致。一种解决方法是在临时目录中添加指向所需 Python 版本的符号链接，并更新 `PATH` 环境变量以使用它。

```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 设置

1. 在您偏好的位置创建一个文件夹，用于下载和安装所有 Zephyr 依赖项。

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

2. 为保持构建环境一致，建议使用 Python 虚拟环境。

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

3. 在虚拟环境中安装并初始化 Zephyr：

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

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

4. 验证 Zephyr 版本。

* Zephyr 版本：3.7 LTS
* Zephyr SDK 版本：0.16.x

5. 查看 Zephyr 兼容性矩阵：

[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. 创建 SDK 目录：

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

7. 下载并设置所需的 Zephyr SDK 版本（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 故障排查资源

**安装依赖项**

[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 与 Python 依赖项**

[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)

**安装 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)

**故障排查**

[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 设置

1. 从 QPM3 下载并安装 RISC-V Snapdragon LLVM。

   当前支持的版本：

   * Snapdragon LLVM (RISC-V)：21.1.1

2. 要安装 QPM3 和 LLVM，请在 Windows 主机上从以下地址下载软件包：

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

   然后将软件包复制到 Ubuntu 主机。

3. 如果已安装 QPM3 和 RISC-V 工具链，请跳过此步骤。

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

4. 从以下位置安装 QIKService3：

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

5. 在 QPM3 UI 中，安装 **Snapdragon LLVM RISCV Toolchain OEM** 工具链。

   当前版本：**21.1.1**

### 8.1.3 设备树编译器安装

1. 安装设备树编译器（DTC）。

从以下地址下载源码：

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

示例步骤：

```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 编译子系统

#### 环境变量

```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
```

#### 执行编译

进入以下目录：

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

使用下表中的命令。

| 子系统 | 命令                                                        |
| --- | --------------------------------------------------------- |
| MCU | 构建：`python ./build_variant.py shikra.lpaicp.prod`         |
| MCU | 清理：`python ./build_variant.py shikra.lpaicp.prod --clean` |

## 8.2 配置、镜像生成与启动流程

1. 明确记录日志和控制台的选择，使首次成功路径有清晰的输出。
2. 初期仅启用您需要的总线，例如串口或 I2C。
3. 仅在较简单的路径稳定后再启用 DMA 或 GPI。
4. 生成 ELF 文件、内存映射和打包后的 MCU 镜像。
5. 使用平台认可的烧录流程加载镜像并进行验证。