Metric Group

oneAPI Level Zero Specification - Version 1.18.31

Metric Group Functions

zetMetricGroupGet

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupGet(zet_device_handle_t hDevice, uint32_t *pCount, zet_metric_group_handle_t *phMetricGroups)

Retrieves metric group for a device.

• The application may call this function from simultaneous threads.

Parameters:

• hDevice – [in] handle of the device

• pCount – [in,out] pointer to the number of metric groups. if count is zero, then the driver shall update the value with the total number of metric groups available. if count is greater than the number of metric groups available, then the driver shall update the value with the correct number of metric groups available.

• phMetricGroups – [in,out][optional][range(0, *pCount)] array of handle of metric groups. if count is less than the number of metric groups available, then driver shall only retrieve that number of metric groups.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zetMetricGroupGetProperties

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupGetProperties(zet_metric_group_handle_t hMetricGroup, zet_metric_group_properties_t *pProperties)

Retrieves attributes of a metric group.

• The application may call this function from simultaneous threads.

Parameters:

• hMetricGroup – [in] handle of the metric group

• pProperties – [in,out] metric group properties

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hMetricGroup

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pProperties

zetMetricGroupCalculateMetricValues

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGroupCalculateMetricValues(zet_metric_group_handle_t hMetricGroup, zet_metric_group_calculation_type_t type, size_t rawDataSize, const uint8_t *pRawData, uint32_t *pMetricValueCount, zet_typed_value_t *pMetricValues)

Calculates metric values from raw data.

• 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

• pMetricValueCount – [in,out] pointer to number of metric values calculated. 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.

• pMetricValues – [in,out][optional][range(0, *pMetricValueCount)] 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:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hMetricGroup

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZET_METRIC_GROUP_CALCULATION_TYPE_MAX_METRIC_VALUES < type

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pRawData

  • nullptr == pMetricValueCount

Metric Group Enums

zet_metric_group_sampling_type_flags_t

Added in version 1.0

enum zet_metric_group_sampling_type_flag_t

Values:

enumerator ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_EVENT_BASED

Event based sampling.

enumerator ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_TIME_BASED

Time based sampling.

enumerator ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_EXP_TRACER_BASED

Experimental Tracer based sampling. (since v1.10)

enumerator ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_FORCE_UINT32

Value marking end of ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_* ENUMs.

zet_metric_group_calculation_type_t

Added in version 1.0

enum zet_metric_group_calculation_type_t

Metric group calculation type.

Values:

enumerator ZET_METRIC_GROUP_CALCULATION_TYPE_METRIC_VALUES

Calculated metric values from raw data.

enumerator ZET_METRIC_GROUP_CALCULATION_TYPE_MAX_METRIC_VALUES

Maximum metric values.

enumerator ZET_METRIC_GROUP_CALCULATION_TYPE_FORCE_UINT32

Value marking end of ZET_METRIC_GROUP_CALCULATION_TYPE_* ENUMs.

Metric Group Structures

zet_metric_group_properties_t

Added in version 1.0

struct zet_metric_group_properties_t

Metric group properties queried using zetMetricGroupGetProperties.

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

char name[ZET_MAX_METRIC_GROUP_NAME]

[out] metric group name

char description[ZET_MAX_METRIC_GROUP_DESCRIPTION]

[out] metric group description

zet_metric_group_sampling_type_flags_t samplingType

[out] metric group sampling type. returns a combination of zet_metric_group_sampling_type_flag_t.

uint32_t domain

[out] metric group domain number. Cannot use multiple, simultaneous metric groups from the same domain.

uint32_t metricCount

[out] metric count belonging to this group