NAME

PAPI - Performance Application Programming Interface

CONTENTS

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

SYNOPSIS

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)

PAPI Presets

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)

PAPI Native Events

PAPI also supports interface functions for discovering the native events on a given platform. For more information on native events, see: PAPI_native (3)

High Level Functions

A simple interface for instrumenting end-user 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_flips (3)  - simplified call to get Mflips/s (floating point instruction rate), real and processor time

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

PAPI_ipc (3)  - gets instructions per cycle, 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 the high-level interface is self-initializing. You can mix high and low level calls, but you must call either PAPI_library_init (3) or a high level routine before calling a low level routine.

Low Level Functions

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_cleanup_eventset (3)  - remove all PAPI events from an event set

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

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

PAPI_enum_event (3)  - return the event code for the next available preset or natvie event

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

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

PAPI_get_dmem_info (3)  - get information about the dynamic memory usage of the current program

PAPI_get_event_info (3)  - get the name and descriptions for a given preset or native 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_multiplex (3)  - get the multiplexing status of specified event set

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_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_shared_lib_info (3)  - get information about the shared libraries used by the process

PAPI_get_thr_specific (3)  - return a pointer to a thread specific stored data structure

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_is_initialized (3)  - return the initialized state of the PAPI library

PAPI_library_init (3)  - initialize the PAPI library

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

PAPI_lock (3)  - lock one of two PAPI internal user mutex variables

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

PAPI_num_hwctrs (3)  - return the number of hardware counters

PAPI_num_events (3)  - return the number of events in an event set

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

PAPI_perror (3)  - convert PAPI error codes to strings

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

PAPI_query_event (3)  - query if a PAPI event exists

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

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

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

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

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

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_multiplex (3)  - convert a standard event set to a multiplexed event set

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

PAPI_set_thr_specific (3)  - save a pointer as a thread specific stored data structure

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 one of two PAPI internal user mutex variables

PAPI_write (3)  - write counter values into counters

AUTHORS

The PAPI Team. See them at the PAPI Web Site: http://icl.cs.utk.edu/projects/papi

SEE ALSO

PAPIF (3), PAPI_presets (3), PAPI_native (3)


PAPI Programmer’s Reference PAPI (3) November, 2003

  Innovative Computing Laboratory
2001 R&D Winner  
Contact PAPI: papi@cs.utk.edu Computer Science Department
  University of Tennessee