Back to Details

openocd-jtag

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenOCD / JTAG Debugging

OpenOCD / JTAG 调试

Purpose

用途

Guide agents through configuring OpenOCD for JTAG and SWD targets, flashing firmware to microcontrollers, attaching GDB for bare-metal debugging, setting hardware watchpoints, and configuring J-Link and CMSIS-DAP adapters.
指导开发者完成针对JTAG和SWD目标的OpenOCD配置、向微控制器烧录固件、连接GDB进行裸机调试、设置硬件观察点，以及配置J-Link和CMSIS-DAP适配器的操作。

Triggers

触发场景

  • "How do I connect GDB to my MCU with OpenOCD?"
  • "How do I flash firmware using OpenOCD?"
  • "How do I set up J-Link with OpenOCD?"
  • "What's the difference between JTAG and SWD?"
  • "How do I set a hardware watchpoint in GDB?"
  • "OpenOCD says 'Error: unable to find JTAG device' — how do I fix it?"
  • "如何使用OpenOCD将GDB连接到我的MCU？"
  • "如何使用OpenOCD烧录固件？"
  • "如何将J-Link与OpenOCD配合设置？"
  • "JTAG和SWD有什么区别？"
  • "如何在GDB中设置硬件观察点？"
  • "OpenOCD提示‘Error: unable to find JTAG device’——该如何修复？"

Workflow

操作流程

1. JTAG vs SWD

1. JTAG 与 SWD 对比

FeatureJTAGSWD (Serial Wire Debug)
Pins4+ (TCK, TMS, TDI, TDO, TRST)2 (SWCLK, SWDIO)
Multi-targetYes (daisy chain)No (one target)
SpeedUp to 30 MHzUp to 10 MHz
AvailabilityFull JTAG: Cortex-A/R, RISC-VSWD: Cortex-M only
Cable costMore complexSimpler 2-wire
Most Cortex-M microcontrollers support both. Use SWD when pin count is limited.
特性JTAGSWD（串行线调试）
引脚数量4+（TCK、TMS、TDI、TDO、TRST）2（SWCLK、SWDIO）
多目标支持是（菊花链连接）否（仅单个目标）
速度最高30 MHz最高10 MHz
适用范围完整JTAG：Cortex-A/R、RISC-VSWD：仅Cortex-M
线缆成本更复杂更简单的2线线缆
大多数Cortex-M微控制器同时支持两者。当引脚数量有限时，优先使用SWD。

2. OpenOCD configuration

2. OpenOCD 配置

tcl
undefined
tcl
undefined

openocd.cfg — CMSIS-DAP (ST-Link v2, DAPLink)

openocd.cfg — CMSIS-DAP（ST-Link v2、DAPLink）

source [find interface/cmsis-dap.cfg] source [find target/stm32f4x.cfg] adapter speed 4000 # kHz
source [find interface/cmsis-dap.cfg] source [find target/stm32f4x.cfg] adapter speed 4000 # kHz

For SWD explicitly

显式指定使用SWD

transport select swd
transport select swd

J-Link adapter

J-Link 适配器配置

source [find interface/jlink.cfg] jlink serial 123456789 # optional: select by serial source [find target/nrf52.cfg] adapter speed 8000

```bash
source [find interface/jlink.cfg] jlink serial 123456789 # 可选：通过序列号选择设备 source [find target/nrf52.cfg] adapter speed 8000

```bash

Run OpenOCD (keeps running, serves GDB on port 3333)

启动OpenOCD（持续运行，在3333端口为GDB提供服务）

openocd -f openocd.cfg
openocd -f openocd.cfg

Common interface config files

查看常见的接口配置文件

ls $(openocd --help 2>&1 | grep "scripts" | head -1)/interface/
ls $(openocd --help 2>&1 | grep "scripts" | head -1)/interface/

cmsis-dap.cfg, jlink.cfg, ftdi/olimex-arm-usb-ocd.cfg, stlink.cfg ...

cmsis-dap.cfg, jlink.cfg, ftdi/olimex-arm-usb-ocd.cfg, stlink.cfg ...

Common target config files

查看常见的目标配置文件

ls $(openocd --help 2>&1 | grep "scripts" | head -1)/target/
ls $(openocd --help 2>&1 | grep "scripts" | head -1)/target/

stm32f4x.cfg, nrf52.cfg, esp32.cfg, rp2040.cfg, at91sam4s.cfg ...

