The Performance Application Programming Interface (PAPI) provides a standard application programming interface for accessing hardware performance counters on microprocessor-based computer systems. The version of PAPI used on Cray XT series systems is supplied, documented, and supported by the PAPI Group, http://icl.cs.utk.edu/papi/.
CrayPat (Cray performance analysis tool) applications use some low-level functions of PAPI internally to capture performance analysis information during program execution. However, CrayPat and PAPI are separate modules, and the PAPI module is not loaded as part of CrayPat. To access PAPI functions and utilities directly, you must first load the PAPI module.
% module load papi |
The following man pages describe the PAPI functions and utilities. These man pages can be viewed only after the PAPI module is loaded.
PAPI provides interface functions for discovering the events that are native to a given processor. For more information on native events, see the PAPI_native.3 man page.
PAPI provides simple interfaces for instrumenting applications written in C or Fortran. These functions are described in the following man pages.
| PAPI_num_counters(3) | Return the number of hardware counters available on the system. |
| PAPI_flips(3) | Return the Mflips (floating point instruction rate per second), real, and CPU time. |
| PAPI_flops(3) | Return the Mflops (floating point operation rate per second), real, and CPU time. |
| PAPI_ipc(3) | Return the instructions per cycle, real, and CPU 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 counting events and return the current counts. |
The high-level functions are self-initializing. You may mix high- and low-level functions, but low-level functions must follow either a high-level function call or a call to PAPI_library_init(3).
PAPI also provides an advanced interface for instrumenting applications. The PAPI library must be initialized before calling any of these functions; initialization can be done by issuing either a high-level function call or a call to PAPI_library_init(3). Some of these functions may be implemented for C or Fortran only; see the individual man pages for more information.
| PAPI_accum(3) | Accumulate and reset hardware events from an event set. |
| PAPI_add_event(3) | Add a single PAPI preset or a native hardware event to an event set. |
| PAPI_add_events(3) | Add an 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) | Deallocate memory associated with an empty PAPI event set. |
| PAPI_enum_event(3) | Return the event code for the next available preset or native event. |
| PAPI_event_code_to_name(3) | Translate an integer PAPI event code into an ASCII PAPI preset or native event name. |
| PAPI_event_name_to_code(3) | Translate an ASCII PAPI present or event name into an integer PAPI event code. |
| PAPI_get_dmem_info(3) | Get dynamic memory usage information. |
| PAPI_get_event_info(3) | Get the name and description of a given preset or native event code. |
| PAPI_get_executable_info(3) | Get the address space information of the executable. |
| PAPIF_get_exe_info(3) | Fortran-only version of PAPI_get_executable_info. |
| 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) | Get the option settings of the PAPI library or of a specific event set. |
| PAPIF_get_clockrate(3) | Get the processor clock rate in MHz. (Fortran only.) |
| PAPIF_get_domain(3) | Get the domain of the specified event set. (Fortran only.) |
| PAPIF_get_granularity(3) | Get the granularity of the specified event set. (Fortran only.) |
| PAPIF_get_preload(3) | Get the LD_PRELOAD environment equivalent. (Fortran only.) |
| PAPI_get_real_cyc(3) | Get the total number of cycles since the starting point. |
| PAPI_get_real_usec(3) | Get the total number of microseconds since the starting point. |
| PAPI_get_shared_lib_info(3) | Get information about shared libraries used by the process. |
| PAPI_get_thr_specific(3) | Get a pointer to a thread—specific stored data structure. |
| PAPI_get_overflow_event_index(3) | Decompose an overflow vector into an event index array. |
| PAPI_get_virt_cyc(3) | Get the process cycle count since the starting point. |
| PAPI_get_virt_usec(3) | Get the process time in microseconds since the starting point. |
| PAPI_is_initialized(3) | Return the initialization state of the PAPI library. |
| PAPI_library_init(3) | Initialize the PAPI library. |
| PAPI_list_events(3) | List the events that are members of 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. |
| 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) | Inform PAPI of the existence of a new thread. |
| 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 hardware counter profiles from multiple code regions. |
| 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_unregister_thread(3) | Inform PAPI that a previously registered thread is disappearing. |
| PAPI_write(3) | Write counter values into counters. |
The PAPI utilities provide more information about the system and the PAPI events that can be examined. See the individual man pages for more information about each utility.
| papi_avail(1) | Returns information regarding the availability of PAPI preset events. |
| papi_clockres(1) | Measures and reports clock latency and resolution for PAPI timers. |
| papi_cost(1) | Computes execution time costs for basic PAPI operations. |
| papi_command_line(1) | Execute PAPI preset or native events from the command line. |
| papi_decode(1) | Decodes PAPI preset events into a csv format suitable for use with PAPI_encode_events. |
| papi_event_chooser(1) | Given a list of named events, lists other events that can also be counted at the same time. |
| papi_mem_info(1) | Returns information regarding the memory architecture of the current processor. |
| papi_native_avail(1) | Returns detailed information for PAPI native events. |