设备基础与升级

本页收录 HFLinkDriver.h 中面向应用的设备基础 API(18 个函数);同文件中的调试会话层接口(118 个,设备会话/CoreSight 上下文/目标控制)不属于公开文档范围。

枚举

Probe physical connection type.

Values:

USB connection

Network connection

LED display mode.

Values:

Values:

5V power supply control; parameter is the character '0' or '1'

Independent UART interface setting; parameter is the character '0' or '1'

Frequency mapping table enable setting; parameter is the character '0' or '1'

Frequency mapping table; parameter {

Input/output delay control; parameter {

LED mode; parameter {

参见

HFLink_LedMode}

Alias; parameter char[32]

Build date; parameter (char *buf, int size)

Sensor number (currently only the base group: voltage/current).

Values:

结构体

Probe device information (filled by HFLink_GetDeviceInfo).

Public Members

Debug clock (Hz)

Connection type

Serial number (32 characters + terminator)

Product name (128 characters + terminator)

Non-zero indicates a third-party DAP (e.g. CherryUSB CMSIS-DAP): disables configure/upgrade/sensor/SWO, caps the speed at 10MHz and forces FIFO depth 1

Probe firmware upgrade state machine control block (allocated by the caller; see the HFLink_Upgrade* functions).

Public Members

Firmware data; a heap buffer when set by HFLink_UpgradeFile, freed by HFLink_UpgradeFree

Total firmware length (bytes)

Bytes sent so far

Firmware CRC32 checksum

Current state machine state

Internal poll counter (VERIFY phase)

Internal timeout/retry counter

Debug clock frequency mapping table (per-channel enable bitmap, read/written via the HFLINK_CONFIG_FREQ_MAP configuration item).

Input/output signal delay configuration (read/written via the HFLINK_CONFIG_IODELAY configuration item; the unit is the internal clock tick).

Public Members

JTAG TCK delay

TMS turn-around delay

TMS output delay

TMS input delay

TDO delay

TDI delay

类型

Device object handle (created by HFLink_Open, released by HFLink_Close).

API

Returns the driver DLL version, formatted 0xMMmmpp (major.minor.patch, e.g. 0x00010100 is 1.1.0).

Initializes the driver: creates the libusb context and optionally starts the background USB event thread.

备注

Must be called before enumerating/opening devices; on Windows it raises the system timer resolution to 1 ms, restored by HFLink_Cleanup().

参数:
  • use_async -- Non-zero enables the libusb event background thread; with 0 events are handled on the calling thread.

返回:

HFLINK_OK on success; HFLINK_ERR on initialization failure.

Cleans up the driver: stops the event thread and releases the libusb context; safely returns HFLINK_OK when not initialized.

Enumerates the currently attached probes (HFLink native + whitelisted third-party CMSIS-DAP).

参数:
  • info -- [out] Caller-allocated array of device information.

  • max_num -- Array capacity; entries beyond it are truncated.

返回:

Number of devices actually enumerated (0 means no probe); HFLINK_ERR_NOT_INITIALIZED when uninitialized; negative on error.

Opens an enumerated probe and creates the device object.

参数:
  • info -- Target device information (from HFLink_GetDeviceInfo).

  • handle -- [out] Receives the device handle.

返回:

HFLINK_OK on success; negative on error. Third-party probes have is_thirdparty non-zero and some capabilities are unavailable.

Closes the device and releases the device object; the handle must not be used afterwards.

Reads the probe serial number; returns a borrowed pointer into the device's internal buffer (valid for the device lifetime, no need to free), or NULL on failure.

Reads the probe model name; returns a borrowed pointer, same semantics as HFLink_GetSerialNumber().

Prepares the probe firmware upgrade state machine from an in-memory bitstream.

备注

Afterwards HFLink_UpgradeTick() must be called periodically to drive the state machine until status reaches a terminal state.

参数:
  • upg_ctl -- Upgrade control block (allocated by the caller and kept alive); data is borrowed until the upgrade ends and is not copied.

返回:

HFLINK_OK on success; HFLINK_ERR_UNSUPPORTED for third-party DAPs; -1 for invalid arguments.

Prepares the upgrade state machine from a firmware file; the file is read into a heap buffer whose ownership is transferred to upg_ctl.

返回:

Same as HFLink_UpgradeBitstream(); a file read failure returns a negative value and sets status to HFLINK_UPG_FAULT.

One step of the upgrade state machine; the caller invokes it at a fixed period (about 1-10 ms) until status reaches a terminal state.

备注

State transitions: IDLE -> (reset + start) -> ERASE/FLASH (in 256-byte pages) -> VERIFY (CRC32 read-back comparison) -> SUCCESS.

返回:

0 if this step succeeded (including still in progress); -1 on failure (status already FAULT or TIMEOUT).

Finishes the upgrade and frees the upgrade buffer (including the UpgradeFile heap buffer), zeroes the control block; always returns 0.

Sets a probe configuration item; the additional argument type depends on conf:

  • HFLINK_CONFIG_5V_SUPPLY / INDEPENDENT_UART / FREQ_MAP_EN: char ('0' or '1')

  • HFLINK_CONFIG_FREQ_MAP: HFLink_Config_FreqMap *

  • HFLINK_CONFIG_IODELAY: HFLink_Config_IODELAY *

  • HFLINK_CONFIG_LEDMODE: HFLink_LedMode

  • HFLINK_CONFIG_NICKNAME: char * (UTF-8 alias, truncated to 31 characters when too long)

返回:

HFLINK_OK on success; HFLINK_ERR_UNSUPPORTED for third-party DAPs.

Reads a probe configuration item; the additional arguments are out-pointers of the matching type:

  • the three boolean items (see HFLink_Configure_SetItem()): char * (receives '0'/'1')

  • FREQ_MAP / IODELAY: pointer to the corresponding struct

  • LEDMODE: HFLink_LedMode *

  • NICKNAME: char * (capacity of at least 32 bytes)

  • BUILD_DATE / FW_VERSION: (char *buf, int size), receives the build date / firmware version string

返回:

HFLINK_OK on success; negative on error.

Saves the written configuration to the probe's persistent storage (retained across power-off).

Reads sensor data (currently HFLINK_SENSOR_BASE: voltage/current).

参数:
  • data -- [out] Receive buffer (length per the sensor convention, >= 64 bytes recommended).

返回:

HFLINK_OK on success; HFLINK_ERR_UNSUPPORTED for third-party DAPs.

Starts asynchronous SWO streaming reads.

Uses multi-buffered libusb asynchronous transfers for gap-free continuous reception; the callback is invoked on the internal event thread and must be thread-safe.

参数:
  • callback -- SWO data callback, invoked for every received data packet

  • userdata -- Callback user data

  • buffer_size -- Buffer size per transfer (bytes); 0 uses the default 4096

返回:

HFLINK_OK on success, HFLINK_ERR_BUSY if already started, HFLINK_ERR on invalid arguments

Stops asynchronous SWO streaming: cancels all in-flight transfers and releases resources.