.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\&.