1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
/*
* Copyright (C) 2020-2023 Intel Corporation
*
* SPDX-License-Identifier: MIT
*
* @file zel_tracing_libapi.cpp
*
* @brief C++ static library for zel tracing layer API.
*
* Perhaps generate this from scripts in the future.
*/
#include "ze_lib.h"
extern "C" {
///////////////////////////////////////////////////////////////////////////////
/// @brief Creates a tracer on the context.
///
/// @details
/// - 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.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == desc`
/// + `nullptr == desc->pUserData`
/// + `nullptr == phTracer`
/// - ::ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY
ze_result_t ZE_APICALL
zelTracerCreate(
const zel_tracer_desc_t* desc, ///< [in] pointer to tracer descriptor
zel_tracer_handle_t* phTracer ///< [out] pointer to handle of tracer object created
)
{
if(ze_lib::destruction)
return ZE_RESULT_ERROR_UNINITIALIZED;
auto pfnCreate = ze_lib::context->zelTracingDdiTable.Tracer.pfnCreate;
if( nullptr == pfnCreate )
return ZE_RESULT_ERROR_UNINITIALIZED;
return pfnCreate( desc, phTracer );
}
///////////////////////////////////////////////////////////////////////////////
/// @brief Destroys a tracer.
///
/// @details
/// - 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.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST
/// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
/// + `nullptr == hTracer`
/// - ::ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
ze_result_t ZE_APICALL
zelTracerDestroy(
zel_tracer_handle_t hTracer ///< [in][release] handle of tracer object to destroy
)
{
if(ze_lib::destruction)
return ZE_RESULT_ERROR_UNINITIALIZED;
auto pfnDestroy = ze_lib::context->zelTracingDdiTable.Tracer.pfnDestroy;
if( nullptr == pfnDestroy )
return ZE_RESULT_ERROR_UNINITIALIZED;
return pfnDestroy( hTracer );
}
///////////////////////////////////////////////////////////////////////////////
/// @brief Sets the collection of callbacks to be executed **before** driver
/// execution.
///
/// @details
/// - 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.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST
/// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
/// + `nullptr == hTracer`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pCoreCbs`
ze_result_t ZE_APICALL
zelTracerSetPrologues(
zel_tracer_handle_t hTracer, ///< [in] handle of the tracer
zel_core_callbacks_t* pCoreCbs ///< [in] pointer to table of 'core' callback function pointers
)
{
if(ze_lib::destruction)
return ZE_RESULT_ERROR_UNINITIALIZED;
auto pfnSetPrologues = ze_lib::context->zelTracingDdiTable.Tracer.pfnSetPrologues;
if( nullptr == pfnSetPrologues )
return ZE_RESULT_ERROR_UNINITIALIZED;
return pfnSetPrologues( hTracer, pCoreCbs );
}
///////////////////////////////////////////////////////////////////////////////
/// @brief Sets the collection of callbacks to be executed **after** driver
/// execution.
///
/// @details
/// - 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.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST
/// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
/// + `nullptr == hTracer`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pCoreCbs`
ze_result_t ZE_APICALL
zelTracerSetEpilogues(
zel_tracer_handle_t hTracer, ///< [in] handle of the tracer
zel_core_callbacks_t* pCoreCbs ///< [in] pointer to table of 'core' callback function pointers
)
{
if(ze_lib::destruction)
return ZE_RESULT_ERROR_UNINITIALIZED;
auto pfnSetEpilogues = ze_lib::context->zelTracingDdiTable.Tracer.pfnSetEpilogues;
if( nullptr == pfnSetEpilogues )
return ZE_RESULT_ERROR_UNINITIALIZED;
return pfnSetEpilogues( hTracer, pCoreCbs );
}
///////////////////////////////////////////////////////////////////////////////
/// @brief Enables (or disables) the tracer
///
/// @details
/// - The application must **not** call this function from simultaneous
/// threads with the same tracer handle.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST
/// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
/// + `nullptr == hTracer`
ze_result_t ZE_APICALL
zelTracerSetEnabled(
zel_tracer_handle_t hTracer, ///< [in] handle of the tracer
ze_bool_t enable ///< [in] enable the tracer if true; disable if false
)
{
if(ze_lib::destruction)
return ZE_RESULT_ERROR_UNINITIALIZED;
auto pfnSetEnabled = ze_lib::context->zelTracingDdiTable.Tracer.pfnSetEnabled;
if( nullptr == pfnSetEnabled )
return ZE_RESULT_ERROR_UNINITIALIZED;
return pfnSetEnabled( hTracer, enable );
}
} // extern "C"
|
