1+ /*
2+ * Copyright (C) 2020 Intel Corporation
3+ *
4+ * SPDX-License-Identifier: MIT
5+ *
6+ * @file zel_tracing_api.h
7+ */
8+ #ifndef _ZEL_TRACING_API_H
9+ #define _ZEL_TRACING_API_H
10+ #if defined(__cplusplus )
11+ #pragma once
12+ #endif
13+
14+ // 'core' API headers
15+ #include "../ze_api.h"
16+
17+ #if defined(__cplusplus )
18+ extern "C" {
19+ #endif
20+
21+ // Intel 'oneAPI' Level-Zero Loader Layer Extension APIs for API Tracing
22+ #if !defined(__GNUC__ )
23+ #pragma region zel_tracing
24+ #endif
25+
26+ ///////////////////////////////////////////////////////////////////////////////
27+ /// @brief Handle of tracer object
28+ typedef struct _zel_tracer_handle_t * zel_tracer_handle_t ;
29+
30+ ///////////////////////////////////////////////////////////////////////////////
31+ ///////////////////////////////////////////////////////////////////////////////
32+ #ifndef ZEL_API_TRACING_NAME
33+ /// @brief API Tracing Extension Name
34+ #define ZEL_API_TRACING_NAME "ZEL_api_tracing"
35+ #endif // ZEL_API_TRACING_NAME
36+
37+ ///////////////////////////////////////////////////////////////////////////////
38+ /// @brief API Tracing Extension Version(s)
39+ typedef enum _zel_api_tracing_version_t
40+ {
41+ ZEL_API_TRACING_VERSION_1_0 = ZE_MAKE_VERSION ( 1 , 0 ), ///< version 1.0
42+ ZEL_API_TRACING_VERSION_CURRENT = ZE_MAKE_VERSION ( 1 , 0 ), ///< latest known version
43+ ZEL_API_TRACING_VERSION_FORCE_UINT32 = 0x7fffffff
44+
45+ } zel_api_tracing_version_t ;
46+
47+ ///////////////////////////////////////////////////////////////////////////////
48+ /// @brief Alias the existing callbacks definition for 'core' callbacks
49+ typedef ze_callbacks_t zel_core_callbacks_t ;
50+
51+ ///////////////////////////////////////////////////////////////////////////////
52+ /// @brief Defines structure types
53+ typedef enum _zel_structure_type_t
54+ {
55+ ZEL_STRUCTURE_TYPE_TRACER_DESC = 0x1 ,///< ::zel_tracer_desc_t
56+ // This enumeration value is deprecated.
57+ // Pluse use ZEL_STRUCTURE_TYPE_TRACER_DESC.
58+ ZEL_STRUCTURE_TYPE_TRACER_EXP_DESC = 0x1 ,///< ::zel_tracer_desc_t
59+ ZEL_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
60+
61+ } zel_structure_type_t ;
62+
63+ ///////////////////////////////////////////////////////////////////////////////
64+ /// @brief Tracer descriptor
65+ typedef struct _zel_tracer_desc_t
66+ {
67+ zel_structure_type_t stype ; ///< [in] type of this structure
68+ const void * pNext ; ///< [in][optional] pointer to extension-specific structure
69+ void * pUserData ; ///< [in] pointer passed to every tracer's callbacks
70+
71+ } zel_tracer_desc_t ;
72+
73+ ///////////////////////////////////////////////////////////////////////////////
74+ /// @brief Creates a tracer
75+ ///
76+ /// @details
77+ /// - The tracer is created in the disabled state.
78+ /// - The application may call this function from simultaneous threads.
79+ /// - The implementation of this function must be thread-safe.
80+ ///
81+ /// @returns
82+ /// - ::ZE_RESULT_SUCCESS
83+ /// - ::ZE_RESULT_ERROR_UNINITIALIZED
84+ /// - ::ZE_RESULT_ERROR_DEVICE_LOST
85+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
86+ /// + `nullptr == desc`
87+ /// + `nullptr == desc->pUserData`
88+ /// + `nullptr == phTracer`
89+ /// - ::ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY
90+ ZE_APIEXPORT ze_result_t ZE_APICALL
91+ zelTracerCreate (
92+ const zel_tracer_desc_t * desc , ///< [in] pointer to tracer descriptor
93+ zel_tracer_handle_t * phTracer ///< [out] pointer to handle of tracer object created
94+ );
95+
96+ ///////////////////////////////////////////////////////////////////////////////
97+ /// @brief Destroys a tracer.
98+ ///
99+ /// @details
100+ /// - The application must **not** call this function from simultaneous
101+ /// threads with the same tracer handle.
102+ /// - The implementation of this function must be thread-safe.
103+ /// - The implementation of this function will stall and wait on any
104+ /// outstanding threads executing callbacks before freeing any Host
105+ /// allocations associated with this tracer.
106+ ///
107+ /// @returns
108+ /// - ::ZE_RESULT_SUCCESS
109+ /// - ::ZE_RESULT_ERROR_UNINITIALIZED
110+ /// - ::ZE_RESULT_ERROR_DEVICE_LOST
111+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
112+ /// + `nullptr == hTracer`
113+ /// - ::ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
114+ ZE_APIEXPORT ze_result_t ZE_APICALL
115+ zelTracerDestroy (
116+ zel_tracer_handle_t hTracer ///< [in][release] handle of tracer object to destroy
117+ );
118+
119+ ///////////////////////////////////////////////////////////////////////////////
120+ /// @brief Sets the collection of callbacks to be executed **before** driver
121+ /// execution.
122+ ///
123+ /// @details
124+ /// - The application only needs to set the function pointers it is
125+ /// interested in receiving; all others should be 'nullptr'
126+ /// - The application must ensure that no other threads are executing
127+ /// functions for which the tracing functions are changing.
128+ /// - The application must **not** call this function from simultaneous
129+ /// threads with the same tracer handle.
130+ ///
131+ /// @returns
132+ /// - ::ZE_RESULT_SUCCESS
133+ /// - ::ZE_RESULT_ERROR_UNINITIALIZED
134+ /// - ::ZE_RESULT_ERROR_DEVICE_LOST
135+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
136+ /// + `nullptr == hTracer`
137+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
138+ /// + `nullptr == pCoreCbs`
139+ ZE_APIEXPORT ze_result_t ZE_APICALL
140+ zelTracerSetPrologues (
141+ zel_tracer_handle_t hTracer , ///< [in] handle of the tracer
142+ zel_core_callbacks_t * pCoreCbs ///< [in] pointer to table of 'core' callback function pointers
143+ );
144+
145+ ///////////////////////////////////////////////////////////////////////////////
146+ /// @brief Sets the collection of callbacks to be executed **after** driver
147+ /// execution.
148+ ///
149+ /// @details
150+ /// - The application only needs to set the function pointers it is
151+ /// interested in receiving; all others should be 'nullptr'
152+ /// - The application must ensure that no other threads are executing
153+ /// functions for which the tracing functions are changing.
154+ /// - The application must **not** call this function from simultaneous
155+ /// threads with the same tracer handle.
156+ ///
157+ /// @returns
158+ /// - ::ZE_RESULT_SUCCESS
159+ /// - ::ZE_RESULT_ERROR_UNINITIALIZED
160+ /// - ::ZE_RESULT_ERROR_DEVICE_LOST
161+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
162+ /// + `nullptr == hTracer`
163+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
164+ /// + `nullptr == pCoreCbs`
165+ ZE_APIEXPORT ze_result_t ZE_APICALL
166+ zelTracerSetEpilogues (
167+ zel_tracer_handle_t hTracer , ///< [in] handle of the tracer
168+ zel_core_callbacks_t * pCoreCbs ///< [in] pointer to table of 'core' callback function pointers
169+ );
170+
171+ ///////////////////////////////////////////////////////////////////////////////
172+ /// @brief Enables (or disables) the tracer
173+ ///
174+ /// @details
175+ /// - The application must **not** call this function from simultaneous
176+ /// threads with the same tracer handle.
177+ ///
178+ /// @returns
179+ /// - ::ZE_RESULT_SUCCESS
180+ /// - ::ZE_RESULT_ERROR_UNINITIALIZED
181+ /// - ::ZE_RESULT_ERROR_DEVICE_LOST
182+ /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
183+ /// + `nullptr == hTracer`
184+ ZE_APIEXPORT ze_result_t ZE_APICALL
185+ zelTracerSetEnabled (
186+ zel_tracer_handle_t hTracer , ///< [in] handle of the tracer
187+ ze_bool_t enable ///< [in] enable the tracer if true; disable if false
188+ );
189+
190+ #if !defined(__GNUC__ )
191+ #pragma endregion
192+ #endif
193+
194+ #if defined(__cplusplus )
195+ // extern "C"
196+ #endif
197+
198+ #endif // _ZEL_TRACING_API_H
0 commit comments