Metric Tracer - Experimental

Metric Tracer - Experimental#

oneAPI Level Zero Specification - Version 1.18.31

Metric Tracer - Experimental Functions#

zetMetricTracerCreateExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricTracerCreateExp(zet_context_handle_t hContext, zet_device_handle_t hDevice, uint32_t metricGroupCount, zet_metric_group_handle_t *phMetricGroups, zet_metric_tracer_exp_desc_t *desc, ze_event_handle_t hNotificationEvent, zet_metric_tracer_exp_handle_t *phMetricTracer)#

Create a metric tracer 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.

  • The metric tracer is created in disabled state

  • Metric groups must support sampling type ZET_METRIC_SAMPLING_TYPE_EXP_FLAG_TRACER_BASED

  • All metric groups must be first activated

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • metricGroupCount – [in] metric group count

  • phMetricGroups – [in][range(0, metricGroupCount )] handles of the metric groups to trace

  • desc – [in,out] metric tracer descriptor

  • hNotificationEvent – [in][optional] event used for report availability notification. Note: If buffer is not drained when the event it flagged, there is a risk of HW event buffer being overrun

  • phMetricTracer – [out] handle of the metric tracer

Returns:

zetMetricTracerDestroyExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricTracerDestroyExp(zet_metric_tracer_exp_handle_t hMetricTracer)#

Destroy a metric tracer.

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

Parameters:

hMetricTracer – [in] handle of the metric tracer

Returns:

zetMetricTracerEnableExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricTracerEnableExp(zet_metric_tracer_exp_handle_t hMetricTracer, ze_bool_t synchronous)#

Start events collection.

  • Driver implementations must make this API call have as minimal overhead as possible, to allow applications start/stop event collection at any point during execution

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

Parameters:

  • hMetricTracer – [in] handle of the metric tracer

  • synchronous – [in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling zetMetricTracerReadDataExp() and checking the return status: ZE_RESULT_NOT_READY will be returned when the tracer is inactive. ZE_RESULT_SUCCESS will be returned when the tracer is active.

Returns:

zetMetricTracerDisableExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricTracerDisableExp(zet_metric_tracer_exp_handle_t hMetricTracer, ze_bool_t synchronous)#

Stop events collection.

  • Driver implementations must make this API call have as minimal overhead as possible, to allow applications start/stop event collection at any point during execution

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

Parameters:

  • hMetricTracer – [in] handle of the metric tracer

  • synchronous – [in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling zetMetricTracerReadDataExp() and checking the return status: ZE_RESULT_SUCCESS will be returned when the tracer is active or when it is inactive but still has data. ZE_RESULT_NOT_READY will be returned when the tracer is inactive and has no more data to be retrieved.

Returns:

zetMetricTracerReadDataExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricTracerReadDataExp(zet_metric_tracer_exp_handle_t hMetricTracer, size_t *pRawDataSize, uint8_t *pRawData)#

Read data from the metric tracer.

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

  • Data can be retrieved after tracer is disabled. When buffers are drained ZE_RESULT_NOT_READY will be returned

Parameters:

  • hMetricTracer – [in] handle of the metric tracer

  • 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.

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

Returns:

zetMetricTracerDecodeExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricTracerDecodeExp(zet_metric_decoder_exp_handle_t phMetricDecoder, size_t *pRawDataSize, uint8_t *pRawData, uint32_t metricsCount, zet_metric_handle_t *phMetrics, uint32_t *pSetCount, uint32_t *pMetricEntriesCountPerSet, uint32_t *pMetricEntriesCount, zet_metric_entry_exp_t *pMetricEntries)#

Decode raw events collected from a tracer.

Parameters:

  • phMetricDecoder – [in] handle of the metric decoder object

  • pRawDataSize – [in,out] size in bytes of raw data buffer. If pMetricEntriesCount is greater than zero but less than total number of decodable metrics available in the raw data buffer, then driver shall update this value with actual number of raw data bytes processed.

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

  • metricsCount – [in] number of decodable metrics in the tracer for which the hMetricDecoder handle was provided. See zetMetricDecoderGetDecodableMetricsExp(). If metricCount is greater than zero but less than the number decodable metrics available in the raw data buffer, then driver shall only decode those.

  • phMetrics – [in] [range(0, metricsCount)] array of handles of decodable metrics in the decoder for which the hMetricDecoder handle was provided. Metrics handles are expected to be for decodable metrics, see zetMetricDecoderGetDecodableMetricsExp()

  • pSetCount – [in,out] pointer to number of metric sets. If count is zero, then the driver shall update the value with the total number of metric sets to be decoded. If count is greater than the number available in the raw data buffer, then the driver shall update the value with the actual number of metric sets to be decoded. There is a 1:1 relation between the number of sets and sub-devices returned in the decoded entries.

  • pMetricEntriesCountPerSet – [in,out][optional][range(0, *pSetCount)] buffer of metric entries counts per metric set, one value per set.

  • pMetricEntriesCount – [in,out] pointer to the total number of metric entries decoded, for all metric sets. If count is zero, then the driver shall update the value with the total number of metric entries to be decoded. If count is greater than zero but less than the total number of metric entries available in the raw data, then user provided number will be decoded. If count is greater than the number available in the raw data buffer, then the driver shall update the value with the actual number of decodable metric entries decoded. If set to null, then driver will only update the value of pSetCount.

  • pMetricEntries – [in,out][optional][range(0, *pMetricEntriesCount)] buffer containing decoded metric entries

Returns:

Metric Tracer - Experimental Structures#

zet_metric_tracer_exp_desc_t#

Added in version 1.10

struct zet_metric_tracer_exp_desc_t#

Metric tracer 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 notifyEveryNBytes#

[in,out] number of collected bytes 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 zetMetricTracerCreateExp.