设备基础与升级
本页收录 HFLinkDriver.h 中面向应用的设备基础 API(18 个函数);同文件中的调试会话层接口(118 个,设备会话/CoreSight 上下文/目标控制)不属于公开文档范围。
枚举
-
enum HFLink_Interface
Probe physical connection type.
Values:
-
enumerator HFLINK_INFERFACE_USB
USB connection
-
enumerator HFLINK_INFERFACE_IP
Network connection
-
enumerator HFLINK_INFERFACE_USB
-
enum HFLink_LedMode
LED display mode.
Values:
-
enumerator HFLINK_LED_MODE_DEFAULT
-
enumerator HFLINK_LED_MODE_CMSISDAP
-
enumerator HFLINK_LED_MODE_DEFAULT
-
enum HFLink_Config
Values:
-
enumerator HFLINK_CONFIG_5V_SUPPLY
5V power supply control; parameter is the character '0' or '1'
-
enumerator HFLINK_CONFIG_INDEPENDENT_UART
Independent UART interface setting; parameter is the character '0' or '1'
-
enumerator HFLINK_CONFIG_FREQ_MAP_EN
Frequency mapping table enable setting; parameter is the character '0' or '1'
-
enumerator HFLINK_CONFIG_FREQ_MAP
Frequency mapping table; parameter {
-
enumerator HFLINK_CONFIG_IODELAY
Input/output delay control; parameter {
-
enumerator HFLINK_CONFIG_LEDMODE
LED mode; parameter {
参见
HFLink_LedMode}
-
enumerator HFLINK_CONFIG_NICKNAME
Alias; parameter char[32]
-
enumerator HFLINK_CONFIG_BUILD_DATE
Build date; parameter (char *buf, int size)
-
enumerator HFLINK_CONFIG_FW_VERSION
-
enumerator HFLINK_CONFIG_5V_SUPPLY
结构体
-
struct HFLink_DeviceInfo
Probe device information (filled by HFLink_GetDeviceInfo).
Public Members
-
int speed
Debug clock (Hz)
-
HFLink_Interface interface
Connection type
-
char serial_number[33]
Serial number (32 characters + terminator)
-
char device_name[129]
Product name (128 characters + terminator)
-
int is_thirdparty
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
-
int speed
-
struct HFLink_Upgrade
Probe firmware upgrade state machine control block (allocated by the caller; see the HFLink_Upgrade* functions).
Public Members
-
uint8_t *buff
Firmware data; a heap buffer when set by HFLink_UpgradeFile, freed by HFLink_UpgradeFree
-
int len
Total firmware length (bytes)
-
int wlen
Bytes sent so far
-
uint32_t checksum
Firmware CRC32 checksum
-
enum HFLink_Upgrade status
Current state machine state
-
int delay_cnt
Internal poll counter (VERIFY phase)
-
int timeout_cnt
Internal timeout/retry counter
-
uint8_t *buff
-
struct HFLink_Config_FreqMap
Debug clock frequency mapping table (per-channel enable bitmap, read/written via the HFLINK_CONFIG_FREQ_MAP configuration item).
-
struct HFLink_Config_IODELAY
Input/output signal delay configuration (read/written via the HFLINK_CONFIG_IODELAY configuration item; the unit is the internal clock tick).
类型
-
typedef struct HFLink_Device *HFLink_Handle
Device object handle (created by HFLink_Open, released by HFLink_Close).
API
-
uint32_t HFLink_GetDllVersion(void)
Returns the driver DLL version, formatted 0xMMmmpp (major.minor.patch, e.g. 0x00010100 is 1.1.0).
-
int HFLink_Initialize(int use_async)
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.
-
int HFLink_Cleanup(void)
Cleans up the driver: stops the event thread and releases the libusb context; safely returns HFLINK_OK when not initialized.
-
int HFLink_GetDeviceInfo(HFLink_DeviceInfo *info, uint32_t max_num)
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.
-
int HFLink_Open(HFLink_DeviceInfo *info, HFLink_Handle *handle)
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.
-
int HFLink_Close(HFLink_Handle handle)
Closes the device and releases the device object; the handle must not be used afterwards.
-
char *HFLink_GetSerialNumber(HFLink_Handle handle)
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.
-
char *HFLink_GetModelName(HFLink_Handle handle)
Reads the probe model name; returns a borrowed pointer, same semantics as HFLink_GetSerialNumber().
-
int HFLink_UpgradeBitstream(HFLink_Handle handle, HFLink_Upgrade *upg_ctl, uint8_t *data, uint32_t len)
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.
-
int HFLink_UpgradeFile(HFLink_Handle handle, HFLink_Upgrade *upg_ctl, const char *path)
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.
-
int HFLink_UpgradeTick(HFLink_Handle handle, HFLink_Upgrade *upg_ctl)
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).
-
int HFLink_UpgradeFree(HFLink_Handle handle, HFLink_Upgrade *upg_ctl)
Finishes the upgrade and frees the upgrade buffer (including the UpgradeFile heap buffer), zeroes the control block; always returns 0.
-
int HFLink_Configure_SetItem(HFLink_Handle handle, HFLink_Config conf, ...)
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_LedModeHFLINK_CONFIG_NICKNAME:char *(UTF-8 alias, truncated to 31 characters when too long)
- 返回:
HFLINK_OK on success; HFLINK_ERR_UNSUPPORTED for third-party DAPs.
-
int HFLink_Configure_GetItem(HFLink_Handle handle, HFLink_Config conf, ...)
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 structLEDMODE: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.
-
int HFLink_Configure_Save(HFLink_Handle handle)
Saves the written configuration to the probe's persistent storage (retained across power-off).
-
int HFLink_Sensor_Read(HFLink_Handle handle, HFLink_Sensor sensor, uint8_t *data, uint32_t len)
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.
-
int HFLink_SWO_Start(HFLink_Handle handle, HFLink_SWO_Callback callback, void *userdata, uint32_t buffer_size)
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
-
int HFLink_SWO_Stop(HFLink_Handle handle)
Stops asynchronous SWO streaming: cancels all in-flight transfers and releases resources.