NAME

PAPI_describe_event, PAPI_event_code_to_name, PAPI_event_name_to_code, PAPI_label_event - convert a hardware event to a description, label, number or string symbol.

CONTENTS

Synopsis
Description
Arguments
Return Values
Errors
Examples
Author
Bugs
See Also

C Interface

#include <papi.h> 

int PAPI_describe_event(char *EventName, int *EventCode, char *EventDescr); 

int PAPI_event_code_to_name(int EventCode, char *EventName); 

int PAPI_event_name_to_code(char *EventName, int *EventCode); 

int PAPI_label_event(int EventCode, char *EventLabel); 

Fortran Interface

#include fpapi.h 

PAPIF_describe_event(C_STRING EventName, C_INT EventCode, C_STRING EventDescr, C_INT check) 

PAPIF_event_code_to_name(C_INT EventCode, C_STRING EventName, C_INT check) 

PAPIF_event_name_to_code(C_STRING EventName, C_INT EventCode, C_INT check) 

PAPIF_label_event(C_INT EventCode, C_STRING EventLabel, C_INT check) 

PAPI_describe_event() is used to translate either an ASCII PAPI preset name or an integer PAPI preset event code into the corresponding event code or name as well as an ASCII description of that event. If the EventName argument is a string of length >0 it is assumed to contain the name to look up and the corresponding event code is returned in the argument EventCode. Otherwise the EventCode argument is used to look up the event name which is stored in the EventName argument. Finally a descriptive string of length less than PAPI_MAX_STR_LEN is copied to the argument EventDescr.

The functionality of this call is a superset of the following two calls.

PAPI_event_name_to_code() is used to translate an ASCII PAPI preset name into an integer PAPI event code.

PAPI_event_code_to_name() is used to translate an integer PAPI event code into an ASCII PAPI preset name.

PAPI_label_event() is used to translate an integer PAPI event code into a short (<=18 character) ASCII label that is more descriptive than the preset name but shorter than the description. These labels can be used as event identifiers in third party tools.

EventName -- a string containing the event name as listed in PAPI_presets (3)

EventCode -- the numeric code for the event

EventDescr -- a descriptive string for the event of length less than PAPI_MAX_STR_LEN.

EventLabel -- a short descriptive label for the event of length less than 18 characters.

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

PAPI_EINVAL
	One or more of the arguments is invalid.
PAPI_ENOTPRESET
	The hardware event specified is not a valid PAPI preset.

int EventCode, EventSet = PAPI_NULL;
char EventCodeStr[PAPI_MAX_STR_LEN];
char EventDescr[PAPI_MAX_STR_LEN];
char EventLabel[20];
        
/* Convert to integer */

if (PAPI_event_name_to_code("PAPI_TOT_INS",&EventCode) != PAPI_OK)
  handle_error(1);

/* Describe event from EventCode */
*EventCodeStr=’ ’; /* Erase the name argument to look up the code */
if (PAPI_describe_event(EventCodeStr,&EventCode,EventDescr) != PAPI_OK)
  handle_error(1);

/* Label event from EventCode */
if (PAPI_label_event(EventCode,EventLabel) != PAPI_OK)
  handle_error(1);

/* Print the differing text strings */
printf("Name: %s0abel: %s0escription: %s0,EventCodeStr,EventLabel,EventDescr);

/* 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, EventCode) != PAPI_OK)
  handle_error(1);

Philip J. Mucci <mucci@cs.utk.edu>

These functions have no known bugs.

PAPI_presets (3), PAPI_add_event (3), PAPI_set_opt (3), PAPI_query_event (3),
The PAPI Web Site: http://icl.cs.utk.edu/projects/papi