HSS 高速采样

以下内容自动抽取自 sdk-headers/HFLinkDriver_hss.h ,含 14 个公开函数及全部公开类型。函数指针回调类型不单独列出,见所属结构体成员说明。

结构体

Sampling block descriptor (counterpart of JLINK_HSS_MEM_BLOCK_DESC; addresses may be any byte alignment).

Public Members

Sampling start address

Number of bytes to read per round (>=1)

Single-frame sample view: data points to the frame's data area within the caller's buffer; blocks are packed contiguously in Start order.

Public Members

Nanosecond timestamp relative to Start

Frame data (blocks concatenated in order, no padding)

Frame data size in bytes = sum of num_bytes

HSS run statistics.

Public Members

Total number of frames written into the ring buffer

Number of old frames dropped on ring buffer overflow

Number of whole batches dropped due to transfer errors (overflow not included)

Measured average sampling period of the latest batch (0 = not yet measured)

Whether in the manual pause state (SetPaused)

Auto-pause during target halt/reset/algorithm execution (driven by CoreSight state)

Timestamp source: 1 = probe firmware TD_TimeStamp, 0 = host monotonic clock

Timing control mode (HFLINK_HSS_MODE_*; auto-detected at Start)

API

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

Destroy a layout object; may be NULL.

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

Get the block as a 32-bit little-endian value (high bytes zero-padded when shorter than 4 bytes).

Get the block as a 64-bit little-endian value (high bytes zero-padded when shorter than 8 bytes).

Create an HSS session. If target is NULL, Start returns HFLINK_ERR_NOT_INITIALIZED.

Destroy the session (automatically stops the sampling thread and frees all resources; ring buffer data is discarded as well).

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)

Stop sampling (idempotent; after stopping, ring buffer data is kept and readable via ReadSamples).

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

Session-layout variant of the block data getter (equivalent to LayoutGetBlock on the session's layout).

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)

Query the run statistics.

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