OpenOCD / JTAG Debugging

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.

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?"

Workflow

1. JTAG vs SWD

Feature JTAG SWD (Serial Wire Debug)

Pins 4+ (TCK, TMS, TDI, TDO, TRST) 2 (SWCLK, SWDIO)

Multi-target Yes (daisy chain) No (one target)

Speed Up to 30 MHz Up to 10 MHz

Availability Full JTAG: Cortex-A/R, RISC-V SWD: Cortex-M only

Cable cost More complex Simpler 2-wire

Most Cortex-M microcontrollers support both. Use SWD when pin count is limited.

2. OpenOCD configuration

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

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

For SWD explicitly

transport select swd

J-Link adapter

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

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

openocd -f openocd.cfg

Common interface config files

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

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/

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

3. Connecting GDB

In terminal 1: start OpenOCD

openocd -f openocd.cfg

In terminal 2: start GDB

arm-none-eabi-gdb firmware.elf

GDB commands

(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

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

4. Flashing firmware

Flash via OpenOCD telnet interface

telnet localhost 4444

OpenOCD telnet commands

reset halt program firmware.elf verify reset exit

Or via GDB

(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"

For raw binary

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

5. Hardware breakpoints and watchpoints

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:

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

(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

List breakpoints/watchpoints

(gdb) info breakpoints

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

6. OpenOCD commands reference

Via telnet (port 4444) or 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

Flash operations

monitor flash list monitor flash erase_sector 0 0 0 # erase sector 0 monitor flash write_bank 0 firmware.bin 0

7. Common errors

Error Cause Fix

unable to find JTAG device

Wrong interface, cable, or power Check USB connection; power target; verify interface config

JTAG scan chain interrogation failed

Wrong target config or bad SWD mode Match config to exact MCU; try transport select swd

flash 'stm32f4x' is not supported

Wrong target Check 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 address Check MPU config; use correct flash/RAM address

Warn: target not examined yet

OpenOCD not connected to target Check power and connections

8. J-Link configuration

openocd.cfg for J-Link

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):

Segger's own GDB server

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

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