跳转至

嵌入式开源工具链环境配置指引

Prerequisite

Architecture: x86_64

OS: Ubuntu 22.04 Jammy

开源工具链概览

配置工具：STM32CubeMX

构建工具：Arm GNU Toolchain

编辑工具：VSCode

调试器后端/烧录工具：pyOCD/OpenOCD

调试器前端：Cortex-Debug

关于调试器后端的选择：OpenOCD支持更丰富，使用范围更广，资料更多（其实很大程度上是OpenOCD问题更多导致的……pyOCD几乎没什么问题，就没人讨论），但是技术比较老旧，经常有奇怪问题（比如连接之后看外设寄存器会报错），而且配置用的是TCL脚本，相对冷门，有额外学习成本；pyOCD更现代，使用方便，而且提供python接口（！），但是资料相对较少，且相关支持有限（比如Cortex-Debug至今没有支持以pyOCD为后端的LiveWatch）。如果你看了足够多的论坛帖子，会经常发现有人提问一个OpenOCD的问题，然后补充一句“芯片和调试器硬件不存在差错，因为我用pyOCD就没这个问题”

我更推荐pyOCD，后面的配置也会主要基于pyOCD进行（OpenOCD配置过程两千字打不住，问题太多了），如果你有闲心可以装个OpenOCD备用。

安装ARM GNU Toolchain

下载地址：

1
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

（注意：不是https://developer.arm.com/downloads/-/gnu-rm这个页面，该工具链已经deprecated）

有两个参数：Host和Target。Host指的是开发机硬件架构，Target指的是目标平台硬件架构。

对于我们的需求，选择x86_64 Linux hosted cross toolchains下的AArch32 bare-metal target (arm-none-eabi)即可。

ARM GNU Toolchain在官网只提供pre-build版本（类似Windows下的portable，也就是刚才下载的压缩包中包含完整的可执行文件），建议将压缩包直接解压到一个固定的目录（假设解压后为toolchain-directory），然后添加环境变量到.bashrc（这样每次启动终端时会自动设置环境变量）：

1
2
3
# 注意把下面的路径改成你的实际路径
echo 'export PATH="/path/to/toolchain-directory/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

测试：

1
arm-none-eabi-gcc --version

正常输出版本信息则安装成功。

安装pyOCD

1
pip3 install pyocd

安装后测试：

1
pyocd --version

正常输出版本信息则安装成功。

安装/使用STM32CubeMX

Step 0：下载安装包

为什么这会成为一个独立的步骤？需要解释一下，在2021年之后，由于出口管制等原因（说的直接一点就是制裁），已经没法直接从ST官网下载安装包（摊手），点击下载会提示如下：

We apologize for the inconvenience, but in accordance with the European Union's Export Regulation 2021/821, the US Export Administration Regulations (EAR), and other relevant rules and regulations, ST is not authorized to allow the download of this software from your country.

因此我们必须从其他地方下载。目前网上仍然能找到6.5版本的安装包，我们可以安装之后在软件内更新本体（没限制），就能用上最新版CubeMX。我已经把安装包传到了服务器上，可以自行下载。

下载地址：

1
http://43.138.83.226/package/en.stm32cubemx-lin_v6-5-0.zip

Step 1：安装

解压刚下载的zip（建议解压到一个固定位置），运行安装程序： 

1
sudo ./SetupSTM32CubeMX-6.5.0

像Windows下一样一路Next即可完成安装。装完之后，在STM32CubeMX目录下

1
./STM32CubeMX

即可启动软件。

Ubuntu下的CubeMX在高分辨率下会出现字体偏小的问题。CubeMX是GDK应用，可以通过设置GDK缩放比来解决：

1
GDK_SCALE=2 ./STM32CubeMX

Step 2：更新

Warning

为了更新软件，必须以sudo权限启动。

启动后从顶部Help 》Check Updates进入更新检查，点击Refresh获取最新版本，选中后点击Install安装即可。

安装/配置Cortex-Debug

Step 0：【可选步骤】获取SVD文件

