papi_help(3) - Linux man page

Name

PAPI - Performance Application Programming Interface

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)

Component PAPI

Beginning with version 3.9, PAPI supports extensions to count performance information on multiple simultaneous components. This capability is only provided in the low level interface. New or modified function calls are prefixed with an asterisk.

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 systemPAPI_flips(3) - simplified call to get Mflips/s (floating point
instruction rate), real and processor timePAPI_flops(3) - simplified call
to get Mflops/s (floating point operation rate), real and processor timePAPI_ipc(3)
- gets instructions per cycle, real and processor timePAPI_accum_counters(3)
- add current counts to array and reset countersPAPI_read_counters(3) - copy
current counts to array and reset countersPAPI_start_counters(3) - start
counting hardware eventsPAPI_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)orahighlevelroutinebefore 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 setPAPI_add_event(3)
- add single PAPI preset or native hardware event to an event setPAPI_add_events(3)
- add array of PAPI preset or native hardware events to an event setPAPI_assign_eventset_component(3)*
- assign a component index to an existing but empty eventsetPAPI_attach(3)
- attach specified event set to a specific process or thread idPAPI_cleanup_eventset(3)
- remove all PAPI events from an event setPAPI_create_eventset(3) - create
a new empty PAPI event setPAPI_destroy_eventset(3) - deallocates memory
associated with an empty PAPI event setPAPI_detach(3) - detach specified
event set from a previously specified process or thread idPAPI_enum_event(3)
- return the event code for the next available preset or natvie eventPAPI_event_code_to_name(3)
- translate an integer PAPI event code into an ASCII PAPI preset or native
namePAPI_event_name_to_code(3) - translate an ASCII PAPI preset or native
name into an integer PAPI event codePAPI_get_component_info(3)* - get information
about the component featuresPAPI_get_dmem_info(3) - get dynamic memory usage
informationPAPI_get_event_info(3) - get the name and descriptions for a
given preset or native event codePAPI_get_executable_info(3) - get the executable�s
address space informationPAPIF_get_exe_info(3) - Fortran version of PAPI_get_executable_info
with different calling semanticsPAPI_get_hardware_info(3) - get information
about the system hardwarePAPI_get_multiplex(3) - get the multiplexing status
of specified event setPAPI_get_cmp_opt(3)* - query the component specific
option settings of a specific event setPAPI_get_opt(3) - query the option
settings of the PAPI library or a specific event setPAPIF_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 pointPAPI_get_real_usec(3)
- return the total number of microseconds since some arbitrary starting
pointPAPI_get_shared_lib_info(3) - get information about the shared libraries
used by the processPAPI_get_thr_specific(3) - return a pointer to a thread
specific stored data structurePAPI_get_overflow_event_index(3) - decomposes
an overflow_vector into an event index arrayPAPI_get_virt_cyc(3) - return
the process cycles since some arbitrary starting pointPAPI_get_virt_usec(3)
- return the process microseconds since some arbitrary starting pointPAPI_is_initialized(3)
- return the initialized state of the PAPI libraryPAPI_library_init(3) -
initialize the PAPI libraryPAPI_list_events(3) - list the events that are
members of an event setPAPI_list_threads(3) - list the thread ids currently
known to PAPIPAPI_lock(3) - lock one of two PAPI internal user mutex variablesPAPI_multiplex_init(3)
- initialize multiplex support in the PAPI libraryPAPI_num_components(3)*
- return the number of components currently installedPAPI_num_cmp_hwctrs(3)*
- return the number of hardware counters for a specified componentPAPI_num_hwctrs(3)
- return the number of hardware counters for the cpuPAPI_num_events(3) -
return the number of events in an event setPAPI_overflow(3) - set up an
event set to begin registering overflowsPAPI_perror(3) - convert PAPI error
codes to stringsPAPI_profil(3) - generate PC histogram data where hardware
counter overflow occursPAPI_query_event(3) - query if a PAPI event existsPAPI_read(3)
- read hardware events from an event set with no resetPAPI_register_thread(3)
- inform PAPI of the existence of a new threadPAPI_remove_event(3) - remove
a hardware event from a PAPI event setPAPI_remove_events(3) - remove an
array of hardware events from a PAPI event setPAPI_reset(3) - reset the
hardware event counts in an event setPAPI_set_debug(3) - set the current
debug level for PAPIPAPI_set_cmp_domain(3)* - set the component specific
default execution domain for new event setsPAPI_set_domain(3) - set the
default execution domain for new event setsPAPIF_set_event_domain(3) - set
the execution domain for a specific event set. Fortran only.PAPI_set_cmp_granularity(3)*
- set the component specific default granularity for new event setsPAPI_set_granularity(3)
- set the default granularity for new event setsPAPI_set_multiplex(3) - convert
a standard event set to a multiplexed event setPAPI_set_opt(3) - change
the option settings of the PAPI library or a specific event setPAPI_set_thr_specific(3)
- save a pointer as a thread specific stored data structurePAPI_shutdown(3)
- finish using PAPI and free all related resourcesPAPI_sprofil(3) - generate
hardware counter profiles from multiple code regionsPAPI_start(3) - start
counting hardware events in an event setPAPI_state(3) - return the counting
state of an event setPAPI_stop(3) - stop counting hardware events in an
event set and return current eventsPAPI_strerror(3) - return a pointer to
the error message corresponding to a specified error codePAPI_thread_id(3)
- get the thread identifier of the current threadPAPI_thread_init(3) - initialize
thread support in the PAPI libraryPAPI_unlock(3) - unlock one of two PAPI
internal user mutex variablesPAPI_unregister_thread(3) - inform PAPI that
a previously registered thread is disappearingPAPI_write(3) - write counter
values into counters

PAPI Utility Commands

A collection of simple utility commands is available in the \utils directory. See individual utilities for details on usage.

papi_avail(1) - provides availability and detail information for PAPI preset
eventspapi_clockres(1) - provides availability and detail information for
PAPI preset eventspapi_cost(1) - provides availability and detail information
for PAPI preset eventspapi_command_line(1) - executes PAPI preset or native
events from the command linepapi_decode(1) - decodes PAPI preset events
into a csv format suitable for PAPI_encode_eventspapi_event_chooser(1)
- given a list of named events, lists other events that can be counted with
thempapi_mem_info(1) - provides information on the memory architecture of
the current processorpapi_native_avail(1) - provides detailed information
for PAPI native events