Tools API

oneAPI Level Zero Specification - Version 1.1.2

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 = 0x2

zet_metric_properties_t

ZET_STRUCTURE_TYPE_METRIC_STREAMER_DESC = 0x3

zet_metric_streamer_desc_t

ZET_STRUCTURE_TYPE_METRIC_QUERY_POOL_DESC = 0x4

zet_metric_query_pool_desc_t

ZET_STRUCTURE_TYPE_PROFILE_PROPERTIES = 0x5

zet_profile_properties_t

ZET_STRUCTURE_TYPE_DEVICE_DEBUG_PROPERTIES = 0x6

zet_device_debug_properties_t

ZET_STRUCTURE_TYPE_DEBUG_MEMORY_SPACE_DESC = 0x7

zet_debug_memory_space_desc_t

ZET_STRUCTURE_TYPE_DEBUG_REGSET_PROPERTIES = 0x8

zet_debug_regset_properties_t

ZET_STRUCTURE_TYPE_TRACER_EXP_DESC = 0x00010001

zet_tracer_exp_desc_t

ZET_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff

zet_value_type_t

enum zet_value_type_t

Supported value types.

Values:

ZET_VALUE_TYPE_UINT32 = 0

32-bit unsigned-integer

ZET_VALUE_TYPE_UINT64 = 1

64-bit unsigned-integer

ZET_VALUE_TYPE_FLOAT32 = 2

32-bit floating-point

ZET_VALUE_TYPE_FLOAT64 = 3

64-bit floating-point

ZET_VALUE_TYPE_BOOL8 = 4

8-bit boolean

