Metric Streamer

Metric Streamer#

oneAPI Level Zero Specification - Version 1.18.31

Metric Streamer Functions#

zetMetricStreamerOpen#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerOpen(zet_context_handle_t hContext, zet_device_handle_t hDevice, zet_metric_group_handle_t hMetricGroup, zet_metric_streamer_desc_t *desc, ze_event_handle_t hNotificationEvent, zet_metric_streamer_handle_t *phMetricStreamer)#

Opens metric streamer for a device.

  • The notification event must have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_HOST_VISIBLE flag.

  • The duration of the signal event created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality.

  • The application must not call this function from simultaneous threads with the same device handle.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • hMetricGroup – [in] handle of the metric group

  • desc – [in,out] metric streamer descriptor

  • hNotificationEvent – [in][optional] event used for report availability notification

  • phMetricStreamer – [out] handle of metric streamer

Returns:

zetMetricStreamerClose#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerClose(zet_metric_streamer_handle_t hMetricStreamer)#

Closes metric streamer.

  • The application must not call this function from simultaneous threads with the same metric streamer handle.

Parameters:

hMetricStreamer – [in][release] handle of the metric streamer

Returns:

zetMetricStreamerReadData#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerReadData(zet_metric_streamer_handle_t hMetricStreamer, uint32_t maxReportCount, size_t *pRawDataSize, uint8_t *pRawData)#

Reads data from metric streamer.

  • The application may call this function from simultaneous threads.

Parameters:

  • hMetricStreamer – [in] handle of the metric streamer

  • maxReportCount – [in] the maximum number of reports the application wants to receive. if UINT32_MAX, then function will retrieve all reports available

  • pRawDataSize – [in,out] pointer to the size in bytes of raw data requested to read. The driver will only retrieve the number of reports that fit into the buffer. pRawDataSize will be updated by the driver to reflect the actual number of bytes written into the buffer. If the size returns the full size requested, the application may need to issue additional reads to retrieve any remaining reports that did not fit into the buffer.

    Deprecated:

    : The behavior of passing in zero size and the function returning the required size is deprecated, for now it returns only the maximum buffer size regardless of how much data there is available to be read.

  • pRawData – [in,out][optional][range(0, *pRawDataSize)] buffer containing streamer reports in raw format

Returns:

Metric Streamer Structures#

zet_metric_streamer_desc_t#

Added in version 1.0

struct zet_metric_streamer_desc_t#

Metric streamer descriptor.

Public Members

zet_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t notifyEveryNReports#

[in,out] number of collected reports after which notification event will be signaled. If the requested value is not supported exactly, then the driver may use a value that is the closest supported approximation and shall update this member during zetMetricStreamerOpen.

uint32_t samplingPeriod#

[in,out] streamer sampling period in nanoseconds. If the requested value is not supported exactly, then the driver may use a value that is the closest supported approximation and shall update this member during zetMetricStreamerOpen.

In this class