OpenOCD笔记

说明

现在我对OpenOCD有了一点了解后，我就想着针对入门级这个范围写下我的理解，分享一下有关于OpenOCD的使用方法，也算是总结和梳理。

本文的主要内容是编写cfg，并引申出与cfg文件相关的一些内容。侧重于理解和实践，希望能够帮助大家了解如下几点内容：

• 能够独立地编写和使用cfg文件
• 能够阅读和参考其他的cfg文件
• 能够在IDE和命令行环境中使用OpenOCD
• Bootloader的例子
• 能够查阅相关文档

环境： Windows 11 CLion Windows Terminal OpenOCD 0.12.0 ST-Link STM32H750VBT6

为什么没有Keil？因为Keil不用OpenOCD下代码。

OpenOCD的安装

注意： Windows
安装很简单，到Github上去下载已经被编译过的压缩包即可。
访问https://github.com/openocd-org/openocd，并按图中指引点击进去。

拉到最底下点击方框内容即可下载。将下载的压缩包解压到自己平常软件的安装位置，并将解压后的文件下的bin文件夹路径添加到环境变量中，如下：
最后保存打开控制台，输入openocd -v后能够得到如下输出：

如何使用OpenOCD

基本的流程是这样的：

1. 创建并编写后缀为cfg的文件
2. 通过控制台或者IDE使用该cfg文件将代码下载到单片机里

编写一个能用的cfg文件

cfg文件是config的缩写，指的是配置文件。OpenOCD通过该文件中的内容来将bin文件下载到单片机的FLASH中去，也可以细致地指定代码在实际Flash中的位置，以及要不要在下载后复位等。

最简单的cfg文件代表仅仅只有下载需求，即代码能够下载到单片机的内部flash中去。那只要确定好两个步骤即可：

1. 确定自己的下载器类型
2. 确定自己的开发板型号

然后就可以得到这样的cfg文件，简单的下载需求是没有问题的：

source [find interface/stlink.cfg]
source [find target/stm32h7x.cfg]

interface/stlink.cfg和target/stm32h7x.cfg处于OpenOCD的安装目录下面share\openocd
打开interface这个目录可以看到有很多的配置文件，比如jlink.cfg cmsis-dap.cfg等，我们要根据自己的下载器来引用不同的配置文件。
而target目录下面则是厂家的芯片配置文件，也是要根据具体的单片机来引用。

使用OpenOCD进行下载

在CLion中下载

CLion提供了相关的图形化的界面让你点击绿色的三角就可以编译代码并按照cfg文件的描述进行下载。

如何在CLion中搭建这样的开发环境呢？可以参考这一篇博客配置CLion用于STM32开发【优雅の嵌入式开发】

在Terminal中下载

首先还是要输入openocd -v确保OpenOCD已经添加到了环境变量中，不然输入了半天发现没有添加到环境中就搞笑了。
然后执行类似于如下的命令即可将代码下载到单片机中去

openocd -f dmeo.cfg -c "program dmeo.bin 0x08000000 exit resert"

乍一看复杂得很，但其实每一个命令都是有意义的。上面的命令执行可能还是会有一点问题：

1. cfg文件路径要指明清楚
2. 执行命令前，要确保电脑和下载器连接好了，下载器也要和单片机连接好
3. demo.bin指的是你要下载到单片机里的文件，可能存在路径和权限问题
4. 0x80000000可能并不适用于你的单片机，要根据实际情况修改

基本命令选项——file

在解决以上问题之前，先大致了解一下-f和-c这两个基本的命令选项起到了一些什么样的作用：

openocd -f path\to\xxx.cfg

这个命令选项可以给OpenOCD指定配置文件，比如我们的例子：

openocd -f demo.cfg

可以使用多个-f联合使用多个cfg文件。比如上面的demo.cfg实际上是引用了stlink.cfg和stm32h7x.cfg这两个文件，因此也可以这样：

openocd -f interface\stlink.cfg -f target\stm32h7x.cfg

去掉interface或者target行不行？回答是不行，OpenOCD会找不到文件而报错退出。

基本命令选项——command

如果总结-f后面紧跟的是cfg文件的话，那-c后面紧跟着的就是命令。-c后program是一条下载命令，它需要你提供文件地址以及下载偏移，文件地址好理解，你要下载某一份代码，总要给人家地址。而偏移则是指的是你要下载到单片机里的具体位置，不知道没关系，先缺省着，执行没有上述示例的0x080000000即

openocd -f interface\stlink.cfg -f target\stm32h7x.cfg -c "program demo.bin exit reset"

然后你会得到如下信息：
这个信息就告诉了你要下载的单片机的代码存放地址是哪里，然后按照它给的信息填写到上方的命令中即可。

