单片机与物联网 / 系统课时

安装 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 工具链。

安装前确认三个条件:

  1. 确认电脑系统与 CPU 架构,例如 Windows x64、Linux x86_64、macOS Intel 或 Apple Silicon。
  2. 确认开发板具体 MCU 型号,以及板载或外置调试探针型号,例如 ST-LINK、CMSIS-DAP 或 J-Link。
  3. 确认调试连接方式。多数 Cortex-M 开发板支持 SWD,但最终以芯片和板卡手册为准。

安装 Arm GNU Toolchain

优先使用 Arm 官方发布的 Arm GNU Toolchain,获取入口为 Arm GNU Toolchain 官方发布仓库。选择发布版本时,检查宿主系统、CPU 架构和目标三元组,不必强求某个固定版本号。Windows、Linux 和 macOS 的分发包格式可能不同。

Windows 安装

以 Windows x64 为例:

  1. 在官方发布页面选择 Windows 宿主、arm-none-eabi 目标的安装包。Arm GNU Toolchain 15.2.Rel1 起的 Windows 安装包提供 MSI 格式;旧版本可能提供 EXE 格式。
  2. 运行安装程序,记下安装目录,并确认实际包含 bin 子目录。
  3. 打开“系统属性 → 高级 → 环境变量”,编辑用户变量 Path,新增工具链的 bin 目录。
  4. 关闭并重新打开 PowerShell,执行验证命令。
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 系统可以先使用发行版仓库安装基础工具,适合快速建立实验环境:

bash
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 的终端执行:

bash
# 示例路径仅适用于相应版本及默认安装位置
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 上执行:

bash
sudo apt install -y openocd
openocd --version

预期输出:安装命令成功结束,版本检查显示 Open On-Chip Debugger 的版本信息,具体版本号随仓库变化。

在 macOS 上,可以使用 Homebrew:

bash
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。以下编译示例不需要开发板,适合排除工具链本身的问题。

bash
# 预期的目标三元组应为 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,再执行:

bash
# 仅适用于实际使用 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 示例。

GCC、GDB、OpenOCD 与 Cortex-M 调试硬件之间的连接关系

在另一个终端启动 GDB。使用官方 Arm GNU Toolchain 时执行 arm-none-eabi-gdb;使用前述 Ubuntu 仓库方案时可替换为 gdb-multiarch。

bash
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 当作常规解决方式。

对于找不到命令的问题,可以先分别检查命令路径:

bash
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 配置,而不是修改编译器选项。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安装 GCC、GDB 和 OpenOCD

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通