SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsopenocd

openocd

Coding & development

View repository

Updated 10-15 22:35

About this skill

OpenOCD Download and Debugging

This skill provides OpenOCD's probe detection, firmware flashing, Flash erasing, GDB Server startup, target reset, Telnet online debugging, GDB source-level debugging, and Semihosting output capture capabilities.

Configuration

Environment-level configuration (skill/config.json)

In the skill directory, config.json contains environment-level configuration (tool paths, port numbers, etc.). Before first use, confirm that the exe path is correct:

{
  "exe": "openocd",
  "scripts_dir": "",
  "gdb_port": 3333,
  "telnet_port": 4444,
  "gdb_exe": "",
  "operation_mode": 1
}
  • exe: openocd.exe path or command name (required)
  • scripts_dir: OpenOCD configuration script directory; when empty, use OpenOCD's built-in path
  • gdb_port: GDB Server port, default 3333
  • telnet_port: Telnet port, default 4444
  • gdb_exe: arm-none-eabi-gdb path, required for GDB debugging subcommands (run/backtrace/locals)
  • operation_mode：1 directly execute / 2 output a risk summary but do not block / 3 confirm before execution

Project-level configuration (.embeddedskills/config.json)

Project parameters such as board/interface/target are managed uniformly in the workspace's .embeddedskills/config.json :

