flash-openocd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenOCD 烧录

OpenOCD Flashing

适用场景

Applicable Scenarios

工作区已经具备可用固件产物，且用户希望给硬件烧录程序。
已探测或用户指定的探针与 OpenOCD 兼容。
团队需要一条标准化的 OpenOCD 烧录流程，并可顺畅交接到串口观察或调试。
需要在烧录前确认探针连接状态或扫描工作区中的 OpenOCD 配置线索。

The workspace already has available firmware artifacts, and the user wants to flash the program to the hardware.
The detected or user-specified probe is compatible with OpenOCD.
The team needs a standardized OpenOCD flashing process that can smoothly transition to serial observation or debugging.
Need to confirm probe connection status or scan OpenOCD configuration clues in the workspace before flashing.

必要输入

Required Inputs

固件产物路径，或包含
```
artifact_path
```
的
```
Project Profile
```
。
OpenOCD 配置信息：显式接口 + 目标配置、板级配置、现有 profile 数据，或工作区中的配置线索。
可选的复位行为和校验偏好。默认开启校验和复位。
若产物为 BIN，还需要烧录基地址。

Firmware artifact path, or a Project Profile containing
```
artifact_path
```
.
OpenOCD configuration information: explicit interface + target configuration, board-level configuration, existing profile data, or configuration clues in the workspace.
Optional reset behavior and verification preferences. Verification and reset are enabled by default.
If the artifact is BIN, the flashing base address is also required.

自动探测

Auto-detection

按
```
ELF > HEX > BIN
```
选择固件产物。
脚本可自动探测已连接的调试探针（ST-Link、CMSIS-DAP、J-Link），优先使用探测到的第一个。
配置优先级依次为：显式用户输入、现有
```
Project Profile
```
、
```
--scan-configs
```
扫描到的工作区线索。
若产物为
```
BIN
```
，必须从工作区或用户输入中获得明确的烧录基地址，否则脚本会阻塞。
不要拼接多个"部分匹配"的配置；这种情况应返回
```
ambiguous-context
```
。

Select firmware artifacts in the order of
```
ELF > HEX > BIN
```
.
The script can automatically detect connected debug probes (ST-Link, CMSIS-DAP, J-Link), prioritizing the first one detected.
Configuration priority is as follows: explicit user input, existing
```
Project Profile
```
,
```
--scan-configs
```
scanned workspace clues.
If the artifact is
```
BIN
```
, a clear flashing base address must be obtained from the workspace or user input; otherwise, the script will block.
Do not splice multiple "partially matched" configurations; in such cases, return
```
ambiguous-context
```
.

执行步骤

Execution Steps

先阅读 references/usage.md，确认本次是环境探测、配置扫描，还是执行烧录。
若不确定探针状态，先运行自带脚本 scripts/openocd_flasher.py 的
```
--detect
```
模式确认。
若不确定 OpenOCD 配置，使用
```
--scan-configs
```
扫描工作区线索。
使用
```
--artifact
```
指定产物，配合
```
--interface
```
+
```
--target
```
或
```
--config
```
执行烧录。
对 BIN 文件，必须同时提供
```
--base-address
```
。
读取脚本输出的烧录结果报告，重点关注校验状态和失败分类。
将烧录配置和结果写回
```
Project Profile
```
，并在需要时交给下游 skill。

First read references/usage.md to confirm whether this is environment detection, configuration scanning, or flashing execution.
If unsure about the probe status, first run the
```
--detect
```
mode of the built-in script scripts/openocd_flasher.py to confirm.
If unsure about the OpenOCD configuration, use
```
--scan-configs
```
to scan workspace clues.
Use
```
--artifact
```
to specify the artifact, and execute flashing with
```
--interface
```
+
```
--target
```
or
```
--config
```
.
For BIN files,
```
--base-address
```
must be provided at the same time.
Read the flashing result report output by the script, focusing on verification status and failure categories.
Write the flashing configuration and results back to
```
Project Profile
```
, and hand over to downstream skill when needed.

失败分流

Failure Diversion

当
```
openocd
```
不可用时，返回
```
environment-missing
```
。
当无法安全解析到产物，或
```
BIN
```
缺少烧录基地址时，返回
```
artifact-missing
```
。
当 OpenOCD 无法发现探针或目标板时，返回
```
connection-failure
```
。
当所选配置文件无效时，返回
```
project-config-error
```
。
当烧录开始了，但校验、停核或复位失败时，返回
```
target-response-abnormal
```
。
当存在多个同样合理的配置集合或目标时，返回
```
ambiguous-context
```
。

When
```
openocd
```
is unavailable, return
```
environment-missing
```
.
When the artifact cannot be safely parsed, or
```
BIN
```
lacks the flashing base address, return
```
artifact-missing
```
.
When OpenOCD cannot detect the probe or target board, return
```
connection-failure
```
.
When the selected configuration file is invalid, return
```
project-config-error
```
.
When flashing starts but verification, core halt, or reset fails, return
```
target-response-abnormal
```
.
When multiple equally reasonable configuration sets or targets exist, return
```
ambiguous-context
```
.

平台说明

Platform Notes

探针访问失败在所有宿主平台上都可能表现为 USB 或驱动问题，只是具体报错文本会随操作系统不同而变化。
自带脚本使用 Python 标准库和 subprocess 调用 openocd，因此烧录调度路径本身是跨平台的。
输出中应保留完整 OpenOCD 配置列表，方便在其他宿主环境中复现同一会话。

Probe access failures may manifest as USB or driver issues on all host platforms, although specific error messages vary by operating system.
The built-in script uses Python standard libraries and subprocess to call openocd, so the flashing scheduling path itself is cross-platform.
The complete list of OpenOCD configurations should be retained in the output to facilitate reproducing the same session in other host environments.

输出约定

Output Conventions

输出 OpenOCD 命令、所选配置文件、产物路径，以及是否要求校验和复位。

在

Project Profile

中保留或更新

artifact_path

、

artifact_kind

、

openocd_config

。

根据用户意图推荐下一步 skill：做启动验证后推荐
```
serial-monitor
```
，需要调试时推荐
```
debug-gdb-openocd
```
。

Output the OpenOCD command, selected configuration files, artifact path, and whether verification and reset are required.

Retain or update

artifact_path

artifact_kind

openocd_config

in the

Project Profile

Recommend the next skill based on user intent: recommend
```
serial-monitor
```
after startup verification, and recommend
```
debug-gdb-openocd
```
when debugging is needed.

交接关系

Handover Relationships

当下一步要看运行日志时，将成功烧录结果交给
```
serial-monitor
```
。
当用户需要断点、停核控制或崩溃分析时，将成功或部分成功的烧录结果交给
```
debug-gdb-openocd
```
。

When the next step is to view running logs, hand over the successful flashing result to
```
serial-monitor
```
.
When the user needs breakpoints, core halt control, or crash analysis, hand over the successful or partially successful flashing result to
```
debug-gdb-openocd
```
.