PAPI Software Specification

Introduction to PAPI Constants

The PAPI constants are defined in the header files:

papiStdEventDefs.h
papi.h

The header file papiStdEventDefs.h contains platform specific constants. These constants are presented in Table 1: Standardized Event Definitions below. The user should read the documentation that accompanies this table for an explanation of these constants.

The remaining header file papi.h contains the PAPI Return Codes , among other internal definitions.

Standardized Event Definitions

Value Symbol Description 0x80000000 PAPI_L1_DCM Level 1 data cache misses 0x80000001 PAPI_L1_ICM Level 1 instruction cache misses 0x80000002 PAPI_L2_DCM Level 2 data cache misses 0x80000003 PAPI_L2_ICM Level 2 instruction cache misses 0x80000004 PAPI_L3_DCM Level 3 data cache misses 0x80000005 PAPI_L3_ICM Level 3 instruction cache misses 0x80000006 PAPI_L1_TCM Level 1 total cache misses 0x80000007 PAPI_L2_TCM Level 2 total cache misses 0x80000008 PAPI_L3_TCM Level 3 total cache misses 0x80000009 PAPI_CA_SNP Snoops 0x8000000A PAPI_CA_SHR Request for access to shared cache line (SMP) 0x8000000B PAPI_CA_CLN Request for access to clean cache line (SMP) 0x8000000C PAPI_CA_INV Cache Line Invalidation (SMP) 0x8000000D PAPI_CA_ITV Cache Line Intervention (SMP) 0x8000000E PAPI_L3_LDM Level 3 load misses 0x8000000F PAPI_L3_STM Level 3 store misses 0x80000010 PAPI_BRU_IDL Cycles branch units are idle 0x80000011 PAPI_FXU_IDL Cycles integer units are idle 0x80000012 PAPI_FPU_IDL Cycles floating point units are idle 0x80000013 PAPI_LSU_IDL Cycles load/store units are idle 0x80000014 PAPI_TLB_DM Data translation lookaside buffer misses 0x80000015 PAPI_TLB_IM Instruction translation lookaside buffer misses 0x80000016 PAPI_TLB_TL Total translation lookaside buffer misses 0x80000017 PAPI_L1_LDM Level 1 load misses 0x80000018 PAPI_L1_STM Level 1 store misses 0x80000019 PAPI_L2_LDM Level 2 load misses 0x8000001A PAPI_L2_STM Level 2 store misses 0x8000001B PAPI_BTAC_M BTAC miss 0x8000001C PAPI_PRF_DM Prefetch data instruction caused a miss 0x8000001D PAPI_L3_DCH Level 3 Data Cache Hit 0x8000001E PAPI_TLB_SD Translation lookaside buffer shootdowns (SMP) 0x8000001F PAPI_CSR_FAL Failed store conditional instructions 0x80000020 PAPI_CSR_SUC Successful store conditional instructions 0x80000021 PAPI_CSR_TOT Total store conditional instructions 0x80000022 PAPI_MEM_SCY Cycles Stalled Waiting for Memory Access 0x80000023 PAPI_MEM_RCY Cycles Stalled Waiting for Memory Read 0x80000024 PAPI_MEM_WCY Cycles Stalled Waiting for Memory Write 0x80000025 PAPI_STL_ICY Cycles with No Instruction Issue 0x80000026 PAPI_FUL_ICY Cycles with Maximum Instruction Issue 0x80000027 PAPI_STL_CCY Cycles with No Instruction Completion 0x80000028 PAPI_FUL_CCY Cycles with Maximum Instruction Completion 0x80000029 PAPI_HW_INT Hardware interrupts 0x8000002A PAPI_BR_UCN Unconditional branch instructions executed 0x8000002B PAPI_BR_CN Conditional branch instructions executed 0x8000002C PAPI_BR_TKN Conditional branch instructions taken 0x8000002D PAPI_BR_NTK Conditional branch instructions not taken 0x8000002E PAPI_BR_MSP Conditional branch instructions mispredicted 0x8000002F PAPI_BR_PRC Conditional branch instructions correctly predicted 0x80000030 PAPI_FMA_INS FMA instructions completed 0x80000031 PAPI_TOT_IIS Total instructions issued 0x80000032 PAPI_TOT_INS Total instructions executed 0x80000033 PAPI_INT_INS Integer instructions executed 0x80000034 PAPI_FP_INS Floating point instructions executed 0x80000035 PAPI_LD_INS Load instructions executed 0x80000036 PAPI_SR_INS Store instructions executed 0x80000037 PAPI_BR_INS Total branch instructions executed 0x80000038 PAPI_VEC_INS Vector/SIMD instructions executed 0x80000039 PAPI_FLOPS Floating Point Instructions executed per second 0x8000003A PAPI_RES_STL Cycles processor is stalled on resource 0x8000003B PAPI_FP_STAL Cycles any FP units are stalled 0x8000003C PAPI_TOT_CYC Total cycles 0x8000003D PAPI_IPS Instructions executed per second 0x8000003E PAPI_LST_INS Total load/store instructions executed 0x8000003F PAPI_SYC_INS Sync. instructions executed 0x80000040 PAPI_L1_DCH L1 data cache hit 0x80000041 PAPI_L2_DCH L2 data cache hit 0x80000042 PAPI_L1_DCA L1 data cache access 0x80000043 PAPI_L2_DCA L2 data cache access 0x80000044 PAPI_L3_DCA L3 data cache access 0x80000045 PAPI_L1_DCR L1 data cache read 0x80000046 PAPI_L2_DCR L2 data cache read 0x80000047 PAPI_L3_DCR L3 data cache read 0x80000048 PAPI_L1_DCW L1 data cache write 0x80000049 PAPI_L2_DCW L2 data cache write 0x8000004A PAPI_L3_DCW L3 data cache write 0x8000004B PAPI_L1_ICH L1 instruction cache hits 0x8000004C PAPI_L2_ICH L2 instruction cache hits 0x8000004D PAPI_L3_ICH L3 instruction cache hits 0x8000004E PAPI_L1_ICA L1 instruction cache accesses 0x8000004F PAPI_L2_ICA L2 instruction cache accesses 0x80000050 PAPI_L3_ICA L3 instruction cache accesses 0x80000051 PAPI_L1_ICR L1 instruction cache reads 0x80000052 PAPI_L2_ICR L2 instruction cache reads 0x80000053 PAPI_L3_ICR L3 instruction cache reads 0x80000054 PAPI_L1_ICW L1 instruction cache writes 0x80000055 PAPI_L2_ICW L2 instruction cache writes 0x80000056 PAPI_L3_ICW L3 instruction cache writes 0x80000057 PAPI_L1_TCH L1 total cache hits 0x80000058 PAPI_L2_TCH L2 total cache hits 0x80000059 PAPI_L3_TCH L3 total cache hits 0x8000005A PAPI_L1_TCA L1 total cache accesses 0x8000005B PAPI_L2_TCA L2 total cache accesses 0x8000005C PAPI_L3_TCA L3 total cache accesses 0x8000005D PAPI_L1_TCR L1 total cache reads 0x8000005E PAPI_L2_TCR L2 total cache reads 0x8000005F PAPI_L3_TCR L3 total cache reads 0x80000060 PAPI_L1_TCW L1 total cache writes 0x80000061 PAPI_L2_TCW L2 total cache writes 0x80000062 PAPI_L3_TCW L3 total cache writes 0x80000063 PAPI_FML_INS Floating Multiply instructions 0x80000064 PAPI_FAD_INS Floating Add instructions 0x80000065 PAPI_FDV_INS Floating Divide instructions 0x80000066 PAPI_FSQ_INS Floating Sqare Root instructions 0x80000067 PAPI_FNV_INS Floating Inverse instructions

