DSP 编译与烧录

固件组成

Ameba SoC 采用异构多核架构，系统固件由 MCU 和 DSP 固件共同组成。 DSP 和 MCU 共享 Flash 和内存资源，固件编译前必须提前规划好 Flash 分区和 Memory Layout（SRAM、PSRAM 及 IPC 共享内存），这是两者正确协作的基础。

用户可以在不同的阶段选择不同的固件打包和烧录方法：

固件类型	文件名	适用阶段	功能描述
Bootloader	km4_boot_all.bin	通用	系统启动引导，负责加载 MCU 和 DSP 固件。
DSP 独立固件	dsp_all.bin	开发阶段	包含 Header 信息的独立 DSP 固件，可直接烧录到 Flash 的 DSP 分区。
MCU 独立固件	kr4_km4_app.bin	开发阶段	仅包含 MCU 应用固件。DSP 固件独立烧录，两者解耦。
DSP 原始固件	dsp.bin	量产阶段	纯二进制代码，必须复制到 MCU SDK 中，作为子固件合并到 MCU 完整固件中。
MCU DSP 统一固件	kr4_km4_dsp_app.bin	量产阶段	All-in-One 应用固件。MCU 代码中已内嵌 DSP 固件，支持整体 OTA 升级和安全启动。

编译流程

Ameba SDK 支持两种编译方式：分开打包（Separate） 适合开发阶段调试；合并打包（Merged） 适合最终量产发布。

下图展示了从源码编译到固件生成的完整流程：

根据项目阶段，请选择合适的模式：

1. 开发阶段：分开打包模式 (Separate Packaging)

   • 特点：DSP 和 MCU 固件文件分离，分别烧录到不同 Flash 地址。

   • 优势：

     • 调试快：修改 DSP 算法后，只需编译并重新烧录较小的 dsp_all.bin，无需重编 MCU。

     • 解耦：适合 DSP 算法工程师独立开发，不依赖 MCU 代码库。

   • 操作：MCU SDK Menuconfig 中关闭 DSP within APP 选项。

2. 量产阶段：合并打包模式 (Merged Packaging)

   • 特点：DSP 固件和 MCU 固件拼接，生成单一文件。

   • 优势：

     • 支持 OTA：系统升级时，MCU 和 DSP 作为一个整体版本进行原子更新，确保兼容性。

     • 支持安全启动：DSP 固件可以通过 MCU 的 Secure Boot 校验，安全性更高。

   • 操作：

     • 必须将 dsp.bin 复制到 MCU SDK 指定目录。

     • MCU SDK Menuconfig 中 开启 DSP within APP 选项。

下面开始讲述配置细节和操作方法：

DSP 固件编译

首先编译 DSP 固件。DSP SDK 提供两种编译方式，请根据开发环境选择。

方式一：命令行编译（Linux）方式二：Xplorer GUI 编译（Windows/Linux）

方式一：命令行编译（Linux）:

适用场景：Linux 服务器、自动化编译流程，难以修改工程配置。

1. 环境准备

在使用脚本编译工程之前，必须将 Xtensa 工具链路径添加到系统环境变量 PATH 中。

# 示例路径（请根据实际安装位置调整）
export PATH=$PATH:/opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools/bin

2. 编译配置

自动编译脚本通过读取 project/auto_build/dsp_batch.xml 文件来确定编译参数。请打开该文件，根据项目需求选择合适的配置（Configuration）：

• HIFI5_PROD_1123_asic_wUPG (Window ABI)：适用于代码和数据位于同一 1GB 地址空间内的场景。

• HIFI5_PROD_1123_asic_UPG (Call0 ABI)：适用于跨存储器调用函数的场景（例如在 SRAM 和 PSRAM 之间跳转）。

关于 ABI 的深层技术细节，请参考 DSP ABI 选择 。

3. 执行编译

进入自动编译目录并运行脚本：

cd project/auto_build/
chmod +x auto_build.sh
./auto_build.sh

警告

工作区重置警告：该脚本会自动创建一个名为 auto_ws 的临时工作区，并将 project_dsp 复制进去进行编译。 请勿在 auto_ws 目录中修改代码，因为下次运行脚本时该目录会被清空并重新覆盖。所有代码修改请在原 project_dsp 目录中进行。

无显示环境（SSH/CI） ：命令行编译需要 Xplorer 打开 X display。脚本会在检测到当前无 display 时自动以 xvfb-run 方式运行 Xplorer，前提是已安装虚拟帧缓冲 xvfb （参见 Linux 开发环境安装 ）。若既无 display 又未安装 xvfb ，脚本会在失败时给出安装提示。

4. 产物确认

编译成功后，固件存放在以下路径：

• 输出目录：<dsp_sdk>/project/image/

• 关键文件：

  • dsp_all.bin (用于开发阶段烧录)

  • dsp.bin (用于量产阶段合并)

MCU 固件编译与烧录

DSP SDK 编译完成后，再进行 MCU SDK 编译。

步骤 1：配置 MCU SDK

无论何种打包模式，MCU 均需调整内存布局以适配 DSP 运行。 SRAM 速度快于 PSRAM，为了加速 DSP 的运算，默认 SDK 将大部分的 SRAM 都划分给了 DSP。 因此 MCU 的数据段必须迁移至 PSRAM。

1. 参考 配置 SDK（menuconfig） 进入 menuconfig。

2. 进入 CONFIG Link Option 菜单，进行如下配置：

   CONFIG Link Option --->
      IMG2 Data and Heap in SRAM or PSRAM?
      ( ) SRAM
      (X) PSRAM
   

   • PSRAM：必选项。MCU 的堆（Heap）和数据段（Data）将存放在 PSRAM 中。

   • Code 段：建议保持默认的 XIP 模式（MCU 直接从 Flash 运行代码）。

