Tools API

oneAPI Level Zero Specification - Version 0.95.0

Common

Common Enums

zet_structure_type_t

enum zet_structure_type_t

Defines structure types.

Values:

ZET_STRUCTURE_TYPE_METRIC_GROUP_PROPERTIES = 0x1

zet_metric_group_properties_t

ZET_STRUCTURE_TYPE_METRIC_PROPERTIES

zet_metric_properties_t

ZET_STRUCTURE_TYPE_METRIC_STREAMER_DESC

zet_metric_streamer_desc_t

ZET_STRUCTURE_TYPE_METRIC_QUERY_POOL_DESC

zet_metric_query_pool_desc_t

ZET_STRUCTURE_TYPE_PROFILE_PROPERTIES

zet_profile_properties_t

ZET_STRUCTURE_TYPE_TRACER_DESC

zet_tracer_desc_t

Common Structures

zet_base_properties_t

struct zet_base_properties_t

Base for all properties types.

Public Members

zet_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

zet_base_desc_t

struct zet_base_desc_t

Base for all descriptor types.

Public Members

zet_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

Metric

Metric Functions

zetMetricGroupGet

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.

Parameters

  • hDevice: handle of the device

  • pCount: pointer to the number of metric groups. if count is zero, then the driver will update the value with the total number of metric groups available. if count is non-zero, then driver will only retrieve that number of metric groups. if count is larger than the number of metric groups available, then the driver will update the value with the correct number of metric groups available.

  • phMetricGroups: [optional][range(0, *pCount)] array of handle of metric groups

  • The application may call this function from simultaneous threads.

Return

zetMetricGroupGetProperties

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.

Parameters

  • hMetricGroup: handle of the metric group

  • pProperties: metric group properties

  • The application may call this function from simultaneous threads.

Return

zetMetricGroupCalculateMetricValues

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

Calculates metric values from raw data.

Parameters

  • hMetricGroup: handle of the metric group

  • rawDataSize: size in bytes of raw data buffer

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

  • pMetricValueCount: pointer to number of metric values calculated. if count is zero, then the driver will update the value with the total number of metric values to be calculated. if count is non-zero, then driver will only calculate that number of metric values. if count is larger than the number available in the raw data buffer, then the driver will update the value with the actual number of metric values to be calculated.

  • pMetricValues: [optional][range(0, *pMetricValueCount)] buffer of calculated metrics

  • The application may call this function from simultaneous threads.

Return

zetMetricGet

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGet(zet_metric_group_handle_t hMetricGroup, uint32_t *pCount, zet_metric_handle_t *phMetrics)

Retrieves metric from a metric group.

Parameters

  • hMetricGroup: handle of the metric group

  • pCount: pointer to the number of metrics. if count is zero, then the driver will update the value with the total number of metrics available. if count is non-zero, then driver will only retrieve that number of metrics. if count is larger than the number of metrics available, then the driver will update the value with the correct number of metrics available.

  • phMetrics: [optional][range(0, *pCount)] array of handle of metrics

  • The application may call this function from simultaneous threads.

Return

zetMetricGetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricGetProperties(zet_metric_handle_t hMetric, zet_metric_properties_t *pProperties)

Retrieves attributes of a metric.

Parameters

  • hMetric: handle of the metric

  • pProperties: metric properties

  • The application may call this function from simultaneous threads.

Return

zetDeviceActivateMetricGroups

ZE_APIEXPORT ze_result_t ZE_APICALL zetDeviceActivateMetricGroups(zet_device_handle_t hDevice, uint32_t count, zet_metric_group_handle_t *phMetricGroups)

Activates metric groups.

Parameters

  • hDevice: handle of the device

  • count: metric group count to activate; must be 0 if nullptr == phMetricGroups

  • phMetricGroups: [optional][range(0, count)] handles of the metric groups to activate. nullptr to deactivate all.

  • Immediately reconfigures the device to activate only those metric groups provided.

  • Any metric groups previously activated but not provided will be deactivated.

  • Deactivating metric groups that are still in-use will result in undefined behavior.

  • All metric groups must have different domains, see zet_metric_group_properties_t.

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

Return