Table 1: Standardized Event Definitions

Return Codes

All of the functions contained in the PAPI APIs return standardized error codes. Values greater than or equal to zero indicate success, less than zero indicates failure.

The Low Level API

int PAPI_accum (int EventSet, long long *values)

This function accumulates (adds) the running or stopped counters in EventSet into the values array. In addition, it re-initializes the internal counters to zero.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

This function modifies an existing EventSet. Separate EventSets containing events that require use of the same hardware may exist, but may not be started if a conflicting EventSet is running. Returns the error code PAPI_ENOEVNT if Event cannot be counted on this platform. The addition of a conflicting event to an event set will return an error unless PAPI_SET_MPXRES has been set. Note: EventSet 0 may not be used; it has been reserved for internal use.

The return value is an integer that indicates whether the call succeeded (a positive integer corresponding to the index in the EventCodeArray where this event is stored) or failed (an error code).

int PAPI_add_events (int *EventSet, int *Events, int number)

This function modifies an existing EventSet. The Events contained in *Events will be loaded into the EventSet. Separate EventSets containing events that require use of the same hardware may exist, but may not be started if a conflicting EventSet is running. If one or more of the items in Events cannot be counted on this platform, this function returns the error code PAPI_ENOEVNT. In addition, the invalid entries in the Events array are set to PAPI_NULL, such that the user can successfully reissue the call. The addition of a conflicting event to an event set will return an error unless PAPI_SET_MPXRES has been set. Note: EventSet 0 may not be used; it has been reserved for internal use.