stm32f4x.cfg, nrf52.cfg, esp32.cfg, rp2040.cfg, at91sam4s.cfg ...

undefined
undefined

3. Connecting GDB

3. 连接 GDB

bash
undefined
bash
undefined

In terminal 1: start OpenOCD

终端1：启动OpenOCD

openocd -f openocd.cfg
openocd -f openocd.cfg

In terminal 2: start GDB

终端2：启动GDB

arm-none-eabi-gdb firmware.elf
arm-none-eabi-gdb firmware.elf

GDB commands

GDB 命令

(gdb) target extended-remote :3333 # connect to OpenOCD (gdb) monitor reset halt # reset and halt target (gdb) load # flash ELF to target (gdb) monitor reset init # re-initialize after flash (gdb) break main # set software breakpoint (gdb) continue
(gdb) target extended-remote :3333 # 连接到OpenOCD (gdb) monitor reset halt # 复位并暂停目标设备 (gdb) load # 将ELF文件烧录到目标设备 (gdb) monitor reset init # 烧录后重新初始化 (gdb) break main # 设置软件断点 (gdb) continue

One-liner for quick debugging

快速调试的单行命令

arm-none-eabi-gdb -ex "target extended-remote :3333"
-ex "monitor reset halt"
-ex "load"
-ex "break main"
-ex "continue"
firmware.elf
undefined
arm-none-eabi-gdb -ex "target extended-remote :3333"
-ex "monitor reset halt"
-ex "load"
-ex "break main"
-ex "continue"
firmware.elf
undefined

4. Flashing firmware

4. 烧录固件

bash
undefined
bash
undefined

Flash via OpenOCD telnet interface

通过OpenOCD telnet接口烧录

telnet localhost 4444
telnet localhost 4444

OpenOCD telnet commands

OpenOCD telnet 命令

reset halt program firmware.elf verify reset exit
reset halt program firmware.elf verify reset exit

Or via GDB

或通过GDB烧录

(gdb) monitor flash write_image erase firmware.bin 0x08000000 (gdb) monitor reset run
(gdb) monitor flash write_image erase firmware.bin 0x08000000 (gdb) monitor reset run

Flash only (no debug) — script mode

仅烧录（不调试）——脚本模式

openocd -f openocd.cfg
-c "program firmware.elf verify reset exit"
openocd -f openocd.cfg
-c "program firmware.elf verify reset exit"

For raw binary

烧录原始二进制文件

openocd -f openocd.cfg
-c "program firmware.bin 0x08000000 verify reset exit"
undefined
openocd -f openocd.cfg
-c "program firmware.bin 0x08000000 verify reset exit"
undefined

5. Hardware breakpoints and watchpoints

5. 硬件断点与观察点

Software breakpoints (
break
) patch instruction memory with trap instructions — they don't work in flash-execute-in-place without debug registers. Use hardware breakpoints instead:
bash
undefined
软件断点（
break
）会用陷阱指令修改指令内存——在闪存原地执行的场景下，没有调试寄存器的支持就无法工作。此时应使用硬件断点：
bash
undefined

Hardware breakpoint (uses debug register, limited count: 4-8 on Cortex-M)

硬件断点（使用调试寄存器，数量有限：Cortex-M通常为4-8个）

(gdb) hbreak function_name (gdb) hbreak *0x08001234
(gdb) hbreak function_name (gdb) hbreak *0x08001234

Hardware watchpoint — triggers on memory read/write

硬件观察点——在内存读/写时触发

(gdb) watch global_variable # write watchpoint (gdb) rwatch some_buffer # read watchpoint (gdb) awatch sensor_value # read OR write watchpoint
(gdb) watch global_variable # 写观察点 (gdb) rwatch some_buffer # 读观察点 (gdb) awatch sensor_value # 读或写观察点

List breakpoints/watchpoints

列出所有断点/观察点

(gdb) info breakpoints
(gdb) info breakpoints

Cortex-M typically has: 4–8 hardware breakpoints, 2–4 watchpoints

Cortex-M 通常支持：4–8个硬件断点，2–4个观察点

undefined
undefined

6. OpenOCD commands reference

6. OpenOCD 命令参考

bash
undefined
bash
undefined

Via telnet (port 4444) or GDB monitor

通过telnet（4444端口）或GDB monitor执行

