PAPI_overflow(3) PAPI PAPI_overflow(3)NAMEPAPI_overflow-
Set up an event set to begin registering overflows.
SYNOPSISDetailed DescriptionPAPI_overflow() 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.
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.
_papi_overflow_handler() is a placeholder for a user-defined function
to process overflow events. A pointer to this function is passed to the
PAPI_overflow 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.
C Interface:
#include <papi.h>
int PAPI_overflow (int EventSet, int EventCode, int threshold, int
flags, PAPI_overflow_handler_t handler );
(*PAPI_overflow_handler_t) _papi_overflow_handler (int EventSet,
void *address, long_long overflow_vector, void *context );
Fortran Interface:
Not implemented
Parameters:
EventSet -- an integer handle to a PAPI event set as created by
PAPI_create_eventset
EventCode -- the preset or native event code to be set for overflow
detection. This event must have already been added to the EventSet.
threshold -- the overflow threshold value for this EventCode.
flags -- 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.
handler -- pointer to the user supplied handler function to call
upon overflow
address -- the Program Counter address at the time of the overflow
overflow_vector -- a long long word containing flag bits to
indicate which hardware counter(s) caused the overflow
*context -- 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.
Return values:
PAPI_OK On success, PAPI_overflow returns PAPI_OK.
PAPI_EINVAL One or more of the arguments is invalid. Most likely a
bad threshold value.
PAPI_ENOMEM Insufficient memory to complete the operation.
PAPI_ENOEVST The EventSet specified does not exist.
PAPI_EISRUN The EventSet is currently counting events.
PAPI_ECNFLCT 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.
PAPI_ENOEVNT The PAPI event is not available on the underlying
hardware.
Example
// Define a simple overflow handler:
void handler(int EventSet, void *address, long_long overflow_vector, void *context)
{
fprintf(stderr,´Overflow at %p! bit=0x%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);
See also:
PAPI_get_overflow_event_index
Author
Generated automatically by Doxygen for PAPI from the source code.
Version 5.1.1.0 Tue May 21 2013 PAPI_overflow(3)
