PAPIC:EventSets
From PAPIDocs
Jump to: navigation, search

Contents

EVENT SETS

Event Sets are user-defined groups of hardware events (preset or native), which are used in conjunction with one another to provide meaningful information. The user specifies the events to be added to an Event Set, and other attributes, such as: the counting domain (user or kernel), whether or not the events in the Event Set are to be multiplexed, and whether the Event Set is to be used for overflow or profiling. Other settings for the Event Set are maintained by PAPI, such as: what low-level hardware registers to use, the most recently read counter values, and the state of the Event Set (running/not running). Event Sets provide an effective abstraction for the organization of information associated with counting hardware events. The PAPI library manages the memory for Event Sets with a user interface through integer handles to simplify calling conventions. The user is free to allocate and use any number of them provided the substrate can provide the required resources. Only one Event Set can be in active use at any time in a given thread or process.


CREATING AN EVENT SET

An event set can be created by calling the following the low-level function:

C:

 
PAPI_create_eventset (''*EventSet'')

 

Fortran:

 
PAPIF_create_eventset(''EventSet, ''check)

 


ARGUMENT

EventSet -- Address of an integer location to store the new EventSet handle.

Once it has been created, the user may add hardware events to the EventSet by calling PAPI_add_event or PAPI_add_events.

On success, this function returns PAPI_OK. On error, a non-zero error code is returned.

For a code example using this function, see the next section.


ADDING EVENTS TO AN EVENT SET

Hardware events can be added to an event set by calling the following the low-level functions:

C:

 
PAPI_add_event(''EventSet, EventCode'')
PAPI_add_events(''EventSet, *EventCode, number'')

 

Fortran:

 
PAPIF_add_event(''EventSet, EventCode, ''check)
PAPIF_add_events(''EventSet, EventCode, number, ''check)

 


ARGUMENTS
 