zetMetricStreamerOpen

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerOpen(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.

Parameters

  • hDevice: handle of the device

  • hMetricGroup: handle of the metric group

  • desc: metric streamer descriptor

  • hNotificationEvent: [optional] event used for report availability notification

  • phMetricStreamer: handle of metric streamer

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

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

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

Return

zetCommandListAppendMetricStreamerMarker

ZE_APIEXPORT ze_result_t ZE_APICALL zetCommandListAppendMetricStreamerMarker(zet_command_list_handle_t hCommandList, zet_metric_streamer_handle_t hMetricStreamer, uint32_t value)

Append metric streamer marker into a command list.

Parameters

  • hCommandList: handle of the command list

  • hMetricStreamer: handle of the metric streamer

  • value: streamer marker value

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

Return

zetMetricStreamerClose

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerClose(zet_metric_streamer_handle_t hMetricStreamer)

Closes metric streamer.

Parameters

  • hMetricStreamer: [release] handle of the metric streamer

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

Return

zetMetricStreamerReadData

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.

Parameters

  • hMetricStreamer: handle of the metric streamer

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

  • pRawDataSize: pointer to size in bytes of raw data requested to read. if size is zero, then the driver will update the value with the total size in bytes needed for all reports available. if size is non-zero, then driver will only retrieve the number of reports that fit into the buffer. if size is larger than size needed for all reports, then driver will update the value with the actual size needed.

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

  • The application may call this function from simultaneous threads.

Return

zetMetricQueryPoolCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryPoolCreate(zet_device_handle_t hDevice, zet_metric_group_handle_t hMetricGroup, const zet_metric_query_pool_desc_t *desc, zet_metric_query_pool_handle_t *phMetricQueryPool)

Creates a pool of metric queries.

Parameters

  • hDevice: handle of the device

  • hMetricGroup: metric group associated with the query object.

  • desc: metric query pool descriptor

  • phMetricQueryPool: handle of metric query pool

  • The application may call this function from simultaneous threads.

Return

zetMetricQueryPoolDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryPoolDestroy(zet_metric_query_pool_handle_t hMetricQueryPool)

Deletes a query pool object.

Parameters

  • hMetricQueryPool: [release] handle of the metric query pool

  • The application must destroy all query handles created from the pool before destroying the pool itself

  • The application must ensure the device is not currently referencing the any query within the pool before it is deleted

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

Return

zetMetricQueryCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryCreate(zet_metric_query_pool_handle_t hMetricQueryPool, uint32_t index, zet_metric_query_handle_t *phMetricQuery)

Creates metric query object.

Parameters

  • hMetricQueryPool: handle of the metric query pool

  • index: index of the query within the pool

  • phMetricQuery: handle of metric query

  • The application may call this function from simultaneous threads.

Return

zetMetricQueryDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryDestroy(zet_metric_query_handle_t hMetricQuery)

Deletes a metric query object.

Parameters

  • hMetricQuery: [release] handle of metric query

  • The application must ensure the device is not currently referencing the query before it is deleted

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

Return

zetMetricQueryReset

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryReset(zet_metric_query_handle_t hMetricQuery)

Resets a metric query object back to inital state.

Parameters

  • hMetricQuery: handle of metric query

  • The application must ensure the device is not currently referencing the query before it is reset

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

Return

zetCommandListAppendMetricQueryBegin

ZE_APIEXPORT ze_result_t ZE_APICALL zetCommandListAppendMetricQueryBegin(zet_command_list_handle_t hCommandList, zet_metric_query_handle_t hMetricQuery)

Appends metric query begin into a command list.

Parameters

  • hCommandList: handle of the command list

  • hMetricQuery: handle of the metric query

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

Return

zetCommandListAppendMetricQueryEnd

ZE_APIEXPORT ze_result_t ZE_APICALL zetCommandListAppendMetricQueryEnd(zet_command_list_handle_t hCommandList, zet_metric_query_handle_t hMetricQuery, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)

Appends metric query end into a command list.

Parameters

  • hCommandList: handle of the command list

  • hMetricQuery: handle of the metric query

  • hSignalEvent: [optional] handle of the event to signal on completion

  • numWaitEvents: [optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents: [optional][range(0, numWaitEvents)] handle of the events to wait on before launching

  • The signal event must not have been created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.

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

Return

zetCommandListAppendMetricMemoryBarrier

ZE_APIEXPORT ze_result_t ZE_APICALL zetCommandListAppendMetricMemoryBarrier(zet_command_list_handle_t hCommandList)

Appends metric query commands to flush all caches.

Parameters

  • hCommandList: handle of the command list

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

Return

zetMetricQueryGetData

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryGetData(zet_metric_query_handle_t hMetricQuery, size_t *pRawDataSize, uint8_t *pRawData)

Retrieves raw data for a given metric query.

Parameters

  • hMetricQuery: handle of the metric query

  • pRawDataSize: pointer to size in bytes of raw data requested to read. if size is zero, then the driver will update the value with the total size in bytes needed for all reports available. if size is non-zero, then driver will only retrieve the number of reports that fit into the buffer. if size is larger than size needed for all reports, then driver will update the value with the actual size needed.

  • pRawData: [optional][range(0, *pRawDataSize)] buffer containing query reports in raw format

  • The application may call this function from simultaneous threads.

Return

Metric Enums

zet_metric_group_sampling_type_t

enum zet_metric_group_sampling_type_t

Metric group sampling type.

Values:

ZET_METRIC_GROUP_SAMPLING_TYPE_EVENT_BASED = ZE_BIT(0)

Event based sampling.

ZET_METRIC_GROUP_SAMPLING_TYPE_TIME_BASED = ZE_BIT(1)

Time based sampling.

zet_metric_type_t

enum zet_metric_type_t

Metric types.

Values:

ZET_METRIC_TYPE_DURATION

Metric type: duration.

ZET_METRIC_TYPE_EVENT

Metric type: event.

ZET_METRIC_TYPE_EVENT_WITH_RANGE

Metric type: event with range.

ZET_METRIC_TYPE_THROUGHPUT

Metric type: throughput.

ZET_METRIC_TYPE_TIMESTAMP

Metric type: timestamp.

ZET_METRIC_TYPE_FLAG

Metric type: flag.

ZET_METRIC_TYPE_RATIO

Metric type: ratio.

ZET_METRIC_TYPE_RAW

Metric type: raw.

zet_value_type_t

enum zet_value_type_t

Supported value types.

Values:

ZET_VALUE_TYPE_UINT32

32-bit unsigned-integer

ZET_VALUE_TYPE_UINT64

64-bit unsigned-integer

ZET_VALUE_TYPE_FLOAT32

32-bit floating-point

ZET_VALUE_TYPE_FLOAT64

64-bit floating-point

ZET_VALUE_TYPE_BOOL8

8-bit boolean

zet_metric_query_pool_flag_t

enum zet_metric_query_pool_flag_t

Metric query pool types.

Values:

ZET_METRIC_QUERY_POOL_FLAG_PERFORMANCE

Performance metric query pool.

ZET_METRIC_QUERY_POOL_FLAG_SKIP_EXECUTION

Skips workload execution between begin/end calls.

Metric Structures

zet_metric_group_properties_t

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] pointer to extension-specific structure

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_t samplingType

[out] metric group sampling type

uint32_t domain

[out] metric group domain number. Cannot use simultaneous metric groups from different domains.

uint32_t maxCommandQueueGroupOrdinal

[out] streamers and queries of this metric group cannot be submitted to a command queue group with a larger ordinal value. See ze_command_queue_desc_t for more information on how to specify the command queue’s group ordinal.

uint32_t metricCount

[out] metric count belonging to this group

zet_value_t

union zet_value_t
#include <zet_api.h>

Union of values.

Public Members

uint32_t ui32

[out] 32-bit unsigned-integer

uint64_t ui64

[out] 32-bit unsigned-integer

float fp32

[out] 32-bit floating-point

double fp64

[out] 64-bit floating-point

ze_bool_t b8

[out] 8-bit boolean

zet_typed_value_t

struct zet_typed_value_t

Typed value.

Public Members

zet_value_type_t type

[out] type of value

zet_value_t value

[out] value

zet_metric_properties_t

struct zet_metric_properties_t

Metric properties queried using zetMetricGetProperties.

Public Members

zet_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

char name[ZET_MAX_METRIC_NAME]

[out] metric name

char description[ZET_MAX_METRIC_DESCRIPTION]

[out] metric description

char component[ZET_MAX_METRIC_COMPONENT]

[out] metric component

uint32_t tierNumber

[out] number of tier

zet_metric_type_t metricType

[out] metric type

zet_value_type_t resultType

[out] metric result type

char resultUnits[ZET_MAX_METRIC_RESULT_UNITS]

[out] metric result units

zet_metric_streamer_desc_t

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] pointer to extension-specific structure

