oneAPI Level Zero Specification - Version 1.12.15
Common#Enumerations
Structures
Defines structure types.
Values:
zet_metric_global_timestamps_resolution_exp_t. Deprecated, use ZET_STRUCTURE_TYPE_METRIC_GLOBAL_TIMESTAMPS_RESOLUTION_EXP.
zet_metric_calculate_exp_desc_t. Deprecated, use ZET_STRUCTURE_TYPE_METRIC_CALCULATE_EXP_DESC.
Supported value types.
Values:
32-bit unsigned-integer
64-bit unsigned-integer
32-bit floating-point
64-bit floating-point
8-bit boolean
C string.
8-bit unsigned-integer
16-bit unsigned-integer
Base for all properties types.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
Base for all descriptor types.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
#include <zet_api.h>
Union of values.
Public Members
[out] 32-bit unsigned-integer
[out] 64-bit unsigned-integer
[out] 32-bit floating-point
[out] 64-bit floating-point
[out] 8-bit boolean
Typed value.
Functions
Enumerations
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.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hModule
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pSize
Supported module debug info formats.
Values:
Format is ELF/DWARF.
Functions
Enumerations
Structures
Retrieves debug properties of the device.
hDevice – [in] device handle
pDebugProperties – [in,out] query result for debug properties
Attach to a device.
The device must be enabled for debug; see zesSchedulerSetComputeUnitDebugMode.
hDevice – [in] device handle
config – [in] the debug configuration
phDebug – [out] debug session handle
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == config
nullptr == phDebug
ZE_RESULT_ERROR_UNSUPPORTED_FEATURE
attaching to this device is not supported
ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS
caller does not have sufficient permissions
a debugger is already attached
Close a debug session.
hDebug – [in][release] debug session handle
Read the topmost debug event.
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.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == event
the timeout expired
Acknowledge a debug event.
hDebug – [in] debug session handle
event – [in] a pointer to a zet_debug_event_t.
Interrupt device threads.
hDebug – [in] debug session handle
thread – [in] the thread to interrupt
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
the thread is already stopped or unavailable
Resume device threads.
hDebug – [in] debug session handle
thread – [in] the thread to resume
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
the thread is already running or unavailable
Read memory.
The thread identifier ‘all’ can be used for accessing the default memory space, e.g. for setting breakpoints.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == buffer
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZET_DEBUG_MEMORY_SPACE_TYPE_ELF < desc->type
the thread is running or unavailable
the memory cannot be accessed from the supplied thread
Write memory.
The thread identifier ‘all’ can be used for accessing the default memory space, e.g. for setting breakpoints.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == buffer
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZET_DEBUG_MEMORY_SPACE_TYPE_ELF < desc->type
the thread is running or unavailable
the memory cannot be accessed from the supplied thread
Retrieves debug register set properties.
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.
Retrieves debug register set properties for a given thread.
hDebug – [in] debug session handle
thread – [in] the thread identifier specifying a single stopped thread
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.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCount
the thread is running or unavailable
ZE_RESULT_ERROR_INVALID_ARGUMENT
the thread argument specifies more than one or a non-existant thread
Read register state.
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 the `count` member of zet_debug_regset_properties_t for the type
count – [in] the number of registers to read; start+count must be less than or equal to the `count` member of ::zet_debug_register_group_properties_t for the type
pRegisterValues – [in,out][optional][range(0, count)] buffer of register values
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
the thread is running or unavailable
Write register state.
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 the `count` member of zet_debug_regset_properties_t for the type
count – [in] the number of registers to write; start+count must be less than or equal to the `count` member of ::zet_debug_register_group_properties_t for the type
pRegisterValues – [in,out][optional][range(0, count)] buffer of register values
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDebug
the thread is running or unavailable
Values:
the device supports attaching for debug
Values:
The event needs to be acknowledged by calling zetDebugAcknowledgeEvent.
Supported debug event types.
Values:
The event is invalid.
The tool was detached.
The debuggee process created command queues on the device.
The debuggee process destroyed all command queues on the device.
An in-memory module was loaded onto the device.
An in-memory module is about to get unloaded from the device.
The thread stopped due to a device exception.
The thread is not available to be stopped.
A page request could not be completed on the device.
Supported debug detach reasons.
Values:
The detach reason is not valid.
The host process exited.
Page fault reasons.
Values:
The page fault reason is not valid.
The address is not mapped.
Invalid access permissions.
Supported device memory space types.
Values:
default memory space (attribute may be omitted)
shared local memory space (GPU-only)
ELF file memory space.
Values:
register set is readable
register set is writeable
Device debug properties queried using zetDeviceGetDebugProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] returns 0 (none) or a valid combination of zet_device_debug_property_flag_t
Debug configuration provided to zetDebugAttach.
Public Members
[in] the host process identifier
Event information for ZET_DEBUG_EVENT_TYPE_DETACHED.
Event information for ZET_DEBUG_EVENT_TYPE_MODULE_LOAD and ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD.
Public Members
[out] the module format
[out] the begin address of the in-memory module (inclusive)
[out] the end address of the in-memory module (exclusive)
[out] the load address of the module on the device
Event information for ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED and ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE.
Event information for ZET_DEBUG_EVENT_TYPE_PAGE_FAULT.
Public Members
[out] the faulting address
[out] the alignment mask
[out] the page fault reason
#include <zet_api.h>
Event type-specific information.
A debug event on the device.
Device memory space descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] type of memory space
[in] the virtual address within the memory space
Device register set properties queried using zetDebugGetRegisterSetProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] device-specific register set type
[out] device-specific version of this register set
[out] general register set flags
[out] device-specific register set flags
[out] number of registers in the set
[out] the size of a register in bits
[out] the size required for reading or writing a register in bytes
Functions
Enumerations
Structures
Retrieves metric group for a device.
The application may call this function from simultaneous threads.
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.
Retrieves attributes of a metric group.
The application may call this function from simultaneous threads.
hMetricGroup – [in] handle of the metric group
pProperties – [in,out] metric group properties
Calculates metric values from raw data.
The application may call this function from simultaneous threads.
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.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawData
nullptr == pMetricValueCount
Retrieves metric from a metric group.
The application may call this function from simultaneous threads.
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.
Retrieves attributes of a metric.
The application may call this function from simultaneous threads.
hMetric – [in] handle of the metric
pProperties – [in,out] metric properties
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.
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.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
(nullptr == phMetricGroups) && (0 < count)
ZE_RESULT_ERROR_INVALID_ARGUMENT
Multiple metric groups share the same domain
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.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phMetricStreamer
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.
hCommandList – [in] handle of the command list
hMetricStreamer – [in] handle of the metric streamer
value – [in] streamer marker value
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hMetricStreamer
Closes metric streamer.
The application must not call this function from simultaneous threads with the same metric streamer handle.
hMetricStreamer – [in][release] handle of the metric streamer
Reads data from metric streamer.
The application may call this function from simultaneous threads.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricStreamer
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawDataSize
ZE_RESULT_WARNING_DROPPED_DATA
Metric streamer data may have been dropped. Reduce sampling period.
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.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phMetricQueryPool
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZET_METRIC_QUERY_POOL_TYPE_EXECUTION < desc->type
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.
hMetricQueryPool – [in][release] handle of the metric query pool
Creates metric query from the pool.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hMetricQueryPool – [in] handle of the metric query pool
index – [in] index of the query within the pool
phMetricQuery – [out] handle of metric query
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricQueryPool
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phMetricQuery
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.
hMetricQuery – [in][release] handle of metric query
Resets a metric query object back to initial 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.
hMetricQuery – [in] handle of metric query
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.
hCommandList – [in] handle of the command list
hMetricQuery – [in] handle of the metric query
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hMetricQuery
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.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hMetricQuery
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Appends metric query commands to flush all caches.
The application must not call this function from simultaneous threads with the same command list handle.
hCommandList – [in] handle of the command list
Retrieves raw data for a given metric query.
The application may call this function from simultaneous threads.
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
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricQuery
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawDataSize
Values:
Event based sampling.
Time based sampling.
Experimental Tracer based sampling.
Metric types.
Values:
Metric type: duration.
Metric type: event.
Metric type: event with range.
Metric type: throughput.
Metric type: timestamp.
Metric type: flag.
Metric type: ratio.
Metric type: raw.
Metric type: event with only timestamp and value has no meaning.
Metric type: the first event of a start/end event pair.
Metric type: the second event of a start/end event pair.
Metric type: value of the event is a monotonically increasing value that can wrap around
Metric which exports linux dma_buf, which could be imported/mapped to the host process
Metric type: instruction pointer. Deprecated, use ZET_METRIC_TYPE_IP.
Metric type: instruction pointer.
Metric group calculation type.
Values:
Calculated metric values from raw data.
Maximum metric values.
Metric query pool types.
Values:
Performance metric query pool.
Skips workload execution between begin/end calls.
Metric group properties queried using zetMetricGroupGetProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] metric group name
[out] metric group description
[out] metric group sampling type. returns a combination of zet_metric_group_sampling_type_flag_t.
[out] metric group domain number. Cannot use multiple, simultaneous metric groups from the same domain.
[out] metric count belonging to this group
Metric properties queried using zetMetricGetProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] metric name
[out] metric description
[out] metric component
[out] number of tier
[out] metric type
[out] metric result type
[out] metric result units
Metric streamer descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in,out] number of collected reports after which notification event will be signaled. If the requested value is not supported exactly, then the driver may use a value that is the closest supported approximation and shall update this member during zetMetricStreamerOpen.
[in,out] streamer sampling period in nanoseconds. If the requested value is not supported exactly, then the driver may use a value that is the closest supported approximation and shall update this member during zetMetricStreamerOpen.
Metric query pool description.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] Query pool type.
[in] Internal slots count within query pool object.
Functions
Enumerations
Structures
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.
hKernel – [in] handle to kernel
pProfileProperties – [out] pointer to profile properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pProfileProperties
Values:
request the compiler attempt to minimize register usage as much as possible to allow for instrumentation
request the compiler generate free register info
Supported profile token types.
Values:
GRF info.
Profiling meta-data for instrumentation.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] indicates which flags were enabled during compilation. returns 0 (none) or a combination of zet_profile_flag_t
[out] number of tokens immediately following this structure
Profile free register token detailing unused registers in the current function.
Public Members
[out] type of token
[out] total size of the token, in bytes
[out] number of register sequences immediately following this structure
Profile register sequence detailing consecutive bytes, all of which are unused.
Public Members
[out] starting byte in the register table, representing the start of unused bytes in the current function
[out] number of consecutive bytes in the sequence, starting from start
Functions
Enumerations
Structures
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.
hContext – [in] handle of the context object
desc – [in] pointer to tracer descriptor
phTracer – [out] pointer to handle of tracer object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == desc->pUserData
nullptr == phTracer
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.
hTracer – [in][release] handle of tracer object to destroy
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.
hTracer – [in] handle of the tracer
pCoreCbs – [in] pointer to table of ‘core’ callback function pointers
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.
hTracer – [in] handle of the tracer
pCoreCbs – [in] pointer to table of ‘core’ callback function pointers
Enables (or disables) the tracer.
The application must not call this function from simultaneous threads with the same tracer handle.
hTracer – [in] handle of the tracer
enable – [in] enable the tracer if true; disable if false
API Tracing Experimental Extension Version(s)
Values:
version 1.0
latest known version
Tracer descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] pointer passed to every tracer’s callbacks
Functions
Enumerations
Get sets of metric groups which could be collected concurrently.
Re-arrange the input metric groups to provide sets of concurrent metric groups.
hDevice – [in] handle of the device
metricGroupCount – [in] metric group count
phMetricGroups – [in,out] metrics groups to be re-arranged to be sets of concurrent groups
pMetricGroupsCountPerConcurrentGroup – [in,out][optional][*pConcurrentGroupCount] count of metric groups per concurrent group.
pConcurrentGroupCount – [out] number of concurrent groups. The value of this parameter could be used to determine the number of replays necessary.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
nullptr == phMetricGroups
Concurrent Metric Groups Experimental Extension Version(s)
Values:
version 1.0
latest known version
Functions
Enumerations
Structures
Create a metric tracer 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.
The metric tracer is created in disabled state
Metric groups must support sampling type ZET_METRIC_SAMPLING_TYPE_EXP_FLAG_TRACER_BASED
All metric groups must be first activated
hContext – [in] handle of the context object
hDevice – [in] handle of the device
metricGroupCount – [in] metric group count
phMetricGroups – [in][range(0, metricGroupCount )] handles of the metric groups to trace
desc – [in,out] metric tracer descriptor
hNotificationEvent – [in][optional] event used for report availability notification. Note: If buffer is not drained when the event it flagged, there is a risk of HW event buffer being overrun
phMetricTracer – [out] handle of the metric tracer
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phMetricGroups
nullptr == desc
nullptr == phMetricTracer
Destroy a metric tracer.
The application must not call this function from simultaneous threads with the same metric tracer handle.
hMetricTracer – [in] handle of the metric tracer
Start events collection.
Driver implementations must make this API call have as minimal overhead as possible, to allow applications start/stop event collection at any point during execution
The application must not call this function from simultaneous threads with the same metric tracer handle.
hMetricTracer – [in] handle of the metric tracer
synchronous – [in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling zetMetricTracerReadDataExp() and checking the return status: ZE_RESULT_NOT_READY will be returned when the tracer is inactive. ZE_RESULT_SUCCESS will be returned when the tracer is active.
Stop events collection.
Driver implementations must make this API call have as minimal overhead as possible, to allow applications start/stop event collection at any point during execution
The application must not call this function from simultaneous threads with the same metric tracer handle.
hMetricTracer – [in] handle of the metric tracer
synchronous – [in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling zetMetricTracerReadDataExp() and checking the return status: ZE_RESULT_SUCCESS will be returned when the tracer is active or when it is inactive but still has data. ZE_RESULT_NOT_READY will be returned when the tracer is inactive and has no more data to be retrieved.
Read data from the metric tracer.
The application must not call this function from simultaneous threads with the same metric tracer handle.
Data can be retrieved after tracer is disabled. When buffers are drained ZE_RESULT_NOT_READY will be returned
hMetricTracer – [in] handle of the metric tracer
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 data available. if size is non-zero, then driver will only retrieve that amount of data. if size is larger than size needed for all data, then driver will update the value with the actual size needed.
pRawData – [in,out][optional][range(0, *pRawDataSize)] buffer containing tracer data in raw format
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricTracer
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawDataSize
ZE_RESULT_WARNING_DROPPED_DATA
Metric tracer data may have been dropped.
Metric tracer is disabled and no data is available to read.
Create a metric decoder for a given metric tracer.
hMetricTracer – [in] handle of the metric tracer
phMetricDecoder – [out] handle of the metric decoder object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricTracer
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phMetricDecoder
Destroy a metric decoder.
phMetricDecoder – [in] handle of the metric decoder object
Return the list of the decodable metrics from the decoder.
The decodable metrics handles returned by this API are defined by the metric groups in the tracer on which the decoder was created.
The decodable metrics handles returned by this API are only valid to decode metrics raw data with zetMetricTracerDecodeExp(). Decodable metric handles are not valid to compare with metrics handles included in metric groups.
hMetricDecoder – [in] handle of the metric decoder object
pCount – [in,out] pointer to number of decodable metric in the hMetricDecoder handle. If count is zero, then the driver shall update the value with the total number of decodable metrics available in the decoder. if count is greater than zero but less than the total number of decodable metrics available in the decoder, then only that number will be returned. if count is greater than the number of decodable metrics available in the decoder, then the driver shall update the value with the actual number of decodable metrics available.
phMetrics – [in,out] [range(0, *pCount)] array of handles of decodable metrics in the hMetricDecoder handle provided.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricDecoder
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCount
nullptr == phMetrics
Decode raw events collected from a tracer.
phMetricDecoder – [in] handle of the metric decoder object
pRawDataSize – [in,out] size in bytes of raw data buffer. If pMetricEntriesCount is greater than zero but less than total number of decodable metrics available in the raw data buffer, then driver shall update this value with actual number of raw data bytes processed.
pRawData – [in,out][optional][range(0, *pRawDataSize)] buffer containing tracer data in raw format
metricsCount – [in] number of decodable metrics in the tracer for which the hMetricDecoder handle was provided. See zetMetricDecoderGetDecodableMetricsExp(). If metricCount is greater than zero but less than the number decodable metrics available in the raw data buffer, then driver shall only decode those.
phMetrics – [in] [range(0, metricsCount)] array of handles of decodable metrics in the decoder for which the hMetricDecoder handle was provided. Metrics handles are expected to be for decodable metrics, see zetMetricDecoderGetDecodableMetricsExp()
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 decoded. 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 decoded. There is a 1:1 relation between the number of sets and sub-devices returned in the decoded entries.
pMetricEntriesCountPerSet – [in,out][optional][range(0, *pSetCount)] buffer of metric entries counts per metric set, one value per set.
pMetricEntriesCount – [in,out] pointer to the total number of metric entries decoded, for all metric sets. If count is zero, then the driver shall update the value with the total number of metric entries to be decoded. If count is greater than zero but less than the total number of metric entries available in the raw data, then user provided number will be decoded. 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 decodable metric entries decoded. If set to null, then driver will only update the value of pSetCount.
pMetricEntries – [in,out][optional][range(0, *pMetricEntriesCount)] buffer containing decoded metric entries
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == phMetricDecoder
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawDataSize
nullptr == phMetrics
nullptr == pSetCount
nullptr == pMetricEntriesCount
Metric Tracer Experimental Extension Version(s)
Values:
version 1.0
latest known version
Metric tracer descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in,out] number of collected bytes after which notification event will be signaled. If the requested value is not supported exactly, then the driver may use a value that is the closest supported approximation and shall update this member during zetMetricTracerCreateExp.
Decoded metric entry.
Public Members
[out] value of the decodable metric entry or event. Number is meaningful based on the metric type.
[out] timestamp at which the event happened.
[out] index to the decodable metric handle in the input array (phMetric) in zetMetricTracerDecodeExp().
[out] True if the event occurred on a sub-device; false means the device on which the metric tracer was opened does not have sub-devices.
[out] If onSubdevice is true, this gives the ID of the sub-device.
Enumerations
Structures
Values:
Metric group and metrics exports memory using linux dma-buf, which could be imported/mapped to the host process. Properties of the dma_buf could be queried using zet_export_dma_buf_exp_properties_t.
Metric group created using zetDeviceCreateMetricGroupsFromMetricsExp.
Metric group which has a collection of metrics.
Query the metric group type using pNext of zet_metric_group_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] metric group type. returns a combination of zet_metric_group_type_exp_flags_t.
Exported dma_buf properties queried using pNext of zet_metric_group_properties_t or zet_metric_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] the file descriptor handle that could be used to import the memory by the host process.
[out] size in bytes of the dma_buf
Functions
Enumerations
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.
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.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawData
nullptr == pSetCount
nullptr == pTotalMetricValueCount
Calculating Multiple Metrics Experimental Extension Version(s)
Values:
version 1.0
latest known version
Functions
Enumerations
Structures
Returns metric timestamps synchronized with global device timestamps, optionally synchronized with host.
The application may call this function from simultaneous threads.
By default, the global and metrics timestamps are synchronized to the device.
hMetricGroup – [in] handle of the metric group
synchronizedWithHost – [in] Returns the timestamps synchronized to the host or the device.
globalTimestamp – [out] Device timestamp.
metricTimestamp – [out] Metric timestamp.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == globalTimestamp
nullptr == metricTimestamp
Global Metric Timestamps Experimental Extension Version(s)
Values:
version 1.0
latest known version
Metric timestamps resolution.
This structure may be returned from zetMetricGroupGetProperties via the pNext member of zet_metric_group_properties_t.
Used for mapping metric timestamps to other timers.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Returns the resolution of metrics timer (used for timestamps) in cycles/sec.
[out] Returns the number of valid bits in the timestamp value.
Functions
Enumerations
Structures
Export Metrics Data for system independent calculation.
This function exports raw data and necessary information to perform metrics calculation of collected data in a different system than where data was collected, which may or may not have accelerators.
Implementations can choose to describe the data arrangement of the exported data, using any mechanism which allows users to read and process them.
The application may call this function from simultaneous threads.
hMetricGroup – [in] handle of the metric group
pRawData – [in] buffer of raw data
rawDataSize – [in] size in bytes of raw data buffer
pExportDataSize – [in,out] size in bytes of export data buffer if size is zero, then the driver shall update the value with the number of bytes necessary to store the exported data. if size is greater than required, then the driver shall update the value with the actual number of bytes necessary to store the exported data.
pExportData – [in,out][optional][range(0, *pExportDataSize)] buffer of exported data.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRawData
nullptr == pExportDataSize
Calculate one or more sets of metric values from exported raw data.
Calculate metrics values using exported data returned by zetMetricGroupGetExportDataExp.
This function is similar to zetMetricGroupCalculateMultipleMetricValuesExp except it would calculate from exported metric data.
This function could be used to calculate metrics on a system different from where the metric raw data was collected.
The application may call this function from simultaneous threads.
hDriver – [in] handle of the driver instance
type – [in] calculation type to be applied on raw data
exportDataSize – [in] size in bytes of exported data buffer
pExportData – [in][range(0, exportDataSize)] buffer of exported data to calculate
pCalculateDescriptor – [in] descriptor specifying calculation specific parameters
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.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pExportData
nullptr == pCalculateDescriptor
nullptr == pSetCount
nullptr == pTotalMetricValueCount
Exporting Metrics Data Experimental Extension Version(s)
Values:
version 1.0
latest known version
Metrics calculation descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] number of reports to skip during calculation
Functions
Enumerations
Structures
Query and get the available metric programmable handles.
Query the available programmable handles using *pCount = 0.
Returns all programmable metric handles available in the device.
The application may call this function from simultaneous threads.
hDevice – [in] handle of the device
pCount – [in,out] pointer to the number of metric programmable handles. if count is zero, then the driver shall update the value with the total number of metric programmable handles available. if count is greater than the number of metric programmable handles available, then the driver shall update the value with the correct number of metric programmable handles available.
phMetricProgrammables – [in,out][optional][range(0, *pCount)] array of handle of metric programmables. if count is less than the number of metric programmables available, then driver shall only retrieve that number of metric programmables.
Get the properties of the metric programmable.
Returns the properties of the metric programmable.
hMetricProgrammable – [in] handle of the metric programmable
pProperties – [in,out] properties of the metric programmable
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricProgrammable
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pProperties
Get the information about the parameters of the metric programmable.
Returns information about the parameters of the metric programmable handle.
hMetricProgrammable – [in] handle of the metric programmable
pParameterCount – [in,out] count of the parameters to retrieve parameter info. if value pParameterCount is greater than count of parameters available, then pParameterCount will be updated with count of parameters available. The count of parameters available can be queried using zetMetricProgrammableGetPropertiesExp.
pParameterInfo – [in,out][range(1, *pParameterCount)] array of parameter info. if parameterCount is less than the number of parameters available, then driver shall only retrieve that number of parameter info.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricProgrammable
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pParameterCount
nullptr == pParameterInfo
Get the information about the parameter value of the metric programmable.
Returns the value-information about the parameter at the specific ordinal of the metric programmable handle.
hMetricProgrammable – [in] handle of the metric programmable
parameterOrdinal – [in] ordinal of the parameter in the metric programmable
pValueInfoCount – [in,out] count of parameter value information to retrieve. if value at pValueInfoCount is greater than count of value info available, then pValueInfoCount will be updated with count of value info available. The count of parameter value info available can be queried using zetMetricProgrammableGetParamInfoExp.
pValueInfo – [in,out][range(1, *pValueInfoCount)] array of parameter value info. if pValueInfoCount is less than the number of value info available, then driver shall only retrieve that number of value info.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricProgrammable
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pValueInfoCount
nullptr == pValueInfo
Create metric handles by applying parameter values on the metric programmable handle.
Multiple parameter values could be used to prepare a metric.
If parameterCount = 0, the default value of the metric programmable would be used for all parameters.
The implementation can post-fix a C string to the metric name and description, based on the parameter values chosen.
zetMetricProgrammableGetParamInfoExp() returns a list of parameters in a defined order.
Therefore, the list of values passed in to the API should respect the same order such that the desired parameter is set with expected value
hMetricProgrammable – [in] handle of the metric programmable
parameterCount – [in] Count of parameters to set.
pParameterValues – [in] list of parameter values to be set.
pName – [in] pointer to metric name to be used. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_NAME.
pDescription – [in] pointer to metric description to be used. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_DESCRIPTION.
pMetricHandleCount – [in,out] Pointer to the number of metric handles. if count is zero, then the driver shall update the value with the number of metric handles available for this programmable. if count is greater than the number of metric handles available, then the driver shall update the value with the correct number of metric handles available.
phMetricHandles – [in,out][optional][range(0,*pMetricHandleCount)] array of handle of metrics. if count is less than the number of metrics available, then driver shall only retrieve that number of metric handles.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricProgrammable
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pParameterValues
nullptr == pName
nullptr == pDescription
nullptr == pMetricHandleCount
Create metric handles by applying parameter values on the metric programmable handle.
This API is deprecated. Please use zetMetricCreateFromProgrammableExp2()
hMetricProgrammable – [in] handle of the metric programmable
pParameterValues – [in] list of parameter values to be set.
parameterCount – [in] Count of parameters to set.
pName – [in] pointer to metric name to be used. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_NAME.
pDescription – [in] pointer to metric description to be used. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_DESCRIPTION.
pMetricHandleCount – [in,out] Pointer to the number of metric handles. if count is zero, then the driver shall update the value with the number of metric handles available for this programmable. if count is greater than the number of metric handles available, then the driver shall update the value with the correct number of metric handles available.
phMetricHandles – [in,out][optional][range(0,*pMetricHandleCount)] array of handle of metrics. if count is less than the number of metrics available, then driver shall only retrieve that number of metric handles.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricProgrammable
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pParameterValues
nullptr == pName
nullptr == pDescription
nullptr == pMetricHandleCount
Create multiple metric group handles from metric handles.
Creates multiple metric groups from metrics which were created using zetMetricCreateFromProgrammableExp2().
Metrics whose Hardware resources do not overlap are added to same metric group.
The metric groups created using this API are managed by the application and cannot be retrieved using zetMetricGroupGet().
The created metric groups are ready for activation and collection.
hDevice – [in] handle of the device.
metricCount – [in] number of metric handles.
phMetrics – [in] metric handles to be added to the metric groups.
pMetricGroupNamePrefix – [in] prefix to the name created for the metric groups. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_GROUP_NAME_PREFIX_EXP.
pDescription – [in] pointer to description of the metric groups. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_GROUP_DESCRIPTION.
pMetricGroupCount – [in,out] pointer to the number of metric group handles to be created. if pMetricGroupCount is zero, then the driver shall update the value with the maximum possible number of metric group handles that could be created. if pMetricGroupCount is greater than the number of metric group handles that could be created, then the driver shall update the value with the correct number of metric group handles generated. if pMetricGroupCount is lesser than the number of metric group handles that could be created, then ZE_RESULT_ERROR_INVALID_ARGUMENT is returned.
phMetricGroup – [in,out][optional][range(0, *pMetricGroupCount)] array of handle of metric group handles. Created Metric group handles.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
nullptr == phMetrics
ZE_RESULT_ERROR_INVALID_ARGUMENT
metricGroupCount is lesser than the number of metric group handles that could be created.
Create metric group handle.
This API is deprecated. Please use zetDeviceCreateMetricGroupsFromMetricsExp
hDevice – [in] handle of the device
pName – [in] pointer to metric group name. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_GROUP_NAME.
pDescription – [in] pointer to metric group description. Must point to a null-terminated character array no longer than ZET_MAX_METRIC_GROUP_DESCRIPTION.
samplingType – [in] Sampling type for the metric group.
phMetricGroup – [in,out] Created Metric group handle
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pName
nullptr == pDescription
nullptr == phMetricGroup
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x7 < samplingType
Add a metric handle to the metric group handle created using zetDeviceCreateMetricGroupsFromMetricsExp.
Reasons for failing to add the metric could be queried using pErrorString
Multiple additions of same metric would add the metric only once to the hMetricGroup
Metric handles from multiple domains may be used in a single metric group.
Metric handles from different sourceIds (refer zet_metric_programmable_exp_properties_t) are not allowed in a single metric group.
hMetricGroup – [in] Handle of the metric group
hMetric – [in] Metric to be added to the group.
pErrorStringSize – [in,out][optional] Size of the error string to query, if an error was reported during adding the metric handle. if *pErrorStringSize is zero, then the driver shall update the value with the size of the error string in bytes.
pErrorString – [in,out][optional][range(0, *pErrorStringSize)] Error string. if *pErrorStringSize is less than the length of the error string available, then driver shall only retrieve that length of error string.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
nullptr == hMetric
ZE_RESULT_ERROR_INVALID_ARGUMENT
If a Metric handle from a pre-defined metric group is requested to be added.
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
If the metric group is currently activated.
Remove a metric from the metric group handle created using zetDeviceCreateMetricGroupsFromMetricsExp.
Remove an already added metric handle from the metric group.
hMetricGroup – [in] Handle of the metric group
hMetric – [in] Metric handle to be removed from the metric group.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
nullptr == hMetric
ZE_RESULT_ERROR_INVALID_ARGUMENT
If trying to remove a metric not previously added to the metric group
If the input metric group is a pre-defined metric group
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
If the metric group is currently activated
Closes a created metric group using zetDeviceCreateMetricGroupsFromMetricsExp, so that it can be activated.
Finalizes the zetMetricGroupAddMetricExp and zetMetricGroupRemoveMetricExp operations on the metric group.
This is a necessary step before activation of the created metric group.
Add / Remove of metrics is possible after zetMetricGroupCloseExp. However, a call to zetMetricGroupCloseExp is necessary after modifying the metric group.
Implementations could choose to add new metrics to the group during zetMetricGroupCloseExp, which are related and might add value to the metrics already added by the application
Applications can query the list of metrics in the metric group using zetMetricGet
hMetricGroup – [in] Handle of the metric group
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_ARGUMENT
If the input metric group is a pre-defined metric group
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
If the metric group is currently activated
Destroy a metric group created using zetDeviceCreateMetricGroupsFromMetricsExp.
Metric handles created using zetMetricCreateFromProgrammableExp2 and are part of the metricGroup are not destroyed.
It is necessary to call zetMetricDestroyExp for each of the metric handles (created from zetMetricCreateFromProgrammableExp2) to destroy them.
hMetricGroup – [in] Handle of the metric group to destroy
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetricGroup
ZE_RESULT_ERROR_INVALID_ARGUMENT
If trying to destroy a pre-defined metric group
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
If trying to destroy an activated metric group
Destroy a metric created using zetMetricCreateFromProgrammableExp2.
If a metric is added to a metric group, the metric has to be removed using zetMetricGroupRemoveMetricExp before it can be destroyed.
hMetric – [in] Handle of the metric to destroy
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hMetric
ZE_RESULT_ERROR_INVALID_ARGUMENT
If trying to destroy a metric from pre-defined metric group
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
If trying to destroy a metric currently added to a metric group
Programmable Metrics Experimental Extension Version(s)
Values:
version 1.1
latest known version
Metric Programmable Parameter types.
Values:
Metric is disaggregated.
Metric for latency measurement.
Produces normalization in percent using raw_metric * 100 / cycles / HW instance_count.
Produces normalization using raw_metric / HW instance_count.
Produces normalization average using raw_metric / timestamp.
Produces normalization average using raw_metric * n bytes.
Generic Parameter type. Please refer the parameter’s description.
Supported value info types.
Values:
32-bit unsigned-integer
64-bit unsigned-integer
32-bit floating-point
64-bit floating-point
8-bit boolean
8-bit unsigned-integer
16-bit unsigned-integer
64-bit unsigned-integer range (minimum and maximum)
64-bit floating point range (minimum and maximum)
Metric Programmable properties queried using zetMetricProgrammableGetPropertiesExp.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] metric programmable name
[out] metric programmable description
[out] metric programmable component
[out] tier number
[out] metric domain number.
[out] number of parameters in the programmable
[out] metric sampling type. returns a combination of zet_metric_group_sampling_type_flag_t.
[out] unique metric source identifier(within platform)to identify the HW block where the metric is collected.
Value info of type uint64_t range.
Public Members
[out] minimum value of the range
[out] maximum value of the range
Value info of type float64 range.
Public Members
[out] minimum value of the range
[out] maximum value of the range
#include <zet_api.h>
Union of value information.
Public Members
[out] 32-bit unsigned-integer
[out] 64-bit unsigned-integer
[out] 32-bit floating-point
[out] 64-bit floating-point
[out] 8-bit boolean
[out] 8-bit unsigned integer
[out] 16-bit unsigned integer
[out] minimum and maximum value of the range
[out] minimum and maximum value of the range
Metric Programmable parameter information.
Metric Programmable parameter value information.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] information about the parameter value
[out] description about the value
Metric Programmable parameter value.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4