.TH "PAPI_overflow" 3 "Mon Dec 18 2017" "Version 5.6.0.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\&.