1PAPI_overflow(3) PAPI PAPI_overflow(3)
2
6 PAPI_overflow - set up an event set to begin registering overflows
7 _papi_overflow_handler - user defined function to process overflow
8 events
9
12 C Interface
13 #include <papi.h>
14 int PAPI_overflow
15 (int EventSet, int EventCode, int threshold, int flags, PAPI_overflow_handler_t handler);
16 (*PAPI_overflow_handler_t) _papi_overflow_handler
17 (int EventSet, void * address, long_long overflow_vector, void * context);
18 Fortran Interface
19 Not implemented
20
23 PAPI_overflow() marks a specific EventCode in an EventSet to generate
24 an overflow signal after every threshold events are counted. More than
25 one event in an event set can be used to trigger overflows. In such
26 cases, the user must call this function once for each overflowing
27 event. To turn off overflow on a specified event, call this function
28 with a threshold value of 0.
29 Overflows can be implemented in either software or hardware, but the
31 scope is the entire event set. PAPI defaults to hardware overflow if it
32 is available. In the case of software overflow, a periodic timer
33 interrupt causes PAPI to compare the event counts against the threshold
34 values and call the overflow handler if one or more events have
35 exceeded their threshold. In the case of hardware overflow, the coun‐
36 ters are typically set to the negative of the threshold value and count
37 up to 0. This zero-crossing triggers a hardware interrupt that calls
38 the overflow handler. Because of this counter interrupt, the counter
39 values for overflowing counters may be very small or even negative num‐
40 bers, and cannot be relied upon as accurate. In such cases the overflow
41 handler can approximate the counts by supplying the threshold value
42 whenever an overflow occurs.
43 _papi_overflow_handler() is a placeholder for a user-defined function
45 to process overflow events. A pointer to this function is passed to
46 the PAPI_overflow routine, where it is invoked whenever a software or
47 hardware overflow occurs. This handler receives the EventSet of the
48 overflowing event, the Program Counter address when the interrupt
49 occured, an overflow_vector that can be processed to determined which
50 event(s) caused the overflow, and a pointer to the machine context,
51 which can be used in a platform-specific manor to extract register
52 information about what was happening when the overflow occured.
53
56 EventSet -- an integer handle to a PAPI event set as created by
57 PAPI_create_eventset(3)
58 EventCode -- the preset or native event code to be set for overflow
60 detection. This event must have already been added to the EvenSet.
61 threshold -- the overflow threshold value for this EventCode.
63 flags -- bit map that controls the overflow mode of operation. Set to
65 PAPI_OVERFLOW_FORCE_SW to force software overflowing, even if hardware
66 overflow support is available. If hardware overflow support is avail‐
67 able on a given system, it will be the default mode of operation. There
68 are situations where it is advantageous to use software overflow
69 instead. Although software overflow is inherently less accurate, with
70 more latency and processing overhead, it does allow for overflowing on
71 derived events, and for the accurate recording of overflowing event
72 counts. These two features are typically not available with hardware
73 overflow. Only one type of overflow is allowed per event set, so set‐
74 ting one event to hardware overflow and another to forced software
75 overflow will result in an error being returned.
76 handler -- pointer to the user supplied handler function to call upon
78 overflow
79 address -- the Program Counter address at the time of the overflow
81 overflow_vector -- a long_long word containing flag bits to indicate
83 which hardware counter(s) caused the overflow
84 *context -- pointer to a machine specific structure that defines the
86 register context at the time of overflow. This parameter is often
87 unused and can be ignored in the user function.
88
90 On success, PAPI_overflow returns PAPI_OK. On error, a non-zero error
91 code is returned. _papi_overflow_handler is a void function and
92 returns nothing.
93
96 PAPI_EINVAL
97 One or more of the arguments is invalid. Specifically, a bad
98 threshold value.
99 PAPI_ENOMEM
101 Insufficient memory to complete the operation.
102 PAPI_ENOEVST
104 The EventSet specified does not exist.
105 PAPI_EISRUN
107 The EventSet is currently counting events.
108 PAPI_ECNFLCT
110 The underlying counter hardware cannot count this event and
111 other events in the EventSet simultaneously. Or you are trying
112 to overflow both by hardware and by forced software at the same
113 time.
114 PAPI_ENOEVNT
116 The PAPI preset is not available on the underlying hardware.
117
120 Define a simple overflow handler:
121 void handler(int EventSet, void *address, long_long overflow_vector, void *context)
122 {
123 fprintf(stderr,"Overflow at %p! bit=0x%llx \n",
124 address,overflow_vector);
125 }
126 Call PAPI_overflow for an event set containing the PAPI_TOT_INS event,
128 setting the threshold to 100000. Use the handler defined above.
129 retval = PAPI_overflow(EventSet, PAPI_TOT_INS, 100000, 0, handler);
130
133 This function has no known bugs.
134
137 PAPI_get_overflow_event_index(3)
138PAPI Programmer's Reference September, 2004 PAPI_overflow(3)