papi_add_events(3) - Linux man page

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.

Return Values

On success, these functions return PAPI_OK. On error, a less than zero error code is returned or the the number of elements that succeeded before the error.

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.