ZephyrOS 嵌入式开发Black Pill V1.2之Debug调试器

版本和环境信息如下：

PC平台： Windows 11 专业版

Zephyr开发环境：v4.1.0 Windows 下搭建 Zephyr 开发环境

WeAct BlackPill V1.2开发板： WeAct STM32F411CEU6 BlackPill 核心板

Debug调试器：

ST-LINK V2: ST-LINK V2 STM8/STM32仿真器

J-LINK 克隆调试器：JLINK V9.5 ARM仿真器

BlackMagicProbe(BMP) 开源调试器：WeAct STM32F103CBT6 BluePill 核心板

调试器安装软件：

dfu-util工具：dfu-util-0.11-binaries

ST-LINK V2：

ST官网stsw-link007下载 ST-LINK V2固件更新工具

stlink tools-1.8.0

J-LINK V9.5克隆调试器：

JLink_Windows_V758_x86_64.exe V7.58以上版本均有防clone盗版功能。

OpenOCD: xpack-openocd-0.12.0-6-win32-x64.zip

ARM GDB: xpack-arm-none-eabi-gcc-14.2.1-1.1-win32-x64.zip

参考文档：

Black Pill V1.2 — Zephyr Project Documentation

1. 背景

WeAct Black Pill V1.2开发板是一款基于STM32F401CC芯片的超低成本精简型开发板（详见STM32F401CC官网[5]）。该板采用STM32F401x系列的48引脚版本（参见STM32F401x参考手册[6]），WeAct的GitHub页面[2]。

2. 硬件信息

基于STM32F401CC芯片的Black Pill V3.0+开发板提供以下硬件组件：

• STM32F401CCU6 in UFQFPN48 package

• ARM® 32-bit Cortex® -M4 CPU with FPU

• 84 MHz max CPU frequency

• VDD from 1.7 V to 3.6 V

• 256 KB Flash

• 64 KB SRAM

• GPIO with external interrupt capability

• 1x12-bit, 2.4 MSPS ADC with 16 channels

• DMA Controller

• Up to 11 Timers (six 16-bit, two 32-bit, two watchdog timers and a SysTick timer)

• USART/UART (3)

• I2C (3)

• SPI/I2S (5)

• SDIO

• USB 2.0 full-speed device/host/OTG controller with on-chip PHY

• CRC calculation unit

• 96-bit unique ID

• RTC

3. 管脚分布信息：

 4. Zephyr默认外设映射

• UART_1 TX/RX : PA9/PA10

• I2C1 SCL/SDA : PB8/PB9

• SPI1 CS/SCK/MISO/MOSI : PA4/PA5/PA6/PA7 (Routed to footprint for external flash)

• PWM_4_CH1 : PB6

• PWM_4_CH2 : PB7

• ADC_1 : PA1

• USER_PB : PA0

• USER_LED : PC13

 5. 烧录与调试

BlackPill_F401CC开发板支持以下运行器（runners）及对应的west命令：

	flash	debug	debugserver	rtt	attach
blackmagicprobe	✅	✅			✅
dfu-util	✅ (default)
jlink	✅	✅	✅	✅	✅
openocd	✅	✅ (default)	✅	✅	✅

 5.1 DFU-Util工具

Zephyr对应BlackPill_F401CC项目默认使用dfu-util烧录。

连接USB-C数据线后，开发板将自动上电。强制进入DFU模式的操作方法：保持BOOT0开关按压状态，同时短按NRST开关后立即释放。

设备管理器里能看到"STM32 BOOTLOADER",说明F401进入到DFU下载模式。

解压dfu-util-0.11-binaries至zephyr-sdk目录下：

解压好后设置系统环境变量

将dfu-util的win64执行程序路径添加在系统变量里。

设置好后打开cmd终端

# 检查dfu-util工具是否安装成功(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>dfu-util --list
dfu-util 0.11Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2021 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/Found DFU: [0483:df11] ver=2200, devnum=9, cfg=1, intf=0, path="1-8.3", alt=3, name="@Device Feature/0xFFFF0000/01*004 e", serial="337033863133"
Found DFU: [0483:df11] ver=2200, devnum=9, cfg=1, intf=0, path="1-8.3", alt=2, name="@OTP Memory /0x1FFF7800/01*512 e,01*016 e", serial="337033863133"
Found DFU: [0483:df11] ver=2200, devnum=9, cfg=1, intf=0, path="1-8.3", alt=1, name="@Option Bytes  /0x1FFFC000/01*016 e", serial="337033863133"
Found DFU: [0483:df11] ver=2200, devnum=9, cfg=1, intf=0, path="1-8.3", alt=0, name="@Internal Flash  /0x08000000/04*016Kg,01*064Kg,03*128Kg", serial="337033863133"

