Skip to content

backport: jtag/drivers: add T-Head CK-Link JTAG adapter driver - #80

Open
will-tm wants to merge 1 commit into
zephyrproject-rtos:zephyr-20250213from
will-tm:backport/cklink-driver
Open

backport: jtag/drivers: add T-Head CK-Link JTAG adapter driver#80
will-tm wants to merge 1 commit into
zephyrproject-rtos:zephyr-20250213from
will-tm:backport/cklink-driver

Conversation

@will-tm

@will-tm will-tm commented May 18, 2026

Copy link
Copy Markdown

Driver for T-Head CK-Link Lite V2 probes, including the Bouffalo Lab BL616/BL702 CK-Link clones used as built-in debuggers on BL61x/BL70x evaluation boards. The wire protocol is a framed command format over USB bulk endpoints, reverse-engineered from T-Head's DebugServer.

Implements JTAG_SCAN via the probe's batch opcode, with IR caching across execute_queue boundaries and end-of-queue flush so OpenOCD's Capture-IR validation reads real hardware data. Speed is programmable (freq_kHz = 48000 / (N+1), capped at the DebugServer-validated 2526 kHz). Probes are matched against a built-in VID/PID list and by adapter serial.

Known protocol limitations, surfaced as one-time warnings:

  • Single batch entry encodes IR/DR bit-counts in single bytes; scans > 255 bits are clamped with TDI pass-through on the un-shifted portion.
  • The T-Head DTM's Capture-IR returns the current IR value rather than the IEEE 1149.1 'xxx01' pattern; init pre-loads IR = IDCODE.
  • No TMS-sequence opcode: JTAG_TMS and JTAG_PATHMOVE return ERROR_JTAG_NOT_IMPLEMENTED.
  • Multi-TAP chains are not supported.
  • RTCK is not supported.

Tested against BL618 and BL702 evaluation boards.

Adapted for the Zephyr OpenOCD fork: uses .transports string array instead of .transport_ids, and the 4-argument jtag_libusb_open() signature (serial matching handled internally by libusb_helper).

Backport of:
https://review.openocd.org/c/openocd/+/9586

Driver for T-Head CK-Link Lite V2 probes, including the Bouffalo Lab
BL616/BL702 CK-Link clones used as built-in debuggers on BL61x/BL70x
evaluation boards. The wire protocol is a framed command format over
USB bulk endpoints, reverse-engineered from T-Head's DebugServer.

Implements JTAG_SCAN via the probe's batch opcode, with IR caching
across execute_queue boundaries and end-of-queue flush so OpenOCD's
Capture-IR validation reads real hardware data. Speed is programmable
(freq_kHz = 48000 / (N+1), capped at the DebugServer-validated 2526
kHz). Probes are matched against a built-in VID/PID list and by
adapter serial.

Known protocol limitations, surfaced as one-time warnings:

  - Single batch entry encodes IR/DR bit-counts in single bytes;
    scans > 255 bits are clamped with TDI pass-through on the
    un-shifted portion.
  - The T-Head DTM's Capture-IR returns the current IR value rather
    than the IEEE 1149.1 'xxx01' pattern; init pre-loads IR = IDCODE.
  - No TMS-sequence opcode: JTAG_TMS and JTAG_PATHMOVE return
    ERROR_JTAG_NOT_IMPLEMENTED.
  - Multi-TAP chains are not supported.
  - RTCK is not supported.

Tested against BL618 and BL702 evaluation boards.

Adapted for the Zephyr OpenOCD fork: uses .transports string array
instead of .transport_ids, and the 4-argument jtag_libusb_open()
signature (serial matching handled internally by libusb_helper).

Backport of:
https://review.openocd.org/c/openocd/+/9586

Signed-off-by: William Markezana <william.markezana@gmail.com>
@will-tm
will-tm force-pushed the backport/cklink-driver branch from 5700896 to 9777f42 Compare May 18, 2026 15:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant