NAME
PAPI_add_event - add PAPI preset or native hardware event to an event set
PAPI_add_events - add PAPI presets or native hardware events to an event set
CONTENTS
Synopsis
Description
Arguments
Return Values
Errors
Examples
Ibm Power6 Notes
Bugs
See Also
SYNOPSIS
C Interface
#include <papi.h>
int PAPI_add_event(int EventSet, int EventCode);
int PAPI_add_events(int EventSet, int *EventCodes, int number);
Fortran Interface
#include fpapi.h
PAPIF_add_event(C_INT EventSet, C_INT EventCode, C_INT check)
PAPIF_add_events(C_INT EventSet, C_INT(*) EventCodes, C_INT number, C_INT check)
DESCRIPTION
PAPI_add_event() adds one event to a PAPI Event Set.
PAPI_add_events() does the same, but for an array of events.
A hardware event can be either a PAPI preset or a native hardware event code.
For a list of PAPI preset events, see
PAPI_presets (3) or run the
utils/papi_avail utility in the PAPI distribution. PAPI presets can be passed to
PAPI_query_event (3) to see if they exist on the underlying architecture.
For a list of native events available on current platform, run the
utils/papi_native_avail utility in the PAPI distribution. For the encoding of native events, see
PAPI_event_name_to_code (3) to learn how to generate native code for the supported native event on the underlying architecture.
ARGUMENTS
EventSet -- an integer handle for a PAPI Event Set as created by
PAPI_create_eventset (3)
EventCode -- a defined event such as PAPI_TOT_INS.
*EventCode -- an array of defined events
number -- an integer indicating the number of events in the array
*EventCode
It should be noted that
PAPI_add_events can partially succeed, exactly like
PAPI_remove_events.
RETURN VALUES
On success, these functions return
PAPI_OK.
On error a negative error code, or a positive number of elements that succeeded before the error, is returned.
ERRORS
Positive integer | |
The number of consecutive elements that succeeded before the error.
|
PAPI_EINVAL | |
One or more of the arguments is invalid.
|
PAPI_ENOMEM | |
Insufficient memory to complete the operation.
|
PAPI_ENOEVST | |
The event set specified does not exist.
|
PAPI_EISRUN | |
The event set is currently counting events.
|
PAPI_ECNFLCT | |
The underlying counter hardware can not count this event and other events
in the event set simultaneously.
|
PAPI_ENOEVNT | |
The PAPI preset is not available on the underlying hardware.
|
PAPI_EBUG | |
Internal error, please send mail to the developers.
|
|
EXAMPLES
int EventSet = PAPI_NULL;
unsigned int native = 0x0;
if (PAPI_create_eventset(&EventSet) != PAPI_OK)
handle_error(1);
/* Add Total Instructions Executed to our EventSet */
if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
handle_error(1);
/* Add native event PM_CYC to EventSet */
if (PAPI_event_name_to_code("PM_CYC",&native) != PAPI_OK)
handle_error(1);
if (PAPI_add_event(EventSet, native) != PAPI_OK)
handle_error(1);
IBM POWER6 NOTES
Event counters 5 and 6 in the IBM POWER6 are restricted:
o Each can count just a single, fixed event.
o They are free-running and so can count only in the combined domain - PAPI_DOM_USER | PAPI_DOM_KERNEL | PAPI_DOM_SUPERVISOR.
o They cannot interrupt on overflow.
Although counter 6 counts processor cycles gated by the run latch
(PM_RUN_CYC), the current implementation maps the PAPI preset event
PAPI_TOT_CYC to PM_CYC because of the domain and overflow limitations of
counter 6. PM_CYC can be counted with relatively few other
events, so its likely that you will receive PAPI_ECNFLCT if you try to add
PAPI_TOT_CYC to an event set that already contains other events. If you
can use the above mentioned combined domain and do not need the overflow
capability, you should consider adding the native event PM_RUN_CYC instead
of PAPI_TOT_CYC.
Counter 5 counts the native event PM_RUN_INST_CMPL, which is instructions
completed gated by the run latch. For the same reasons given for counter
6, PAPI_TOT_INS is mapped to PM_INST_CMPL instead of PM_RUN_INST_CMPL. And
as above, if you try to add PAPI_TOT_INS to an event group with other
events already in it, you are likely to receive PAPI_ECNFLCT. If you can
use the above combined domain and do not need the overflow capability, you
should consider adding the native event PM_RUN_INST_CMPL instead of
PAPI_TOT_INS.
BUGS
The vector function should take a pointer to a length argument so a proper return value can
be set upon partial success.
SEE ALSO
PAPI_presets (3),
PAPI_native (3),
PAPI_remove_event (3),
PAPI_remove_events (3),
PAPI_query_event (3),
PAPI_cleanup_eventset (3),
PAPI_destroy_eventset (3),
PAPI_event_code_to_name (3)
PAPI Programmers Reference | PAPI_add_event (3) | September, 2004 |
|
|