4. OpenOCD 配置文件结构：语法基础、变量、过程与执行流程

配置文件是 OpenOCD 的灵魂。说白了，你调试什么芯片、用什么调试器、怎么操作，全得靠它告诉 OpenOCD。我刚开始接触 OpenOCD 时，总觉得配置文件就是一堆命令的堆砌，后来踩了不少坑才明白——它的结构其实很清晰，而且非常灵活。

这一节，我们就来拆解 OpenOCD 配置文件的骨架。你掌握了这些，后面写自己的配置就顺手多了。

4.1 配置文件语法基础

OpenOCD 的配置文件其实是一种脚本语言。它的语法非常简洁，没有花括号，没有分号，全靠换行和缩进来组织。嗯，有点像 Tcl 的简化版——实际上它就是基于 Tcl 的。

4.1.1 注释与空白

注释用 # 开头，整行都是注释。空行会被忽略。我个人习惯在每个配置段前面加一段注释，说明这段是干什么的，方便以后回头看。

# 这是注释
# 设置调试器接口
adapter driver jlink

# 空行分隔不同配置段
source [find interface/jlink.cfg]

4.1.2 命令与参数

每行一个命令，命令后面跟参数。参数之间用空格分隔。如果参数本身包含空格，用双引号括起来。

# 命令 参数1 参数2 ...
set CHIPNAME stm32f407
target create $_CHIPNAME.cpu cortex_m -endian little

4.1.3 续行

一行写不下？用反斜杠 \ 续行。不过我个人建议尽量别用，一行写一个命令最清晰。实在要续行，注意反斜杠后面不能有空格。

# 续行示例（不推荐，但有时需要）
flash bank $_FLASHNAME stm32f4x 0x08000000 0x100000 \
    2 4 $_TARGETNAME

4.2 变量定义与使用

变量是配置文件的精髓。没有变量，你每次换芯片都得改一堆地方。有了变量，改一个值就行。

4.2.1 定义变量

用 set 命令定义变量。变量名习惯用大写，加下划线分隔。我个人喜欢在文件开头把所有变量集中定义，像 C 语言的宏定义一样。

# 定义变量
set CHIPNAME stm32f407
set CPUTAPID 0x4ba00477
set FLASH_SIZE 0x100000

4.2.2 使用变量

用 $_变量名 引用变量。注意前面的 $ 符号不能少。

# 使用变量
set _TARGETNAME $_CHIPNAME.cpu
target create $_TARGETNAME cortex_m -endian little

4.2.3 变量作用域

变量默认是全局的。但如果你在 proc 过程里用 set，默认是局部变量。想改全局变量，得加 global 关键字。

4.3 proc 过程定义

proc 是 OpenOCD 的“函数”。你可以把一组操作封装起来，重复调用。这在复杂调试流程里特别有用。

4.3.1 定义 proc

语法很简单：proc 过程名 {参数列表} { 过程体 }。注意过程体用花括号括起来，可以跨多行。

# 定义一个简单的复位过程
proc my_reset {} {
    echo "执行自定义复位..."
    reset halt
    echo "复位完成"
}

# 带参数的过程
proc flash_and_run {filename} {
    echo "正在烧录: $filename"
    program $filename 0x08000000 verify
    resume
}

4.3.2 调用 proc

直接写过程名加参数就行，跟普通命令一样。

# 调用过程
my_reset
flash_and_run "my_firmware.bin"

4.3.3 proc 的返回值

用 return 返回结果。不写 return 的话，最后一条命令的结果就是返回值。

proc get_chip_id {} {
    set id [mrw 0xE0042000]
    return $id
}

# 使用返回值
set chip_id [get_chip_id]
echo "芯片ID: $chip_id"

4.4 脚本执行流程

OpenOCD 启动时，配置文件的执行顺序是有讲究的。搞错了顺序，可能连调试器都连不上。

4.4.1 执行顺序

OpenOCD 按以下顺序处理配置：

1. 命令行参数：-f 指定的配置文件，按顺序执行
2. 接口配置：先加载调试器驱动（如 jlink.cfg）
3. 目标配置：再加载目标芯片配置（如 stm32f4x.cfg）
4. 板级配置：最后加载板级特定配置（如 board.cfg）
5. 用户命令：如果命令行有 -c 参数，最后执行

为什么会这样？因为接口配置必须先于目标配置——你得先告诉 OpenOCD 用什么调试器，它才能去连接目标芯片。

4.4.2 source 命令

source 命令用来包含其他配置文件。它会在当前位置插入被包含文件的内容。

# 先加载接口配置
source [find interface/jlink.cfg]

# 再加载目标配置
source [find target/stm32f4x.cfg]

# 最后加载板级配置
source [find board/stm32f4discovery.cfg]

[find ...] 是 OpenOCD 的搜索机制，它会在安装目录的 scripts 子目录里找文件。我个人建议尽量用 find，而不是写绝对路径，这样配置文件移植性更好。

4.4.3 init 与 reset

配置加载完后，OpenOCD 会自动执行 init 和 reset init。但如果你在配置文件里手动调用了 init，后面的配置就不会再执行了。嗯，这是个容易忽略的点。

4.5 知识结构总览

下面这张图把配置文件的核心结构串起来了。你可以把它当作一个快速参考。

4.6 实战建议

最后，分享几个我在项目中积累的经验：

• 变量命名要规范：我习惯用 CHIPNAME、TAPID、FLASH_BASE 这种全大写加下划线的风格，一看就知道是变量。
• proc 要短小精悍：一个 proc 只做一件事。比如“擦除”、“烧录”、“复位”分开定义，组合使用。
• 配置文件分层：接口配置、目标配置、板级配置分开写，用 source 组合。这样换芯片时只需要改目标配置那一层。
• 调试时多用 echo：在 proc 里加 echo 输出，能帮你快速定位问题。我经常在关键步骤前后打印状态。