匠芯创 cJTAG / JTAG 实板调试：FT232H、OpenOCD 与 GDB

本文整理 匠芯创（ArtInChip）D125 E907 + FT232H + SiFive OpenOCD 2020.11.0 的实板调试记录，包含硬件连接、完整配置、原始运行日志及 GDB 附加步骤。项目已确认 cJTAG 连接经过实板验证：PA 组使用 D0 → PA11（TCKC），D1/D2 → PA10（TMSC）。

本文同时收录 D125 两线 cJTAG 和 D213 四线 JTAG：D125 的实板验证结论与日志保持原有范围；D213 依据新增 D21x 配置整理，不将 D125 日志作为 D213 实测证明。

验证边界

项目已确认本文 cJTAG 接线和 OpenOCD 连接经过实板验证，日志记录了 IDCODE/DTMCS 读取与 CPU examine。本文新增的 GDB 操作指引不据此宣称所有步骤均已验证。示例使用 ftdi_oscan1_mode on 的两线模式，不是普通四线 JTAG 接法；该命令依赖所用 OpenOCD 分支，不保证其他版本或 FTDI 模块可直接使用。

D125：cJTAG 硬件连接

D125 引脚

根据本次提供的官方 D125 数据手册引脚摘录，两组调试引脚均使用 功能 8。根据板上实际引出和固件 pinmux 选择一组，不同时连接两组。下表脚号按封装区分，不是开发板排针编号。

cJTAG 信号	MCU 引脚	D125CxS 芯片脚号	D125ExS 芯片脚号
JTAG_MS / TMSC	PA10	79	53
JTAG_CK / TCKC	PA11	80	54
JTAG_MS / TMSC（另一组）	PC0	61	23
JTAG_CK / TCKC（另一组）	PC5	66	28

FT232H 接线

FT232H 模块信号	连接位置	作用
D0 / ADBUS0	D125 JTAG_CK：PA11 或 PC5	输出调试时钟
D1 / ADBUS1	D125 JTAG_MS：PA10 或 PC0	FT232H 向目标输出数据
D2 / ADBUS2	同一 JTAG_MS 节点	FT232H 从目标输入数据
GND	D125 GND	调试器与目标板共地

本例 D1、D2 在同一 JTAG_MS 节点短接。PA 组接法为 D0 → PA11，D1/D2 → PA10；PC 组则为 D0 → PC5，D1/D2 → PC0。

接线更正

此前 PA10/PA11 的时钟与数据文字说明相反，现已纠正为 PA11 时钟、PA10 数据。项目已确认 cJTAG 调试经过实板验证；这是对文档接线描述的更正，不应继续标记为“未上板验证”。其他封装、PC 组接线和不同适配器仍需按实际硬件核对。

D0 与 D1/D2 短接组不能接到同一个引脚。 D1/D2 短接仅适用于本例适配器及驱动模式，不能推广为普通 JTAG 接法。

连接前断电，确认 FT232H 模块 VCCIO、输出电平与 D125 对应 IO 电源域匹配。USB 供电电压不等于 IO 电平；不要把 5 V 接到调试信号，也不要未经核对把模块电源输出接入目标板。目标板应正常供电。

配置保留了 TMS 和 JTAG_SEL 的适配器布局定义，不表示需要把 D3 或 JTAG_SEL 接到目标的 JTAG_MS 或 JTAG_CK。更换适配器时应核对其原理图和驱动实现。

Windows 准备：先安装 FT232H WinUSB 驱动

启动 OpenOCD 前，先为本例 FT232H 安装 WinUSB 驱动。 D125 cJTAG 与 D213 JTAG 共用这一步；已正确安装时无需重复替换。

1. 关闭占用适配器的软件，插入 FT232H，从 Zadig 官网 下载并运行工具，按提示授予管理员权限。
2. 如未显示设备，选择 Options → List All Devices。
3. 选择实际 FT232H。截图名称为 USB <-> Serial Converter，核对 USB ID：0403 / 6014，与本文配置一致；名称可能不同，多设备时应通过插拔或序列号确认。
4. 将右侧目标驱动选择为 WinUSB。截图左侧当前驱动为 FTDIBUS，按钮为 Replace Driver；未安装驱动时可能显示 Install Driver。
5. 执行安装并等待成功提示，重新检查当前驱动已是 WinUSB，再启动下文 OpenOCD。

截图由项目提供，显示安装进行中，不是安装完成凭证；图中 Zadig 和驱动版本仅为当时环境，不要求固定使用该版本。

仅替换目标适配器的驱动