uint32_t notifyEveryNReports

[in,out] number of collected reports after which notification event will be signalled

uint32_t samplingPeriod

[in,out] streamer sampling period in nanoseconds

zet_metric_query_pool_desc_t

struct zet_metric_query_pool_desc_t

Metric query pool description.

Public Members

zet_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

zet_metric_query_pool_flag_t flags

[in] Query pool type.

uint32_t count

[in] Internal slots count within query pool object.

Module

Module Functions

zetModuleGetDebugInfo

ZE_APIEXPORT ze_result_t ZE_APICALL zetModuleGetDebugInfo(zet_module_handle_t hModule, zet_module_debug_info_format_t format, size_t *pSize, uint8_t *pDebugInfo)

Retrieve debug info from module.

Parameters

  • hModule: handle of the module

  • format: debug info format requested

  • pSize: size of debug info in bytes

  • pDebugInfo: [optional] byte pointer to debug info

  • The caller can pass nullptr for pDebugInfo when querying only for size.

  • The implementation will copy the native binary into a buffer supplied by the caller.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Return

Module Enums

zet_module_debug_info_format_t

enum zet_module_debug_info_format_t

Supported module debug info formats.

Values:

ZET_MODULE_DEBUG_INFO_FORMAT_ELF_DWARF

Format is ELF/DWARF.

