DSP 调试

准备工作

在进行 DSP 调试之前，请确保完成以下安装：

1. 安装 xt-ocd 工具：参考 安装调试插件。xt-ocd 支持通过 SWD 协议使用 J-Link 调试器进行 DSP 调试。

2. 安装 J-Link 驱动：我们使用的版本是 V6.44，更新的版本应该也可以工作，但尚未经过测试。

将 DSP 连接至 J-Link

Xtensa OCD Daemon 的默认安装路径为: C:\Program Files (x86)\Tensilica\Xtensa OCD Daemon 14.08。

1. 用以下代码替换路径下的 topology.xml 文件：

   • Windows： C:Program Files (x86)TensilicaXtensa OCD Daemon 14.08topology.xml

   • Linux： /opt/Tensilica/xocd-14.08/topology.xml

2. 需要根据 J-Link 序列号修改 usbser 值:

   <configuration>
   <controller id='Controller0' module='jlink' usbser='XXXXXX' type='swd' speed='4000000' locking='1'/>
   <driver id='XtensaDriver0' dap='1' xdm-offset='0x80000000' module='xtensa' step-intr='mask,stepover,setps' />
   <chain controller='Controller0'>
   <tap id='TAP0' irwidth='5' />
   </chain>
   <system module='jtag'>
   <component id='Component0' tap='TAP0' config='trax' />
   </system>
   <device id='Xtensa0' component='Component0' driver='XtensaDriver0' ap-sel='3'/>
   <application id='GDBStub' module='gdbstub' port='20000'>
   <target device='Xtensa0' />
   </application>
   </configuration>
   

   通过 J-Link commander 查找 usbser 值：

   

调试方法

使用 Xplorer 调试 DSP 内核时，建议先擦除整个 Flash ，然后仅下载 KM4/KR4 固件。 调试启动时， DSP 固件将通过 J-Link 直接加载到 PSRAM 中。

GUI 调试CMD 调试

GUI 调试:

1. 点击 Debug Configurations…

   

2. 选择 Xtensa On Chip Debug，然后创建新的调试配置。勾选 Use XOCD Manager 选项，点击 Connect 按钮。刷新 OCD Version 后选择 14.08 版本。

   Topology File 应选择上一节中编辑的 C:Program Files (x86)TensilicaXtensa OCD Daemon 14.08topology.xml。 Connection Type 选择 SWD。

   

3. 选择 core0，将 Download binary 设为 Always。然后点击 Apply 和 Debug。

   

4. 默认情况下，DSP 内核将在 main 函数的第一行停止。如需检查内存值，建议使用 Bounded Memory 并在内存值变化时手动刷新内存表。

   

Crash dump 分析

当 DSP 触发未处理异常（HardFault / 非法访问 / 跳转到坏地址等）时，xt_unhandled_exception() 会打印一份 crash dump，随后关中断并自旋，把内核停在现场，供串口或 JTAG 分析。SDK 提供脚本 <dsp_sdk>/project/img_utility/dsp_dump.py，可一键解析 dump：解码异常原因（exccause）并对 backtrace 做符号化（还原函数名与源码行号）。

一份 crash dump 包含：

• 寄存器块：pc / ps / a0..a15 / sar / exccause / excvaddr / lbeg / lend / lcount

• 出错任务名（task:…，仅在调度器启动后有效）

• 一小段栈 hexdump

• backtrace（frame 0 为出错 PC，其余为每层 call 之后的返回地址）

备注

AmebaLite 多核（KM4 / KR4 / DSP）共用一路 LogUART，日志会逐字符穿插混叠。分析 crash 前强烈建议先在 MCU SDK 使能 CONFIG_LOGUART_AGG_EN，否则 dump 里的寄存器 / PC 行可能被别的核冲成乱码。开启后每行按核打标签（DSP = [AP]、KM4 = [HP]、KR4 = [LP]）。

使用 dsp_dump.py 分析

脚本仅依赖 Python3 标准库。先把 Xtensa 工具加入 PATH，再把包含 dump 的日志喂给它：

export PATH=$PATH:/opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools/bin

python3 <dsp_sdk>/project/img_utility/dsp_dump.py serial.log     # 读串口日志文件
cat dump.txt | python3 <dsp_sdk>/project/img_utility/dsp_dump.py # 或管道 / 粘贴

常用选项：

