3. 配置文件基础：OpenOCD 配置文件的语法、结构与调试开关

说实话，我刚接触 OpenOCD 那会儿，最头疼的就是它的配置文件。一堆 source、adapter、target 命令，看着像脚本又不像脚本。后来摸透了才发现，这东西的语法其实很单纯，结构也固定。你只要搞懂它怎么组织，后面写配置就跟填空一样简单。

3.1 配置文件语法：Tcl 的子集

OpenOCD 的配置文件用的是 Tcl 语言的一个子集。说白了，就是 Tcl 的简化版。你不用学完整 Tcl，记住几条规则就够了。

• 命令 + 参数：每条配置都是一条命令，后面跟参数。比如 adapter speed 1000，adapter 是命令，speed 和 1000 是参数。
• 空格分隔：命令和参数之间用空格隔开。参数里如果有空格，用花括号 {} 包起来。
• 换行结束：每条命令独占一行，换行就是结束。想跨行写？用反斜杠 \ 续行。
• 变量与替换：可以用 $变量名 引用变量，用 [命令] 做命令替换。不过初学者先别碰这个，容易绕晕。

3.2 注释：给未来的自己留条活路

我有个坏习惯，以前写配置从不加注释。直到有一次，三个月后回头调一个老项目，看着几百行配置完全想不起来当时为什么那么写……嗯，从那以后我每条关键配置都加注释。

OpenOCD 支持两种注释方式：

语法	说明	示例
#	单行注释，从 # 到行尾	# 设置 JTAG 频率为 1MHz
if 0 { ... }	多行注释块，条件永远为假	if 0 { 这段不会执行 }

3.3 配置文件结构：三层架构

OpenOCD 的配置文件分成三层：interface、target、board。你想想看，这其实对应了调试链路的三个环节：调试器 → 目标芯片 → 开发板。

我画了张图，帮你理清这三层的关系：

3.4 interface 层：告诉 OpenOCD 你用啥调试器

interface 文件定义的是调试器硬件。比如你用 J-Link、ST-Link、FTDI 还是 CMSIS-DAP。每个调试器有自己的通信协议和引脚定义。

一个典型的 interface 配置长这样：

# interface/stlink.cfg
adapter driver hla
hla_layout stlink
hla_device_desc "ST-Link/V2"
hla_vid_pid 0x0483 0x3748

# 设置 JTAG/SWD 频率
adapter speed 1000

3.5 target 层：告诉 OpenOCD 你在调啥芯片

target 文件定义的是目标芯片的内核、内存映射、复位方式等。不同厂商的芯片，即使内核一样（比如都是 Cortex-M4），配置也可能差很多。

举个例子，STM32F4 的 target 配置：

# target/stm32f4x.cfg
set CHIPNAME stm32f4x
set ENDIAN little

# 创建目标
target create $_CHIPNAME.cpu cortex_m -endian $_ENDIAN -chain-position $_CHIPNAME.cpu

# 设置工作区（用于下载算法）
$_CHIPNAME.cpu configure -work-area-phys 0x20000000 -work-area-size 0x10000

# 设置复位配置
reset_config srst_only srst_nogate

这里有个关键点：target create 命令的 -chain-position 参数指定了目标在 JTAG 链上的位置。单核芯片通常就是 $_CHIPNAME.cpu。多核芯片需要指定序号。

3.6 board 层：把一切串起来

board 文件是最高层，它把 interface 和 target 组合在一起，再加上板级特有的配置。比如板上的复位电路、LED 指示、额外的内存等。

一个完整的 board 配置示例：

# board/stm32f4discovery.cfg
source [find interface/stlink.cfg]
source [find target/stm32f4x.cfg]

# 板级复位配置
reset_config srst_only

# 板级初始化脚本
proc init_board { } {
    # 设置调试器电压
    adapter assert srst
    sleep 10
    adapter deassert srst
}

# 板级特定命令
flash bank stm32f4x.flash stm32f4x 0x08000000 0x100000 2 4 $_CHIPNAME.cpu

看到没？board 文件用 source 命令把前两层拉进来，然后加自己的东西。这样设计的好处是：换一块板子，只要改 board 文件就行，interface 和 target 可以复用。

3.7 调试开关：让 OpenOCD 开口说话

配置写好了，但 OpenOCD 到底在执行什么？这时候就需要调试开关了。我个人习惯在调试阶段把日志级别开到最大，等稳定了再降下来。

OpenOCD 的调试开关分两种：

开关	作用	推荐场景
debug_level N	设置调试信息详细程度（0-3）	0=仅错误，1=警告，2=信息，3=详细调试
log_output 文件路径	将日志输出到文件	调试复杂问题时记录完整日志

在配置文件中设置：

# 开启详细调试
debug_level 3

# 同时输出到文件
log_output openocd_debug.log

也可以在命令行启动时指定：

openocd -f board/stm32f4discovery.cfg -d 3 -l debug.log

3.8 一个完整的配置示例

最后，给你看一个我实际项目里用过的完整配置。这是一个 STM32F407 的开发板，用 J-Link 调试：

# board/my_stm32f407.cfg
# 作者：我
# 日期：2024-03-15
# 说明：STM32F407 + J-Link 调试配置

# ===== 调试器配置 =====
source [find interface/jlink.cfg]
adapter speed 1000

# ===== 目标芯片配置 =====
source [find target/stm32f4x.cfg]

# ===== 板级特定配置 =====
reset_config srst_only

# 板级初始化
init_board

# 调试开关
debug_level 2
log_output debug.log

# 自定义命令：复位并暂停
proc reset_halt { } {
    reset halt
    sleep 100
}

这个配置我用了大半年，基本没出过问题。你拿过去改改芯片型号和调试器类型，就能直接用在你的板子上。