NAME

PAPI - Performance Application Programming Interface

CONTENTS

Synopsis
PAPI Presets
High Level Functions
Low Level Functions
Authors
See Also

The PAPI Performance Application Programming Interface provides machine and operating system independent access to hardware performance counters found on most modern processors. Any of over 100 preset events can be counted through either a simple high level programming interface or a more complete low level interface from either C or Fortran. A list of the function calls in these interfaces is given below, with references to other pages for more complete details. For general information on the Fortran interface see: PAPIF (3)

An extensive list of predefined events is implemented on all systems where they can be supported. For a list of these events, see: PAPI_presets (3)

A simple interface for single thread applications. Fully supported on both C and Fortran. See individual functions for details on usage.

PAPI_num_counters (3)  - get the number of hardware counters available on the system

PAPI_flops (3)  - simplified call to get Mflops/s, real and processor time

PAPI_accum_counters (3)  - add current counts to array and reset counters

PAPI_read_counters (3)  - copy current counts to array and reset counters

PAPI_start_counters (3)  - start counting hardware events

PAPI_stop_counters (3)  - stop counters and return current counts

Note that when using the high-level interface the use of PAPI_library_init (3) to initialize the library is optional. If, however, explicit initialization is not made, either of PAPI_flops (3) or PAPI_num_counters (3) must be called before any other call to a PAPI function.

Advanced interface for all applications and performance tools. Some functions may be implemented only for C or Fortran. See individual functions for details on usage and support.

PAPI_accum (3)  - accumulate and reset hardware events from an event set

PAPI_add_event (3)  - add single PAPI preset or native hardware event to an event set

PAPI_add_events (3)  - add array of PAPI preset or native hardware events to an event set

PAPI_add_pevent (3)  - reserved for future use

PAPI_cleanup_eventset (3)  - remove all PAPI events from an event set

PAPI_create_eventset (3)  - create a new empty PAPI event set

PAPI_describe_event (3)  - return description of event given the name or event code

PAPI_destroy_eventset (3)  - deallocates memory associated with an empty PAPI event set

PAPI_event_code_to_name (3)  - translate an integer PAPI event code into an ASCII PAPI preset name

PAPI_event_name_to_code (3)  - translate an ASCII PAPI preset name into an integer PAPI event code

PAPI_get_executable_info (3)  - get the executable’s address space information

PAPI_get_hardware_info (3)  - get information about the system hardware

PAPI_get_opt (3)  - query the option settings of the PAPI library or a specific event set

PAPIF_get_clockrate (3)  - get the processor clockrate in MHz. Fortran only.

PAPIF_get_domain (3)  - get the domain of the specified eventset. Fortran only.

PAPIF_get_granularity (3)  - get the granularity of the specified eventset. Fortran only.

PAPIF_get_preload (3)  - get the ’LD_PRELOAD’ environment equivalent. Fortran only.

PAPI_get_overflow_address (3)  - return the address at which overflow occurred for profiling

PAPI_get_real_cyc (3)  - return the total number of cycles since some arbitrary starting point

PAPI_get_real_usec (3)  - return the total number of microseconds since some arbitrary starting point

PAPI_get_virt_cyc (3)  - return the process cycles since some arbitrary starting point

PAPI_get_virt_usec (3)  - return the process microseconds since some arbitrary starting point

PAPI_label_event (3)  - return a short label for an event given the event code

PAPI_library_init (3)  - initialize the PAPI library

PAPI_list_events (3)  - list the events defined in an event set

PAPI_lock (3)  - lock the PAPI internal mutex variable

PAPI_multiplex_init (3)  - initialize multiplex support in the PAPI library

PAPI_overflow (3)  - set up an event set to begin registering overflows

PAPI_perror (3)  - return a copy of the error message corresponding to a specified error code

PAPI_profil (3)  - generate PC histogram data where hardware counter overflow occurs

PAPI_query_all_events_verbose (3)  - request detailed information on all PAPI events

PAPI_query_event (3)  - query if a PAPI event exists

PAPI_query_event_verbose (3)  - request detailed information on a PAPI event

PAPI_read (3)  - read hardware events from an event set with no reset

PAPI_rem_event (3)  - remove a hardware event from a PAPI event set

PAPI_rem_events (3)  - remove an array of hardware events from a PAPI event set

PAPI_rem_pevent (3)  - reserved for future use

PAPI_reset (3)  - reset the hardware event counts in an EventSet

PAPI_restore (3)  - Restore the saved state of the PAPI library

PAPI_save (3)  - Restore the saved state of the PAPI library

PAPI_set_debug (3)  - set the current debug level for PAPI

PAPI_set_domain (3)  - set the default execution domain for new event sets

PAPIF_set_event_domain (3)  - set the execution domain for a specific event set. Fortran only.

PAPI_set_granularity (3)  - set the default granularity for new event sets

PAPI_set_opt (3)  - change the option settings of the PAPI library or a specific event set

PAPI_set_multiplex (3)  - convert a standard event set to a multiplexed event set

PAPI_shutdown (3)  - finish using PAPI and free all related resources

PAPI_sprofil (3)  - generate PC histogram data where hardware counter overflow occurs

PAPI_start (3)  - start counting hardware events in an event set

PAPI_state (3)  - return the counting state of an event set

PAPI_stop (3)  - stop counting hardware events in an event set and return current events

PAPI_strerror (3)  - return a pointer to the error message corresponding to a specified error code

PAPI_thread_id (3)  - get the thread identifier of the current thread

PAPI_thread_init (3)  - initialize thread support in the PAPI library

PAPI_unlock (3)  - unlock the PAPI internal mutex variable

PAPI_write (3)  - write counter values into counters

Philip J. Mucci <mucci@cs.utk.edu>
Kevin London <london@cs.utk.edu>
Dan Terpstra <terpstra@cs.utk.edu>

The PAPI Web Site: http://icl.cs.utk.edu/projects/papi