{
  "openocd": {
    "board": "",
    "interface": "interface/stlink.cfg",
    "target": "target/stm32f4x.cfg",
    "adapter_speed": "4000",
    "transport": "swd",
    "tpiu_name": "stm32f4x.tpiu",
    "traceclk": "168000000",
    "pin_freq": "2000000"
  }
}
  • board: board configuration (e.g. board/stm32f4discovery.cfg), takes priority over interface+target
  • interface: interface configuration (e.g. interface/stlink.cfg）
  • target: target configuration (e.g. target/stm32f4x.cfg）
  • adapter_speed: debugging speed in kHz
  • transport: transport protocol (swd/jtag)
  • tpiu_name / traceclk / pin_freq: TPIU parameters required for ITM/SWO observation

Parameter resolution priority:Explicit CLI parameters > .embeddedskills/config.json(project-level) > skill/config.json(environment-level) > .embeddedskills/state.json > default value/error

After successful execution, confirmed parameters are automatically written back to the project configuration.

Subcommands

Basic Operations

Subcommand Purpose Risk
probe Verify the board or interface+target combination, detect target connectivity Low
flash Flash firmware (.elf / .hex / .bin) High
erase Erase target Flash High
reset / reset-init Reset target chip High
targets / flash-banks / adapter-info Query low-level target / flash / adapter information Low
raw Execute controlled OpenOCD native commands High

GDB Server

Subcommand Purpose Risk
gdb-server Start GDB Server, keep it running and wait for GDB connection Low
gdb backtrace/locals Quickly obtain the call stack and local variables Low
gdb break/continue/next/step/finish/until one-shot execution flow control Low
gdb frame/print/watch/disassemble/threads/crash-report one-shot source-level diagnostics Low

Telnet Online Debugging

Subcommand Purpose Risk
halt Halt the CPU, return PC/xPSR Low
resume Resume CPU execution Low
step Single-step execution (supports --count N） Low
reg View all CPU registers Low
read-mem Read memory (--width 8/16/32，--length N） Low
write-mem Write memory (--width 8/16/32） High
bp Set hardware breakpoint Low
rbp Remove breakpoint Low
run-to Run to specified address (set breakpoint + resume + wait for hit) Low

Semihosting

Subcommand Purpose Risk
semihosting Enable ARM Semihosting and capture target printf output Low
itm Read SWO/ITM observation data based on TPIU/ITM Low

Execution flow

  1. Read skill/config.json, confirm exe path is valid
  2. Read .embeddedskills/config.json to get project-level configuration (board/interface/target, etc.)
  3. Read .embeddedskills/state.json to get historical state
  4. Parameter parsing priority:Explicit CLI parameters > .embeddedskills/config.json(project-level) > skill/config.json(environment-level) > .embeddedskills/state.json > default value/error
  5. When board is known, prefer -f board/*.cfg, otherwise combine -f interface/*.cfg -f target/*.cfg
  6. board、interface、target When both are missing, do not automatically combine them; directly ask the user to provide them
  7. According to operation_mode , decide whether confirmation is required before execution
  8. Call the corresponding script according to the subcommand
  9. Uniformly parse Info、Error and the ready log in the output, and return structured results
  10. After successful execution, write the confirmed parameters back to .embeddedskills/config.json

Script invocation

There are five Python scripts in the skill directory, implemented using the standard library with no additional dependencies.

openocd_run.py — probe / flash / erase / reset

# 探测连通性（使用 board）
python <skill-dir>/scripts/openocd_run.py probe --board board/stm32f4discovery.cfg --json

# 探测连通性（使用 interface + target）
python <skill-dir>/scripts/openocd_run.py probe --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 烧录 ELF 固件
python <skill-dir>/scripts/openocd_run.py flash --file build/app.elf --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 烧录 BIN 固件（必须提供地址）
python <skill-dir>/scripts/openocd_run.py flash --file build/app.bin --address 0x08000000 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 擦除 Flash（自动选择 mass/sector）
python <skill-dir>/scripts/openocd_run.py erase --mode auto --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 复位目标
python <skill-dir>/scripts/openocd_run.py reset --mode halt --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 查询 target 列表
python <skill-dir>/scripts/openocd_run.py targets --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 查询 flash bank
python <skill-dir>/scripts/openocd_run.py flash-banks --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 执行受控 raw 命令
python <skill-dir>/scripts/openocd_run.py raw --interface interface/stlink.cfg --target target/stm32f4x.cfg --command "init" "targets" --json

Common optional parameters:--board <cfg>、--search <目录>、--adapter-speed <kHz>、--transport <swd|jtag>、--exe <openocd路径>

openocd_gdb.py — GDB Server startup and debugging

# 启动 GDB Server（保持运行）
python <skill-dir>/scripts/openocd_gdb.py server --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 无子命令时默认 server（向后兼容）
python <skill-dir>/scripts/openocd_gdb.py --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 执行自定义 GDB 命令序列
python <skill-dir>/scripts/openocd_gdb.py run --gdb-exe arm-none-eabi-gdb --elf build/app.elf --interface interface/stlink.cfg --target target/stm32f4x.cfg --commands "break main" "continue" "backtrace" "info locals" --json

# 快捷获取调用栈
python <skill-dir>/scripts/openocd_gdb.py backtrace --gdb-exe arm-none-eabi-gdb --elf build/app.elf --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 快捷查看局部变量
python <skill-dir>/scripts/openocd_gdb.py locals --gdb-exe arm-none-eabi-gdb --elf build/app.elf --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

Optional parameters:--gdb-port、--telnet-port、--search、--adapter-speed、--transport、--board

openocd_telnet.py — Telnet online debugging

# 暂停 CPU
python <skill-dir>/scripts/openocd_telnet.py halt --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 恢复运行
python <skill-dir>/scripts/openocd_telnet.py resume --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 单步 5 次
python <skill-dir>/scripts/openocd_telnet.py step --count 5 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 查看寄存器
python <skill-dir>/scripts/openocd_telnet.py reg --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 读内存（32bit x 16 个字）
python <skill-dir>/scripts/openocd_telnet.py read-mem --address 0x20000000 --length 16 --width 32 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 写内存
python <skill-dir>/scripts/openocd_telnet.py write-mem --address 0x20000000 --value 0xDEADBEEF --width 32 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 设置硬件断点
python <skill-dir>/scripts/openocd_telnet.py bp --address 0x08001234 --bp-length 2 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 移除断点
python <skill-dir>/scripts/openocd_telnet.py rbp --address 0x08001234 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 运行到指定地址（设置断点 + resume + 等待）
python <skill-dir>/scripts/openocd_telnet.py run-to --address 0x08001234 --timeout-ms 3000 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

Common optional parameters:--board、--search、--adapter-speed、--transport、--gdb-port、--telnet-port

openocd_semihosting.py — Semihosting output capture

# 捕获 semihosting 输出（持续到 Ctrl+C）
python <skill-dir>/scripts/openocd_semihosting.py --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 捕获 30 秒
python <skill-dir>/scripts/openocd_semihosting.py --timeout 30 --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

openocd_itm.py — ITM/SWO observation

# 使用配置中的 TPIU 参数持续读取 ITM
python <skill-dir>/scripts/openocd_itm.py --interface interface/stlink.cfg --target target/stm32f4x.cfg --json

# 指定 TPIU 名称和端口
python <skill-dir>/scripts/openocd_itm.py \
  --interface interface/stlink.cfg --target target/stm32f4x.cfg \
  --tpiu-name stm32f4x.tpiu --traceclk 168000000 --pin-freq 2000000 \
  --itm-port 0 --itm-port 1 --json

openocd_itm.py will start an independent OpenOCD Server, enable the TPIU/ITM configuration, and uniformly wrap trace output as JSON Lines.

Typical debugging workflow

Quick check (Telnet)

halt -> reg -> read-mem 0x20000000 -> step -> resume

Suitable for quickly viewing the current CPU state and memory contents.

Breakpoint debugging (Telnet)

run-to 0x08001234 -> reg -> read-mem -> resume

Pause after running to the specified address, and inspect registers and memory.

Source-level debugging (GDB)

gdb run --elf app.elf --commands "break main" "continue" "backtrace" "info locals"

Use the ELF file to provide symbol information for function-level breakpoints and variable inspection.

Semihosting output

semihosting

Capture debug information output by the target through printf(SVC instruction), similar to J-Link RTT.

Output format

All scripts return in JSON format, with the base field being status（ok/error）、action、summary、details, and may include context、artifacts、metrics、state、next_actions、timing. Streaming observation commands use JSON Lines and uniformly output source、channel_type、stream_type。

Success example:

{
  "status": "ok",
  "action": "halt",
  "summary": "已暂停，PC=0x08000298",
  "details": {
    "pc": "0x08000298",
    "xpsr": "0x01000000",
    "msp": "0x20020000",
    "halted": true
  }
}

GDB call stack example:

{
  "status": "ok",
  "action": "backtrace",
  "summary": "GDB backtrace 执行成功",
  "details": {
    "gdb_port": 3333,
    "frames": [
      {"frame": 0, "function": "main", "location": "src/main.c:42"}
    ]
  }
}

Error example:

{
  "status": "error",
  "action": "halt",
  "error": {
    "code": "server_failed",
    "message": "OpenOCD 启动失败或超时"
  }
}

Core rules

  • Do not automatically guess the combination of board、interface、target ; when missing, the user must be asked
  • Known board board configuration is used first, interface+target is no longer needed
  • The parameter resolution priority is:Explicit CLI parameters > .embeddedskills/config.json(project level) > skill/config.json(environment level) > .embeddedskills/state.json > default value/error
  • .bin The file must explicitly provide the flash address; an error is reported if it is missing
  • Mapped targets such as STM32F4 under erase --mode auto will first reset halt, then prefer mass erase
  • erase --mode mass When no mapping is hit, directly return mass_erase_unsupported, to avoid mistakenly assuming a full-chip erase has been performed
  • When Flash lock protection is detected, only a warning is given; it is not automatically unlocked
  • When connection fails, provide troubleshooting suggestions (check wiring, power supply, driver, cfg path); do not automatically try more aggressive parameters
  • Flashing, erasing, and reset are executed directly when parameters are complete and user intent is clear
  • gdb-server After startup, return the port and connection method; the process keeps running
  • GDB debugging (run/backtrace/locals) requires configuring gdb_exe(arm-none-eabi-gdb path)
  • Each Telnet debug command starts an independent OpenOCD Server, which closes automatically after execution
  • After Semihosting is enabled via Telnet, it continuously reads OpenOCD stderr output
  • The result echo always includes the cfg combination, port, and executed action
  • Artifact paths (elf/file) do not enter the project configuration and still only depend on state.json
  • last_flash/last_debug/last_observe and other runtime states continue to be written to state.json

Reference

When encountering board/interface/target configuration issues, consult references/common_targets.md。