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）适合最终量产发布。

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

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

开发阶段：分开打包模式 (Separate Packaging)
- 特点：DSP 和 MCU 固件文件分离，分别烧录到不同 Flash 地址。
- 优势：
  - 调试快：修改 DSP 算法后，只需编译并重新烧录较小的 dsp_all.bin，无需重编 MCU。
  - 解耦：适合 DSP 算法工程师独立开发，不依赖 MCU 代码库。
- 操作：MCU SDK Menuconfig 中关闭 DSP within APP 选项。
量产阶段：合并打包模式 (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 服务器、自动化编译流程，难以修改工程配置。

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 目录中进行。

4. 产物确认

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

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

关键文件：

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

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

适用场景：Window 环境，或者修改工程配置。

1. 环境准备

Xtensa 工具链：需将路径加入系统环境变量 PATH。

(Windows 默认: C:\usr\xtensa\XtDevTools\install\tools\RI-2021.8-win32\XtensaTools\bin)

Python 环境：确保安装了 Python (3.8+)，并将其加入环境变量。

小技巧

如果您的系统命令是 python3 而非 python，请在工程属性的 Post-build step 中调整命令为 python3 （如下图红框所示）。

2. 导入工程

打开 Xtensa Xplorer，设置 Workspace 为 <dsp_sdk>\project。

点击菜单 File > Import，选择 General > Existing Projects into Workspace。

勾选 project_dsp (源码工程) 和 RTK_LSP (链接脚本工程)，点击 Finish。

3. 编译配置

在 Xplorer 工具栏中，设置 Build Active 参数：

P (Project): 选择 project_dsp

C (Config): 根据项目配置选择 ABI 配置：

HIFI5_PROD_1123_asic_wUPG (Window ABI)

HIFI5_PROD_1123_asic_UPG (Call0 ABI)

T (Target): 选择 Release 。

4. 执行编译

点击工具栏的 Build Active 图标开始编译。

5. 产物确认

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

输出目录：<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。

参考配置 SDK（menuconfig）进入 menuconfig。
进入 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 运行代码）。

步骤 2：编译 MCU 固件

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

禁用集成选项：

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

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

执行编译：保存配置并退出，执行编译命令。
- 生成产物：<mcu_sdk>/amebalite_gcc_project/kr4_km4_app.bin
- 特点：此固件仅包含 MCU 代码，不含 DSP 二进制数据。

目标：将 DSP 固件作为数据段合并到 MCU 固件中，生成单一固件。

准备 DSP 固件（关键步骤）：将 DSP SDK 编译生成的 纯数据固件 dsp.bin 复制到 MCU SDK 组件目录。
- 源文件：<dsp_sdk>/project/image/dsp.bin
- 目标地：<mcu_sdk>/component/dsp/dsp.bin (假设路径，请根据实际下面实际 Kconfig 中配置的地址做调整)
启用集成选项：进入 menuconfig，勾选集成选项并指定路径。
```
CONFIG DSP Enable --->
   [*] Enable DSP
   [*]   DSP within APP image
   (../component/dsp) DSP_IMAGE_TARGET_DIR
```
路径设置说明： DSP_IMAGE_TARGET_DIR 是相对于 MCU 工程目录（ <mcu_sdk>/amebalite_gcc_project）的相对路径。
- 默认配置通常为 ../component/dsp
- 请务必检查 .config 文件，确认路径解析正确： CONFIG_DSP_IMAGE_TARGET_DIR="../component/dsp"
执行编译：

保存配置并退出，正常执行 MCU SDK 编译命令。
- 生成产物：<mcu_sdk>/project/.../kr4_km4_dsp_app.bin
- 特点：此固件包含了完整的 DSP 二进制数据，支持整体 OTA。

步骤 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 升级与固件防篡改校验，仅供实验室开发使用。

对应上文的合并打包模式。在此模式下，DSP 固件已内嵌于 MCU 固件中，仅需烧录一个文件。烧录清单：

固件文件	目标分区 (Flash Layout)	说明
`km4_boot_all.bin`	IMG_BOOT	Bootloader
`kr4_km4_dsp_app.bin`	IMG_APP	MCU + DSP 合并固件

步骤 4：复位验证

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

检查启动日志：

观察是否出现 DSP 初始化的相关打印。
验证成功标志：

正常情况下，您应该能看到类似以下的输出：
```
Hello DSP World
```
由于 KM4、KR4 和 DSP 三个内核共享同一个物理串口输出，日志可能混叠。建议在 DSP 代码中为打印信息添加特定的前缀（如 [DSP]），或者进行多行打印，以便于区分和调试。

编译调试文件

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

反汇编文件

反汇编文件将机器码翻译回汇编语言，用于底层代码分析和 Crash 定位。 SDK 默认关闭反汇编生成，若需开启请执行以下步骤：

打开后处理脚本：<dsp_sdk>/project/img_utility/code_analyze.py

找到配置项 ENABLE_Disassembler 并将其改为 1：

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

重新执行编译流程。反汇编文件位置：

编译方式	反汇编文件路径
命令行编译	`<dsp_sdk>/auto_ws/project/dsp/bin/HIFI5_PROD_1123_asic_<ABI>/UPG/Release/project_dsp.asm`
Xplorer GUI 编译	`<dsp_sdk>/project/project_dsp/bin/HIFI5_PROD_1123_asic_<ABI>/Release/project_dsp.asm`

Map 文件

Map 文件详细记录了符号（函数、变量）的运行地址及各段的大小，是分析固件结构和排查地址错误的利器。Map 文件位置：

编译方式	Map 文件路径
Linux 命令行编译	`<dsp_sdk>/auto_ws/project/dsp/bin/HIFI5_PROD_1123_asic_<ABI>/Release/project_dsp.map`
Xplorer GUI 编译	`<dsp_sdk>/project/project_dsp/bin/HIFI5_PROD_1123_asic_<ABI>/Release/project_dsp.map`

常见问题

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 区分串口输出核