''EventSet'' -- an integer handle for a PAPI Event Set as created by PAPI_create_eventset.
''EventCode'' -- a defined event such as PAPI_TOT_INS. 
''*EventCode'' – address of an array of defined events. 
''number'' -- an integer indicating the number of events in the array ''*''''EventCode''.

 

PAPI_add_event adds a single hardware event to a PAPI event set.

PAPI_add_events does the same as PAPI_add_event, but for an array of hardware event codes.

In the following code example, the preset event, PAPI_TOT_INS is added to an event set:

 
#include <papi.h>
#include <stdio.h>

main()
{
int EventSet = PAPI_NULL;
int retval;

/* Initialize the PAPI library */
retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr, "PAPI library init error!\n");
  exit(1); 
}

/* Create an EventSet */ 
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);
}
 


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


Starting, Reading, Adding to, and Stopping an Event Set

Hardware events in an event set can be started, read, added, and stopped by calling the following low-level functions, respectively:

C:

 
PAPI_start(''EventSet'')
PAPI_read(''EventSet, *values'')
PAPI_accum(''EventSet'', ''*values'')
PAPI_stop(''EventSet, *values'')

 

Fortran:

 
PAPIF_start(''EventSet,'' check)
PAPIF_read(''EventSet, values,'' check)
PAPIF_accum(''EventSet'', ''values'', check)
PAPIF_stop(''EventSet, values,'' check)

 


ARGUMENTS
 
''EventSet'' -- an integer handle for a PAPI Event Set as created by PAPI_create_eventset.
''*values'' -- an array to hold the counter values of the counting events.

 

PAPI_start starts the counting events in a previously defined event set.

PAPI_read reads (copies) the counters of the indicated event set into the array, values. The counters are left counting after the read without resetting.

PAPI_accum adds the counters of the indicated event set into the array, values. The counters are reset and left counting after the call of this function.

PAPI_stop stops the counting events in a previously defined event set and returns the current events.

The following is a code example of using PAPI_start to start the counting of events in an event set, PAPI_read to read the counters of the same event set into the array values, and PAPI_stop to stop the counting of events in the event set:

 
#include <papi.h>
#include <stdio.h>
    
main()
{
int retval, EventSet = PAPI_NULL;
long_long values[1];

/* Initialize the PAPI library */
retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr, "PAPI library init error!\n");
  exit(1);
}

/* Create the Event Set */
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);

/* Start counting */
if (PAPI_start(EventSet) != PAPI_OK)
    handle_error(1);

/* Do some computation here */

if (PAPI_read(EventSet, values) != PAPI_OK)
    handle_error(1);

/* Do some computation here */

if (PAPI_stop(EventSet, values) != PAPI_OK)
    handle_error(1);
}
 


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

RESETTING EVENTS IN AN EVENT SET

The hardware event counts in an event set can be reset to zero by calling the following low-level function:

C:

 
PAPI_reset(''EventSet'')

 

Fortran:

 
PAPI_reset(''EventSet'', check)

 


ARGUMENT

EventSet -- an integer handle for a PAPI event set as created by PAPI_create_eventset.

For example, the EventSet in the code example of the previous section could have been reset to zero by adding the following lines:

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

 

On success, this function returns PAPI_OK and on error, a non-zero error code is returned.


REMOVING EVENTS IN AN EVENT SET

A hardware event and an array of hardware events can be removed from an event set by calling the following low-level functions, respectively:

C:

 
PAPI_remove_event(''EventSet'', ''EventCode'')


  <pre> 
PAPI_remove_events(''EventSet'', ''EventCode'', ''number'')

 

Fortran:

 
PAPIF_remove_event(''EventSet'', ''EventCode'', check)
PAPIF_remove_events(''EventSet'', ''EventCode'', ''number'', check)

 


ARGUMENTS
 
''EventSet'' -- an integer handle for a PAPI event set as created by PAPI_create_eventset.
''EventCode'' -- a defined event such as PAPI_TOT_INS or a native event. 
''*EventCode'' -- an array of defined events.
''number'' -- an integer indicating the number of events in the array ''*EventCode''.

 

PAPI_remove_event removes a single hardware event from a PAPI event set.

PAPI_remove_events, does the same as PAPI_remove_event, but for an array of hardware event codes.

In the following code example, PAPI_remove_event is used to remove the event, PAPI_TOT_INS, from an event set:

 
#include <papi.h>
#include <stdio.h>
main()
{
int retval, EventSet = PAPI_NULL;

/* Initialize the PAPI library */
retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr, "PAPI library init error!\n");
  exit(1);
}

/* Create an EventSet */ 
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);

/* Remove event */
if (PAPI_remove_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
  handle_error(1);
}
 


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


EMPTYING AND DESTROYING AN EVENT SET

All the events in an event set can be emptied and destroyed by calling the following low-level functions, respectively:

C:

 
PAPI_cleanup_eventset(''EventSet'')
PAPI_destroy_eventset(''EventSet'')

 

Fortran:

 
PAPIF_cleanup_eventset(''EventSet'', check)
PAPIF_destroy_eventset(''EventSet'', check)

 


ARGUMENT

EventSet -- an integer handle for a PAPI event set as created by PAPI_create_eventset.

Note that the event set must be empty in order to use'PAPI_destroy_eventset'.

In the following code example, PAPI_cleanup_eventset is used to empty all the events from an event set and PAPI_remove_eventset is used to deallocate the memory associated with the empty event set:

 
#include <papi.h>
#include <stdio.h>
   
main()
{
int retval, EventSet = PAPI_NULL;

/* Initialize the PAPI library */
retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr, "PAPI library init error!\n");
  exit(1);
}

/* Create the EventSet */ 
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);

/* Remove all events in the eventset */
if (PAPI_cleanup_eventset(&EventSet) != PAPI_OK)
  handle_error(1);

/* Free all memory and data structures, EventSet must be empty. */
if (PAPI_destroy_eventset(&EventSet) != PAPI_OK)
  handle_error(1);
}
 


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


THE STATE OF AN EVENT SET

The counting state of an Event Set can be obtained by calling the following low-level function:

C:

 
PAPI_state(''EventSet, *status'')
	
 

Fortran:

 
PAPIF_state(''EventSet'', ''status'', check)

 


ARGUMENTS

EventSet -- an integer handle for a PAPI event set as created by PAPI_create_eventset.

status -- an integer containing a Boolean combination of one or more of the following nonzero constants as defined in the PAPI header file, papi.h:

PAPI_STOPPED EventSet is stopped
PAPI_RUNNING EventSet is running
PAPI_PAUSED EventSet temporarily disabled by the library
PAPI_NOT_INIT EventSet defined, but not initialized
PAPI_OVERFLOWING EventSet has overflow enabled
PAPI_PROFILING EventSet has profiling enabled
PAPI_MULTIPLEXING EventSet has multiplexing enabled
PAPI_ATTACHED EventSet is attached to another thread/process


In the following code example, PAPI_state is used to return the counting state of an EventSet:

 
#include <papi.h>
#include <stdio.h>

main ()
{
int retval, status = 0, EventSet = PAPI_NULL;

/* Initialize the PAPI library */
retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr, "PAPI library init error!\n");
  exit(1);
}

/* Create the EventSet */
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);

/* Start counting */
if (PAPI_state(EventSet, &status) != PAPI_OK)
  handle_error(1);

printf("State is now %d\n", status);

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

if (PAPI_state(EventSet, &status) != PAPI_OK)
  handle_error(1);

printf("State is now %d\n", status);
}
 



OUTPUT:
 
State is now 1
State is now 2
 


On success, this function returns PAPI_OK and on error, a non-zero error code is returned.