1 /*
2 Copyright (c) 2005-2023 Intel Corporation
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16
17 #ifndef _ITTNOTIFY_H_
18 #define _ITTNOTIFY_H_
19
20 /**
21 @file
22 @brief Public User API functions and types
23 @mainpage
24
25 The Instrumentation and Tracing Technology API (ITT API) is used to
26 annotate a user's program with additional information
27 that can be used by correctness and performance tools. The user inserts
28 calls in their program. Those calls generate information that is collected
29 at runtime, and used by Intel(R) Threading Tools.
30
31 @section API Concepts
32 The following general concepts are used throughout the API.
33
34 @subsection Unicode Support
35 Many API functions take character string arguments. On Windows, there
36 are two versions of each such function. The function name is suffixed
37 by W if Unicode support is enabled, and by A otherwise. Any API function
38 that takes a character string argument adheres to this convention.
39
40 @subsection Conditional Compilation
41 Many users prefer having an option to modify ITT API code when linking it
42 inside their runtimes. ITT API header file provides a mechanism to replace
43 ITT API function names inside your code with empty strings. To do this,
44 define the macros INTEL_NO_ITTNOTIFY_API during compilation and remove the
45 static library from the linker script.
46
47 @subsection Domains
48 [see domains]
49 Domains provide a way to separate notification for different modules or
50 libraries in a program. Domains are specified by dotted character strings,
51 e.g. TBB.Internal.Control.
52
53 A mechanism (to be specified) is provided to enable and disable
54 domains. By default, all domains are enabled.
55 @subsection Named Entities and Instances
56 Named entities (frames, regions, tasks, and markers) communicate
57 information about the program to the analysis tools. A named entity often
58 refers to a section of program code, or to some set of logical concepts
59 that the programmer wants to group together.
60
61 Named entities relate to the programmer's static view of the program. When
62 the program actually executes, many instances of a given named entity
63 may be created.
64
65 The API annotations denote instances of named entities. The actual
66 named entities are displayed using the analysis tools. In other words,
67 the named entities come into existence when instances are created.
68
69 Instances of named entities may have instance identifiers (IDs). Some
70 API calls use instance identifiers to create relationships between
71 different instances of named entities. Other API calls associate data
72 with instances of named entities.
73
74 Some named entities must always have instance IDs. In particular, regions
75 and frames always have IDs. Task and markers need IDs only if the ID is
76 needed in another API call (such as adding a relation or metadata).
77
78 The lifetime of instance IDs is distinct from the lifetime of
79 instances. This allows various relationships to be specified separate
80 from the actual execution of instances. This flexibility comes at the
81 expense of extra API calls.
82
83 The same ID may not be reused for different instances, unless a previous
84 [ref] __itt_id_destroy call for that ID has been issued.
85 */
86
87 /** @cond exclude_from_documentation */
88 #ifndef ITT_OS_WIN
89 # define ITT_OS_WIN 1
90 #endif /* ITT_OS_WIN */
91
92 #ifndef ITT_OS_LINUX
93 # define ITT_OS_LINUX 2
94 #endif /* ITT_OS_LINUX */
95
96 #ifndef ITT_OS_MAC
97 # define ITT_OS_MAC 3
98 #endif /* ITT_OS_MAC */
99
100 #ifndef ITT_OS_FREEBSD
101 # define ITT_OS_FREEBSD 4
102 #endif /* ITT_OS_FREEBSD */
103
104 #ifndef ITT_OS
105 # if defined WIN32 || defined _WIN32
106 # define ITT_OS ITT_OS_WIN
107 # elif defined( __APPLE__ ) && defined( __MACH__ )
108 # define ITT_OS ITT_OS_MAC
109 # elif defined( __FreeBSD__ )
110 # define ITT_OS ITT_OS_FREEBSD
111 # else
112 # define ITT_OS ITT_OS_LINUX
113 # endif
114 #endif /* ITT_OS */
115
116 #ifndef ITT_PLATFORM_WIN
117 # define ITT_PLATFORM_WIN 1
118 #endif /* ITT_PLATFORM_WIN */
119
120 #ifndef ITT_PLATFORM_POSIX
121 # define ITT_PLATFORM_POSIX 2
122 #endif /* ITT_PLATFORM_POSIX */
123
124 #ifndef ITT_PLATFORM_MAC
125 # define ITT_PLATFORM_MAC 3
126 #endif /* ITT_PLATFORM_MAC */
127
128 #ifndef ITT_PLATFORM_FREEBSD
129 # define ITT_PLATFORM_FREEBSD 4
130 #endif /* ITT_PLATFORM_FREEBSD */
131
132 #ifndef ITT_PLATFORM
133 # if ITT_OS==ITT_OS_WIN
134 # define ITT_PLATFORM ITT_PLATFORM_WIN
135 # elif ITT_OS==ITT_OS_MAC
136 # define ITT_PLATFORM ITT_PLATFORM_MAC
137 # elif ITT_OS==ITT_OS_FREEBSD
138 # define ITT_PLATFORM ITT_PLATFORM_FREEBSD
139 # else
140 # define ITT_PLATFORM ITT_PLATFORM_POSIX
141 # endif
142 #endif /* ITT_PLATFORM */
143
144 #if defined(_UNICODE) && !defined(UNICODE)
145 #define UNICODE
146 #endif
147
148 #include <stddef.h>
149 #if ITT_PLATFORM==ITT_PLATFORM_WIN
150 #include <tchar.h>
151 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
152 #include <stdint.h>
153 #if defined(UNICODE) || defined(_UNICODE)
154 #include <wchar.h>
155 #endif /* UNICODE || _UNICODE */
156 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
157
158 #ifndef ITTAPI_CDECL
159 # if ITT_PLATFORM==ITT_PLATFORM_WIN
160 # define ITTAPI_CDECL __cdecl
161 # else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
162 # if defined _M_IX86 || defined __i386__
163 # define ITTAPI_CDECL __attribute__ ((cdecl))
164 # else /* _M_IX86 || __i386__ */
165 # define ITTAPI_CDECL /* actual only on x86 platform */
166 # endif /* _M_IX86 || __i386__ */
167 # endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
168 #endif /* ITTAPI_CDECL */
169
170 #ifndef STDCALL
171 # if ITT_PLATFORM==ITT_PLATFORM_WIN
172 # define STDCALL __stdcall
173 # else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
174 # if defined _M_IX86 || defined __i386__
175 # define STDCALL __attribute__ ((stdcall))
176 # else /* _M_IX86 || __i386__ */
177 # define STDCALL /* supported only on x86 platform */
178 # endif /* _M_IX86 || __i386__ */
179 # endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
180 #endif /* STDCALL */
181
182 #define ITTAPI ITTAPI_CDECL
183 #define LIBITTAPI ITTAPI_CDECL
184
185 /* TODO: Temporary for compatibility! */
186 #define ITTAPI_CALL ITTAPI_CDECL
187 #define LIBITTAPI_CALL ITTAPI_CDECL
188
189 #if ITT_PLATFORM==ITT_PLATFORM_WIN
190 /* use __forceinline (VC++ specific) */
191 #if defined(__MINGW32__) && !defined(__cplusplus)
192 #define ITT_INLINE static __inline__ __attribute__((__always_inline__,__gnu_inline__))
193 #else
194 #define ITT_INLINE static __forceinline
195 #endif /* __MINGW32__ */
196
197 #define ITT_INLINE_ATTRIBUTE /* nothing */
198 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
199 /*
200 * Generally, functions are not inlined unless optimization is specified.
201 * For functions declared inline, this attribute inlines the function even
202 * if no optimization level was specified.
203 */
204 #ifdef __STRICT_ANSI__
205 #define ITT_INLINE static
206 #define ITT_INLINE_ATTRIBUTE __attribute__((unused))
207 #else /* __STRICT_ANSI__ */
208 #define ITT_INLINE static inline
209 #define ITT_INLINE_ATTRIBUTE __attribute__((always_inline, unused))
210 #endif /* __STRICT_ANSI__ */
211 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
212 /** @endcond */
213
214 #ifdef INTEL_ITTNOTIFY_ENABLE_LEGACY
215 # if ITT_PLATFORM==ITT_PLATFORM_WIN
216 # pragma message("WARNING!!! Deprecated API is used. Please undefine INTEL_ITTNOTIFY_ENABLE_LEGACY macro")
217 # else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
218 # warning "Deprecated API is used. Please undefine INTEL_ITTNOTIFY_ENABLE_LEGACY macro"
219 # endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
220 # include "legacy/ittnotify.h"
221 #endif /* INTEL_ITTNOTIFY_ENABLE_LEGACY */
222
223 /** @cond exclude_from_documentation */
224 /* Helper macro for joining tokens */
225 #define ITT_JOIN_AUX(p,n) p##n
226 #define ITT_JOIN(p,n) ITT_JOIN_AUX(p,n)
227
228 #ifdef ITT_MAJOR
229 #undef ITT_MAJOR
230 #endif
231 #ifdef ITT_MINOR
232 #undef ITT_MINOR
233 #endif
234 #define ITT_MAJOR 3
235 #define ITT_MINOR 0
236
237 /* Standard versioning of a token with major and minor version numbers */
238 #define ITT_VERSIONIZE(x) \
239 ITT_JOIN(x, \
240 ITT_JOIN(_, \
241 ITT_JOIN(ITT_MAJOR, \
242 ITT_JOIN(_, ITT_MINOR))))
243
244 #ifndef INTEL_ITTNOTIFY_PREFIX
245 # define INTEL_ITTNOTIFY_PREFIX __itt_
246 #endif /* INTEL_ITTNOTIFY_PREFIX */
247 #ifndef INTEL_ITTNOTIFY_POSTFIX
248 # define INTEL_ITTNOTIFY_POSTFIX _ptr_
249 #endif /* INTEL_ITTNOTIFY_POSTFIX */
250
251 #define ITTNOTIFY_NAME_AUX(n) ITT_JOIN(INTEL_ITTNOTIFY_PREFIX,n)
252 #define ITTNOTIFY_NAME(n) ITT_VERSIONIZE(ITTNOTIFY_NAME_AUX(ITT_JOIN(n,INTEL_ITTNOTIFY_POSTFIX)))
253
254 #define ITTNOTIFY_VOID(n) (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)
255 #define ITTNOTIFY_DATA(n) (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)
256
257 #define ITTNOTIFY_VOID_D0(n,d) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d)
258 #define ITTNOTIFY_VOID_D1(n,d,x) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x)
259 #define ITTNOTIFY_VOID_D2(n,d,x,y) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y)
260 #define ITTNOTIFY_VOID_D3(n,d,x,y,z) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z)
261 #define ITTNOTIFY_VOID_D4(n,d,x,y,z,a) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z,a)
262 #define ITTNOTIFY_VOID_D5(n,d,x,y,z,a,b) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b)
263 #define ITTNOTIFY_VOID_D6(n,d,x,y,z,a,b,c) (d == NULL) ? (void)0 : (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b,c)
264 #define ITTNOTIFY_DATA_D0(n,d) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d)
265 #define ITTNOTIFY_DATA_D1(n,d,x) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x)
266 #define ITTNOTIFY_DATA_D2(n,d,x,y) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y)
267 #define ITTNOTIFY_DATA_D3(n,d,x,y,z) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z)
268 #define ITTNOTIFY_DATA_D4(n,d,x,y,z,a) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z,a)
269 #define ITTNOTIFY_DATA_D5(n,d,x,y,z,a,b) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b)
270 #define ITTNOTIFY_DATA_D6(n,d,x,y,z,a,b,c) (d == NULL) ? 0 : (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b,c)
271
272 #ifdef ITT_STUB
273 #undef ITT_STUB
274 #endif
275 #ifdef ITT_STUBV
276 #undef ITT_STUBV
277 #endif
278 #define ITT_STUBV(api,type,name,args) \
279 typedef type (api* ITT_JOIN(ITTNOTIFY_NAME(name),_t)) args; \
280 extern ITT_JOIN(ITTNOTIFY_NAME(name),_t) ITTNOTIFY_NAME(name);
281 #define ITT_STUB ITT_STUBV
282 /** @endcond */
283
284 #ifdef __cplusplus
285 extern "C" {
286 #endif /* __cplusplus */
287
288 /** @cond exclude_from_gpa_documentation */
289 /**
290 * @defgroup public Public API
291 * @{
292 * @}
293 */
294
295 /**
296 * @defgroup control Collection Control
297 * @ingroup public
298 * General behavior: application continues to run, but no profiling information is being collected
299 *
300 * Pausing occurs not only for the current thread but for all process as well as spawned processes
301 * - Intel(R) Parallel Inspector and Intel(R) Inspector XE:
302 * - Does not analyze or report errors that involve memory access.
303 * - Other errors are reported as usual. Pausing data collection in
304 * Intel(R) Parallel Inspector and Intel(R) Inspector XE
305 * only pauses tracing and analyzing memory access.
306 * It does not pause tracing or analyzing threading APIs.
307 * .
308 * - Intel(R) Parallel Amplifier and Intel(R) VTune(TM) Amplifier XE:
309 * - Does continue to record when new threads are started.
310 * .
311 * - Other effects:
312 * - Possible reduction of runtime overhead.
313 * .
314 * @{
315 */
316 /** @brief Pause collection */
317 void ITTAPI __itt_pause(void);
318 /** @brief Resume collection */
319 void ITTAPI __itt_resume(void);
320 /** @brief Detach collection */
321 void ITTAPI __itt_detach(void);
322
323 /**
324 * @enum __itt_collection_scope
325 * @brief Enumerator for collection scopes
326 */
327 typedef enum {
328 __itt_collection_scope_host = 1 << 0,
329 __itt_collection_scope_offload = 1 << 1,
330 __itt_collection_scope_all = 0x7FFFFFFF
331 } __itt_collection_scope;
332
333 /** @brief Pause scoped collection */
334 void ITTAPI __itt_pause_scoped(__itt_collection_scope);
335 /** @brief Resume scoped collection */
336 void ITTAPI __itt_resume_scoped(__itt_collection_scope);
337
338 /** @cond exclude_from_documentation */
339 #ifndef INTEL_NO_MACRO_BODY
340 #ifndef INTEL_NO_ITTNOTIFY_API
341 ITT_STUBV(ITTAPI, void, pause, (void))
342 ITT_STUBV(ITTAPI, void, pause_scoped, (__itt_collection_scope))
343 ITT_STUBV(ITTAPI, void, resume, (void))
344 ITT_STUBV(ITTAPI, void, resume_scoped, (__itt_collection_scope))
345 ITT_STUBV(ITTAPI, void, detach, (void))
346 #define __itt_pause ITTNOTIFY_VOID(pause)
347 #define __itt_pause_ptr ITTNOTIFY_NAME(pause)
348 #define __itt_pause_scoped ITTNOTIFY_VOID(pause_scoped)
349 #define __itt_pause_scoped_ptr ITTNOTIFY_NAME(pause_scoped)
350 #define __itt_resume ITTNOTIFY_VOID(resume)
351 #define __itt_resume_ptr ITTNOTIFY_NAME(resume)
352 #define __itt_resume_scoped ITTNOTIFY_VOID(resume_scoped)
353 #define __itt_resume_scoped_ptr ITTNOTIFY_NAME(resume_scoped)
354 #define __itt_detach ITTNOTIFY_VOID(detach)
355 #define __itt_detach_ptr ITTNOTIFY_NAME(detach)
356 #else /* INTEL_NO_ITTNOTIFY_API */
357 #define __itt_pause()
358 #define __itt_pause_ptr 0
359 #define __itt_pause_scoped(scope)
360 #define __itt_pause_scoped_ptr 0
361 #define __itt_resume()
362 #define __itt_resume_ptr 0
363 #define __itt_resume_scoped(scope)
364 #define __itt_resume_scoped_ptr 0
365 #define __itt_detach()
366 #define __itt_detach_ptr 0
367 #endif /* INTEL_NO_ITTNOTIFY_API */
368 #else /* INTEL_NO_MACRO_BODY */
369 #define __itt_pause_ptr 0
370 #define __itt_pause_scoped_ptr 0
371 #define __itt_resume_ptr 0
372 #define __itt_resume_scoped_ptr 0
373 #define __itt_detach_ptr 0
374 #endif /* INTEL_NO_MACRO_BODY */
375 /** @endcond */
376 /** @} control group */
377 /** @endcond */
378
379 /**
380 * @defgroup Intel Processor Trace control
381 * API from this group provides control over collection and analysis of Intel Processor Trace (Intel PT) data
382 * Information about Intel Processor Trace technology can be found here (Volume 3 chapter 35):
383 * https://github.com/tpn/pdfs/blob/master/Intel%2064%20and%20IA-32%20Architectures%20Software%20Developer's%20Manual%20-%20Combined%20Volumes%201-4%20-%20May%202018%20(325462-sdm-vol-1-2abcd-3abcd).pdf
384 * Use this API to mark particular code regions for loading detailed performance statistics.
385 * This mode makes your analysis faster and more accurate.
386 * @{
387 */
388 typedef unsigned char __itt_pt_region;
389
390 /**
391 * @brief function saves a region name marked with Intel PT API and returns a region id.
392 * Only 7 names can be registered. Attempts to register more names will be ignored and a region id with auto names will be returned.
393 * For automatic naming of regions pass NULL as function parameter
394 */
395 #if ITT_PLATFORM==ITT_PLATFORM_WIN
396 __itt_pt_region ITTAPI __itt_pt_region_createA(const char *name);
397 __itt_pt_region ITTAPI __itt_pt_region_createW(const wchar_t *name);
398 #if defined(UNICODE) || defined(_UNICODE)
399 # define __itt_pt_region_create __itt_pt_region_createW
400 #else /* UNICODE */
401 # define __itt_pt_region_create __itt_pt_region_createA
402 #endif /* UNICODE */
403 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
404 __itt_pt_region ITTAPI __itt_pt_region_create(const char *name);
405 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
406
407 /** @cond exclude_from_documentation */
408 #ifndef INTEL_NO_MACRO_BODY
409 #ifndef INTEL_NO_ITTNOTIFY_API
410 #if ITT_PLATFORM==ITT_PLATFORM_WIN
411 ITT_STUB(ITTAPI, __itt_pt_region, pt_region_createA, (const char *name))
412 ITT_STUB(ITTAPI, __itt_pt_region, pt_region_createW, (const wchar_t *name))
413 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
414 ITT_STUB(ITTAPI, __itt_pt_region, pt_region_create, (const char *name))
415 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
416 #if ITT_PLATFORM==ITT_PLATFORM_WIN
417 #define __itt_pt_region_createA ITTNOTIFY_DATA(pt_region_createA)
418 #define __itt_pt_region_createA_ptr ITTNOTIFY_NAME(pt_region_createA)
419 #define __itt_pt_region_createW ITTNOTIFY_DATA(pt_region_createW)
420 #define __itt_pt_region_createW_ptr ITTNOTIFY_NAME(pt_region_createW)
421 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
422 #define __itt_pt_region_create ITTNOTIFY_DATA(pt_region_create)
423 #define __itt_pt_region_create_ptr ITTNOTIFY_NAME(pt_region_create)
424 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
425 #else /* INTEL_NO_ITTNOTIFY_API */
426 #if ITT_PLATFORM==ITT_PLATFORM_WIN
427 #define __itt_pt_region_createA(name) (__itt_pt_region)0
428 #define __itt_pt_region_createA_ptr 0
429 #define __itt_pt_region_createW(name) (__itt_pt_region)0
430 #define __itt_pt_region_createW_ptr 0
431 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
432 #define __itt_pt_region_create(name) (__itt_pt_region)0
433 #define __itt_pt_region_create_ptr 0
434 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
435 #endif /* INTEL_NO_ITTNOTIFY_API */
436 #else /* INTEL_NO_MACRO_BODY */
437 #if ITT_PLATFORM==ITT_PLATFORM_WIN
438 #define __itt_pt_region_createA_ptr 0
439 #define __itt_pt_region_createW_ptr 0
440 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
441 #define __itt_pt_region_create_ptr 0
442 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
443 #endif /* INTEL_NO_MACRO_BODY */
444 /** @endcond */
445
446 /**
447 * @brief function contains a special code pattern identified on the post-processing stage and
448 * marks the beginning of a code region targeted for Intel PT analysis
449 * @param[in] region - region id, 0 <= region < 8
450 */
451 void __itt_mark_pt_region_begin(__itt_pt_region region);
452 /**
453 * @brief function contains a special code pattern identified on the post-processing stage and
454 * marks the end of a code region targeted for Intel PT analysis
455 * @param[in] region - region id, 0 <= region < 8
456 */
457 void __itt_mark_pt_region_end(__itt_pt_region region);
458 /** @} Intel PT control group*/
459
460 /**
461 * @defgroup threads Threads
462 * @ingroup public
463 * Give names to threads
464 * @{
465 */
466 /**
467 * @brief Sets thread name of calling thread
468 * @param[in] name - name of thread
469 */
470 #if ITT_PLATFORM==ITT_PLATFORM_WIN
471 void ITTAPI __itt_thread_set_nameA(const char *name);
472 void ITTAPI __itt_thread_set_nameW(const wchar_t *name);
473 #if defined(UNICODE) || defined(_UNICODE)
474 # define __itt_thread_set_name __itt_thread_set_nameW
475 # define __itt_thread_set_name_ptr __itt_thread_set_nameW_ptr
476 #else /* UNICODE */
477 # define __itt_thread_set_name __itt_thread_set_nameA
478 # define __itt_thread_set_name_ptr __itt_thread_set_nameA_ptr
479 #endif /* UNICODE */
480 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
481 void ITTAPI __itt_thread_set_name(const char *name);
482 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
483
484 /** @cond exclude_from_documentation */
485 #ifndef INTEL_NO_MACRO_BODY
486 #ifndef INTEL_NO_ITTNOTIFY_API
487 #if ITT_PLATFORM==ITT_PLATFORM_WIN
488 ITT_STUBV(ITTAPI, void, thread_set_nameA, (const char *name))
489 ITT_STUBV(ITTAPI, void, thread_set_nameW, (const wchar_t *name))
490 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
491 ITT_STUBV(ITTAPI, void, thread_set_name, (const char *name))
492 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
493 #if ITT_PLATFORM==ITT_PLATFORM_WIN
494 #define __itt_thread_set_nameA ITTNOTIFY_VOID(thread_set_nameA)
495 #define __itt_thread_set_nameA_ptr ITTNOTIFY_NAME(thread_set_nameA)
496 #define __itt_thread_set_nameW ITTNOTIFY_VOID(thread_set_nameW)
497 #define __itt_thread_set_nameW_ptr ITTNOTIFY_NAME(thread_set_nameW)
498 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
499 #define __itt_thread_set_name ITTNOTIFY_VOID(thread_set_name)
500 #define __itt_thread_set_name_ptr ITTNOTIFY_NAME(thread_set_name)
501 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
502 #else /* INTEL_NO_ITTNOTIFY_API */
503 #if ITT_PLATFORM==ITT_PLATFORM_WIN
504 #define __itt_thread_set_nameA(name)
505 #define __itt_thread_set_nameA_ptr 0
506 #define __itt_thread_set_nameW(name)
507 #define __itt_thread_set_nameW_ptr 0
508 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
509 #define __itt_thread_set_name(name)
510 #define __itt_thread_set_name_ptr 0
511 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
512 #endif /* INTEL_NO_ITTNOTIFY_API */
513 #else /* INTEL_NO_MACRO_BODY */
514 #if ITT_PLATFORM==ITT_PLATFORM_WIN
515 #define __itt_thread_set_nameA_ptr 0
516 #define __itt_thread_set_nameW_ptr 0
517 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
518 #define __itt_thread_set_name_ptr 0
519 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
520 #endif /* INTEL_NO_MACRO_BODY */
521 /** @endcond */
522
523 /** @cond exclude_from_gpa_documentation */
524
525 /**
526 * @brief Mark current thread as ignored from this point on, for the duration of its existence.
527 */
528 void ITTAPI __itt_thread_ignore(void);
529
530 /** @cond exclude_from_documentation */
531 #ifndef INTEL_NO_MACRO_BODY
532 #ifndef INTEL_NO_ITTNOTIFY_API
533 ITT_STUBV(ITTAPI, void, thread_ignore, (void))
534 #define __itt_thread_ignore ITTNOTIFY_VOID(thread_ignore)
535 #define __itt_thread_ignore_ptr ITTNOTIFY_NAME(thread_ignore)
536 #else /* INTEL_NO_ITTNOTIFY_API */
537 #define __itt_thread_ignore()
538 #define __itt_thread_ignore_ptr 0
539 #endif /* INTEL_NO_ITTNOTIFY_API */
540 #else /* INTEL_NO_MACRO_BODY */
541 #define __itt_thread_ignore_ptr 0
542 #endif /* INTEL_NO_MACRO_BODY */
543 /** @endcond */
544 /** @} threads group */
545
546 /**
547 * @defgroup suppress Error suppression
548 * @ingroup public
549 * General behavior: application continues to run, but errors are suppressed
550 *
551 * @{
552 */
553
554 /*****************************************************************//**
555 * @name group of functions used for error suppression in correctness tools
556 *********************************************************************/
557 /** @{ */
558 /**
559 * @hideinitializer
560 * @brief possible value for suppression mask
561 */
562 #define __itt_suppress_all_errors 0x7fffffff
563
564 /**
565 * @hideinitializer
566 * @brief possible value for suppression mask (suppresses errors from threading analysis)
567 */
568 #define __itt_suppress_threading_errors 0x000000ff
569
570 /**
571 * @hideinitializer
572 * @brief possible value for suppression mask (suppresses errors from memory analysis)
573 */
574 #define __itt_suppress_memory_errors 0x0000ff00
575
576 /**
577 * @brief Start suppressing errors identified in mask on this thread
578 */
579 void ITTAPI __itt_suppress_push(unsigned int mask);
580
581 /** @cond exclude_from_documentation */
582 #ifndef INTEL_NO_MACRO_BODY
583 #ifndef INTEL_NO_ITTNOTIFY_API
584 ITT_STUBV(ITTAPI, void, suppress_push, (unsigned int mask))
585 #define __itt_suppress_push ITTNOTIFY_VOID(suppress_push)
586 #define __itt_suppress_push_ptr ITTNOTIFY_NAME(suppress_push)
587 #else /* INTEL_NO_ITTNOTIFY_API */
588 #define __itt_suppress_push(mask)
589 #define __itt_suppress_push_ptr 0
590 #endif /* INTEL_NO_ITTNOTIFY_API */
591 #else /* INTEL_NO_MACRO_BODY */
592 #define __itt_suppress_push_ptr 0
593 #endif /* INTEL_NO_MACRO_BODY */
594 /** @endcond */
595
596 /**
597 * @brief Undo the effects of the matching call to __itt_suppress_push
598 */
599 void ITTAPI __itt_suppress_pop(void);
600
601 /** @cond exclude_from_documentation */
602 #ifndef INTEL_NO_MACRO_BODY
603 #ifndef INTEL_NO_ITTNOTIFY_API
604 ITT_STUBV(ITTAPI, void, suppress_pop, (void))
605 #define __itt_suppress_pop ITTNOTIFY_VOID(suppress_pop)
606 #define __itt_suppress_pop_ptr ITTNOTIFY_NAME(suppress_pop)
607 #else /* INTEL_NO_ITTNOTIFY_API */
608 #define __itt_suppress_pop()
609 #define __itt_suppress_pop_ptr 0
610 #endif /* INTEL_NO_ITTNOTIFY_API */
611 #else /* INTEL_NO_MACRO_BODY */
612 #define __itt_suppress_pop_ptr 0
613 #endif /* INTEL_NO_MACRO_BODY */
614 /** @endcond */
615
616 /**
617 * @enum __itt_suppress_mode
618 * @brief Enumerator for the suppressing modes
619 */
620 typedef enum __itt_suppress_mode {
621 __itt_unsuppress_range,
622 __itt_suppress_range
623 } __itt_suppress_mode_t;
624
625 /**
626 * @enum __itt_collection_state
627 * @brief Enumerator for collection state.
628 */
629 typedef enum {
630 __itt_collection_uninitialized = 0, /* uninitialized */
631 __itt_collection_init_fail = 1, /* failed to init */
632 __itt_collection_collector_absent = 2, /* non work state collector is absent */
633 __itt_collection_collector_exists = 3, /* work state collector exists */
634 __itt_collection_init_successful = 4 /* success to init */
635 } __itt_collection_state;
636
637 /**
638 * @brief Mark a range of memory for error suppression or unsuppression for error types included in mask
639 */
640 void ITTAPI __itt_suppress_mark_range(__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size);
641
642 /** @cond exclude_from_documentation */
643 #ifndef INTEL_NO_MACRO_BODY
644 #ifndef INTEL_NO_ITTNOTIFY_API
645 ITT_STUBV(ITTAPI, void, suppress_mark_range, (__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size))
646 #define __itt_suppress_mark_range ITTNOTIFY_VOID(suppress_mark_range)
647 #define __itt_suppress_mark_range_ptr ITTNOTIFY_NAME(suppress_mark_range)
648 #else /* INTEL_NO_ITTNOTIFY_API */
649 #define __itt_suppress_mark_range(mask)
650 #define __itt_suppress_mark_range_ptr 0
651 #endif /* INTEL_NO_ITTNOTIFY_API */
652 #else /* INTEL_NO_MACRO_BODY */
653 #define __itt_suppress_mark_range_ptr 0
654 #endif /* INTEL_NO_MACRO_BODY */
655 /** @endcond */
656
657 /**
658 * @brief Undo the effect of a matching call to __itt_suppress_mark_range. If not matching
659 * call is found, nothing is changed.
660 */
661 void ITTAPI __itt_suppress_clear_range(__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size);
662
663 /** @cond exclude_from_documentation */
664 #ifndef INTEL_NO_MACRO_BODY
665 #ifndef INTEL_NO_ITTNOTIFY_API
666 ITT_STUBV(ITTAPI, void, suppress_clear_range, (__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size))
667 #define __itt_suppress_clear_range ITTNOTIFY_VOID(suppress_clear_range)
668 #define __itt_suppress_clear_range_ptr ITTNOTIFY_NAME(suppress_clear_range)
669 #else /* INTEL_NO_ITTNOTIFY_API */
670 #define __itt_suppress_clear_range(mask)
671 #define __itt_suppress_clear_range_ptr 0
672 #endif /* INTEL_NO_ITTNOTIFY_API */
673 #else /* INTEL_NO_MACRO_BODY */
674 #define __itt_suppress_clear_range_ptr 0
675 #endif /* INTEL_NO_MACRO_BODY */
676 /** @endcond */
677 /** @} */
678 /** @} suppress group */
679
680 /**
681 * @defgroup sync Synchronization
682 * @ingroup public
683 * Indicate user-written synchronization code
684 * @{
685 */
686 /**
687 * @hideinitializer
688 * @brief possible value of attribute argument for sync object type
689 */
690 #define __itt_attr_barrier 1
691
692 /**
693 * @hideinitializer
694 * @brief possible value of attribute argument for sync object type
695 */
696 #define __itt_attr_mutex 2
697
698 /**
699 @brief Name a synchronization object
700 @param[in] addr Handle for the synchronization object. You should
701 use a real address to uniquely identify the synchronization object.
702 @param[in] objtype null-terminated object type string. If NULL is
703 passed, the name will be "User Synchronization".
704 @param[in] objname null-terminated object name string. If NULL,
705 no name will be assigned to the object.
706 @param[in] attribute one of [#__itt_attr_barrier, #__itt_attr_mutex]
707 */
708
709 #if ITT_PLATFORM==ITT_PLATFORM_WIN
710 void ITTAPI __itt_sync_createA(void *addr, const char *objtype, const char *objname, int attribute);
711 void ITTAPI __itt_sync_createW(void *addr, const wchar_t *objtype, const wchar_t *objname, int attribute);
712 #if defined(UNICODE) || defined(_UNICODE)
713 # define __itt_sync_create __itt_sync_createW
714 # define __itt_sync_create_ptr __itt_sync_createW_ptr
715 #else /* UNICODE */
716 # define __itt_sync_create __itt_sync_createA
717 # define __itt_sync_create_ptr __itt_sync_createA_ptr
718 #endif /* UNICODE */
719 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
720 void ITTAPI __itt_sync_create (void *addr, const char *objtype, const char *objname, int attribute);
721 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
722
723 /** @cond exclude_from_documentation */
724 #ifndef INTEL_NO_MACRO_BODY
725 #ifndef INTEL_NO_ITTNOTIFY_API
726 #if ITT_PLATFORM==ITT_PLATFORM_WIN
727 ITT_STUBV(ITTAPI, void, sync_createA, (void *addr, const char *objtype, const char *objname, int attribute))
728 ITT_STUBV(ITTAPI, void, sync_createW, (void *addr, const wchar_t *objtype, const wchar_t *objname, int attribute))
729 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
730 ITT_STUBV(ITTAPI, void, sync_create, (void *addr, const char* objtype, const char* objname, int attribute))
731 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
732 #if ITT_PLATFORM==ITT_PLATFORM_WIN
733 #define __itt_sync_createA ITTNOTIFY_VOID(sync_createA)
734 #define __itt_sync_createA_ptr ITTNOTIFY_NAME(sync_createA)
735 #define __itt_sync_createW ITTNOTIFY_VOID(sync_createW)
736 #define __itt_sync_createW_ptr ITTNOTIFY_NAME(sync_createW)
737 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
738 #define __itt_sync_create ITTNOTIFY_VOID(sync_create)
739 #define __itt_sync_create_ptr ITTNOTIFY_NAME(sync_create)
740 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
741 #else /* INTEL_NO_ITTNOTIFY_API */
742 #if ITT_PLATFORM==ITT_PLATFORM_WIN
743 #define __itt_sync_createA(addr, objtype, objname, attribute)
744 #define __itt_sync_createA_ptr 0
745 #define __itt_sync_createW(addr, objtype, objname, attribute)
746 #define __itt_sync_createW_ptr 0
747 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
748 #define __itt_sync_create(addr, objtype, objname, attribute)
749 #define __itt_sync_create_ptr 0
750 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
751 #endif /* INTEL_NO_ITTNOTIFY_API */
752 #else /* INTEL_NO_MACRO_BODY */
753 #if ITT_PLATFORM==ITT_PLATFORM_WIN
754 #define __itt_sync_createA_ptr 0
755 #define __itt_sync_createW_ptr 0
756 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
757 #define __itt_sync_create_ptr 0
758 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
759 #endif /* INTEL_NO_MACRO_BODY */
760 /** @endcond */
761
762 /**
763 @brief Rename a synchronization object
764
765 You can use the rename call to assign or reassign a name to a given
766 synchronization object.
767 @param[in] addr handle for the synchronization object.
768 @param[in] name null-terminated object name string.
769 */
770 #if ITT_PLATFORM==ITT_PLATFORM_WIN
771 void ITTAPI __itt_sync_renameA(void *addr, const char *name);
772 void ITTAPI __itt_sync_renameW(void *addr, const wchar_t *name);
773 #if defined(UNICODE) || defined(_UNICODE)
774 # define __itt_sync_rename __itt_sync_renameW
775 # define __itt_sync_rename_ptr __itt_sync_renameW_ptr
776 #else /* UNICODE */
777 # define __itt_sync_rename __itt_sync_renameA
778 # define __itt_sync_rename_ptr __itt_sync_renameA_ptr
779 #endif /* UNICODE */
780 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
781 void ITTAPI __itt_sync_rename(void *addr, const char *name);
782 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
783
784 /** @cond exclude_from_documentation */
785 #ifndef INTEL_NO_MACRO_BODY
786 #ifndef INTEL_NO_ITTNOTIFY_API
787 #if ITT_PLATFORM==ITT_PLATFORM_WIN
788 ITT_STUBV(ITTAPI, void, sync_renameA, (void *addr, const char *name))
789 ITT_STUBV(ITTAPI, void, sync_renameW, (void *addr, const wchar_t *name))
790 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
791 ITT_STUBV(ITTAPI, void, sync_rename, (void *addr, const char *name))
792 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
793 #if ITT_PLATFORM==ITT_PLATFORM_WIN
794 #define __itt_sync_renameA ITTNOTIFY_VOID(sync_renameA)
795 #define __itt_sync_renameA_ptr ITTNOTIFY_NAME(sync_renameA)
796 #define __itt_sync_renameW ITTNOTIFY_VOID(sync_renameW)
797 #define __itt_sync_renameW_ptr ITTNOTIFY_NAME(sync_renameW)
798 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
799 #define __itt_sync_rename ITTNOTIFY_VOID(sync_rename)
800 #define __itt_sync_rename_ptr ITTNOTIFY_NAME(sync_rename)
801 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
802 #else /* INTEL_NO_ITTNOTIFY_API */
803 #if ITT_PLATFORM==ITT_PLATFORM_WIN
804 #define __itt_sync_renameA(addr, name)
805 #define __itt_sync_renameA_ptr 0
806 #define __itt_sync_renameW(addr, name)
807 #define __itt_sync_renameW_ptr 0
808 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
809 #define __itt_sync_rename(addr, name)
810 #define __itt_sync_rename_ptr 0
811 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
812 #endif /* INTEL_NO_ITTNOTIFY_API */
813 #else /* INTEL_NO_MACRO_BODY */
814 #if ITT_PLATFORM==ITT_PLATFORM_WIN
815 #define __itt_sync_renameA_ptr 0
816 #define __itt_sync_renameW_ptr 0
817 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
818 #define __itt_sync_rename_ptr 0
819 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
820 #endif /* INTEL_NO_MACRO_BODY */
821 /** @endcond */
822
823 /**
824 @brief Destroy a synchronization object.
825 @param addr Handle for the synchronization object.
826 */
827 void ITTAPI __itt_sync_destroy(void *addr);
828
829 /** @cond exclude_from_documentation */
830 #ifndef INTEL_NO_MACRO_BODY
831 #ifndef INTEL_NO_ITTNOTIFY_API
832 ITT_STUBV(ITTAPI, void, sync_destroy, (void *addr))
833 #define __itt_sync_destroy ITTNOTIFY_VOID(sync_destroy)
834 #define __itt_sync_destroy_ptr ITTNOTIFY_NAME(sync_destroy)
835 #else /* INTEL_NO_ITTNOTIFY_API */
836 #define __itt_sync_destroy(addr)
837 #define __itt_sync_destroy_ptr 0
838 #endif /* INTEL_NO_ITTNOTIFY_API */
839 #else /* INTEL_NO_MACRO_BODY */
840 #define __itt_sync_destroy_ptr 0
841 #endif /* INTEL_NO_MACRO_BODY */
842 /** @endcond */
843
844 /*****************************************************************//**
845 * @name group of functions is used for performance measurement tools
846 *********************************************************************/
847 /** @{ */
848 /**
849 * @brief Enter spin loop on user-defined sync object
850 */
851 void ITTAPI __itt_sync_prepare(void* addr);
852
853 /** @cond exclude_from_documentation */
854 #ifndef INTEL_NO_MACRO_BODY
855 #ifndef INTEL_NO_ITTNOTIFY_API
856 ITT_STUBV(ITTAPI, void, sync_prepare, (void *addr))
857 #define __itt_sync_prepare ITTNOTIFY_VOID(sync_prepare)
858 #define __itt_sync_prepare_ptr ITTNOTIFY_NAME(sync_prepare)
859 #else /* INTEL_NO_ITTNOTIFY_API */
860 #define __itt_sync_prepare(addr)
861 #define __itt_sync_prepare_ptr 0
862 #endif /* INTEL_NO_ITTNOTIFY_API */
863 #else /* INTEL_NO_MACRO_BODY */
864 #define __itt_sync_prepare_ptr 0
865 #endif /* INTEL_NO_MACRO_BODY */
866 /** @endcond */
867
868 /**
869 * @brief Quit spin loop without acquiring spin object
870 */
871 void ITTAPI __itt_sync_cancel(void *addr);
872
873 /** @cond exclude_from_documentation */
874 #ifndef INTEL_NO_MACRO_BODY
875 #ifndef INTEL_NO_ITTNOTIFY_API
876 ITT_STUBV(ITTAPI, void, sync_cancel, (void *addr))
877 #define __itt_sync_cancel ITTNOTIFY_VOID(sync_cancel)
878 #define __itt_sync_cancel_ptr ITTNOTIFY_NAME(sync_cancel)
879 #else /* INTEL_NO_ITTNOTIFY_API */
880 #define __itt_sync_cancel(addr)
881 #define __itt_sync_cancel_ptr 0
882 #endif /* INTEL_NO_ITTNOTIFY_API */
883 #else /* INTEL_NO_MACRO_BODY */
884 #define __itt_sync_cancel_ptr 0
885 #endif /* INTEL_NO_MACRO_BODY */
886 /** @endcond */
887
888 /**
889 * @brief Successful spin loop completion (sync object acquired)
890 */
891 void ITTAPI __itt_sync_acquired(void *addr);
892
893 /** @cond exclude_from_documentation */
894 #ifndef INTEL_NO_MACRO_BODY
895 #ifndef INTEL_NO_ITTNOTIFY_API
896 ITT_STUBV(ITTAPI, void, sync_acquired, (void *addr))
897 #define __itt_sync_acquired ITTNOTIFY_VOID(sync_acquired)
898 #define __itt_sync_acquired_ptr ITTNOTIFY_NAME(sync_acquired)
899 #else /* INTEL_NO_ITTNOTIFY_API */
900 #define __itt_sync_acquired(addr)
901 #define __itt_sync_acquired_ptr 0
902 #endif /* INTEL_NO_ITTNOTIFY_API */
903 #else /* INTEL_NO_MACRO_BODY */
904 #define __itt_sync_acquired_ptr 0
905 #endif /* INTEL_NO_MACRO_BODY */
906 /** @endcond */
907
908 /**
909 * @brief Start sync object releasing code. Is called before the lock release call.
910 */
911 void ITTAPI __itt_sync_releasing(void* addr);
912
913 /** @cond exclude_from_documentation */
914 #ifndef INTEL_NO_MACRO_BODY
915 #ifndef INTEL_NO_ITTNOTIFY_API
916 ITT_STUBV(ITTAPI, void, sync_releasing, (void *addr))
917 #define __itt_sync_releasing ITTNOTIFY_VOID(sync_releasing)
918 #define __itt_sync_releasing_ptr ITTNOTIFY_NAME(sync_releasing)
919 #else /* INTEL_NO_ITTNOTIFY_API */
920 #define __itt_sync_releasing(addr)
921 #define __itt_sync_releasing_ptr 0
922 #endif /* INTEL_NO_ITTNOTIFY_API */
923 #else /* INTEL_NO_MACRO_BODY */
924 #define __itt_sync_releasing_ptr 0
925 #endif /* INTEL_NO_MACRO_BODY */
926 /** @endcond */
927 /** @} */
928
929 /** @} sync group */
930
931 /**************************************************************//**
932 * @name group of functions is used for correctness checking tools
933 ******************************************************************/
934 /** @{ */
935 /**
936 * @ingroup legacy
937 * @deprecated Legacy API
938 * @brief Fast synchronization which does no require spinning.
939 * - This special function is to be used by TBB and OpenMP libraries only when they know
940 * there is no spin but they need to suppress TC warnings about shared variable modifications.
941 * - It only has corresponding pointers in static library and does not have corresponding function
942 * in dynamic library.
943 * @see void __itt_sync_prepare(void* addr);
944 */
945 void ITTAPI __itt_fsync_prepare(void* addr);
946
947 /** @cond exclude_from_documentation */
948 #ifndef INTEL_NO_MACRO_BODY
949 #ifndef INTEL_NO_ITTNOTIFY_API
950 ITT_STUBV(ITTAPI, void, fsync_prepare, (void *addr))
951 #define __itt_fsync_prepare ITTNOTIFY_VOID(fsync_prepare)
952 #define __itt_fsync_prepare_ptr ITTNOTIFY_NAME(fsync_prepare)
953 #else /* INTEL_NO_ITTNOTIFY_API */
954 #define __itt_fsync_prepare(addr)
955 #define __itt_fsync_prepare_ptr 0
956 #endif /* INTEL_NO_ITTNOTIFY_API */
957 #else /* INTEL_NO_MACRO_BODY */
958 #define __itt_fsync_prepare_ptr 0
959 #endif /* INTEL_NO_MACRO_BODY */
960 /** @endcond */
961
962 /**
963 * @ingroup legacy
964 * @deprecated Legacy API
965 * @brief Fast synchronization which does no require spinning.
966 * - This special function is to be used by TBB and OpenMP libraries only when they know
967 * there is no spin but they need to suppress TC warnings about shared variable modifications.
968 * - It only has corresponding pointers in static library and does not have corresponding function
969 * in dynamic library.
970 * @see void __itt_sync_cancel(void *addr);
971 */
972 void ITTAPI __itt_fsync_cancel(void *addr);
973
974 /** @cond exclude_from_documentation */
975 #ifndef INTEL_NO_MACRO_BODY
976 #ifndef INTEL_NO_ITTNOTIFY_API
977 ITT_STUBV(ITTAPI, void, fsync_cancel, (void *addr))
978 #define __itt_fsync_cancel ITTNOTIFY_VOID(fsync_cancel)
979 #define __itt_fsync_cancel_ptr ITTNOTIFY_NAME(fsync_cancel)
980 #else /* INTEL_NO_ITTNOTIFY_API */
981 #define __itt_fsync_cancel(addr)
982 #define __itt_fsync_cancel_ptr 0
983 #endif /* INTEL_NO_ITTNOTIFY_API */
984 #else /* INTEL_NO_MACRO_BODY */
985 #define __itt_fsync_cancel_ptr 0
986 #endif /* INTEL_NO_MACRO_BODY */
987 /** @endcond */
988
989 /**
990 * @ingroup legacy
991 * @deprecated Legacy API
992 * @brief Fast synchronization which does no require spinning.
993 * - This special function is to be used by TBB and OpenMP libraries only when they know
994 * there is no spin but they need to suppress TC warnings about shared variable modifications.
995 * - It only has corresponding pointers in static library and does not have corresponding function
996 * in dynamic library.
997 * @see void __itt_sync_acquired(void *addr);
998 */
999 void ITTAPI __itt_fsync_acquired(void *addr);
1000
1001 /** @cond exclude_from_documentation */
1002 #ifndef INTEL_NO_MACRO_BODY
1003 #ifndef INTEL_NO_ITTNOTIFY_API
1004 ITT_STUBV(ITTAPI, void, fsync_acquired, (void *addr))
1005 #define __itt_fsync_acquired ITTNOTIFY_VOID(fsync_acquired)
1006 #define __itt_fsync_acquired_ptr ITTNOTIFY_NAME(fsync_acquired)
1007 #else /* INTEL_NO_ITTNOTIFY_API */
1008 #define __itt_fsync_acquired(addr)
1009 #define __itt_fsync_acquired_ptr 0
1010 #endif /* INTEL_NO_ITTNOTIFY_API */
1011 #else /* INTEL_NO_MACRO_BODY */
1012 #define __itt_fsync_acquired_ptr 0
1013 #endif /* INTEL_NO_MACRO_BODY */
1014 /** @endcond */
1015
1016 /**
1017 * @ingroup legacy
1018 * @deprecated Legacy API
1019 * @brief Fast synchronization which does no require spinning.
1020 * - This special function is to be used by TBB and OpenMP libraries only when they know
1021 * there is no spin but they need to suppress TC warnings about shared variable modifications.
1022 * - It only has corresponding pointers in static library and does not have corresponding function
1023 * in dynamic library.
1024 * @see void __itt_sync_releasing(void* addr);
1025 */
1026 void ITTAPI __itt_fsync_releasing(void* addr);
1027
1028 /** @cond exclude_from_documentation */
1029 #ifndef INTEL_NO_MACRO_BODY
1030 #ifndef INTEL_NO_ITTNOTIFY_API
1031 ITT_STUBV(ITTAPI, void, fsync_releasing, (void *addr))
1032 #define __itt_fsync_releasing ITTNOTIFY_VOID(fsync_releasing)
1033 #define __itt_fsync_releasing_ptr ITTNOTIFY_NAME(fsync_releasing)
1034 #else /* INTEL_NO_ITTNOTIFY_API */
1035 #define __itt_fsync_releasing(addr)
1036 #define __itt_fsync_releasing_ptr 0
1037 #endif /* INTEL_NO_ITTNOTIFY_API */
1038 #else /* INTEL_NO_MACRO_BODY */
1039 #define __itt_fsync_releasing_ptr 0
1040 #endif /* INTEL_NO_MACRO_BODY */
1041 /** @endcond */
1042 /** @} */
1043
1044 /**
1045 * @defgroup model Modeling by Intel(R) Parallel Advisor
1046 * @ingroup public
1047 * This is the subset of itt used for modeling by Intel(R) Parallel Advisor.
1048 * This API is called ONLY using annotate.h, by "Annotation" macros
1049 * the user places in their sources during the parallelism modeling steps.
1050 *
1051 * site_begin/end and task_begin/end take the address of handle variables,
1052 * which are writeable by the API. Handles must be 0 initialized prior
1053 * to the first call to begin, or may cause a run-time failure.
1054 * The handles are initialized in a multi-thread safe way by the API if
1055 * the handle is 0. The commonly expected idiom is one static handle to
1056 * identify a site or task. If a site or task of the same name has already
1057 * been started during this collection, the same handle MAY be returned,
1058 * but is not required to be - it is unspecified if data merging is done
1059 * based on name. These routines also take an instance variable. Like
1060 * the lexical instance, these must be 0 initialized. Unlike the lexical
1061 * instance, this is used to track a single dynamic instance.
1062 *
1063 * API used by the Intel(R) Parallel Advisor to describe potential concurrency
1064 * and related activities. User-added source annotations expand to calls
1065 * to these procedures to enable modeling of a hypothetical concurrent
1066 * execution serially.
1067 * @{
1068 */
1069 #if !defined(_ADVISOR_ANNOTATE_H_) || defined(ANNOTATE_EXPAND_NULL)
1070
1071 typedef void* __itt_model_site; /*!< @brief handle for lexical site */
1072 typedef void* __itt_model_site_instance; /*!< @brief handle for dynamic instance */
1073 typedef void* __itt_model_task; /*!< @brief handle for lexical site */
1074 typedef void* __itt_model_task_instance; /*!< @brief handle for dynamic instance */
1075
1076 /**
1077 * @enum __itt_model_disable
1078 * @brief Enumerator for the disable methods
1079 */
1080 typedef enum {
1081 __itt_model_disable_observation,
1082 __itt_model_disable_collection
1083 } __itt_model_disable;
1084
1085 #endif /* !_ADVISOR_ANNOTATE_H_ || ANNOTATE_EXPAND_NULL */
1086
1087 /**
1088 * @brief ANNOTATE_SITE_BEGIN/ANNOTATE_SITE_END support.
1089 *
1090 * site_begin/end model a potential concurrency site.
1091 * site instances may be recursively nested with themselves.
1092 * site_end exits the most recently started but unended site for the current
1093 * thread. The handle passed to end may be used to validate structure.
1094 * Instances of a site encountered on different threads concurrently
1095 * are considered completely distinct. If the site name for two different
1096 * lexical sites match, it is unspecified whether they are treated as the
1097 * same or different for data presentation.
1098 */
1099 void ITTAPI __itt_model_site_begin(__itt_model_site *site, __itt_model_site_instance *instance, const char *name);
1100 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1101 void ITTAPI __itt_model_site_beginW(const wchar_t *name);
1102 #endif
1103 void ITTAPI __itt_model_site_beginA(const char *name);
1104 void ITTAPI __itt_model_site_beginAL(const char *name, size_t siteNameLen);
1105 void ITTAPI __itt_model_site_end (__itt_model_site *site, __itt_model_site_instance *instance);
1106 void ITTAPI __itt_model_site_end_2(void);
1107
1108 /** @cond exclude_from_documentation */
1109 #ifndef INTEL_NO_MACRO_BODY
1110 #ifndef INTEL_NO_ITTNOTIFY_API
1111 ITT_STUBV(ITTAPI, void, model_site_begin, (__itt_model_site *site, __itt_model_site_instance *instance, const char *name))
1112 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1113 ITT_STUBV(ITTAPI, void, model_site_beginW, (const wchar_t *name))
1114 #endif
1115 ITT_STUBV(ITTAPI, void, model_site_beginA, (const char *name))
1116 ITT_STUBV(ITTAPI, void, model_site_beginAL, (const char *name, size_t siteNameLen))
1117 ITT_STUBV(ITTAPI, void, model_site_end, (__itt_model_site *site, __itt_model_site_instance *instance))
1118 ITT_STUBV(ITTAPI, void, model_site_end_2, (void))
1119 #define __itt_model_site_begin ITTNOTIFY_VOID(model_site_begin)
1120 #define __itt_model_site_begin_ptr ITTNOTIFY_NAME(model_site_begin)
1121 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1122 #define __itt_model_site_beginW ITTNOTIFY_VOID(model_site_beginW)
1123 #define __itt_model_site_beginW_ptr ITTNOTIFY_NAME(model_site_beginW)
1124 #endif
1125 #define __itt_model_site_beginA ITTNOTIFY_VOID(model_site_beginA)
1126 #define __itt_model_site_beginA_ptr ITTNOTIFY_NAME(model_site_beginA)
1127 #define __itt_model_site_beginAL ITTNOTIFY_VOID(model_site_beginAL)
1128 #define __itt_model_site_beginAL_ptr ITTNOTIFY_NAME(model_site_beginAL)
1129 #define __itt_model_site_end ITTNOTIFY_VOID(model_site_end)
1130 #define __itt_model_site_end_ptr ITTNOTIFY_NAME(model_site_end)
1131 #define __itt_model_site_end_2 ITTNOTIFY_VOID(model_site_end_2)
1132 #define __itt_model_site_end_2_ptr ITTNOTIFY_NAME(model_site_end_2)
1133 #else /* INTEL_NO_ITTNOTIFY_API */
1134 #define __itt_model_site_begin(site, instance, name)
1135 #define __itt_model_site_begin_ptr 0
1136 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1137 #define __itt_model_site_beginW(name)
1138 #define __itt_model_site_beginW_ptr 0
1139 #endif
1140 #define __itt_model_site_beginA(name)
1141 #define __itt_model_site_beginA_ptr 0
1142 #define __itt_model_site_beginAL(name, siteNameLen)
1143 #define __itt_model_site_beginAL_ptr 0
1144 #define __itt_model_site_end(site, instance)
1145 #define __itt_model_site_end_ptr 0
1146 #define __itt_model_site_end_2()
1147 #define __itt_model_site_end_2_ptr 0
1148 #endif /* INTEL_NO_ITTNOTIFY_API */
1149 #else /* INTEL_NO_MACRO_BODY */
1150 #define __itt_model_site_begin_ptr 0
1151 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1152 #define __itt_model_site_beginW_ptr 0
1153 #endif
1154 #define __itt_model_site_beginA_ptr 0
1155 #define __itt_model_site_beginAL_ptr 0
1156 #define __itt_model_site_end_ptr 0
1157 #define __itt_model_site_end_2_ptr 0
1158 #endif /* INTEL_NO_MACRO_BODY */
1159 /** @endcond */
1160
1161 /**
1162 * @brief ANNOTATE_TASK_BEGIN/ANNOTATE_TASK_END support
1163 *
1164 * task_begin/end model a potential task, which is contained within the most
1165 * closely enclosing dynamic site. task_end exits the most recently started
1166 * but unended task. The handle passed to end may be used to validate
1167 * structure. It is unspecified if bad dynamic nesting is detected. If it
1168 * is, it should be encoded in the resulting data collection. The collector
1169 * should not fail due to construct nesting issues, nor attempt to directly
1170 * indicate the problem.
1171 */
1172 void ITTAPI __itt_model_task_begin(__itt_model_task *task, __itt_model_task_instance *instance, const char *name);
1173 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1174 void ITTAPI __itt_model_task_beginW(const wchar_t *name);
1175 void ITTAPI __itt_model_iteration_taskW(const wchar_t *name);
1176 #endif
1177 void ITTAPI __itt_model_task_beginA(const char *name);
1178 void ITTAPI __itt_model_task_beginAL(const char *name, size_t taskNameLen);
1179 void ITTAPI __itt_model_iteration_taskA(const char *name);
1180 void ITTAPI __itt_model_iteration_taskAL(const char *name, size_t taskNameLen);
1181 void ITTAPI __itt_model_task_end (__itt_model_task *task, __itt_model_task_instance *instance);
1182 void ITTAPI __itt_model_task_end_2(void);
1183
1184 /** @cond exclude_from_documentation */
1185 #ifndef INTEL_NO_MACRO_BODY
1186 #ifndef INTEL_NO_ITTNOTIFY_API
1187 ITT_STUBV(ITTAPI, void, model_task_begin, (__itt_model_task *task, __itt_model_task_instance *instance, const char *name))
1188 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1189 ITT_STUBV(ITTAPI, void, model_task_beginW, (const wchar_t *name))
1190 ITT_STUBV(ITTAPI, void, model_iteration_taskW, (const wchar_t *name))
1191 #endif
1192 ITT_STUBV(ITTAPI, void, model_task_beginA, (const char *name))
1193 ITT_STUBV(ITTAPI, void, model_task_beginAL, (const char *name, size_t taskNameLen))
1194 ITT_STUBV(ITTAPI, void, model_iteration_taskA, (const char *name))
1195 ITT_STUBV(ITTAPI, void, model_iteration_taskAL, (const char *name, size_t taskNameLen))
1196 ITT_STUBV(ITTAPI, void, model_task_end, (__itt_model_task *task, __itt_model_task_instance *instance))
1197 ITT_STUBV(ITTAPI, void, model_task_end_2, (void))
1198 #define __itt_model_task_begin ITTNOTIFY_VOID(model_task_begin)
1199 #define __itt_model_task_begin_ptr ITTNOTIFY_NAME(model_task_begin)
1200 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1201 #define __itt_model_task_beginW ITTNOTIFY_VOID(model_task_beginW)
1202 #define __itt_model_task_beginW_ptr ITTNOTIFY_NAME(model_task_beginW)
1203 #define __itt_model_iteration_taskW ITTNOTIFY_VOID(model_iteration_taskW)
1204 #define __itt_model_iteration_taskW_ptr ITTNOTIFY_NAME(model_iteration_taskW)
1205 #endif
1206 #define __itt_model_task_beginA ITTNOTIFY_VOID(model_task_beginA)
1207 #define __itt_model_task_beginA_ptr ITTNOTIFY_NAME(model_task_beginA)
1208 #define __itt_model_task_beginAL ITTNOTIFY_VOID(model_task_beginAL)
1209 #define __itt_model_task_beginAL_ptr ITTNOTIFY_NAME(model_task_beginAL)
1210 #define __itt_model_iteration_taskA ITTNOTIFY_VOID(model_iteration_taskA)
1211 #define __itt_model_iteration_taskA_ptr ITTNOTIFY_NAME(model_iteration_taskA)
1212 #define __itt_model_iteration_taskAL ITTNOTIFY_VOID(model_iteration_taskAL)
1213 #define __itt_model_iteration_taskAL_ptr ITTNOTIFY_NAME(model_iteration_taskAL)
1214 #define __itt_model_task_end ITTNOTIFY_VOID(model_task_end)
1215 #define __itt_model_task_end_ptr ITTNOTIFY_NAME(model_task_end)
1216 #define __itt_model_task_end_2 ITTNOTIFY_VOID(model_task_end_2)
1217 #define __itt_model_task_end_2_ptr ITTNOTIFY_NAME(model_task_end_2)
1218 #else /* INTEL_NO_ITTNOTIFY_API */
1219 #define __itt_model_task_begin(task, instance, name)
1220 #define __itt_model_task_begin_ptr 0
1221 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1222 #define __itt_model_task_beginW(name)
1223 #define __itt_model_task_beginW_ptr 0
1224 #endif
1225 #define __itt_model_task_beginA(name)
1226 #define __itt_model_task_beginA_ptr 0
1227 #define __itt_model_task_beginAL(name, siteNameLen)
1228 #define __itt_model_task_beginAL_ptr 0
1229 #define __itt_model_iteration_taskA(name)
1230 #define __itt_model_iteration_taskA_ptr 0
1231 #define __itt_model_iteration_taskAL(name, siteNameLen)
1232 #define __itt_model_iteration_taskAL_ptr 0
1233 #define __itt_model_task_end(task, instance)
1234 #define __itt_model_task_end_ptr 0
1235 #define __itt_model_task_end_2()
1236 #define __itt_model_task_end_2_ptr 0
1237 #endif /* INTEL_NO_ITTNOTIFY_API */
1238 #else /* INTEL_NO_MACRO_BODY */
1239 #define __itt_model_task_begin_ptr 0
1240 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1241 #define __itt_model_task_beginW_ptr 0
1242 #endif
1243 #define __itt_model_task_beginA_ptr 0
1244 #define __itt_model_task_beginAL_ptr 0
1245 #define __itt_model_iteration_taskA_ptr 0
1246 #define __itt_model_iteration_taskAL_ptr 0
1247 #define __itt_model_task_end_ptr 0
1248 #define __itt_model_task_end_2_ptr 0
1249 #endif /* INTEL_NO_MACRO_BODY */
1250 /** @endcond */
1251
1252 /**
1253 * @brief ANNOTATE_LOCK_ACQUIRE/ANNOTATE_LOCK_RELEASE support
1254 *
1255 * lock_acquire/release model a potential lock for both lockset and
1256 * performance modeling. Each unique address is modeled as a separate
1257 * lock, with invalid addresses being valid lock IDs. Specifically:
1258 * no storage is accessed by the API at the specified address - it is only
1259 * used for lock identification. Lock acquires may be self-nested and are
1260 * unlocked by a corresponding number of releases.
1261 * (These closely correspond to __itt_sync_acquired/__itt_sync_releasing,
1262 * but may not have identical semantics.)
1263 */
1264 void ITTAPI __itt_model_lock_acquire(void *lock);
1265 void ITTAPI __itt_model_lock_acquire_2(void *lock);
1266 void ITTAPI __itt_model_lock_release(void *lock);
1267 void ITTAPI __itt_model_lock_release_2(void *lock);
1268
1269 /** @cond exclude_from_documentation */
1270 #ifndef INTEL_NO_MACRO_BODY
1271 #ifndef INTEL_NO_ITTNOTIFY_API
1272 ITT_STUBV(ITTAPI, void, model_lock_acquire, (void *lock))
1273 ITT_STUBV(ITTAPI, void, model_lock_acquire_2, (void *lock))
1274 ITT_STUBV(ITTAPI, void, model_lock_release, (void *lock))
1275 ITT_STUBV(ITTAPI, void, model_lock_release_2, (void *lock))
1276 #define __itt_model_lock_acquire ITTNOTIFY_VOID(model_lock_acquire)
1277 #define __itt_model_lock_acquire_ptr ITTNOTIFY_NAME(model_lock_acquire)
1278 #define __itt_model_lock_acquire_2 ITTNOTIFY_VOID(model_lock_acquire_2)
1279 #define __itt_model_lock_acquire_2_ptr ITTNOTIFY_NAME(model_lock_acquire_2)
1280 #define __itt_model_lock_release ITTNOTIFY_VOID(model_lock_release)
1281 #define __itt_model_lock_release_ptr ITTNOTIFY_NAME(model_lock_release)
1282 #define __itt_model_lock_release_2 ITTNOTIFY_VOID(model_lock_release_2)
1283 #define __itt_model_lock_release_2_ptr ITTNOTIFY_NAME(model_lock_release_2)
1284 #else /* INTEL_NO_ITTNOTIFY_API */
1285 #define __itt_model_lock_acquire(lock)
1286 #define __itt_model_lock_acquire_ptr 0
1287 #define __itt_model_lock_acquire_2(lock)
1288 #define __itt_model_lock_acquire_2_ptr 0
1289 #define __itt_model_lock_release(lock)
1290 #define __itt_model_lock_release_ptr 0
1291 #define __itt_model_lock_release_2(lock)
1292 #define __itt_model_lock_release_2_ptr 0
1293 #endif /* INTEL_NO_ITTNOTIFY_API */
1294 #else /* INTEL_NO_MACRO_BODY */
1295 #define __itt_model_lock_acquire_ptr 0
1296 #define __itt_model_lock_acquire_2_ptr 0
1297 #define __itt_model_lock_release_ptr 0
1298 #define __itt_model_lock_release_2_ptr 0
1299 #endif /* INTEL_NO_MACRO_BODY */
1300 /** @endcond */
1301
1302 /**
1303 * @brief ANNOTATE_RECORD_ALLOCATION/ANNOTATE_RECORD_DEALLOCATION support
1304 *
1305 * record_allocation/deallocation describe user-defined memory allocator
1306 * behavior, which may be required for correctness modeling to understand
1307 * when storage is not expected to be actually reused across threads.
1308 */
1309 void ITTAPI __itt_model_record_allocation (void *addr, size_t size);
1310 void ITTAPI __itt_model_record_deallocation(void *addr);
1311
1312 /** @cond exclude_from_documentation */
1313 #ifndef INTEL_NO_MACRO_BODY
1314 #ifndef INTEL_NO_ITTNOTIFY_API
1315 ITT_STUBV(ITTAPI, void, model_record_allocation, (void *addr, size_t size))
1316 ITT_STUBV(ITTAPI, void, model_record_deallocation, (void *addr))
1317 #define __itt_model_record_allocation ITTNOTIFY_VOID(model_record_allocation)
1318 #define __itt_model_record_allocation_ptr ITTNOTIFY_NAME(model_record_allocation)
1319 #define __itt_model_record_deallocation ITTNOTIFY_VOID(model_record_deallocation)
1320 #define __itt_model_record_deallocation_ptr ITTNOTIFY_NAME(model_record_deallocation)
1321 #else /* INTEL_NO_ITTNOTIFY_API */
1322 #define __itt_model_record_allocation(addr, size)
1323 #define __itt_model_record_allocation_ptr 0
1324 #define __itt_model_record_deallocation(addr)
1325 #define __itt_model_record_deallocation_ptr 0
1326 #endif /* INTEL_NO_ITTNOTIFY_API */
1327 #else /* INTEL_NO_MACRO_BODY */
1328 #define __itt_model_record_allocation_ptr 0
1329 #define __itt_model_record_deallocation_ptr 0
1330 #endif /* INTEL_NO_MACRO_BODY */
1331 /** @endcond */
1332
1333 /**
1334 * @brief ANNOTATE_INDUCTION_USES support
1335 *
1336 * Note particular storage is inductive through the end of the current site
1337 */
1338 void ITTAPI __itt_model_induction_uses(void* addr, size_t size);
1339
1340 /** @cond exclude_from_documentation */
1341 #ifndef INTEL_NO_MACRO_BODY
1342 #ifndef INTEL_NO_ITTNOTIFY_API
1343 ITT_STUBV(ITTAPI, void, model_induction_uses, (void *addr, size_t size))
1344 #define __itt_model_induction_uses ITTNOTIFY_VOID(model_induction_uses)
1345 #define __itt_model_induction_uses_ptr ITTNOTIFY_NAME(model_induction_uses)
1346 #else /* INTEL_NO_ITTNOTIFY_API */
1347 #define __itt_model_induction_uses(addr, size)
1348 #define __itt_model_induction_uses_ptr 0
1349 #endif /* INTEL_NO_ITTNOTIFY_API */
1350 #else /* INTEL_NO_MACRO_BODY */
1351 #define __itt_model_induction_uses_ptr 0
1352 #endif /* INTEL_NO_MACRO_BODY */
1353 /** @endcond */
1354
1355 /**
1356 * @brief ANNOTATE_REDUCTION_USES support
1357 *
1358 * Note particular storage is used for reduction through the end
1359 * of the current site
1360 */
1361 void ITTAPI __itt_model_reduction_uses(void* addr, size_t size);
1362
1363 /** @cond exclude_from_documentation */
1364 #ifndef INTEL_NO_MACRO_BODY
1365 #ifndef INTEL_NO_ITTNOTIFY_API
1366 ITT_STUBV(ITTAPI, void, model_reduction_uses, (void *addr, size_t size))
1367 #define __itt_model_reduction_uses ITTNOTIFY_VOID(model_reduction_uses)
1368 #define __itt_model_reduction_uses_ptr ITTNOTIFY_NAME(model_reduction_uses)
1369 #else /* INTEL_NO_ITTNOTIFY_API */
1370 #define __itt_model_reduction_uses(addr, size)
1371 #define __itt_model_reduction_uses_ptr 0
1372 #endif /* INTEL_NO_ITTNOTIFY_API */
1373 #else /* INTEL_NO_MACRO_BODY */
1374 #define __itt_model_reduction_uses_ptr 0
1375 #endif /* INTEL_NO_MACRO_BODY */
1376 /** @endcond */
1377
1378 /**
1379 * @brief ANNOTATE_OBSERVE_USES support
1380 *
1381 * Have correctness modeling record observations about uses of storage
1382 * through the end of the current site
1383 */
1384 void ITTAPI __itt_model_observe_uses(void* addr, size_t size);
1385
1386 /** @cond exclude_from_documentation */
1387 #ifndef INTEL_NO_MACRO_BODY
1388 #ifndef INTEL_NO_ITTNOTIFY_API
1389 ITT_STUBV(ITTAPI, void, model_observe_uses, (void *addr, size_t size))
1390 #define __itt_model_observe_uses ITTNOTIFY_VOID(model_observe_uses)
1391 #define __itt_model_observe_uses_ptr ITTNOTIFY_NAME(model_observe_uses)
1392 #else /* INTEL_NO_ITTNOTIFY_API */
1393 #define __itt_model_observe_uses(addr, size)
1394 #define __itt_model_observe_uses_ptr 0
1395 #endif /* INTEL_NO_ITTNOTIFY_API */
1396 #else /* INTEL_NO_MACRO_BODY */
1397 #define __itt_model_observe_uses_ptr 0
1398 #endif /* INTEL_NO_MACRO_BODY */
1399 /** @endcond */
1400
1401 /**
1402 * @brief ANNOTATE_CLEAR_USES support
1403 *
1404 * Clear the special handling of a piece of storage related to induction,
1405 * reduction or observe_uses
1406 */
1407 void ITTAPI __itt_model_clear_uses(void* addr);
1408
1409 /** @cond exclude_from_documentation */
1410 #ifndef INTEL_NO_MACRO_BODY
1411 #ifndef INTEL_NO_ITTNOTIFY_API
1412 ITT_STUBV(ITTAPI, void, model_clear_uses, (void *addr))
1413 #define __itt_model_clear_uses ITTNOTIFY_VOID(model_clear_uses)
1414 #define __itt_model_clear_uses_ptr ITTNOTIFY_NAME(model_clear_uses)
1415 #else /* INTEL_NO_ITTNOTIFY_API */
1416 #define __itt_model_clear_uses(addr)
1417 #define __itt_model_clear_uses_ptr 0
1418 #endif /* INTEL_NO_ITTNOTIFY_API */
1419 #else /* INTEL_NO_MACRO_BODY */
1420 #define __itt_model_clear_uses_ptr 0
1421 #endif /* INTEL_NO_MACRO_BODY */
1422 /** @endcond */
1423
1424 /**
1425 * @brief ANNOTATE_DISABLE_*_PUSH/ANNOTATE_DISABLE_*_POP support
1426 *
1427 * disable_push/disable_pop push and pop disabling based on a parameter.
1428 * Disabling observations stops processing of memory references during
1429 * correctness modeling, and all annotations that occur in the disabled
1430 * region. This allows description of code that is expected to be handled
1431 * specially during conversion to parallelism or that is not recognized
1432 * by tools (e.g. some kinds of synchronization operations.)
1433 * This mechanism causes all annotations in the disabled region, other
1434 * than disable_push and disable_pop, to be ignored. (For example, this
1435 * might validly be used to disable an entire parallel site and the contained
1436 * tasks and locking in it for data collection purposes.)
1437 * The disable for collection is a more expensive operation, but reduces
1438 * collector overhead significantly. This applies to BOTH correctness data
1439 * collection and performance data collection. For example, a site
1440 * containing a task might only enable data collection for the first 10
1441 * iterations. Both performance and correctness data should reflect this,
1442 * and the program should run as close to full speed as possible when
1443 * collection is disabled.
1444 */
1445 void ITTAPI __itt_model_disable_push(__itt_model_disable x);
1446 void ITTAPI __itt_model_disable_pop(void);
1447 void ITTAPI __itt_model_aggregate_task(size_t x);
1448
1449 /** @cond exclude_from_documentation */
1450 #ifndef INTEL_NO_MACRO_BODY
1451 #ifndef INTEL_NO_ITTNOTIFY_API
1452 ITT_STUBV(ITTAPI, void, model_disable_push, (__itt_model_disable x))
1453 ITT_STUBV(ITTAPI, void, model_disable_pop, (void))
1454 ITT_STUBV(ITTAPI, void, model_aggregate_task, (size_t x))
1455 #define __itt_model_disable_push ITTNOTIFY_VOID(model_disable_push)
1456 #define __itt_model_disable_push_ptr ITTNOTIFY_NAME(model_disable_push)
1457 #define __itt_model_disable_pop ITTNOTIFY_VOID(model_disable_pop)
1458 #define __itt_model_disable_pop_ptr ITTNOTIFY_NAME(model_disable_pop)
1459 #define __itt_model_aggregate_task ITTNOTIFY_VOID(model_aggregate_task)
1460 #define __itt_model_aggregate_task_ptr ITTNOTIFY_NAME(model_aggregate_task)
1461 #else /* INTEL_NO_ITTNOTIFY_API */
1462 #define __itt_model_disable_push(x)
1463 #define __itt_model_disable_push_ptr 0
1464 #define __itt_model_disable_pop()
1465 #define __itt_model_disable_pop_ptr 0
1466 #define __itt_model_aggregate_task(x)
1467 #define __itt_model_aggregate_task_ptr 0
1468 #endif /* INTEL_NO_ITTNOTIFY_API */
1469 #else /* INTEL_NO_MACRO_BODY */
1470 #define __itt_model_disable_push_ptr 0
1471 #define __itt_model_disable_pop_ptr 0
1472 #define __itt_model_aggregate_task_ptr 0
1473 #endif /* INTEL_NO_MACRO_BODY */
1474 /** @endcond */
1475 /** @} model group */
1476
1477 /**
1478 * @defgroup heap Heap
1479 * @ingroup public
1480 * Heap group
1481 * @{
1482 */
1483
1484 typedef void* __itt_heap_function;
1485
1486 /**
1487 * @brief Create an identification for heap function
1488 * @return non-zero identifier or NULL
1489 */
1490 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1491 __itt_heap_function ITTAPI __itt_heap_function_createA(const char* name, const char* domain);
1492 __itt_heap_function ITTAPI __itt_heap_function_createW(const wchar_t* name, const wchar_t* domain);
1493 #if defined(UNICODE) || defined(_UNICODE)
1494 # define __itt_heap_function_create __itt_heap_function_createW
1495 # define __itt_heap_function_create_ptr __itt_heap_function_createW_ptr
1496 #else
1497 # define __itt_heap_function_create __itt_heap_function_createA
1498 # define __itt_heap_function_create_ptr __itt_heap_function_createA_ptr
1499 #endif /* UNICODE */
1500 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1501 __itt_heap_function ITTAPI __itt_heap_function_create(const char* name, const char* domain);
1502 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1503
1504 /** @cond exclude_from_documentation */
1505 #ifndef INTEL_NO_MACRO_BODY
1506 #ifndef INTEL_NO_ITTNOTIFY_API
1507 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1508 ITT_STUB(ITTAPI, __itt_heap_function, heap_function_createA, (const char* name, const char* domain))
1509 ITT_STUB(ITTAPI, __itt_heap_function, heap_function_createW, (const wchar_t* name, const wchar_t* domain))
1510 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1511 ITT_STUB(ITTAPI, __itt_heap_function, heap_function_create, (const char* name, const char* domain))
1512 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1513 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1514 #define __itt_heap_function_createA ITTNOTIFY_DATA(heap_function_createA)
1515 #define __itt_heap_function_createA_ptr ITTNOTIFY_NAME(heap_function_createA)
1516 #define __itt_heap_function_createW ITTNOTIFY_DATA(heap_function_createW)
1517 #define __itt_heap_function_createW_ptr ITTNOTIFY_NAME(heap_function_createW)
1518 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1519 #define __itt_heap_function_create ITTNOTIFY_DATA(heap_function_create)
1520 #define __itt_heap_function_create_ptr ITTNOTIFY_NAME(heap_function_create)
1521 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1522 #else /* INTEL_NO_ITTNOTIFY_API */
1523 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1524 #define __itt_heap_function_createA(name, domain) (__itt_heap_function)0
1525 #define __itt_heap_function_createA_ptr 0
1526 #define __itt_heap_function_createW(name, domain) (__itt_heap_function)0
1527 #define __itt_heap_function_createW_ptr 0
1528 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1529 #define __itt_heap_function_create(name, domain) (__itt_heap_function)0
1530 #define __itt_heap_function_create_ptr 0
1531 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1532 #endif /* INTEL_NO_ITTNOTIFY_API */
1533 #else /* INTEL_NO_MACRO_BODY */
1534 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1535 #define __itt_heap_function_createA_ptr 0
1536 #define __itt_heap_function_createW_ptr 0
1537 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1538 #define __itt_heap_function_create_ptr 0
1539 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1540 #endif /* INTEL_NO_MACRO_BODY */
1541 /** @endcond */
1542
1543 /**
1544 * @brief Record an allocation begin occurrence.
1545 */
1546 void ITTAPI __itt_heap_allocate_begin(__itt_heap_function h, size_t size, int initialized);
1547
1548 /** @cond exclude_from_documentation */
1549 #ifndef INTEL_NO_MACRO_BODY
1550 #ifndef INTEL_NO_ITTNOTIFY_API
1551 ITT_STUBV(ITTAPI, void, heap_allocate_begin, (__itt_heap_function h, size_t size, int initialized))
1552 #define __itt_heap_allocate_begin ITTNOTIFY_VOID(heap_allocate_begin)
1553 #define __itt_heap_allocate_begin_ptr ITTNOTIFY_NAME(heap_allocate_begin)
1554 #else /* INTEL_NO_ITTNOTIFY_API */
1555 #define __itt_heap_allocate_begin(h, size, initialized)
1556 #define __itt_heap_allocate_begin_ptr 0
1557 #endif /* INTEL_NO_ITTNOTIFY_API */
1558 #else /* INTEL_NO_MACRO_BODY */
1559 #define __itt_heap_allocate_begin_ptr 0
1560 #endif /* INTEL_NO_MACRO_BODY */
1561 /** @endcond */
1562
1563 /**
1564 * @brief Record an allocation end occurrence.
1565 */
1566 void ITTAPI __itt_heap_allocate_end(__itt_heap_function h, void** addr, size_t size, int initialized);
1567
1568 /** @cond exclude_from_documentation */
1569 #ifndef INTEL_NO_MACRO_BODY
1570 #ifndef INTEL_NO_ITTNOTIFY_API
1571 ITT_STUBV(ITTAPI, void, heap_allocate_end, (__itt_heap_function h, void** addr, size_t size, int initialized))
1572 #define __itt_heap_allocate_end ITTNOTIFY_VOID(heap_allocate_end)
1573 #define __itt_heap_allocate_end_ptr ITTNOTIFY_NAME(heap_allocate_end)
1574 #else /* INTEL_NO_ITTNOTIFY_API */
1575 #define __itt_heap_allocate_end(h, addr, size, initialized)
1576 #define __itt_heap_allocate_end_ptr 0
1577 #endif /* INTEL_NO_ITTNOTIFY_API */
1578 #else /* INTEL_NO_MACRO_BODY */
1579 #define __itt_heap_allocate_end_ptr 0
1580 #endif /* INTEL_NO_MACRO_BODY */
1581 /** @endcond */
1582
1583 /**
1584 * @brief Record a free begin occurrence.
1585 */
1586 void ITTAPI __itt_heap_free_begin(__itt_heap_function h, void* addr);
1587
1588 /** @cond exclude_from_documentation */
1589 #ifndef INTEL_NO_MACRO_BODY
1590 #ifndef INTEL_NO_ITTNOTIFY_API
1591 ITT_STUBV(ITTAPI, void, heap_free_begin, (__itt_heap_function h, void* addr))
1592 #define __itt_heap_free_begin ITTNOTIFY_VOID(heap_free_begin)
1593 #define __itt_heap_free_begin_ptr ITTNOTIFY_NAME(heap_free_begin)
1594 #else /* INTEL_NO_ITTNOTIFY_API */
1595 #define __itt_heap_free_begin(h, addr)
1596 #define __itt_heap_free_begin_ptr 0
1597 #endif /* INTEL_NO_ITTNOTIFY_API */
1598 #else /* INTEL_NO_MACRO_BODY */
1599 #define __itt_heap_free_begin_ptr 0
1600 #endif /* INTEL_NO_MACRO_BODY */
1601 /** @endcond */
1602
1603 /**
1604 * @brief Record a free end occurrence.
1605 */
1606 void ITTAPI __itt_heap_free_end(__itt_heap_function h, void* addr);
1607
1608 /** @cond exclude_from_documentation */
1609 #ifndef INTEL_NO_MACRO_BODY
1610 #ifndef INTEL_NO_ITTNOTIFY_API
1611 ITT_STUBV(ITTAPI, void, heap_free_end, (__itt_heap_function h, void* addr))
1612 #define __itt_heap_free_end ITTNOTIFY_VOID(heap_free_end)
1613 #define __itt_heap_free_end_ptr ITTNOTIFY_NAME(heap_free_end)
1614 #else /* INTEL_NO_ITTNOTIFY_API */
1615 #define __itt_heap_free_end(h, addr)
1616 #define __itt_heap_free_end_ptr 0
1617 #endif /* INTEL_NO_ITTNOTIFY_API */
1618 #else /* INTEL_NO_MACRO_BODY */
1619 #define __itt_heap_free_end_ptr 0
1620 #endif /* INTEL_NO_MACRO_BODY */
1621 /** @endcond */
1622
1623 /**
1624 * @brief Record a reallocation begin occurrence.
1625 */
1626 void ITTAPI __itt_heap_reallocate_begin(__itt_heap_function h, void* addr, size_t new_size, int initialized);
1627
1628 /** @cond exclude_from_documentation */
1629 #ifndef INTEL_NO_MACRO_BODY
1630 #ifndef INTEL_NO_ITTNOTIFY_API
1631 ITT_STUBV(ITTAPI, void, heap_reallocate_begin, (__itt_heap_function h, void* addr, size_t new_size, int initialized))
1632 #define __itt_heap_reallocate_begin ITTNOTIFY_VOID(heap_reallocate_begin)
1633 #define __itt_heap_reallocate_begin_ptr ITTNOTIFY_NAME(heap_reallocate_begin)
1634 #else /* INTEL_NO_ITTNOTIFY_API */
1635 #define __itt_heap_reallocate_begin(h, addr, new_size, initialized)
1636 #define __itt_heap_reallocate_begin_ptr 0
1637 #endif /* INTEL_NO_ITTNOTIFY_API */
1638 #else /* INTEL_NO_MACRO_BODY */
1639 #define __itt_heap_reallocate_begin_ptr 0
1640 #endif /* INTEL_NO_MACRO_BODY */
1641 /** @endcond */
1642
1643 /**
1644 * @brief Record a reallocation end occurrence.
1645 */
1646 void ITTAPI __itt_heap_reallocate_end(__itt_heap_function h, void* addr, void** new_addr, size_t new_size, int initialized);
1647
1648 /** @cond exclude_from_documentation */
1649 #ifndef INTEL_NO_MACRO_BODY
1650 #ifndef INTEL_NO_ITTNOTIFY_API
1651 ITT_STUBV(ITTAPI, void, heap_reallocate_end, (__itt_heap_function h, void* addr, void** new_addr, size_t new_size, int initialized))
1652 #define __itt_heap_reallocate_end ITTNOTIFY_VOID(heap_reallocate_end)
1653 #define __itt_heap_reallocate_end_ptr ITTNOTIFY_NAME(heap_reallocate_end)
1654 #else /* INTEL_NO_ITTNOTIFY_API */
1655 #define __itt_heap_reallocate_end(h, addr, new_addr, new_size, initialized)
1656 #define __itt_heap_reallocate_end_ptr 0
1657 #endif /* INTEL_NO_ITTNOTIFY_API */
1658 #else /* INTEL_NO_MACRO_BODY */
1659 #define __itt_heap_reallocate_end_ptr 0
1660 #endif /* INTEL_NO_MACRO_BODY */
1661 /** @endcond */
1662
1663 /** @brief internal access begin */
1664 void ITTAPI __itt_heap_internal_access_begin(void);
1665
1666 /** @cond exclude_from_documentation */
1667 #ifndef INTEL_NO_MACRO_BODY
1668 #ifndef INTEL_NO_ITTNOTIFY_API
1669 ITT_STUBV(ITTAPI, void, heap_internal_access_begin, (void))
1670 #define __itt_heap_internal_access_begin ITTNOTIFY_VOID(heap_internal_access_begin)
1671 #define __itt_heap_internal_access_begin_ptr ITTNOTIFY_NAME(heap_internal_access_begin)
1672 #else /* INTEL_NO_ITTNOTIFY_API */
1673 #define __itt_heap_internal_access_begin()
1674 #define __itt_heap_internal_access_begin_ptr 0
1675 #endif /* INTEL_NO_ITTNOTIFY_API */
1676 #else /* INTEL_NO_MACRO_BODY */
1677 #define __itt_heap_internal_access_begin_ptr 0
1678 #endif /* INTEL_NO_MACRO_BODY */
1679 /** @endcond */
1680
1681 /** @brief internal access end */
1682 void ITTAPI __itt_heap_internal_access_end(void);
1683
1684 /** @cond exclude_from_documentation */
1685 #ifndef INTEL_NO_MACRO_BODY
1686 #ifndef INTEL_NO_ITTNOTIFY_API
1687 ITT_STUBV(ITTAPI, void, heap_internal_access_end, (void))
1688 #define __itt_heap_internal_access_end ITTNOTIFY_VOID(heap_internal_access_end)
1689 #define __itt_heap_internal_access_end_ptr ITTNOTIFY_NAME(heap_internal_access_end)
1690 #else /* INTEL_NO_ITTNOTIFY_API */
1691 #define __itt_heap_internal_access_end()
1692 #define __itt_heap_internal_access_end_ptr 0
1693 #endif /* INTEL_NO_ITTNOTIFY_API */
1694 #else /* INTEL_NO_MACRO_BODY */
1695 #define __itt_heap_internal_access_end_ptr 0
1696 #endif /* INTEL_NO_MACRO_BODY */
1697 /** @endcond */
1698
1699 /** @brief record memory growth begin */
1700 void ITTAPI __itt_heap_record_memory_growth_begin(void);
1701
1702 /** @cond exclude_from_documentation */
1703 #ifndef INTEL_NO_MACRO_BODY
1704 #ifndef INTEL_NO_ITTNOTIFY_API
1705 ITT_STUBV(ITTAPI, void, heap_record_memory_growth_begin, (void))
1706 #define __itt_heap_record_memory_growth_begin ITTNOTIFY_VOID(heap_record_memory_growth_begin)
1707 #define __itt_heap_record_memory_growth_begin_ptr ITTNOTIFY_NAME(heap_record_memory_growth_begin)
1708 #else /* INTEL_NO_ITTNOTIFY_API */
1709 #define __itt_heap_record_memory_growth_begin()
1710 #define __itt_heap_record_memory_growth_begin_ptr 0
1711 #endif /* INTEL_NO_ITTNOTIFY_API */
1712 #else /* INTEL_NO_MACRO_BODY */
1713 #define __itt_heap_record_memory_growth_begin_ptr 0
1714 #endif /* INTEL_NO_MACRO_BODY */
1715 /** @endcond */
1716
1717 /** @brief record memory growth end */
1718 void ITTAPI __itt_heap_record_memory_growth_end(void);
1719
1720 /** @cond exclude_from_documentation */
1721 #ifndef INTEL_NO_MACRO_BODY
1722 #ifndef INTEL_NO_ITTNOTIFY_API
1723 ITT_STUBV(ITTAPI, void, heap_record_memory_growth_end, (void))
1724 #define __itt_heap_record_memory_growth_end ITTNOTIFY_VOID(heap_record_memory_growth_end)
1725 #define __itt_heap_record_memory_growth_end_ptr ITTNOTIFY_NAME(heap_record_memory_growth_end)
1726 #else /* INTEL_NO_ITTNOTIFY_API */
1727 #define __itt_heap_record_memory_growth_end()
1728 #define __itt_heap_record_memory_growth_end_ptr 0
1729 #endif /* INTEL_NO_ITTNOTIFY_API */
1730 #else /* INTEL_NO_MACRO_BODY */
1731 #define __itt_heap_record_memory_growth_end_ptr 0
1732 #endif /* INTEL_NO_MACRO_BODY */
1733 /** @endcond */
1734
1735 /**
1736 * @brief Specify the type of heap detection/reporting to modify.
1737 */
1738 /**
1739 * @hideinitializer
1740 * @brief Report on memory leaks.
1741 */
1742 #define __itt_heap_leaks 0x00000001
1743
1744 /**
1745 * @hideinitializer
1746 * @brief Report on memory growth.
1747 */
1748 #define __itt_heap_growth 0x00000002
1749
1750
1751 /** @brief heap reset detection */
1752 void ITTAPI __itt_heap_reset_detection(unsigned int reset_mask);
1753
1754 /** @cond exclude_from_documentation */
1755 #ifndef INTEL_NO_MACRO_BODY
1756 #ifndef INTEL_NO_ITTNOTIFY_API
1757 ITT_STUBV(ITTAPI, void, heap_reset_detection, (unsigned int reset_mask))
1758 #define __itt_heap_reset_detection ITTNOTIFY_VOID(heap_reset_detection)
1759 #define __itt_heap_reset_detection_ptr ITTNOTIFY_NAME(heap_reset_detection)
1760 #else /* INTEL_NO_ITTNOTIFY_API */
1761 #define __itt_heap_reset_detection()
1762 #define __itt_heap_reset_detection_ptr 0
1763 #endif /* INTEL_NO_ITTNOTIFY_API */
1764 #else /* INTEL_NO_MACRO_BODY */
1765 #define __itt_heap_reset_detection_ptr 0
1766 #endif /* INTEL_NO_MACRO_BODY */
1767 /** @endcond */
1768
1769 /** @brief report */
1770 void ITTAPI __itt_heap_record(unsigned int record_mask);
1771
1772 /** @cond exclude_from_documentation */
1773 #ifndef INTEL_NO_MACRO_BODY
1774 #ifndef INTEL_NO_ITTNOTIFY_API
1775 ITT_STUBV(ITTAPI, void, heap_record, (unsigned int record_mask))
1776 #define __itt_heap_record ITTNOTIFY_VOID(heap_record)
1777 #define __itt_heap_record_ptr ITTNOTIFY_NAME(heap_record)
1778 #else /* INTEL_NO_ITTNOTIFY_API */
1779 #define __itt_heap_record()
1780 #define __itt_heap_record_ptr 0
1781 #endif /* INTEL_NO_ITTNOTIFY_API */
1782 #else /* INTEL_NO_MACRO_BODY */
1783 #define __itt_heap_record_ptr 0
1784 #endif /* INTEL_NO_MACRO_BODY */
1785 /** @endcond */
1786
1787 /** @} heap group */
1788 /** @endcond */
1789 /* ========================================================================== */
1790
1791 /**
1792 * @defgroup domains Domains
1793 * @ingroup public
1794 * Domains group
1795 * @{
1796 */
1797
1798 /** @cond exclude_from_documentation */
1799 #pragma pack(push, 8)
1800
1801 typedef struct ___itt_domain
1802 {
1803 volatile int flags; /*!< Zero if disabled, non-zero if enabled. The meaning of different non-zero values is reserved to the runtime */
1804 const char* nameA; /*!< Copy of original name in ASCII. */
1805 #if defined(UNICODE) || defined(_UNICODE)
1806 const wchar_t* nameW; /*!< Copy of original name in UNICODE. */
1807 #else /* UNICODE || _UNICODE */
1808 void* nameW;
1809 #endif /* UNICODE || _UNICODE */
1810 int extra1; /*!< Reserved to the runtime */
1811 void* extra2; /*!< Reserved to the runtime */
1812 struct ___itt_domain* next;
1813 } __itt_domain;
1814
1815 #pragma pack(pop)
1816 /** @endcond */
1817
1818 /**
1819 * @ingroup domains
1820 * @brief Create a domain.
1821 * Create domain using some domain name: the URI naming style is recommended.
1822 * Because the set of domains is expected to be static over the application's
1823 * execution time, there is no mechanism to destroy a domain.
1824 * Any domain can be accessed by any thread in the process, regardless of
1825 * which thread created the domain. This call is thread-safe.
1826 * @param[in] name name of domain
1827 */
1828 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1829 __itt_domain* ITTAPI __itt_domain_createA(const char *name);
1830 __itt_domain* ITTAPI __itt_domain_createW(const wchar_t *name);
1831 #if defined(UNICODE) || defined(_UNICODE)
1832 # define __itt_domain_create __itt_domain_createW
1833 # define __itt_domain_create_ptr __itt_domain_createW_ptr
1834 #else /* UNICODE */
1835 # define __itt_domain_create __itt_domain_createA
1836 # define __itt_domain_create_ptr __itt_domain_createA_ptr
1837 #endif /* UNICODE */
1838 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1839 __itt_domain* ITTAPI __itt_domain_create(const char *name);
1840 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1841
1842 /** @cond exclude_from_documentation */
1843 #ifndef INTEL_NO_MACRO_BODY
1844 #ifndef INTEL_NO_ITTNOTIFY_API
1845 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1846 ITT_STUB(ITTAPI, __itt_domain*, domain_createA, (const char *name))
1847 ITT_STUB(ITTAPI, __itt_domain*, domain_createW, (const wchar_t *name))
1848 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1849 ITT_STUB(ITTAPI, __itt_domain*, domain_create, (const char *name))
1850 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1851 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1852 #define __itt_domain_createA ITTNOTIFY_DATA(domain_createA)
1853 #define __itt_domain_createA_ptr ITTNOTIFY_NAME(domain_createA)
1854 #define __itt_domain_createW ITTNOTIFY_DATA(domain_createW)
1855 #define __itt_domain_createW_ptr ITTNOTIFY_NAME(domain_createW)
1856 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1857 #define __itt_domain_create ITTNOTIFY_DATA(domain_create)
1858 #define __itt_domain_create_ptr ITTNOTIFY_NAME(domain_create)
1859 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1860 #else /* INTEL_NO_ITTNOTIFY_API */
1861 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1862 #define __itt_domain_createA(name) (__itt_domain*)0
1863 #define __itt_domain_createA_ptr 0
1864 #define __itt_domain_createW(name) (__itt_domain*)0
1865 #define __itt_domain_createW_ptr 0
1866 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1867 #define __itt_domain_create(name) (__itt_domain*)0
1868 #define __itt_domain_create_ptr 0
1869 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1870 #endif /* INTEL_NO_ITTNOTIFY_API */
1871 #else /* INTEL_NO_MACRO_BODY */
1872 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1873 #define __itt_domain_createA_ptr 0
1874 #define __itt_domain_createW_ptr 0
1875 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1876 #define __itt_domain_create_ptr 0
1877 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1878 #endif /* INTEL_NO_MACRO_BODY */
1879 /** @endcond */
1880 /** @} domains group */
1881
1882 /**
1883 * @defgroup ids IDs
1884 * @ingroup public
1885 * IDs group
1886 * @{
1887 */
1888
1889 /** @cond exclude_from_documentation */
1890 #pragma pack(push, 8)
1891
1892 typedef struct ___itt_id
1893 {
1894 unsigned long long d1, d2, d3;
1895 } __itt_id;
1896
1897 #pragma pack(pop)
1898 /** @endcond */
1899
1900 static const __itt_id __itt_null = { 0, 0, 0 };
1901
1902 /**
1903 * @ingroup ids
1904 * @brief A convenience function is provided to create an ID without domain control.
1905 * @brief This is a convenience function to initialize an __itt_id structure. This function
1906 * does not affect the collector runtime in any way. After you make the ID with this
1907 * function, you still must create it with the __itt_id_create function before using the ID
1908 * to identify a named entity.
1909 * @param[in] addr The address of object; high QWORD of the ID value.
1910 * @param[in] extra The extra data to unique identify object; low QWORD of the ID value.
1911 */
1912
1913 ITT_INLINE __itt_id ITTAPI __itt_id_make(void* addr, unsigned long long extra) ITT_INLINE_ATTRIBUTE;
__itt_id_make(void * addr,unsigned long long extra)1914 ITT_INLINE __itt_id ITTAPI __itt_id_make(void* addr, unsigned long long extra)
1915 {
1916 __itt_id id = __itt_null;
1917 id.d1 = (unsigned long long)((uintptr_t)addr);
1918 id.d2 = (unsigned long long)extra;
1919 id.d3 = (unsigned long long)0; /* Reserved. Must be zero */
1920 return id;
1921 }
1922
1923 /**
1924 * @ingroup ids
1925 * @brief Create an instance of identifier.
1926 * This establishes the beginning of the lifetime of an instance of
1927 * the given ID in the trace. Once this lifetime starts, the ID
1928 * can be used to tag named entity instances in calls such as
1929 * __itt_task_begin, and to specify relationships among
1930 * identified named entity instances, using the \ref relations APIs.
1931 * Instance IDs are not domain specific!
1932 * @param[in] domain The domain controlling the execution of this call.
1933 * @param[in] id The ID to create.
1934 */
1935 void ITTAPI __itt_id_create(const __itt_domain *domain, __itt_id id);
1936
1937 /** @cond exclude_from_documentation */
1938 #ifndef INTEL_NO_MACRO_BODY
1939 #ifndef INTEL_NO_ITTNOTIFY_API
1940 ITT_STUBV(ITTAPI, void, id_create, (const __itt_domain *domain, __itt_id id))
1941 #define __itt_id_create(d,x) ITTNOTIFY_VOID_D1(id_create,d,x)
1942 #define __itt_id_create_ptr ITTNOTIFY_NAME(id_create)
1943 #else /* INTEL_NO_ITTNOTIFY_API */
1944 #define __itt_id_create(domain,id)
1945 #define __itt_id_create_ptr 0
1946 #endif /* INTEL_NO_ITTNOTIFY_API */
1947 #else /* INTEL_NO_MACRO_BODY */
1948 #define __itt_id_create_ptr 0
1949 #endif /* INTEL_NO_MACRO_BODY */
1950 /** @endcond */
1951
1952 /**
1953 * @ingroup ids
1954 * @brief Destroy an instance of identifier.
1955 * This ends the lifetime of the current instance of the given ID value in the trace.
1956 * Any relationships that are established after this lifetime ends are invalid.
1957 * This call must be performed before the given ID value can be reused for a different
1958 * named entity instance.
1959 * @param[in] domain The domain controlling the execution of this call.
1960 * @param[in] id The ID to destroy.
1961 */
1962 void ITTAPI __itt_id_destroy(const __itt_domain *domain, __itt_id id);
1963
1964 /** @cond exclude_from_documentation */
1965 #ifndef INTEL_NO_MACRO_BODY
1966 #ifndef INTEL_NO_ITTNOTIFY_API
1967 ITT_STUBV(ITTAPI, void, id_destroy, (const __itt_domain *domain, __itt_id id))
1968 #define __itt_id_destroy(d,x) ITTNOTIFY_VOID_D1(id_destroy,d,x)
1969 #define __itt_id_destroy_ptr ITTNOTIFY_NAME(id_destroy)
1970 #else /* INTEL_NO_ITTNOTIFY_API */
1971 #define __itt_id_destroy(domain,id)
1972 #define __itt_id_destroy_ptr 0
1973 #endif /* INTEL_NO_ITTNOTIFY_API */
1974 #else /* INTEL_NO_MACRO_BODY */
1975 #define __itt_id_destroy_ptr 0
1976 #endif /* INTEL_NO_MACRO_BODY */
1977 /** @endcond */
1978 /** @} ids group */
1979
1980 /**
1981 * @defgroup handless String Handles
1982 * @ingroup public
1983 * String Handles group
1984 * @{
1985 */
1986
1987 /** @cond exclude_from_documentation */
1988 #pragma pack(push, 8)
1989
1990 typedef struct ___itt_string_handle
1991 {
1992 const char* strA; /*!< Copy of original string in ASCII. */
1993 #if defined(UNICODE) || defined(_UNICODE)
1994 const wchar_t* strW; /*!< Copy of original string in UNICODE. */
1995 #else /* UNICODE || _UNICODE */
1996 void* strW;
1997 #endif /* UNICODE || _UNICODE */
1998 int extra1; /*!< Reserved. Must be zero */
1999 void* extra2; /*!< Reserved. Must be zero */
2000 struct ___itt_string_handle* next;
2001 } __itt_string_handle;
2002
2003 #pragma pack(pop)
2004 /** @endcond */
2005
2006 /**
2007 * @ingroup handles
2008 * @brief Create a string handle.
2009 * Create and return handle value that can be associated with a string.
2010 * Consecutive calls to __itt_string_handle_create with the same name
2011 * return the same value. Because the set of string handles is expected to remain
2012 * static during the application's execution time, there is no mechanism to destroy a string handle.
2013 * Any string handle can be accessed by any thread in the process, regardless of which thread created
2014 * the string handle. This call is thread-safe.
2015 * @param[in] name The input string
2016 */
2017 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2018 __itt_string_handle* ITTAPI __itt_string_handle_createA(const char *name);
2019 __itt_string_handle* ITTAPI __itt_string_handle_createW(const wchar_t *name);
2020 #if defined(UNICODE) || defined(_UNICODE)
2021 # define __itt_string_handle_create __itt_string_handle_createW
2022 # define __itt_string_handle_create_ptr __itt_string_handle_createW_ptr
2023 #else /* UNICODE */
2024 # define __itt_string_handle_create __itt_string_handle_createA
2025 # define __itt_string_handle_create_ptr __itt_string_handle_createA_ptr
2026 #endif /* UNICODE */
2027 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2028 __itt_string_handle* ITTAPI __itt_string_handle_create(const char *name);
2029 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2030
2031 /** @cond exclude_from_documentation */
2032 #ifndef INTEL_NO_MACRO_BODY
2033 #ifndef INTEL_NO_ITTNOTIFY_API
2034 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2035 ITT_STUB(ITTAPI, __itt_string_handle*, string_handle_createA, (const char *name))
2036 ITT_STUB(ITTAPI, __itt_string_handle*, string_handle_createW, (const wchar_t *name))
2037 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2038 ITT_STUB(ITTAPI, __itt_string_handle*, string_handle_create, (const char *name))
2039 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2040 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2041 #define __itt_string_handle_createA ITTNOTIFY_DATA(string_handle_createA)
2042 #define __itt_string_handle_createA_ptr ITTNOTIFY_NAME(string_handle_createA)
2043 #define __itt_string_handle_createW ITTNOTIFY_DATA(string_handle_createW)
2044 #define __itt_string_handle_createW_ptr ITTNOTIFY_NAME(string_handle_createW)
2045 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2046 #define __itt_string_handle_create ITTNOTIFY_DATA(string_handle_create)
2047 #define __itt_string_handle_create_ptr ITTNOTIFY_NAME(string_handle_create)
2048 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2049 #else /* INTEL_NO_ITTNOTIFY_API */
2050 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2051 #define __itt_string_handle_createA(name) (__itt_string_handle*)0
2052 #define __itt_string_handle_createA_ptr 0
2053 #define __itt_string_handle_createW(name) (__itt_string_handle*)0
2054 #define __itt_string_handle_createW_ptr 0
2055 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2056 #define __itt_string_handle_create(name) (__itt_string_handle*)0
2057 #define __itt_string_handle_create_ptr 0
2058 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2059 #endif /* INTEL_NO_ITTNOTIFY_API */
2060 #else /* INTEL_NO_MACRO_BODY */
2061 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2062 #define __itt_string_handle_createA_ptr 0
2063 #define __itt_string_handle_createW_ptr 0
2064 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2065 #define __itt_string_handle_create_ptr 0
2066 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2067 #endif /* INTEL_NO_MACRO_BODY */
2068 /** @endcond */
2069 /** @} handles group */
2070
2071 /** @cond exclude_from_documentation */
2072 typedef unsigned long long __itt_timestamp;
2073 /** @endcond */
2074
2075 #define __itt_timestamp_none ((__itt_timestamp)-1LL)
2076
2077 /** @cond exclude_from_gpa_documentation */
2078
2079 /**
2080 * @ingroup timestamps
2081 * @brief Return timestamp corresponding to the current moment.
2082 * This returns the timestamp in the format that is the most relevant for the current
2083 * host or platform (RDTSC, QPC, and others). You can use the "<" operator to
2084 * compare __itt_timestamp values.
2085 */
2086 __itt_timestamp ITTAPI __itt_get_timestamp(void);
2087
2088 /** @cond exclude_from_documentation */
2089 #ifndef INTEL_NO_MACRO_BODY
2090 #ifndef INTEL_NO_ITTNOTIFY_API
2091 ITT_STUB(ITTAPI, __itt_timestamp, get_timestamp, (void))
2092 #define __itt_get_timestamp ITTNOTIFY_DATA(get_timestamp)
2093 #define __itt_get_timestamp_ptr ITTNOTIFY_NAME(get_timestamp)
2094 #else /* INTEL_NO_ITTNOTIFY_API */
2095 #define __itt_get_timestamp()
2096 #define __itt_get_timestamp_ptr 0
2097 #endif /* INTEL_NO_ITTNOTIFY_API */
2098 #else /* INTEL_NO_MACRO_BODY */
2099 #define __itt_get_timestamp_ptr 0
2100 #endif /* INTEL_NO_MACRO_BODY */
2101 /** @endcond */
2102 /** @} timestamps */
2103 /** @endcond */
2104
2105 /** @cond exclude_from_gpa_documentation */
2106
2107 /**
2108 * @defgroup regions Regions
2109 * @ingroup public
2110 * Regions group
2111 * @{
2112 */
2113 /**
2114 * @ingroup regions
2115 * @brief Begin of region instance.
2116 * Successive calls to __itt_region_begin with the same ID are ignored
2117 * until a call to __itt_region_end with the same ID
2118 * @param[in] domain The domain for this region instance
2119 * @param[in] id The instance ID for this region instance. Must not be __itt_null
2120 * @param[in] parentid The instance ID for the parent of this region instance, or __itt_null
2121 * @param[in] name The name of this region
2122 */
2123 void ITTAPI __itt_region_begin(const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name);
2124
2125 /**
2126 * @ingroup regions
2127 * @brief End of region instance.
2128 * The first call to __itt_region_end with a given ID ends the
2129 * region. Successive calls with the same ID are ignored, as are
2130 * calls that do not have a matching __itt_region_begin call.
2131 * @param[in] domain The domain for this region instance
2132 * @param[in] id The instance ID for this region instance
2133 */
2134 void ITTAPI __itt_region_end(const __itt_domain *domain, __itt_id id);
2135
2136 /** @cond exclude_from_documentation */
2137 #ifndef INTEL_NO_MACRO_BODY
2138 #ifndef INTEL_NO_ITTNOTIFY_API
2139 ITT_STUBV(ITTAPI, void, region_begin, (const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2140 ITT_STUBV(ITTAPI, void, region_end, (const __itt_domain *domain, __itt_id id))
2141 #define __itt_region_begin(d,x,y,z) ITTNOTIFY_VOID_D3(region_begin,d,x,y,z)
2142 #define __itt_region_begin_ptr ITTNOTIFY_NAME(region_begin)
2143 #define __itt_region_end(d,x) ITTNOTIFY_VOID_D1(region_end,d,x)
2144 #define __itt_region_end_ptr ITTNOTIFY_NAME(region_end)
2145 #else /* INTEL_NO_ITTNOTIFY_API */
2146 #define __itt_region_begin(d,x,y,z)
2147 #define __itt_region_begin_ptr 0
2148 #define __itt_region_end(d,x)
2149 #define __itt_region_end_ptr 0
2150 #endif /* INTEL_NO_ITTNOTIFY_API */
2151 #else /* INTEL_NO_MACRO_BODY */
2152 #define __itt_region_begin_ptr 0
2153 #define __itt_region_end_ptr 0
2154 #endif /* INTEL_NO_MACRO_BODY */
2155 /** @endcond */
2156 /** @} regions group */
2157
2158 /**
2159 * @defgroup frames Frames
2160 * @ingroup public
2161 * Frames are similar to regions, but are intended to be easier to use and to implement.
2162 * In particular:
2163 * - Frames always represent periods of elapsed time
2164 * - By default, frames have no nesting relationships
2165 * @{
2166 */
2167
2168 /**
2169 * @ingroup frames
2170 * @brief Begin a frame instance.
2171 * Successive calls to __itt_frame_begin with the
2172 * same ID are ignored until a call to __itt_frame_end with the same ID.
2173 * @param[in] domain The domain for this frame instance
2174 * @param[in] id The instance ID for this frame instance or NULL
2175 */
2176 void ITTAPI __itt_frame_begin_v3(const __itt_domain *domain, __itt_id *id);
2177
2178 /**
2179 * @ingroup frames
2180 * @brief End a frame instance.
2181 * The first call to __itt_frame_end with a given ID
2182 * ends the frame. Successive calls with the same ID are ignored, as are
2183 * calls that do not have a matching __itt_frame_begin call.
2184 * @param[in] domain The domain for this frame instance
2185 * @param[in] id The instance ID for this frame instance or NULL for current
2186 */
2187 void ITTAPI __itt_frame_end_v3(const __itt_domain *domain, __itt_id *id);
2188
2189 /**
2190 * @ingroup frames
2191 * @brief Submits a frame instance.
2192 * Successive calls to __itt_frame_begin or __itt_frame_submit with the
2193 * same ID are ignored until a call to __itt_frame_end or __itt_frame_submit
2194 * with the same ID.
2195 * Passing special __itt_timestamp_none value as "end" argument means
2196 * take the current timestamp as the end timestamp.
2197 * @param[in] domain The domain for this frame instance
2198 * @param[in] id The instance ID for this frame instance or NULL
2199 * @param[in] begin Timestamp of the beginning of the frame
2200 * @param[in] end Timestamp of the end of the frame
2201 */
2202 void ITTAPI __itt_frame_submit_v3(const __itt_domain *domain, __itt_id *id,
2203 __itt_timestamp begin, __itt_timestamp end);
2204
2205 /** @cond exclude_from_documentation */
2206 #ifndef INTEL_NO_MACRO_BODY
2207 #ifndef INTEL_NO_ITTNOTIFY_API
2208 ITT_STUBV(ITTAPI, void, frame_begin_v3, (const __itt_domain *domain, __itt_id *id))
2209 ITT_STUBV(ITTAPI, void, frame_end_v3, (const __itt_domain *domain, __itt_id *id))
2210 ITT_STUBV(ITTAPI, void, frame_submit_v3, (const __itt_domain *domain, __itt_id *id, __itt_timestamp begin, __itt_timestamp end))
2211 #define __itt_frame_begin_v3(d,x) ITTNOTIFY_VOID_D1(frame_begin_v3,d,x)
2212 #define __itt_frame_begin_v3_ptr ITTNOTIFY_NAME(frame_begin_v3)
2213 #define __itt_frame_end_v3(d,x) ITTNOTIFY_VOID_D1(frame_end_v3,d,x)
2214 #define __itt_frame_end_v3_ptr ITTNOTIFY_NAME(frame_end_v3)
2215 #define __itt_frame_submit_v3(d,x,b,e) ITTNOTIFY_VOID_D3(frame_submit_v3,d,x,b,e)
2216 #define __itt_frame_submit_v3_ptr ITTNOTIFY_NAME(frame_submit_v3)
2217 #else /* INTEL_NO_ITTNOTIFY_API */
2218 #define __itt_frame_begin_v3(domain,id)
2219 #define __itt_frame_begin_v3_ptr 0
2220 #define __itt_frame_end_v3(domain,id)
2221 #define __itt_frame_end_v3_ptr 0
2222 #define __itt_frame_submit_v3(domain,id,begin,end)
2223 #define __itt_frame_submit_v3_ptr 0
2224 #endif /* INTEL_NO_ITTNOTIFY_API */
2225 #else /* INTEL_NO_MACRO_BODY */
2226 #define __itt_frame_begin_v3_ptr 0
2227 #define __itt_frame_end_v3_ptr 0
2228 #define __itt_frame_submit_v3_ptr 0
2229 #endif /* INTEL_NO_MACRO_BODY */
2230 /** @endcond */
2231 /** @} frames group */
2232 /** @endcond */
2233
2234 /**
2235 * @defgroup taskgroup Task Group
2236 * @ingroup public
2237 * Task Group
2238 * @{
2239 */
2240 /**
2241 * @ingroup task_groups
2242 * @brief Denotes a task_group instance.
2243 * Successive calls to __itt_task_group with the same ID are ignored.
2244 * @param[in] domain The domain for this task_group instance
2245 * @param[in] id The instance ID for this task_group instance. Must not be __itt_null.
2246 * @param[in] parentid The instance ID for the parent of this task_group instance, or __itt_null.
2247 * @param[in] name The name of this task_group
2248 */
2249 void ITTAPI __itt_task_group(const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name);
2250
2251 /** @cond exclude_from_documentation */
2252 #ifndef INTEL_NO_MACRO_BODY
2253 #ifndef INTEL_NO_ITTNOTIFY_API
2254 ITT_STUBV(ITTAPI, void, task_group, (const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2255 #define __itt_task_group(d,x,y,z) ITTNOTIFY_VOID_D3(task_group,d,x,y,z)
2256 #define __itt_task_group_ptr ITTNOTIFY_NAME(task_group)
2257 #else /* INTEL_NO_ITTNOTIFY_API */
2258 #define __itt_task_group(d,x,y,z)
2259 #define __itt_task_group_ptr 0
2260 #endif /* INTEL_NO_ITTNOTIFY_API */
2261 #else /* INTEL_NO_MACRO_BODY */
2262 #define __itt_task_group_ptr 0
2263 #endif /* INTEL_NO_MACRO_BODY */
2264 /** @endcond */
2265 /** @} taskgroup group */
2266
2267 /**
2268 * @defgroup tasks Tasks
2269 * @ingroup public
2270 * A task instance represents a piece of work performed by a particular
2271 * thread for a period of time. A call to __itt_task_begin creates a
2272 * task instance. This becomes the current instance for that task on that
2273 * thread. A following call to __itt_task_end on the same thread ends the
2274 * instance. There may be multiple simultaneous instances of tasks with the
2275 * same name on different threads. If an ID is specified, the task instance
2276 * receives that ID. Nested tasks are allowed.
2277 *
2278 * Note: The task is defined by the bracketing of __itt_task_begin and
2279 * __itt_task_end on the same thread. If some scheduling mechanism causes
2280 * task switching (the thread executes a different user task) or task
2281 * switching (the user task switches to a different thread) then this breaks
2282 * the notion of current instance. Additional API calls are required to
2283 * deal with that possibility.
2284 * @{
2285 */
2286
2287 /**
2288 * @ingroup tasks
2289 * @brief Begin a task instance.
2290 * @param[in] domain The domain for this task
2291 * @param[in] taskid The instance ID for this task instance, or __itt_null
2292 * @param[in] parentid The parent instance to which this task instance belongs, or __itt_null
2293 * @param[in] name The name of this task
2294 */
2295 void ITTAPI __itt_task_begin(const __itt_domain *domain, __itt_id taskid, __itt_id parentid, __itt_string_handle *name);
2296
2297 /**
2298 * @ingroup tasks
2299 * @brief Begin a task instance.
2300 * @param[in] domain The domain for this task
2301 * @param[in] taskid The identifier for this task instance (may be 0)
2302 * @param[in] parentid The parent of this task (may be 0)
2303 * @param[in] fn The pointer to the function you are tracing
2304 */
2305 void ITTAPI __itt_task_begin_fn(const __itt_domain *domain, __itt_id taskid, __itt_id parentid, void* fn);
2306
2307 /**
2308 * @ingroup tasks
2309 * @brief End the current task instance.
2310 * @param[in] domain The domain for this task
2311 */
2312 void ITTAPI __itt_task_end(const __itt_domain *domain);
2313
2314 /**
2315 * @ingroup tasks
2316 * @brief Begin an overlapped task instance.
2317 * @param[in] domain The domain for this task.
2318 * @param[in] taskid The identifier for this task instance, *cannot* be __itt_null.
2319 * @param[in] parentid The parent of this task, or __itt_null.
2320 * @param[in] name The name of this task.
2321 */
2322 void ITTAPI __itt_task_begin_overlapped(const __itt_domain* domain, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
2323
2324 /**
2325 * @ingroup tasks
2326 * @brief End an overlapped task instance.
2327 * @param[in] domain The domain for this task
2328 * @param[in] taskid Explicit ID of finished task
2329 */
2330 void ITTAPI __itt_task_end_overlapped(const __itt_domain *domain, __itt_id taskid);
2331
2332 /** @cond exclude_from_documentation */
2333 #ifndef INTEL_NO_MACRO_BODY
2334 #ifndef INTEL_NO_ITTNOTIFY_API
2335 ITT_STUBV(ITTAPI, void, task_begin, (const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2336 ITT_STUBV(ITTAPI, void, task_begin_fn, (const __itt_domain *domain, __itt_id id, __itt_id parentid, void* fn))
2337 ITT_STUBV(ITTAPI, void, task_end, (const __itt_domain *domain))
2338 ITT_STUBV(ITTAPI, void, task_begin_overlapped, (const __itt_domain *domain, __itt_id taskid, __itt_id parentid, __itt_string_handle *name))
2339 ITT_STUBV(ITTAPI, void, task_end_overlapped, (const __itt_domain *domain, __itt_id taskid))
2340 #define __itt_task_begin(d,x,y,z) ITTNOTIFY_VOID_D3(task_begin,d,x,y,z)
2341 #define __itt_task_begin_ptr ITTNOTIFY_NAME(task_begin)
2342 #define __itt_task_begin_fn(d,x,y,z) ITTNOTIFY_VOID_D3(task_begin_fn,d,x,y,z)
2343 #define __itt_task_begin_fn_ptr ITTNOTIFY_NAME(task_begin_fn)
2344 #define __itt_task_end(d) ITTNOTIFY_VOID_D0(task_end,d)
2345 #define __itt_task_end_ptr ITTNOTIFY_NAME(task_end)
2346 #define __itt_task_begin_overlapped(d,x,y,z) ITTNOTIFY_VOID_D3(task_begin_overlapped,d,x,y,z)
2347 #define __itt_task_begin_overlapped_ptr ITTNOTIFY_NAME(task_begin_overlapped)
2348 #define __itt_task_end_overlapped(d,x) ITTNOTIFY_VOID_D1(task_end_overlapped,d,x)
2349 #define __itt_task_end_overlapped_ptr ITTNOTIFY_NAME(task_end_overlapped)
2350 #else /* INTEL_NO_ITTNOTIFY_API */
2351 #define __itt_task_begin(domain,id,parentid,name)
2352 #define __itt_task_begin_ptr 0
2353 #define __itt_task_begin_fn(domain,id,parentid,fn)
2354 #define __itt_task_begin_fn_ptr 0
2355 #define __itt_task_end(domain)
2356 #define __itt_task_end_ptr 0
2357 #define __itt_task_begin_overlapped(domain,taskid,parentid,name)
2358 #define __itt_task_begin_overlapped_ptr 0
2359 #define __itt_task_end_overlapped(domain,taskid)
2360 #define __itt_task_end_overlapped_ptr 0
2361 #endif /* INTEL_NO_ITTNOTIFY_API */
2362 #else /* INTEL_NO_MACRO_BODY */
2363 #define __itt_task_begin_ptr 0
2364 #define __itt_task_begin_fn_ptr 0
2365 #define __itt_task_end_ptr 0
2366 #define __itt_task_begin_overlapped_ptr 0
2367 #define __itt_task_end_overlapped_ptr 0
2368 #endif /* INTEL_NO_MACRO_BODY */
2369 /** @endcond */
2370 /** @} tasks group */
2371
2372
2373 /**
2374 * @defgroup markers Markers
2375 * Markers represent a single discrete event in time. Markers have a scope,
2376 * described by an enumerated type __itt_scope. Markers are created by
2377 * the API call __itt_marker. A marker instance can be given an ID for use in
2378 * adding metadata.
2379 * @{
2380 */
2381
2382 /**
2383 * @brief Describes the scope of an event object in the trace.
2384 */
2385 typedef enum
2386 {
2387 __itt_scope_unknown = 0,
2388 __itt_scope_global,
2389 __itt_scope_track_group,
2390 __itt_scope_track,
2391 __itt_scope_task,
2392 __itt_scope_marker
2393 } __itt_scope;
2394
2395 /** @cond exclude_from_documentation */
2396 #define __itt_marker_scope_unknown __itt_scope_unknown
2397 #define __itt_marker_scope_global __itt_scope_global
2398 #define __itt_marker_scope_process __itt_scope_track_group
2399 #define __itt_marker_scope_thread __itt_scope_track
2400 #define __itt_marker_scope_task __itt_scope_task
2401 /** @endcond */
2402
2403 /**
2404 * @ingroup markers
2405 * @brief Create a marker instance
2406 * @param[in] domain The domain for this marker
2407 * @param[in] id The instance ID for this marker or __itt_null
2408 * @param[in] name The name for this marker
2409 * @param[in] scope The scope for this marker
2410 */
2411 void ITTAPI __itt_marker(const __itt_domain *domain, __itt_id id, __itt_string_handle *name, __itt_scope scope);
2412
2413 /** @cond exclude_from_documentation */
2414 #ifndef INTEL_NO_MACRO_BODY
2415 #ifndef INTEL_NO_ITTNOTIFY_API
2416 ITT_STUBV(ITTAPI, void, marker, (const __itt_domain *domain, __itt_id id, __itt_string_handle *name, __itt_scope scope))
2417 #define __itt_marker(d,x,y,z) ITTNOTIFY_VOID_D3(marker,d,x,y,z)
2418 #define __itt_marker_ptr ITTNOTIFY_NAME(marker)
2419 #else /* INTEL_NO_ITTNOTIFY_API */
2420 #define __itt_marker(domain,id,name,scope)
2421 #define __itt_marker_ptr 0
2422 #endif /* INTEL_NO_ITTNOTIFY_API */
2423 #else /* INTEL_NO_MACRO_BODY */
2424 #define __itt_marker_ptr 0
2425 #endif /* INTEL_NO_MACRO_BODY */
2426 /** @endcond */
2427 /** @} markers group */
2428
2429 /**
2430 * @defgroup metadata Metadata
2431 * The metadata API is used to attach extra information to named
2432 * entities. Metadata can be attached to an identified named entity by ID,
2433 * or to the current entity (which is always a task).
2434 *
2435 * Conceptually metadata has a type (what kind of metadata), a key (the
2436 * name of the metadata), and a value (the actual data). The encoding of
2437 * the value depends on the type of the metadata.
2438 *
2439 * The type of metadata is specified by an enumerated type __itt_metdata_type.
2440 * @{
2441 */
2442
2443 /**
2444 * @ingroup parameters
2445 * @brief describes the type of metadata
2446 */
2447 typedef enum {
2448 __itt_metadata_unknown = 0,
2449 __itt_metadata_u64, /**< Unsigned 64-bit integer */
2450 __itt_metadata_s64, /**< Signed 64-bit integer */
2451 __itt_metadata_u32, /**< Unsigned 32-bit integer */
2452 __itt_metadata_s32, /**< Signed 32-bit integer */
2453 __itt_metadata_u16, /**< Unsigned 16-bit integer */
2454 __itt_metadata_s16, /**< Signed 16-bit integer */
2455 __itt_metadata_float, /**< Signed 32-bit floating-point */
2456 __itt_metadata_double /**< SIgned 64-bit floating-point */
2457 } __itt_metadata_type;
2458
2459 /**
2460 * @ingroup parameters
2461 * @brief Add metadata to an instance of a named entity.
2462 * @param[in] domain The domain controlling the call
2463 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2464 * @param[in] key The name of the metadata
2465 * @param[in] type The type of the metadata
2466 * @param[in] count The number of elements of the given type. If count == 0, no metadata will be added.
2467 * @param[in] data The metadata itself
2468 */
2469 void ITTAPI __itt_metadata_add(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data);
2470
2471 /** @cond exclude_from_documentation */
2472 #ifndef INTEL_NO_MACRO_BODY
2473 #ifndef INTEL_NO_ITTNOTIFY_API
2474 ITT_STUBV(ITTAPI, void, metadata_add, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data))
2475 #define __itt_metadata_add(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(metadata_add,d,x,y,z,a,b)
2476 #define __itt_metadata_add_ptr ITTNOTIFY_NAME(metadata_add)
2477 #else /* INTEL_NO_ITTNOTIFY_API */
2478 #define __itt_metadata_add(d,x,y,z,a,b)
2479 #define __itt_metadata_add_ptr 0
2480 #endif /* INTEL_NO_ITTNOTIFY_API */
2481 #else /* INTEL_NO_MACRO_BODY */
2482 #define __itt_metadata_add_ptr 0
2483 #endif /* INTEL_NO_MACRO_BODY */
2484 /** @endcond */
2485
2486 /**
2487 * @ingroup parameters
2488 * @brief Add string metadata to an instance of a named entity.
2489 * @param[in] domain The domain controlling the call
2490 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2491 * @param[in] key The name of the metadata
2492 * @param[in] data The metadata itself
2493 * @param[in] length The number of characters in the string, or -1 if the length is unknown but the string is null-terminated
2494 */
2495 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2496 void ITTAPI __itt_metadata_str_addA(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length);
2497 void ITTAPI __itt_metadata_str_addW(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const wchar_t *data, size_t length);
2498 #if defined(UNICODE) || defined(_UNICODE)
2499 # define __itt_metadata_str_add __itt_metadata_str_addW
2500 # define __itt_metadata_str_add_ptr __itt_metadata_str_addW_ptr
2501 #else /* UNICODE */
2502 # define __itt_metadata_str_add __itt_metadata_str_addA
2503 # define __itt_metadata_str_add_ptr __itt_metadata_str_addA_ptr
2504 #endif /* UNICODE */
2505 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2506 void ITTAPI __itt_metadata_str_add(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length);
2507 #endif
2508
2509 /** @cond exclude_from_documentation */
2510 #ifndef INTEL_NO_MACRO_BODY
2511 #ifndef INTEL_NO_ITTNOTIFY_API
2512 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2513 ITT_STUBV(ITTAPI, void, metadata_str_addA, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length))
2514 ITT_STUBV(ITTAPI, void, metadata_str_addW, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const wchar_t *data, size_t length))
2515 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2516 ITT_STUBV(ITTAPI, void, metadata_str_add, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length))
2517 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2518 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2519 #define __itt_metadata_str_addA(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_addA,d,x,y,z,a)
2520 #define __itt_metadata_str_addA_ptr ITTNOTIFY_NAME(metadata_str_addA)
2521 #define __itt_metadata_str_addW(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_addW,d,x,y,z,a)
2522 #define __itt_metadata_str_addW_ptr ITTNOTIFY_NAME(metadata_str_addW)
2523 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2524 #define __itt_metadata_str_add(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add,d,x,y,z,a)
2525 #define __itt_metadata_str_add_ptr ITTNOTIFY_NAME(metadata_str_add)
2526 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2527 #else /* INTEL_NO_ITTNOTIFY_API */
2528 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2529 #define __itt_metadata_str_addA(d,x,y,z,a)
2530 #define __itt_metadata_str_addA_ptr 0
2531 #define __itt_metadata_str_addW(d,x,y,z,a)
2532 #define __itt_metadata_str_addW_ptr 0
2533 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2534 #define __itt_metadata_str_add(d,x,y,z,a)
2535 #define __itt_metadata_str_add_ptr 0
2536 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2537 #endif /* INTEL_NO_ITTNOTIFY_API */
2538 #else /* INTEL_NO_MACRO_BODY */
2539 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2540 #define __itt_metadata_str_addA_ptr 0
2541 #define __itt_metadata_str_addW_ptr 0
2542 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2543 #define __itt_metadata_str_add_ptr 0
2544 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2545 #endif /* INTEL_NO_MACRO_BODY */
2546 /** @endcond */
2547
2548 /**
2549 * @ingroup parameters
2550 * @brief Add metadata to an instance of a named entity.
2551 * @param[in] domain The domain controlling the call
2552 * @param[in] scope The scope of the instance to which the metadata is to be added
2553
2554 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2555
2556 * @param[in] key The name of the metadata
2557 * @param[in] type The type of the metadata
2558 * @param[in] count The number of elements of the given type. If count == 0, no metadata will be added.
2559 * @param[in] data The metadata itself
2560 */
2561 void ITTAPI __itt_metadata_add_with_scope(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data);
2562
2563 /** @cond exclude_from_documentation */
2564 #ifndef INTEL_NO_MACRO_BODY
2565 #ifndef INTEL_NO_ITTNOTIFY_API
2566 ITT_STUBV(ITTAPI, void, metadata_add_with_scope, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data))
2567 #define __itt_metadata_add_with_scope(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(metadata_add_with_scope,d,x,y,z,a,b)
2568 #define __itt_metadata_add_with_scope_ptr ITTNOTIFY_NAME(metadata_add_with_scope)
2569 #else /* INTEL_NO_ITTNOTIFY_API */
2570 #define __itt_metadata_add_with_scope(d,x,y,z,a,b)
2571 #define __itt_metadata_add_with_scope_ptr 0
2572 #endif /* INTEL_NO_ITTNOTIFY_API */
2573 #else /* INTEL_NO_MACRO_BODY */
2574 #define __itt_metadata_add_with_scope_ptr 0
2575 #endif /* INTEL_NO_MACRO_BODY */
2576 /** @endcond */
2577
2578 /**
2579 * @ingroup parameters
2580 * @brief Add string metadata to an instance of a named entity.
2581 * @param[in] domain The domain controlling the call
2582 * @param[in] scope The scope of the instance to which the metadata is to be added
2583
2584 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2585
2586 * @param[in] key The name of the metadata
2587 * @param[in] data The metadata itself
2588 * @param[in] length The number of characters in the string, or -1 if the length is unknown but the string is null-terminated
2589 */
2590 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2591 void ITTAPI __itt_metadata_str_add_with_scopeA(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length);
2592 void ITTAPI __itt_metadata_str_add_with_scopeW(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const wchar_t *data, size_t length);
2593 #if defined(UNICODE) || defined(_UNICODE)
2594 # define __itt_metadata_str_add_with_scope __itt_metadata_str_add_with_scopeW
2595 # define __itt_metadata_str_add_with_scope_ptr __itt_metadata_str_add_with_scopeW_ptr
2596 #else /* UNICODE */
2597 # define __itt_metadata_str_add_with_scope __itt_metadata_str_add_with_scopeA
2598 # define __itt_metadata_str_add_with_scope_ptr __itt_metadata_str_add_with_scopeA_ptr
2599 #endif /* UNICODE */
2600 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2601 void ITTAPI __itt_metadata_str_add_with_scope(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length);
2602 #endif
2603
2604 /** @cond exclude_from_documentation */
2605 #ifndef INTEL_NO_MACRO_BODY
2606 #ifndef INTEL_NO_ITTNOTIFY_API
2607 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2608 ITT_STUBV(ITTAPI, void, metadata_str_add_with_scopeA, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length))
2609 ITT_STUBV(ITTAPI, void, metadata_str_add_with_scopeW, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const wchar_t *data, size_t length))
2610 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2611 ITT_STUBV(ITTAPI, void, metadata_str_add_with_scope, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length))
2612 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2613 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2614 #define __itt_metadata_str_add_with_scopeA(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add_with_scopeA,d,x,y,z,a)
2615 #define __itt_metadata_str_add_with_scopeA_ptr ITTNOTIFY_NAME(metadata_str_add_with_scopeA)
2616 #define __itt_metadata_str_add_with_scopeW(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add_with_scopeW,d,x,y,z,a)
2617 #define __itt_metadata_str_add_with_scopeW_ptr ITTNOTIFY_NAME(metadata_str_add_with_scopeW)
2618 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2619 #define __itt_metadata_str_add_with_scope(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add_with_scope,d,x,y,z,a)
2620 #define __itt_metadata_str_add_with_scope_ptr ITTNOTIFY_NAME(metadata_str_add_with_scope)
2621 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2622 #else /* INTEL_NO_ITTNOTIFY_API */
2623 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2624 #define __itt_metadata_str_add_with_scopeA(d,x,y,z,a)
2625 #define __itt_metadata_str_add_with_scopeA_ptr 0
2626 #define __itt_metadata_str_add_with_scopeW(d,x,y,z,a)
2627 #define __itt_metadata_str_add_with_scopeW_ptr 0
2628 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2629 #define __itt_metadata_str_add_with_scope(d,x,y,z,a)
2630 #define __itt_metadata_str_add_with_scope_ptr 0
2631 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2632 #endif /* INTEL_NO_ITTNOTIFY_API */
2633 #else /* INTEL_NO_MACRO_BODY */
2634 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2635 #define __itt_metadata_str_add_with_scopeA_ptr 0
2636 #define __itt_metadata_str_add_with_scopeW_ptr 0
2637 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2638 #define __itt_metadata_str_add_with_scope_ptr 0
2639 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2640 #endif /* INTEL_NO_MACRO_BODY */
2641 /** @endcond */
2642
2643 /** @} metadata group */
2644
2645 /**
2646 * @defgroup relations Relations
2647 * Instances of named entities can be explicitly associated with other
2648 * instances using instance IDs and the relationship API calls.
2649 *
2650 * @{
2651 */
2652
2653 /**
2654 * @ingroup relations
2655 * @brief The kind of relation between two instances is specified by the enumerated type __itt_relation.
2656 * Relations between instances can be added with an API call. The relation
2657 * API uses instance IDs. Relations can be added before or after the actual
2658 * instances are created and persist independently of the instances. This
2659 * is the motivation for having different lifetimes for instance IDs and
2660 * the actual instances.
2661 */
2662 typedef enum
2663 {
2664 __itt_relation_is_unknown = 0,
2665 __itt_relation_is_dependent_on, /**< "A is dependent on B" means that A cannot start until B completes */
2666 __itt_relation_is_sibling_of, /**< "A is sibling of B" means that A and B were created as a group */
2667 __itt_relation_is_parent_of, /**< "A is parent of B" means that A created B */
2668 __itt_relation_is_continuation_of, /**< "A is continuation of B" means that A assumes the dependencies of B */
2669 __itt_relation_is_child_of, /**< "A is child of B" means that A was created by B (inverse of is_parent_of) */
2670 __itt_relation_is_continued_by, /**< "A is continued by B" means that B assumes the dependencies of A (inverse of is_continuation_of) */
2671 __itt_relation_is_predecessor_to /**< "A is predecessor to B" means that B cannot start until A completes (inverse of is_dependent_on) */
2672 } __itt_relation;
2673
2674 /**
2675 * @ingroup relations
2676 * @brief Add a relation to the current task instance.
2677 * The current task instance is the head of the relation.
2678 * @param[in] domain The domain controlling this call
2679 * @param[in] relation The kind of relation
2680 * @param[in] tail The ID for the tail of the relation
2681 */
2682 void ITTAPI __itt_relation_add_to_current(const __itt_domain *domain, __itt_relation relation, __itt_id tail);
2683
2684 /**
2685 * @ingroup relations
2686 * @brief Add a relation between two instance identifiers.
2687 * @param[in] domain The domain controlling this call
2688 * @param[in] head The ID for the head of the relation
2689 * @param[in] relation The kind of relation
2690 * @param[in] tail The ID for the tail of the relation
2691 */
2692 void ITTAPI __itt_relation_add(const __itt_domain *domain, __itt_id head, __itt_relation relation, __itt_id tail);
2693
2694 /** @cond exclude_from_documentation */
2695 #ifndef INTEL_NO_MACRO_BODY
2696 #ifndef INTEL_NO_ITTNOTIFY_API
2697 ITT_STUBV(ITTAPI, void, relation_add_to_current, (const __itt_domain *domain, __itt_relation relation, __itt_id tail))
2698 ITT_STUBV(ITTAPI, void, relation_add, (const __itt_domain *domain, __itt_id head, __itt_relation relation, __itt_id tail))
2699 #define __itt_relation_add_to_current(d,x,y) ITTNOTIFY_VOID_D2(relation_add_to_current,d,x,y)
2700 #define __itt_relation_add_to_current_ptr ITTNOTIFY_NAME(relation_add_to_current)
2701 #define __itt_relation_add(d,x,y,z) ITTNOTIFY_VOID_D3(relation_add,d,x,y,z)
2702 #define __itt_relation_add_ptr ITTNOTIFY_NAME(relation_add)
2703 #else /* INTEL_NO_ITTNOTIFY_API */
2704 #define __itt_relation_add_to_current(d,x,y)
2705 #define __itt_relation_add_to_current_ptr 0
2706 #define __itt_relation_add(d,x,y,z)
2707 #define __itt_relation_add_ptr 0
2708 #endif /* INTEL_NO_ITTNOTIFY_API */
2709 #else /* INTEL_NO_MACRO_BODY */
2710 #define __itt_relation_add_to_current_ptr 0
2711 #define __itt_relation_add_ptr 0
2712 #endif /* INTEL_NO_MACRO_BODY */
2713 /** @endcond */
2714 /** @} relations group */
2715
2716 /** @cond exclude_from_documentation */
2717 #pragma pack(push, 8)
2718
2719 typedef struct ___itt_clock_info
2720 {
2721 unsigned long long clock_freq; /*!< Clock domain frequency */
2722 unsigned long long clock_base; /*!< Clock domain base timestamp */
2723 } __itt_clock_info;
2724
2725 #pragma pack(pop)
2726 /** @endcond */
2727
2728 /** @cond exclude_from_documentation */
2729 typedef void (ITTAPI *__itt_get_clock_info_fn)(__itt_clock_info* clock_info, void* data);
2730 /** @endcond */
2731
2732 /** @cond exclude_from_documentation */
2733 #pragma pack(push, 8)
2734
2735 typedef struct ___itt_clock_domain
2736 {
2737 __itt_clock_info info; /*!< Most recent clock domain info */
2738 __itt_get_clock_info_fn fn; /*!< Callback function pointer */
2739 void* fn_data; /*!< Input argument for the callback function */
2740 int extra1; /*!< Reserved. Must be zero */
2741 void* extra2; /*!< Reserved. Must be zero */
2742 struct ___itt_clock_domain* next;
2743 } __itt_clock_domain;
2744
2745 #pragma pack(pop)
2746 /** @endcond */
2747
2748 /**
2749 * @ingroup clockdomains
2750 * @brief Create a clock domain.
2751 * Certain applications require the capability to trace their application using
2752 * a clock domain different than the CPU, for instance the instrumentation of events
2753 * that occur on a GPU.
2754 * Because the set of domains is expected to be static over the application's execution time,
2755 * there is no mechanism to destroy a domain.
2756 * Any domain can be accessed by any thread in the process, regardless of which thread created
2757 * the domain. This call is thread-safe.
2758 * @param[in] fn A pointer to a callback function which retrieves alternative CPU timestamps
2759 * @param[in] fn_data Argument for a callback function; may be NULL
2760 */
2761 __itt_clock_domain* ITTAPI __itt_clock_domain_create(__itt_get_clock_info_fn fn, void* fn_data);
2762
2763 /** @cond exclude_from_documentation */
2764 #ifndef INTEL_NO_MACRO_BODY
2765 #ifndef INTEL_NO_ITTNOTIFY_API
2766 ITT_STUB(ITTAPI, __itt_clock_domain*, clock_domain_create, (__itt_get_clock_info_fn fn, void* fn_data))
2767 #define __itt_clock_domain_create ITTNOTIFY_DATA(clock_domain_create)
2768 #define __itt_clock_domain_create_ptr ITTNOTIFY_NAME(clock_domain_create)
2769 #else /* INTEL_NO_ITTNOTIFY_API */
2770 #define __itt_clock_domain_create(fn,fn_data) (__itt_clock_domain*)0
2771 #define __itt_clock_domain_create_ptr 0
2772 #endif /* INTEL_NO_ITTNOTIFY_API */
2773 #else /* INTEL_NO_MACRO_BODY */
2774 #define __itt_clock_domain_create_ptr 0
2775 #endif /* INTEL_NO_MACRO_BODY */
2776 /** @endcond */
2777
2778 /**
2779 * @ingroup clockdomains
2780 * @brief Recalculate clock domains frequencies and clock base timestamps.
2781 */
2782 void ITTAPI __itt_clock_domain_reset(void);
2783
2784 /** @cond exclude_from_documentation */
2785 #ifndef INTEL_NO_MACRO_BODY
2786 #ifndef INTEL_NO_ITTNOTIFY_API
2787 ITT_STUBV(ITTAPI, void, clock_domain_reset, (void))
2788 #define __itt_clock_domain_reset ITTNOTIFY_VOID(clock_domain_reset)
2789 #define __itt_clock_domain_reset_ptr ITTNOTIFY_NAME(clock_domain_reset)
2790 #else /* INTEL_NO_ITTNOTIFY_API */
2791 #define __itt_clock_domain_reset()
2792 #define __itt_clock_domain_reset_ptr 0
2793 #endif /* INTEL_NO_ITTNOTIFY_API */
2794 #else /* INTEL_NO_MACRO_BODY */
2795 #define __itt_clock_domain_reset_ptr 0
2796 #endif /* INTEL_NO_MACRO_BODY */
2797 /** @endcond */
2798
2799 /**
2800 * @ingroup clockdomain
2801 * @brief Create an instance of identifier. This establishes the beginning of the lifetime of
2802 * an instance of the given ID in the trace. Once this lifetime starts, the ID can be used to
2803 * tag named entity instances in calls such as __itt_task_begin, and to specify relationships among
2804 * identified named entity instances, using the \ref relations APIs.
2805 * @param[in] domain The domain controlling the execution of this call.
2806 * @param[in] clock_domain The clock domain controlling the execution of this call.
2807 * @param[in] timestamp The user defined timestamp.
2808 * @param[in] id The ID to create.
2809 */
2810 void ITTAPI __itt_id_create_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id);
2811
2812 /**
2813 * @ingroup clockdomain
2814 * @brief Destroy an instance of identifier. This ends the lifetime of the current instance of the
2815 * given ID value in the trace. Any relationships that are established after this lifetime ends are
2816 * invalid. This call must be performed before the given ID value can be reused for a different
2817 * named entity instance.
2818 * @param[in] domain The domain controlling the execution of this call.
2819 * @param[in] clock_domain The clock domain controlling the execution of this call.
2820 * @param[in] timestamp The user defined timestamp.
2821 * @param[in] id The ID to destroy.
2822 */
2823 void ITTAPI __itt_id_destroy_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id);
2824
2825 /** @cond exclude_from_documentation */
2826 #ifndef INTEL_NO_MACRO_BODY
2827 #ifndef INTEL_NO_ITTNOTIFY_API
2828 ITT_STUBV(ITTAPI, void, id_create_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id))
2829 ITT_STUBV(ITTAPI, void, id_destroy_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id))
2830 #define __itt_id_create_ex(d,x,y,z) ITTNOTIFY_VOID_D3(id_create_ex,d,x,y,z)
2831 #define __itt_id_create_ex_ptr ITTNOTIFY_NAME(id_create_ex)
2832 #define __itt_id_destroy_ex(d,x,y,z) ITTNOTIFY_VOID_D3(id_destroy_ex,d,x,y,z)
2833 #define __itt_id_destroy_ex_ptr ITTNOTIFY_NAME(id_destroy_ex)
2834 #else /* INTEL_NO_ITTNOTIFY_API */
2835 #define __itt_id_create_ex(domain,clock_domain,timestamp,id)
2836 #define __itt_id_create_ex_ptr 0
2837 #define __itt_id_destroy_ex(domain,clock_domain,timestamp,id)
2838 #define __itt_id_destroy_ex_ptr 0
2839 #endif /* INTEL_NO_ITTNOTIFY_API */
2840 #else /* INTEL_NO_MACRO_BODY */
2841 #define __itt_id_create_ex_ptr 0
2842 #define __itt_id_destroy_ex_ptr 0
2843 #endif /* INTEL_NO_MACRO_BODY */
2844 /** @endcond */
2845
2846 /**
2847 * @ingroup clockdomain
2848 * @brief Begin a task instance.
2849 * @param[in] domain The domain for this task
2850 * @param[in] clock_domain The clock domain controlling the execution of this call.
2851 * @param[in] timestamp The user defined timestamp.
2852 * @param[in] taskid The instance ID for this task instance, or __itt_null
2853 * @param[in] parentid The parent instance to which this task instance belongs, or __itt_null
2854 * @param[in] name The name of this task
2855 */
2856 void ITTAPI __itt_task_begin_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
2857
2858 /**
2859 * @ingroup clockdomain
2860 * @brief Begin a task instance.
2861 * @param[in] domain The domain for this task
2862 * @param[in] clock_domain The clock domain controlling the execution of this call.
2863 * @param[in] timestamp The user defined timestamp.
2864 * @param[in] taskid The identifier for this task instance, or __itt_null
2865 * @param[in] parentid The parent of this task, or __itt_null
2866 * @param[in] fn The pointer to the function you are tracing
2867 */
2868 void ITTAPI __itt_task_begin_fn_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, void* fn);
2869
2870 /**
2871 * @ingroup clockdomain
2872 * @brief End the current task instance.
2873 * @param[in] domain The domain for this task
2874 * @param[in] clock_domain The clock domain controlling the execution of this call.
2875 * @param[in] timestamp The user defined timestamp.
2876 */
2877 void ITTAPI __itt_task_end_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp);
2878
2879 /** @cond exclude_from_documentation */
2880 #ifndef INTEL_NO_MACRO_BODY
2881 #ifndef INTEL_NO_ITTNOTIFY_API
2882 ITT_STUBV(ITTAPI, void, task_begin_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2883 ITT_STUBV(ITTAPI, void, task_begin_fn_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_id parentid, void* fn))
2884 ITT_STUBV(ITTAPI, void, task_end_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp))
2885 #define __itt_task_begin_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(task_begin_ex,d,x,y,z,a,b)
2886 #define __itt_task_begin_ex_ptr ITTNOTIFY_NAME(task_begin_ex)
2887 #define __itt_task_begin_fn_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(task_begin_fn_ex,d,x,y,z,a,b)
2888 #define __itt_task_begin_fn_ex_ptr ITTNOTIFY_NAME(task_begin_fn_ex)
2889 #define __itt_task_end_ex(d,x,y) ITTNOTIFY_VOID_D2(task_end_ex,d,x,y)
2890 #define __itt_task_end_ex_ptr ITTNOTIFY_NAME(task_end_ex)
2891 #else /* INTEL_NO_ITTNOTIFY_API */
2892 #define __itt_task_begin_ex(domain,clock_domain,timestamp,id,parentid,name)
2893 #define __itt_task_begin_ex_ptr 0
2894 #define __itt_task_begin_fn_ex(domain,clock_domain,timestamp,id,parentid,fn)
2895 #define __itt_task_begin_fn_ex_ptr 0
2896 #define __itt_task_end_ex(domain,clock_domain,timestamp)
2897 #define __itt_task_end_ex_ptr 0
2898 #endif /* INTEL_NO_ITTNOTIFY_API */
2899 #else /* INTEL_NO_MACRO_BODY */
2900 #define __itt_task_begin_ex_ptr 0
2901 #define __itt_task_begin_fn_ex_ptr 0
2902 #define __itt_task_end_ex_ptr 0
2903 #endif /* INTEL_NO_MACRO_BODY */
2904 /** @endcond */
2905
2906 /**
2907 * @defgroup counters Counters
2908 * @ingroup public
2909 * Counters are user-defined objects with a monotonically increasing
2910 * value. Counter values are 64-bit unsigned integers.
2911 * Counters have names that can be displayed in
2912 * the tools.
2913 * @{
2914 */
2915
2916 /**
2917 * @brief opaque structure for counter identification
2918 */
2919 /** @cond exclude_from_documentation */
2920
2921 typedef struct ___itt_counter* __itt_counter;
2922
2923 /**
2924 * @brief Create an unsigned 64 bits integer counter with given name/domain
2925 *
2926 * After __itt_counter_create() is called, __itt_counter_inc(id), __itt_counter_inc_delta(id, delta),
2927 * __itt_counter_set_value(id, value_ptr) or __itt_counter_set_value_ex(id, clock_domain, timestamp, value_ptr)
2928 * can be used to change the value of the counter, where value_ptr is a pointer to an unsigned 64 bits integer
2929 *
2930 * The call is equal to __itt_counter_create_typed(name, domain, __itt_metadata_u64)
2931 */
2932 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2933 __itt_counter ITTAPI __itt_counter_createA(const char *name, const char *domain);
2934 __itt_counter ITTAPI __itt_counter_createW(const wchar_t *name, const wchar_t *domain);
2935 #if defined(UNICODE) || defined(_UNICODE)
2936 # define __itt_counter_create __itt_counter_createW
2937 # define __itt_counter_create_ptr __itt_counter_createW_ptr
2938 #else /* UNICODE */
2939 # define __itt_counter_create __itt_counter_createA
2940 # define __itt_counter_create_ptr __itt_counter_createA_ptr
2941 #endif /* UNICODE */
2942 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2943 __itt_counter ITTAPI __itt_counter_create(const char *name, const char *domain);
2944 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2945
2946 #ifndef INTEL_NO_MACRO_BODY
2947 #ifndef INTEL_NO_ITTNOTIFY_API
2948 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2949 ITT_STUB(ITTAPI, __itt_counter, counter_createA, (const char *name, const char *domain))
2950 ITT_STUB(ITTAPI, __itt_counter, counter_createW, (const wchar_t *name, const wchar_t *domain))
2951 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2952 ITT_STUB(ITTAPI, __itt_counter, counter_create, (const char *name, const char *domain))
2953 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2954 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2955 #define __itt_counter_createA ITTNOTIFY_DATA(counter_createA)
2956 #define __itt_counter_createA_ptr ITTNOTIFY_NAME(counter_createA)
2957 #define __itt_counter_createW ITTNOTIFY_DATA(counter_createW)
2958 #define __itt_counter_createW_ptr ITTNOTIFY_NAME(counter_createW)
2959 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2960 #define __itt_counter_create ITTNOTIFY_DATA(counter_create)
2961 #define __itt_counter_create_ptr ITTNOTIFY_NAME(counter_create)
2962 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2963 #else /* INTEL_NO_ITTNOTIFY_API */
2964 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2965 #define __itt_counter_createA(name, domain)
2966 #define __itt_counter_createA_ptr 0
2967 #define __itt_counter_createW(name, domain)
2968 #define __itt_counter_createW_ptr 0
2969 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2970 #define __itt_counter_create(name, domain)
2971 #define __itt_counter_create_ptr 0
2972 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2973 #endif /* INTEL_NO_ITTNOTIFY_API */
2974 #else /* INTEL_NO_MACRO_BODY */
2975 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2976 #define __itt_counter_createA_ptr 0
2977 #define __itt_counter_createW_ptr 0
2978 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2979 #define __itt_counter_create_ptr 0
2980 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2981 #endif /* INTEL_NO_MACRO_BODY */
2982 /** @endcond */
2983
2984 /**
2985 * @brief Increment the unsigned 64 bits integer counter value
2986 *
2987 * Calling this function to non-unsigned 64 bits integer counters has no effect
2988 */
2989 void ITTAPI __itt_counter_inc(__itt_counter id);
2990
2991 #ifndef INTEL_NO_MACRO_BODY
2992 #ifndef INTEL_NO_ITTNOTIFY_API
2993 ITT_STUBV(ITTAPI, void, counter_inc, (__itt_counter id))
2994 #define __itt_counter_inc ITTNOTIFY_VOID(counter_inc)
2995 #define __itt_counter_inc_ptr ITTNOTIFY_NAME(counter_inc)
2996 #else /* INTEL_NO_ITTNOTIFY_API */
2997 #define __itt_counter_inc(id)
2998 #define __itt_counter_inc_ptr 0
2999 #endif /* INTEL_NO_ITTNOTIFY_API */
3000 #else /* INTEL_NO_MACRO_BODY */
3001 #define __itt_counter_inc_ptr 0
3002 #endif /* INTEL_NO_MACRO_BODY */
3003 /** @endcond */
3004 /**
3005 * @brief Increment the unsigned 64 bits integer counter value with x
3006 *
3007 * Calling this function to non-unsigned 64 bits integer counters has no effect
3008 */
3009 void ITTAPI __itt_counter_inc_delta(__itt_counter id, unsigned long long value);
3010
3011 #ifndef INTEL_NO_MACRO_BODY
3012 #ifndef INTEL_NO_ITTNOTIFY_API
3013 ITT_STUBV(ITTAPI, void, counter_inc_delta, (__itt_counter id, unsigned long long value))
3014 #define __itt_counter_inc_delta ITTNOTIFY_VOID(counter_inc_delta)
3015 #define __itt_counter_inc_delta_ptr ITTNOTIFY_NAME(counter_inc_delta)
3016 #else /* INTEL_NO_ITTNOTIFY_API */
3017 #define __itt_counter_inc_delta(id, value)
3018 #define __itt_counter_inc_delta_ptr 0
3019 #endif /* INTEL_NO_ITTNOTIFY_API */
3020 #else /* INTEL_NO_MACRO_BODY */
3021 #define __itt_counter_inc_delta_ptr 0
3022 #endif /* INTEL_NO_MACRO_BODY */
3023 /** @endcond */
3024
3025 /**
3026 * @brief Decrement the unsigned 64 bits integer counter value
3027 *
3028 * Calling this function to non-unsigned 64 bits integer counters has no effect
3029 */
3030 void ITTAPI __itt_counter_dec(__itt_counter id);
3031
3032 #ifndef INTEL_NO_MACRO_BODY
3033 #ifndef INTEL_NO_ITTNOTIFY_API
3034 ITT_STUBV(ITTAPI, void, counter_dec, (__itt_counter id))
3035 #define __itt_counter_dec ITTNOTIFY_VOID(counter_dec)
3036 #define __itt_counter_dec_ptr ITTNOTIFY_NAME(counter_dec)
3037 #else /* INTEL_NO_ITTNOTIFY_API */
3038 #define __itt_counter_dec(id)
3039 #define __itt_counter_dec_ptr 0
3040 #endif /* INTEL_NO_ITTNOTIFY_API */
3041 #else /* INTEL_NO_MACRO_BODY */
3042 #define __itt_counter_dec_ptr 0
3043 #endif /* INTEL_NO_MACRO_BODY */
3044 /** @endcond */
3045 /**
3046 * @brief Decrement the unsigned 64 bits integer counter value with x
3047 *
3048 * Calling this function to non-unsigned 64 bits integer counters has no effect
3049 */
3050 void ITTAPI __itt_counter_dec_delta(__itt_counter id, unsigned long long value);
3051
3052 #ifndef INTEL_NO_MACRO_BODY
3053 #ifndef INTEL_NO_ITTNOTIFY_API
3054 ITT_STUBV(ITTAPI, void, counter_dec_delta, (__itt_counter id, unsigned long long value))
3055 #define __itt_counter_dec_delta ITTNOTIFY_VOID(counter_dec_delta)
3056 #define __itt_counter_dec_delta_ptr ITTNOTIFY_NAME(counter_dec_delta)
3057 #else /* INTEL_NO_ITTNOTIFY_API */
3058 #define __itt_counter_dec_delta(id, value)
3059 #define __itt_counter_dec_delta_ptr 0
3060 #endif /* INTEL_NO_ITTNOTIFY_API */
3061 #else /* INTEL_NO_MACRO_BODY */
3062 #define __itt_counter_dec_delta_ptr 0
3063 #endif /* INTEL_NO_MACRO_BODY */
3064 /** @endcond */
3065
3066 /**
3067 * @ingroup counters
3068 * @brief Increment a counter by one.
3069 * The first call with a given name creates a counter by that name and sets its
3070 * value to zero. Successive calls increment the counter value.
3071 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3072 * The domain argument is used only to enable or disable the API calls.
3073 * @param[in] name The name of the counter
3074 */
3075 void ITTAPI __itt_counter_inc_v3(const __itt_domain *domain, __itt_string_handle *name);
3076
3077 /**
3078 * @ingroup counters
3079 * @brief Increment a counter by the value specified in delta.
3080 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3081 * The domain argument is used only to enable or disable the API calls.
3082 * @param[in] name The name of the counter
3083 * @param[in] delta The amount by which to increment the counter
3084 */
3085 void ITTAPI __itt_counter_inc_delta_v3(const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta);
3086
3087 #ifndef INTEL_NO_MACRO_BODY
3088 #ifndef INTEL_NO_ITTNOTIFY_API
3089 ITT_STUBV(ITTAPI, void, counter_inc_v3, (const __itt_domain *domain, __itt_string_handle *name))
3090 ITT_STUBV(ITTAPI, void, counter_inc_delta_v3, (const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta))
3091 #define __itt_counter_inc_v3(d,x) ITTNOTIFY_VOID_D1(counter_inc_v3,d,x)
3092 #define __itt_counter_inc_v3_ptr ITTNOTIFY_NAME(counter_inc_v3)
3093 #define __itt_counter_inc_delta_v3(d,x,y) ITTNOTIFY_VOID_D2(counter_inc_delta_v3,d,x,y)
3094 #define __itt_counter_inc_delta_v3_ptr ITTNOTIFY_NAME(counter_inc_delta_v3)
3095 #else /* INTEL_NO_ITTNOTIFY_API */
3096 #define __itt_counter_inc_v3(domain,name)
3097 #define __itt_counter_inc_v3_ptr 0
3098 #define __itt_counter_inc_delta_v3(domain,name,delta)
3099 #define __itt_counter_inc_delta_v3_ptr 0
3100 #endif /* INTEL_NO_ITTNOTIFY_API */
3101 #else /* INTEL_NO_MACRO_BODY */
3102 #define __itt_counter_inc_v3_ptr 0
3103 #define __itt_counter_inc_delta_v3_ptr 0
3104 #endif /* INTEL_NO_MACRO_BODY */
3105 /** @endcond */
3106
3107
3108 /**
3109 * @ingroup counters
3110 * @brief Decrement a counter by one.
3111 * The first call with a given name creates a counter by that name and sets its
3112 * value to zero. Successive calls decrement the counter value.
3113 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3114 * The domain argument is used only to enable or disable the API calls.
3115 * @param[in] name The name of the counter
3116 */
3117 void ITTAPI __itt_counter_dec_v3(const __itt_domain *domain, __itt_string_handle *name);
3118
3119 /**
3120 * @ingroup counters
3121 * @brief Decrement a counter by the value specified in delta.
3122 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3123 * The domain argument is used only to enable or disable the API calls.
3124 * @param[in] name The name of the counter
3125 * @param[in] delta The amount by which to decrement the counter
3126 */
3127 void ITTAPI __itt_counter_dec_delta_v3(const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta);
3128
3129 #ifndef INTEL_NO_MACRO_BODY
3130 #ifndef INTEL_NO_ITTNOTIFY_API
3131 ITT_STUBV(ITTAPI, void, counter_dec_v3, (const __itt_domain *domain, __itt_string_handle *name))
3132 ITT_STUBV(ITTAPI, void, counter_dec_delta_v3, (const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta))
3133 #define __itt_counter_dec_v3(d,x) ITTNOTIFY_VOID_D1(counter_dec_v3,d,x)
3134 #define __itt_counter_dec_v3_ptr ITTNOTIFY_NAME(counter_dec_v3)
3135 #define __itt_counter_dec_delta_v3(d,x,y) ITTNOTIFY_VOID_D2(counter_dec_delta_v3,d,x,y)
3136 #define __itt_counter_dec_delta_v3_ptr ITTNOTIFY_NAME(counter_dec_delta_v3)
3137 #else /* INTEL_NO_ITTNOTIFY_API */
3138 #define __itt_counter_dec_v3(domain,name)
3139 #define __itt_counter_dec_v3_ptr 0
3140 #define __itt_counter_dec_delta_v3(domain,name,delta)
3141 #define __itt_counter_dec_delta_v3_ptr 0
3142 #endif /* INTEL_NO_ITTNOTIFY_API */
3143 #else /* INTEL_NO_MACRO_BODY */
3144 #define __itt_counter_dec_v3_ptr 0
3145 #define __itt_counter_dec_delta_v3_ptr 0
3146 #endif /* INTEL_NO_MACRO_BODY */
3147 /** @endcond */
3148
3149 /** @} counters group */
3150
3151
3152 /**
3153 * @brief Set the counter value
3154 */
3155 void ITTAPI __itt_counter_set_value(__itt_counter id, void *value_ptr);
3156
3157 #ifndef INTEL_NO_MACRO_BODY
3158 #ifndef INTEL_NO_ITTNOTIFY_API
3159 ITT_STUBV(ITTAPI, void, counter_set_value, (__itt_counter id, void *value_ptr))
3160 #define __itt_counter_set_value ITTNOTIFY_VOID(counter_set_value)
3161 #define __itt_counter_set_value_ptr ITTNOTIFY_NAME(counter_set_value)
3162 #else /* INTEL_NO_ITTNOTIFY_API */
3163 #define __itt_counter_set_value(id, value_ptr)
3164 #define __itt_counter_set_value_ptr 0
3165 #endif /* INTEL_NO_ITTNOTIFY_API */
3166 #else /* INTEL_NO_MACRO_BODY */
3167 #define __itt_counter_set_value_ptr 0
3168 #endif /* INTEL_NO_MACRO_BODY */
3169 /** @endcond */
3170
3171 /**
3172 * @brief Set the counter value
3173 */
3174 void ITTAPI __itt_counter_set_value_ex(__itt_counter id, __itt_clock_domain *clock_domain, unsigned long long timestamp, void *value_ptr);
3175
3176 /** @cond exclude_from_documentation */
3177 #ifndef INTEL_NO_MACRO_BODY
3178 #ifndef INTEL_NO_ITTNOTIFY_API
3179 ITT_STUBV(ITTAPI, void, counter_set_value_ex, (__itt_counter id, __itt_clock_domain *clock_domain, unsigned long long timestamp, void *value_ptr))
3180 #define __itt_counter_set_value_ex ITTNOTIFY_VOID(counter_set_value_ex)
3181 #define __itt_counter_set_value_ex_ptr ITTNOTIFY_NAME(counter_set_value_ex)
3182 #else /* INTEL_NO_ITTNOTIFY_API */
3183 #define __itt_counter_set_value_ex(id, clock_domain, timestamp, value_ptr)
3184 #define __itt_counter_set_value_ex_ptr 0
3185 #endif /* INTEL_NO_ITTNOTIFY_API */
3186 #else /* INTEL_NO_MACRO_BODY */
3187 #define __itt_counter_set_value_ex_ptr 0
3188 #endif /* INTEL_NO_MACRO_BODY */
3189 /** @endcond */
3190
3191 /**
3192 * @brief Create a typed counter with given name/domain
3193 *
3194 * After __itt_counter_create_typed() is called, __itt_counter_inc(id), __itt_counter_inc_delta(id, delta),
3195 * __itt_counter_set_value(id, value_ptr) or __itt_counter_set_value_ex(id, clock_domain, timestamp, value_ptr)
3196 * can be used to change the value of the counter
3197 */
3198 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3199 __itt_counter ITTAPI __itt_counter_create_typedA(const char *name, const char *domain, __itt_metadata_type type);
3200 __itt_counter ITTAPI __itt_counter_create_typedW(const wchar_t *name, const wchar_t *domain, __itt_metadata_type type);
3201 #if defined(UNICODE) || defined(_UNICODE)
3202 # define __itt_counter_create_typed __itt_counter_create_typedW
3203 # define __itt_counter_create_typed_ptr __itt_counter_create_typedW_ptr
3204 #else /* UNICODE */
3205 # define __itt_counter_create_typed __itt_counter_create_typedA
3206 # define __itt_counter_create_typed_ptr __itt_counter_create_typedA_ptr
3207 #endif /* UNICODE */
3208 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3209 __itt_counter ITTAPI __itt_counter_create_typed(const char *name, const char *domain, __itt_metadata_type type);
3210 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3211
3212 #ifndef INTEL_NO_MACRO_BODY
3213 #ifndef INTEL_NO_ITTNOTIFY_API
3214 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3215 ITT_STUB(ITTAPI, __itt_counter, counter_create_typedA, (const char *name, const char *domain, __itt_metadata_type type))
3216 ITT_STUB(ITTAPI, __itt_counter, counter_create_typedW, (const wchar_t *name, const wchar_t *domain, __itt_metadata_type type))
3217 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3218 ITT_STUB(ITTAPI, __itt_counter, counter_create_typed, (const char *name, const char *domain, __itt_metadata_type type))
3219 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3220 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3221 #define __itt_counter_create_typedA ITTNOTIFY_DATA(counter_create_typedA)
3222 #define __itt_counter_create_typedA_ptr ITTNOTIFY_NAME(counter_create_typedA)
3223 #define __itt_counter_create_typedW ITTNOTIFY_DATA(counter_create_typedW)
3224 #define __itt_counter_create_typedW_ptr ITTNOTIFY_NAME(counter_create_typedW)
3225 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3226 #define __itt_counter_create_typed ITTNOTIFY_DATA(counter_create_typed)
3227 #define __itt_counter_create_typed_ptr ITTNOTIFY_NAME(counter_create_typed)
3228 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3229 #else /* INTEL_NO_ITTNOTIFY_API */
3230 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3231 #define __itt_counter_create_typedA(name, domain, type)
3232 #define __itt_counter_create_typedA_ptr 0
3233 #define __itt_counter_create_typedW(name, domain, type)
3234 #define __itt_counter_create_typedW_ptr 0
3235 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3236 #define __itt_counter_create_typed(name, domain, type)
3237 #define __itt_counter_create_typed_ptr 0
3238 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3239 #endif /* INTEL_NO_ITTNOTIFY_API */
3240 #else /* INTEL_NO_MACRO_BODY */
3241 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3242 #define __itt_counter_create_typedA_ptr 0
3243 #define __itt_counter_create_typedW_ptr 0
3244 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3245 #define __itt_counter_create_typed_ptr 0
3246 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3247 #endif /* INTEL_NO_MACRO_BODY */
3248 /** @endcond */
3249
3250 /**
3251 * @brief Destroy the counter identified by the pointer previously returned by __itt_counter_create() or
3252 * __itt_counter_create_typed()
3253 */
3254 void ITTAPI __itt_counter_destroy(__itt_counter id);
3255
3256 #ifndef INTEL_NO_MACRO_BODY
3257 #ifndef INTEL_NO_ITTNOTIFY_API
3258 ITT_STUBV(ITTAPI, void, counter_destroy, (__itt_counter id))
3259 #define __itt_counter_destroy ITTNOTIFY_VOID(counter_destroy)
3260 #define __itt_counter_destroy_ptr ITTNOTIFY_NAME(counter_destroy)
3261 #else /* INTEL_NO_ITTNOTIFY_API */
3262 #define __itt_counter_destroy(id)
3263 #define __itt_counter_destroy_ptr 0
3264 #endif /* INTEL_NO_ITTNOTIFY_API */
3265 #else /* INTEL_NO_MACRO_BODY */
3266 #define __itt_counter_destroy_ptr 0
3267 #endif /* INTEL_NO_MACRO_BODY */
3268 /** @endcond */
3269 /** @} counters group */
3270
3271 /**
3272 * @ingroup markers
3273 * @brief Create a marker instance.
3274 * @param[in] domain The domain for this marker
3275 * @param[in] clock_domain The clock domain controlling the execution of this call.
3276 * @param[in] timestamp The user defined timestamp.
3277 * @param[in] id The instance ID for this marker, or __itt_null
3278 * @param[in] name The name for this marker
3279 * @param[in] scope The scope for this marker
3280 */
3281 void ITTAPI __itt_marker_ex(const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_string_handle *name, __itt_scope scope);
3282
3283 /** @cond exclude_from_documentation */
3284 #ifndef INTEL_NO_MACRO_BODY
3285 #ifndef INTEL_NO_ITTNOTIFY_API
3286 ITT_STUBV(ITTAPI, void, marker_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_string_handle *name, __itt_scope scope))
3287 #define __itt_marker_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(marker_ex,d,x,y,z,a,b)
3288 #define __itt_marker_ex_ptr ITTNOTIFY_NAME(marker_ex)
3289 #else /* INTEL_NO_ITTNOTIFY_API */
3290 #define __itt_marker_ex(domain,clock_domain,timestamp,id,name,scope)
3291 #define __itt_marker_ex_ptr 0
3292 #endif /* INTEL_NO_ITTNOTIFY_API */
3293 #else /* INTEL_NO_MACRO_BODY */
3294 #define __itt_marker_ex_ptr 0
3295 #endif /* INTEL_NO_MACRO_BODY */
3296 /** @endcond */
3297
3298 /**
3299 * @ingroup clockdomain
3300 * @brief Add a relation to the current task instance.
3301 * The current task instance is the head of the relation.
3302 * @param[in] domain The domain controlling this call
3303 * @param[in] clock_domain The clock domain controlling the execution of this call.
3304 * @param[in] timestamp The user defined timestamp.
3305 * @param[in] relation The kind of relation
3306 * @param[in] tail The ID for the tail of the relation
3307 */
3308 void ITTAPI __itt_relation_add_to_current_ex(const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_relation relation, __itt_id tail);
3309
3310 /**
3311 * @ingroup clockdomain
3312 * @brief Add a relation between two instance identifiers.
3313 * @param[in] domain The domain controlling this call
3314 * @param[in] clock_domain The clock domain controlling the execution of this call.
3315 * @param[in] timestamp The user defined timestamp.
3316 * @param[in] head The ID for the head of the relation
3317 * @param[in] relation The kind of relation
3318 * @param[in] tail The ID for the tail of the relation
3319 */
3320 void ITTAPI __itt_relation_add_ex(const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id head, __itt_relation relation, __itt_id tail);
3321
3322 /** @cond exclude_from_documentation */
3323 #ifndef INTEL_NO_MACRO_BODY
3324 #ifndef INTEL_NO_ITTNOTIFY_API
3325 ITT_STUBV(ITTAPI, void, relation_add_to_current_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_relation relation, __itt_id tail))
3326 ITT_STUBV(ITTAPI, void, relation_add_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id head, __itt_relation relation, __itt_id tail))
3327 #define __itt_relation_add_to_current_ex(d,x,y,z,a) ITTNOTIFY_VOID_D4(relation_add_to_current_ex,d,x,y,z,a)
3328 #define __itt_relation_add_to_current_ex_ptr ITTNOTIFY_NAME(relation_add_to_current_ex)
3329 #define __itt_relation_add_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(relation_add_ex,d,x,y,z,a,b)
3330 #define __itt_relation_add_ex_ptr ITTNOTIFY_NAME(relation_add_ex)
3331 #else /* INTEL_NO_ITTNOTIFY_API */
3332 #define __itt_relation_add_to_current_ex(domain,clock_domain,timestame,relation,tail)
3333 #define __itt_relation_add_to_current_ex_ptr 0
3334 #define __itt_relation_add_ex(domain,clock_domain,timestamp,head,relation,tail)
3335 #define __itt_relation_add_ex_ptr 0
3336 #endif /* INTEL_NO_ITTNOTIFY_API */
3337 #else /* INTEL_NO_MACRO_BODY */
3338 #define __itt_relation_add_to_current_ex_ptr 0
3339 #define __itt_relation_add_ex_ptr 0
3340 #endif /* INTEL_NO_MACRO_BODY */
3341 /** @endcond */
3342
3343 /** @cond exclude_from_documentation */
3344 typedef enum ___itt_track_group_type
3345 {
3346 __itt_track_group_type_normal = 0
3347 } __itt_track_group_type;
3348 /** @endcond */
3349
3350 /** @cond exclude_from_documentation */
3351 #pragma pack(push, 8)
3352
3353 typedef struct ___itt_track_group
3354 {
3355 __itt_string_handle* name; /*!< Name of the track group */
3356 struct ___itt_track* track; /*!< List of child tracks */
3357 __itt_track_group_type tgtype; /*!< Type of the track group */
3358 int extra1; /*!< Reserved. Must be zero */
3359 void* extra2; /*!< Reserved. Must be zero */
3360 struct ___itt_track_group* next;
3361 } __itt_track_group;
3362
3363 #pragma pack(pop)
3364 /** @endcond */
3365
3366 /**
3367 * @brief Placeholder for custom track types. Currently, "normal" custom track
3368 * is the only available track type.
3369 */
3370 typedef enum ___itt_track_type
3371 {
3372 __itt_track_type_normal = 0
3373 #ifdef INTEL_ITTNOTIFY_API_PRIVATE
3374 , __itt_track_type_queue
3375 #endif /* INTEL_ITTNOTIFY_API_PRIVATE */
3376 } __itt_track_type;
3377
3378 /** @cond exclude_from_documentation */
3379 #pragma pack(push, 8)
3380
3381 typedef struct ___itt_track
3382 {
3383 __itt_string_handle* name; /*!< Name of the track group */
3384 __itt_track_group* group; /*!< Parent group to a track */
3385 __itt_track_type ttype; /*!< Type of the track */
3386 int extra1; /*!< Reserved. Must be zero */
3387 void* extra2; /*!< Reserved. Must be zero */
3388 struct ___itt_track* next;
3389 } __itt_track;
3390
3391 #pragma pack(pop)
3392 /** @endcond */
3393
3394 /**
3395 * @brief Create logical track group.
3396 */
3397 __itt_track_group* ITTAPI __itt_track_group_create(__itt_string_handle* name, __itt_track_group_type track_group_type);
3398
3399 /** @cond exclude_from_documentation */
3400 #ifndef INTEL_NO_MACRO_BODY
3401 #ifndef INTEL_NO_ITTNOTIFY_API
3402 ITT_STUB(ITTAPI, __itt_track_group*, track_group_create, (__itt_string_handle* name, __itt_track_group_type track_group_type))
3403 #define __itt_track_group_create ITTNOTIFY_DATA(track_group_create)
3404 #define __itt_track_group_create_ptr ITTNOTIFY_NAME(track_group_create)
3405 #else /* INTEL_NO_ITTNOTIFY_API */
3406 #define __itt_track_group_create(name) (__itt_track_group*)0
3407 #define __itt_track_group_create_ptr 0
3408 #endif /* INTEL_NO_ITTNOTIFY_API */
3409 #else /* INTEL_NO_MACRO_BODY */
3410 #define __itt_track_group_create_ptr 0
3411 #endif /* INTEL_NO_MACRO_BODY */
3412 /** @endcond */
3413
3414 /**
3415 * @brief Create logical track.
3416 */
3417 __itt_track* ITTAPI __itt_track_create(__itt_track_group* track_group, __itt_string_handle* name, __itt_track_type track_type);
3418
3419 /** @cond exclude_from_documentation */
3420 #ifndef INTEL_NO_MACRO_BODY
3421 #ifndef INTEL_NO_ITTNOTIFY_API
3422 ITT_STUB(ITTAPI, __itt_track*, track_create, (__itt_track_group* track_group,__itt_string_handle* name, __itt_track_type track_type))
3423 #define __itt_track_create ITTNOTIFY_DATA(track_create)
3424 #define __itt_track_create_ptr ITTNOTIFY_NAME(track_create)
3425 #else /* INTEL_NO_ITTNOTIFY_API */
3426 #define __itt_track_create(track_group,name,track_type) (__itt_track*)0
3427 #define __itt_track_create_ptr 0
3428 #endif /* INTEL_NO_ITTNOTIFY_API */
3429 #else /* INTEL_NO_MACRO_BODY */
3430 #define __itt_track_create_ptr 0
3431 #endif /* INTEL_NO_MACRO_BODY */
3432 /** @endcond */
3433
3434 /**
3435 * @brief Set the logical track.
3436 */
3437 void ITTAPI __itt_set_track(__itt_track* track);
3438
3439 /** @cond exclude_from_documentation */
3440 #ifndef INTEL_NO_MACRO_BODY
3441 #ifndef INTEL_NO_ITTNOTIFY_API
3442 ITT_STUBV(ITTAPI, void, set_track, (__itt_track *track))
3443 #define __itt_set_track ITTNOTIFY_VOID(set_track)
3444 #define __itt_set_track_ptr ITTNOTIFY_NAME(set_track)
3445 #else /* INTEL_NO_ITTNOTIFY_API */
3446 #define __itt_set_track(track)
3447 #define __itt_set_track_ptr 0
3448 #endif /* INTEL_NO_ITTNOTIFY_API */
3449 #else /* INTEL_NO_MACRO_BODY */
3450 #define __itt_set_track_ptr 0
3451 #endif /* INTEL_NO_MACRO_BODY */
3452 /** @endcond */
3453
3454 /* ========================================================================== */
3455 /** @cond exclude_from_gpa_documentation */
3456 /**
3457 * @defgroup events Events
3458 * @ingroup public
3459 * Events group
3460 * @{
3461 */
3462 /** @brief user event type */
3463 typedef int __itt_event;
3464
3465 /**
3466 * @brief Create an event notification
3467 * @note name or namelen being null/name and namelen not matching, user event feature not enabled
3468 * @return non-zero event identifier upon success and __itt_err otherwise
3469 */
3470 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3471 __itt_event LIBITTAPI __itt_event_createA(const char *name, int namelen);
3472 __itt_event LIBITTAPI __itt_event_createW(const wchar_t *name, int namelen);
3473 #if defined(UNICODE) || defined(_UNICODE)
3474 # define __itt_event_create __itt_event_createW
3475 # define __itt_event_create_ptr __itt_event_createW_ptr
3476 #else
3477 # define __itt_event_create __itt_event_createA
3478 # define __itt_event_create_ptr __itt_event_createA_ptr
3479 #endif /* UNICODE */
3480 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3481 __itt_event LIBITTAPI __itt_event_create(const char *name, int namelen);
3482 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3483
3484 /** @cond exclude_from_documentation */
3485 #ifndef INTEL_NO_MACRO_BODY
3486 #ifndef INTEL_NO_ITTNOTIFY_API
3487 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3488 ITT_STUB(LIBITTAPI, __itt_event, event_createA, (const char *name, int namelen))
3489 ITT_STUB(LIBITTAPI, __itt_event, event_createW, (const wchar_t *name, int namelen))
3490 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3491 ITT_STUB(LIBITTAPI, __itt_event, event_create, (const char *name, int namelen))
3492 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3493 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3494 #define __itt_event_createA ITTNOTIFY_DATA(event_createA)
3495 #define __itt_event_createA_ptr ITTNOTIFY_NAME(event_createA)
3496 #define __itt_event_createW ITTNOTIFY_DATA(event_createW)
3497 #define __itt_event_createW_ptr ITTNOTIFY_NAME(event_createW)
3498 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3499 #define __itt_event_create ITTNOTIFY_DATA(event_create)
3500 #define __itt_event_create_ptr ITTNOTIFY_NAME(event_create)
3501 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3502 #else /* INTEL_NO_ITTNOTIFY_API */
3503 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3504 #define __itt_event_createA(name, namelen) (__itt_event)0
3505 #define __itt_event_createA_ptr 0
3506 #define __itt_event_createW(name, namelen) (__itt_event)0
3507 #define __itt_event_createW_ptr 0
3508 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3509 #define __itt_event_create(name, namelen) (__itt_event)0
3510 #define __itt_event_create_ptr 0
3511 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3512 #endif /* INTEL_NO_ITTNOTIFY_API */
3513 #else /* INTEL_NO_MACRO_BODY */
3514 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3515 #define __itt_event_createA_ptr 0
3516 #define __itt_event_createW_ptr 0
3517 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3518 #define __itt_event_create_ptr 0
3519 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3520 #endif /* INTEL_NO_MACRO_BODY */
3521 /** @endcond */
3522
3523 /**
3524 * @brief Record an event occurrence.
3525 * @return __itt_err upon failure (invalid event id/user event feature not enabled)
3526 */
3527 int LIBITTAPI __itt_event_start(__itt_event event);
3528
3529 /** @cond exclude_from_documentation */
3530 #ifndef INTEL_NO_MACRO_BODY
3531 #ifndef INTEL_NO_ITTNOTIFY_API
3532 ITT_STUB(LIBITTAPI, int, event_start, (__itt_event event))
3533 #define __itt_event_start ITTNOTIFY_DATA(event_start)
3534 #define __itt_event_start_ptr ITTNOTIFY_NAME(event_start)
3535 #else /* INTEL_NO_ITTNOTIFY_API */
3536 #define __itt_event_start(event) (int)0
3537 #define __itt_event_start_ptr 0
3538 #endif /* INTEL_NO_ITTNOTIFY_API */
3539 #else /* INTEL_NO_MACRO_BODY */
3540 #define __itt_event_start_ptr 0
3541 #endif /* INTEL_NO_MACRO_BODY */
3542 /** @endcond */
3543
3544 /**
3545 * @brief Record an event end occurrence.
3546 * @note It is optional if events do not have durations.
3547 * @return __itt_err upon failure (invalid event id/user event feature not enabled)
3548 */
3549 int LIBITTAPI __itt_event_end(__itt_event event);
3550
3551 /** @cond exclude_from_documentation */
3552 #ifndef INTEL_NO_MACRO_BODY
3553 #ifndef INTEL_NO_ITTNOTIFY_API
3554 ITT_STUB(LIBITTAPI, int, event_end, (__itt_event event))
3555 #define __itt_event_end ITTNOTIFY_DATA(event_end)
3556 #define __itt_event_end_ptr ITTNOTIFY_NAME(event_end)
3557 #else /* INTEL_NO_ITTNOTIFY_API */
3558 #define __itt_event_end(event) (int)0
3559 #define __itt_event_end_ptr 0
3560 #endif /* INTEL_NO_ITTNOTIFY_API */
3561 #else /* INTEL_NO_MACRO_BODY */
3562 #define __itt_event_end_ptr 0
3563 #endif /* INTEL_NO_MACRO_BODY */
3564 /** @endcond */
3565 /** @} events group */
3566
3567
3568 /**
3569 * @defgroup arrays Arrays Visualizer
3570 * @ingroup public
3571 * Visualize arrays
3572 * @{
3573 */
3574
3575 /**
3576 * @enum __itt_av_data_type
3577 * @brief Defines types of arrays data (for C/C++ intrinsic types)
3578 */
3579 typedef enum
3580 {
3581 __itt_e_first = 0,
3582 __itt_e_char = 0, /* 1-byte integer */
3583 __itt_e_uchar, /* 1-byte unsigned integer */
3584 __itt_e_int16, /* 2-byte integer */
3585 __itt_e_uint16, /* 2-byte unsigned integer */
3586 __itt_e_int32, /* 4-byte integer */
3587 __itt_e_uint32, /* 4-byte unsigned integer */
3588 __itt_e_int64, /* 8-byte integer */
3589 __itt_e_uint64, /* 8-byte unsigned integer */
3590 __itt_e_float, /* 4-byte floating */
3591 __itt_e_double, /* 8-byte floating */
3592 __itt_e_last = __itt_e_double
3593 } __itt_av_data_type;
3594
3595 /**
3596 * @brief Save an array data to a file.
3597 * Output format is defined by the file extension. The csv and bmp formats are supported (bmp - for 2-dimensional array only).
3598 * @param[in] data - pointer to the array data
3599 * @param[in] rank - the rank of the array
3600 * @param[in] dimensions - pointer to an array of integers, which specifies the array dimensions.
3601 * The size of dimensions must be equal to the rank
3602 * @param[in] type - the type of the array, specified as one of the __itt_av_data_type values (for intrinsic types)
3603 * @param[in] filePath - the file path; the output format is defined by the file extension
3604 * @param[in] columnOrder - defines how the array is stored in the linear memory.
3605 * It should be 1 for column-major order (e.g. in FORTRAN) or 0 - for row-major order (e.g. in C).
3606 */
3607
3608 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3609 int ITTAPI __itt_av_saveA(void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder);
3610 int ITTAPI __itt_av_saveW(void *data, int rank, const int *dimensions, int type, const wchar_t *filePath, int columnOrder);
3611 #if defined(UNICODE) || defined(_UNICODE)
3612 # define __itt_av_save __itt_av_saveW
3613 # define __itt_av_save_ptr __itt_av_saveW_ptr
3614 #else /* UNICODE */
3615 # define __itt_av_save __itt_av_saveA
3616 # define __itt_av_save_ptr __itt_av_saveA_ptr
3617 #endif /* UNICODE */
3618 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3619 int ITTAPI __itt_av_save(void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder);
3620 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3621
3622 /** @cond exclude_from_documentation */
3623 #ifndef INTEL_NO_MACRO_BODY
3624 #ifndef INTEL_NO_ITTNOTIFY_API
3625 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3626 ITT_STUB(ITTAPI, int, av_saveA, (void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder))
3627 ITT_STUB(ITTAPI, int, av_saveW, (void *data, int rank, const int *dimensions, int type, const wchar_t *filePath, int columnOrder))
3628 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3629 ITT_STUB(ITTAPI, int, av_save, (void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder))
3630 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3631 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3632 #define __itt_av_saveA ITTNOTIFY_DATA(av_saveA)
3633 #define __itt_av_saveA_ptr ITTNOTIFY_NAME(av_saveA)
3634 #define __itt_av_saveW ITTNOTIFY_DATA(av_saveW)
3635 #define __itt_av_saveW_ptr ITTNOTIFY_NAME(av_saveW)
3636 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3637 #define __itt_av_save ITTNOTIFY_DATA(av_save)
3638 #define __itt_av_save_ptr ITTNOTIFY_NAME(av_save)
3639 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3640 #else /* INTEL_NO_ITTNOTIFY_API */
3641 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3642 #define __itt_av_saveA(name)
3643 #define __itt_av_saveA_ptr 0
3644 #define __itt_av_saveW(name)
3645 #define __itt_av_saveW_ptr 0
3646 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3647 #define __itt_av_save(name)
3648 #define __itt_av_save_ptr 0
3649 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3650 #endif /* INTEL_NO_ITTNOTIFY_API */
3651 #else /* INTEL_NO_MACRO_BODY */
3652 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3653 #define __itt_av_saveA_ptr 0
3654 #define __itt_av_saveW_ptr 0
3655 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3656 #define __itt_av_save_ptr 0
3657 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3658 #endif /* INTEL_NO_MACRO_BODY */
3659 /** @endcond */
3660
3661 void ITTAPI __itt_enable_attach(void);
3662
3663 /** @cond exclude_from_documentation */
3664 #ifndef INTEL_NO_MACRO_BODY
3665 #ifndef INTEL_NO_ITTNOTIFY_API
3666 ITT_STUBV(ITTAPI, void, enable_attach, (void))
3667 #define __itt_enable_attach ITTNOTIFY_VOID(enable_attach)
3668 #define __itt_enable_attach_ptr ITTNOTIFY_NAME(enable_attach)
3669 #else /* INTEL_NO_ITTNOTIFY_API */
3670 #define __itt_enable_attach()
3671 #define __itt_enable_attach_ptr 0
3672 #endif /* INTEL_NO_ITTNOTIFY_API */
3673 #else /* INTEL_NO_MACRO_BODY */
3674 #define __itt_enable_attach_ptr 0
3675 #endif /* INTEL_NO_MACRO_BODY */
3676 /** @endcond */
3677
3678 /** @cond exclude_from_gpa_documentation */
3679
3680 /** @} arrays group */
3681
3682 /** @endcond */
3683
3684 /**
3685 * @brief Module load notification
3686 * This API is used to report necessary information in case of bypassing default system loader.
3687 * Notification should be done immediately after this module is loaded to process memory.
3688 * @param[in] start_addr - module start address
3689 * @param[in] end_addr - module end address
3690 * @param[in] path - file system full path to the module
3691 */
3692 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3693 void ITTAPI __itt_module_loadA(void *start_addr, void *end_addr, const char *path);
3694 void ITTAPI __itt_module_loadW(void *start_addr, void *end_addr, const wchar_t *path);
3695 #if defined(UNICODE) || defined(_UNICODE)
3696 # define __itt_module_load __itt_module_loadW
3697 # define __itt_module_load_ptr __itt_module_loadW_ptr
3698 #else /* UNICODE */
3699 # define __itt_module_load __itt_module_loadA
3700 # define __itt_module_load_ptr __itt_module_loadA_ptr
3701 #endif /* UNICODE */
3702 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3703 void ITTAPI __itt_module_load(void *start_addr, void *end_addr, const char *path);
3704 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3705
3706 /** @cond exclude_from_documentation */
3707 #ifndef INTEL_NO_MACRO_BODY
3708 #ifndef INTEL_NO_ITTNOTIFY_API
3709 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3710 ITT_STUB(ITTAPI, void, module_loadA, (void *start_addr, void *end_addr, const char *path))
3711 ITT_STUB(ITTAPI, void, module_loadW, (void *start_addr, void *end_addr, const wchar_t *path))
3712 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3713 ITT_STUB(ITTAPI, void, module_load, (void *start_addr, void *end_addr, const char *path))
3714 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3715 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3716 #define __itt_module_loadA ITTNOTIFY_VOID(module_loadA)
3717 #define __itt_module_loadA_ptr ITTNOTIFY_NAME(module_loadA)
3718 #define __itt_module_loadW ITTNOTIFY_VOID(module_loadW)
3719 #define __itt_module_loadW_ptr ITTNOTIFY_NAME(module_loadW)
3720 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3721 #define __itt_module_load ITTNOTIFY_VOID(module_load)
3722 #define __itt_module_load_ptr ITTNOTIFY_NAME(module_load)
3723 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3724 #else /* INTEL_NO_ITTNOTIFY_API */
3725 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3726 #define __itt_module_loadA(start_addr, end_addr, path)
3727 #define __itt_module_loadA_ptr 0
3728 #define __itt_module_loadW(start_addr, end_addr, path)
3729 #define __itt_module_loadW_ptr 0
3730 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3731 #define __itt_module_load(start_addr, end_addr, path)
3732 #define __itt_module_load_ptr 0
3733 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3734 #endif /* INTEL_NO_ITTNOTIFY_API */
3735 #else /* INTEL_NO_MACRO_BODY */
3736 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3737 #define __itt_module_loadA_ptr 0
3738 #define __itt_module_loadW_ptr 0
3739 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3740 #define __itt_module_load_ptr 0
3741 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3742 #endif /* INTEL_NO_MACRO_BODY */
3743 /** @endcond */
3744
3745 /**
3746 * @brief Report module unload
3747 * This API is used to report necessary information in case of bypassing default system loader.
3748 * Notification should be done just before the module is unloaded from process memory.
3749 * @param[in] addr - base address of loaded module
3750 */
3751 void ITTAPI __itt_module_unload(void *addr);
3752
3753 /** @cond exclude_from_documentation */
3754 #ifndef INTEL_NO_MACRO_BODY
3755 #ifndef INTEL_NO_ITTNOTIFY_API
3756 ITT_STUBV(ITTAPI, void, module_unload, (void *addr))
3757 #define __itt_module_unload ITTNOTIFY_VOID(module_unload)
3758 #define __itt_module_unload_ptr ITTNOTIFY_NAME(module_unload)
3759 #else /* INTEL_NO_ITTNOTIFY_API */
3760 #define __itt_module_unload(addr)
3761 #define __itt_module_unload_ptr 0
3762 #endif /* INTEL_NO_ITTNOTIFY_API */
3763 #else /* INTEL_NO_MACRO_BODY */
3764 #define __itt_module_unload_ptr 0
3765 #endif /* INTEL_NO_MACRO_BODY */
3766 /** @endcond */
3767
3768 /** @cond exclude_from_documentation */
3769 typedef enum
3770 {
3771 __itt_module_type_unknown = 0,
3772 __itt_module_type_elf,
3773 __itt_module_type_coff
3774 } __itt_module_type;
3775 /** @endcond */
3776
3777 /** @cond exclude_from_documentation */
3778 typedef enum
3779 {
3780 itt_section_type_unknown,
3781 itt_section_type_bss, /* notifies that the section contains uninitialized data. These are the relevant section types and the modules that contain them:
3782 * ELF module: SHT_NOBITS section type
3783 * COFF module: IMAGE_SCN_CNT_UNINITIALIZED_DATA section type
3784 */
3785 itt_section_type_data, /* notifies that section contains initialized data. These are the relevant section types and the modules that contain them:
3786 * ELF module: SHT_PROGBITS section type
3787 * COFF module: IMAGE_SCN_CNT_INITIALIZED_DATA section type
3788 */
3789 itt_section_type_text /* notifies that the section contains executable code. These are the relevant section types and the modules that contain them:
3790 * ELF module: SHT_PROGBITS section type
3791 * COFF module: IMAGE_SCN_CNT_CODE section type
3792 */
3793 } __itt_section_type;
3794 /** @endcond */
3795
3796 /**
3797 * @hideinitializer
3798 * @brief bit-mask, detects a section attribute that indicates whether a section can be executed as code:
3799 * These are the relevant section attributes and the modules that contain them:
3800 * ELF module: PF_X section attribute
3801 * COFF module: IMAGE_SCN_MEM_EXECUTE attribute
3802 */
3803 #define __itt_section_exec 0x20000000
3804
3805 /**
3806 * @hideinitializer
3807 * @brief bit-mask, detects a section attribute that indicates whether a section can be read.
3808 * These are the relevant section attributes and the modules that contain them:
3809 * ELF module: PF_R attribute
3810 * COFF module: IMAGE_SCN_MEM_READ attribute
3811 */
3812 #define __itt_section_read 0x40000000
3813
3814 /**
3815 * @hideinitializer
3816 * @brief bit-mask, detects a section attribute that indicates whether a section can be written to.
3817 * These are the relevant section attributes and the modules that contain them:
3818 * ELF module: PF_W attribute
3819 * COFF module: IMAGE_SCN_MEM_WRITE attribute
3820 */
3821 #define __itt_section_write 0x80000000
3822
3823 /** @cond exclude_from_documentation */
3824 #pragma pack(push, 8)
3825
3826 typedef struct ___itt_section_info
3827 {
3828 const char* name; /*!< Section name in UTF8 */
3829 __itt_section_type type; /*!< Section content and semantics description */
3830 size_t flags; /*!< Section bit flags that describe attributes using bit mask
3831 * Zero if disabled, non-zero if enabled
3832 */
3833 void* start_addr; /*!< Section load(relocated) start address */
3834 size_t size; /*!< Section file offset */
3835 size_t file_offset; /*!< Section size */
3836 } __itt_section_info;
3837
3838 #pragma pack(pop)
3839 /** @endcond */
3840
3841 /** @cond exclude_from_documentation */
3842 #pragma pack(push, 8)
3843
3844 typedef struct ___itt_module_object
3845 {
3846 unsigned int version; /*!< API version*/
3847 __itt_id module_id; /*!< Unique identifier. This is unchanged for sections that belong to the same module */
3848 __itt_module_type module_type; /*!< Binary module format */
3849 const char* module_name; /*!< Unique module name or path to module in UTF8
3850 * Contains module name when module_bufer and module_size exist
3851 * Contains module path when module_bufer and module_size absent
3852 * module_name remains the same for the certain module_id
3853 */
3854 void* module_buffer; /*!< Module buffer content */
3855 size_t module_size; /*!< Module buffer size */
3856 /*!< If module_buffer and module_size exist, the binary module is dumped onto the system.
3857 * If module_buffer and module_size do not exist,
3858 * the binary module exists on the system already.
3859 * The module_name parameter contains the path to the module.
3860 */
3861 __itt_section_info* section_array; /*!< Reference to section information */
3862 size_t section_number;
3863 } __itt_module_object;
3864
3865 #pragma pack(pop)
3866 /** @endcond */
3867
3868 /**
3869 * @brief Load module content and its loaded(relocated) sections.
3870 * This API is useful to save a module, or specify its location on the system and report information about loaded sections.
3871 * The target module is saved on the system if module buffer content and size are available.
3872 * If module buffer content and size are unavailable, the module name contains the path to the existing binary module.
3873 * @param[in] module_obj - provides module and section information, along with unique module identifiers (name,module ID)
3874 * which bind the binary module to particular sections.
3875 */
3876 void ITTAPI __itt_module_load_with_sections(__itt_module_object* module_obj);
3877
3878 /** @cond exclude_from_documentation */
3879 #ifndef INTEL_NO_MACRO_BODY
3880 #ifndef INTEL_NO_ITTNOTIFY_API
3881 ITT_STUBV(ITTAPI, void, module_load_with_sections, (__itt_module_object* module_obj))
3882 #define __itt_module_load_with_sections ITTNOTIFY_VOID(module_load_with_sections)
3883 #define __itt_module_load_with_sections_ptr ITTNOTIFY_NAME(module_load_with_sections)
3884 #else /* INTEL_NO_ITTNOTIFY_API */
3885 #define __itt_module_load_with_sections(module_obj)
3886 #define __itt_module_load_with_sections_ptr 0
3887 #endif /* INTEL_NO_ITTNOTIFY_API */
3888 #else /* INTEL_NO_MACRO_BODY */
3889 #define __itt_module_load_with_sections_ptr 0
3890 #endif /* INTEL_NO_MACRO_BODY */
3891 /** @endcond */
3892
3893 /**
3894 * @brief Unload a module and its loaded(relocated) sections.
3895 * This API notifies that the module and its sections were unloaded.
3896 * @param[in] module_obj - provides module and sections information, along with unique module identifiers (name,module ID)
3897 * which bind the binary module to particular sections.
3898 */
3899 void ITTAPI __itt_module_unload_with_sections(__itt_module_object* module_obj);
3900
3901 /** @cond exclude_from_documentation */
3902 #ifndef INTEL_NO_MACRO_BODY
3903 #ifndef INTEL_NO_ITTNOTIFY_API
3904 ITT_STUBV(ITTAPI, void, module_unload_with_sections, (__itt_module_object* module_obj))
3905 #define __itt_module_unload_with_sections ITTNOTIFY_VOID(module_unload_with_sections)
3906 #define __itt_module_unload_with_sections_ptr ITTNOTIFY_NAME(module_unload_with_sections)
3907 #else /* INTEL_NO_ITTNOTIFY_API */
3908 #define __itt_module_unload_with_sections(module_obj)
3909 #define __itt_module_unload_with_sections_ptr 0
3910 #endif /* INTEL_NO_ITTNOTIFY_API */
3911 #else /* INTEL_NO_MACRO_BODY */
3912 #define __itt_module_unload_with_sections_ptr 0
3913 #endif /* INTEL_NO_MACRO_BODY */
3914 /** @endcond */
3915
3916 /** @cond exclude_from_documentation */
3917 #pragma pack(push, 8)
3918
3919 typedef struct ___itt_histogram
3920 {
3921 const __itt_domain* domain; /*!< Domain of the histogram*/
3922 const char* nameA; /*!< Name of the histogram */
3923 #if defined(UNICODE) || defined(_UNICODE)
3924 const wchar_t* nameW;
3925 #else /* UNICODE || _UNICODE */
3926 void* nameW;
3927 #endif /* UNICODE || _UNICODE */
3928 __itt_metadata_type x_type; /*!< Type of the histogram X axis */
3929 __itt_metadata_type y_type; /*!< Type of the histogram Y axis */
3930 int extra1; /*!< Reserved to the runtime */
3931 void* extra2; /*!< Reserved to the runtime */
3932 struct ___itt_histogram* next;
3933 } __itt_histogram;
3934
3935 #pragma pack(pop)
3936 /** @endcond */
3937
3938 /**
3939 * @brief Create a typed histogram instance with given name/domain.
3940 * @param[in] domain The domain controlling the call.
3941 * @param[in] name The name of the histogram.
3942 * @param[in] x_type The type of the X axis in histogram (may be 0 to calculate batch statistics).
3943 * @param[in] y_type The type of the Y axis in histogram.
3944 */
3945 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3946 __itt_histogram* ITTAPI __itt_histogram_createA(const __itt_domain* domain, const char* name, __itt_metadata_type x_type, __itt_metadata_type y_type);
3947 __itt_histogram* ITTAPI __itt_histogram_createW(const __itt_domain* domain, const wchar_t* name, __itt_metadata_type x_type, __itt_metadata_type y_type);
3948 #if defined(UNICODE) || defined(_UNICODE)
3949 # define __itt_histogram_create __itt_histogram_createW
3950 # define __itt_histogram_create_ptr __itt_histogram_createW_ptr
3951 #else /* UNICODE */
3952 # define __itt_histogram_create __itt_histogram_createA
3953 # define __itt_histogram_create_ptr __itt_histogram_createA_ptr
3954 #endif /* UNICODE */
3955 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3956 __itt_histogram* ITTAPI __itt_histogram_create(const __itt_domain* domain, const char* name, __itt_metadata_type x_type, __itt_metadata_type y_type);
3957 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3958
3959 /** @cond exclude_from_documentation */
3960 #ifndef INTEL_NO_MACRO_BODY
3961 #ifndef INTEL_NO_ITTNOTIFY_API
3962 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3963 ITT_STUB(ITTAPI, __itt_histogram*, histogram_createA, (const __itt_domain* domain, const char* name, __itt_metadata_type x_type, __itt_metadata_type y_type))
3964 ITT_STUB(ITTAPI, __itt_histogram*, histogram_createW, (const __itt_domain* domain, const wchar_t* name, __itt_metadata_type x_type, __itt_metadata_type y_type))
3965 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3966 ITT_STUB(ITTAPI, __itt_histogram*, histogram_create, (const __itt_domain* domain, const char* name, __itt_metadata_type x_type, __itt_metadata_type y_type))
3967 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3968 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3969 #define __itt_histogram_createA ITTNOTIFY_DATA(histogram_createA)
3970 #define __itt_histogram_createA_ptr ITTNOTIFY_NAME(histogram_createA)
3971 #define __itt_histogram_createW ITTNOTIFY_DATA(histogram_createW)
3972 #define __itt_histogram_createW_ptr ITTNOTIFY_NAME(histogram_createW)
3973 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3974 #define __itt_histogram_create ITTNOTIFY_DATA(histogram_create)
3975 #define __itt_histogram_create_ptr ITTNOTIFY_NAME(histogram_create)
3976 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3977 #else /* INTEL_NO_ITTNOTIFY_API */
3978 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3979 #define __itt_histogram_createA(domain, name, x_type, y_type) (__itt_histogram*)0
3980 #define __itt_histogram_createA_ptr 0
3981 #define __itt_histogram_createW(domain, name, x_type, y_type) (__itt_histogram*)0
3982 #define __itt_histogram_createW_ptr 0
3983 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3984 #define __itt_histogram_create(domain, name, x_type, y_type) (__itt_histogram*)0
3985 #define __itt_histogram_create_ptr 0
3986 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3987 #endif /* INTEL_NO_ITTNOTIFY_API */
3988 #else /* INTEL_NO_MACRO_BODY */
3989 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3990 #define __itt_histogram_createA_ptr 0
3991 #define __itt_histogram_createW_ptr 0
3992 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3993 #define __itt_histogram_create_ptr 0
3994 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3995 #endif /* INTEL_NO_MACRO_BODY */
3996 /** @endcond */
3997
3998 /**
3999 * @brief Submit statistics for a histogram instance.
4000 * @param[in] histogram Pointer to the histogram instance to which the histogram statistic is to be dumped.
4001 * @param[in] length The number of elements in dumped axis data array.
4002 * @param[in] x_data The X axis dumped data itself (may be NULL to calculate batch statistics).
4003 * @param[in] y_data The Y axis dumped data itself.
4004 */
4005 void ITTAPI __itt_histogram_submit(__itt_histogram* histogram, size_t length, void* x_data, void* y_data);
4006
4007 /** @cond exclude_from_documentation */
4008 #ifndef INTEL_NO_MACRO_BODY
4009 #ifndef INTEL_NO_ITTNOTIFY_API
4010 ITT_STUBV(ITTAPI, void, histogram_submit, (__itt_histogram* histogram, size_t length, void* x_data, void* y_data))
4011 #define __itt_histogram_submit ITTNOTIFY_VOID(histogram_submit)
4012 #define __itt_histogram_submit_ptr ITTNOTIFY_NAME(histogram_submit)
4013 #else /* INTEL_NO_ITTNOTIFY_API */
4014 #define __itt_histogram_submit(histogram, length, x_data, y_data)
4015 #define __itt_histogram_submit_ptr 0
4016 #endif /* INTEL_NO_ITTNOTIFY_API */
4017 #else /* INTEL_NO_MACRO_BODY */
4018 #define __itt_histogram_submit_ptr 0
4019 #endif /* INTEL_NO_MACRO_BODY */
4020
4021 /**
4022 * @brief function allows to obtain the current collection state at the moment
4023 * @return collection state as a enum __itt_collection_state
4024 */
4025 __itt_collection_state __itt_get_collection_state(void);
4026
4027 /**
4028 * @brief function releases resources allocated by ITT API static part
4029 * this API should be called from the library destructor
4030 * @return void
4031 */
4032 void __itt_release_resources(void);
4033 /** @endcond */
4034
4035 /**
4036 * @brief Create a typed counter with given domain pointer, string name and counter type
4037 */
4038 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4039 __itt_counter ITTAPI __itt_counter_createA_v3(const __itt_domain* domain, const char* name, __itt_metadata_type type);
4040 __itt_counter ITTAPI __itt_counter_createW_v3(const __itt_domain* domain, const wchar_t* name, __itt_metadata_type type);
4041 #if defined(UNICODE) || defined(_UNICODE)
4042 # define __itt_counter_create_v3 __itt_counter_createW_v3
4043 # define __itt_counter_create_v3_ptr __itt_counter_createW_v3_ptr
4044 #else /* UNICODE */
4045 # define __itt_counter_create_v3 __itt_counter_createA_v3
4046 # define __itt_counter_create_v3_ptr __itt_counter_createA_v3_ptr
4047 #endif /* UNICODE */
4048 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4049 __itt_counter ITTAPI __itt_counter_create_v3(const __itt_domain* domain, const char* name, __itt_metadata_type type);
4050 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4051
4052 #ifndef INTEL_NO_MACRO_BODY
4053 #ifndef INTEL_NO_ITTNOTIFY_API
4054 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4055 ITT_STUB(ITTAPI, __itt_counter, counter_createA_v3, (const __itt_domain* domain, const char* name, __itt_metadata_type type))
4056 ITT_STUB(ITTAPI, __itt_counter, counter_createW_v3, (const __itt_domain* domain, const wchar_t* name, __itt_metadata_type type))
4057 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4058 ITT_STUB(ITTAPI, __itt_counter, counter_create_v3, (const __itt_domain* domain, const char* name, __itt_metadata_type type))
4059 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4060 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4061 #define __itt_counter_createA_v3 ITTNOTIFY_DATA(counter_createA_v3)
4062 #define __itt_counter_createA_v3_ptr ITTNOTIFY_NAME(counter_createA_v3)
4063 #define __itt_counter_createW_v3 ITTNOTIFY_DATA(counter_createW_v3)
4064 #define __itt_counter_createW_v3_ptr ITTNOTIFY_NAME(counter_createW_v3)
4065 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4066 #define __itt_counter_create_v3 ITTNOTIFY_DATA(counter_create_v3)
4067 #define __itt_counter_create_v3_ptr ITTNOTIFY_NAME(counter_create_v3)
4068 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4069 #else /* INTEL_NO_ITTNOTIFY_API */
4070 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4071 #define __itt_counter_createA_v3(domain, name, type) (__itt_counter)0
4072 #define __itt_counter_createA_v3_ptr 0
4073 #define __itt_counter_createW_v3(domain, name, type) (__itt_counter)0
4074 #define __itt_counter_create_typedW_ptr 0
4075 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4076 #define __itt_counter_create_v3(domain, name, type) (__itt_counter)0
4077 #define __itt_counter_create_v3_ptr 0
4078 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4079 #endif /* INTEL_NO_ITTNOTIFY_API */
4080 #else /* INTEL_NO_MACRO_BODY */
4081 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4082 #define __itt_counter_createA_v3_ptr 0
4083 #define __itt_counter_createW_v3_ptr 0
4084 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4085 #define __itt_counter_create_v3_ptr 0
4086 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4087 #endif /* INTEL_NO_MACRO_BODY */
4088 /** @endcond */
4089
4090 /**
4091 * @brief Set the counter value api
4092 */
4093 void ITTAPI __itt_counter_set_value_v3(__itt_counter counter, void *value_ptr);
4094
4095 #ifndef INTEL_NO_MACRO_BODY
4096 #ifndef INTEL_NO_ITTNOTIFY_API
4097 ITT_STUBV(ITTAPI, void, counter_set_value_v3, (__itt_counter counter, void *value_ptr))
4098 #define __itt_counter_set_value_v3 ITTNOTIFY_VOID(counter_set_value_v3)
4099 #define __itt_counter_set_value_v3_ptr ITTNOTIFY_NAME(counter_set_value_v3)
4100 #else /* INTEL_NO_ITTNOTIFY_API */
4101 #define __itt_counter_set_value_v3(counter, value_ptr)
4102 #define __itt_counter_set_value_v3_ptr 0
4103 #endif /* INTEL_NO_ITTNOTIFY_API */
4104 #else /* INTEL_NO_MACRO_BODY */
4105 #define __itt_counter_set_value_v3_ptr 0
4106 #endif /* INTEL_NO_MACRO_BODY */
4107 /** @endcond */
4108
4109 /**
4110 * @brief describes the type of context metadata
4111 */
4112 typedef enum {
4113 __itt_context_unknown = 0, /*!< Undefined type */
4114 __itt_context_nameA, /*!< ASCII string char* type */
4115 __itt_context_nameW, /*!< Unicode string wchar_t* type */
4116 __itt_context_deviceA, /*!< ASCII string char* type */
4117 __itt_context_deviceW, /*!< Unicode string wchar_t* type */
4118 __itt_context_unitsA, /*!< ASCII string char* type */
4119 __itt_context_unitsW, /*!< Unicode string wchar_t* type */
4120 __itt_context_pci_addrA, /*!< ASCII string char* type */
4121 __itt_context_pci_addrW, /*!< Unicode string wchar_t* type */
4122 __itt_context_tid, /*!< Unsigned 64-bit integer type */
4123 __itt_context_max_val, /*!< Unsigned 64-bit integer type */
4124 __itt_context_bandwidth_flag, /*!< Unsigned 64-bit integer type */
4125 __itt_context_latency_flag, /*!< Unsigned 64-bit integer type */
4126 __itt_context_occupancy_flag, /*!< Unsigned 64-bit integer type */
4127 __itt_context_on_thread_flag, /*!< Unsigned 64-bit integer type */
4128 __itt_context_is_abs_val_flag, /*!< Unsigned 64-bit integer type */
4129 __itt_context_cpu_instructions_flag, /*!< Unsigned 64-bit integer type */
4130 __itt_context_cpu_cycles_flag /*!< Unsigned 64-bit integer type */
4131 } __itt_context_type;
4132
4133 #if defined(UNICODE) || defined(_UNICODE)
4134 # define __itt_context_name __itt_context_nameW
4135 # define __itt_context_device __itt_context_deviceW
4136 # define __itt_context_units __itt_context_unitsW
4137 # define __itt_context_pci_addr __itt_context_pci_addrW
4138 #else /* UNICODE || _UNICODE */
4139 # define __itt_context_name __itt_context_nameA
4140 # define __itt_context_device __itt_context_deviceA
4141 # define __itt_context_units __itt_context_unitsA
4142 # define __itt_context_pci_addr __itt_context_pci_addrA
4143 #endif /* UNICODE || _UNICODE */
4144
4145 /** @cond exclude_from_documentation */
4146 #pragma pack(push, 8)
4147
4148 typedef struct ___itt_context_metadata
4149 {
4150 __itt_context_type type; /*!< Type of the context metadata value */
4151 void* value; /*!< Pointer to context metadata value itself */
4152 } __itt_context_metadata;
4153
4154 #pragma pack(pop)
4155 /** @endcond */
4156
4157 /** @cond exclude_from_documentation */
4158 #pragma pack(push, 8)
4159
4160 typedef struct ___itt_counter_metadata
4161 {
4162 __itt_counter counter; /*!< Associated context metadata counter */
4163 __itt_context_type type; /*!< Type of the context metadata value */
4164 const char* str_valueA; /*!< String context metadata value */
4165 #if defined(UNICODE) || defined(_UNICODE)
4166 const wchar_t* str_valueW;
4167 #else /* UNICODE || _UNICODE */
4168 void* str_valueW;
4169 #endif /* UNICODE || _UNICODE */
4170 unsigned long long value; /*!< Numeric context metadata value */
4171 int extra1; /*!< Reserved to the runtime */
4172 void* extra2; /*!< Reserved to the runtime */
4173 struct ___itt_counter_metadata* next;
4174 } __itt_counter_metadata;
4175
4176 #pragma pack(pop)
4177 /** @endcond */
4178
4179 /**
4180 * @brief Bind context metadata to counter instance
4181 * @param[in] counter Pointer to the counter instance to which the context metadata is to be associated.
4182 * @param[in] length The number of elements in context metadata array.
4183 * @param[in] metadata The context metadata itself.
4184 */
4185 void ITTAPI __itt_bind_context_metadata_to_counter(__itt_counter counter, size_t length, __itt_context_metadata* metadata);
4186
4187 /** @cond exclude_from_documentation */
4188 #ifndef INTEL_NO_MACRO_BODY
4189 #ifndef INTEL_NO_ITTNOTIFY_API
4190 ITT_STUBV(ITTAPI, void, bind_context_metadata_to_counter, (__itt_counter counter, size_t length, __itt_context_metadata* metadata))
4191 #define __itt_bind_context_metadata_to_counter ITTNOTIFY_VOID(bind_context_metadata_to_counter)
4192 #define __itt_bind_context_metadata_to_counter_ptr ITTNOTIFY_NAME(bind_context_metadata_to_counter)
4193 #else /* INTEL_NO_ITTNOTIFY_API */
4194 #define __itt_bind_context_metadata_to_counter(counter, length, metadata)
4195 #define __itt_bind_context_metadata_to_counter_ptr 0
4196 #endif /* INTEL_NO_ITTNOTIFY_API */
4197 #else /* INTEL_NO_MACRO_BODY */
4198 #define __itt_bind_context_metadata_to_counter_ptr 0
4199 #endif /* INTEL_NO_MACRO_BODY */
4200 /** @endcond */
4201
4202 #ifdef __cplusplus
4203 }
4204 #endif /* __cplusplus */
4205
4206 #endif /* _ITTNOTIFY_H_ */
4207
4208 #ifdef INTEL_ITTNOTIFY_API_PRIVATE
4209
4210 #ifndef _ITTNOTIFY_PRIVATE_
4211 #define _ITTNOTIFY_PRIVATE_
4212
4213 #ifdef __cplusplus
4214 extern "C" {
4215 #endif /* __cplusplus */
4216
4217 /**
4218 * @ingroup clockdomain
4219 * @brief Begin an overlapped task instance.
4220 * @param[in] domain The domain for this task
4221 * @param[in] clock_domain The clock domain controlling the execution of this call.
4222 * @param[in] timestamp The user defined timestamp.
4223 * @param[in] taskid The identifier for this task instance, *cannot* be __itt_null.
4224 * @param[in] parentid The parent of this task, or __itt_null.
4225 * @param[in] name The name of this task.
4226 */
4227 void ITTAPI __itt_task_begin_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
4228
4229 /**
4230 * @ingroup clockdomain
4231 * @brief End an overlapped task instance.
4232 * @param[in] domain The domain for this task
4233 * @param[in] clock_domain The clock domain controlling the execution of this call.
4234 * @param[in] timestamp The user defined timestamp.
4235 * @param[in] taskid Explicit ID of finished task
4236 */
4237 void ITTAPI __itt_task_end_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid);
4238
4239 /** @cond exclude_from_documentation */
4240 #ifndef INTEL_NO_MACRO_BODY
4241 #ifndef INTEL_NO_ITTNOTIFY_API
4242 ITT_STUBV(ITTAPI, void, task_begin_overlapped_ex, (const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name))
4243 ITT_STUBV(ITTAPI, void, task_end_overlapped_ex, (const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid))
4244 #define __itt_task_begin_overlapped_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(task_begin_overlapped_ex,d,x,y,z,a,b)
4245 #define __itt_task_begin_overlapped_ex_ptr ITTNOTIFY_NAME(task_begin_overlapped_ex)
4246 #define __itt_task_end_overlapped_ex(d,x,y,z) ITTNOTIFY_VOID_D3(task_end_overlapped_ex,d,x,y,z)
4247 #define __itt_task_end_overlapped_ex_ptr ITTNOTIFY_NAME(task_end_overlapped_ex)
4248 #else /* INTEL_NO_ITTNOTIFY_API */
4249 #define __itt_task_begin_overlapped_ex(domain,clock_domain,timestamp,taskid,parentid,name)
4250 #define __itt_task_begin_overlapped_ex_ptr 0
4251 #define __itt_task_end_overlapped_ex(domain,clock_domain,timestamp,taskid)
4252 #define __itt_task_end_overlapped_ex_ptr 0
4253 #endif /* INTEL_NO_ITTNOTIFY_API */
4254 #else /* INTEL_NO_MACRO_BODY */
4255 #define __itt_task_begin_overlapped_ex_ptr 0
4256 #define __itt_task_end_overlapped_ptr 0
4257 #define __itt_task_end_overlapped_ex_ptr 0
4258 #endif /* INTEL_NO_MACRO_BODY */
4259 /** @endcond */
4260
4261 /**
4262 * @defgroup makrs_internal Marks
4263 * @ingroup internal
4264 * Marks group
4265 * @warning Internal API:
4266 * - It is not shipped to outside of Intel
4267 * - It is delivered to internal Intel teams using e-mail or SVN access only
4268 * @{
4269 */
4270 /** @brief user mark type */
4271 typedef int __itt_mark_type;
4272
4273 /**
4274 * @brief Creates a user mark type with the specified name using char or Unicode string.
4275 * @param[in] name - name of mark to create
4276 * @return Returns a handle to the mark type
4277 */
4278 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4279 __itt_mark_type ITTAPI __itt_mark_createA(const char *name);
4280 __itt_mark_type ITTAPI __itt_mark_createW(const wchar_t *name);
4281 #if defined(UNICODE) || defined(_UNICODE)
4282 # define __itt_mark_create __itt_mark_createW
4283 # define __itt_mark_create_ptr __itt_mark_createW_ptr
4284 #else /* UNICODE */
4285 # define __itt_mark_create __itt_mark_createA
4286 # define __itt_mark_create_ptr __itt_mark_createA_ptr
4287 #endif /* UNICODE */
4288 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4289 __itt_mark_type ITTAPI __itt_mark_create(const char *name);
4290 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4291
4292 /** @cond exclude_from_documentation */
4293 #ifndef INTEL_NO_MACRO_BODY
4294 #ifndef INTEL_NO_ITTNOTIFY_API
4295 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4296 ITT_STUB(ITTAPI, __itt_mark_type, mark_createA, (const char *name))
4297 ITT_STUB(ITTAPI, __itt_mark_type, mark_createW, (const wchar_t *name))
4298 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4299 ITT_STUB(ITTAPI, __itt_mark_type, mark_create, (const char *name))
4300 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4301 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4302 #define __itt_mark_createA ITTNOTIFY_DATA(mark_createA)
4303 #define __itt_mark_createA_ptr ITTNOTIFY_NAME(mark_createA)
4304 #define __itt_mark_createW ITTNOTIFY_DATA(mark_createW)
4305 #define __itt_mark_createW_ptr ITTNOTIFY_NAME(mark_createW)
4306 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4307 #define __itt_mark_create ITTNOTIFY_DATA(mark_create)
4308 #define __itt_mark_create_ptr ITTNOTIFY_NAME(mark_create)
4309 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4310 #else /* INTEL_NO_ITTNOTIFY_API */
4311 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4312 #define __itt_mark_createA(name) (__itt_mark_type)0
4313 #define __itt_mark_createA_ptr 0
4314 #define __itt_mark_createW(name) (__itt_mark_type)0
4315 #define __itt_mark_createW_ptr 0
4316 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4317 #define __itt_mark_create(name) (__itt_mark_type)0
4318 #define __itt_mark_create_ptr 0
4319 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4320 #endif /* INTEL_NO_ITTNOTIFY_API */
4321 #else /* INTEL_NO_MACRO_BODY */
4322 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4323 #define __itt_mark_createA_ptr 0
4324 #define __itt_mark_createW_ptr 0
4325 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4326 #define __itt_mark_create_ptr 0
4327 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4328 #endif /* INTEL_NO_MACRO_BODY */
4329 /** @endcond */
4330
4331 /**
4332 * @brief Creates a "discrete" user mark type of the specified type and an optional parameter using char or Unicode string.
4333 *
4334 * - The mark of "discrete" type is placed to collection results in case of success. It appears in overtime view(s) as a special tick sign.
4335 * - The call is "synchronous" - function returns after mark is actually added to results.
4336 * - This function is useful, for example, to mark different phases of application
4337 * (beginning of the next mark automatically meand end of current region).
4338 * - Can be used together with "continuous" marks (see below) at the same collection session
4339 * @param[in] mt - mark, created by __itt_mark_create(const char* name) function
4340 * @param[in] parameter - string parameter of mark
4341 * @return Returns zero value in case of success, non-zero value otherwise.
4342 */
4343 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4344 int ITTAPI __itt_markA(__itt_mark_type mt, const char *parameter);
4345 int ITTAPI __itt_markW(__itt_mark_type mt, const wchar_t *parameter);
4346 #if defined(UNICODE) || defined(_UNICODE)
4347 # define __itt_mark __itt_markW
4348 # define __itt_mark_ptr __itt_markW_ptr
4349 #else /* UNICODE */
4350 # define __itt_mark __itt_markA
4351 # define __itt_mark_ptr __itt_markA_ptr
4352 #endif /* UNICODE */
4353 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4354 int ITTAPI __itt_mark(__itt_mark_type mt, const char *parameter);
4355 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4356
4357 /** @cond exclude_from_documentation */
4358 #ifndef INTEL_NO_MACRO_BODY
4359 #ifndef INTEL_NO_ITTNOTIFY_API
4360 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4361 ITT_STUB(ITTAPI, int, markA, (__itt_mark_type mt, const char *parameter))
4362 ITT_STUB(ITTAPI, int, markW, (__itt_mark_type mt, const wchar_t *parameter))
4363 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4364 ITT_STUB(ITTAPI, int, mark, (__itt_mark_type mt, const char *parameter))
4365 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4366 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4367 #define __itt_markA ITTNOTIFY_DATA(markA)
4368 #define __itt_markA_ptr ITTNOTIFY_NAME(markA)
4369 #define __itt_markW ITTNOTIFY_DATA(markW)
4370 #define __itt_markW_ptr ITTNOTIFY_NAME(markW)
4371 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4372 #define __itt_mark ITTNOTIFY_DATA(mark)
4373 #define __itt_mark_ptr ITTNOTIFY_NAME(mark)
4374 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4375 #else /* INTEL_NO_ITTNOTIFY_API */
4376 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4377 #define __itt_markA(mt, parameter) (int)0
4378 #define __itt_markA_ptr 0
4379 #define __itt_markW(mt, parameter) (int)0
4380 #define __itt_markW_ptr 0
4381 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4382 #define __itt_mark(mt, parameter) (int)0
4383 #define __itt_mark_ptr 0
4384 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4385 #endif /* INTEL_NO_ITTNOTIFY_API */
4386 #else /* INTEL_NO_MACRO_BODY */
4387 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4388 #define __itt_markA_ptr 0
4389 #define __itt_markW_ptr 0
4390 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4391 #define __itt_mark_ptr 0
4392 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4393 #endif /* INTEL_NO_MACRO_BODY */
4394 /** @endcond */
4395
4396 /**
4397 * @brief Use this if necessary to create a "discrete" user event type (mark) for process
4398 * rather then for one thread
4399 * @see int __itt_mark(__itt_mark_type mt, const char* parameter);
4400 */
4401 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4402 int ITTAPI __itt_mark_globalA(__itt_mark_type mt, const char *parameter);
4403 int ITTAPI __itt_mark_globalW(__itt_mark_type mt, const wchar_t *parameter);
4404 #if defined(UNICODE) || defined(_UNICODE)
4405 # define __itt_mark_global __itt_mark_globalW
4406 # define __itt_mark_global_ptr __itt_mark_globalW_ptr
4407 #else /* UNICODE */
4408 # define __itt_mark_global __itt_mark_globalA
4409 # define __itt_mark_global_ptr __itt_mark_globalA_ptr
4410 #endif /* UNICODE */
4411 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4412 int ITTAPI __itt_mark_global(__itt_mark_type mt, const char *parameter);
4413 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4414
4415 /** @cond exclude_from_documentation */
4416 #ifndef INTEL_NO_MACRO_BODY
4417 #ifndef INTEL_NO_ITTNOTIFY_API
4418 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4419 ITT_STUB(ITTAPI, int, mark_globalA, (__itt_mark_type mt, const char *parameter))
4420 ITT_STUB(ITTAPI, int, mark_globalW, (__itt_mark_type mt, const wchar_t *parameter))
4421 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4422 ITT_STUB(ITTAPI, int, mark_global, (__itt_mark_type mt, const char *parameter))
4423 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4424 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4425 #define __itt_mark_globalA ITTNOTIFY_DATA(mark_globalA)
4426 #define __itt_mark_globalA_ptr ITTNOTIFY_NAME(mark_globalA)
4427 #define __itt_mark_globalW ITTNOTIFY_DATA(mark_globalW)
4428 #define __itt_mark_globalW_ptr ITTNOTIFY_NAME(mark_globalW)
4429 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4430 #define __itt_mark_global ITTNOTIFY_DATA(mark_global)
4431 #define __itt_mark_global_ptr ITTNOTIFY_NAME(mark_global)
4432 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4433 #else /* INTEL_NO_ITTNOTIFY_API */
4434 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4435 #define __itt_mark_globalA(mt, parameter) (int)0
4436 #define __itt_mark_globalA_ptr 0
4437 #define __itt_mark_globalW(mt, parameter) (int)0
4438 #define __itt_mark_globalW_ptr 0
4439 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4440 #define __itt_mark_global(mt, parameter) (int)0
4441 #define __itt_mark_global_ptr 0
4442 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4443 #endif /* INTEL_NO_ITTNOTIFY_API */
4444 #else /* INTEL_NO_MACRO_BODY */
4445 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4446 #define __itt_mark_globalA_ptr 0
4447 #define __itt_mark_globalW_ptr 0
4448 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4449 #define __itt_mark_global_ptr 0
4450 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4451 #endif /* INTEL_NO_MACRO_BODY */
4452 /** @endcond */
4453
4454 /**
4455 * @brief Creates an "end" point for "continuous" mark with specified name.
4456 *
4457 * - Returns zero value in case of success, non-zero value otherwise.
4458 * Also returns non-zero value when preceding "begin" point for the
4459 * mark with the same name failed to be created or not created.
4460 * - The mark of "continuous" type is placed to collection results in
4461 * case of success. It appears in overtime view(s) as a special tick
4462 * sign (different from "discrete" mark) together with line from
4463 * corresponding "begin" mark to "end" mark.
4464 * @note Continuous marks can overlap and be nested inside each other.
4465 * Discrete mark can be nested inside marked region
4466 * @param[in] mt - mark, created by __itt_mark_create(const char* name) function
4467 * @return Returns zero value in case of success, non-zero value otherwise.
4468 */
4469 int ITTAPI __itt_mark_off(__itt_mark_type mt);
4470
4471 /** @cond exclude_from_documentation */
4472 #ifndef INTEL_NO_MACRO_BODY
4473 #ifndef INTEL_NO_ITTNOTIFY_API
4474 ITT_STUB(ITTAPI, int, mark_off, (__itt_mark_type mt))
4475 #define __itt_mark_off ITTNOTIFY_DATA(mark_off)
4476 #define __itt_mark_off_ptr ITTNOTIFY_NAME(mark_off)
4477 #else /* INTEL_NO_ITTNOTIFY_API */
4478 #define __itt_mark_off(mt) (int)0
4479 #define __itt_mark_off_ptr 0
4480 #endif /* INTEL_NO_ITTNOTIFY_API */
4481 #else /* INTEL_NO_MACRO_BODY */
4482 #define __itt_mark_off_ptr 0
4483 #endif /* INTEL_NO_MACRO_BODY */
4484 /** @endcond */
4485
4486 /**
4487 * @brief Use this if necessary to create an "end" point for mark of process
4488 * @see int __itt_mark_off(__itt_mark_type mt);
4489 */
4490 int ITTAPI __itt_mark_global_off(__itt_mark_type mt);
4491
4492 /** @cond exclude_from_documentation */
4493 #ifndef INTEL_NO_MACRO_BODY
4494 #ifndef INTEL_NO_ITTNOTIFY_API
4495 ITT_STUB(ITTAPI, int, mark_global_off, (__itt_mark_type mt))
4496 #define __itt_mark_global_off ITTNOTIFY_DATA(mark_global_off)
4497 #define __itt_mark_global_off_ptr ITTNOTIFY_NAME(mark_global_off)
4498 #else /* INTEL_NO_ITTNOTIFY_API */
4499 #define __itt_mark_global_off(mt) (int)0
4500 #define __itt_mark_global_off_ptr 0
4501 #endif /* INTEL_NO_ITTNOTIFY_API */
4502 #else /* INTEL_NO_MACRO_BODY */
4503 #define __itt_mark_global_off_ptr 0
4504 #endif /* INTEL_NO_MACRO_BODY */
4505 /** @endcond */
4506 /** @} marks group */
4507
4508 /**
4509 * @defgroup counters_internal Counters
4510 * @ingroup internal
4511 * Counters group
4512 * @{
4513 */
4514
4515
4516 /**
4517 * @defgroup stitch Stack Stitching
4518 * @ingroup internal
4519 * Stack Stitching group
4520 * @{
4521 */
4522 /**
4523 * @brief opaque structure for counter identification
4524 */
4525 typedef struct ___itt_caller *__itt_caller;
4526
4527 /**
4528 * @brief Create the stitch point e.g. a point in call stack where other stacks should be stitched to.
4529 * The function returns a unique identifier which is used to match the cut points with corresponding stitch points.
4530 */
4531 __itt_caller ITTAPI __itt_stack_caller_create(void);
4532
4533 /** @cond exclude_from_documentation */
4534 #ifndef INTEL_NO_MACRO_BODY
4535 #ifndef INTEL_NO_ITTNOTIFY_API
4536 ITT_STUB(ITTAPI, __itt_caller, stack_caller_create, (void))
4537 #define __itt_stack_caller_create ITTNOTIFY_DATA(stack_caller_create)
4538 #define __itt_stack_caller_create_ptr ITTNOTIFY_NAME(stack_caller_create)
4539 #else /* INTEL_NO_ITTNOTIFY_API */
4540 #define __itt_stack_caller_create() (__itt_caller)0
4541 #define __itt_stack_caller_create_ptr 0
4542 #endif /* INTEL_NO_ITTNOTIFY_API */
4543 #else /* INTEL_NO_MACRO_BODY */
4544 #define __itt_stack_caller_create_ptr 0
4545 #endif /* INTEL_NO_MACRO_BODY */
4546 /** @endcond */
4547
4548 /**
4549 * @brief Destroy the information about stitch point identified by the pointer previously returned by __itt_stack_caller_create()
4550 */
4551 void ITTAPI __itt_stack_caller_destroy(__itt_caller id);
4552
4553 /** @cond exclude_from_documentation */
4554 #ifndef INTEL_NO_MACRO_BODY
4555 #ifndef INTEL_NO_ITTNOTIFY_API
4556 ITT_STUBV(ITTAPI, void, stack_caller_destroy, (__itt_caller id))
4557 #define __itt_stack_caller_destroy ITTNOTIFY_VOID(stack_caller_destroy)
4558 #define __itt_stack_caller_destroy_ptr ITTNOTIFY_NAME(stack_caller_destroy)
4559 #else /* INTEL_NO_ITTNOTIFY_API */
4560 #define __itt_stack_caller_destroy(id)
4561 #define __itt_stack_caller_destroy_ptr 0
4562 #endif /* INTEL_NO_ITTNOTIFY_API */
4563 #else /* INTEL_NO_MACRO_BODY */
4564 #define __itt_stack_caller_destroy_ptr 0
4565 #endif /* INTEL_NO_MACRO_BODY */
4566 /** @endcond */
4567
4568 /**
4569 * @brief Sets the cut point. Stack from each event which occurs after this call will be cut
4570 * at the same stack level the function was called and stitched to the corresponding stitch point.
4571 */
4572 void ITTAPI __itt_stack_callee_enter(__itt_caller id);
4573
4574 /** @cond exclude_from_documentation */
4575 #ifndef INTEL_NO_MACRO_BODY
4576 #ifndef INTEL_NO_ITTNOTIFY_API
4577 ITT_STUBV(ITTAPI, void, stack_callee_enter, (__itt_caller id))
4578 #define __itt_stack_callee_enter ITTNOTIFY_VOID(stack_callee_enter)
4579 #define __itt_stack_callee_enter_ptr ITTNOTIFY_NAME(stack_callee_enter)
4580 #else /* INTEL_NO_ITTNOTIFY_API */
4581 #define __itt_stack_callee_enter(id)
4582 #define __itt_stack_callee_enter_ptr 0
4583 #endif /* INTEL_NO_ITTNOTIFY_API */
4584 #else /* INTEL_NO_MACRO_BODY */
4585 #define __itt_stack_callee_enter_ptr 0
4586 #endif /* INTEL_NO_MACRO_BODY */
4587 /** @endcond */
4588
4589 /**
4590 * @brief This function eliminates the cut point which was set by latest __itt_stack_callee_enter().
4591 */
4592 void ITTAPI __itt_stack_callee_leave(__itt_caller id);
4593
4594 /** @cond exclude_from_documentation */
4595 #ifndef INTEL_NO_MACRO_BODY
4596 #ifndef INTEL_NO_ITTNOTIFY_API
4597 ITT_STUBV(ITTAPI, void, stack_callee_leave, (__itt_caller id))
4598 #define __itt_stack_callee_leave ITTNOTIFY_VOID(stack_callee_leave)
4599 #define __itt_stack_callee_leave_ptr ITTNOTIFY_NAME(stack_callee_leave)
4600 #else /* INTEL_NO_ITTNOTIFY_API */
4601 #define __itt_stack_callee_leave(id)
4602 #define __itt_stack_callee_leave_ptr 0
4603 #endif /* INTEL_NO_ITTNOTIFY_API */
4604 #else /* INTEL_NO_MACRO_BODY */
4605 #define __itt_stack_callee_leave_ptr 0
4606 #endif /* INTEL_NO_MACRO_BODY */
4607 /** @endcond */
4608
4609 /** @} stitch group */
4610
4611 /* ***************************************************************************************************************************** */
4612
4613 #include <stdarg.h>
4614
4615 /** @cond exclude_from_documentation */
4616 typedef enum __itt_error_code
4617 {
4618 __itt_error_success = 0, /*!< no error */
4619 __itt_error_no_module = 1, /*!< module can't be loaded */
4620 /* %1$s -- library name; win: %2$d -- system error code; unix: %2$s -- system error message. */
4621 __itt_error_no_symbol = 2, /*!< symbol not found */
4622 /* %1$s -- library name, %2$s -- symbol name. */
4623 __itt_error_unknown_group = 3, /*!< unknown group specified */
4624 /* %1$s -- env var name, %2$s -- group name. */
4625 __itt_error_cant_read_env = 4, /*!< GetEnvironmentVariable() failed */
4626 /* %1$s -- env var name, %2$d -- system error. */
4627 __itt_error_env_too_long = 5, /*!< variable value too long */
4628 /* %1$s -- env var name, %2$d -- actual length of the var, %3$d -- max allowed length. */
4629 __itt_error_system = 6 /*!< pthread_mutexattr_init or pthread_mutex_init failed */
4630 /* %1$s -- function name, %2$d -- errno. */
4631 } __itt_error_code;
4632
4633 typedef void (__itt_error_handler_t)(__itt_error_code code, va_list);
4634 __itt_error_handler_t* __itt_set_error_handler(__itt_error_handler_t*);
4635
4636 const char* ITTAPI __itt_api_version(void);
4637 /** @endcond */
4638
4639 /** @cond exclude_from_documentation */
4640 #ifndef INTEL_NO_MACRO_BODY
4641 #ifndef INTEL_NO_ITTNOTIFY_API
4642 #define __itt_error_handler ITT_JOIN(INTEL_ITTNOTIFY_PREFIX, error_handler)
4643 void __itt_error_handler(__itt_error_code code, va_list args);
4644 extern const int ITTNOTIFY_NAME(err);
4645 #define __itt_err ITTNOTIFY_NAME(err)
4646 ITT_STUB(ITTAPI, const char*, api_version, (void))
4647 #define __itt_api_version ITTNOTIFY_DATA(api_version)
4648 #define __itt_api_version_ptr ITTNOTIFY_NAME(api_version)
4649 #else /* INTEL_NO_ITTNOTIFY_API */
4650 #define __itt_api_version() (const char*)0
4651 #define __itt_api_version_ptr 0
4652 #endif /* INTEL_NO_ITTNOTIFY_API */
4653 #else /* INTEL_NO_MACRO_BODY */
4654 #define __itt_api_version_ptr 0
4655 #endif /* INTEL_NO_MACRO_BODY */
4656 /** @endcond */
4657
4658 #ifdef __cplusplus
4659 }
4660 #endif /* __cplusplus */
4661
4662 #endif /* _ITTNOTIFY_PRIVATE_ */
4663
4664 #endif /* INTEL_ITTNOTIFY_API_PRIVATE */
4665