OpenMPI  0.1.1
vt_trc.h
1 /**
2  * VampirTrace
3  * http://www.tu-dresden.de/zih/vampirtrace
4  *
5  * Copyright (c) 2005-2012, ZIH, TU Dresden, Federal Republic of Germany
6  *
7  * Copyright (c) 1998-2005, Forschungszentrum Juelich, Juelich Supercomputing
8  * Centre, Federal Republic of Germany
9  *
10  * See the file COPYING in the package base directory for details
11  **/
12 
13 #ifndef _VT_TRC_H
14 #define _VT_TRC_H
15 
16 #ifdef __cplusplus
17 # define EXTERN extern "C"
18 #else
19 # define EXTERN extern
20 #endif
21 
22 #include "vt_inttypes.h"
23 
24 #include <stdlib.h>
25 
26 /* id indices for internal regions */
27 #define VT__TRC_USER 0
28 #define VT__TRC_SYNC 1
29 #define VT__TRC_SYNCTIME 2
30 #define VT__TRC_FLUSH 3
31 #define VT__TRC_STAT 4
32 #define VT__TRC_OFF 5
33 #define VT__TRC_REWIND 6
34 #define VT__TRC_OMPPREG 7
35 #define VT__TRC_REGID_NUM 8
36 
37 /* id indices for internal markers */
38 #define VT__TRC_MARKER_ERROR 0
39 #define VT__TRC_MARKER_WARNING 1
40 #define VT__TRC_MARKER_HINT 2
41 
42 /**
43  * TODO: Description
44  */
45 EXTERN void vt_open(void);
46 
47 /**
48  * TODO: Description
49  */
50 EXTERN void vt_reset(void);
51 /**
52  * TODO: Description
53  *
54  * @param signum signal number
55  */
56 EXTERN void vt_close_by_signal(int signum);
57 
58 /**
59  * TODO: Description
60  */
61 EXTERN void vt_close(void);
62 
63 /**
64  * TODO: Description
65  *
66  * @param tid thread id
67  * @param mark flag: mark trace status as function enter/exit?
68  * (0 - no, 1 - yes)
69  */
70 EXTERN void vt_trace_on(uint32_t tid, uint8_t mark);
71 
72 /**
73  * TODO: Description
74  *
75  * @param tid thread id
76  * @param mark flag: mark trace status as function enter/exit?
77  * (0 - no, 1 - yes)
78  * @param permanent flag: trace switched off permanently?
79  * (e.g. if max. buffer flushes reached)
80  * (0 - no, 1 - yes)
81  */
82 EXTERN void vt_trace_off(uint32_t tid, uint8_t mark, uint8_t permanent);
83 
84 /**
85  * TODO: Description
86  *
87  * @param tid thread id
88  *
89  * @return current trace status
90  * (0 - off, 1 - on)
91  */
92 EXTERN uint8_t vt_is_trace_on(uint32_t tid);
93 
94 /**
95  * TODO: Description
96  *
97  * @param tid thread id
98  * @param size buffer size to be guaranteed
99  */
100 EXTERN void vt_guarantee_buffer(uint32_t tid, size_t size);
101 
102 /**
103  * TODO: Description
104  *
105  * @param tid thread id
106  */
107 EXTERN void vt_buffer_flush(uint32_t tid);
108 
109 /**
110  * TODO: Description
111  *
112  * @param tid thread id
113  * @param time timestamp
114  */
115 EXTERN void vt_update_counter(uint32_t tid, uint64_t* time);
116 
117 /**
118  * TODO: Description
119  * This function have to be called immediately after initializing the
120  * communication middle-ware, e.g. atfer MPI_Init().
121  */
122 EXTERN void vt_mpi_init(void);
123 
124 /**
125  * TODO: Description
126  * This function have to be called immediately before finalizing the
127  * communication middle-ware, e.g. before MPI_Finalize().
128  */
129 EXTERN void vt_mpi_finalize(void);
130 
131 /**
132  * TODO: Description
133  *
134  * @param tid thread id
135  * @param time timestamp
136  * @param comm MPI communicator
137  */
138 EXTERN void vt_mpi_sync(uint32_t tid, uint64_t* time, void* comm);
139 
140 /**
141  * Retrieve and increment current id counter.
142  *
143  * @return new id
144  */
145 EXTERN uint32_t vt_get_curid(void);
146 
147 /*
148  *-----------------------------------------------------------------------------
149  * Definition records
150  *-----------------------------------------------------------------------------
151  */
152 
153 /**
154  * TODO: Description
155  *
156  * @param tid thread id
157  * @param fmt comment as format string like printf
158  */
159 EXTERN void vt_def_comment(uint32_t tid, const char* fmt, ...);
160 
161 /**
162  * TODO: Description
163  *
164  * @param tid thread id
165  * @param fname source file name
166  *
167  * @return source file id
168  */
169 EXTERN uint32_t vt_def_scl_file(uint32_t tid, const char* fname);
170 
171 /**
172  * TODO: Description
173  *
174  * @param tid thread id
175  * @param fid source file id (created by vt_def_scl_file)
176  * @param begln begin line number
177  * @param endln end line number
178  * @param fname source file name
179  *
180  * @return source code location id
181  */
182 EXTERN uint32_t vt_def_scl(uint32_t tid, uint32_t fid, uint32_t begln,
183  uint32_t endln);
184 
185 /**
186  * TODO: Description
187  *
188  * @param tid thread id
189  * @param gname file group name
190  *
191  * @return file group id
192  */
193 EXTERN uint32_t vt_def_file_group(uint32_t tid, const char* gname);
194 
195 /**
196  * TODO: Description
197  *
198  * @param tid thread id
199  * @param fname file name
200  * @param gid file group id (created by vt_def_file_group)
201  *
202  * @return file id
203  */
204 EXTERN uint32_t vt_def_file(uint32_t tid, const char* fname, uint32_t gid);
205 
206 /**
207  * TODO: Description
208  *
209  * @param tid thread id
210  * @param gname region group name
211  *
212  * @return region group id
213  */
214 EXTERN uint32_t vt_def_region_group(uint32_t tid, const char* gname);
215 
216 /**
217  * TODO: Description
218  *
219  * @param tid thread id
220  * @param rname region name
221  * @param fid source file id (created by vt_def_scl_file)
222  * @param begln begin line number
223  * @param endln end line number
224  * @param rgroup region group name
225  * @param rtype region type
226  *
227  * @return region id
228  */
229 EXTERN uint32_t vt_def_region(uint32_t tid, const char* rname, uint32_t fid,
230  uint32_t begln, uint32_t endln,
231  const char* rdesc, uint8_t rtype);
232 
233 /**
234  * TODO: Description
235  *
236  * @param tid thread id
237  * @param gname counter group name
238  *
239  * @return counter group id
240  */
241 EXTERN uint32_t vt_def_counter_group(uint32_t tid, const char* gname);
242 
243 /**
244  * TODO: Description
245  *
246  * @param tid thread id
247  * @param cname counter name
248  * @param cunit counter unit
249  * @param cprop counter properties bitmask
250  * @param cgid counter group id (created by vt_def_counter_group)
251  * @param pgid process group id (created by vt_def_procgrp if group counter,
252  * otherwise 0)
253  *
254  * @return counter id
255  */
256 EXTERN uint32_t vt_def_counter(uint32_t tid, const char* cname,
257  const char* cunit, uint32_t cprop, uint32_t gid,
258  uint32_t pgid);
259 
260 /**
261  * TODO: Description
262  *
263  * @param tid thread id
264  * @param gname process group name
265  * @param grpc number of entries in @grpv array
266  * @param grpv array of member process/thread ids
267  * @param gid previous created process group id (if 0, create a new one)
268  *
269  * @return process group id
270  */
271 EXTERN uint32_t vt_def_procgrp(uint32_t tid, const char* gname, uint32_t gattr,
272  uint32_t grpc, uint32_t grpv[], uint32_t gid);
273 
274 /**
275  * TODO: Description
276  *
277  * @param tid thread id
278  * @param gid process group id (created by vt_def_procgrp)
279  * @param gattr process group attributes bitmask
280  */
281 EXTERN void vt_def_procgrp_attributes(uint32_t tid, uint32_t gid,
282  uint32_t gattr);
283 
284 /**
285  * TODO: Description
286  *
287  * @param tid thread id
288  * @param mname marker name
289  * @param mtype marker type
290  *
291  * @return marker id
292  */
293 EXTERN uint32_t vt_def_marker(uint32_t tid, const char* mname,
294  uint32_t mtype);
295 
296 /**
297  * TODO: Description
298  *
299  * @param tid thread id
300  * @param ctype MPI communicator type
301  * (VT_MPI_COMM_WORLD, VT_MPI_COMM_SELF, or VT_MPI_COMM_OTHER)
302  * @param grpc number of members
303  * @param grpv bit-vector of members
304  *
305  * @return MPI communicator id
306  */
307 EXTERN uint32_t vt_def_mpi_comm(uint32_t tid, uint8_t ctype, uint32_t grpc,
308  uint8_t grpv[]);
309 
310 /**
311  * TODO: Description
312  *
313  * @param tid thread id
314  * @param cname communicator name
315  *
316  * @return User communicator id
317  */
318 EXTERN uint32_t vt_def_user_comm(uint32_t tid, const char* cname);
319 
320 /**
321  * TODO: Description
322  *
323  * @param tid thread id
324  * @param vtype value type
325  * @param kname key name
326  *
327  * @return key id
328  */
329 EXTERN uint32_t vt_def_keyval(uint32_t tid, uint8_t vtype, const char* kname);
330 
331 /**
332  * TODO: Description
333  *
334  * @param tid thread id
335  * @param sname unique async. source name
336  *
337  * @return async. source key id
338  */
339 EXTERN uint32_t vt_def_async_source(uint32_t tid, const char* sname);
340 
341 /*
342  *-----------------------------------------------------------------------------
343  * Event records
344  *-----------------------------------------------------------------------------
345  */
346 
347 /* -- Region -- */
348 
349 /**
350  * TODO: Description
351  *
352  * @param tid thread id
353  * @param time timestamp
354  * @param rid region id (created by vt_def_region)
355  *
356  * @return flag: enter was recorded?
357  * (0 - no, 1 - yes)
358  */
359 EXTERN uint8_t vt_enter(uint32_t tid, uint64_t* time, uint32_t rid);
360 
361 /**
362  * TODO: Description
363  *
364  * @param tid thread id
365  * @param time timestamp
366  */
367 EXTERN void vt_exit(uint32_t tid, uint64_t* time);
368 
369 /* -- File I/O -- */
370 
371 /**
372  * DEPRECATED
373  * TODO: Description
374  *
375  * @param tid thread id
376  * @param time begin timestamp
377  * @param etime end timestamp
378  * @param fid file id (created by vt_def_file)
379  * @param hid handle id
380  * @param op file operation
381  * @param bytes read/wrote bytes
382  */
383 EXTERN void vt_ioexit(uint32_t tid, uint64_t* time, uint64_t* etime,
384  uint32_t fid, uint64_t hid, uint32_t op, uint64_t bytes );
385 
386 /**
387  * TODO: Description
388  *
389  * @param tid thread id
390  * @param time timestamp
391  * @param mid matching id
392  */
393 EXTERN void vt_iobegin( uint32_t tid, uint64_t* time, uint64_t mid );
394 
395 /**
396  * TODO: Description
397  *
398  * @param tid thread id
399  * @param time timestamp
400  * @param fid file id (created by vt_def_file)
401  * @param mid matching id
402  * @param hid handle id
403  * @param op file operation
404  * @param bytes read/wrote bytes
405  */
406 EXTERN void vt_ioend(uint32_t tid, uint64_t* time, uint32_t fid, uint64_t mid,
407  uint64_t hid, uint32_t op, uint64_t bytes);
408 
409 /* -- Counter -- */
410 
411 /**
412  * TODO: Description
413  *
414  * @param tid thread id
415  * @param time timestamp
416  * @param hid counter id (created by vt_def_counter)
417  * @param cval counter value
418  */
419 EXTERN void vt_count(uint32_t tid, uint64_t* time, uint32_t cid, uint64_t cval);
420 
421 /* -- Comment -- */
422 
423 /**
424  * TODO: Description
425  *
426  * @param tid thread id
427  * @param time timestamp
428  * @param fmt comment as format string like printf
429  */
430 EXTERN void vt_comment(uint32_t tid, uint64_t* time, const char* fmt, ... );
431 
432 /* -- Rewind -- */
433 
434 /**
435  * TODO: Description
436  *
437  * @param tid thread id
438  * @param time timestamp
439  */
440 EXTERN void vt_rewind(uint32_t tid, uint64_t* time);
441 
442 /**
443  * TODO: Description
444  *
445  * @param tid thread id
446  * @param time timestamp
447  */
448 EXTERN void vt_set_rewind_mark(uint32_t tid, uint64_t* time);
449 
450 /* -- Marker -- */
451 
452 /**
453  * TODO: Description
454  *
455  * @param tid thread id
456  * @param time timestamp
457  * @param mid marker id (created by vt_def_marker)
458  * @param fmt marker text as format string like printf
459  */
460 EXTERN void vt_marker(uint32_t tid, uint64_t* time, uint32_t mid,
461  const char* fmt, ...);
462 
463 /**
464  * TODO: Description
465  *
466  * @param tid thread id
467  * @param time timestamp
468  * @param fmt marker text as format string like printf
469  */
470 EXTERN void vt_marker_error(uint32_t tid, uint64_t* time,
471  const char* fmt, ...);
472 
473 /**
474  * TODO: Description
475  *
476  * @param tid thread id
477  * @param time timestamp
478  * @param fmt marker text as format string like printf
479  */
480 EXTERN void vt_marker_warning(uint32_t tid, uint64_t* time,
481  const char* fmt, ...);
482 
483 /**
484  * TODO: Description
485  *
486  * @param tid thread id
487  * @param time timestamp
488  * @param fmt marker text as format string like printf
489  */
490 EXTERN void vt_marker_hint(uint32_t tid, uint64_t* time,
491  const char* fmt, ...);
492 
493 /* -- Key-Value -- */
494 
495 /**
496  * TODO: Description
497  *
498  * @param tid thread id
499  * @param time timestamp
500  * @param kid key id
501  * @param vtype value type
502  * @param kval value
503  */
504 EXTERN void vt_keyval(uint32_t tid, uint32_t kid, uint8_t vtype, void* kvalue);
505 
506 /**
507  * TODO: Description
508  *
509  * @param tid thread id
510  * @param kid async. source key id
511  * @param time actual time of next async. event
512  */
513 EXTERN void vt_next_async_time(uint32_t tid, uint32_t kid, uint64_t atime);
514 
515 /* -- MPI-1 -- */
516 
517 /**
518  * TODO: Description
519  *
520  * @param tid thread id
521  * @param time timestamp
522  * @param dpid destination process id
523  * @param cid communicator id (created by vt_def_mpi_comm)
524  * @param tag message tag
525  * @param sent sent bytes
526  */
527 EXTERN void vt_mpi_send(uint32_t tid, uint64_t* time, uint32_t dpid,
528  uint32_t cid, uint32_t tag, uint32_t sent);
529 
530 /**
531  * TODO: Description
532  *
533  * @param tid thread id
534  * @param time timestamp
535  * @param spid source process id
536  * @param cid communicator id (created by vt_def_mpi_comm)
537  * @param tag message tag
538  * @param recvd received bytes
539  */
540 EXTERN void vt_mpi_recv(uint32_t tid, uint64_t* time, uint32_t spid,
541  uint32_t cid, uint32_t tag, uint32_t recvd);
542 
543 
544 /**
545  * DEPRECATED
546  * TODO: Description
547  *
548  * @param tid thread id
549  * @param time timestamp
550  * @param etime end timestamp
551  * @param rid region id of coll. operation (created by vt_def_region)
552  * @param rpid root process id
553  * @param cid communicator id (created by vt_def_mpi_comm)
554  * @param comm MPI communicator
555  * @param sent sent bytes
556  * @param recvd received bytes
557  */
558 EXTERN void vt_mpi_collexit(uint32_t tid, uint64_t* time, uint64_t* etime,
559  uint32_t rid, uint32_t rpid, uint32_t cid,
560  void* comm, uint32_t sent, uint32_t recvd);
561 
562 /**
563  * TODO: Description
564  *
565  * @param tid thread id
566  * @param time timestamp
567  * @param rid region id of coll. operation (created by vt_def_region)
568  * @param mid matching id
569  * @param rpid root process id
570  * @param cid communicator id (created by vt_def_mpi_comm)
571  * @param sent sent bytes
572  * @param recvd received bytes
573  */
574 EXTERN void vt_mpi_collbegin(uint32_t tid, uint64_t* time, uint32_t rid,
575  uint64_t mid, uint32_t rpid, uint32_t cid,
576  uint64_t sent, uint64_t recvd);
577 
578 /**
579  * TODO: Description
580  *
581  * @param tid thread id
582  * @param time timestamp
583  * @param mid matching id
584  * @param comm MPI communicator
585  */
586 EXTERN void vt_mpi_collend(uint32_t tid, uint64_t* time, uint64_t mid,
587  void* comm, uint8_t was_recorded);
588 
589 /* -- MPI2 - 1sided -- */
590 
591 /**
592  * TODO: Description
593  *
594  * @param tid thread id
595  * @param time timestamp
596  * @param tpid process id
597  * @param cid communicator id (created by vt_def_mpi_comm)
598  * @param tag message tag
599  * @param sent sent bytes
600  */
601 EXTERN void vt_mpi_rma_put(uint32_t tid, uint64_t* time, uint32_t tpid,
602  uint32_t cid, uint32_t tag, uint64_t sent);
603 
604 /**
605  * TODO: Description
606  *
607  * @param tid thread id
608  * @param time timestamp
609  * @param tpid process id
610  * @param cid communicator id (created by vt_def_mpi_comm)
611  * @param tag message tag
612  * @param sent sent bytes
613  */
614 EXTERN void vt_mpi_rma_putre(uint32_t tid, uint64_t* time, uint32_t tpid,
615  uint32_t cid, uint32_t tag, uint64_t sent);
616 
617 /**
618  * TODO: Description
619  *
620  * @param tid thread id
621  * @param time timestamp
622  * @param tpid process id
623  * @param cid communicator id (created by vt_def_mpi_comm)
624  * @param tag message tag
625  * @param recvd received bytes
626  */
627 EXTERN void vt_mpi_rma_get(uint32_t tid, uint64_t* time, uint32_t tpid,
628  uint32_t cid, uint32_t tag, uint64_t recvd);
629 
630 /**
631  * TODO: Description
632  *
633  * @param tid thread id
634  * @param time timestamp
635  * @param cid communicator id (created by vt_def_mpi_comm)
636  * @param tag message tag
637  */
638 EXTERN void vt_mpi_rma_end(uint32_t tid, uint64_t* time, uint32_t cid,
639  uint32_t tag);
640 
641 /* -- OpenMP -- */
642 
643 /**
644  * TODO: Description
645  *
646  * @param tid thread id
647  */
648 EXTERN void vt_omp_fork(uint32_t tid);
649 
650 /**
651  * TODO: Description
652  *
653  * @param tid thread id
654  * @param ptid parent thread id
655  */
656 EXTERN void vt_omp_fork2(uint32_t tid, uint32_t* ptid);
657 
658 /**
659  * TODO: Description
660  *
661  * @param tid thread id
662  */
663 EXTERN void vt_omp_join(uint32_t tid);
664 
665 /**
666  * TODO: Description
667  *
668  * @param tid thread id
669  */
670 EXTERN void vt_omp_parallel_begin(uint32_t tid);
671 
672 /**
673  * TODO: Description
674  *
675  * @param tid thread id
676  * @param ptid parent thread id
677  */
678 EXTERN void vt_omp_parallel_begin2(uint32_t tid, uint32_t ptid);
679 
680 /**
681  * TODO: Description
682  *
683  * @param tid thread id
684  */
685 EXTERN void vt_omp_parallel_end(uint32_t tid);
686 
687 /* -- User Point-to-Point Communication -- */
688 
689 /**
690  * TODO: Description
691  *
692  * @param tid thread id
693  * @param time timestamp
694  * @param cid communicator id (created by vt_def_user_comm)
695  * @param tag message tag (has to be unique per communication pair)
696  * @param sent sent bytes
697  */
698 
699 EXTERN void vt_user_send(uint32_t tid, uint64_t* time, uint32_t cid,
700  uint32_t tag, uint32_t sent);
701 
702 /**
703  * TODO: Description
704  *
705  * @param tid thread id
706  * @param time timestamp
707  * @param cid communicator id (created by vt_def_user_comm)
708  * @param tag message tag (has to be unique per communication pair)
709  * @param sent received bytes
710  */
711 
712 EXTERN void vt_user_recv(uint32_t tid, uint64_t* time, uint32_t cid,
713  uint32_t tag, uint32_t recvd);
714 
715 /* -- VampirTrace Internal -- */
716 
717 /**
718  * TODO: Description
719  *
720  * @param tid thread id
721  * @param time timestamp
722  */
723 EXTERN void vt_enter_user(uint32_t tid, uint64_t* time);
724 
725 /**
726  * TODO: Description
727  *
728  * @param tid thread id
729  * @param time timestamp
730  */
731 EXTERN void vt_exit_user(uint32_t tid, uint64_t* time);
732 
733 /**
734  * TODO: Description
735  *
736  * @param tid thread id
737  * @param time timestamp
738  */
739 EXTERN void vt_enter_stat(uint32_t tid, uint64_t* time);
740 
741 /**
742  * TODO: Description
743  *
744  * @param tid thread id
745  * @param time timestamp
746  */
747 EXTERN void vt_exit_stat(uint32_t tid, uint64_t* time);
748 
749 /**
750  * TODO: Description
751  *
752  * @param tid thread id
753  * @param time timestamp
754  */
755 EXTERN void vt_enter_flush(uint32_t tid, uint64_t* time);
756 
757 /**
758  * TODO: Description
759  *
760  * @param tid thread id
761  * @param time timestamp
762  */
763 EXTERN void vt_exit_flush(uint32_t tid, uint64_t* time);
764 
765 /**
766  * TODO: Description
767  *
768  * @param tid thread id
769  * @param time timestamp
770  */
771 EXTERN void vt_enter_rewind(uint32_t tid, uint64_t* time);
772 
773 /**
774  * TODO: Description
775  *
776  * @param tid thread id
777  * @param time timestamp
778  */
779 EXTERN void vt_exit_rewind(uint32_t tid, uint64_t* time);
780 
781 /*
782  *-----------------------------------------------------------------------------
783  * Global variables
784  *-----------------------------------------------------------------------------
785  */
786 
787 EXTERN int vt_num_traces; /** number of processes */
788 EXTERN int vt_my_trace; /** current process id (i.e. MPI-rank) */
789 EXTERN int vt_my_ptrace; /** parent process id */
790 EXTERN uint8_t vt_my_trace_is_master; /** 1st process on local node? */
791 EXTERN uint8_t vt_my_trace_is_disabled; /** process disabled? */
792 EXTERN uint8_t vt_my_trace_is_first_avail; /** 1st not disabled process? */
793 EXTERN int vt_my_funique; /** unique file id */
794 
795 /** array of indices for internal regions */
796 EXTERN uint32_t vt_trc_regid[VT__TRC_REGID_NUM];
797 
798 /** array of indices for internal markers (error, warnings, hints) */
799 EXTERN uint32_t vt_trc_mid[3];
800 
801 /** id of process group containing all processes */
802 EXTERN uint32_t vt_all_pgid;
803 
804 /** node process group id */
805 EXTERN uint32_t vt_node_pgid;
806 
807 /** counter group id for miscellaneous counters (e.g. cpu id) */
808 EXTERN uint32_t vt_misc_cgid;
809 
810 /** flag: indicates whether VampirTrace is initialized and ready to trace */
811 EXTERN uint8_t vt_is_alive;
812 
813 /** flag: indicates whether VampirTrace shall be closed if MPI_Finalize is
814  called */
815 EXTERN uint8_t vt_close_on_mpi_finalize;
816 
817 /** start time (set during vt_open() with vt_pform_wtime() */
818 EXTERN uint64_t vt_start_time;
819 
820 /** start time (µs after 00:00:00 UTC 1 January 1970) */
821 EXTERN uint64_t vt_start_time_epoch;
822 
823 #endif /* _VT_TRC_H */