HSS 高速采样
以下内容自动抽取自 sdk-headers/HFLinkDriver_hss.h ,含 14 个公开函数及全部公开类型。函数指针回调类型不单独列出,见所属结构体成员说明。
结构体
-
struct HFLink_HSS_MemBlock
Sampling block descriptor (counterpart of JLINK_HSS_MEM_BLOCK_DESC; addresses may be any byte alignment).
-
struct HFLink_HSS_SampleView
Single-frame sample view: data points to the frame's data area within the caller's buffer; blocks are packed contiguously in Start order.
-
struct HFLink_HSS_Stats
HSS run statistics.
Public Members
-
uint64_t total_samples
Total number of frames written into the ring buffer
-
uint64_t dropped_samples
Number of old frames dropped on ring buffer overflow
-
uint64_t dropped_batches
Number of whole batches dropped due to transfer errors (overflow not included)
-
uint64_t mean_period_ns
Measured average sampling period of the latest batch (0 = not yet measured)
-
int paused
Whether in the manual pause state (SetPaused)
-
int target_halted
Auto-pause during target halt/reset/algorithm execution (driven by CoreSight state)
-
int ts_from_probe
Timestamp source: 1 = probe firmware TD_TimeStamp, 0 = host monotonic clock
-
int delay_mode
Timing control mode (HFLINK_HSS_MODE_*; auto-detected at Start)
-
uint64_t total_samples
API
-
HFLink_HSS_Layout *HFLink_HSS_LayoutCreate(const HFLink_HSS_MemBlock *blocks, uint32_t num_blocks)
Create a sampling layout (a decoding view of the block descriptors)
- 参数:
blocks -- Block descriptor array (copied internally)
num_blocks -- Number of blocks (1..HFLINK_HSS_MAX_BLOCKS)
- 返回:
Layout pointer; NULL if the arguments are invalid or a single round's encoding exceeds the single-Transfer-packet limit
-
void HFLink_HSS_LayoutDestroy(HFLink_HSS_Layout *layout)
Destroy a layout object; may be NULL.
-
const uint8_t *HFLink_HSS_LayoutGetBlock(const HFLink_HSS_Layout *layout, const HFLink_HSS_SampleView *sample, uint32_t block_index, uint32_t *num_bytes)
Get the raw data pointer of the specified block within a sample
- 参数:
layout -- Layout (defines the block layout)
sample -- Sample view (data must be organized in this layout's frame format)
block_index -- Block index (0-based)
num_bytes -- May be NULL; outputs the block size in bytes
- 返回:
Pointer to the block data (points inside sample->data); NULL if the index is out of range
-
uint32_t HFLink_HSS_LayoutGetU32(const HFLink_HSS_Layout *layout, const HFLink_HSS_SampleView *sample, uint32_t block_index)
Get the block as a 32-bit little-endian value (high bytes zero-padded when shorter than 4 bytes).
-
uint64_t HFLink_HSS_LayoutGetU64(const HFLink_HSS_Layout *layout, const HFLink_HSS_SampleView *sample, uint32_t block_index)
Get the block as a 64-bit little-endian value (high bytes zero-padded when shorter than 8 bytes).
-
HFLink_HSSHandle *HFLink_HSS_Create(HFLink_CoreSightTarget *target)
Create an HSS session. If target is NULL, Start returns HFLINK_ERR_NOT_INITIALIZED.
-
void HFLink_HSS_Destroy(HFLink_HSSHandle *hss)
Destroy the session (automatically stops the sampling thread and frees all resources; ring buffer data is discarded as well).
-
int HFLink_HSS_Start(HFLink_HSSHandle *hss, const HFLink_HSS_MemBlock *blocks, uint32_t num_blocks, uint32_t period_us, uint32_t flags)
Start periodic sampling (when already running: stops the old sampling, flushes the buffer, applies the new configuration, and restarts)
- 参数:
hss -- Session
blocks -- Sampling block descriptor array
num_blocks -- Number of blocks (1..HFLINK_HSS_MAX_BLOCKS)
period_us -- Sampling period (microseconds, >=1; best effort)
flags -- Reserved, must be 0
- 返回:
HFLINK_OK; HFLINK_ERR_HSS_INVALID_PARAM if the arguments are invalid; HFLINK_ERR_HSS_TOO_MANY_BLOCKS if a single round's encoding exceeds the single-Transfer-packet limit; HFLINK_ERR_HSS_UNSUPPORTED if the probe/target capabilities are insufficient (e.g. APv2 hierarchical path)
-
int HFLink_HSS_Stop(HFLink_HSSHandle *hss)
Stop sampling (idempotent; after stopping, ring buffer data is kept and readable via ReadSamples).
-
int HFLink_HSS_ReadSamples(HFLink_HSSHandle *hss, uint8_t *buffer, uint32_t buffer_size, HFLink_HSS_SampleView *views, uint32_t max_views)
Read complete sample frames (no need to Stop first)
备注
Each frame consumes data_size bytes from buffer; limited by both max_views and buffer_size
- 参数:
hss -- Session
buffer -- Output buffer (copy destination for frame data)
buffer_size -- Buffer capacity
views -- Sample view array (data points to each frame's data area within buffer)
max_views -- Capacity of views
- 返回:
>=0 number of samples read (complete frames only); negative values are HFLINK_ERR_* errors
-
const uint8_t *HFLink_HSS_GetBlock(const HFLink_HSSHandle *hss, const HFLink_HSS_SampleView *sample, uint32_t block_index, uint32_t *num_bytes)
Session-layout variant of the block data getter (equivalent to LayoutGetBlock on the session's layout).
-
int HFLink_HSS_GetCaps(const HFLink_CoreSightTarget *target, uint32_t *max_blocks, uint32_t *max_freq_hz)
Query the HSS capabilities of the current connection
- 参数:
target -- Target (used to read the SWD clock; may be NULL, estimated with conservative values)
max_blocks -- May be NULL; outputs the maximum number of blocks
max_freq_hz -- May be NULL; outputs the estimated maximum sampling frequency (best-effort reference value)
-
int HFLink_HSS_GetStats(HFLink_HSSHandle *hss, HFLink_HSS_Stats *stats)
Query the run statistics.
-
int HFLink_HSS_SetPaused(HFLink_HSSHandle *hss, int paused)
Pause/resume sampling (the host should pause while the target is halted; mirrors the SEGGER CPU-halt auto-pause semantics)
备注
Auto-pause triggered by consecutive transfer errors is also resumed through this interface