Metric Group - Experimental

Metric Group - Experimental#

oneAPI Level Zero Specification - Version 1.18.31

Metric Group - Experimental Functions#

zetMetricGroupCalculateMultipleMetricValuesExp#

Added in version 1.2

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupCalculateMultipleMetricValuesExp(zet_metric_group_handle_t hMetricGroup, zet_metric_group_calculation_type_t type, size_t rawDataSize, const uint8_t *pRawData, uint32_t *pSetCount, uint32_t *pTotalMetricValueCount, uint32_t *pMetricCounts, zet_typed_value_t *pMetricValues)#

Calculate one or more sets of metric values from raw data.

  • This function is similar to zetMetricGroupCalculateMetricValues except it may calculate more than one set of metric values from a single data buffer. There may be one set of metric values for each sub-device, for example.

  • Each set of metric values may consist of a different number of metric values, returned as the metric value count.

  • All metric values are calculated into a single buffer; use the metric counts to determine which metric values belong to which set.

  • The application may call this function from simultaneous threads.

Parameters:

  • hMetricGroup – [in] handle of the metric group

  • type – [in] calculation type to be applied on raw data

  • rawDataSize – [in] size in bytes of raw data buffer

  • pRawData – [in][range(0, rawDataSize)] buffer of raw data to calculate

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

  • pTotalMetricValueCount – [in,out] pointer to number of the total number of metric values calculated, for all metric sets. if count is zero, then the driver shall update the value with the total number of metric values to be calculated. 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 values to be calculated.

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

  • pMetricValues – [in,out][optional][range(0, *pTotalMetricValueCount)] buffer of calculated metrics. if count is less than the number available in the raw data buffer, then driver shall only calculate that number of metric values.

Returns:

zetMetricGroupGetGlobalTimestampsExp#

Added in version 1.5

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupGetGlobalTimestampsExp(zet_metric_group_handle_t hMetricGroup, ze_bool_t synchronizedWithHost, uint64_t *globalTimestamp, uint64_t *metricTimestamp)#

Returns metric timestamps synchronized with either host or device timestamps at the time of invoking the function.

  • The application may call this function from simultaneous threads.

Parameters:

  • hMetricGroup – [in] handle of the metric group

  • synchronizedWithHost – [in] if set to true, the globalTimestamp will reflect the host timestamp, else will reflect the device timestamp.

  • globalTimestamp – [out] if synchronizedWithHost is false, timestamp is in tick counts. [out] if synchronizedWithHost is true, the timestamp is in nanoseconds.

  • metricTimestamp – [out] Metric timestamp in tick counts.

Returns:

zetMetricGroupGetExportDataExp#

Added in version 1.6

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupGetExportDataExp(zet_metric_group_handle_t hMetricGroup, const uint8_t *pRawData, size_t rawDataSize, size_t *pExportDataSize, uint8_t *pExportData)#

Export Metrics Data for system independent calculation.

  • This function exports raw data and necessary information to perform metrics calculation of collected data in a different system than where data was collected, which may or may not have accelerators.

  • Implementations can choose to describe the data arrangement of the exported data, using any mechanism which allows users to read and process them.

  • The application may call this function from simultaneous threads.

Parameters:

  • hMetricGroup – [in] handle of the metric group

  • pRawData – [in] buffer of raw data

  • rawDataSize – [in] size in bytes of raw data buffer

  • pExportDataSize – [in,out] size in bytes of export data buffer if size is zero, then the driver shall update the value with the number of bytes necessary to store the exported data. if size is greater than required, then the driver shall update the value with the actual number of bytes necessary to store the exported data.

  • pExportData – [in,out][optional][range(0, *pExportDataSize)] buffer of exported data.

Returns:

zetMetricGroupCalculateMetricExportDataExp#

Added in version 1.6

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupCalculateMetricExportDataExp(ze_driver_handle_t hDriver, zet_metric_group_calculation_type_t type, size_t exportDataSize, const uint8_t *pExportData, zet_metric_calculate_exp_desc_t *pCalculateDescriptor, uint32_t *pSetCount, uint32_t *pTotalMetricValueCount, uint32_t *pMetricCounts, zet_typed_value_t *pMetricValues)#

Calculate one or more sets of metric values from exported raw data.

  • Calculate metrics values using exported data returned by zetMetricGroupGetExportDataExp.

  • This function is similar to zetMetricGroupCalculateMultipleMetricValuesExp except it would calculate from exported metric data.

  • This function could be used to calculate metrics on a system different from where the metric raw data was collected.

  • The application may call this function from simultaneous threads.

Parameters:

  • hDriver – [in] handle of the driver instance

  • type – [in] calculation type to be applied on raw data

  • exportDataSize – [in] size in bytes of exported data buffer

  • pExportData – [in][range(0, exportDataSize)] buffer of exported data to calculate

  • pCalculateDescriptor – [in] descriptor specifying calculation specific parameters

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

  • pTotalMetricValueCount – [in,out] pointer to number of the total number of metric values calculated, for all metric sets. if count is zero, then the driver shall update the value with the total number of metric values to be calculated. 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 values to be calculated.

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

  • pMetricValues – [in,out][optional][range(0, *pTotalMetricValueCount)] buffer of calculated metrics. if count is less than the number available in the raw data buffer, then driver shall only calculate that number of metric values.

