Pinecil 实现 JLink JTAG 访问功能

背景

Pinecil 是一款广受欢迎的开源便携式焊接工具，其内部搭载了 Bouffalo Lab 的 BL706 微控制器（MCU）。作者早在两年前购买了 Pinecil 并撰写了关于焊接扩展板（breakout board）及访问 UART 端口的文章。近期，随着 Zephyr 操作系统正式上游支持 Bouffalo Lab BL706 MCU，作者再次深入使用 Pinecil 进行开发工作。这一进展离不开 @VynDragon、@will-tm、@josuah 等贡献者在 Bouffalo Lab 上游支持方面所做的努力。

虽然 UART 接口对于查看系统日志非常有用，但在排查早期系统初始化阶段的问题或驱动程序故障时，JTAG 调试访问至关重要。尽管市面上有多种 JTAG 调试器，但作者通常首选 SEGGER 的 J-Link，因其拥有广泛的兼容性和强大的工具链支持。

核心内容

本文详细记录了如何通过物理连接和软件配置，将 J-Link 调试器接入 Pinecil 的 BL706 芯片，从而实现底层硬件调试。

1. 硬件连接方案

为了连接 J-Link 到 Pinecil，必须使用作者此前文章中描述的扩展板。该扩展板提供了用于 JTAG breakout 的 10 针排母，包含：

• 1 个 3.3V 参考电压引脚（VTref）
• 4 个接地引脚（GND）
• 标准的 JTAG 信号线

连接方式非常灵活：虽然市面上有许多适配器可将各种调试引脚布局转换为 J-Link 的 20 针连接器，但使用公对母杜邦线（female-to-female dupont wires）直接连接 Pinecil 扩展板上的标准 2.54mm 引脚与 J-Link 是最简便的方法。

接线注意事项：

• 排线方向： 如果使用排线，需注意引脚方向。以缺口朝上为基准，J-Link 排线的左上角（VTref 引脚，即白色线）应对应 J-Link 引脚布局右上角的 VTref 引脚。
• 固定连接： 建议在杜邦线与 J-Link 之间使用排线（配合公对母杜邦线），这样可以避免在 Pinecil 调试会话之间需要频繁重新插拔引脚，方便 J-Link 用于其他目的。

2. 连接验证

连接完成后，可以使用 JLinkExe 命令来验证映射是否正确。如果 VTref 引脚正确连接到扩展板的 3.3V 引脚，J-Link 应能检测到逻辑电压水平（约 3.3V）。

作者提供的终端输出示例显示：

• 成功通过 USB 连接到 J-Link。
• 固件版本：J-Link V11。
• VTref=3.335V：确认电压检测正常。

3. 软件调试配置

要附加调试器（如 gdb），可以使用 JLinkGDBServer 连接到 BL706 MCU 底层 SiFive E24 核心集群中的 JTAG 电路，并在本地端口 2331 启动 GDB 服务器。

启动命令：

JLinkGDBServer -device E24 -if JTAG

服务器输出关键信息：

• 监听 TCP/IP 端口 2331。
• 目标设备：E24。
• 目标接口：JTAG，速度 4000kHz。
• 检测到目标电压：3.30 V。
• 发现 1 个 JTAG 设备，总 IR 长度为 5。
• JTAG ID: 0x20000E05 (RISC-V)：确认检测到 RISC-V 架构。
• 检测到 RISC-V RV32，使用 RV32 寄存器集与 GDB 通信。
• 核心实现了单精度浮点单元（FPU）。
• 服务器进入等待 GDB 连接状态。

4. 客户端连接与调试

最后，使用 gdb 连接到服务器并加载固件符号表：

gdb -ex 'target remote :2331' ./path/to/firmware.elf

连接成功后，GDB 会显示远程调试信息，例如当前停在 arch_irq_unlock 函数处。此时，开发者即可开始逐步执行指令（step through instructions），深入排查系统底层问题。

关键要点

• 硬件依赖：必须使用 Pinecil 的专用扩展板才能引出 JTAG 信号，扩展板需提供 3.3V 参考电压和标准 JTAG 引脚。
• 连接简便性：无需专用适配器，使用标准的 2.54mm 公对母杜邦线即可连接 Pinecil 扩展板与 J-Link。
• 电压检测关键：VTref 引脚的连接至关重要，J-Link 通过此引脚检测目标板电压（约 3.3V），这是通信正常的前提。
• 核心架构识别：BL706 基于 SiFive E24 核心，属于 RISC-V RV32 架构，J-Link 能自动识别并配置相应的寄存器集。
• 调试流程标准化：
  1. 物理连接 J-Link 与 Pinecil 扩展板。
  2. 运行 JLinkExe 验证电压和连接。
  3. 运行 JLinkGDBServer -device E24 -if JTAG 启动 GDB 服务器。
  4. 使用 gdb 连接本地端口 2331 并加载 .elf 文件进行断点和单步调试。
• Zephyr 支持：该调试方法得益于 Zephyr RTOS 对 Bouffalo Lab BL706 MCU 的上游支持，使得在开源生态中调试该硬件成为可能。

意义与影响

这篇文章不仅是一份技术操作指南，更体现了开源硬件与软件生态的深度融合。

1. 降低嵌入式开发门槛：Pinecil 作为消费级/DIY 热门产品，其底层调试通常较为困难。通过公开 JTAG 调试方案，使得普通开发者也能深入排查 BL706 芯片的底层驱动和初始化问题，极大地提升了该平台的可开发性。
2. 推动 RISC-V 在嵌入式领域的落地：BL706 是 RISC-V 架构在低功耗 IoT 设备中的典型代表。通过 Zephyr 的上游支持和成熟的 J-Link 调试工具链，证明了 RISC-V 芯片在专业嵌入式开发环境中具备与 ARM 等架构同等的调试友好性。
3. 开源协作的价值：文中特别致谢了多位贡献者，展示了社区协作在推动硬件支持（如 Zephyr 对 Bouffalo Lab 的支持）中的关键作用。这种“硬件开源+软件开源+调试工具开源”的模式，加速了创新迭代。
4. 实用主义的技术选型：作者选择 J-Link 而非其他廉价调试器，强调了在复杂底层调试中，工具链的兼容性和稳定性（如 SEGGER 的工具生态）对于提升开发效率的重要性。这为其他嵌入式开发者提供了宝贵的实践经验。