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