ZET_VALUE_TYPE_FORCE_UINT32 = 0x7fffffff

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

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: [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

  • 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 = 0

Format is ELF/DWARF.

ZET_MODULE_DEBUG_INFO_FORMAT_FORCE_UINT32 = 0x7fffffff

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

Return

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

Return

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

Return

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.

Return

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

Return

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

Return

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

Return

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.

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

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

Return

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.

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

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

Return

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.

Return

zetDebugReadRegisters

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadRegisters(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, zet_debug_regset_type_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

Return

zetDebugWriteRegisters

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugWriteRegisters(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, zet_debug_regset_type_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

Return

Debug Enums

zet_device_debug_property_flags_t

enum zet_device_debug_property_flag_t

Values:

ZET_DEVICE_DEBUG_PROPERTY_FLAG_ATTACH = ZE_BIT(0)

the device supports attaching for debug

ZET_DEVICE_DEBUG_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff

zet_debug_event_flags_t

enum zet_debug_event_flag_t

Values:

ZET_DEBUG_EVENT_FLAG_NEED_ACK = ZE_BIT(0)

The event needs to be acknowledged by calling zetDebugAcknowledgeEvent.

ZET_DEBUG_EVENT_FLAG_FORCE_UINT32 = 0x7fffffff

zet_debug_event_type_t

enum zet_debug_event_type_t

Supported debug event types.

Values:

ZET_DEBUG_EVENT_TYPE_INVALID = 0

The event is invalid.

ZET_DEBUG_EVENT_TYPE_DETACHED = 1

The tool was detached.

ZET_DEBUG_EVENT_TYPE_PROCESS_ENTRY = 2

The debuggee process created command queues on the device.

ZET_DEBUG_EVENT_TYPE_PROCESS_EXIT = 3

The debuggee process destroyed all command queues on the device.

ZET_DEBUG_EVENT_TYPE_MODULE_LOAD = 4

An in-memory module was loaded onto the device.

ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD = 5

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

ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED = 6

The thread stopped due to a device exception.

ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE = 7

The thread is not available to be stopped.

ZET_DEBUG_EVENT_TYPE_PAGE_FAULT = 8

A page request could not be completed on the device.

ZET_DEBUG_EVENT_TYPE_FORCE_UINT32 = 0x7fffffff

zet_debug_detach_reason_t

enum zet_debug_detach_reason_t

Supported debug detach reasons.

Values:

ZET_DEBUG_DETACH_REASON_INVALID = 0

The detach reason is not valid.

ZET_DEBUG_DETACH_REASON_HOST_EXIT = 1

The host process exited.

ZET_DEBUG_DETACH_REASON_FORCE_UINT32 = 0x7fffffff

zet_debug_page_fault_reason_t

enum zet_debug_page_fault_reason_t

Page fault reasons.

Values:

ZET_DEBUG_PAGE_FAULT_REASON_INVALID = 0

The page fault reason is not valid.

ZET_DEBUG_PAGE_FAULT_REASON_MAPPING_ERROR = 1

The address is not mapped.

ZET_DEBUG_PAGE_FAULT_REASON_PERMISSION_ERROR = 2

Invalid access permissions.

ZET_DEBUG_PAGE_FAULT_REASON_FORCE_UINT32 = 0x7fffffff

zet_debug_memory_space_type_t

enum zet_debug_memory_space_type_t

Supported device memory space types.

Values:

ZET_DEBUG_MEMORY_SPACE_TYPE_DEFAULT = 0

default memory space (attribute may be omitted)

ZET_DEBUG_MEMORY_SPACE_TYPE_SLM = 1

shared local memory space (GPU-only)

ZET_DEBUG_MEMORY_SPACE_TYPE_FORCE_UINT32 = 0x7fffffff

zet_debug_regset_type_t

enum zet_debug_regset_type_t

Supported device register set types.

Values:

ZET_DEBUG_REGSET_TYPE_INVALID = 0

An invalid register set.

ZET_DEBUG_REGSET_TYPE_GPR = 1

The general purpose register set.

ZET_DEBUG_REGSET_TYPE_ACC = 2

The accumulator register set.

ZET_DEBUG_REGSET_TYPE_ADDR = 3

The address register set.

ZET_DEBUG_REGSET_TYPE_FLAG = 4

The flags register set.

ZET_DEBUG_REGSET_TYPE_FORCE_UINT32 = 0x7fffffff

zet_debug_regset_flags_t

enum zet_debug_regset_flag_t

Values:

ZET_DEBUG_REGSET_FLAG_READ_ONLY = ZE_BIT(0)

register set is read-only

ZET_DEBUG_REGSET_FLAG_FORCE_UINT32 = 0x7fffffff

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

uint64_t moduleEnd

[out] the end address of the in-memory module

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

zet_debug_regset_type_t type

[out] register set type

zet_debug_regset_flags_t flags

[out] register set flags

uint32_t count

[out] number of registers in the set

zet_value_type_t valueType

[out] register value type

size_t valueSize

[out] register value size 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.

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.

  • 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: [in] handle of the metric group

  • pProperties: [in,out] 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, 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.

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.

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

  • 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: [in] handle of the metric

  • pProperties: [in,out] metric properties

  • The application may call this function from simultaneous threads.

Return

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.

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.

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

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

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

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: [in] handle of the command list

  • hMetricStreamer: [in] handle of the metric streamer

  • value: [in] streamer marker value

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

Return

zetMetricStreamerClose

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricStreamerClose(zet_metric_streamer_handle_t hMetricStreamer)

Closes metric streamer.

Parameters

  • hMetricStreamer: [in][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: [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

  • The application may call this function from simultaneous threads.

Return

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.

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

  • The application may call this function from simultaneous threads.

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

Return

zetMetricQueryPoolDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryPoolDestroy(zet_metric_query_pool_handle_t hMetricQueryPool)

Deletes a query pool object.

Parameters

  • hMetricQueryPool: [in][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.

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

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

Parameters

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

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

  • phMetricQuery: [out] handle of metric query

  • The application may call this function from simultaneous threads.

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

Return

zetMetricQueryDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetMetricQueryDestroy(zet_metric_query_handle_t hMetricQuery)

Deletes a metric query object.

Parameters

  • hMetricQuery: [in][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.

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

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: [in] 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: [in] handle of the command list

  • hMetricQuery: [in] handle of the metric query

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

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: [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] must be nullptr

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

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: [in] 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: [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

  • The application may call this function from simultaneous threads.

Return

Metric Enums

zet_metric_group_sampling_type_flags_t

enum zet_metric_group_sampling_type_flag_t

Values:

ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_EVENT_BASED = ZE_BIT(0)

Event based sampling.

ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_TIME_BASED = ZE_BIT(1)

Time based sampling.

ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_FORCE_UINT32 = 0x7fffffff

zet_metric_type_t

enum zet_metric_type_t

Metric types.

Values:

ZET_METRIC_TYPE_DURATION = 0

Metric type: duration.

ZET_METRIC_TYPE_EVENT = 1

Metric type: event.

ZET_METRIC_TYPE_EVENT_WITH_RANGE = 2

Metric type: event with range.

ZET_METRIC_TYPE_THROUGHPUT = 3

Metric type: throughput.

ZET_METRIC_TYPE_TIMESTAMP = 4

Metric type: timestamp.

ZET_METRIC_TYPE_FLAG = 5

Metric type: flag.

ZET_METRIC_TYPE_RATIO = 6

Metric type: ratio.

ZET_METRIC_TYPE_RAW = 7

Metric type: raw.

ZET_METRIC_TYPE_FORCE_UINT32 = 0x7fffffff

zet_metric_group_calculation_type_t

enum zet_metric_group_calculation_type_t

Metric group calculation type.

Values:

ZET_METRIC_GROUP_CALCULATION_TYPE_METRIC_VALUES = 0

Calculated metric values from raw data.

ZET_METRIC_GROUP_CALCULATION_TYPE_MAX_METRIC_VALUES = 1

Maximum metric values.

ZET_METRIC_GROUP_CALCULATION_TYPE_FORCE_UINT32 = 0x7fffffff

zet_metric_query_pool_type_t

enum zet_metric_query_pool_type_t

Metric query pool types.

Values:

ZET_METRIC_QUERY_POOL_TYPE_PERFORMANCE = 0

Performance metric query pool.

ZET_METRIC_QUERY_POOL_TYPE_EXECUTION = 1

Skips workload execution between begin/end calls.

ZET_METRIC_QUERY_POOL_TYPE_FORCE_UINT32 = 0x7fffffff

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.

Parameters

  • hKernel: [in] handle to kernel

  • pProfileProperties: [out] 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_flags_t

enum zet_profile_flag_t

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_FLAG_FORCE_UINT32 = 0x7fffffff

zet_profile_token_type_t

enum zet_profile_token_type_t

Supported profile token types.

Values:

ZET_PROFILE_TOKEN_TYPE_FREE_REGISTER = 0

GRF info.

ZET_PROFILE_TOKEN_TYPE_FORCE_UINT32 = 0x7fffffff

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.

Parameters

  • hContext: [in] handle of the context object

  • desc: [in] pointer to tracer descriptor

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

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

Return

zetTracerExpDestroy

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpDestroy(zet_tracer_exp_handle_t hTracer)

Destroys a tracer.

Parameters

  • hTracer: [in][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 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.

Return

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.

Parameters

  • hTracer: [in] handle of the tracer

  • pCoreCbs: [in] 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

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.

Parameters

  • hTracer: [in] handle of the tracer

  • pCoreCbs: [in] 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

zetTracerExpSetEnabled

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpSetEnabled(zet_tracer_exp_handle_t hTracer, ze_bool_t enable)

Enables (or disables) the tracer.

Parameters

  • hTracer: [in] handle of the tracer

  • enable: [in] 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 Enums

zet_api_tracing_exp_version_t

enum zet_api_tracing_exp_version_t

API Tracing Experimental Extension Version(s)

Values:

ZET_API_TRACING_EXP_VERSION_1_0 = ZE_MAKE_VERSION(1, 0)

version 1.0

ZET_API_TRACING_EXP_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0)

latest known version

ZET_API_TRACING_EXP_VERSION_FORCE_UINT32 = 0x7fffffff

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