📚 课程目录第2章开发环境搭建

2. 开发环境搭建：高通Hexagon SDK安装、QAIC编译器配置、目标板连接与调试环境验证

说实话，环境搭建这一步，看着简单，其实坑不少。我见过太多人卡在“装好了但跑不起来”的阶段，一查全是路径不对、版本冲突、驱动没装全。咱们这一章，就把这些事一次性理清楚。

2.1 Hexagon SDK 安装——别急着点下一步

高通Hexagon SDK，说白了就是一套给Hexagon DSP写代码的工具链。你可以在高通开发者官网下载，但要注意：必须注册并签署NDA。我当年第一次下载时，以为随便注册就行，结果卡在审批环节整整两天。

版本选择建议：目前主流是SDK 4.x 和 5.x。如果你用QCS610/615平台，建议SDK 4.5.0.3；如果是SM8250（骁龙865）以上，用SDK 5.x。别追新，稳定第一。

安装步骤其实不复杂，但有几个关键点：

安装路径不要有中文和空格。我习惯放在 C:\Qualcomm\Hexagon_SDK\5.0.0，干净利落。
安装时勾选“Add to PATH”。虽然SDK自带环境脚本，但手动加PATH能省很多事。
安装完成后，务必重启。别问我为什么，驱动加载需要。

装完后，验证一下环境变量：

echo %HEXAGON_SDK_ROOT%
# 应该输出：C:\Qualcomm\Hexagon_SDK\5.0.0

echo %HEXAGON_TOOLS_ROOT%
# 应该输出：C:\Qualcomm\Hexagon_SDK\5.0.0\tools

如果输出为空，别慌。去 SDK安装目录\setup_env.cmd 跑一遍，它会帮你设好临时环境。但我建议你直接写进系统环境变量，一劳永逸。

2.2 QAIC 编译器配置——这玩意儿有点脾气

QAIC（Qualcomm AI Compiler）是我们把模型部署到DSP上的关键工具。它负责把ONNX/TFLite模型编译成Hexagon能跑的二进制。嗯，这里要注意：QAIC不是SDK自带的，需要单独下载。

下载地址同样在高通开发者网站，搜索“Qualcomm AI Engine Direct”。安装后，你会得到这样一个目录结构：

C:\Qualcomm\QAIC\
├── 2.10.0.0\
│   ├── bin\          # 编译器本体
│   ├── lib\          # 运行时库
│   ├── include\      # 头文件
│   └── examples\     # 示例模型
└── latest -> 2.10.0.0

配置QAIC环境，核心就三步：

设置QAIC_HOME：指向你的QAIC安装目录。
把bin目录加入PATH：这样你就能在任意目录调用 qaic-exec 了。
验证编译器版本：

qaic-exec --version
# 输出示例：QAIC 2.10.0.0 (Build 12345)

我的习惯：我会写一个 setup_qaic.bat 脚本，把QAIC_HOME、PATH、还有后面要用的ADB路径一次性配好。每次开新终端，先跑这个脚本，省得反复配。

我曾经遇到过一个坑：QAIC 2.8 编译出来的模型，在SDK 4.5上跑会报“Unsupported op”。后来发现是版本不匹配。所以QAIC版本必须和SDK版本对齐。具体对照表如下：

Hexagon SDK 版本	推荐 QAIC 版本	备注
4.5.0.3	2.8.0.0	稳定组合，推荐
5.0.0	2.10.0.0	支持更多算子
5.1.0	2.12.0.0	最新，但文档较少

2.3 目标板连接——ADB是你的生命线

目标板，就是你的开发板。我常用的是 高通RB5平台（基于SM8250）。连接方式很简单：USB Type-C 连电脑，板子上电。

但这里有个关键：驱动。Windows下，RB5会识别为一个“Android设备”，需要安装高通USB驱动。如果你发现设备管理器里有个黄色感叹号，那就是驱动没装。

驱动安装包在SDK目录下：tools\adb\driver\。右键点击 android_winusb.inf，选择“安装”。装完后，拔插USB，应该能看到：

adb devices
# 输出示例：
# List of devices attached
# 12345678    device

如果显示 unauthorized，别急。看看板子屏幕，有个“允许USB调试”的弹窗，点确定就行。我第一次用RB5时，盯着屏幕看了五分钟才发现这个弹窗……

网络连接替代方案：如果USB线不够长，可以用ADB over TCP/IP。先通过USB连接，然后执行：

adb tcpip 5555
adb connect 192.168.1.100:5555

但注意：网络环境不稳定时，调试会频繁断连。我建议能用USB就别用网络。

2.4 调试环境验证——跑通第一个Hello World

环境搭好了，得验证一下能不能用。咱们跑一个最简单的例子：在DSP上打印“Hello from Hexagon”。

SDK里自带了一个示例：examples\audio\capi_v2_basic。编译和部署步骤如下：

编译DSP端代码：

cd %HEXAGON_SDK_ROOT%\examples\audio\capi_v2_basic
make tree V=hexagon_ReleaseG
# 编译产物：build\hexagon_ReleaseG\libcapi_v2_basic.so

推送到目标板：

adb push build\hexagon_ReleaseG\libcapi_v2_basic.so /vendor/lib/rfsa/adsp/
adb shell sync

运行测试程序：

adb shell
cd /data
./capi_v2_basic_test
# 如果看到 "Hello from Hexagon" 输出，说明环境通了

  验证清单：
  ✅ SDK环境变量正确
✅ QAIC编译器可调用
✅ ADB能识别目标板
✅ DSP端so文件能加载
✅ 测试程序输出正常

如果卡在最后一步，最常见的原因是 SELinux权限。你可以临时关闭它来排查：

adb shell setenforce 0

但注意，这只是调试用。正式部署时，你得写对应的SELinux策略文件。

2.5 整体环境结构图

下面这张图，帮你理清整个开发环境的关系。我每次带新人，都会先让他们看这张图——比看文档快多了。

这张图里，主机侧负责开发和编译，目标板侧负责运行和调试。中间的ADB就是桥梁。我每次调试降噪算法，都是在这个框架里循环：改代码 → 编译 → 推送 → 测试 → 看结果 → 再改。熟练之后，一个循环也就一两分钟。

2.6 避坑指南——我踩过的那些坑

最后，分享几个我实际项目中遇到的坑，你遇到了可以直接抄答案：

路径问题：我曾经把SDK装在了 C:\Program Files 下，结果编译时一堆空格报错。后来全部移到 C:\Qualcomm\，再没出过问题。
ADB版本冲突：电脑上装了多个ADB（比如Android Studio自带一个，SDK自带一个），版本不一致会导致连接不稳定。我习惯只用SDK自带的ADB，把其他的从PATH里删掉。
目标板断电后重连：RB5断电后，ADB设备列表会消失。这时候别慌，重新 adb kill-server && adb start-server && adb devices 就行。
DSP内存不足：降噪模型如果太大，推送时会报“No memory”。这时候需要减小模型尺寸，或者用 hexagon-ld 查看DSP内存使用情况。