DSP 开发环境搭建

开发 Ameba DSP 应用需要同时搭建两套开发环境：

MCU 开发环境：用于编译 MCU 固件（FreeRTOS），MCU 负责加载和启动 DSP
DSP 开发环境：用于编译和调试 DSP 算法固件

备注

关于两个 SDK 的架构关系和协作机制，请参考： DSP SDK 系统架构概述

MCU 开发环境搭建

即使只开发 DSP 应用，也需要搭建 MCU 开发环境。MCU 固件负责将 DSP 固件加载到内存、初始化硬件资源，并最终生成可烧录的完整固件。请根据您的开发习惯选择以下方式之一：

CLI 开发环境（推荐）：搭建 CLI 开发环境
VS Code 开发环境： VS Code 插件使用指南

DSP 开发环境搭建

DSP 开发环境用于编译和调试 DSP 算法固件，基于 Cadence Xtensa Xplorer IDE。

材料准备

Xtensa Xplorer IDE 安装程序

Xplorer 是 Cadence 提供的 DSP 专用集成开发环境，包含编译器、调试器等工具。

根据您使用的操作系统，下载对应的软件包：

备注

Patch 文件用于解决极少数情况下的编译器崩溃问题。可以通过 Xplorer GUI 更新获取，或联系 Realtek 获取。

HiFi5 DSP 配置包

编译配置 (Build Configuration) 是描述 Tensilica 处理器实现所需全部参数和必要编译组件的配置文件。配置文件位于 DSP SDK 的 configurations 目录下：

HIFI5_PROD_1123_asic_UPG_win32_redist.tgz (Call0 ABI)
HIFI5_PROD_1123_asic_wUPG_win32_redist.tgz (Window ABI)

HIFI5_PROD_1123_asic_UPG_linux_redist.tgz (Call0 ABI)
HIFI5_PROD_1123_asic_wUPG_linux_redist.tgz (Window ABI)

备注

两种 ABI 的函数调用约定不同，建议在安装配置包前先了解两者的区别。详细的信息请参考： ABI 选择指南

Xtensa Xplorer 许可证

Xplorer IDE 需要有效的许可证才能正常使用。联系 benz_yu@realsil.com.cn 可申请一份临时许可证。申请许可证时，邮件中必须包含以下信息：

MAC 地址：用于绑定许可证到特定机器
工作单位：用于确认申请资格
学校/学院（仅学生）：需要提供学生身份证明

../_images/apply_for_license_email_cn.png

备注

一人只能申请一份许可证
临时许可证的有效期为 3 个月
请妥善保管许可证文件，避免泄露

安装方法

请根据您的操作系统选择对应的安装指南：

步骤 1：安装 Xtensa Xplorer IDE

双击安装程序并按照提示完成安装。安装注意事项：

记录安装路径，后续步骤需要使用。本文档在 Windows 环境下使用的默认安装路径为 C:\usr

安装完成后首次启动 GUI 时，通常会提示软件更新。请务必执行更新操作，因为新补丁修复了可能导致编译器崩溃的问题。

步骤 2：安装 HiFi5 DSP 配置包

配置包 (Build Configuration) 描述了 Tensilica 处理器实现所需的全部参数和编译组件。在开始 DSP 开发前，必须安装相应的编译配置。

2.1 启动 Xplorer 并设置工作区

2.1.1 双击桌面快捷方式 Xplorer 9.0.18 启动 Xplorer

2.1.2 在启动界面点击 Browse，将工作区 (Workspace) 设置为 <dsp_sdk>\project

2.1.3 点击 Launch 进入 Xplorer 主界面

2.2 打开 System Overview 面板

默认情况下，System Overview 面板位于界面左下方，用于管理编译配置。若该面板未显示，可通过以下方式打开： Window > Show View > System Overview

2.3 安装编译配置

2.3.1 在 System Overview 面板中，右键点击 Configuration，选择 New Configuration

2.3.2 在弹出窗口中选择第四项，点击 Next

2.3.3 点击 Browse 定位配置文件（位于 <dsp_sdk>\configurations 目录）

2.3.4 点击 Add Build，然后点击 Finish

配置文件说明：

HIFI5_PROD_1123_asic_UPG_win32_redist.tgz → Call0 ABI 配置

HIFI5_PROD_1123_asic_wUPG_win32_redist.tgz → Window ABI 配置

下图以安装 Call0 ABI 配置为例。若 System Overview 面板中出现下图红框标注的条目，说明配置已成功安装：

2.3.5 重复上述步骤安装另一个 ABI 配置（建议两个都安装）

2.4 配置环境变量

将 Xtensa 工具的 bin 目录添加到系统 PATH 环境变量中，否则部分辅助脚本可能无法定位可执行文件。 Windows 系统下的默认路径为： C:\usr\xtensa\XtDevTools\install\tools\RI-2021.8-win32\XtensaTools\bin

步骤 3：安装许可证

Xplorer IDE 需要有效许可证才能正常工作。许可证有两种类型：

Floating License：从 Cadence 购买，需配置许可证服务器地址和端口

Node-locked License：从 Realtek 申请，绑定到特定机器

