单片机与物联网 / 系统课时
安装 GCC、GDB 和 OpenOCD
安装 GCC、GDB 和 OpenOCD
要把 Cortex-M 裸机程序编译、烧录并停在断点上,需要先接通三套工具:Arm GNU Toolchain 负责交叉编译和调试,OpenOCD 负责连接调试探针与芯片。本篇完成安装、命令行核验和调试接口检查,得到一套可继续开发固件的环境。
学习目标
- 选择正确的 Arm GNU Toolchain 发行包,安装 GCC、GDB 和 OpenOCD。
- 验证交叉编译目标架构、工具版本及系统 PATH。
- 使用 OpenOCD 检查调试探针,并识别常见连接故障。
确认工具分工和安装前提
三套核心工具的职责如下:
| 工具 | 常用命令 | 职责 |
|---|---|---|
| GCC | arm-none-eabi-gcc |
将 C 源码编译为 Cortex-M 目标代码 |
| GDB | arm-none-eabi-gdb |
设置断点、查看寄存器和执行单步调试 |
| OpenOCD | openocd |
通过 SWD/JTAG 调试探针访问目标芯片 |
其中,arm-none-eabi 是关键目标三元组:arm 表示 Arm 架构,none 表示不依赖特定操作系统,eabi 表示嵌入式 ABI。它适用于常见 Cortex-M 裸机固件,不应误选面向 Linux 应用的 arm-linux-gnueabihf 或 aarch64-linux-gnu 工具链。
安装前确认三个条件:
- 确认电脑系统与 CPU 架构,例如 Windows x64、Linux x86_64、macOS Intel 或 Apple Silicon。
- 确认开发板具体 MCU 型号,以及板载或外置调试探针型号,例如 ST-LINK、CMSIS-DAP 或 J-Link。
- 确认调试连接方式。多数 Cortex-M 开发板支持 SWD,但最终以芯片和板卡手册为准。
安装 Arm GNU Toolchain
优先使用 Arm 官方发布的 Arm GNU Toolchain,获取入口为 Arm GNU Toolchain 官方发布仓库。选择发布版本时,检查宿主系统、CPU 架构和目标三元组,不必强求某个固定版本号。Windows、Linux 和 macOS 的分发包格式可能不同。
Windows 安装
以 Windows x64 为例:
- 在官方发布页面选择 Windows 宿主、
arm-none-eabi目标的安装包。Arm GNU Toolchain 15.2.Rel1 起的 Windows 安装包提供 MSI 格式;旧版本可能提供 EXE 格式。 - 运行安装程序,记下安装目录,并确认实际包含
bin子目录。 - 打开“系统属性 → 高级 → 环境变量”,编辑用户变量
Path,新增工具链的bin目录。 - 关闭并重新打开 PowerShell,执行验证命令。
# 确认命令解析到哪一个可执行文件
Get-Command arm-none-eabi-gcc
arm-none-eabi-gcc --version
arm-none-eabi-gdb --version预期结果:Get-Command 能找到 GCC 可执行文件,后两个命令分别输出 GCC 和 GNU gdb 的版本信息,具体版本号与安装包一致。
Ubuntu 安装
Ubuntu 或 Debian 系统可以先使用发行版仓库安装基础工具,适合快速建立实验环境:
sudo apt update
sudo apt install -y gcc-arm-none-eabi gdb-multiarch openocd
# 确认交叉编译器和多架构调试器均可执行
arm-none-eabi-gcc --version
gdb-multiarch --version预期结果:APT 成功安装软件包,两条版本检查命令正常返回版本信息。Ubuntu 软件包版本取决于发行版仓库,可能落后于 Arm 官方发布版。
这里需要注意:gdb-multiarch 是支持多种目标架构的 GDB,命令名称不是 arm-none-eabi-gdb。如果希望所有平台统一使用后者,应安装包含该程序的 Arm 官方工具链,并确保其 bin 目录位于 PATH 中。
在 Linux 上使用官方压缩包时,选择对应宿主架构的 arm-none-eabi 发行包,解压后将实际 bin 目录添加到 PATH;不要同时混用仓库 GCC 与另一套版本不兼容的工具组件。
macOS 安装
macOS 用户可选择 Arm 官方提供的匹配宿主架构的安装包。确认是 Intel x86_64 还是 Apple Silicon arm64,并选择对应的发行文件。不同发行版本的宿主架构支持和安装目录可能变化。
在安装器完成安装后,先找到真实的 bin 目录。以版本 15.2.Rel1 的默认安装路径为例,可在使用 zsh 的终端执行:
# 示例路径仅适用于相应版本及默认安装位置
export PATH="/Applications/ArmGNUToolchain/15.2.rel1/arm-none-eabi/bin:$PATH"
arm-none-eabi-gcc --version
arm-none-eabi-gdb --version预期结果:两条命令均打印版本信息。若路径不同,先查看安装器给出的实际位置再调整 PATH。确认正常后,可将对应 export PATH=... 写入 ~/.zshrc,重新打开终端生效。
安装 OpenOCD 并验证命令
OpenOCD 独立于交叉编译器安装。它需要调试探针驱动或操作系统 USB 访问权限,还需要与探针及芯片匹配的配置脚本。
在 Ubuntu 或 Debian 上执行:
sudo apt install -y openocd
openocd --version预期输出:安装命令成功结束,版本检查显示 Open On-Chip Debugger 的版本信息,具体版本号随仓库变化。
在 macOS 上,可以使用 Homebrew:
brew install open-ocd
openocd --version预期结果:Homebrew 安装完成,openocd --version 正常打印版本信息。注意 Homebrew 软件包名是 open-ocd,但可执行命令是 openocd。
Windows 用户可通过 OpenOCD 官方项目 查找安装说明,也可使用 MSYS2 对应环境的软件包。安装后确保 openocd.exe 所在目录可被终端找到。不要仅把源码仓库下载下来就当作已安装可执行程序。
安装完成后,检查 OpenOCD 自带脚本目录中是否有 interface、target 和 board 等配置目录。它们分别描述探针接口、目标芯片和预定义开发板配置。不同发行包的脚本安装位置可能不同。
核对编译目标与调试连接
先验证交叉编译器的默认目标及 Cortex-M 编译能力,再启动 OpenOCD。以下编译示例不需要开发板,适合排除工具链本身的问题。
# 预期的目标三元组应为 arm-none-eabi
arm-none-eabi-gcc -dumpmachine
printf 'int add(int a, int b) { return a + b; }\n' > test.c
arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -c test.c -o test.o
arm-none-eabi-objdump -f test.o预期结果:第一条命令返回 arm-none-eabi;编译成功生成 test.o;objdump 显示 ELF32 小端 Arm 目标文件,架构描述可能因工具链版本不同而略有区别。这里的 Cortex-M4 仅为编译测试目标,真实项目必须改为实际 MCU 内核,并正确配置 FPU 等选项。
接下来以带 ST-LINK 调试器的 STM32F4 开发板为例。先连接开发板 USB,再执行:
# 仅适用于实际使用 ST-LINK 与 STM32F4 目标的情况
openocd -f interface/stlink.cfg -c "transport select swd" -f target/stm32f4x.cfg预期结果:OpenOCD 检测到探针和目标芯片,正常情况下出现类似 Listening on port 3333 for gdb connections 的监听信息,终端会保持运行,不会立即返回命令提示符。USB 标识、目标电压、芯片 ID 和实际端口信息会因硬件及配置变化而不同。
如果使用的是 CMSIS-DAP、J-Link 或其他 MCU,必须替换成实际探针的 interface 配置和芯片对应的 target 或 board 配置,不要照搬 STM32F4 示例。