选项	说明
--core AP	仅解析 DSP(AP) 一路的帧
--no-symbolize	只解 exccause + 列出裸 PC，不做符号化
--elf <ELF>	手动指定 project_dsp 的 ELF（链接后的 ELF，不是 .bin）
--addr2line <path>	手动指定 xt-addr2line 路径

脚本行为要点：

• 自动探测 ELF 与 xt-addr2line：ELF 默认在 auto_ws/project_dsp/bin/*/Release/project_dsp 查找，工具在 PATH / $XT_ADDR2LINE / Xtensa 安装目录查找。找不到时会打印明确报错并列出搜索过的位置与修复建议（加 PATH / 传 --elf / 先编译），并回退打印裸 PC。

• 兼容多核聚合前缀：自动剥离行首时间戳与任意位置的 [AP] / [HP] / [LP] / … 标签。

• 多 dump 自动取最近一份：一份串口日志常含多次崩溃，只有最近一份才与当前烧录的 ELF 地址对得上；脚本默认解析最后一份并给出提示。务必保证 ELF 与产生该 dump 的固件是同一次编译，否则符号全错。

示例输出：

task     : svc
pc       : 0xbad00000
exccause : 12  InstrPIFDataErrorCause
           PIF data error during instruction fetch
excvaddr : 0xbad00000  (faulting address)

=============== backtrace ==============
 0. 0xbad00000 [AP]  ??            (??:0)
 1. 0x60306790 [AP]  svc_parse     (main.c:138)
 2. 0x60306766 [AP]  svc_dispatch  (main.c:149)
 3. 0x60306720 [AP]  svc_handle    (main.c:154)
 4. 0x603066c2 [AP]  svc_task      (main.c:161)

怎么读 backtrace

• frame 0 是出错 PC；其余帧是每层 call 之后的返回地址（符号化时对返回地址帧用 pc-1 查询，落到调用点行号）。

• DSP 当前使用 Call0 ABI。Call0 没有 ABI 规定的帧链，backtrace 采用扫栈 + call 指令校验：绝不漏真帧，但偶尔会混入 stale 假阳性；符号化后不属于调用链的函数一眼可辨，忽略即可。

exccause 速查（常见）

dsp_dump.py 会直接给出全名，这里列最常撞上的几个：

exccause	名称	含义
2	InstructionFetchErrorCause	取指时内部物理地址 / 数据错误
3	LoadStoreErrorCause	load/store 时内部物理地址 / 数据错误
9	LoadStoreAlignmentCause	非对齐 load/store
12	InstrPIFDataErrorCause	取指时 PIF 数据错误（如跳到坏地址）
13	LoadStorePIFDataErrorCause	load/store 时 PIF 数据错误（如访问未映射地址）
28 / 29	Load/StoreProhibitedCause	访问了不允许 load/store 的页（MPU / Region）
32..39	Coprocessor{n}Disabled	在 cp{n} 关闭时用了协处理器指令（n = code − 32）

没有脚本时的手动办法

手动运行 xt-addr2line -f -C -e <project_dsp ELF> <pc0> <pc1> …``（返回地址帧可用 ``pc-1），或直接在 project_dsp.asm 里按地址查（见 编译调试文件）。

调试建议

• 如果始终无法连接调试端口，可能是因为 SWD 端口被关闭（SWD 端口被用作普通 GPIO）。需要打开 GPIO 的 SWD 功能。

• 生成 DSP 反汇编和 map 文件: 编译调试文件 。

• Linux 环境下为方便调试，可以将以下路径加入 PATH：

  /opt/Tensilica/xocd-14.08
  /opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools/bin
  

• 如果使用 auto_build.sh 而非 Xplorer 编译项目，可在以下路径找到 project_dsp elf 文件： <dsp_sdk>/auto_ws/project_dsp/bin/<configuration_name>/Release

• 更多调试指南请参考 Xtensa 文档。

xt-ocd 调试问题

问题描述：在 Linux Xplorer 中进行调试时，出现 Cannot Find OCD Daemons 错误。

原因分析：xt-ocd 版本或路径未正确配置。

解决方法：在文件 /opt/xtensa/Xplorer-9.0.18/utils/xocdm9.0.18.3000/xocdm.ini 中的 # [XOCDInstallations] 后添加一行：

14.08=/opt/Tensilica/xocd-14.08