除此之外，program命令还提供一些可选的需求：比如执行后命令后退不退出OpenOCD、程序下载到单片机以后单片机复位不复位，以及要不要对下载到单片机里边的数据和电脑上的bin文件进行校验等。一般来说reset和exit就足够，分别对应着单片机复位、退出OpenOCD。退出OpenOCD这一条后面会有解释。

实际的用法展示

所以在E:\demo这个目录下，我实际要执行的命令是：

openocd -f interface\stlink.cfg -f target\stm32h7x.cfg -c "program cmake-build-debug-arm/Bootloader.bin 0x08000000 exit reset"

其中cmake-build-debug-arm/为demo的子目录，编译后的文件就在其中，如果你的Terminal路径在C盘，并且想要下载其他盘符下的文件，那么就需要给出要下载的文件的完整路径，这一点十分重要。

如何编写更加复杂的cfg文件

复杂这个概念是要根据需求来的，如果你觉得普通的下载不能满需求的时候，复杂就随之而来。我有一个需求就是Bootloader，有两种情况，第一种较为简单，就是想要将代码下载到内部Flash中特定的位置上，相当于将内部Flash划分成两个部分。第二种则是要将代码下载到外部的Flash中。

内部FLASH的Bootloader

在OpenOCD中实现很简单，按照上述的下载方式调用program命令，并指定你要下载的位置即可，比如上面写的是0x08000000，但是这是最开始的地址，如果你想把代码写入到128K的中间位置，前64KB给做跳转程序，后64KB来做跳转后的运行程序，那么就应该修改下载的地址，将0x08000000改为0x08010000：

openocd -f interface\stlink.cfg -f target\stm32h7x.cfg -c "program cmake-build-debug-arm/Bootloader.bin 0x08010000 exit reset"

这就可以将代码下载到0x08010000这个位置，也就是64KB处。这好像和cfg文件没有任何关系，仍然还是命令行的方式，但实际上，我们是可以将这些命令写入到cfg文件中的，最后能够得到的文件如下：

source [find interface/stlink.cfg]
source [find target/stm32h7x.cfg]

set FILENAME "E:/demo/cmake-build-debug-arm/Bootloader.bin"
program $FILENAME 0x08010000 exit reset

其中set代表给FILENAME这个变量设置值，也要注意引用路径的时候，要使用斜杠，也就是/。

外部FLASH的Bootloader

外部FLASH中考虑的东西相对较多，但从理解上讲无非只是步骤麻烦了点。我也写过针对STM32H750VBT6这款芯片的外部Bootloader的实现的文章，并提供了代码，放在了Github上。在CLion上实现STM32H750VBT6的Bootloader.md

查看已有的cfg文件示例

cfg文件用到的是TCL脚本的语法，但也没有必要专门去学TCL脚本是怎么编写的，因为OpenOCD的文件里都自带了相当数量的cfg文件，有什么不会的可以直接进行参考。你可能会问cfg文件那么多，要看哪个？我总结了两点：

1. 根据自己的芯片型号查看同型号的cfg文件
2. 如果是某一个具体的命令的用法那就通过findstr或者grep命令查找对应的关键字。

比如在Windows下可以通过findstr进行字符串的查找write_image的用法，不会写findstr的查找内容也没关系，问问ChatGPT，它能给出很有用的回复。

findstr /s /c "write_image" *.cfg

同时也要理解一些TCL语法，比如proc``set等看多了就知道是什么意思了。proc声明函数，set声明变量……

如何查阅OpenOCD的文档

查阅文档很简单，首先你要对OpenOCD有一个很基本的认识，然后明白自己的需求，查找对应的关键字即可，虽然这样做有点笨，因为有时候关键字实在是太多了。也可以问问ChatGPT、看看其他的博客。

但读手册是一定可以找到答案的。

通过命令行查看更多的信息

OpenOCD是支持远程调试的，当然也可以使用本地进行调试，在执行下面的命令后，OpenOCD就会等待连接：

openocd -f interface\stlink.cfg -f target\stm32h7x.cfg

所以之前提到的退出OpenOCD，指的是终止OpenOCD响应连接。所以如果你的cfg文件中存在exit相关的命令，就不会进入到OpenOCD的远程调试模式中。
我们怎么连接呢？只需要重新打开一个终端，输入telnet localhost 4444可以进入到调试界面。

可以输入halt reset flash banks等命令查看相应的信息，也可以使用flash write_image进行下载。至于怎么知道这些命令，则需要查看OpenOCD的文档了。

其他问题

单片机锁住了

OpenOCD下载导致单片机被锁住解决办法， stm32f1x.cpu – clearing lockup after double fault target_stm32 cpu lockup

为什么要使用OpenOCD

我觉得这也是一个需求的问题，如果你经常使用Keil做ARM芯片的相关开发，那么OpenOCD完全是没有必要的。但是如果你想在其他环境中，比如各种IDE或者命令行中开发ARM和非ARM芯片，应该或多或少会接触到OpenOCD。