SVD=System View Description系统视图描述文件，就是用于描述芯片寄存器映射、外设信息等系统配置的一个文本xml文件。调试插件需要svd才能获取系统信息，展示寄存器状态。如果不打算看寄存器状态，就不需要SVD文件。不同系列芯片的SVD文件不同，但是获取的方法是通用的。如果用Ozone会方便点（自带各种型号芯片的SVD），但是Cortex-Debug没这个功能，所以得自己找。

SVD文件是DFP（=Device Family Pack，芯片厂商提供的一个软件包，除了svd之外还包括HAL库/链接脚本/启动文件等硬件强相关的软件接口）的一部分。ST的DFP包（在正常情况下）通过Keil MDK Pack Installer分发，所以下面安装的时候会发现所有DFP包都有Keil前缀（摊手）。虽然DFP是为Keil定制的，但是它本质上仍然是个压缩包，可以直接解压提取出内容。

获取SVD文件的方法有多种，最简单的方法是自己下载（指路：https://github.com/Open-CMSIS-Pack），但是麻烦+不好管理，更合理的方法是使用pyOCD自带的包管理器，也就是pyocd pack命令。

我们假设目标芯片是STM32H723VGT6（其他芯片可以同理），按照以下步骤执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 先确认pyocd有内建这块芯片的dfp，找到对应的pack名称
$ pyocd pack -f h723
  Part            Vendor               Pack                 Version   Installed  
---------------------------------------------------------------------------------
  STM32H723VEHx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False      
  STM32H723VETx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False      
  STM32H723VGHx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False      
  STM32H723VGTx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False    # 此处匹配（可见pack未安装）  
  STM32H723ZEIx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False      
  STM32H723ZETx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False      
  STM32H723ZGIx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False      
  STM32H723ZGTx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.0     False
# 随后直接安装即可
$ pyocd pack -i STM32H723VGTx
Downloading packs (press Control-C to cancel):
    Keil.STM32H7xx_DFP.4.1.0
Downloading descriptors (001/001)
# 安装完成之后，对应的pack会被放在$HOME/.local/share/cmsis-pack-manager/Keil/下（$HOME是你的用户home目录）
$ cd ~/.local/share/cmsis-pack-manager/Keil
# 根据对应的pack名称（上面-f命令的输出）找到存放pack的目录。可见最终我们需要的pack名称为4.1.0.pack
$ ls && cd STM32H7xx_DFP && ls
STM32H7xx_DFP
4.1.0.pack
# 接下来我们将4.1.0.pack当作一个zip文件进行解压，并提取出其中的svd文件
$ cp 4.1.0.pack pack.zip    # 复制一份，改名为pack.zip
$ unzip pack.zip -d pack    # 解压到名为pack的目录
$ cd pack/CMSIS/SVD && ls
_htmresc             STM32H723.svd  STM32H733.svd  STM32H742.svd   STM32H745_CM4.svd  STM32H747_CM7.svd  STM32H755_CM4.svd  STM32H757_CM7.svd  STM32H7B3.svd
Release_Notes_files  STM32H725.svd  STM32H735.svd  STM32H742x.svd  STM32H745_CM7.svd  STM32H750.svd      STM32H755_CM7.svd  STM32H7A3.svd
Release_Notes.htm    STM32H730.svd  STM32H73x.svd  STM32H743.svd   STM32H747_CM4.svd  STM32H753.svd      STM32H757_CM4.svd  STM32H7B0.svd
# 该目录下的STM32H723.svd就是我们最终需要的SVD文件
# 提取完成之后，推荐把我们临时解压的pack目录和复制的pack.zip删除，避免直接操作pyOCD系统路径带来的一些问题

Step 1： 安装VSCode插件

直接在插件中心搜索Cortex-Debug安装即可。

Step 2： 配置launch.json

此时还没有创建launch.json，直接按Ctrl+Shift+D进入“运行和调试”面板点击创建即可。

Cortex-Debug支持多种server类型，包括但不限于OpenOCD、pyOCD，以及external。如果你指定了一个具体的调试器后端，Cortex-Debug会按照它的语法直接启动gdb server，然后和它通信。external意味着你需要先在外部（比如另开一个终端）启动一个gdb server，然后在VSCode按F5进调试，Cortex-Debug会通过指定端口和该server通信，完成调试。