Returns:

zetMetricGroupCreateExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupCreateExp(zet_device_handle_t hDevice, const char *pName, const char *pDescription, zet_metric_group_sampling_type_flags_t samplingType, zet_metric_group_handle_t *phMetricGroup)#

Create metric group handle.

Parameters:

  • hDevice – [in] handle of the device

  • pName – [in] pointer to metric group name. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_GROUP_NAME.

  • pDescription – [in] pointer to metric group description. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_GROUP_DESCRIPTION.

  • samplingType – [in] Sampling type for the metric group.

  • phMetricGroup – [in,out] Created Metric group handle

Returns:

zetMetricGroupAddMetricExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupAddMetricExp(zet_metric_group_handle_t hMetricGroup, zet_metric_handle_t hMetric, size_t *pErrorStringSize, char *pErrorString)#

Add a metric handle to the metric group handle created using zetDeviceCreateMetricGroupsFromMetricsExp.

  • Reasons for failing to add the metric could be queried using pErrorString

  • Multiple additions of same metric would add the metric only once to the hMetricGroup

  • Metric handles from multiple domains may be used in a single metric group.

  • Metric handles from different sourceIds (refer zet_metric_programmable_exp_properties_t) are not allowed in a single metric group.

Parameters:

  • hMetricGroup – [in] Handle of the metric group

  • hMetric – [in] Metric to be added to the group.

  • pErrorStringSize – [in,out][optional] Size of the error string to query, if an error was reported during adding the metric handle. if *pErrorStringSize is zero, then the driver shall update the value with the size of the error string in bytes.

  • pErrorString – [in,out][optional][range(0, *pErrorStringSize)] Error string. if *pErrorStringSize is less than the length of the error string available, then driver shall only retrieve that length of error string.

Returns:

zetMetricGroupRemoveMetricExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupRemoveMetricExp(zet_metric_group_handle_t hMetricGroup, zet_metric_handle_t hMetric)#

Remove a metric from the metric group handle created using zetDeviceCreateMetricGroupsFromMetricsExp.

  • Remove an already added metric handle from the metric group.

Parameters:

  • hMetricGroup – [in] Handle of the metric group

  • hMetric – [in] Metric handle to be removed from the metric group.

Returns:

zetMetricGroupCloseExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupCloseExp(zet_metric_group_handle_t hMetricGroup)#

Closes a created metric group using zetDeviceCreateMetricGroupsFromMetricsExp, so that it can be activated.

Parameters:

hMetricGroup – [in] Handle of the metric group

Returns:

zetMetricGroupDestroyExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupDestroyExp(zet_metric_group_handle_t hMetricGroup)#

Destroy a metric group created using zetDeviceCreateMetricGroupsFromMetricsExp.

Parameters:

hMetricGroup – [in] Handle of the metric group to destroy

Returns:

Metric Group - Experimental Enums#

zet_metric_group_type_exp_flags_t#

Added in version 1.13

enum zet_metric_group_type_exp_flag_t#

Values:

enumerator ZET_METRIC_GROUP_TYPE_EXP_FLAG_EXPORT_DMA_BUF#

Metric group and metrics exports memory using linux dma-buf, which could be imported/mapped to the host process. Properties of the dma_buf could be queried using zet_export_dma_buf_exp_properties_t.

enumerator ZET_METRIC_GROUP_TYPE_EXP_FLAG_USER_CREATED#

Metric group created using zetDeviceCreateMetricGroupsFromMetricsExp.

enumerator ZET_METRIC_GROUP_TYPE_EXP_FLAG_OTHER#

Metric group which has a collection of metrics.

enumerator ZET_METRIC_GROUP_TYPE_EXP_FLAG_MARKER#

Metric group is capable of generating Marker metric.

enumerator ZET_METRIC_GROUP_TYPE_EXP_FLAG_FORCE_UINT32#

Value marking end of ZET_METRIC_GROUP_TYPE_EXP_FLAG_* ENUMs.

Metric Group - Experimental Structures#

zet_metric_group_type_exp_t#

Added in version 1.0

struct zet_metric_group_type_exp_t#

Query the metric group type using pNext of zet_metric_group_properties_t.

Public Members

zet_structure_type_t stype#

[in] type of this structure

void *pNext#

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

zet_metric_group_type_exp_flags_t type#

[out] metric group type. returns a combination of zet_metric_group_type_exp_flags_t.

zet_metric_source_id_exp_t#

Added in version 1.13

struct zet_metric_source_id_exp_t#

Query the metric source unique identifier using pNext of zet_metric_group_properties_t.

Public Members

zet_structure_type_t stype#

[in] type of this structure

void *pNext#

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

uint32_t sourceId#

[out] unique number representing the Metric Source.