使用west flash烧录 

(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>west flash
-- west flash: rebuilding
ninja: no work to do.
-- west flash: using runner dfu-util
dfu-util 0.11Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2021 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/Warning: Invalid DFU suffix signature
A valid DFU suffix will be required in a future dfu-util release
Opening DFU capable USB device...
Device ID 0483:df11
Device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Interface #0 ...
Determining device status...
DFU state(10) = dfuERROR, status(10) = Device's firmware is corrupt. It cannot return to run-time (non-DFU) operations
Clearing status
Determining device status...
DFU state(2) = dfuIDLE, status(0) = No error condition is present
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash  "
Downloading element to address = 0x08000000, size = 15992
Erase           [=========================] 100%        15992 bytes
Erase    done.
Download        [=========================] 100%        15992 bytes
Download done.
File downloaded successfully
Submitting leave request...
Transitioning to dfuMANIFEST state(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>

5.2 ST-LINK V2 + OpenOCD + GDB工具

首先淘宝购买ST-LINK V2 STM8/STM32仿真器固件比较旧，zephyr使用stlink检测固件会报错，需要先更新ST-LINK为最新版本。

去ST官网下载 stsw-link007

ST-Link 与 STM32F401CC 接线

ST-Link 引脚	STM32F401CC 引脚	备注
SWDIO	PA13	必须连接
SWCLK	PA14	必须连接
GND	GND	必须连接
RST	R	必须连接

下载 openocd-0.12.0-6至zephyr-sdk

解压好后设置系统环境变量

将openocd的bin执行程序路径添加在系统变量里。 

下载arm-none-eabi-gcc-14.2.1至zephyr-sdk

将arm-none-eabi-gdb.exe的bin执行程序路径添加在系统变量里。 

创建一个stm32f4.cfg的Tcl文件

# 选择 ST-Link 调试器
source [find interface/stlink.cfg]# 选择 SWD 协议
transport select dapdirect_swd# 目标芯片配置
source [find target/stm32f4x.cfg]reset_config srst_only

 设置好后打开cmd终端, 验证openocd是否运行正常。

(.venv) D:\workspace\zephyrproject\zephyr-project>openocd -f stm32f4.cfg
xPack Open On-Chip Debugger 0.12.0+dev-01850-geb6f2745b-dirty (2025-02-07-10:08)
Licensed under GNU GPL v2
For bug reports, readhttp://openocd.org/doc/doxygen/bugs.html
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : STLINK V2J46S7 (API v2) VID:PID 0483:3748
Info : Target voltage: 3.232653
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : clock speed 1800 kHz
Info : stlink_dap_op_connect(connect)
Info : SWD DPIDR 0x2ba01477
Error: Failed to read memory at 0xe000ed04
Error: [stm32f4x.cpu] Examination failed
Warn : target stm32f4x.cpu examination failed
Info : [stm32f4x.cpu] starting gdb server on 3333
Info : Listening on port 3333 for gdb connections

OpenOCD刷写命令

# 完全擦除
openocd.exe -f stm32f4.cfg -c "init; reset halt; stm32f4x mass_erase 0; exit"
# 烧写ELF文件
openocd -f stm32f4.cfg -c "program zephyr.elf verify reset exit"
#烧写Binary文件
openocd -f stm32f4.cfg -c "program zephyr.bin verify reset exit 0x08000000"

Zephyr使用OpenOCD方式烧录 

(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>west flash --runner openocd
-- west flash: rebuilding
ninja: no work to do.
-- west flash: using runner openocd
-- runners.openocd: Flashing file: D:/workspace/zephyrproject/zephyr-project/zephyr/build/zephyr/zephyr.hex
xPack Open On-Chip Debugger 0.12.0+dev-01850-geb6f2745b-dirty (2025-02-07-10:08)
Licensed under GNU GPL v2
For bug reports, readhttp://openocd.org/doc/doxygen/bugs.html
Info : STLINK V2J46S7 (API v2) VID:PID 0483:3748
Info : Target voltage: 3.212066
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : clock speed 1800 kHz
Info : stlink_dap_op_connect(connect)
Info : SWD DPIDR 0x2ba01477
Info : [stm32f4x.cpu] Cortex-M4 r0p1 processor detected
Info : [stm32f4x.cpu] target has 6 breakpoints, 4 watchpoints
Info : [stm32f4x.cpu] Examination succeed
Info : [stm32f4x.cpu] starting gdb server on 3333
Info : Listening on port 3333 for gdb connectionsTargetName         Type       Endian TapName            State
--  ------------------ ---------- ------ ------------------ ------------0* stm32f4x.cpu       cortex_m   little stm32f4x.cpu       unknown
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
[stm32f4x.cpu] halted due to breakpoint, current mode: Thread
xPSR: 0x61000000 pc: 0x2000002e msp: 0x20000c00
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : device id = 0x10016433
Info : flash size = 384 KiB
auto erase enabled
wrote 16384 bytes from file D:/workspace/zephyrproject/zephyr-project/zephyr/build/zephyr/zephyr.hex in 0.592510s (27.004 KiB/s)
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
[stm32f4x.cpu] halted due to breakpoint, current mode: Thread
xPSR: 0x61000000 pc: 0x20000044 msp: 0x20000c00
shutdown command invoked

注意 OpenOCD 0.12.0版本

.\zephyr-project\zephyr\boards\weact\blackpill_f401cc\support\openocd.cfg

source [find interface/stlink.cfg]# OpenOCD V0.11.0
# transport select hla_swd
# OpenOCD V0.12.0
transport select dapdirect_swdsource [find target/stm32f4x.cfg]reset_config srst_only$_TARGETNAME configure -event gdb-attach {echo "Debugger attaching: halting execution"reset haltgdb_breakpoint_override hard
}$_TARGETNAME configure -event gdb-detach {echo "Debugger detaching: resuming execution"resume
}

Zephyr项目west flash --runner openocd命令，指定使用openocd的方式。

注意执行命令后，同时短按NRST开关后立即释放。

(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>west flash --runner openocd
-- west flash: rebuilding
ninja: no work to do.
-- west flash: using runner openocd
-- runners.openocd: Flashing file: D:/workspace/zephyrproject/zephyr-project/zephyr/build/zephyr/zephyr.hex
Open On-Chip Debugger 0.11.0 (2021-11-18) [https://github.com/sysprogs/openocd]
Licensed under GNU GPL v2
libusb1 09e75e98b4d9ea7909e8837b7a3f00dda4589dc3
For bug reports, readhttp://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : clock speed 2000 kHz
Info : STLINK V2J46S7 (API v2) VID:PID 0483:3748
Info : Target voltage: 3.221593
Info : stm32f4x.cpu: Cortex-M4 r0p1 processor detected
Info : stm32f4x.cpu: target has 6 breakpoints, 4 watchpoints
Info : starting gdb server for stm32f4x.cpu on 3333
Info : Listening on port 3333 for gdb connectionsTargetName         Type       Endian TapName            State
--  ------------------ ---------- ------ ------------------ ------------0* stm32f4x.cpu       hla_target little stm32f4x.cpu       haltedInfo : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x08000868 msp: 0x20001180
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : Unable to match requested speed 8000 kHz, using 4000 kHz
Info : device id = 0x10006431
Info : flash size = 512 kbytes
auto erase enabled
wrote 16384 bytes from file D:/workspace/zephyrproject/zephyr-project/zephyr/build/zephyr/zephyr.hex in 0.618922s (25.851 KiB/s)Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
target halted due to breakpoint, current mode: Thread
xPSR: 0x61000000 pc: 0x20000044 msp: 0x20001180
shutdown command invoked

 注意出现错误，按住Rest按键再执行

(.venv) D:\workspace\zephyrproject\zephyr-sdk>openocd -f stm32f4.cfg
xPack Open On-Chip Debugger 0.12.0+dev-01850-geb6f2745b-dirty (2025-02-07-10:08)
Licensed under GNU GPL v2
For bug reports, readhttp://openocd.org/doc/doxygen/bugs.html
0x4000
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : STLINK V2J46S7 (API v2) VID:PID 0483:3748
Info : Target voltage: 3.205770
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : stlink_dap_op_connect(connect)
Info : SWD DPIDR 0x2ba01477
Error: Failed to read memory at 0xe000ed04
Error: [stm32f4x.cpu] Examination failed
Warn : target stm32f4x.cpu examination failed
Info : [stm32f4x.cpu] starting gdb server on 3333
Info : Listening on port 3333 for gdb connections
shutdown command invoked

 5.3 J-LINK工具

J-LINK 克隆调试器只能使用JLink_Windows_V758_x86_64版本，这个版本之后的版本都有JLink Clone检测功能。对于企业来说会带来一些不必要的麻烦，企业还是使用正版J-LINK硬件。

下载安装JLink_Windows_V758_x86_64，同样需要设置系统环境变量。

设置好后打开cmd终端, 验证JLink是否运行正常。

(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>west flash --runner jlink
-- west flash: rebuilding
ninja: no work to do.
-- west flash: using runner jlink
-- runners.jlink: reset after flashing requested
-- runners.jlink: JLink version: 7.58
-- runners.jlink: Flashing file: D:\workspace\zephyrproject\zephyr-project\zephyr\build\zephyr\zephyr.hex

验证JLink debug调试功能

west debug --runner jlink
west attach --runner jlink(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>west debug --runner jlink
-- west debug: rebuilding
ninja: no work to do.
-- west debug: using runner jlink
-- runners.jlink: reset after flashing requested
-- runners.jlink: JLink version: 7.58
-- runners.jlink: J-Link GDB server running on port 2331; no thread info available
GNU gdb (Zephyr SDK 0.17.1) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-host_w64-mingw32 --target=arm-zephyr-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/zephyrproject-rtos/sdk-ng/issues>.
Find the GDB manual and other documentation resources online at:<http://www.gnu.org/software/gdb/documentation/>.For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from D:\workspace\zephyrproject\zephyr-project\zephyr\build\zephyr\zephyr.elf...
Remote debugging using :2331
__enable_irq () at D:/workspace/zephyrproject/zephyr-project/modules/hal/cmsis/CMSIS/Core/Include/cmsis_gcc.h:951
951       __ASM volatile ("cpsie i" : : : "memory");
Resetting target
Loading section rom_start, size 0x194 lma 0x8000000
Loading section text, size 0x3444 lma 0x8000194
Loading section .ARM.exidx, size 0x8 lma 0x80035d8
Loading section initlevel, size 0x80 lma 0x80035e0
Loading section device_area, size 0x180 lma 0x8003660
Loading section sw_isr_table, size 0x2a8 lma 0x80037e0
Loading section gpio_driver_api_area, size 0x24 lma 0x8003a88
Loading section reset_driver_api_area, size 0x10 lma 0x8003aac
Loading section clock_control_driver_api_area, size 0x1c lma 0x8003abc
Loading section uart_driver_api_area, size 0x4c lma 0x8003ad8
--Type <RET> for more, q to quit, c to continue without paging--
Loading section rodata, size 0x2ec lma 0x8003b24
Loading section datas, size 0x4c lma 0x8003e10
Loading section device_states, size 0x18 lma 0x8003e5c
Loading section .last_section, size 0x4 lma 0x8003e74
Start address 0x08000868, load size 15992
Transfer rate: 3 KB/sec, 1142 bytes/write.
Resetting target
(gdb)(.venv) D:\workspace\zephyrproject\zephyr-project\zephyr>west attach --runner jlink
-- west attach: rebuilding
ninja: no work to do.
-- west attach: using runner jlink
-- runners.jlink: reset after flashing requested
-- runners.jlink: JLink version: 7.58
-- runners.jlink: J-Link GDB server running on port 2331; no thread info available
GNU gdb (Zephyr SDK 0.17.1) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-host_w64-mingw32 --target=arm-zephyr-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/zephyrproject-rtos/sdk-ng/issues>.
Find the GDB manual and other documentation resources online at:<http://www.gnu.org/software/gdb/documentation/>.For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from D:\workspace\zephyrproject\zephyr-project\zephyr\build\zephyr\zephyr.elf...
Remote debugging using :2331
z_arm_reset () at D:/workspace/zephyrproject/zephyr-project/zephyr/arch/arm/core/cortex_m\reset.S:121
121         ldr r0, =z_main_stack + CONFIG_MAIN_STACK_SIZE
(gdb)

 还会弹出JLinkGDBServer的窗口。