对于pyOCD的launch.json配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "name": "pyOCD",                        // 【无需更改】显示在顶部选择框中的调试选项名称
    "cwd": "${workspaceFolder}",            // 【无需更改】当前项目工作目录
    "executable": "build/demo.elf",         // 【需要配置】编译出的ELF文件路径（相对cwd的路径）
    "request": "launch",                    // 【无需更改】
    "type": "cortex-debug",                 // 【无需更改】
    // 【无需更改】指定pyocd为gdb server（cortex-debug会按照语法自动生成启动命令）
    "servertype": "pyocd",
    // 【可选配置】svd文件存放路径
    "svdFile": "${workspaceFolder}/STM32H723.svd",
    // 【需要配置】芯片型号（和上面pyocd pack -f结果的Part部分一致）
    "targetId": "STM32H723VGTx",
    // 【需要配置】芯片的DFP包（上面提到的.pack文件）
    "cmsisPack": "/path/to/cmsis/pack"
},

对于external gdb server的launch.json配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "name": "External",             // 【无需更改】显示在顶部选择框中的调试选项名称
    "cwd": "${workspaceFolder}",    // 【无需更改】当前项目工作目录
    "executable": "build/demo.elf", // 【需要配置】编译出的ELF文件路径（相对cwd的路径）
    "request": "launch",            // 【无需更改】
    "type": "cortex-debug",         // 【无需更改】
    "servertype": "external",       // 【无需更改】指定外部gdb server
    "gdbTarget": "localhost:3333",  // 【无需更改】gdb server端口，默认为3333
    // 【需要配置】arm-none-eabi-gdb的可执行文件路径（绝对路径）
    "gdbPath" : "/path/to/arm-none-eabi-gdb/executable",
    // 【可选配置】svd文件存放路径
    "svdFile": "${workspaceFolder}/STM32H723.svd",
}

以上配置对应的gdb server启动命令（别忘了：先启动，再进调试）：

1
2
3
4
5
6
7
# 对于pyOCD
# 只需指定目标芯片型号和DFP。默认通信端口为localhost:3333，如果要更改可以通过--port指定
pyocd gdbserver --target=STM32H723VGTx  --pack=$HOME/.local/share/cmsis-pack-manager/Keil/STM32H7xx_DFP/4.1.0.pack

# 对于OpenOCD
# 如果用的不是JLink可以自己改
openocd -f interface/jlink.cfg -f target/stm32h7x.cfg

Note

截至目前（2025年7月），Cortex-Debug仍然没有支持以pyOCD为后端的LiveWatch。

【可选步骤】安装OpenOCD

推荐使用编译安装（实际上也可以用apt install直接装，但是二进制版本容易出现问题）。

Step 0：安装依赖

根据OpenOCD README内容： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
GCC or Clang is currently required to build OpenOCD. The developers
have begun to enforce strict code warnings (-Wall, -Werror, -Wextra,
and more) and use C99-specific features: inline functions, named
initializers, mixing declarations with code, and other tricks. While
it may be possible to use other compilers, they must be somewhat
modern and could require extending support to conditionally remove
GCC-specific extensions.

You'll also need:

- make
- libtool
- pkg-config >= 0.23 or pkgconf
- libjim >= 0.79

Additionally, for building from git:

- autoconf >= 2.69
- automake >= 1.14
- texinfo >= 5.0

以上提到的dependencies必须预先安装。同时，在后续编译安装的configure阶段可能出现部分依赖缺失，如果查出问题可以按照以下方法安装（如果没问题就不要输入下面的命令，防止误装两个版本）。

Note

对于编译安装的软件，可以自己选择是否保留源码目录。保留这个目录的主要目的是将来卸载（makefile文件保存了安装路径信息，将来可以通过sudo make uninstall移除），如果不打算卸载可以直接删了，如果打算保留，建议在电脑上建一个专门的目录统一存放，否则home目录会变得很乱。

