openocd-jtag

OpenOCD / JTAG デバッグ

目的

JTAG および SWD ターゲット向けの OpenOCD 設定、マイクロコントローラーへのファームウェアの書き込み、ベアメタルデバッグのための GDB の接続、ハードウェアウォッチポイントの設定、J-Link および CMSIS-DAP アダプターの設定について、エージェントをガイドします。

トリガー

• 「OpenOCD で GDB を MCU に接続するにはどうすればよいですか？」
• 「OpenOCD を使ってファームウェアを書き込むにはどうすればよいですか？」
• 「OpenOCD で J-Link をセットアップするにはどうすればよいですか？」
• 「JTAG と SWD の違いは何ですか？」
• 「GDB でハードウェアウォッチポイントを設定するにはどうすればよいですか？」
• 「OpenOCD で 'Error: unable to find JTAG device' と表示されます。どうすれば解決できますか？」

ワークフロー

1. JTAG と SWD の比較

機能	JTAG	SWD（Serial Wire Debug）
ピン	4 以上（TCK、TMS、TDI、TDO、TRST）	2（SWCLK、SWDIO）
マルチターゲット	対応（デイジーチェーン）	非対応（ターゲット 1 つ）
速度	最大 30 MHz	最大 10 MHz
対応範囲	フル JTAG：Cortex-A/R、RISC-V	SWD：Cortex-M のみ
ケーブルのコスト	より複雑	よりシンプルな 2 線

ほとんどの Cortex-M マイクロコントローラーは両方に対応しています。ピン数に制限がある場合は SWD を使用してください。

2. OpenOCD の設定

# 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. 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. ファームウェアの書き込み

# 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. ハードウェアブレークポイントとウォッチポイント

ソフトウェアブレークポイント（break）は、トラップ命令で命令メモリーを書き換えます。デバッグレジスターなしのフラッシュ実行（execute-in-place）では機能しません。代わりにハードウェアブレークポイントを使用してください。

# 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 コマンドのリファレンス

# 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. よくあるエラー

エラー	原因	解決方法
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 の設定

# 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（OpenOCD の代替）：

# Segger's own GDB server
JLinkGDBServer -if SWD -device STM32L476RG -port 3333 &
arm-none-eabi-gdb -ex "target remote :3333" firmware.elf

関連スキル

• OpenOCD で FreeRTOS を考慮したデバッグを行うには、skills/embedded/freertos を使用してください
• Zephyr の west debug 連携には、skills/embedded/zephyr を使用してください
• GDB セッションを管理するには、skills/debuggers/gdb を使用してください
• フラッシュアドレスのメモリーマップを理解するには、skills/embedded/linker-scripts を使用してください