Pin

Pin Functions

zetKernelGetProfileInfo

ZE_APIEXPORT ze_result_t ZE_APICALL zetKernelGetProfileInfo(zet_kernel_handle_t hKernel, zet_profile_properties_t *pProfileProperties)

Retrieve profiling information generated for the kernel.

Parameters

  • hKernel: handle to kernel

  • pProfileProperties: pointer to profile properties

  • Module must be created using the following build option:

    • ”-zet-profile-flags <n>” - enable generation of profile information

    • ”<n>” must be a combination of zet_profile_flag_t, in hex

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Return

Pin Enums

zet_profile_flag_t

enum zet_profile_flag_t

Supportted profile features.

Values:

ZET_PROFILE_FLAG_REGISTER_REALLOCATION = ZE_BIT(0)

possible to allow for instrumentation

request the compiler attempt to minimize register usage as much as

ZET_PROFILE_FLAG_FREE_REGISTER_INFO = ZE_BIT(1)

request the compiler generate free register info

zet_profile_token_type_t

enum zet_profile_token_type_t

Supported profile token types.

Values:

ZET_PROFILE_TOKEN_TYPE_FREE_REGISTER

GRF info.

Pin Structures

zet_profile_properties_t

struct zet_profile_properties_t

Profiling meta-data for instrumentation.

Public Members

zet_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] pointer to extension-specific structure

zet_profile_flag_t flags

[out] indicates which flags were enabled during compilation

uint32_t numTokens

[out] number of tokens immediately following this structure

zet_profile_free_register_token_t

struct zet_profile_free_register_token_t

Profile free register token detailing unused registers in the current function.

Public Members

zet_profile_token_type_t type

[out] type of token

uint32_t size

[out] total size of the token, in bytes

uint32_t count

[out] number of register sequences immediately following this structure

zet_profile_register_sequence_t

struct zet_profile_register_sequence_t

Profile register sequence detailing consecutive bytes, all of which are unused.

Public Members

uint32_t start

[out] starting byte in the register table, representing the start of unused bytes in the current function

uint32_t count

[out] number of consecutive bytes in the sequence, starting from start

Tracing

Tracing Functions

zetTracerCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerCreate(zet_driver_handle_t hDriver, const zet_tracer_desc_t *desc, zet_tracer_handle_t *phTracer)

Creates a tracer for the specified driver.

Parameters

  • hDriver: handle of the driver

  • desc: pointer to tracer descriptor

  • phTracer: pointer to handle of tracer object created

  • The tracer can only be used on the driver on which it was created.

  • The tracer is created in the disabled state.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Return

zetTracerDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerDestroy(zet_tracer_handle_t hTracer)

Destroys a tracer.

Parameters

  • hTracer: [release] handle of tracer object to destroy

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

  • The implementation of this function will stall and wait on any outstanding threads executing callbacks before freeing any Host allocations associated with this tracer.

Return

zetTracerSetPrologues

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerSetPrologues(zet_tracer_handle_t hTracer, zet_core_callbacks_t *pCoreCbs)

Sets the collection of callbacks to be executed before driver execution.

Parameters

  • hTracer: handle of the tracer

  • pCoreCbs: pointer to table of ‘core’ callback function pointers

  • The application only needs to set the function pointers it is interested in receiving; all others should be ‘nullptr’

  • The application must ensure that no other threads are executing functions for which the tracing functions are changing.

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

Return

zetTracerSetEpilogues

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerSetEpilogues(zet_tracer_handle_t hTracer, zet_core_callbacks_t *pCoreCbs)

Sets the collection of callbacks to be executed after driver execution.

Parameters

  • hTracer: handle of the tracer

  • pCoreCbs: pointer to table of ‘core’ callback function pointers

  • The application only needs to set the function pointers it is interested in receiving; all others should be ‘nullptr’

  • The application must ensure that no other threads are executing functions for which the tracing functions are changing.

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

Return

zetTracerSetEnabled

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerSetEnabled(zet_tracer_handle_t hTracer, ze_bool_t enable)

Enables (or disables) the tracer.

Parameters

  • hTracer: handle of the tracer

  • enable: enable the tracer if true; disable if false

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

Return

Tracing Structures

zet_tracer_desc_t

struct zet_tracer_desc_t

Tracer descriptor.

Public Members

zet_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] pointer to extension-specific structure

void *pUserData

[in] pointer passed to every tracer’s callbacks