第 4 章 配置文件体系详解导读上一章我们通过三要素模型快速完成了调试连接。本章将深入 OpenOCD 配置文件的内部机制——从搜索路径与加载顺序到 interface、target、board 三层配置文件的结构解析再到 cfg 文件之间的继承与组合模式。最后我们将从零编写一块自定义开发板的完整配置文件帮助你掌握面对非标硬件时的配置能力。4.1 配置文件搜索路径与加载顺序当你在命令行执行openocd -f interface/stlink.cfg -f target/stm32f4x.cfg时OpenOCD 并不要求你给出文件的绝对路径。它会按照一套固定的优先级顺序依次搜索以下位置当前工作目录命令行-s选项指定的搜索目录add_script_search_dir命令添加的目录环境变量OPENOCD_SCRIPTS指向的目录%APPDATA%/OpenOCD仅 Windows$HOME/Library/Preferences/org.openocd仅 macOS$XDG_CONFIG_HOME/openocdLinux默认为$HOME/.config/openocd$HOME/.openocd系统级脚本目录$pkgdatadir/siteOpenOCD 自带脚本库$pkgdatadir/scripts搜索采用首次匹配原则找到第一个同名文件后立即使用不再继续搜索。这意味着你可以将自定义配置文件放在当前目录或$HOME/.openocd中来覆盖系统默认配置而无需修改安装目录下的文件。如果没有通过-f或-c指定任何配置OpenOCD 会尝试读取当前目录下的openocd.cfg文件。配置阶段与运行阶段OpenOCD 启动后首先进入配置阶段Configuration Stage此阶段可以执行 TAP 声明、Flash bank 注册、适配器设置等配置命令。配置阶段结束后进入运行阶段Run Stage此时配置命令不再可用但可以执行内存读写、Flash 编程等运行时命令。openocd -f interface/stlink.cfg -f target/stm32f4x.cfg │ │ ▼ ▼ ┌─────────────────────────────────────┐ │ 配 置 阶 段 │ │ · adapter driver 设置 │ │ · TAP 声明 (swj_newdap) │ │ · target create │ │ · flash bank 注册 │ ├─────────────────────────────────────┤ │ init 命令自动或手动 │ ├─────────────────────────────────────┤ │ 运 行 阶 段 │ │ · 验证 JTAG 扫描链 │ │ · 等待 GDB/Telnet 连接 │ │ · 执行 reset / halt / flash write │ └─────────────────────────────────────┘4.2 interface 配置详解适配器参数调优interface 配置文件负责声明调试适配器的驱动类型、USB 标识和信号布局。以下是三种常见适配器的真实配置。ST-Link# tcl/interface/stlink.cfg adapter driver st-link st-link vid_pid 0x0483 0x3744 0x0483 0x3748 0x0483 0x374b \ 0x0483 0x374d 0x0483 0x374e 0x0483 0x374f 0x0483 0x3752 \ 0x0483 0x3753 0x0483 0x3754 0x0483 0x3755 0x0483 0x3757 # 传输协议在 board 文件中选择 # transport select swd # transport select jtagST-Link 配置文件列出了 ST-LINK/V1、V2、V2-1、V3 各型号的多组 VID/PID确保各版本硬件都能被识别。注意传输协议SWD/JTAG通常不在 interface 文件中指定而是留给 board 或用户配置文件选择。CMSIS-DAP# tcl/interface/cmsis-dap.cfg adapter driver cmsis-dap # 可选指定设备序列号以区分多个适配器 # adapter serial 02200201E6661E601B98E3B9CMSIS-DAP 是 ARM 定义的标准调试协议配置最为简洁只需指定驱动名称。FTDI 系列以 Olimex ARM-USB-OCD-H 为例# tcl/interface/ftdi/olimex-arm-usb-ocd-h.cfg adapter driver ftdi ftdi device_desc Olimex OpenOCD JTAG ARM-USB-OCD-H ftdi vid_pid 0x15ba 0x002b ftdi layout_init 0x0908 0x0b1b ftdi layout_signal nSRST -oe 0x0200 ftdi layout_signal nTRST -data 0x0100 ftdi layout_signal LED -data 0x0800FTDI 适配器配置最为复杂需要通过layout_init设置 GPIO 初始状态并用layout_signal映射复位信号nSRST、nTRST到具体的 GPIO 引脚。常用适配器参数参数说明示例adapter driver驱动类型st-link,cmsis-dap,jlink,ftdiadapter speedJTAG/SWD 时钟频率kHzadapter speed 4000adapter serial指定设备序列号adapter serial ABC123transport select选择传输协议transport select swd4.3 target 配置详解TAP 声明、目标创建、工作区设置target 配置文件是三层配置中最复杂的一层它描述了芯片内部的调试架构。以stm32f1x.cfg为例逐步解析其核心结构。第一步引入辅助脚本与参数化source [find target/swj-dp.tcl] source [find mem_helper.tcl] if { [info exists CHIPNAME] } { set _CHIPNAME $CHIPNAME } else { set _CHIPNAME stm32f1x } set _ENDIAN little if { [info exists WORKAREASIZE] } { set _WORKAREASIZE $WORKAREASIZE } else { set _WORKAREASIZE 0x1000 }这段代码体现了 OpenOCD 配置文件的参数化设计外部board 文件或命令行可以通过set CHIPNAME xxx预设变量如果未设置则使用默认值。以下划线开头的变量如_CHIPNAME是 target 文件的内部变量对外不构成接口约定。第二步声明 TAPTest Access Portif { [info exists CPUTAPID] } { set _CPUTAPID $CPUTAPID } else { if { [using_jtag] } { set _CPUTAPID 0x3ba00477 } { set _CPUTAPID 0x1ba01477 } } swj_newdap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \ -expected-id $_CPUTAPID dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpuswj_newdap命令在 JTAG 扫描链上声明一个 TAP参数含义第一个参数芯片名作为 TAP 名的前缀第二个参数TAP 名称通常为cpu最终形成stm32f1x.cpu的点分名称-irlen 4指令寄存器长度为 4 位-expected-id期望的 JTAG IDCODE用于扫描链验证dap create则在 TAP 之上创建一个 DAPDebug Access Port对象供后续 target 使用。第三步创建调试目标set _TARGETNAME $_CHIPNAME.cpu target create $_TARGETNAME cortex_m -endian $_ENDIAN -dap $_CHIPNAME.dap $_TARGETNAME configure -work-area-phys 0x20000000 \ -work-area-size $_WORKAREASIZE -work-area-backup 0target create创建一个可调试目标核心参数包括目标类型cortex_m、cortex_a等、字节序和关联的 DAP。工作区work-area是芯片 SRAM 中的一段空间OpenOCD 用它来加速 Flash 编程等操作。-work-area-backup 0表示不备份工作区原内容编程速度更快。第四步Flash bank 注册与时钟配置flash bank $_CHIPNAME.flash stm32f1x 0x08000000 0 0 0 $_TARGETNAME adapter speed 1000 adapter srst delay 100 reset_config srst_nogateFlash bank 将芯片的内部 Flash 注册到 OpenOCD使其可以通过flash write_image等命令操作。adapter speed 1000将 JTAG/SWD 时钟设为 1MHz——STM32F1 复位后内部 RC 振荡器为 8MHzJTAG 时钟不应超过 CPU 时钟的 1/6。4.4 board 配置详解开发板级完整配置board 配置文件是面向最终用户的一站式配置。它通过source命令组合 interface 和 target 文件并添加板级特定参数。以 STM32F4 Discovery 为例# tcl/board/stm32f4discovery.cfg # 第一步加载板载调试器配置 source [find interface/stlink.cfg] # 第二步选择传输协议 transport select swd # 第三步覆盖 target 默认参数在 source target 之前 set WORKAREASIZE 0x10000 ;# STM32F407 有 192KB SRAM工作区扩大到 64KB # 第四步加载目标芯片配置 source [find target/stm32f4x.cfg] # 第五步板级复位配置 reset_config srst_only这个文件只有 5 行有效代码但它完成了以下工作指定了板载 ST-Link 作为调试接口选择 SWD 传输协议STM32F4 Discovery 的 ST-Link 仅引出 SWD 引脚将工作区从默认的 32KB 扩大到 64KB充分利用 STM32F407 的大 SRAM加载了 STM32F4 系列的完整 TAP/Target/Flash 配置配置复位策略为仅使用 SRST 信号用户只需一行命令即可开始工作openocd-fboard/stm32f4discovery.cfg4.5 cfg 文件的继承与组合模式OpenOCD 配置文件之间的关系可以用以下层次图表示┌──────────────────────────────────────────────────────┐ │ 用户配置文件 │ │ (openocd.cfg / 命令行) │ │ · 可覆盖任何下层变量 │ │ · 可添加项目特定的 Tcl 工具函数 │ ├──────────────────────────────────────────────────────┤ │ board/*.cfg │ │ · source interface 配置 │ │ · 设置 WORKAREASIZE / CHIPNAME 等变量 │ │ · source target 配置 │ │ · 添加 reset-init 事件处理器 │ │ · 配置外部 Flash / SDRAM │ ├──────────────┬───────────────────────────────────────┤ │ interface/*.cfg │ target/*.cfg │ │ · adapter driver│ · swj_newdap (TAP 声明) │ │ · vid_pid │ · dap create │ │ · layout_signal │ · target create │ │ │ · flash bank │ │ │ · adapter speed │ └──────────────┴───────────────────────────────────────┘变量覆盖机制OpenOCD 使用 Tcl 语言的变量机制实现配置继承。target 文件通过info exists检查变量是否已定义# target 文件中的典型模式 if { [info exists WORKAREASIZE] } { set _WORKAREASIZE $WORKAREASIZE ;# 使用外部传入的值 } else { set _WORKAREASIZE 0x1000 ;# 使用默认值 }board 文件在sourcetarget 之前设置变量即可完成覆盖# board 文件中 set WORKAREASIZE 0x10000 ;# 覆盖默认的 4KB 为 64KB source [find target/stm32f4x.cfg] ;# target 文件读到已存在的变量常用输入/输出变量变量名方向说明CHIPNAME输入芯片名称用于 TAP 和 target 的命名前缀ENDIAN输入字节序little或bigCPUTAPID输入JTAG IDCODE覆盖默认值WORKAREASIZE输入工作区大小字节FLASH_SIZE输入Flash 大小0 表示自动探测_TARGETNAME输出创建的 target 名称供 board 文件引用_CHIPNAME输出内部使用的芯片名多芯片组合一块开发板上可能包含多个芯片。board 文件可以多次设置CHIPNAME并 source 不同的 target 文件# 假设一块板子上有 PXA270 CPU 和 Xilinx FPGA set CHIPNAME network set ENDIAN big source [find target/pxa270.cfg] $_TARGETNAME configure -event reset-init { ... } set CHIPNAME xilinx unset ENDIAN source [find target/spartan3.cfg]4.6 实战从零编写一块自定义开发板的配置文件假设你手上有一块自制开发板主控为 STM32F103RCT6256KB Flash48KB SRAM板载调试器为 CMSIS-DAP通过 SWD 连接。下面从零编写其完整配置。方案一直接在命令行组合现有配置openocd-finterface/cmsis-dap.cfg\-ctransport select swd\-cset WORKAREASIZE 0x5000\-ftarget/stm32f1x.cfg这种方式无需编写任何文件适合快速验证。方案二编写 board 配置文件推荐创建myboard.cfg# myboard.cfg - 自定义 STM32F103RC 开发板配置 # 硬件STM32F103RCT6 CMSIS-DAP (SWD) # 接口配置 source [find interface/cmsis-dap.cfg] transport select swd # 目标芯片参数覆盖 # STM32F103RC: 256KB Flash, 48KB SRAM # 工作区设为 20KB为应用保留足够 SRAM set WORKAREASIZE 0x5000 # 加载目标配置 source [find target/stm32f1x.cfg] # 板级复位配置 # 板上只引出了 SWD 引脚没有 SRST 信号 # 使用软件复位 (SYSRESETREQ) reset_config none cortex_m reset_config sysresetreq # 板级初始化 $_TARGETNAME configure -event reset-init { # STM32F103 复位后使用 8MHz HSI # 配置 PLL: HSE 8MHz - PLLCLK 72MHz # RCC_CR: 启用 HSE mmw 0x40021000 0x00010000 0 # 等待 HSE 就绪 sleep 10 # RCC_CFGR: PLL 倍频 x9, HSE 作为 PLL 输入, APB1 分频 /2 mww 0x40021004 0x001D0402 # FLASH_ACR: 2 个等待周期 预取缓冲使能 mww 0x40022000 0x00000012 # RCC_CR: 启用 PLL mmw 0x40021000 0x01000000 0 sleep 10 # RCC_CFGR: 切换系统时钟到 PLL mmw 0x40021004 0x00000002 0 # 时钟已提升到 72MHz加速 SWD adapter speed 4000 } $_TARGETNAME configure -event reset-start { # 复位前降低时钟速率确保通信稳定 adapter speed 1000 }使用方式# 将 myboard.cfg 放在项目目录下直接引用openocd-fmyboard.cfg# 或放入 ~/.openocd/ 目录全局可用openocd-fmyboard.cfg调试验证启动后你应该看到类似输出Info : CMSIS-DAP: SWD supported Info : SWD DPIDR 0x1ba01477 Info : [stm32f1x.cpu] Cortex-M3 r1p1 processor detected Info : [stm32f1x.cpu] target has been examined Info : stm32f1x.flash: device id 0x20036414 Info : flash size 256 KiB如果遇到问题按以下顺序排查适配器未识别→ 检查 USB 连接和驱动安装DPIDR 不匹配→ 检查 SWD/JTAG 接线和CPUTAPID设置Flash 探测失败→ 检查WORKAREASIZE是否过大导致侵占了应用使用的 SRAMreset-init 超时→ 检查时钟配置是否与实际硬件一致HSE 频率、PLL 参数小结本章系统讲解了 OpenOCD 配置文件的完整体系搜索路径遵循 10 级优先级当前目录优先支持通过多种方式覆盖默认配置interface 文件关注适配器驱动和硬件标识不同类型适配器的复杂度差异很大target 文件是核心层通过参数化的 Tcl 脚本实现 TAP 声明、目标创建和 Flash 注册board 文件是面向用户的组合层通过变量覆盖和source命令将 interface 与 target 粘合在一起继承机制基于 Tcl 的info exists模式board 在 source target 之前设置变量即可覆盖默认值面对自定义硬件可以从现有配置文件出发逐步定制 board 文件掌握了配置文件体系你就具备了支持任意硬件平台的基础能力。下一章预告第 5 章将深入 JTAG 与 SWD 协议原理讲解扫描链、TAP 状态机、DAP 寄存器等底层概念帮助你理解 OpenOCD 配置背后的硬件逻辑。
第 4 章 配置文件体系详解（OpenOCD）
第 4 章 配置文件体系详解导读上一章我们通过三要素模型快速完成了调试连接。本章将深入 OpenOCD 配置文件的内部机制——从搜索路径与加载顺序到 interface、target、board 三层配置文件的结构解析再到 cfg 文件之间的继承与组合模式。最后我们将从零编写一块自定义开发板的完整配置文件帮助你掌握面对非标硬件时的配置能力。4.1 配置文件搜索路径与加载顺序当你在命令行执行openocd -f interface/stlink.cfg -f target/stm32f4x.cfg时OpenOCD 并不要求你给出文件的绝对路径。它会按照一套固定的优先级顺序依次搜索以下位置当前工作目录命令行-s选项指定的搜索目录add_script_search_dir命令添加的目录环境变量OPENOCD_SCRIPTS指向的目录%APPDATA%/OpenOCD仅 Windows$HOME/Library/Preferences/org.openocd仅 macOS$XDG_CONFIG_HOME/openocdLinux默认为$HOME/.config/openocd$HOME/.openocd系统级脚本目录$pkgdatadir/siteOpenOCD 自带脚本库$pkgdatadir/scripts搜索采用首次匹配原则找到第一个同名文件后立即使用不再继续搜索。这意味着你可以将自定义配置文件放在当前目录或$HOME/.openocd中来覆盖系统默认配置而无需修改安装目录下的文件。如果没有通过-f或-c指定任何配置OpenOCD 会尝试读取当前目录下的openocd.cfg文件。配置阶段与运行阶段OpenOCD 启动后首先进入配置阶段Configuration Stage此阶段可以执行 TAP 声明、Flash bank 注册、适配器设置等配置命令。配置阶段结束后进入运行阶段Run Stage此时配置命令不再可用但可以执行内存读写、Flash 编程等运行时命令。openocd -f interface/stlink.cfg -f target/stm32f4x.cfg │ │ ▼ ▼ ┌─────────────────────────────────────┐ │ 配 置 阶 段 │ │ · adapter driver 设置 │ │ · TAP 声明 (swj_newdap) │ │ · target create │ │ · flash bank 注册 │ ├─────────────────────────────────────┤ │ init 命令自动或手动 │ ├─────────────────────────────────────┤ │ 运 行 阶 段 │ │ · 验证 JTAG 扫描链 │ │ · 等待 GDB/Telnet 连接 │ │ · 执行 reset / halt / flash write │ └─────────────────────────────────────┘4.2 interface 配置详解适配器参数调优interface 配置文件负责声明调试适配器的驱动类型、USB 标识和信号布局。以下是三种常见适配器的真实配置。ST-Link# tcl/interface/stlink.cfg adapter driver st-link st-link vid_pid 0x0483 0x3744 0x0483 0x3748 0x0483 0x374b \ 0x0483 0x374d 0x0483 0x374e 0x0483 0x374f 0x0483 0x3752 \ 0x0483 0x3753 0x0483 0x3754 0x0483 0x3755 0x0483 0x3757 # 传输协议在 board 文件中选择 # transport select swd # transport select jtagST-Link 配置文件列出了 ST-LINK/V1、V2、V2-1、V3 各型号的多组 VID/PID确保各版本硬件都能被识别。注意传输协议SWD/JTAG通常不在 interface 文件中指定而是留给 board 或用户配置文件选择。CMSIS-DAP# tcl/interface/cmsis-dap.cfg adapter driver cmsis-dap # 可选指定设备序列号以区分多个适配器 # adapter serial 02200201E6661E601B98E3B9CMSIS-DAP 是 ARM 定义的标准调试协议配置最为简洁只需指定驱动名称。FTDI 系列以 Olimex ARM-USB-OCD-H 为例# tcl/interface/ftdi/olimex-arm-usb-ocd-h.cfg adapter driver ftdi ftdi device_desc Olimex OpenOCD JTAG ARM-USB-OCD-H ftdi vid_pid 0x15ba 0x002b ftdi layout_init 0x0908 0x0b1b ftdi layout_signal nSRST -oe 0x0200 ftdi layout_signal nTRST -data 0x0100 ftdi layout_signal LED -data 0x0800FTDI 适配器配置最为复杂需要通过layout_init设置 GPIO 初始状态并用layout_signal映射复位信号nSRST、nTRST到具体的 GPIO 引脚。常用适配器参数参数说明示例adapter driver驱动类型st-link,cmsis-dap,jlink,ftdiadapter speedJTAG/SWD 时钟频率kHzadapter speed 4000adapter serial指定设备序列号adapter serial ABC123transport select选择传输协议transport select swd4.3 target 配置详解TAP 声明、目标创建、工作区设置target 配置文件是三层配置中最复杂的一层它描述了芯片内部的调试架构。以stm32f1x.cfg为例逐步解析其核心结构。第一步引入辅助脚本与参数化source [find target/swj-dp.tcl] source [find mem_helper.tcl] if { [info exists CHIPNAME] } { set _CHIPNAME $CHIPNAME } else { set _CHIPNAME stm32f1x } set _ENDIAN little if { [info exists WORKAREASIZE] } { set _WORKAREASIZE $WORKAREASIZE } else { set _WORKAREASIZE 0x1000 }这段代码体现了 OpenOCD 配置文件的参数化设计外部board 文件或命令行可以通过set CHIPNAME xxx预设变量如果未设置则使用默认值。以下划线开头的变量如_CHIPNAME是 target 文件的内部变量对外不构成接口约定。第二步声明 TAPTest Access Portif { [info exists CPUTAPID] } { set _CPUTAPID $CPUTAPID } else { if { [using_jtag] } { set _CPUTAPID 0x3ba00477 } { set _CPUTAPID 0x1ba01477 } } swj_newdap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \ -expected-id $_CPUTAPID dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpuswj_newdap命令在 JTAG 扫描链上声明一个 TAP参数含义第一个参数芯片名作为 TAP 名的前缀第二个参数TAP 名称通常为cpu最终形成stm32f1x.cpu的点分名称-irlen 4指令寄存器长度为 4 位-expected-id期望的 JTAG IDCODE用于扫描链验证dap create则在 TAP 之上创建一个 DAPDebug Access Port对象供后续 target 使用。第三步创建调试目标set _TARGETNAME $_CHIPNAME.cpu target create $_TARGETNAME cortex_m -endian $_ENDIAN -dap $_CHIPNAME.dap $_TARGETNAME configure -work-area-phys 0x20000000 \ -work-area-size $_WORKAREASIZE -work-area-backup 0target create创建一个可调试目标核心参数包括目标类型cortex_m、cortex_a等、字节序和关联的 DAP。工作区work-area是芯片 SRAM 中的一段空间OpenOCD 用它来加速 Flash 编程等操作。-work-area-backup 0表示不备份工作区原内容编程速度更快。第四步Flash bank 注册与时钟配置flash bank $_CHIPNAME.flash stm32f1x 0x08000000 0 0 0 $_TARGETNAME adapter speed 1000 adapter srst delay 100 reset_config srst_nogateFlash bank 将芯片的内部 Flash 注册到 OpenOCD使其可以通过flash write_image等命令操作。adapter speed 1000将 JTAG/SWD 时钟设为 1MHz——STM32F1 复位后内部 RC 振荡器为 8MHzJTAG 时钟不应超过 CPU 时钟的 1/6。4.4 board 配置详解开发板级完整配置board 配置文件是面向最终用户的一站式配置。它通过source命令组合 interface 和 target 文件并添加板级特定参数。以 STM32F4 Discovery 为例# tcl/board/stm32f4discovery.cfg # 第一步加载板载调试器配置 source [find interface/stlink.cfg] # 第二步选择传输协议 transport select swd # 第三步覆盖 target 默认参数在 source target 之前 set WORKAREASIZE 0x10000 ;# STM32F407 有 192KB SRAM工作区扩大到 64KB # 第四步加载目标芯片配置 source [find target/stm32f4x.cfg] # 第五步板级复位配置 reset_config srst_only这个文件只有 5 行有效代码但它完成了以下工作指定了板载 ST-Link 作为调试接口选择 SWD 传输协议STM32F4 Discovery 的 ST-Link 仅引出 SWD 引脚将工作区从默认的 32KB 扩大到 64KB充分利用 STM32F407 的大 SRAM加载了 STM32F4 系列的完整 TAP/Target/Flash 配置配置复位策略为仅使用 SRST 信号用户只需一行命令即可开始工作openocd-fboard/stm32f4discovery.cfg4.5 cfg 文件的继承与组合模式OpenOCD 配置文件之间的关系可以用以下层次图表示┌──────────────────────────────────────────────────────┐ │ 用户配置文件 │ │ (openocd.cfg / 命令行) │ │ · 可覆盖任何下层变量 │ │ · 可添加项目特定的 Tcl 工具函数 │ ├──────────────────────────────────────────────────────┤ │ board/*.cfg │ │ · source interface 配置 │ │ · 设置 WORKAREASIZE / CHIPNAME 等变量 │ │ · source target 配置 │ │ · 添加 reset-init 事件处理器 │ │ · 配置外部 Flash / SDRAM │ ├──────────────┬───────────────────────────────────────┤ │ interface/*.cfg │ target/*.cfg │ │ · adapter driver│ · swj_newdap (TAP 声明) │ │ · vid_pid │ · dap create │ │ · layout_signal │ · target create │ │ │ · flash bank │ │ │ · adapter speed │ └──────────────┴───────────────────────────────────────┘变量覆盖机制OpenOCD 使用 Tcl 语言的变量机制实现配置继承。target 文件通过info exists检查变量是否已定义# target 文件中的典型模式 if { [info exists WORKAREASIZE] } { set _WORKAREASIZE $WORKAREASIZE ;# 使用外部传入的值 } else { set _WORKAREASIZE 0x1000 ;# 使用默认值 }board 文件在sourcetarget 之前设置变量即可完成覆盖# board 文件中 set WORKAREASIZE 0x10000 ;# 覆盖默认的 4KB 为 64KB source [find target/stm32f4x.cfg] ;# target 文件读到已存在的变量常用输入/输出变量变量名方向说明CHIPNAME输入芯片名称用于 TAP 和 target 的命名前缀ENDIAN输入字节序little或bigCPUTAPID输入JTAG IDCODE覆盖默认值WORKAREASIZE输入工作区大小字节FLASH_SIZE输入Flash 大小0 表示自动探测_TARGETNAME输出创建的 target 名称供 board 文件引用_CHIPNAME输出内部使用的芯片名多芯片组合一块开发板上可能包含多个芯片。board 文件可以多次设置CHIPNAME并 source 不同的 target 文件# 假设一块板子上有 PXA270 CPU 和 Xilinx FPGA set CHIPNAME network set ENDIAN big source [find target/pxa270.cfg] $_TARGETNAME configure -event reset-init { ... } set CHIPNAME xilinx unset ENDIAN source [find target/spartan3.cfg]4.6 实战从零编写一块自定义开发板的配置文件假设你手上有一块自制开发板主控为 STM32F103RCT6256KB Flash48KB SRAM板载调试器为 CMSIS-DAP通过 SWD 连接。下面从零编写其完整配置。方案一直接在命令行组合现有配置openocd-finterface/cmsis-dap.cfg\-ctransport select swd\-cset WORKAREASIZE 0x5000\-ftarget/stm32f1x.cfg这种方式无需编写任何文件适合快速验证。方案二编写 board 配置文件推荐创建myboard.cfg# myboard.cfg - 自定义 STM32F103RC 开发板配置 # 硬件STM32F103RCT6 CMSIS-DAP (SWD) # 接口配置 source [find interface/cmsis-dap.cfg] transport select swd # 目标芯片参数覆盖 # STM32F103RC: 256KB Flash, 48KB SRAM # 工作区设为 20KB为应用保留足够 SRAM set WORKAREASIZE 0x5000 # 加载目标配置 source [find target/stm32f1x.cfg] # 板级复位配置 # 板上只引出了 SWD 引脚没有 SRST 信号 # 使用软件复位 (SYSRESETREQ) reset_config none cortex_m reset_config sysresetreq # 板级初始化 $_TARGETNAME configure -event reset-init { # STM32F103 复位后使用 8MHz HSI # 配置 PLL: HSE 8MHz - PLLCLK 72MHz # RCC_CR: 启用 HSE mmw 0x40021000 0x00010000 0 # 等待 HSE 就绪 sleep 10 # RCC_CFGR: PLL 倍频 x9, HSE 作为 PLL 输入, APB1 分频 /2 mww 0x40021004 0x001D0402 # FLASH_ACR: 2 个等待周期 预取缓冲使能 mww 0x40022000 0x00000012 # RCC_CR: 启用 PLL mmw 0x40021000 0x01000000 0 sleep 10 # RCC_CFGR: 切换系统时钟到 PLL mmw 0x40021004 0x00000002 0 # 时钟已提升到 72MHz加速 SWD adapter speed 4000 } $_TARGETNAME configure -event reset-start { # 复位前降低时钟速率确保通信稳定 adapter speed 1000 }使用方式# 将 myboard.cfg 放在项目目录下直接引用openocd-fmyboard.cfg# 或放入 ~/.openocd/ 目录全局可用openocd-fmyboard.cfg调试验证启动后你应该看到类似输出Info : CMSIS-DAP: SWD supported Info : SWD DPIDR 0x1ba01477 Info : [stm32f1x.cpu] Cortex-M3 r1p1 processor detected Info : [stm32f1x.cpu] target has been examined Info : stm32f1x.flash: device id 0x20036414 Info : flash size 256 KiB如果遇到问题按以下顺序排查适配器未识别→ 检查 USB 连接和驱动安装DPIDR 不匹配→ 检查 SWD/JTAG 接线和CPUTAPID设置Flash 探测失败→ 检查WORKAREASIZE是否过大导致侵占了应用使用的 SRAMreset-init 超时→ 检查时钟配置是否与实际硬件一致HSE 频率、PLL 参数小结本章系统讲解了 OpenOCD 配置文件的完整体系搜索路径遵循 10 级优先级当前目录优先支持通过多种方式覆盖默认配置interface 文件关注适配器驱动和硬件标识不同类型适配器的复杂度差异很大target 文件是核心层通过参数化的 Tcl 脚本实现 TAP 声明、目标创建和 Flash 注册board 文件是面向用户的组合层通过变量覆盖和source命令将 interface 与 target 粘合在一起继承机制基于 Tcl 的info exists模式board 在 source target 之前设置变量即可覆盖默认值面对自定义硬件可以从现有配置文件出发逐步定制 board 文件掌握了配置文件体系你就具备了支持任意硬件平台的基础能力。下一章预告第 5 章将深入 JTAG 与 SWD 协议原理讲解扫描链、TAP 状态机、DAP 寄存器等底层概念帮助你理解 OpenOCD 配置背后的硬件逻辑。