安装许可证的步骤：

3.1 在 Xplorer 中点击菜单 Help > Xplorer License Keys

3.2 点击 Install Software Keys

3.3 根据许可证类型选择：

Floating License：在对话框中填写服务器的端口和 IP 地址

Node-locked License：点击右侧浏览按钮，选择 xxx.lic 授权文件

点击 Finish 完成安装

备注

关于如何申请 Node-locked License，请参考 Xtensa Xplorer 许可证章节。

在 Linux 系统上安装 DSP 开发环境时，推荐使用 sudo 命令而非直接使用 root 账户。

步骤 1：安装系统依赖包

1.1 安装 Xplorer 基础依赖
sudo apt-get install libxi6 libxtst6 libxrender1
1.2 安装 X11 转发支持（可选）
如果在 Linux 服务器（如 Ubuntu Server 20.04 LTS）上安装 Xplorer，但需要通过本地 PC 显示图形界面（X11 转发），建议安装 GTK 支持包。虽然 Xplorer 支持纯命令行编译，但使用 GUI 修改工程配置更为直观方便。
sudo apt-get install libgtk-3-dev

步骤 2：安装 Xtensa Xplorer IDE

2.1 运行安装程序
chmod +x Xplorer-9.0.18-linux-x64-installer.bin
sudo ./Xplorer-9.0.18-linux-x64-installer.bin
默认安装路径为 /opt/xtensa，安装过程中其他组件可选择全部安装（选择 yes）。
2.2 安装工具链补丁：安装完成后，首次启动 Xplorer 时通常会提示软件更新。请务必执行更新操作，因为新补丁修复了可能导致编译器崩溃的问题。
如果无法通过图形界面更新，可手动安装补丁：
将补丁包拷贝至 xtensa 工具路径：
sudo cp XtensaTools_RI_2021_8_patch734507_linux.tgz /opt/xtensa/XtDevTools/install/tools/
解压补丁并覆盖原有文件：
cd /opt/xtensa/XtDevTools/install/tools/
sudo tar -zxvf XtensaTools_RI_2021_8_patch734507_linux.tgz
Realtek 提供的补丁包不一定是最新版本。如需获取最新补丁，建议咨询 Cadence 或通过 XPG 下载。

步骤 3：安装 HiFi5 DSP 配置包

3.1 解压配置文件

cd /opt/xtensa/XtDevTools/install/builds/
sudo tar -zxvf HIFI5_PROD_1123_asic_wUPG_linux_redist.tgz
sudo tar -zxvf HIFI5_PROD_1123_asic_UPG_linux_redist.tgz

解压后的目录结构示例：

../_images/directory_structure_after_decompression.jpeg

3.2 安装 Window ABI 配置

cd /opt/xtensa/XtDevTools/install/builds/RI-2021.8-linux/HIFI5_PROD_1123_asic_wUPG
sudo ./install

安装过程中需要输入 Xtensa 工具路径：

Xtensa Tools path: /opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools
What registry would you like to use? [keep default, 按回车]
Do you want to make "HIFI5_PROD_1123_asic_wUPG" the default Xtensa core? [y, 按回车]

3.3 安装 Call0 ABI 配置：使用相同流程安装另一个配置包：

cd /opt/xtensa/XtDevTools/install/builds/RI-2021.8-linux/HIFI5_PROD_1123_asic_UPG
sudo ./install

3.4 注册配置文件：将配置参数文件复制到注册表目录：

cd /opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools/config
sudo cp HIFI5_PROD_1123_asic_UPG-params /opt/xtensa/XtDevTools/XtensaRegistry/RI-2021.8-linux/
sudo cp HIFI5_PROD_1123_asic_wUPG-params /opt/xtensa/XtDevTools/XtensaRegistry/RI-2021.8-linux/

3.5 配置环境变量：将 Xtensa 工具的 bin 目录添加到系统 PATH 中：

echo 'export PATH=$PATH:/opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools/bin' >> ~/.bashrc
source ~/.bashrc

步骤 4：安装许可证

4.1 配置许可证环境变量
设置 LM_LICENSE_FILE 或 XTENSAD_LICENSE_FILE 环境变量，指向许可证文件或许可证服务器。对于 Node-locked License：指向许可证文件的完整路径：
export LM_LICENSE_FILE=/path/to/your/license.lic
对于 Floating License：格式为 <port>@<address>：
export LM_LICENSE_FILE=port@server_address
4.2 配置环境变量：将上述环境变量添加到 ~/.bashrc 或 /etc/profile 中：
# 添加到 ~/.bashrc
echo 'export LM_LICENSE_FILE=/path/to/your/license.lic' >> ~/.bashrc

# 使环境变量生效
source ~/.bashrc
备注

关于如何申请 Node-locked License，请参考 Xtensa Xplorer 许可证章节。

安装调试工具

如果需要使用 J-Link 等调试器进行 DSP 在线调试，需要安装 xt-ocd 调试插件。

Xtensa 片上调试器守护程序（Xtensa on Chip Debugger Daemon xt-ocd）是一款基于 GDB 的强大调试工具。该工具默认不随 Xplorer IDE 安装。Xplorer 中包含一个自解压的可执行安装程序。