不要选择键盘、鼠标、USB Hub 或其他串口设备。替换驱动可能使依赖原 FTDI 驱动的程序无法再访问该设备；需要恢复原用途时，应重新安装匹配的 FTDI 驱动。本文适配器为 FT232H，不能仅凭“FT232”名称认定其他型号可用。

操作依据：Zadig 官方使用指南。

D125 OpenOCD 配置

保存为 openocd-d125-ft232h.cfg，或 下载配置文件。

配置已按本次提供的 tmp/openocd-d125-ft232h.cfg 更新，保留原始参数与注释。两份下载配置均使用 bindto 0.0.0.0，会监听所有网络接口。仅在隔离、可信网络中使用；本机调试建议将其改为 bindto 127.0.0.1，远程访问优先使用 SSH 隧道，避免直接暴露调试端口。

# D125 E907 + FT232H，SiFive OpenOCD 2020.11.0。
# 目标走 cJTAG OSCAN1，不是四线 IEEE 1149.1。引脚布局仅适用于当前这块适配器。

adapter driver ftdi
ftdi_vid_pid 0x0403 0x6014
ftdi_channel 0

# 多块 FTDI 同时在线时，取消下一行注释并填入序列号。
# ftdi_serial "YOUR_FT232H_SERIAL"

ftdi_oscan1_mode on
transport select jtag

# ADBUS0=TCK、ADBUS1=TDI、ADBUS2=TDO、ADBUS3=TMS；ACBUS0=JTAG_SEL 输出使能。
ftdi_layout_init 0x0008 0x001b
ftdi_layout_signal TCK -data 0x0001
ftdi_layout_signal TDI -data 0x0002
ftdi_layout_signal TDO -input 0x0004
ftdi_layout_signal TMS -data 0x0008
ftdi_layout_signal JTAG_SEL -data 0x0100 -oe 0x0100


if {![info exists ADAPTER_KHZ]} { set ADAPTER_KHZ 100 }
adapter speed $ADAPTER_KHZ
reset_config none

# RISC-V DTM：IR 长度 5，板上实测 IDCODE=0x10000b6f、DTMCS=0x000040a1。
# 保留默认 IR 校验（init 时可能仍有 capture 告警）。examine 放到后面手动做。
jtag newtap d125 cpu -irlen 5 -expected-id 0x10000b6f
target create d125.cpu riscv -chain-position d125.cpu -defer-examine

bindto 0.0.0.0
gdb_port 3333
telnet_port 4444
tcl_port disabled
gdb_breakpoint_override hard

# 不加载 flash 算法，不做 RAM 初始化、硬件复位或自动 halt。

# 旧驱动在本连接上会在初始 IR 校验失败。先读 IDCODE/DTMCS，匹配后再 examine。
init
irscan d125.cpu 0x01
set d125_id [drscan d125.cpu 32 0]
irscan d125.cpu 0x10
set d125_dtmcs [drscan d125.cpu 32 0]
echo "D125 IDCODE=0x$d125_id DTMCS=0x$d125_dtmcs"
if {$d125_id ne "10000b6f" || $d125_dtmcs ne "000040a1"} {
    error "D125 probe mismatch; refusing CPU examination."
}
d125.cpu arp_examine
echo "D125 CPU examination complete; GDB port 3333. Attach GDB to halt."

该配置不提供 Flash 烧写算法、RAM 初始化或硬件复位流程，也不主动执行 halt。100 kHz 是当前记录使用的起始速率，不代表最高稳定速率。

运行命令

在 Windows PowerShell 中进入配置文件所在目录，执行：

.\OpenOCD-SiFive-0.10.0\bin\openocd.exe -f .\openocd-d125-ft232h.cfg

目录名中的 0.10.0 与启动日志中的 2020.11.0 是不同的版本标识；应检查实际启动横幅，而不是仅凭文件夹名判断版本。

如需降低速度，可在读取配置前设置变量：

.\OpenOCD-SiFive-0.10.0\bin\openocd.exe -c "set ADAPTER_KHZ 50" -f .\openocd-d125-ft232h.cfg

项目提供的运行日志

以下是原连接记录，不是本次文档整理重新测得的结果：

Open On-Chip Debugger 0.10.0+dev (SiFive OpenOCD 0.10.0-2020.11.0)
Licensed under GNU GPL v2
For bug reports:
        https://github.com/sifive/freedom-tools/issues
force hard breakpoints
Info : clock speed 100 kHz
Info : JTAG tap: d125.cpu tap/device found: 0x10000b6f (mfg: 0x5b7 (<unknown>), part: 0x0000, ver: 0x1)
Error: d125.cpu: IR capture error; saw 0x00 not 0x01
Warn : Bypassing JTAG setup events due to errors
Info : starting gdb server for d125.cpu on 3333
Info : Listening on port 3333 for gdb connections
D125 IDCODE=0x10000b6f DTMCS=0x000040a1
Info : datacount=1 progbufsize=2
Info : Examined RISC-V core; found 1 harts
Info :  hart 0: XLEN=32, misa=0x40901125
D125 CPU examination complete; GDB port 3333. Attach GDB to halt.
Info : tcl server disabled
Info : Listening on port 4444 for telnet connections

