Tools API

oneAPI Level Zero Specification - Version 1.4.3

Common

Common Enums

zet_structure_type_t

enum zet_structure_type_t

Defines structure types.

Values:

enumerator ZET_STRUCTURE_TYPE_METRIC_GROUP_PROPERTIES

zet_metric_group_properties_t

enumerator ZET_STRUCTURE_TYPE_METRIC_PROPERTIES

zet_metric_properties_t

enumerator ZET_STRUCTURE_TYPE_METRIC_STREAMER_DESC

zet_metric_streamer_desc_t

enumerator ZET_STRUCTURE_TYPE_METRIC_QUERY_POOL_DESC

zet_metric_query_pool_desc_t

enumerator ZET_STRUCTURE_TYPE_PROFILE_PROPERTIES

zet_profile_properties_t

enumerator ZET_STRUCTURE_TYPE_DEVICE_DEBUG_PROPERTIES

zet_device_debug_properties_t

enumerator ZET_STRUCTURE_TYPE_DEBUG_MEMORY_SPACE_DESC

zet_debug_memory_space_desc_t

enumerator ZET_STRUCTURE_TYPE_DEBUG_REGSET_PROPERTIES

zet_debug_regset_properties_t

enumerator ZET_STRUCTURE_TYPE_TRACER_EXP_DESC

zet_tracer_exp_desc_t

enumerator ZET_STRUCTURE_TYPE_FORCE_UINT32

zet_value_type_t

enum zet_value_type_t

Supported value types.

Values:

enumerator ZET_VALUE_TYPE_UINT32

32-bit unsigned-integer

enumerator ZET_VALUE_TYPE_UINT64

64-bit unsigned-integer

enumerator ZET_VALUE_TYPE_FLOAT32

32-bit floating-point

enumerator ZET_VALUE_TYPE_FLOAT64

64-bit floating-point

enumerator ZET_VALUE_TYPE_BOOL8

8-bit boolean

enumerator ZET_VALUE_TYPE_FORCE_UINT32

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

zet_value_t

union zet_value_t
#include <>

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

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.

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

Parameters

  • hModule – [in] handle of the module

  • format – [in] debug info format requested

  • pSize – [in,out] size of debug info in bytes

  • pDebugInfo – [in,out][optional] byte pointer to debug info

Returns

Module Enums

zet_module_debug_info_format_t

enum zet_module_debug_info_format_t

Supported module debug info formats.

Values:

enumerator ZET_MODULE_DEBUG_INFO_FORMAT_ELF_DWARF

Format is ELF/DWARF.

enumerator ZET_MODULE_DEBUG_INFO_FORMAT_FORCE_UINT32

Debug

Debug Functions

zetDeviceGetDebugProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zetDeviceGetDebugProperties(zet_device_handle_t hDevice, zet_device_debug_properties_t *pDebugProperties)

Retrieves debug properties of the device.

Parameters

  • hDevice – [in] device handle

  • pDebugProperties – [in,out] query result for debug properties

Returns

zetDebugAttach

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugAttach(zet_device_handle_t hDevice, const zet_debug_config_t *config, zet_debug_session_handle_t *phDebug)

Attach to a device.

Parameters

  • hDevice – [in] device handle

  • config – [in] the debug configuration

  • phDebug – [out] debug session handle

Returns

zetDebugDetach

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugDetach(zet_debug_session_handle_t hDebug)

Close a debug session.

Parameters

hDebug – [in][release] debug session handle

Returns

zetDebugReadEvent

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadEvent(zet_debug_session_handle_t hDebug, uint64_t timeout, zet_debug_event_t *event)

Read the topmost debug event.