以下是 xt-ocd 的简要安装方法。更多 xt-ocd 使用指南，请参阅 Xtensa 文档。

Xplorer 的建议安装路径为 C:\usr\xtensa\XtDevTools\downloads\RI-2021.8\tools\xt-ocd-14.08-windows64-installer，

由于安装路径和软件版本存在差异，实际路径和安装程序名称可能有所不同。

Xplorer 的建议安装路径为 /opt/xtensa:

cd /opt/xtensa/XtDevTools/downloads/RI-2021.8/tools/
sudo ./xt-ocd-14.08-linux64-installer

xt-ocd 默认将安装在此路径：

/opt/Tensilica/xocd-14.08

Linux J-Link 驱动默认安装在 /opt/SEGGER/ 路径下，示例中 J-Link 版本为 V6.44。用户需要根据实际的 J-Link 版本和路径修改下面的命令：

ln -s /opt/SEGGER/JLink_V644i/libjlinkarm.so.6 /opt/Tensilica/xocd-14.08/modules/libjlinkarm.so.6

如果系统中找不到 libncursesw.so.5 文件，可以用下面的命令解决：

sudo ln -s /lib/x86_64-linux-gnu/libncursesw.so.6 /lib/x86_64-linux-gnu/libncursesw.so.5

环境验证

完成两套环境搭建后，建议进行以下验证步骤，确保环境配置正确。

1. 验证 MCU 开发环境

cd <SDK>/amebalite_gcc_project
python build.py -h

如果显示帮助信息，说明 MCU 开发环境已正确配置。

2. 验证 DSP 开发环境

启动 Xplorer IDE，导入 <dsp_sdk>/project 作为工作区，尝试编译 project_dsp 工程。

详细的编译步骤请参考： DSP 编译和烧录

常见问题

Xplorer 依赖和环境问题

问题描述：

DSP SDK 需要 Python3 环境支持，但用户可能不希望更改系统默认的 Python 版本。
若系统中安装了其他版本 Xplorer 且其他版本的 bin 目录已加入系统 PATH，当直接使用 xt-clang 和 xt-ar（如通过 Cmake、Makefile 或 python）进行编译链接而非通过 Xplorer 时，链接过程可能出现注册表值错误：当前 Xtensa 配置未正确安装，或使用的 Xtensa 工具与配置安装时指定的路径不一致。
Xplorer 能正常编译 SDK，但自定义编译方式（比如使用第三方 lib 的 Cmake）出现上述路径不一致错误。

原因分析：

DSP SDK 的后处理依赖 Python3，但用户的系统可能已经设置了其他默认 Python 版本，导致运行环境不符。
系统 PATH 中存在多个 Xplorer 版本的 bin 路径，导致使用了不同版本的工具链，引起系统编译时路径错误。
自定义编译方式可能使用不同的 PATH 设置。如果系统 PATH 中添加了其他版本工具链目录，会导致编译工具无法正确识别所需的版本。

解决方法：

Python 问题：参考 DSP 工程编译，修改后处理命令（右键 Xtensa Xplorer > Tasks > Building your Project > Building multiple projects），然后在编译后命令中指定为 Python3。
用户需要仔细管理和调整系统 PATH 变量，只加入所需的 Xtensa 工具版本路径，并清除多余的工具链路径，以防止路径混乱。
检查 PATH 设置，例如在 profile 文件中进行确认，确保没有其他版本的干扰。并在修改后重新打开 Terminal 更新 PATH 。

auto_build.sh 编译脚本问题

问题描述：

当前 dsp_batch.xml 默认导入并编译 project_dsp 项目。用户需要更改编译配置。
默认 Xplorer IDE 路径为 /opt/xtensa/Xplorer-9.0.18/xplorer。用户需要根据实际安装位置修改 IDE 路径。

解决方法：

修改 dsp_batch.xml 文件，或使用 Xplorer batch build 生成目标 xml 文件（参考 Xplorer 帮助文档 Xtensa Xplorer > Tasks > Building your Project > Building multiple projects）。
根据实际环境和版本更新 auto_build.sh 中的 Xplorer IDE 路径，以匹配实际安装位置，确保路径配置正确。

Linux 项目配置

问题描述：修改项目配置（如修改编译选项、增删文件等）需要使用 Xplorer GUI 集成开发环境，但是 Linux Server 没有 GUI。

原因分析：Cadence 的 Xplorer 工程，不建议直接手动修改工程配置源文件，使用 GUI 修改更稳定可靠。

解决方法：在 Linux 服务器上，可通过 X11 协议将 Xplorer GUI 窗口远程显示到本地终端。方法如下：

将 /etc/ssh/sshd_config 文件中 X11Forwarding 标志设为 yes。
执行以下命令：
```
sudo apt-get install dbus-x11
/opt/xtensa/Xplorer-9.0.18/xplorer
```
Xplorer 的 GUI 窗口将弹出到本地计算机。如果客户的 SSH 终端不支持远程显示，可以使用 MobaXterm。若服务器不支持 x11 远程显示，可以使用手动修改工程文件方法添加编译项目。