在另一个终端启动 GDB。使用官方 Arm GNU Toolchain 时执行 arm-none-eabi-gdb;使用前述 Ubuntu 仓库方案时可替换为 gdb-multiarch。
arm-none-eabi-gdb -q -ex 'target extended-remote localhost:3333' -ex 'info registers' -ex 'disconnect' -ex 'quit'预期结果:GDB 能连接到 OpenOCD,执行 info registers 时显示目标寄存器的名称和当前值,例如 r0、sp、pc 和 xpsr,随后断开连接并退出。寄存器数值取决于目标当前状态,不存在固定预期值。若 OpenOCD 没有启动或连接失败,GDB 会报告连接错误而不是显示寄存器。
处理找不到命令和连接失败
排查时按工具层级逐步定位,不要一看到 GDB 连接失败就重新安装所有软件。
| 现象 | 常见原因 | 可操作的修复 |
|---|---|---|
arm-none-eabi-gcc 找不到 |
PATH 未包含实际 bin 目录 | 检查安装路径,更新 PATH 并重启终端 |
| 找到的 GCC 版本不对 | 多套工具链发生路径竞争 | 使用 where.exe 或 which 查看命令来源,调整 PATH 顺序 |
arm-none-eabi-gdb 不存在 |
只安装了发行版的 GCC 或 GDB 命名不同 | 检查是否提供 gdb-multiarch,或安装官方 Arm GNU Toolchain |
| OpenOCD 报找不到配置文件 | 脚本路径错误或发行包不完整 | 检查脚本目录,使用匹配版本的配置文件 |
| OpenOCD 无法打开 USB 设备 | USB 驱动、线缆或访问权限问题 | 检查设备识别、驱动和 Linux udev 权限 |
| OpenOCD 检测不到目标 | MCU 未上电、SWD 接线错误或目标配置不匹配 | 核对 VTref、GND、SWDIO、SWCLK 和芯片型号 |
| GDB 连接被拒绝 | OpenOCD 未监听或端口不一致 | 检查 OpenOCD 日志中的实际 GDB 监听端口 |
Linux 下如果普通用户无法访问调试探针,应优先安装适用于探针的 udev 规则并重新登录或重新插拔设备,不应把长期使用 sudo openocd 当作常规解决方式。
对于找不到命令的问题,可以先分别检查命令路径:
command -v arm-none-eabi-gcc
command -v arm-none-eabi-gdb
command -v openocd预期结果:Linux/macOS 中已正确安装并配置 PATH 的工具会显示各自可执行文件的实际路径;未找到的命令不会输出路径,并产生非零退出状态。Ubuntu 使用 gdb-multiarch 时,应以该名称替换第二条命令。
最终验收应满足:GCC 的目标为 arm-none-eabi,GDB 能启动,OpenOCD 能加载正确探针与目标配置,连接开发板后可从 GDB 读取寄存器。如果前三项通过而硬件连接失败,应优先检查探针、权限、供电和 SWD 配置,而不是修改编译器选项。