1.HIDAPI

1
sudo apt install libhidapi-dev

2.jimtcl

1
2
3
4
5
git clone https://github.com/msteveb/jimtcl
cd jimtcl
./configure
make
sudo make install # 官方文档里没有这步，必须手动执行

3.libjaylink

1
2
3
4
5
6
7
git clone git://git.zapb.de/libjaylink.git
cd libjaylink
./autogen.sh
./configure
make
sudo make install
sudo ldconfig # 装完之后必须手动刷新动态链接缓存，否则openocd的配置脚本识别不到

Step 1：下载源码

源码地址：

1
https://github.com/openocd-org/openocd.git

在终端执行

1
git clone https://github.com/openocd-org/openocd.git

命令会将代码仓库clone到~/openocd

Step 2：Build from source

OpenOCD使用gnu libtools进行构建，分成4步：bootstrap -> configure -> make -> make install

Warning

注意：步骤之间有先后关系，前一个步骤执行成功后才会生成后一个步骤所需的脚本和构建产物。

按照以下步骤执行（注意configure步骤必须使能调试器）：

1
2
3
4
5
6
./bootstrap
# 以下一步需要设置使能调试器类型。
# 注意：如果此处没有使能，后续将会无法更改，必须卸载重装
./configure --enable-cmsis-dap --enable-jlink --enable-stlink
make
sudo make install

configure结束后，会输出一份configure summary，类似下面这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
OpenOCD configuration summary
---------------------------------------------------
MPSSE mode of FTDI based devices                 yes (auto)
ST-Link Programmer                               yes
TI ICDI JTAG Programmer                          yes (auto)
Keil ULINK JTAG Programmer                       yes (auto)
ANGIE Adapter                                    yes (auto)
Altera USB-Blaster II Compatible                 yes (auto)
Bitbang mode of FT232R based devices             yes (auto)
Versaloon-Link JTAG Programmer                   yes (auto)
TI XDS110 Debug Probe                            yes (auto)
OSBDM (JTAG only) Programmer                     yes (auto)
eStick/opendous JTAG Programmer                  yes (auto)
Olimex ARM-JTAG-EW Programmer                    yes (auto)
Raisonance RLink JTAG Programmer                 yes (auto)
USBProg JTAG Programmer                          yes (auto)
Espressif JTAG Programmer                        yes (auto)
CMSIS-DAP v2 compliant dongle (USB bulk)         yes (auto)
CMSIS-DAP v1 compliant dongle (HID)              yes
Nu-Link Programmer                               yes (auto)
Cypress KitProg Programmer                       yes (auto)
Altera USB-Blaster Compatible                    no
ASIX Presto Adapter                              no
OpenJTAG Adapter                                 no
Linux GPIO bitbang through libgpiod              no
CoreSight Direct Memory                          yes (auto)
Linux GPIO bitbang through sysfs                 yes (auto)
Remote Bitbang driver                            yes (auto)
SEGGER J-Link Programmer                         yes
Xilinx XVC/PCIe                                  yes (auto)
Bus Pirate                                       yes (auto)
Linux spidev driver                              yes (auto)
Cadence Virtual Debug Interface                  yes (auto)
JTAG DPI Adapter                                 yes (auto)
JTAG VPI Adapter                                 yes (auto)
BlueField SoC via rshim                          yes (auto)
Amontec JTAG-Accelerator driver                  no
Bitbanging on EP93xx-based SBCs                  no
Bitbanging on AT91RM9200-based SBCs              no
Bitbanging on BCM2835 (as found in Raspberry Pi) no
Bitbanging on NXP IMX processors                 no
Bitbanging on AM335x (as found in Beaglebones)   no
Dummy Adapter                                    yes (auto)
Use Capstone disassembly framework               no
Collect coverage using gcov                      no

如果没输出说明configure失败，可以检查最后一行输出，判断是哪个依赖缺失。

Step 3：验证

1
openocd --version

输出结果示例：

1
2
3
4
Open On-Chip Debugger 0.12.0+dev-02088-gcbc32c383 (2025-07-09-15:47)
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html