1. 代码开发工具 OpenOCD 的 TCL 脚本:从手动敲命令到可重复回归
代码开发工具里的 OpenOCD,很多人只把它当成烧录和 GDB 的连接器;真正把它用顺,是在 TCL 脚本里把单片机复位、寄存器读写和断言串成一条可重复的回归。手工敲 reset halt、mww、mrw 的调试方式,在单次排障时够用,一旦要跑十块板、每天跑一遍,就会变成体力活。OpenOCD 内嵌 Jim-Tcl 解释器,配上 -f 加载脚本、-c 执行命令,就能把“点一下走一步”的调试动作固化下来。下面从测试框架、远程 RPC 到 CI/CD 集成,按一条可照做的路线把这件事讲透;适合已经会用 OpenOCD 烧录、但还没把硬件测试接进流水线的嵌入式开发者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具里的 TCL 测试框架:断言、用例与报告怎么落地
2.1 断言与计数器:把“看一眼”变成“判一下”
硬件测试最怕的是“日志里打印了一堆值,人眼扫一遍觉得没问题”。OpenOCD 的 TCL 脚本可以直接读写目标内存,所以完全可以把“读回来比一比”写成断言,让脚本自己给出 PASS 或 FAIL。下面这套框架不依赖额外库,OpenOCD 启动时就能解释:
tcl复制# test_framework.tcl - 简易测试框架
# 全局计数器
set test_pass 0
set test_fail 0
set test_total 0
# 断言:检查内存值是否符合预期
proc assert_mem_equal {addr expected msg} {
global test_pass test_fail test_total
incr test_total
set actual [mrw $addr]
if {$actual == $expected} {
incr test_pass
echo "PASS: $msg"
} else {
incr test_fail
echo "FAIL: $msg (expected [format 0x%08X $expected], got [format 0x%08X $actual])"
}
}
# 断言:检查目标状态
proc assert_target_state {expected_state msg} {
global test_pass test_fail test_total
incr test_total
set state [dict get [target current] -state]
if {$state eq $expected_state} {
incr test_pass
echo "PASS: $msg"
} else {
incr test_fail
echo "FAIL: $msg (expected $expected_state, got $state)"
}
}
# 输出测试报告
proc test_report {} {
global test_pass test_fail test_total
echo "=============================="
echo "Test Report: $test_total total, $test_pass passed, $test_fail failed"
echo "=============================="
if {$test_fail > 0} {
return -code error "Tests failed"
}
}
assert_mem_equal 接收三个参数:addr 是要读的内存地址,expected 是期望值,msg 是失败时给人看的说明。它内部用 mrw $addr 读回实际值,按 32 位比较;不相等时把期望值和实际值都格式化成 0x%08X,方便在日志里直接定位。assert_target_state 不读内存,而是用 dict get [target current] -state 取当前目标的运行状态,例如 reset halt 之后预期是 halted,就用它判断目标有没有真正停住。
计数器放在全局变量里,每调用一次断言就 incr test_total,通过就加 test_pass,失败就加 test_fail。test_report 在末尾统一输出总数、通过数和失败数;只要 test_fail > 0,就用 return -code error "Tests failed" 让脚本以错误结束。注意,这个错误会不会变成 OpenOCD 进程的非零退出码,跟启动方式和 OpenOCD 版本有关,CI 里仍然要显式检查退出码,不能只看日志里有没有 FAIL。
2.2 用例层:GPIO 输出测试怎么落到寄存器
框架只负责“判”,具体“怎么让外设动起来”要放到用例里。下面这个 GPIO 用例把复位、时钟使能、引脚配置、置高、置低和断言串在一起:
tcl复制# test_gpio.tcl - GPIO 功能测试用例
source [find test_framework.tcl]
proc test_gpio_output {} {
# 复位并停住目标
reset halt
# 使能 GPIOA 时钟 (以 STM32F1 为例,RCC_APB2ENR)
mww 0x40021018 0x00000004
# 配置 PA0 为推挽输出
mww 0x40010800 0x00000003
# 设置 PA0 输出高电平 (GPIOA_BSRR)
mww 0x40010810 0x00000001
assert_mem_equal 0x4001080C 0x00000001 "PA0 应输出高电平"
# 设置 PA0 输出低电平
mww 0x40010814 0x00000001
assert_mem_equal 0x4001080C 0x00000000 "PA0 应输出低电平"
}
# 执行测试
test_gpio_output
test_report
source [find test_framework.tcl] 的作用是把框架文件加载进来,find 会在 OpenOCD 的脚本搜索路径里找文件;如果框架文件和用例不在搜索路径里,最容易出的问题就是找不到文件,后面避坑章节会展开。reset halt 先把目标复位并停在复位向量处,保证测试从一个确定状态开始,而不是接着上一次运行的残局。
mww 0x40021018 0x00000004 写的是 RCC_APB2ENR,值 0x00000004 对应 bit2,用来使能 GPIOA 时钟。这一步不能省:复位后外设时钟默认关闭,直接写 GPIO 寄存器不会生效,读回值也可能一直是 0。mww 0x40010800 0x00000003 写 GPIOA_CRL,把 PA0 配成推挽输出模式;mww 0x40010810 0x00000001 写 BSRR 的低 16 位,把 PA0 置高;mww 0x40010814 0x00000001 写 BRR,把 PA0 拉低。断言读的是 0x4001080C,也就是 GPIOA_ODR 输出数据寄存器,读回 1 表示高电平,读回 0 表示低电平。
这里的关键不是记住几个地址,而是理解“配置寄存器”和“数据寄存器”不是一回事:BSRR/BRR 是写来改变输出的,ODR 是读回当前输出状态的。把断言压在 ODR 上,比只打印 BSRR 的写入值更有意义。
2.3 用 -f 跑脚本:命令行、日志和退出码
用例写完后,用 -f 按顺序加载接口配置、目标配置和测试脚本:
bash复制openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -f test_gpio.tcl
-f 的参数是一个配置文件或 TCL 脚本,OpenOCD 会按命令行出现的顺序依次加载。先加载 interface/stlink.cfg 是为了让 OpenOCD 知道用哪种调试器连接;再加载 target/stm32f1x.cfg 是为了知道目标芯片的 Flash 算法、内存映射和寄存器定义;最后加载 test_gpio.tcl,脚本里的 test_gpio_output 和 test_report 在顶层直接调用,所以加载即执行。
跑完后先看回显:每条断言都会打印 PASS: 或 FAIL:,最后 test_report 会给出总数。单次排障看回显就够了;接进流水线时,不能只看回显,还要让 CI 拿到进程退出码。test_report 里的 return -code error 是一个信号,但真正决定流水线红不红的,是外层脚本有没有接住这个信号。下一章先把 OpenOCD 放到后台,用 TCL Server 和 Python 把连接关系理清楚,再回到 CI 里接退出码。
3. TCL Server 与 Python RPC:把 OpenOCD 接进远程测试链路
3.1 TCL Server 的边界:默认 6666 和连接生命周期
OpenOCD 启动时会监听一个 TCL RPC 端口,默认是 6666。任何外部程序都可以通过 TCP 连接向 OpenOCD 发送 TCL 命令并获取返回结果。这个能力让 OpenOCD 不只是一个命令行工具,而是可以被 Python、pytest 或 CI 脚本远程驱动的调试服务。
用之前先明确边界:6666 是本地 TCP 端口,同一台机器上同时开两个 OpenOCD 实例,第二个会因为端口被占用而启动失败;上一个实例没有退干净,也会出现“连接被拒绝”或“连上了但不是当前目标”的玄学现象。启动前用 ss -ltnp | grep 6666 看一下端口有没有被占,比事后猜要省时间。连接建立后,客户端发一条 TCL 命令,服务端回显结果;命令结束的标记和读取方式取决于客户端实现,最简单的做法是发完命令后关闭写端,再循环读到 EOF。
3.2 最小 Python 客户端:发一条 mrw 读 CPUID
下面这个客户端只做一件事:连上 6666,发送 mrw 0xE000ED00,把回显读回来。mrw 是 OpenOCD 的读内存命令,0xE000ED00 是 Cortex-M 的 CPUID 寄存器地址:
python复制import socket
HOST, PORT = "127.0.0.1", 6666
def tcl(cmd: str, timeout: float = 2.0) -> str:
with socket.create_connection((HOST, PORT), timeout=timeout) as s:
s.sendall((cmd + "\n").encode())
s.shutdown(socket.SHUT_WR) # 告诉服务端命令结束
chunks = []
while True:
data = s.recv(4096)
if not data:
break
chunks.append(data)
return b"".join(chunks).decode(errors="replace")
if __name__ == "__main__":
print(tcl("mrw 0xE000ED00"))
create_connection 的 timeout=2.0 是连接超时,不是命令执行超时;如果 OpenOCD 还没开始监听,这里会直接抛异常。sendall 把命令加上换行发出去,shutdown(socket.SHUT_WR) 关闭写方向,让服务端知道命令发送完毕;然后循环 recv 直到对端关闭。mrw 0xE000ED00 读回的是 32 位值,实际回显通常带地址前缀,例如 0xe000ed00: 411fc231 这类格式,不同版本可能有差异,先单独跑一条看回显,再写解析逻辑。
这个客户端适合做冒烟测试:能连上、能读到 CPUID,说明 OpenOCD 进程、调试器连接和目标供电至少是通的。它不适合直接塞进大规模测试,因为每次调用都新建连接,频繁测试时开销不小;更稳的做法是用一个长连接封装,或者用 pytest fixture 管理进程和连接的生命周期。
3.3 pytest fixture:把进程和连接分开管
Python 侧做硬件测试,推荐把“OpenOCD 进程”和“TCL 连接”分成两个 fixture。进程 fixture 负责启动、等待端口就绪、结束时回收;连接 fixture 负责发命令。下面是一个最小结构:
python复制import subprocess, time, socket, pytest
class OpenOcdProcess:
"""管理 OpenOCD 后台进程"""
def __init__(self, interface, target):
self.proc = subprocess.Popen(
["openocd", "-f", interface, "-f", target],
stdout=subprocess.PIPE, stderr=subprocess.PIPE
)
def stop(self):
self.proc.terminate()
self.proc.wait()
def wait_port(host="127.0.0.1", port=6666, timeout=10.0):
deadline = time.time() + timeout
while time.time() < deadline:
try:
with socket.create_connection((host, port), timeout=0.5):
return True
except OSError:
time.sleep(0.1)
return False
@pytest.fixture(scope="session")
def ocd_session():
proc = OpenOcdProcess("interface/stlink.cfg", "target/stm32f1x.cfg")
if not wait_port():
proc.stop()
pytest.fail("OpenOCD TCL Server 未在 10 秒内就绪")
yield proc
proc.stop()
subprocess.Popen 把 OpenOCD 放到后台,stdout 和 stderr 都接到管道,避免日志污染测试输出;需要看日志时可以把它们重定向到文件。wait_port 用短连接轮询 6666,连上就返回,最多等 10 秒;比硬编码 time.sleep(2) 稳,因为机器慢的时候 2 秒可能不够,机器快的时候又白等。scope="session" 表示整个测试会话只启动一次 OpenOCD,减少反复启动带来的端口冲突和调试器占用。
yield proc 之前的代码是 setup,之后的 proc.stop() 是 teardown;terminate() 发终止信号,wait() 回收子进程,避免留下僵尸进程。连接侧可以再用一个 ocd fixture 包一层 OpenOcd 客户端,把 read_memory 和 write_memory 映射到 mrw 和 mww。材料里的 Python 测试默认有这样一个封装;如果手头没有,可以先用上一节的最小 socket 客户端补一个壳,先跑通再谈封装质量。
4. 用代码开发工具做 CI/CD:烧录、硬件测试与失败退出码
4.1 烧录:program verify reset exit 四个动作
CI 里的第一步是把固件烧进去。下面这段 bash 脚本把烧录和日志保存放在一起:
bash复制#!/bin/bash
set -o pipefail
FIRMWARE="build/firmware.elf"
INTERFACE="interface/stlink.cfg"
TARGET="target/stm32f1x.cfg"
LOG_FILE="test_results.log"
echo "==== 步骤1: 烧录固件 ===="
openocd -f $INTERFACE -f $TARGET \
-c "program $FIRMWARE verify reset exit" 2>&1 | tee $LOG_FILE
if [ ${PIPESTATUS[0]} -ne 0 ]; then
echo "FATAL: 烧录失败"
exit 1
fi
program $FIRMWARE 把 ELF 文件烧进目标 Flash;verify 烧完后回读校验;reset 让目标复位;exit 让 OpenOCD 在烧录完成后退出。四个动作缺一个都可能留下麻烦:不 verify 就不知道写进去的数据对不对;不 reset 目标可能还停在调试器接管的状态;不 exit OpenOCD 会一直挂着,CI 任务不结束。
2>&1 | tee $LOG_FILE 把标准错误并到标准输出,再通过 tee 同时写到终端和日志文件。set -o pipefail 让管道中任意一个命令失败时整体返回非零,但这里真正要看的是 ${PIPESTATUS[0]},也就是 openocd 自己的退出码。PIPESTATUS 是 bash 的数组,管道执行后立刻读取才有效;中间插了别的命令,数组会被重置。烧录失败时 exit 1,让 CI 明确停在第一阶段。
4.2 测试:-f 加载 TCL 脚本并加 shutdown
烧录通过后,第二步加载测试脚本:
bash复制echo "==== 步骤2: 运行硬件测试 ===="
openocd -f $INTERFACE -f $TARGET \
-f $TEST_SCRIPT \
-c "shutdown" 2>&1 | tee -a $LOG_FILE
if [ ${PIPESTATUS[0]} -ne 0 ]; then
echo "FATAL: 硬件测试失败"
exit 2
fi
echo "==== 全部通过 ===="
exit 0
这里 -f $TEST_SCRIPT 加载上一章的 tests/hardware_test.tcl,脚本里执行断言和 test_report;-c "shutdown" 是在脚本执行完后关闭 OpenOCD,防止进程留在后台。tee -a 追加日志,保留烧录阶段的记录。测试失败时 exit 2,和烧录失败的 exit 1 区分开,CI 上看退出码就知道停在哪一步。
注意 shutdown 要放在 -c 里,而不是只依赖测试脚本末尾;有些脚本只写了断言和报告,没有显式关闭,OpenOCD 就会一直监听 6666,CI 任务看起来“卡住”。如果测试脚本本身在失败时用 return -code error 结束,OpenOCD 的退出码可能非零,外层仍然要用 ${PIPESTATUS[0]} 接住,不能假设日志里出现 FAIL 就一定会让流水线变红。
4.3 报告:pytest 与 JUnit XML
更复杂的测试场景可以用 pytest 驱动,通过 TCL RPC 控制 OpenOCD,同时生成标准化报告。下面两个用例一个读 CPUID,一个读写 SRAM:
python复制def test_cpuid(ocd):
"""验证 CPUID 寄存器"""
cpuid = ocd.read_memory(32, 0xE000ED00, 1)[0]
# Cortex-M3 的 CPUID 应为 0x411FC231
assert (cpuid & 0xFF00FFF0) == 0x4100C230
def test_sram_readwrite(ocd):
"""验证 SRAM 读写"""
test_data = [0x12345678, 0xAABBCCDD, 0x00000000, 0xFFFFFFFF]
ocd.write_memory(32, 0x20000100, test_data)
result = ocd.read_memory(32, 0x20000100, len(test_data))
assert result == test_data
ocd.read_memory(32, 0xE000ED00, 1) 里的 32 表示按 32 位宽度读,0xE000ED00 是 CPUID 地址,1 表示读一个值,返回列表后取 [0]。cpuid & 0xFF00FFF0 是掩码,用来忽略掉不参与识别的位,再和 0x4100C230 比较;不同 Cortex-M 核的 CPUID 不同,这个断言要按实际目标改,不要照抄。test_sram_readwrite 先往 0x20000100 写四个 32 位字,再原样读回比较;地址要落在目标 SRAM 范围内,别写到外设寄存器区。
运行命令带上 JUnit XML 输出:
bash复制pytest test_hardware.py -v --junitxml=report.xml
-v 让每条用例的名字和结果都打印出来;--junitxml=report.xml 生成 JUnit XML,Jenkins、GitLab CI 这类平台可以直接解析和展示。read_memory 和 write_memory 的参数含义要在封装里写清楚:第一个参数是位宽,第二个是地址,第三个是数量或值列表。如果封装内部用 mrw/mww,读回格式要按实际回显解析,不要假设空格分隔就是纯值。
5. 避坑与排查:TCL 脚本接进流水线前要拦住的五类翻车
5.1 路径、端口与进程生命周期
现象: 脚本一加载就报找不到 test_framework.tcl。
原因: source [find test_framework.tcl] 里的 find 只在 OpenOCD 的脚本搜索路径里找,当前工作目录不一定在搜索路径里。
解决: 把框架文件和用例放在同一目录,用绝对路径加载,例如 source [file join [pwd] test_framework.tcl];或者启动时先用 -f 把框架文件加载进去,再加载用例文件。路径问题不要靠猜,先把 pwd 和文件实际位置打印出来。
现象: Python 客户端偶发 Connection refused,重跑一次又好了。
原因: OpenOCD 启动后还没开始监听 6666,硬编码 time.sleep(2) 在慢机器上不够;或者上一个 OpenOCD 实例没退,端口被占。
解决: 用 wait_port 轮询 6666,连上再跑用例