The return value is an integer that indicates whether the call succeeded (a positive integer corresponding to the index in the EventCodeArray where this event is stored) or failed (an error code).

int PAPI_add_pevent (int *EventSet, int code, void *inout)

This function adds a native programmable Event to an existing EventSet. Such EventSets can only consist of one event, namely that which is specified in this call. Its semantics are very similar to that of ioctl() system call. inout points to an opaque data structure that is specific to the value in code. Higher level macros may be provided in the header file. Please check the documentation for each substrate. This function has a C binding only. (not yet implemented)

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_cleanup_eventset (int *EventSet)

This function effectively cleans the target EventSet. It removes all of the hardware events which have been added to the EventSet. It can then be removed from existence with a call to PAPI_destroy_eventset. The EventSet must be stopped in order for this call to succeed.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_create_eventset (int *EventSet)

This function creates a new EventSet for use. This call is not thread safe.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_describe_event (char *name, int *EventCode, char *description)

This function identifies a PAPI_Event in one of two ways.

Given the name of the Event (i.e. "PAPI_INT_INS"), the function will write the corresponding value in EventCode (51) and a descriptive string ("Integer Instructions") to the description buffer.

Given the integer value of EventCode (51), the function will write the string value of the EventName ("PAPI_INT_INS") to the name buffer and a descriptive string ("Integer Instructions") to the description buffer.

Set *description to NULL if the description is not needed.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_label_event (int *EventCode, char *label)

Given an integer EventCode, this function will return a short string to the label buffer. This string is appropriate to use as an event label for third party tools.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_destroy_eventset (int *EventSet )

This function effectively removes an EventSet from existence. The EventSet must be empty in order for this call to succeed.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

const PAPI_exe_info_t *PAPI_get_executable_info (void)

This function returns a pointer to a structure of type PAPI_exe_info_t, which contains path, name, start and end addresses for the program's text, data, and bss segments. For the definition of the structure, see papi.h Returns pointer to structure of type PAPI_exe_info_t if successful, and NULL if otherwise.

This function returns a pointer to a structure of type PAPI_hw_info_t, which contains number of CPUs, nodes, vendor number/name for CPU, CPU revision, clock speed. For the definition of the structure, see papi.h Returns pointer to structure of type PAPI_hw_info_t if successful, and NULL if otherwise.

int PAPI_get_opt (int option, PAPI_option_t *ptr)

This function queries the status of tunable options in the PerfAPI Library. "option" is an input/output parameter. The "ptr" structure is for input and output. Not all options fill the PAPI_option_t structure. This function has a C binding only.

The reader is urged to carefully read the PerfAPI Draft for a complete discussion of PAPI_get_opt. The file papi.h contains definitions for the structures unioned in the PAPI_option_t structure.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

Returns overflow address if successful, appropriate error code otherwise. Typically called inside the overflow handler routine. See PAPI_overflow().

This function returns a value in cycles, and can be used at the beginning and end of a section of code to calculate number of total cycles elapsed while the section executed. Returns time of type long long if successful, appropriate error code otherwise.

long long PAPI_get_real_usec (void)

This function returns a real (wall) time in micro seconds, and can be used at the beginning and end of a section of code to calculate real time in micro seconds for the section. Returns time of type long long if successful, appropriate error code otherwise.

This function returns a value in cycles, and can be used at the beginning and end of a section of code to calculate number of virtual (process or thread) cycles elapsed in the section. Returns time of type long long if successful, appropriate error code otherwise.

long long PAPI_get_virt_usec (void)

This function returns a virtual time in micro seconds, and can be used at the beginning and end of a section of code to calculate user time in micro seconds for the section. Returns time of type long long if successful, appropriate error code otherwise.

