hs-openocd:基于 OpenOCD 生态的海思芯片调试工具项目

开发OpenOCD代码提交

Branch1Tags2
FilesLast commitLast 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 之上做了三类定制:

  1. 厂商芯片适配:新增海思系列芯片的目标配置与 RISC-V CoreSight 调试支持。
  2. 多平台交叉编译:一套脚本同时产出 Linux x64 / Linux aarch64 / Windows (mingw64) / macOS arm64 四个平台的可执行文件及依赖库。
  3. 开箱即用的发布产物:每个平台打包为自包含的 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.cfg
  • 3322-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 修改。

# 构建完成后 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 文件。

Introduction

开发OpenOCD代码提交

Customize your domain