📚 课程目录第2章调试环境搭建

2. 调试环境搭建：GDB + OpenOCD + VSCode 调试环境配置实战

说实话，很多嵌入式开发者写代码挺溜，一遇到调试就抓瞎。要么靠 printf 大法，要么插个 J-Link 用厂商 IDE 点两下。但真正到了复杂 bug 面前，这些手段往往不够用。

我个人习惯是：GDB + OpenOCD + VSCode 三件套。这套组合拳打好了，调试效率能翻一倍不止。今天我就带你把这套环境从头到尾搭起来。

核心思路：OpenOCD 负责跟调试器硬件通信，GDB 负责执行调试命令，VSCode 负责给你一个图形化界面。三个工具各司其职，缺一不可。

2.1 整体架构：三个工具怎么配合？

先别急着装软件。你得先搞清楚这三兄弟是怎么协作的。我画了张图，你看一眼就明白了。

你看，VSCode 在最上层，它通过 GDB 的 MI（Machine Interface）协议跟 GDB 通信。GDB 再通过远程调试协议连到 OpenOCD。OpenOCD 最后通过 JTAG 或 SWD 接口操作目标芯片。

小提示：如果你用的是 ST-Link，OpenOCD 原生支持。J-Link 需要额外装驱动。我建议新手先用 ST-Link 练手，坑少一些。

2.2 安装与配置：一步一步来

2.2.1 安装 OpenOCD

OpenOCD 的安装方式取决于你的操作系统。我以 Ubuntu 和 Windows 为例。

Ubuntu 下安装：

sudo apt update
sudo apt install openocd

Windows 下安装：

去 OpenOCD 官方 GitHub 下载预编译包
解压到 C:\openocd，把 C:\openocd\bin 加到系统 PATH
打开命令行，输入 openocd --version 验证

注意：Windows 下记得装驱动。ST-Link 需要 Zadig 工具把驱动换成 WinUSB 或 libusb。我曾经在这上面卡了半小时，死活连不上，最后发现是驱动没换。

2.2.2 安装 ARM 交叉编译 GDB

普通 GDB 调试不了 ARM 芯片。你得用 arm-none-eabi-gdb。

# Ubuntu
sudo apt install gdb-multiarch
# 或者
sudo apt install arm-none-eabi-gdb

# macOS
brew install arm-none-eabi-gdb

# Windows
# 从 ARM 官网下载 GNU Arm Embedded Toolchain

我个人推荐 gdb-multiarch，它支持多种架构，一个工具搞定所有。

2.2.3 配置 VSCode

VSCode 这边需要装几个插件：

插件名	作用	必装？
Cortex-Debug	ARM Cortex-M 调试支持	是
C/C++	代码补全、语法高亮	推荐
Native Debug	GDB 前端集成	可选

装好插件后，在项目根目录创建 .vscode/launch.json。这是调试配置的核心文件。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "OpenOCD Debug",
      "type": "cortex-debug",
      "request": "launch",
      "servertype": "openocd",
      "cwd": "${workspaceRoot}",
      "executable": "./build/firmware.elf",
      "device": "STM32F103C8",
      "configFiles": [
        "interface/stlink.cfg",
        "target/stm32f1x.cfg"
      ],
      "svdFile": "./STM32F103.svd",
      "runToMain": true,
      "preLaunchTask": "build"
    }
  ]
}

关键参数说明：

executable：编译出来的 .elf 文件路径，必须带调试符号（-g 选项）
configFiles：OpenOCD 的配置文件，interface 选调试器，target 选芯片
svdFile：SVD 文件，用来显示外设寄存器值，强烈建议配上
runToMain：启动后自动跑到 main 函数入口

2.3 启动调试：从零到跑起来

配置写好了，怎么启动？我一般分三步走。

2.3.1 先启动 OpenOCD

打开一个终端，手动启动 OpenOCD：

openocd -f interface/stlink.cfg -f target/stm32f1x.cfg

看到 Info : Listening on port 3333 for gdb connections 就说明成功了。

