Intel® OpenMP* Runtime Library
 All Classes Functions Variables Typedefs Enumerations Enumerator Groups Pages
kmp_itt.h
1 #if USE_ITT_BUILD
2 /*
3  * kmp_itt.h -- ITT Notify interface.
4  * $Revision: 42829 $
5  * $Date: 2013-11-21 05:44:01 -0600 (Thu, 21 Nov 2013) $
6  */
7 
8 /* <copyright>
9  Copyright (c) 1997-2013 Intel Corporation. All Rights Reserved.
10 
11  Redistribution and use in source and binary forms, with or without
12  modification, are permitted provided that the following conditions
13  are met:
14 
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of Intel Corporation nor the names of its
21  contributors may be used to endorse or promote products derived
22  from this software without specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
27  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
28  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
29  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
30  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
34  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 
36 </copyright> */
37 
38 #ifndef KMP_ITT_H
39 #define KMP_ITT_H
40 
41 #include "kmp_lock.h"
42 
43 #define INTEL_ITTNOTIFY_API_PRIVATE
44 #include "ittnotify.h"
45 #include "legacy/ittnotify.h"
46 
47 #if KMP_DEBUG
48  #define __kmp_inline // Turn off inlining in debug mode.
49 #else
50  #define __kmp_inline static inline
51 #endif
52 
53 #if USE_ITT_NOTIFY
54  extern kmp_int32 __kmp_itt_prepare_delay;
55 # ifdef __cplusplus
56  extern "C" void __kmp_itt_fini_ittlib(void);
57 # else
58  extern void __kmp_itt_fini_ittlib(void);
59 # endif
60 #endif
61 
62 // Simplify the handling of an argument that is only required when USE_ITT_BUILD is enabled.
63 #define USE_ITT_BUILD_ARG(x) ,x
64 
65 void __kmp_itt_initialize();
66 void __kmp_itt_destroy();
67 
68 // -------------------------------------------------------------------------------------------------
69 // New stuff for reporting high-level constructs.
70 // -------------------------------------------------------------------------------------------------
71 
72 // Note the naming convention:
73 // __kmp_itt_xxxing() function should be called before action, while
74 // __kmp_itt_xxxed() function should be called after action.
75 
76 // --- Parallel region reporting ---
77 __kmp_inline void __kmp_itt_region_forking( int gtid, int serialized = 0 ); // Master only, before forking threads.
78 __kmp_inline void __kmp_itt_region_joined( int gtid, int serialized = 0 ); // Master only, after joining threads.
79  // (*) Note: A thread may execute tasks after this point, though.
80 
81 // --- Frame reporting ---
82 __kmp_inline void __kmp_itt_frame_submit( int gtid, __itt_timestamp begin, __itt_timestamp end, int imbalance, ident_t *loc );
83 
84 // --- Barrier reporting ---
85 __kmp_inline void * __kmp_itt_barrier_object( int gtid, int bt, int set_name = 0, int delta = 0 );
86 __kmp_inline void __kmp_itt_barrier_starting( int gtid, void * object );
87 __kmp_inline void __kmp_itt_barrier_middle( int gtid, void * object );
88 __kmp_inline void __kmp_itt_barrier_finished( int gtid, void * object );
89 
90 // --- Taskwait reporting ---
91 __kmp_inline void * __kmp_itt_taskwait_object( int gtid );
92 __kmp_inline void __kmp_itt_taskwait_starting( int gtid, void * object );
93 __kmp_inline void __kmp_itt_taskwait_finished( int gtid, void * object );
94 
95 // --- Task reporting ---
96 __kmp_inline void __kmp_itt_task_starting( void * object );
97 __kmp_inline void __kmp_itt_task_finished( void * object );
98 
99 // --- Lock reporting ---
100 __kmp_inline void __kmp_itt_lock_creating( kmp_user_lock_p lock );
101 __kmp_inline void __kmp_itt_lock_acquiring( kmp_user_lock_p lock );
102 __kmp_inline void __kmp_itt_lock_acquired( kmp_user_lock_p lock );
103 __kmp_inline void __kmp_itt_lock_releasing( kmp_user_lock_p lock );
104 __kmp_inline void __kmp_itt_lock_cancelled( kmp_user_lock_p lock );
105 __kmp_inline void __kmp_itt_lock_destroyed( kmp_user_lock_p lock );
106 
107 // --- Critical reporting ---
108 __kmp_inline void __kmp_itt_critical_creating( kmp_user_lock_p lock );
109 __kmp_inline void __kmp_itt_critical_acquiring( kmp_user_lock_p lock );
110 __kmp_inline void __kmp_itt_critical_acquired( kmp_user_lock_p lock );
111 __kmp_inline void __kmp_itt_critical_releasing( kmp_user_lock_p lock );
112 __kmp_inline void __kmp_itt_critical_destroyed( kmp_user_lock_p lock );
113 
114 // --- Single reporting ---
115 __kmp_inline void __kmp_itt_single_start( int gtid );
116 __kmp_inline void __kmp_itt_single_end( int gtid );
117 
118 // --- Ordered reporting ---
119 __kmp_inline void __kmp_itt_ordered_init( int gtid );
120 __kmp_inline void __kmp_itt_ordered_prep( int gtid );
121 __kmp_inline void __kmp_itt_ordered_start( int gtid );
122 __kmp_inline void __kmp_itt_ordered_end( int gtid );
123 
124 // --- Threads reporting ---
125 __kmp_inline void __kmp_itt_thread_ignore();
126 __kmp_inline void __kmp_itt_thread_name( int gtid );
127 
128 // --- System objects ---
129 __kmp_inline void __kmp_itt_system_object_created( void * object, char const * name );
130 
131 // --- Stack stitching ---
132 __kmp_inline __itt_caller __kmp_itt_stack_caller_create(void);
133 __kmp_inline void __kmp_itt_stack_caller_destroy(__itt_caller);
134 __kmp_inline void __kmp_itt_stack_callee_enter(__itt_caller);
135 __kmp_inline void __kmp_itt_stack_callee_leave(__itt_caller);
136 
137 // -------------------------------------------------------------------------------------------------
138 // Old stuff for reporting low-level internal synchronization.
139 // -------------------------------------------------------------------------------------------------
140 
141 #if USE_ITT_NOTIFY
142 
143  /*
144  * Support for SSC marks, which are used by SDE
145  * http://software.intel.com/en-us/articles/intel-software-development-emulator
146  * to mark points in instruction traces that represent spin-loops and are
147  * therefore uninteresting when collecting traces for architecture simulation.
148  */
149  #ifndef INCLUDE_SSC_MARKS
150  # define INCLUDE_SSC_MARKS (KMP_OS_LINUX && KMP_ARCH_X86_64)
151  #endif
152 
153  /* Linux 64 only for now */
154  #if (INCLUDE_SSC_MARKS && KMP_OS_LINUX && KMP_ARCH_X86_64)
155  // Portable (at least for gcc and icc) code to insert the necessary instructions
156  // to set %ebx and execute the unlikely no-op.
157  # define INSERT_SSC_MARK(tag) \
158  __asm__ __volatile__ ("movl %0, %%ebx; .byte 0x64, 0x67, 0x90 " ::"i"(tag):"%ebx")
159  #else
160  # define INSERT_SSC_MARK(tag) ((void)0)
161  #endif
162 
163  /* Markers for the start and end of regions that represent polling and
164  * are therefore uninteresting to architectural simulations 0x4376 and
165  * 0x4377 are arbitrary numbers that should be unique in the space of
166  * SSC tags, but there is no central issuing authority rather
167  * randomness is expected to work.
168  */
169  #define SSC_MARK_SPIN_START() INSERT_SSC_MARK(0x4376)
170  #define SSC_MARK_SPIN_END() INSERT_SSC_MARK(0x4377)
171 
172  // The object is an address that associates a specific set of the prepare, acquire, release,
173  // and cancel operations.
174 
175  /* Sync prepare indicates a thread is going to start waiting for another thread
176  to send a release event. This operation should be done just before the thread
177  begins checking for the existence of the release event */
178 
179  /* Sync cancel indicates a thread is cancelling a wait on another thread anc
180  continuing execution without waiting for the other thread to release it */
181 
182  /* Sync acquired indicates a thread has received a release event from another
183  thread and has stopped waiting. This operation must occur only after the release
184  event is received. */
185 
186  /* Sync release indicates a thread is going to send a release event to another thread
187  so it will stop waiting and continue execution. This operation must just happen before
188  the release event. */
189 
190  #define KMP_FSYNC_PREPARE( obj ) __itt_fsync_prepare( (void *)( obj ) )
191  #define KMP_FSYNC_CANCEL( obj ) __itt_fsync_cancel( (void *)( obj ) )
192  #define KMP_FSYNC_ACQUIRED( obj ) __itt_fsync_acquired( (void *)( obj ) )
193  #define KMP_FSYNC_RELEASING( obj ) __itt_fsync_releasing( (void *)( obj ) )
194 
195  /*
196  In case of waiting in a spin loop, ITT wants KMP_FSYNC_PREPARE() to be called with a delay
197  (and not called at all if waiting time is small). So, in spin loops, do not use
198  KMP_FSYNC_PREPARE(), but use KMP_FSYNC_SPIN_INIT() (before spin loop),
199  KMP_FSYNC_SPIN_PREPARE() (whithin the spin loop), and KMP_FSYNC_SPIN_ACQUIRED().
200  See KMP_WAIT_YIELD() for example.
201  */
202 
203  #undef KMP_FSYNC_SPIN_INIT
204  #define KMP_FSYNC_SPIN_INIT( obj, spin ) \
205  int sync_iters = 0; \
206  if ( __itt_fsync_prepare_ptr ) { \
207  if ( obj == NULL ) { \
208  obj = spin; \
209  } /* if */ \
210  } /* if */ \
211  SSC_MARK_SPIN_START()
212 
213  #undef KMP_FSYNC_SPIN_PREPARE
214  #define KMP_FSYNC_SPIN_PREPARE( obj ) do { \
215  if ( __itt_fsync_prepare_ptr && sync_iters < __kmp_itt_prepare_delay ) { \
216  ++ sync_iters; \
217  if ( sync_iters >= __kmp_itt_prepare_delay ) { \
218  KMP_FSYNC_PREPARE( (void*) obj ); \
219  } /* if */ \
220  } /* if */ \
221  } while (0)
222  #undef KMP_FSYNC_SPIN_ACQUIRED
223  #define KMP_FSYNC_SPIN_ACQUIRED( obj ) do { \
224  SSC_MARK_SPIN_END(); \
225  if ( sync_iters >= __kmp_itt_prepare_delay ) { \
226  KMP_FSYNC_ACQUIRED( (void*) obj ); \
227  } /* if */ \
228  } while (0)
229 
230  /* ITT will not report objects created within KMP_ITT_IGNORE(), e. g.:
231  KMP_ITT_IGNORE(
232  ptr = malloc( size );
233  );
234  */
235  #define KMP_ITT_IGNORE( statement ) do { \
236  __itt_state_t __itt_state_; \
237  if ( __itt_state_get_ptr ) { \
238  __itt_state_ = __itt_state_get(); \
239  __itt_obj_mode_set( __itt_obj_prop_ignore, __itt_obj_state_set ); \
240  } /* if */ \
241  { statement } \
242  if ( __itt_state_get_ptr ) { \
243  __itt_state_set( __itt_state_ ); \
244  } /* if */ \
245  } while (0)
246 
247  const int KMP_MAX_FRAME_DOMAINS = 512; // Maximum number of frame domains to use (maps to
248  // different OpenMP regions in the user source code).
249  extern kmp_int32 __kmp_frame_domain_count;
250  extern __itt_domain* __kmp_itt_domains[KMP_MAX_FRAME_DOMAINS];
251 #else
252 
253 // Null definitions of the synchronization tracing functions.
254 # define KMP_FSYNC_PREPARE( obj ) ((void)0)
255 # define KMP_FSYNC_CANCEL( obj ) ((void)0)
256 # define KMP_FSYNC_ACQUIRED( obj ) ((void)0)
257 # define KMP_FSYNC_RELEASING( obj ) ((void)0)
258 
259 # define KMP_FSYNC_SPIN_INIT( obj, spin ) ((void)0)
260 # define KMP_FSYNC_SPIN_PREPARE( obj ) ((void)0)
261 # define KMP_FSYNC_SPIN_ACQUIRED( obj ) ((void)0)
262 
263 # define KMP_ITT_IGNORE(stmt ) do { stmt } while (0)
264 
265 #endif // USE_ITT_NOTIFY
266 
267 #if ! KMP_DEBUG
268  // In release mode include definitions of inline functions.
269  #include "kmp_itt.inl"
270 #endif
271 
272 #endif // KMP_ITT_H
273 
274 #else /* USE_ITT_BUILD */
275 
276 // Null definitions of the synchronization tracing functions.
277 // If USE_ITT_BULID is not enabled, USE_ITT_NOTIFY cannot be either.
278 // By defining these we avoid unpleasant ifdef tests in many places.
279 # define KMP_FSYNC_PREPARE( obj ) ((void)0)
280 # define KMP_FSYNC_CANCEL( obj ) ((void)0)
281 # define KMP_FSYNC_ACQUIRED( obj ) ((void)0)
282 # define KMP_FSYNC_RELEASING( obj ) ((void)0)
283 
284 # define KMP_FSYNC_SPIN_INIT( obj, spin ) ((void)0)
285 # define KMP_FSYNC_SPIN_PREPARE( obj ) ((void)0)
286 # define KMP_FSYNC_SPIN_ACQUIRED( obj ) ((void)0)
287 
288 # define KMP_ITT_IGNORE(stmt ) do { stmt } while (0)
289 
290 # define USE_ITT_BUILD_ARG(x)
291 
292 #endif /* USE_ITT_BUILD */
Definition: kmp.h:200