1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
.TH "PAPI_overflow" 3 "Mon Jun 30 2014" "Version 5.3.2.0" "PAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
PAPI_overflow \-
.PP
Set up an event set to begin registering overflows\&.
.SH SYNOPSIS
.br
.PP
.SH "Detailed Description"
.PP
\fBPAPI_overflow()\fP marks a specific EventCode in an EventSet to generate an overflow signal after every threshold events are counted\&. More than one event in an event set can be used to trigger overflows\&. In such cases, the user must call this function once for each overflowing event\&. To turn off overflow on a specified event, call this function with a threshold value of 0\&.
.PP
Overflows can be implemented in either software or hardware, but the scope is the entire event set\&. PAPI defaults to hardware overflow if it is available\&. In the case of software overflow, a periodic timer interrupt causes PAPI to compare the event counts against the threshold values and call the overflow handler if one or more events have exceeded their threshold\&. In the case of hardware overflow, the counters are typically set to the negative of the threshold value and count up to 0\&. This zero-crossing triggers a hardware interrupt that calls the overflow handler\&. Because of this counter interrupt, the counter values for overflowing counters may be very small or even negative numbers, and cannot be relied upon as accurate\&. In such cases the overflow handler can approximate the counts by supplying the threshold value whenever an overflow occurs\&.
.PP
_papi_overflow_handler() is a placeholder for a user-defined function to process overflow events\&. A pointer to this function is passed to the \fBPAPI_overflow\fP routine, where it is invoked whenever a software or hardware overflow occurs\&. This handler receives the EventSet of the overflowing event, the Program Counter address when the interrupt occured, an overflow_vector that can be processed to determined which event(s) caused the overflow, and a pointer to the machine context, which can be used in a platform-specific manor to extract register information about what was happening when the overflow occured\&.
.PP
\fBC Interface:\fP
.RS 4
#include <\fBpapi\&.h\fP>
.br
int \fBPAPI_overflow\fP (int EventSet, int EventCode, int threshold, int flags, PAPI_overflow_handler_t handler );
.br
.br
(*PAPI_overflow_handler_t) _papi_overflow_handler (int EventSet, void *address, long_long overflow_vector, void *context );
.RE
.PP
\fBFortran Interface:\fP
.RS 4
Not implemented
.RE
.PP
\fBParameters:\fP
.RS 4
\fIEventSet\fP -- an integer handle to a PAPI event set as created by \fBPAPI_create_eventset\fP
.br
\fIEventCode\fP -- the preset or native event code to be set for overflow detection\&. This event must have already been added to the EventSet\&.
.br
\fIthreshold\fP -- the overflow threshold value for this EventCode\&.
.br
\fIflags\fP -- bitmap that controls the overflow mode of operation\&. Set to PAPI_OVERFLOW_FORCE_SW to force software overflowing, even if hardware overflow support is available\&. If hardware overflow support is available on a given system, it will be the default mode of operation\&. There are situations where it is advantageous to use software overflow instead\&. Although software overflow is inherently less accurate, with more latency and processing overhead, it does allow for overflowing on derived events, and for the accurate recording of overflowing event counts\&. These two features are typically not available with hardware overflow\&. Only one type of overflow is allowed per event set, so setting one event to hardware overflow and another to forced software overflow will result in an error being returned\&.
.br
\fIhandler\fP -- pointer to the user supplied handler function to call upon overflow
.br
\fIaddress\fP -- the Program Counter address at the time of the overflow
.br
\fIoverflow_vector\fP -- a long long word containing flag bits to indicate which hardware counter(s) caused the overflow
.br
\fI*context\fP -- pointer to a machine specific structure that defines the register context at the time of overflow\&. This parameter is often unused and can be ignored in the user function\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIPAPI_OK\fP On success, \fBPAPI_overflow\fP returns PAPI_OK\&.
.br
\fIPAPI_EINVAL\fP One or more of the arguments is invalid\&. Most likely a bad threshold value\&.
.br
\fIPAPI_ENOMEM\fP Insufficient memory to complete the operation\&.
.br
\fIPAPI_ENOEVST\fP The EventSet specified does not exist\&.
.br
\fIPAPI_EISRUN\fP The EventSet is currently counting events\&.
.br
\fIPAPI_ECNFLCT\fP The underlying counter hardware cannot count this event and other events in the EventSet simultaneously\&. Also can happen if you are trying to overflow both by hardware and by forced software at the same time\&.
.br
\fIPAPI_ENOEVNT\fP The PAPI event is not available on the underlying hardware\&.
.RE
.PP
\fBExample\fP
.RS 4
.PP
.nf
* // Define a simple overflow handler:
* void handler(int EventSet, void *address, long_long overflow_vector, void *context)
* {
* fprintf(stderr,\"Overflow at %p! bit=%#llx \\n\",
* address,overflow_vector);
* }
*
* // Call PAPI_overflow for an EventSet containing PAPI_TOT_INS,
* // setting the threshold to 100000\&. Use the handler defined above\&.
* retval = PAPI_overflow(EventSet, PAPI_TOT_INS, 100000, 0, handler);
*
.fi
.PP
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBPAPI_get_overflow_event_index\fP
.RE
.PP
.SH "Author"
.PP
Generated automatically by Doxygen for PAPI from the source code\&.
|