小技巧：我习惯把这条命令写成一个脚本文件 debug.sh，省得每次敲。Windows 下可以写个 debug.bat。

2.3.2 再启动 GDB

新开一个终端，连到 OpenOCD：

arm-none-eabi-gdb build/firmware.elf
(gdb) target remote localhost:3333
(gdb) monitor reset halt
(gdb) load
(gdb) continue

这几条命令的意思：

target remote：连到 OpenOCD 的 GDB 端口
monitor reset halt：复位芯片并暂停
load：把固件烧进去
continue：开始运行

2.3.3 最后用 VSCode 一键调试

在 VSCode 里按 F5，它会自动帮你做上面所有事情。你只需要在代码里打断点、看变量、单步执行。

嗯，这里要注意：第一次按 F5 之前，确保 OpenOCD 没在运行。VSCode 的 Cortex-Debug 插件会自动启动 OpenOCD，端口冲突会报错。

2.4 常见问题与避坑指南

这套环境我用了好几年，踩过的坑不少。挑几个典型的说说。

坑一：OpenOCD 连不上调试器

我曾经遇到一次，插上 ST-Link 后 OpenOCD 报 Error: open failed。查了半天，发现是 Ubuntu 的 udev 规则没配。解决方法：

sudo apt install stlink-tools
# 或者手动添加 udev 规则
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", MODE="0666"' | sudo tee /etc/udev/rules.d/99-stlink.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

坑二：GDB 报 "Remote 'g' packet reply is too long"

这个问题我印象很深。一般是芯片架构跟 GDB 配置不匹配。比如你连的是 Cortex-M4 芯片，但 OpenOCD 配置里写的是 Cortex-M3。检查 target/stm32f4x.cfg 这类文件是否选对了。

坑三：VSCode 调试时看不到变量值

说白了就是编译优化搞的鬼。你想想看，编译器把变量优化掉了，GDB 当然找不到。解决办法：编译时加 -O0 -g3，关掉优化，保留完整调试信息。

2.5 进阶技巧：让调试更顺手

基础环境搭好了，我再分享几个让调试更爽的小技巧。

2.5.1 使用 .gdbinit 文件

每次启动 GDB 都要敲那几条命令，烦不烦？在 home 目录下创建 .gdbinit 文件，把常用命令写进去：

target remote localhost:3333
monitor reset halt
load
break main
continue

这样启动 GDB 后它会自动执行这些命令，省事多了。

2.5.2 用 SVD 文件看寄存器

SVD 文件是芯片厂商提供的，里面描述了所有外设寄存器的地址和位域。配上它之后，VSCode 的 Cortex-Debug 插件可以直接显示寄存器的当前值，比看数据手册快多了。

你可以在芯片厂商官网下载 SVD 文件，或者从 CMSIS-SVD 仓库找。

2.5.3 调试脚本自动化

有些 bug 需要反复执行同样的操作。我习惯写 GDB 脚本来自动化：

# test.gdb
break UART_IRQHandler
commands
  print uart_rx_buffer[0]
  continue
end
continue

启动时加载：arm-none-eabi-gdb -x test.gdb firmware.elf

个人经验：调试脚本特别适合复现时序相关的 bug。比如每次进中断都打印某个变量，比手动按断点快十倍。

2.6 环境验证：跑一个最小测试

环境搭好了，怎么知道它能不能用？我一般写一个最简单的程序验证：

// main.c
#include "stm32f1xx.h"

int counter = 0;

int main(void) {
    while(1) {
        counter++;
        for(volatile int i = 0; i < 100000; i++);
    }
}

编译、烧录、调试。如果能在 VSCode 里看到 counter 变量在递增，说明整个链路通了。

如果看不到，按这个顺序排查：

OpenOCD 是否正常启动（看终端输出）
GDB 能否连上 OpenOCD（target remote localhost:3333）
VSCode 的 launch.json 路径是否正确
编译时是否加了 -g 选项

这套环境一旦跑通，后面调试任何嵌入式项目都会顺手很多。你想想看，不用再靠 printf 猜来猜去，直接在代码里打断点看变量，那种感觉确实不一样。