如何判断连接状态

• TAP IDCODE 为 0x10000b6f，显式读取 DTMCS 为 0x000040a1。
• 配置仅在两个读值匹配后执行 CPU examine；不匹配时停止，不应删除校验强行继续。
• 日志显示识别到一个 RV32 hart，但 IR capture error 仍然存在，不等于整个扫描链已无异常。
• 本记录在初始校验报错后显式扫描成功，并完成 CPU examine；这不是适用于所有 IR 错误的通用修复。
• 端口监听成功不代表 CPU halt、寄存器读取、断点或 Flash 操作已经验证。

D213：四线 JTAG 硬件与配置

D125 使用两线 cJTAG；D213 在本文使用项目提供的 D21x 四线 IEEE 1149.1 JTAG 配置，两者不能混用。D213 配置文件和 TAP 名保留为 d21x，不改成 d125。

FT232H 信号	D213 目标信号	方向（相对适配器）
D0 / ADBUS0	TCK	输出时钟
D1 / ADBUS1	TDI	输出数据
D2 / ADBUS2	TDO	输入数据
D3 / ADBUS3	TMS	输出状态控制
GND	GND	共地
D4 / ADBUS4	nTRST（可选，核对板级设计）	复位输出，配置初始拉高
D5 / ADBUS5	nSRST（可选，核对板级设计）	复位输出，配置初始拉高

四线 JTAG 不短接 D1/D2，也不启用 ftdi_oscan1_mode。 当前资料未给出 D213 的 GPIO 名、封装脚号或排针编号，接线前必须按实际原理图和 pinmux 确认，不能沿用 D125 PA10/PA11。

reset_config none 表示本配置不主动执行硬件复位；初始拉高并不代表两根复位线适用于所有目标板。基础连接可不接复位线。

D213 配置文件

下载 openocd-d21x-ft232h.cfg。下面内容与项目提供的配置同步，中文注释在英文文章中也原样保留，方便比对。

# D21x + FT232H，SiFive OpenOCD 2020.11.0。
# 目标为 IEEE 1149.1 四线 JTAG（TCK/TDI/TDO/TMS），不要开启 cJTAG/OSCAN1。

adapter driver ftdi
ftdi_vid_pid 0x0403 0x6014
ftdi_channel 0

# 多块 FTDI 同时在线时，取消下一行注释并填入序列号。
# ftdi_serial "YOUR_FT232H_SERIAL"

transport select jtag

# ADBUS0=TCK、ADBUS1=TDI、ADBUS3=TMS 输出；ADBUS2=TDO 输入。
# ADBUS4/5 作 nTRST/nSRST，初始拉高，避免上电就把目标按在复位里。
ftdi_layout_init 0x0030 0x003b

# nTRST=ADBUS4，nSRST=ADBUS5；本配置 reset_config none，这两根线不主动翻转。
ftdi_layout_signal ntrst -data 0x0010
# 接到目标 SRST 时使用。
ftdi_layout_signal nsrst -data 0x0020

if {![info exists ADAPTER_KHZ]} { set ADAPTER_KHZ 100 }
adapter speed $ADAPTER_KHZ
reset_config none

# RISC-V DTM：IR 长度 5，IDCODE=0x10000b6f。先建 TAP，examine 放到后面手动做。
jtag newtap d21x cpu -irlen 5 -expected-id 0x10000b6f
target create d21x.cpu riscv -chain-position d21x.cpu -defer-examine

bindto 0.0.0.0
gdb_port 3333
telnet_port 4444
tcl_port disabled
gdb_breakpoint_override hard

# 不加载 flash 算法，不做 RAM 初始化、硬件复位或自动 halt。

# init 时 TDO 空闲电平会被当成后续 TAP，并触发 IR capture 告警。
# 先关掉非 d21x 的 TAP，再读 IDCODE(IR=0x01) 和 DTMCS(IR=0x10)，匹配后才 examine。
init
echo "D21x taps after init: [jtag names]"
foreach tap_name [jtag names] {
    if {![string match "d21x.*" $tap_name]} {
        echo "Disabling extra TAP $tap_name"
        jtag tapdisable $tap_name
    }
}
runtest 5
irscan d21x.cpu 0x01
set d21x_id [drscan d21x.cpu 32 0]
irscan d21x.cpu 0x10
set d21x_dtmcs [drscan d21x.cpu 32 0]
echo "D21x IDCODE=0x$d21x_id DTMCS=0x$d21x_dtmcs"
if {$d21x_id ne "10000b6f" || $d21x_dtmcs ne "000040a1"} {
    error "D21x probe mismatch; refusing CPU examination."
}
d21x.cpu arp_examine
echo "D21x CPU examination complete; GDB port 3333. Attach GDB to halt."

