NAME

PAPI_add_event, PAPI_add_events - add PAPI preset or native hardware event to an event set

CONTENTS

Synopsis
Description
Arguments
Return Values
Errors
Examples
Authors
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 a hardware event to a PAPI Event Set. 

PAPI_add_events() does the same, but for an array of hardware event codes. 

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

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.

RETURN VALUES

On success, these functions return PAPI_OK. On error, a non-zero error code is returned.

ERRORS

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.

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 (0xc1 on hardware counter 1) */

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

/* Start counting */

if (PAPI_start(EventSet) != PAPI_OK) handle_error(1);

AUTHORS

The PAPI Team. See them at the PAPI Web Site: http://icl.cs.utk.edu/projects/papi

BUGS

These functions have no known bugs.

SEE ALSO

PAPI_presets (3), PAPI_set_opt (3), PAPI_start (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 Programmer’s Reference PAPI_add_event (3) November, 2003

  Innovative Computing Laboratory
2001 R&D Winner  
Contact PAPI: papi@cs.utk.edu Computer Science Department
  University of Tennessee