开发OpenOCD代码提交
| Files | Last commit | Last update |
|---|---|---|
| 1 month ago | ||
| 5 days ago | ||
| 5 days ago | ||
| 5 days ago | ||
| 3 months ago | ||
| 3 months ago | ||
| 3 months ago | ||
| 3 months ago | ||
| 5 days ago |
hs-openocd
基于 OpenOCD 0.12.0 定制的多平台烧录调试工具,面向海思(HiSilicon)系列芯片。
版本:
0.12.0
本仓库在官方 OpenOCD 之上做了三类定制:
- 厂商芯片适配:新增海思系列芯片的目标配置与 RISC-V CoreSight 调试支持。
- 多平台交叉编译:一套脚本同时产出 Linux x64 / Linux aarch64 / Windows (mingw64) / macOS arm64 四个平台的可执行文件及依赖库。
- 开箱即用的发布产物:每个平台打包为自包含的 tar.gz(内含可执行文件与所需 cfg 配置,平铺于同一目录),解压即可运行。
目录结构
hs-openocd/
├── opensource/ # 第三方/上游源码
│ ├── openocd/ # OpenOCD 0.12.0 主源码(含海思定制)
│ ├── jimtcl/ # 内嵌 Tcl 解释器依赖
│ ├── libjaylink/ # J-Link 支持库(内置编译)
│ └── libusbx/ # USB 库源码
├── build/ # 构建脚本入口与核心
│ ├── build_dependence.sh # 主入口:选择平台并执行完整构建
│ └── core/ # 构建核心脚本
│ ├── public_config.sh # 公共配置:工具链、路径、安全编译选项
│ ├── sourcecode_prepare.sh# 解压、打补丁、bootstrap 源码
│ ├── build_libusbx.sh # 编译 libusbx
│ ├── build_openocd_connect.sh # 编译 openocd(主力产物)
│ ├── package_output.sh # 将各平台产物打包为 output/openocd-<平台>.tar.gz
│ └── build_openocd.sh # 编译标准 openocd(含 HISPARK_TRACE)
├── LICENSE # 项目主开源许可证(GPL-2.0)
├── LICENSE.OpenSource # 第三方开源组件许可证
├── COPYRIGHT # 项目基础版权声明
├── COPYRIGHT.OpenSource # 第三方开源组件版权声明
└── README.md
源码架构(OpenOCD 分层)
OpenOCD 采用分层架构,源码位于 opensource/openocd/src/:
| 模块 | 路径 | 职责 |
|---|---|---|
| 入口 | src/main.c / src/openocd.c | 程序入口、初始化、命令循环 |
| JTAG/SWD 适配层 | src/jtag/drivers/ | 各类调试器驱动:jlink.c、ftdi.c、cmsis_dap.c、ft2232.c 等 |
| Target 调试目标 | src/target/ | CPU 调试:aarch64.c、cortex_a.c、cortex_m.c、riscv/ |
| Flash 烧录 | src/flash/nor/ | 上游 Flash 框架及可选的 WS63/GD25Q32 驱动,见下文 |
| Server | src/server/ | GDB Server / Telnet / Tcl 接口 |
| Transport | src/transport/ | JTAG / SWD 传输层 |
| Helper | src/helper/ | 通用工具、日志、命令系统 |
| Tcl 配置 | tcl/interface/、tcl/target/ | 调试器与目标板配置脚本 |
海思定制点
1. 厂商目标配置 — tcl/target/vendorhm/
涵盖海思多款芯片的 JTAG/SWD/J-Link 配置,命名规则为 <芯片>-{jtag|swd|jlink}.cfg,例如:
WS63-jlink.cfg/WS63-swd.cfg3322-jlink.cfg
2. Flash 烧写策略 — 保留原配置,新增 WS63 显式启用入口
原有 WS63-jlink.cfg、WS63-swd.cfg 和 3322 配置保持 debug-only。
新增 ws63.cfg 使用同一海思 riscvcs 后端,提供 WS63/GD25Q32 Flash、缓存维护、
断点复位保护和 LiteOS 任务视图;适用条件及 Linux 实测范围见
WS63 功能参考与连接指南。
签名固件应按 SDK 分区安装;GDB load ELF 不等同于生成可启动的签名应用。
3. RISC-V CoreSight 调试 — src/target/riscv/,配合 target create ... riscvcs(见 WS63-jlink.cfg)。
构建指南
环境依赖
# OpenOCD 基础依赖
sudo apt install make libtool pkg-config autoconf automake texinfo
# Windows 交叉编译(mingw64)
sudo apt install gcc-mingw-w64-x86-64
# Linux aarch64 交叉编译(脚本会自动检测并尝试安装)
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
# macOS 交叉编译(osxcross,需自行准备,提供 oa64-clang 等工具)
# 或设置 OSXCROSS_ROOT 环境变量指向 osxcross 安装目录
# Linux 产物动态库路径修正
sudo apt install patchelf
一键构建
构建入口为 build/build_dependence.sh,支持平台别名与原生 build_type:
cd build
# 全量构建(默认,会先清空 output/)
bash build_dependence.sh all
# 单平台构建(增量,不影响其他平台已有产物)
bash build_dependence.sh linux # Linux x64 (linux64)
bash build_dependence.sh linux-arm64 # Linux aarch64 (linux-arm64)
bash build_dependence.sh windows # Windows (mingw64)
bash build_dependence.sh macos # macOS arm64 (macos-arm64)
| 别名 | 原生 build_type | 目标三元组 | 输出目录 |
|---|---|---|---|
linux |
linux64 |
系统默认 cc |
output/linux/x64/ |
linux-arm64 |
linux-arm64 |
aarch64-linux-gnu |
output/linux/aarch64/ |
windows |
mingw64 |
x86_64-w64-mingw32 |
output/mingw/x64/ |
macos |
macos-arm64 |
aarch64-apple-darwin(osxcross) |
output/macos/arm64/ |
安全编译选项
所有产物统一启用安全编译加固(见 build/core/public_config.sh):
- 编译:
-fPIC -fstack-protector-strong -D_FORTIFY_SOURCE=2 -O2 - 链接:Linux
-Wl,-z,relro,-z,now,-z,noexecstack,-s;Windows--nxcompat,--dynamicbase,--no-seh;macOS-bind_at_load,-dead_strip
构建产物
每构建一个平台,先在 output/<平台>/ 下生成自包含目录,再由 package_output.sh 打包为 output/openocd-<平台>.tar.gz,随后删除源平台目录。因此一次完整构建后 output/ 仅保留以下分发压缩包:
output/
├── openocd-linux-x64.tar.gz # Linux x64
├── openocd-linux-aarch64.tar.gz # Linux aarch64
├── openocd-windows-x64.tar.gz # Windows (mingw64)
└── openocd-macos-arm64.tar.gz # macOS arm64
每个 tar.gz 内为一个同名顶层目录(openocd-<平台>/),可执行文件与所需 cfg 全部平铺在同一目录下,解压即可运行。
openocd-linux-x64/ # Linux x64
├── openocd # 主可执行文件(libusb 静态链接)
├── jlink.cfg # 调试器配置(J-Link,*-jlink.cfg 依赖它)
├── ft2232h-ftdi-swd.cfg # 调试器配置(FTDI SWD,WS63-swd.cfg 依赖它)
├── ft2232h-ftdi-3322.cfg # 调试器配置(FTDI,3322 专用,去掉 -data 0x800)
├── ft2232h-ftdi-ws63.cfg # 调试器配置(FTDI,WS63 专用,RST 连接策略)
├── WS63-jlink.cfg # 海思 WS63(J-Link)
├── WS63-swd.cfg # 海思 WS63(FTDI SWD)
└── 3322-jlink.cfg # 海思 3322(J-Link / FTDI SWD 通用)
openocd-linux-aarch64/ # Linux aarch64(aarch64-linux-gnu 交叉编译,内容同上)
├── openocd
├── jlink.cfg
├── ft2232h-ftdi-swd.cfg
├── ft2232h-ftdi-3322.cfg
├── ft2232h-ftdi-ws63.cfg
├── WS63-jlink.cfg
├── WS63-swd.cfg
└── 3322-jlink.cfg
openocd-windows-x64/
├── openocd.exe
├── libusb-1.0.dll
├── libssp-0.dll
└── jlink.cfg, ft2232h-ftdi*.cfg, WS63-*.cfg, 3322-*.cfg
openocd-macos-arm64/
├── openocd # libusb 静态链接;构建机检测到 ldid/codesign 时自动做 ad-hoc 签名
│ # (Apple Silicon 必需),否则跳过并警告——发布前需在 macOS 上补签:
│ # codesign -s - openocd
└── jlink.cfg, ft2232h-ftdi*.cfg, WS63-*.cfg, 3322-*.cfg
macOS 用户须用终端
tar -xzf解压(勿用 Finder 双击):浏览器只给压缩包贴隔离标记,终端解压不传播至内部文件,可直接运行;Finder 解压会传播标记,导致运行时被 Gatekeeper 杀掉("Killed")。
使用方法
产物为自包含目录,WS63 / 3322 相关 cfg 及其调试器配置已与二进制平铺在同一目录下,-s 指向该目录后直接用文件名加载即可。
WS53 SWD 调试
新增 ws53.cfg,通过 AP0 使能调试并访问 AP1 的 RISC-V Debug Module。
自动创建 WS53.ap0/ap1/ap2 原始访问目标,默认 WS53.cpu 保持 A 核 GDB 调试。
在解压后的发布包目录运行:
./openocd -s . -f jlink.cfg -c "adapter serial 23121310; bindto 127.0.0.1" -f ws53.cfg -c "init; halt"
默认 100 kHz,硬件断点,不注册 Flash bank。使用 WS53 SDK 的 RISC-V GDB 连接 127.0.0.1:3333。
已在新 A 板验证暂停、寄存器/内存读取、单步、硬件断点命中、GDB 连接和脱离。
已修复 reset run 保留 PLL 时钟导致的持续 SWD WAIT,重复启动及复位后 GDB 重连验证通过。
本轮未烧录;完整检查记录列出通过项及验证边界。详细原理、构建命令、验证边界见 WS53 使用说明。
WS63 修复基于 PR #22
(1aff54e6c5259de553fce2e8cf781bd1d71426be)。旧 WS63-jlink.cfg、WS63-swd.cfg
也已接入修复,保持自动 init/halt 和默认关闭 Flash bank;本轮未进行 WS63 硬件验证。
WS63 原生 Flash 与 LiteOS 功能
在标准发布包目录运行(固件须已开启 GPIO13/14 的 SWD):
./openocd -s . -f cmsis-dap.cfg -c "adapter speed 4000" -f ws63.cfg -c "init; halt"
包内新增 cmsis-dap.cfg、ws63.cfg、contrib/ws63/prepare_elf.py 与 doc/ws63*.md。
CMSIS-DAP 与 J-Link 共用 ws63.cfg;J-Link 将接口配置换成 jlink.cfg。
只有使用 ELF 准备工具生成 LiteOS 配置或补充回溯信息时,才需要 Python 3 和
pyelftools。在发布包根目录创建独立的 Python 环境并安装依赖:
python3 -m venv .venv
.venv/bin/python -m pip install pyelftools
.venv/bin/python contrib/ws63/prepare_elf.py --help
Windows 使用 .venv\Scripts\python.exe 替代 .venv/bin/python。
实际处理 ELF 还需要对应 WS63 SDK 的 objdump、objcopy,详见
LiteOS 符号和回溯准备。
Flash 写入要求 POSIX 持久备份;Windows 保留调试/读出并拒绝 Flash 修改。
连接调试(原有 WS63 + J-Link 配置)
# 构建完成后 output/ 下仅保留分发包,先解压(以 Linux x64 为例)再进入同名顶层目录
tar -xzf output/openocd-linux-x64.tar.gz -C output/
cd output/openocd-linux-x64
# WS63 / 3322 via J-Link
./openocd -s . -f jlink.cfg -f WS63-jlink.cfg
./openocd -s . -f jlink.cfg -f 3322-jlink.cfg
# WS63 via FTDI(FT2232H 调试器,默认 GDB 端口 3333,使用 RST 连接)
./openocd -s . -f ft2232h-ftdi-ws63.cfg -f WS63-swd.cfg
# WS63 via FTDI SWD(也可用 WS63-jlink.cfg 作为目标配置,默认 GDB 端口 3333)
./openocd -s . -f ft2232h-ftdi-3322.cfg -f WS63-jlink.cfg
# 3322 via FTDI SWD(用专用 -3322- 接口 cfg,已去掉 -data 0x800)
./openocd -s . -f ft2232h-ftdi-3322.cfg -f 3322-jlink.cfg
# 指定 GDB 端口(目标 cfg 末尾会执行 init,gdb_port 必须放在它之前)
./openocd -s . -f jlink.cfg -c "gdb_port 30000" -f WS63-jlink.cfg
# 开启调试日志
./openocd -s . -f jlink.cfg -f WS63-jlink.cfg -d3 -l log.txt
连接 GDB / Telnet
OpenOCD 默认监听:
| 服务 | 默认端口 | 用途 |
|---|---|---|
| GDB Server | 3333 |
供 GDB 远程调试 |
| Telnet | 4444 |
交互式命令行 |
| Tcl | 6666 |
脚本接口 |
# 另开终端
telnet localhost 4444 # 进入 OpenOCD 命令行
riscv32-unknown-elf-gdb # 启动 GDB(WS63/3322 为 RISC-V 架构,需用 RISC-V 工具链的 gdb)
(gdb) target remote :3333 # 连接 OpenOCD GDB Server
调试器配置(包内已附带)
| 调试器 | 接口配置 | 适配的目标 cfg |
|---|---|---|
| SEGGER J-Link | jlink.cfg |
WS63-jlink.cfg、3322-jlink.cfg;WS63 新功能使用 ws63.cfg |
| CMSIS-DAP | cmsis-dap.cfg |
ws63.cfg |
| FTDI FT2232H (SWD) | ft2232h-ftdi-swd.cfg |
WS63-swd.cfg |
| FTDI FT2232H (WS63 专用) | ft2232h-ftdi-ws63.cfg |
WS63-swd.cfg |
| FTDI FT2232H (3322 专用) | ft2232h-ftdi-3322.cfg |
3322-jlink.cfg |
许可证
本仓库采用「主许可证 + 第三方组件许可证」双轨声明,根目录提供四个文件:
| 文件 | 说明 |
|---|---|
| LICENSE | 项目主开源许可证:海思自研代码(构建脚本、WS63/3322 等 flash 驱动、vendorhm 配置)采用 GPL-2.0;OpenOCD 0.12.0 上游源码(含对其修改)依其原许可证保留 GPL-2.0-or-later(海思不可去除上游的“or later”授权);编译产物 openocd 二进制按 GPL Version 2 分发。 |
| LICENSE.OpenSource | 第三方开源组件许可证:libusb / libjaylink 为 LGPL-2.1,Jim Tcl 为自有 BSD 风格 license。 |
| COPYRIGHT | 项目版权声明:Copyright (c) HiSilicon (Shanghai) Technologies Co., Ltd. |
| COPYRIGHT.OpenSource | 第三方组件版权声明 + 开源软件通知(OPEN SOURCE SOFTWARE NOTICE)+ 免责声明(Warranty Disclaimer)。 |
各第三方组件(jimtcl、libusb、libjaylink)保留其原始版权与许可证,完整文本见 opensource/ 下各组件的
COPYING/LICENSE文件。