int PAPI_library_init (int version)

This function initializes the PAPI library and has to be called before the low level PAPI can be used. The argument should always be set to PAPI_VER_CURRENT. The reason for this is that you may be linked with a shared library, so this will detect version skew. Don't forget PAPI_thread_init also has to be called before low level PAPI calls can be used in a threaded application.

This function decomposes EventSet into the hardware Events it contains. number is both an input and output parameter.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

void PAPI_lock (void)

Grabs access to the PAPI mutex variable. This function is provided to the user to have a platform independent call to an (hopefully) efficiently implemented mutex. This function has no return value.

void PAPI_unlock (void)

Unlocks the mutex acquired by a call to PAPI_lock() . This function has no return value.

int PAPI_multiplex_init (int EventSet, int *Events, int *number)

This function enables and initializes multiplex support in the PAPI library. This allows a user to count more events than there are physical counters by time sharing the existing counters at some loss in precision. Applications that make no use of multiplexing do not need to call this routine.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_set_multiplex (int EventSet)

This function converts a standard EventSet created by a call to PAPI_create_eventset() into an event set capable of handling multiplexed events. This must be done after calling PAPI_multiplex_init() , but prior to calling PAPI_start(). Events can be added to an eventset either before or after converting it into a multiplexed set, but the conversion must be done prior to using it as a multiplexed set.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_overflow (int EventSet, int EventCode, int threshold, int flags,
PAPI_overflow_handler_t handler)

This function sets up an EventSet such that when it is PAPI_start()'ed, it begins to register overflows. This EventSet may only have multiple events in it, but only 1 can be an overflow trigger. Subsequent calls to PAPI_overflow replace earlier calls. To turn off overflow, set the handler to NULL.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_perror (int code, char *destination, int length)

This function copies length worth of the error description string corresponding to code into destination. The resulting string is always null terminated. If length is 0, then the string is printed on stderr. The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

char *PAPI_strerror (int code)

This function returns the corresponding english error string from the passed code. Returns NULL if code is invalid.

int PAPI_profil (unsigned short *buf, unsigned bufsiz, unsigned long offset,
    unsigned scale, int EventSet, int EventCode, int threshold, int flags)

This function sets the values in the PAPI_sprofil_t structure, if profiling is to be enabled for this EventSet. The EventSet must be in the stopped state for this call to succeed.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_sprofil (PAPI_sprofil_t *prof, int profcnt, int EventSet,
    int EventCode, int threshold, int flags)

This function assumes a pre-initialized PAPI_sprofil_t structure and enables profiling for this EventSet. The EventSet must be in the stopped state for this call to succeed.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_query_event (int EventCode)

This function tests if the event designated by EventCode is supported by the current substrate.

If the answer is yes, the function returns PAPI_OK. If the answer is no, the function returns an error code.

int PAPI_query_event_verbose (int EventCode, PAPI_preset_info_t *info)

This function returns description about queried event if it is supported on the current platform. Returns PAPI_OK if successful, and appropriate error code otherwise.

Returns structure containing all PAPI presets, regardless of implementation on current platform. The return structure is of type PAPI_preset_info_t (see papi.h).

This function translates an EventCode from the user into the event name used by PAPI. Return code is PAPI_OK if successful, and appropriate error code otherwise.

This function translates an event name to PAPI event code. Return value is PAPI_OK if successful and appropriate error code otherwise.

This function copies the running or stopped counters in EventSet into the values array. Internal counters will not be re-initialized to zero.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_rem_event (int *EventSet, int Event)

This function removes the hardware counter Event from EventSet.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_rem_events (int *EventSet, int *Events, int number)

This function removes the hardware counters listed in the Events array from EventSet.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_reset (int EventSet)

This function initializes the internal counters of the hardware Events contained in EventSet to zero.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_restore (void)

PAPI_save and PAPI_restore are for use with external libraries that wish to preserve the state of PAPI and the hardware counters. For instance a C++ instrumentation library will probably want to call PAPI_save() upon entry to it's functions and PAPI_restore() upon exit. These function calls map to whatever is the most efficient on the underlying platform for saving and restoring. Returns PAPI_OK if successful, and appropriate error code otherwise. (not yet implemented)

see above description (not yet implemented)