Parameters

  • hDebug – [in] debug session handle

  • timeout – [in] if non-zero, then indicates the maximum time (in milliseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then immediately returns the status of the event; if UINT64_MAX, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

  • event – [in,out] a pointer to a zet_debug_event_t.

Returns

zetDebugAcknowledgeEvent

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugAcknowledgeEvent(zet_debug_session_handle_t hDebug, const zet_debug_event_t *event)

Acknowledge a debug event.

Parameters

  • hDebug – [in] debug session handle

  • event – [in] a pointer to a zet_debug_event_t.

Returns

zetDebugInterrupt

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugInterrupt(zet_debug_session_handle_t hDebug, ze_device_thread_t thread)

Interrupt device threads.

Parameters

  • hDebug – [in] debug session handle

  • thread – [in] the thread to interrupt

Returns

zetDebugResume

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugResume(zet_debug_session_handle_t hDebug, ze_device_thread_t thread)

Resume device threads.

Parameters

  • hDebug – [in] debug session handle

  • thread – [in] the thread to resume

Returns

zetDebugReadMemory

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadMemory(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, const zet_debug_memory_space_desc_t *desc, size_t size, void *buffer)

Read memory.

  • The thread identifier ‘all’ can be used for accessing the default memory space, e.g. for setting breakpoints.

Parameters

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier.

  • desc – [in] memory space descriptor

  • size – [in] the number of bytes to read

  • buffer – [in,out] a buffer to hold a copy of the memory

Returns

zetDebugWriteMemory

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugWriteMemory(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, const zet_debug_memory_space_desc_t *desc, size_t size, const void *buffer)

Write memory.

  • The thread identifier ‘all’ can be used for accessing the default memory space, e.g. for setting breakpoints.

Parameters

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier.

  • desc – [in] memory space descriptor

  • size – [in] the number of bytes to write

  • buffer – [in] a buffer holding the pattern to write

Returns

zetDebugGetRegisterSetProperties

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugGetRegisterSetProperties(zet_device_handle_t hDevice, uint32_t *pCount, zet_debug_regset_properties_t *pRegisterSetProperties)

Retrieves debug register set properties.

Parameters

  • hDevice – [in] device handle

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

  • pRegisterSetProperties – [in,out][optional][range(0, *pCount)] array of query results for register set properties. if count is less than the number of register set properties available, then driver shall only retrieve that number of register set properties.

Returns

zetDebugReadRegisters

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadRegisters(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, uint32_t type, uint32_t start, uint32_t count, void *pRegisterValues)

Read register state.

Parameters

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier

  • type – [in] register set type

  • start – [in] the starting offset into the register state area; must be less than zet_debug_regset_properties_t.count for the type

  • count – [in] the number of registers to read; start+count must be <= zet_debug_register_group_properties_t.count for the type

  • pRegisterValues – [in,out][optional][range(0, count)] buffer of register values

Returns

zetDebugWriteRegisters

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugWriteRegisters(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, uint32_t type, uint32_t start, uint32_t count, void *pRegisterValues)

Write register state.

Parameters

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier

  • type – [in] register set type

  • start – [in] the starting offset into the register state area; must be less than zet_debug_regset_properties_t.count for the type

  • count – [in] the number of registers to write; start+count must be <= zet_debug_register_group_properties_t.count for the type

  • pRegisterValues – [in,out][optional][range(0, count)] buffer of register values

Returns

Debug Enums

zet_device_debug_property_flags_t

enum zet_device_debug_property_flag_t

Values:

enumerator ZET_DEVICE_DEBUG_PROPERTY_FLAG_ATTACH

the device supports attaching for debug

enumerator ZET_DEVICE_DEBUG_PROPERTY_FLAG_FORCE_UINT32

zet_debug_event_flags_t

enum zet_debug_event_flag_t

Values:

enumerator ZET_DEBUG_EVENT_FLAG_NEED_ACK

The event needs to be acknowledged by calling zetDebugAcknowledgeEvent.

enumerator ZET_DEBUG_EVENT_FLAG_FORCE_UINT32

zet_debug_event_type_t

enum zet_debug_event_type_t

Supported debug event types.

Values:

enumerator ZET_DEBUG_EVENT_TYPE_INVALID

The event is invalid.

enumerator ZET_DEBUG_EVENT_TYPE_DETACHED

The tool was detached.

enumerator ZET_DEBUG_EVENT_TYPE_PROCESS_ENTRY

The debuggee process created command queues on the device.

enumerator ZET_DEBUG_EVENT_TYPE_PROCESS_EXIT

The debuggee process destroyed all command queues on the device.

enumerator ZET_DEBUG_EVENT_TYPE_MODULE_LOAD

An in-memory module was loaded onto the device.

enumerator ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD

An in-memory module is about to get unloaded from the device.

enumerator ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED

The thread stopped due to a device exception.

enumerator ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE

The thread is not available to be stopped.

enumerator ZET_DEBUG_EVENT_TYPE_PAGE_FAULT

A page request could not be completed on the device.

enumerator ZET_DEBUG_EVENT_TYPE_FORCE_UINT32

zet_debug_detach_reason_t

enum zet_debug_detach_reason_t

Supported debug detach reasons.

Values:

enumerator ZET_DEBUG_DETACH_REASON_INVALID

The detach reason is not valid.

enumerator ZET_DEBUG_DETACH_REASON_HOST_EXIT

The host process exited.

enumerator ZET_DEBUG_DETACH_REASON_FORCE_UINT32

zet_debug_page_fault_reason_t

enum zet_debug_page_fault_reason_t

Page fault reasons.

Values:

enumerator ZET_DEBUG_PAGE_FAULT_REASON_INVALID

The page fault reason is not valid.

enumerator ZET_DEBUG_PAGE_FAULT_REASON_MAPPING_ERROR

The address is not mapped.

enumerator ZET_DEBUG_PAGE_FAULT_REASON_PERMISSION_ERROR

Invalid access permissions.

enumerator ZET_DEBUG_PAGE_FAULT_REASON_FORCE_UINT32

zet_debug_memory_space_type_t

enum zet_debug_memory_space_type_t

Supported device memory space types.

Values:

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_DEFAULT

default memory space (attribute may be omitted)

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_SLM

shared local memory space (GPU-only)

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_FORCE_UINT32

zet_debug_regset_flags_t

enum zet_debug_regset_flag_t

Values:

enumerator ZET_DEBUG_REGSET_FLAG_READABLE

register set is readable

enumerator ZET_DEBUG_REGSET_FLAG_WRITEABLE

register set is writeable

enumerator ZET_DEBUG_REGSET_FLAG_FORCE_UINT32

Debug Structures

zet_device_debug_properties_t

struct zet_device_debug_properties_t

Device debug properties queried using zetDeviceGetDebugProperties.

Public Members

zet_structure_type_t stype

[in] type of this structure

void *pNext

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

zet_device_debug_property_flags_t flags

[out] returns 0 (none) or a valid combination of zet_device_debug_property_flag_t

zet_debug_config_t

struct zet_debug_config_t

Debug configuration provided to zetDebugAttach.

Public Members

uint32_t pid

[in] the host process identifier

zet_debug_event_info_detached_t

struct zet_debug_event_info_detached_t

Event information for ZET_DEBUG_EVENT_TYPE_DETACHED.

Public Members

zet_debug_detach_reason_t reason

[out] the detach reason

zet_debug_event_info_module_t

struct zet_debug_event_info_module_t

Event information for ZET_DEBUG_EVENT_TYPE_MODULE_LOAD and ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD.

Public Members

zet_module_debug_info_format_t format

[out] the module format

uint64_t moduleBegin

[out] the begin address of the in-memory module (inclusive)

uint64_t moduleEnd

[out] the end address of the in-memory module (exclusive)

uint64_t load

[out] the load address of the module on the device

zet_debug_event_info_thread_stopped_t

struct zet_debug_event_info_thread_stopped_t

Event information for ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED and ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE.

Public Members

ze_device_thread_t thread

[out] the stopped/unavailable thread

zet_debug_event_info_page_fault_t

struct zet_debug_event_info_page_fault_t

Event information for ZET_DEBUG_EVENT_TYPE_PAGE_FAULT.

Public Members

uint64_t address

[out] the faulting address

uint64_t mask

[out] the alignment mask

zet_debug_page_fault_reason_t reason

[out] the page fault reason

zet_debug_event_t

struct zet_debug_event_t

A debug event on the device.

Public Members

zet_debug_event_type_t type

[out] the event type

zet_debug_event_flags_t flags

[out] returns 0 (none) or a combination of zet_debug_event_flag_t

zet_debug_event_info_t info

[out] event type specific information

zet_debug_memory_space_desc_t

struct zet_debug_memory_space_desc_t

Device memory space descriptor.

Public Members

zet_structure_type_t stype

[in] type of this structure

const void *pNext

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

zet_debug_memory_space_type_t type

[in] type of memory space

uint64_t address

[in] the virtual address within the memory space

zet_debug_regset_properties_t

struct zet_debug_regset_properties_t

Device register set properties queried using zetDebugGetRegisterSetProperties.

Public Members

zet_structure_type_t stype

[in] type of this structure

void *pNext

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

uint32_t type

[out] device-specific register set type

uint32_t version

[out] device-specific version of this register set

zet_debug_regset_flags_t generalFlags

[out] general register set flags

uint32_t deviceFlags

[out] device-specific register set flags

uint32_t count

[out] number of registers in the set

uint32_t bitSize

[out] the size of a register in bits

uint32_t byteSize

[out] the size required for reading or writing a register in bytes

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.

  • 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

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.

  • The application may call this function from simultaneous threads.

Parameters

  • hMetricGroup – [in] handle of the metric group

  • pProperties – [in,out] metric group properties

Returns

zetMetricGroupCalculateMetricValues

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

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.

  • The application may call this function from simultaneous threads.

Parameters

  • hMetricGroup – [in] handle of the metric group

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

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

Returns

zetMetricGetProperties

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

Retrieves attributes of a metric.

  • The application may call this function from simultaneous threads.

Parameters

  • hMetric – [in] handle of the metric

  • pProperties – [in,out] metric properties

Returns

zetContextActivateMetricGroups

ZE_APIEXPORT ze_result_t ZE_APICALL zetContextActivateMetricGroups(zet_context_handle_t hContext, zet_device_handle_t hDevice, uint32_t count, zet_metric_group_handle_t *phMetricGroups)

Activates metric groups.

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

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • count – [in] metric group count to activate; must be 0 if `nullptr == phMetricGroups`

  • phMetricGroups – [in][optional][range(0, count)] handles of the metric groups to activate. nullptr deactivates all previously used metric groups. all metrics groups must come from a different domains. metric query and metric stream must use activated metric groups.

Returns

zetMetricStreamerOpen

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

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

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • hMetricGroup – [in] handle of the metric group

  • desc – [in,out] metric streamer descriptor

  • hNotificationEvent – [in][optional] event used for report availability notification

  • phMetricStreamer – [out] handle of metric streamer

Returns

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.

  • The application must ensure the metric streamer is accessible by the device on which the command list was created.

  • The application must ensure the command list and metric streamer were created on the same context.

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

  • Allow to associate metric stream time based metrics with executed workload.

Parameters

  • hCommandList – [in] handle of the command list

  • hMetricStreamer – [in] handle of the metric streamer

  • value – [in] streamer marker value

Returns

zetMetricStreamerClose

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerClose(zet_metric_streamer_handle_t hMetricStreamer)

Closes metric streamer.

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

Parameters

hMetricStreamer – [in][release] handle of the metric streamer

Returns

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.

  • The application may call this function from simultaneous threads.

Parameters

  • hMetricStreamer – [in] handle of the metric streamer

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

  • pRawDataSize – [in,out] 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 – [in,out][optional][range(0, *pRawDataSize)] buffer containing streamer reports in raw format

Returns

zetMetricQueryPoolCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryPoolCreate(zet_context_handle_t hContext, 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 on the context.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • hMetricGroup – [in] metric group associated with the query object.

  • desc – [in] metric query pool descriptor

  • phMetricQueryPool – [out] handle of metric query pool

Returns

zetMetricQueryPoolDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryPoolDestroy(zet_metric_query_pool_handle_t hMetricQueryPool)

Deletes a query pool object.

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

  • The implementation of this function must be thread-safe.

Parameters

hMetricQueryPool – [in][release] handle of the metric query pool

Returns

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 from the pool.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters

  • hMetricQueryPool – [in] handle of the metric query pool

  • index – [in] index of the query within the pool

  • phMetricQuery – [out] handle of metric query

Returns

zetMetricQueryDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryDestroy(zet_metric_query_handle_t hMetricQuery)

Deletes a metric query object.

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

  • The implementation of this function must be thread-safe.

Parameters

hMetricQuery – [in][release] handle of metric query

Returns

zetMetricQueryReset

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryReset(zet_metric_query_handle_t hMetricQuery)

Resets a metric query object back to inital state.

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

Parameters

hMetricQuery – [in] handle of metric query

Returns

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.

  • The application must ensure the metric query is accessible by the device on which the command list was created.

  • The application must ensure the command list and metric query were created on the same context.

  • This command blocks all following commands from beginning until the execution of the query completes.

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

Parameters

  • hCommandList – [in] handle of the command list

  • hMetricQuery – [in] handle of the metric query

Returns

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.

  • The application must ensure the metric query and events are accessible by the device on which the command list was created.

  • The application must ensure the command list, events and metric query were created on the same context.

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

  • If numWaitEvents is zero, then all previous commands are completed prior to the execution of the query.

  • If numWaitEvents is non-zero, then all phWaitEvents must be signaled prior to the execution of the query.

  • This command blocks all following commands from beginning until the execution of the query completes.

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

Parameters

  • hCommandList – [in] handle of the command list

  • hMetricQuery – [in] handle of the metric query

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

  • numWaitEvents – [in] must be zero

  • phWaitEvents – [in][mbz] must be nullptr

Returns

zetCommandListAppendMetricMemoryBarrier

ZE_APIEXPORT ze_result_t ZE_APICALL zetCommandListAppendMetricMemoryBarrier(zet_command_list_handle_t hCommandList)

Appends metric query commands to flush all caches.

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

Parameters

hCommandList – [in] handle of the command list

Returns

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.

  • The application may call this function from simultaneous threads.

Parameters

  • hMetricQuery – [in] handle of the metric query

  • pRawDataSize – [in,out] 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 – [in,out][optional][range(0, *pRawDataSize)] buffer containing query reports in raw format

Returns

Metric Enums

zet_metric_group_sampling_type_flags_t

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_FORCE_UINT32

zet_metric_type_t

enum zet_metric_type_t

Metric types.

Values:

enumerator ZET_METRIC_TYPE_DURATION

Metric type: duration.

enumerator ZET_METRIC_TYPE_EVENT

Metric type: event.

enumerator ZET_METRIC_TYPE_EVENT_WITH_RANGE

Metric type: event with range.

enumerator ZET_METRIC_TYPE_THROUGHPUT

Metric type: throughput.

enumerator ZET_METRIC_TYPE_TIMESTAMP

Metric type: timestamp.

enumerator ZET_METRIC_TYPE_FLAG

Metric type: flag.

enumerator ZET_METRIC_TYPE_RATIO

Metric type: ratio.

enumerator ZET_METRIC_TYPE_RAW

Metric type: raw.

enumerator ZET_METRIC_TYPE_IP_EXP

Metric type: instruction pointer.

enumerator ZET_METRIC_TYPE_FORCE_UINT32

zet_metric_group_calculation_type_t

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

zet_metric_query_pool_type_t

enum zet_metric_query_pool_type_t

Metric query pool types.

Values:

enumerator ZET_METRIC_QUERY_POOL_TYPE_PERFORMANCE

Performance metric query pool.

enumerator ZET_METRIC_QUERY_POOL_TYPE_EXECUTION

Skips workload execution between begin/end calls.

enumerator ZET_METRIC_QUERY_POOL_TYPE_FORCE_UINT32

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

returns a combination of zet_metric_group_sampling_type_flag_t.

[out] metric group sampling type.

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

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_type_t type

[in] Query pool type.

uint32_t count

[in] Internal slots count within query pool object.

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.

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

Parameters

  • hKernel – [in] handle to kernel

  • pProfileProperties – [out] pointer to profile properties

Returns

Pin Enums

zet_profile_flags_t

enum zet_profile_flag_t

Values:

enumerator ZET_PROFILE_FLAG_REGISTER_REALLOCATION

possible to allow for instrumentation

request the compiler attempt to minimize register usage as much as

enumerator ZET_PROFILE_FLAG_FREE_REGISTER_INFO

request the compiler generate free register info

enumerator ZET_PROFILE_FLAG_FORCE_UINT32

zet_profile_token_type_t

enum zet_profile_token_type_t

Supported profile token types.

Values:

enumerator ZET_PROFILE_TOKEN_TYPE_FREE_REGISTER

GRF info.

enumerator ZET_PROFILE_TOKEN_TYPE_FORCE_UINT32

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_flags_t flags

[out] indicates which flags were enabled during compilation. returns 0 (none) or a combination of zet_profile_flag_t

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

zetTracerExpCreate

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpCreate(zet_context_handle_t hContext, const zet_tracer_exp_desc_t *desc, zet_tracer_exp_handle_t *phTracer)

Creates a tracer on the context.

  • The application must only use the tracer for the context which was provided during creation.

  • The tracer is created in the disabled state.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters

  • hContext – [in] handle of the context object

  • desc – [in] pointer to tracer descriptor

  • phTracer – [out] pointer to handle of tracer object created

Returns

zetTracerExpDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpDestroy(zet_tracer_exp_handle_t hTracer)

Destroys a tracer.

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

  • The implementation of this function must be thread-safe.

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

Parameters

hTracer – [in][release] handle of tracer object to destroy

Returns

zetTracerExpSetPrologues

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpSetPrologues(zet_tracer_exp_handle_t hTracer, zet_core_callbacks_t *pCoreCbs)

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

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

Parameters

  • hTracer – [in] handle of the tracer

  • pCoreCbs – [in] pointer to table of ‘core’ callback function pointers

Returns

zetTracerExpSetEpilogues

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpSetEpilogues(zet_tracer_exp_handle_t hTracer, zet_core_callbacks_t *pCoreCbs)

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

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

Parameters

  • hTracer – [in] handle of the tracer

  • pCoreCbs – [in] pointer to table of ‘core’ callback function pointers

Returns

zetTracerExpSetEnabled

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpSetEnabled(zet_tracer_exp_handle_t hTracer, ze_bool_t enable)

Enables (or disables) the tracer.

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

Parameters

  • hTracer – [in] handle of the tracer

  • enable – [in] enable the tracer if true; disable if false

Returns

Tracing Enums

zet_api_tracing_exp_version_t

enum zet_api_tracing_exp_version_t

API Tracing Experimental Extension Version(s)

Values:

enumerator ZET_API_TRACING_EXP_VERSION_1_0

version 1.0

enumerator ZET_API_TRACING_EXP_VERSION_CURRENT

latest known version

enumerator ZET_API_TRACING_EXP_VERSION_FORCE_UINT32

Tracing Structures

zet_tracer_exp_desc_t

struct zet_tracer_exp_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

Multimetricvalues

Multimetricvalues Functions

zetMetricGroupCalculateMultipleMetricValuesExp

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

Multimetricvalues Enums

ze_calculate_multiple_metrics_exp_version_t

enum ze_calculate_multiple_metrics_exp_version_t

Calculating Multiple Metrics Experimental Extension Version(s)

Values:

enumerator ZE_CALCULATE_MULTIPLE_METRICS_EXP_VERSION_1_0

version 1.0

enumerator ZE_CALCULATE_MULTIPLE_METRICS_EXP_VERSION_CURRENT

latest known version

enumerator ZE_CALCULATE_MULTIPLE_METRICS_EXP_VERSION_FORCE_UINT32