3. 进入 CONFIG DSP Enable 菜单，指定 DSP 固件目录（所有 DSP 打包与校验动作的锚点）：

   CONFIG DSP Enable --->
      [*] Enable DSP
      (<dsp_sdk>/project/image) DSP SDK image output directory
   

   DSP SDK image output directory （ CONFIG_DSP_SDK_IMAGE_DIR ）指向 DSP SDK 的 image 输出目录，即存放 dsp.bin / dsp_all.bin 的目录。 绝对路径原样使用；相对路径相对于 MCU 工程目录（ <mcu_sdk>/component/soc/amebalite/project ）解析。 MCU 打包与地址校验都从此目录读取 DSP 固件， 无需再手动复制 dsp.bin 。

小技巧

若希望一条命令同时重建 DSP 与 MCU，可在 CONFIG DSP Enable 中开启 Build DSP SDK from source during ameba.py build （ CONFIG_DSP_BUILD_FROM_SOURCE ）。 开启后，MCU 编译前会自动调用 DSP SDK 的 auto_build.sh 重建 DSP 固件，确保其与 MCU 布局同步。此功能需已正确设置 CONFIG_DSP_SDK_IMAGE_DIR 且本机 Xplorer 可用。

步骤 2：编译 MCU 固件

开发阶段（分开打包）量产阶段（合并打包）

开发阶段（分开打包）:

目标：生成独立 MCU 固件，与 DSP 固件隔离，便于快速迭代。

1. 禁用集成选项：

   进入 menuconfig，确保取消勾选 DSP within APP image。

   CONFIG DSP Enable --->
      [*] Enable DSP
      [ ] DSP within APP image  <-- 确保取消
   

2. 执行编译： 保存配置并退出，执行编译命令。

   • 生成产物：<mcu_sdk>/build_<SOC_NAME>/kr4_km4_app.bin

   • 特点：此固件仅包含 MCU 代码，不含 DSP 二进制数据。

步骤 3：烧录固件

开发阶段（分开烧录）开发阶段（合并烧录）

开发阶段（分开烧录）:

对应上文的分开打包模式。在此模式下，Flash 中存在独立的 DSP 分区，需要分别烧录两个文件。烧录清单：

固件文件	目标分区 (Flash Layout)	说明
km4_boot_all.bin	IMG_BOOT	Bootloader
kr4_km4_app.bin	IMG_APP	MCU 应用程序
dsp_all.bin	IMG_DSP	DSP 完整固件（带 Header）

警告

此模式不支持 OTA 升级与固件防篡改校验，仅供实验室开发使用。

步骤 4：复位验证

完成烧录后，请按复位键重启开发板，并通过 UART 串口工具查看 Log。

1. 检查启动日志：

   观察是否出现 DSP 初始化的相关打印。

2. 验证成功标志：

   正常情况下，您应该能看到类似以下的输出：

   Hello DSP World
   

   由于 KM4、KR4 和 DSP 三个内核共享同一个物理串口输出，日志可能混叠。 建议在 DSP 代码中为打印信息添加特定的前缀（如 [DSP]），或者进行多行打印，以便于区分和调试。

编译调试文件

除二进制固件外，编译还可以生成用于调试分析的反汇编文件和 Map 文件:

反汇编文件与 Map 文件

反汇编文件将机器码翻译回汇编语言，用于底层代码分析和 Crash 定位；Map 文件详细记录了符号（函数、变量）的运行地址及各段的大小，是分析固件结构和排查地址错误的利器。

编译时，后处理脚本 <dsp_sdk>/project/img_utility/code_analyze.py 会在 post-build 阶段自动生成反汇编（调用 xt-objdump）并拷贝 Map 文件，默认即为开启，无需额外操作。

备注

反汇编生成依赖 xt-objdump，请确保 Xtensa Tools 目录已加入 PATH，否则会生成空的 asm 文件。

反汇编文件与 Map 文件都会被统一拷贝到 同一个固定目录 <dsp_sdk>/project/image/ 下：无论使用命令行（auto_build.sh，编译产物本在 auto_ws/…）还是 Xplorer GUI 编译、无论 ABI 配置是 UPG 还是 wUPG，都归到这里；每次编译覆盖，始终对应最新一次编译。

产物	路径
反汇编文件	<dsp_sdk>/project/image/project_dsp.asm
Map 文件	<dsp_sdk>/project/image/project_dsp.map

如需关闭反汇编生成（例如加快编译），打开 code_analyze.py，将顶部配置项 ENABLE_Disassembler 改为 0 即可（Map 文件的拷贝不受此项控制，始终生成）：

# User Configuration
ENABLE_Disassembler = 1  # 1: Enable (Default), 0: Disable

常见问题

Q：编译失败，提示找不到 xt-* 命令？

A：请检查 Xtensa Tools 目录是否已添加到 PATH 环境变量。

Q：GUI 编译时提示 Python 错误？

A：检查 Python 版本是否为 3.8+，并在 Xplorer 项目属性中确认 Python 命令路径。

Q：命令行编译速度慢？

A：命令行编译每次都是全量编译，如需增量编译，请使用 GUI 方式。

Q：如何切换 Call0 和 Window ABI？

A：在 GUI 编译中，通过 C （Configuration）下拉框切换；在命令行编译中，修改 dsp_batch.xml 配置文件。

Q：没有看到 "Hello DSP World" 输出？

A：可能原因：

• DSP 固件未正确烧录

• menuconfig 未使能 DSP

• DSP 启动失败（可查看 map 文件或反汇编文件进行调试）

• DSP 日志与 MCU 日志混杂，建议在 MCU SDK 中使能 AGG 区分串口输出核