Metric - Experimental

oneAPI Level Zero Specification - Version 1.18.31

Metric - Experimental Functions

zetMetricCreateFromProgrammableExp

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricCreateFromProgrammableExp(zet_metric_programmable_exp_handle_t hMetricProgrammable, zet_metric_programmable_param_value_exp_t *pParameterValues, uint32_t parameterCount, const char *pName, const char *pDescription, uint32_t *pMetricHandleCount, zet_metric_handle_t *phMetricHandles)

Create metric handles by applying parameter values on the metric programmable handle.

• This API is deprecated. Please use zetMetricCreateFromProgrammableExp2()

Parameters:

• hMetricProgrammable – [in] handle of the metric programmable

• pParameterValues – [in] list of parameter values to be set.

• parameterCount – [in] Count of parameters to set.

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

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

• pMetricHandleCount – [in,out] Pointer to the number of metric handles. if count is zero, then the driver shall update the value with the number of metric handles available for this programmable. if count is greater than the number of metric handles available, then the driver shall update the value with the correct number of metric handles available.

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

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 == hMetricProgrammable

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pParameterValues

  • nullptr == pName

  • nullptr == pDescription

  • nullptr == pMetricHandleCount

zetMetricDestroyExp

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricDestroyExp(zet_metric_handle_t hMetric)

Destroy a metric created using zetMetricCreateFromProgrammableExp2.

• If a metric is added to a metric group, the metric has to be removed using zetMetricGroupRemoveMetricExp before it can be destroyed.

Parameters:

hMetric – [in] Handle of the metric to destroy

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_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 == hMetric

• ZE_RESULT_ERROR_INVALID_ARGUMENT

  • If trying to destroy a metric from pre-defined metric group

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

  • If trying to destroy a metric currently added to a metric group

zetMetricCreateFromProgrammableExp2

Added in version 1.11

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricCreateFromProgrammableExp2(zet_metric_programmable_exp_handle_t hMetricProgrammable, uint32_t parameterCount, zet_metric_programmable_param_value_exp_t *pParameterValues, const char *pName, const char *pDescription, uint32_t *pMetricHandleCount, zet_metric_handle_t *phMetricHandles)

Create metric handles by applying parameter values on the metric programmable handle.

• Multiple parameter values could be used to prepare a metric.

• If parameterCount = 0, the default value of the metric programmable would be used for all parameters.

• The implementation can post-fix a C string to the metric name and description, based on the parameter values chosen.

• zetMetricProgrammableGetParamInfoExp() returns a list of parameters in a defined order.

• Therefore, the list of values passed in to the API should respect the same order such that the desired parameter is set with expected value

Parameters:

• hMetricProgrammable – [in] handle of the metric programmable

• parameterCount – [in] Count of parameters to set.

• pParameterValues – [in] list of parameter values to be set.

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

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

• pMetricHandleCount – [in,out] Pointer to the number of metric handles. if count is zero, then the driver shall update the value with the number of metric handles available for this programmable. if count is greater than the number of metric handles available, then the driver shall update the value with the correct number of metric handles available.

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

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 == hMetricProgrammable

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pParameterValues

  • nullptr == pName

  • nullptr == pDescription

  • nullptr == pMetricHandleCount

Metric - Experimental Structures

zet_metric_global_timestamps_resolution_exp_t

Added in version 1.5

struct zet_metric_global_timestamps_resolution_exp_t

Metric timestamps resolution.

• This structure may be returned from zetMetricGroupGetProperties via the pNext member of zet_metric_group_properties_t.

• Used for mapping metric timestamps to other timers.

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

uint64_t timerResolution

[out] Returns the resolution of metrics timer (used for timestamps) in cycles/sec.

uint64_t timestampValidBits

[out] Returns the number of valid bits in the timestamp value. (i.e can be used to calculate the max value of the hardware timestamp register or can be use to generate the mask of valid bits in the timestamp value)

zet_metric_calculate_exp_desc_t

Added in version 1.6

struct zet_metric_calculate_exp_desc_t

Metrics calculation 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 rawReportSkipCount

[in] number of reports to skip during calculation

zet_export_dma_buf_exp_properties_t

Added in version 1.0

struct zet_export_dma_buf_exp_properties_t

Exported dma_buf properties queried using pNext of zet_metric_group_properties_t or zet_metric_properties_t.

• This structure must be passed via the pNext member of zet_metric_group_properties_t or zet_metric_properties_t

• The implementation retains ownership of fd for its entire lifetime. The application must not close fd; it is closed by the implementation when the metric or metric group that exported it is destroyed, or when metrics are disabled on the device.

• The application must free any allocation it imported from fd before destroying the exporting metric or metric group, or disabling metrics on the device. Otherwise the imported allocation outlives fd and any subsequent use of it is undefined.

• fd refers to a shared resource. The same fd may be reported by repeated queries and by queries on different metric or metric group handles. The implementation performs no synchronization on fd or on the memory it exports; if the application uses either from more than one thread it must serialize that access itself, for example with a mutex or by confining access to a single thread.

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

int fd

[out] the file descriptor handle provided for importing memory by the host process. Owned by the implementation; must not be closed by the application.

size_t size

[out] size in bytes of the dma_buf