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

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 avail test case 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 native_avail test case 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.

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);

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_cleanup_eventset(3), PAPI_destroy_eventset(3), PAPI_event_code_to_name(3), PAPI_remove_events(3), PAPI_query_event(3), PAPI_presets(3), PAPI_native(3), PAPI_remove_event(3)