PAPI Software Specification

This software specification describes the PAPI 2.1.0 Release, and is current as of December 18, 2001. It consists of the following sections:

Introduction to PAPI Constants
Standardized Event Definitions
Return Codes
Low Level API
High Level API

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

The following is a table of hardware events deemed relevant and useful in tuning application performance. These events have identical assignments in the header files on different platforms however they may differ in their actual semantics. In addition, all of these events are not guaranteed to be present on all platforms. Please check your platform's documentation carefully. Note: these values should not be changed by the user.

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_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`		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.

Value	Symbol	Definition
`0`	`PAPI_OK`	No error
`-1`	`PAPI_EINVAL`	Invalid argument
`-2`	`PAPI_ENOMEM`	Insufficient memory
`-3`	`PAPI_ESYS`	A System or C library call failed, please check `errno`
`-4`	`PAPI_ESBSTR`	Substrate returned an error, usually the result of an unimplemented feature
`-5`	`PAPI_ECLOST`	Access to the counters was lost or interrupted
`-6`	`PAPI_EBUG`	Internal error, please send mail to the developers
`-7`	`PAPI_ENOEVNT`	Hardware Event does not exist
`-8`	`PAPI_ECNFLCT`	Hardware Event exists, but cannot be counted due to counter resource limitations
`-9`	`PAPI_ENOTRUN`	No Events or EventSets are currently not counting
`-10`	`PAPI_ISRUN`	EventSet is currently running
`-11`	`PAPI_ENOEVST`	No such EventSet available
`-12`	`PAPI_ENOCNTR`	Hardware does not support performance counters
`-14`	`PAPI_EMISC`	'Unknown error' code

Table 2: Return Codes

The Low Level API

The following functions represent the low level portion of the PAPI API. These functions provide greatly increased efficiency and functionality over the high level API presented in the next section. As mentioned in the introduction, the low level API is only as powerful as the substrate upon which it is built. Thus some features may not be available on every platform. The converse may also be true, that more advanced features may be available and defined in the header file. The user is encouraged to read the documentation for each platform carefully.

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

int PAPI_add_event (int *EventSet, int Event)

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.

const PAPI_hw_info_t *PAPI_get_hardware_info (void)

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

void *PAPI_get_overflow_address (void *context)

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

long long PAPI_get_real_cyc (void)

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.

long long PAPI_get_virt_cyc (void)

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.

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

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.

const PAPI_preset_info_t *PAPI_query_all_events_verbose (void)

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

int PAPI_event_code_to_name (int EventCode, char *out)

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.

int PAPI_event_name_to_code (char *in, int *out)

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

int PAPI_read (int EventSet, long long *values)

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)

int PAPI_save (void)

see above description (not yet implemented)

int PAPI_set_debug (int level)

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

int PAPI_set_opt (int option, PAPI_option_t *ptr)

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, log 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

The simple interface implemented by the following six routines allows the user to access and count specific hardware events. It should be noted that this API can be used in conjunction with the low level API. However, the high level API by itself is only able to access those events countable simultaneously by the underlying hardware. Note that the high level interface performs initialization implicitly and is not thread safe. Under the covers it calls PAPI_library_init(PAPI_VER_CURRENT) and PAPI_thread_init(NULL, 0).

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.

int PAPI_start_counters(int *events, int array_len)

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.

int PAPI_read_counters(long long *values, int array_len)

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.

int PAPI_accum_counters(long long *values, int array_len)

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.

int PAPI_stop_counters(long long *values, int array_len)

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.

int PAPI_flops(float *rtime, float *ptime, long_long *flpins, float *mflops )

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.