D213 启动与检查

.\OpenOCD-SiFive-0.10.0\bin\openocd.exe -f .\openocd-d21x-ft232h.cfg

此配置列出初始化后的 TAP，禁用名称不匹配 d21x.* 的 TAP，执行 runtest 5，再校验 IDCODE 和 DTMCS。该处理针对项目当前连接，不是通用多 TAP 链配置；真实多器件链不可直接照搬。

配置预期 IDCODE 为 0x10000b6f、DTMCS 为 0x000040a1，匹配后才执行 d21x.cpu arp_examine。这些是脚本校验值，不是本文新增的 D213 实测日志。 当前提供的完整运行日志属于 D125，不能将其当作 D213 的验证结果。错误时先核对接线、芯片与扫描链，不删除校验绕过失败。

D125 和 D213 配置均使用 GDB 3333、Telnet 4444；同一主机只启动其中一个，或自行规划不冲突的端口。GDB 连接步骤见下节，D213 必须选用与 D213 板上固件匹配的 ELF。

使用 GDB 连接

准备与目标 RISC-V 架构兼容的 GDB，以及与板上当前固件匹配、带调试信息的 ELF。下面的 riscv64-unknown-elf-gdb.exe 仅为工具名示例，需替换为 SDK 实际提供且支持 RV32 的 GDB。

保持 OpenOCD 窗口运行，在另一个终端启动：

riscv64-unknown-elf-gdb.exe .\firmware.elf

随后在 GDB 提示符中执行：

target extended-remote 127.0.0.1:3333
monitor halt
info registers
x/8i $pc
bt

启动时指定 ELF 只在主机加载符号，不会自动烧写固件。连接与 halt 会影响目标运行，测试前让电机、执行器等受控外设处于安全状态。回溯质量取决于符号、优化选项和当前执行状态。

若需要断点，使用固件中实际存在的函数名：

hbreak your_function
continue

your_function 是占位符；运行过程中可按 Ctrl+C 请求中断，再检查寄存器。硬件断点数量有限。已运行过的初始化函数不会因设置断点而重新执行。

结束前可删除断点；根据是否需要恢复目标，显式选择 monitor resume：

delete breakpoints
monitor resume
detach
quit

不要直接套用 load、run 或 monitor reset halt。 本配置未提供固件下载、RAM 初始化及板级复位保证，附加调试不等于支持重新启动或烧写。

通用连接与 halt 命令参考：OpenOCD GDB 文档、OpenOCD 通用命令。这些文档不验证本例 D125 的电气连接或旧版驱动行为。

常见问题

匠芯创 D125 使用 FT232H 时，PA10 和 PA11 分别接什么？

PA10 是 JTAG_MS / TMSC，接 FT232H 的 D1/D2 共用数据节点；PA11 是 JTAG_CK / TCKC，接 D0。两脚选择功能 8，并与目标板共地。

D125 cJTAG 是否已经实板验证？

是，项目已确认本例连接经过实板验证，提供的日志记录了 IDCODE、DTMCS 和 RV32 CPU examine。验证结论不自动覆盖其他适配器、所有 GDB 操作或 Flash 烧写。

这份 OpenOCD 配置可以烧写 D125 Flash 吗？

本配置未提供 Flash 算法，不应作为烧写配置。它用于连接与 CPU 检查，文章另提供 GDB 附加指引。

相关教程：匠芯创 D126 Wi-Fi / BLE 使用。

排查要点

现象	优先检查
找不到 FTDI 设备	USB 枚举、VID/PID、驱动、是否被其他程序占用；多适配器时指定序列号
不认识 ftdi_oscan1_mode	OpenOCD 分支及构建版本是否与记录一致
IDCODE / DTMCS 不匹配	PA10/PA11 接线、共地、电平、pinmux、供电与时钟速度
IR capture error	保留完整日志；结合显式读值及 CPU examine 判断，不能仅屏蔽校验
GDB 无法连接	OpenOCD 是否仍在运行、3333 端口是否被占用、本机地址是否正确
连接后 halt 或读寄存器失败	CPU 调试状态、链路稳定性、固件对调试引脚的复用及旧驱动兼容性
符号地址或回溯异常	ELF 是否与当前板上固件一致，是否包含调试信息