monitor reset halt # reset and hold at reset vector monitor reset init # reset and run init scripts monitor reset run # reset and run freely monitor halt # halt running target monitor resume # resume execution monitor mdw 0x20000000 # memory display word at address monitor mww 0x40021000 0x1 # memory write word monitor reg r0 # read register monitor arm disassemble 0x08000000 16 # disassemble 16 instructions
monitor reset halt # 复位并停在复位向量处 monitor reset init # 复位并运行初始化脚本 monitor reset run # 复位并自由运行 monitor halt # 暂停运行中的目标设备 monitor resume # 恢复执行 monitor mdw 0x20000000 # 显示指定地址的内存字 monitor mww 0x40021000 0x1 # 向指定地址写入内存字 monitor reg r0 # 读取寄存器值 monitor arm disassemble 0x08000000 16 # 反汇编16条指令

Flash operations

闪存操作

monitor flash list monitor flash erase_sector 0 0 0 # erase sector 0 monitor flash write_bank 0 firmware.bin 0
undefined
monitor flash list monitor flash erase_sector 0 0 0 # 擦除扇区0 monitor flash write_bank 0 firmware.bin 0
undefined

7. Common errors

7. 常见错误

ErrorCauseFix
unable to find JTAG device
Wrong interface, cable, or powerCheck USB connection; power target; verify interface config
JTAG scan chain interrogation failed
Wrong target config or bad SWD modeMatch config to exact MCU; try 
transport select swd
flash 'stm32f4x' is not supported
Wrong targetCheck MCU part number; use correct 
.cfg
Error: timed out while waiting for target halted
Target running, not halted
monitor halt
; check BOOT pins
Cannot access memory at address
MMU, memory protection, or wrong addressCheck MPU config; use correct flash/RAM address
Warn: target not examined yet
OpenOCD not connected to targetCheck power and connections
错误信息原因解决方法
unable to find JTAG device
接口、线缆错误或未供电检查USB连接；为目标设备供电；验证接口配置
JTAG scan chain interrogation failed
目标配置错误或SWD模式异常配置文件与MCU型号匹配；尝试
transport select swd
flash 'stm32f4x' is not supported
目标设备错误检查MCU型号；使用正确的
.cfg
文件
Error: timed out while waiting for target halted
目标设备正在运行，未暂停执行
monitor halt
；检查BOOT引脚状态
Cannot access memory at address
MMU、内存保护或地址错误检查MPU配置；使用正确的闪存/RAM地址
Warn: target not examined yet
OpenOCD未连接到目标设备检查供电和连接

8. J-Link configuration

8. J-Link 配置

tcl
undefined
tcl
undefined

openocd.cfg for J-Link

用于J-Link的openocd.cfg配置

source [find interface/jlink.cfg] jlink usb 0 # use first J-Link found transport select swd # or jtag adapter speed 4000
source [find target/stm32l4x.cfg]

J-Link GDB Server (alternative to OpenOCD):

```bash
source [find interface/jlink.cfg] jlink usb 0 # 使用第一个找到的J-Link设备 transport select swd # 或jtag adapter speed 4000
source [find target/stm32l4x.cfg]

J-Link GDB Server（OpenOCD的替代方案）：

```bash

Segger's own GDB server

Segger官方的GDB服务器

JLinkGDBServer -if SWD -device STM32L476RG -port 3333 & arm-none-eabi-gdb -ex "target remote :3333" firmware.elf
undefined
JLinkGDBServer -if SWD -device STM32L476RG -port 3333 & arm-none-eabi-gdb -ex "target remote :3333" firmware.elf
undefined

Related skills

相关技能

  • Use 
    skills/embedded/freertos
    for FreeRTOS-aware debugging with OpenOCD
  • Use 
    skills/embedded/zephyr
    for Zephyr's 
    west debug
    integration
  • Use 
    skills/debuggers/gdb
    for GDB session management
  • Use 
    skills/embedded/linker-scripts
    for understanding memory map for flash addresses
  • 如需结合OpenOCD进行FreeRTOS感知调试，请使用
    skills/embedded/freertos
  • 如需Zephyr的
    west debug
    集成，请使用
    skills/embedded/zephyr
  • 如需GDB会话管理，请使用
    skills/debuggers/gdb
  • 如需理解闪存地址的内存映射，请使用
    skills/embedded/linker-scripts