Unix/Linux Go Back    


CentOS 7.0 - man page for papi_overflow (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PAPI_overflow(3)			       PAPI				 PAPI_overflow(3)

NAME
       PAPI_overflow -

       Set up an event set to begin registering overflows.

SYNOPSIS
Detailed Description
       PAPI_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,
	   *		 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.2.0.0 			 Tue Jun 17 2014			 PAPI_overflow(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:40 AM.