Tracer Exp - Deprecated

oneAPI Level Zero Specification - Version 1.20.41

Tracer Exp - Deprecated Functions

zetTracerExpCreate

Added in version 1.0

Deprecated since 1.14. Not supported in L0 drivers; tracing moved to the loader. Use L0 Loader API Tracing instead.

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

Creates a tracer on the context.

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

• The tracer is created in the disabled state.

• The application may call this function from simultaneous threads.

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

Parameters:

• hContext – [in] handle of the context object

• desc – [in] pointer to tracer descriptor

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

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == desc->pUserData

  • nullptr == phTracer

zetTracerExpDestroy

Added in version 1.0

Deprecated since 1.14. Not supported in L0 drivers; tracing moved to the loader. Use L0 Loader API Tracing instead.

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpDestroy(zet_tracer_exp_handle_t hTracer)

Destroys a tracer.

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

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

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

Parameters:

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

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hTracer

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

zetTracerExpSetPrologues

Added in version 1.0

Deprecated since 1.14. Not supported in L0 drivers; tracing moved to the loader. Use L0 Loader API Tracing instead.

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

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

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

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

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

Parameters:

• hTracer – [in] handle of the tracer

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

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hTracer

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCoreCbs

zetTracerExpSetEpilogues

Added in version 1.0

Deprecated since 1.14. Not supported in L0 drivers; tracing moved to the loader. Use L0 Loader API Tracing instead.

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

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

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

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

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

Parameters:

• hTracer – [in] handle of the tracer

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

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hTracer

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCoreCbs

zetTracerExpSetEnabled

Added in version 1.0

Deprecated since 1.14. Not supported in L0 drivers; tracing moved to the loader. Use L0 Loader API Tracing instead.

ZE_APIEXPORT ze_result_t ZE_APICALL zetTracerExpSetEnabled(zet_tracer_exp_handle_t hTracer, ze_bool_t enable)

Enables (or disables) the tracer

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

Parameters:

• hTracer – [in] handle of the tracer

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

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hTracer

Tracer Exp - Deprecated Structures

zet_tracer_exp_desc_t

Added in version 1.0

Deprecated since 1.14. Not supported in L0 drivers; tracing moved to the loader. Use L0 Loader API Tracing instead.

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] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

void *pUserData

[in] pointer passed to every tracer’s callbacks