This function sets the default debug level for the PAPI library to one of three debug levels as defined in the papi.h header file. The current debug level is internally stored in the PAPI library and is used by the default internal PAPI error handler subroutine. The error handler is called by library routines on the occurence of recoverable errors.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_set_domain (int domain)

This function sets the execution domain in which events are counted. Here domain is one of the constants PAPI_DOM_USER, PAPI_DOM_MIN, PAPI_DOM_KERNEL, PAPI_DOM_OTHER, PAPI_DOM_ALL, PAPI_DOM_MAX, or PAPI_DOM_HWSPEC as defined in the header file. These constants are listed below and can also be found in the online PerfAPI Draft. The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_set_granularity (int granularity)

This function sets the measurement granularity in which the counters function. By default, the granularity is set to the most restrictive supported by the substrate. Returns PAPI_OK if successful, and appropriate error code otherwise. Granularity settings include per thread, process, process group, current cpu, and each cpu. For more information, see papi.h

This function sets specific options of the PerfAPI Library, its substrate, or specific EventSets. The PAPI_option_t structure represents a union of all the structures that can be arguments to the different options. In addition, there may exist machine specific options so please check the header file for documentation. This function has a C binding only.

The reader is urged to carefully read the PerfAPI Draft for a complete discussion of PAPI_set_opt. The file papi.h contains definitions for the structures unioned in the PAPI_option_t structure.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

void PAPI_shutdown (void)

This is an exit function used by the PAPI Library to free resources and shut down when certain error conditions arise. This call is not necessary, but allows the user the capability to free memory and resources used by the PAPI Library.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_start (int EventSet)

This function starts counting all of the hardware events contained in EventSet. All counters are implicitly set to zero. PAPI_start() will not start the hardware counters if a conflicting EventSet is already running and the counters are already in use.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_state (int EventSet, int *status)

This function returns the state of the entire EventSet in status. If the call succeeds, then status is either PAPI_RUNNING or PAPI_STOPPED.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_stop (int EventSet, long long *values)

This function terminates the counting of all hardware events contained in EventSet. In addition, the counters contained in that EventSet are copied into the values array.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

int PAPI_thread_init (unsigned long int (*handle)(), int flag)

This function initializes thread support. The first argument is a pointer to a function that returns the Thread ID of the currently running thread. The flag argument is currently not used and should be set to zero.

The return value is an integer that indicates whether the call succeeded (PAPI_OK) or failed (not PAPI_OK).

unsigned long int PAPI_thread_id (void)

This function calls the thread id function registered by PAPI_thread_init().

The return value is an unsigned long integer representing the thread id or (unsigned long int)-1.

int PAPI_write (int EventSet, long long *values)

This function assigns the values contained in the values array to the internal counters of the Events contained in the EventSet. Returns PAPI_OK if successful, and appropriate error code otherwise.

The High Level API

int PAPI_num_counters(void)

This function returns the optimal length of the values array for the high level functions. This value corresponds to the number of hardware counters supported by the current substrate.

Start counting the events named in the events array. This function implicitly stops and initializes any counters running as a result of a previous call to PAPI_start_counters(). It is the user's responsibility to choose events that can be counted simultaneously by reading the vendor's documentation. The length of this array should be no longer than PAPI_MAX_EVENTS. Returns PAPI_OK if successful, and an appropriate error code otherwise.

Read the running counter values into the values array. This call implicitly re-initializes the counters to zero and lets them continue to run upon return. Returns PAPI_OK if successful, and an appropriate error code otherwise.

Add the running counter values to the values in the values array. This call implicitly re-initializes the counters to zero and lets them continue to run upon return. Returns PAPI_OK if successful, and an appropriate error code otherwise.

Stop the running counters and copy the counts into the values array. This is to be used in conjunction with PAPI_start_counters. Returns PAPI_OK if successful, and an appropriate error code otherwise.

Simplified single call to measure the number of floating point instructions executed and the MegaFlop rate, defined as the number of floating point instructions per microsecond. Note that not all floating point instructions are created equal: Some platforms implement a floating point multiply/add (FMA) as a single instruction; and a floating point square root is often more costly than a floating point add. Caution must be used in comparing measurements on different platforms. Each call to PAPI_flops returns the real (clock) time and process time, floating point instructions executed, and MFlops for the period since the last call. A call to PAPI_flops with flpins = -1 resets the counters. Returns PAPI_OK if successful, and an appropriate error code otherwise.