Contents 1 NAME 2 Synopsis 3 Description 3.1 Component PAPI 4 PAPI Presets 5 PAPI Native Events 6 High Level Functions 7 Low Level Functions 8 PAPI Utility Commands 9 See Also

NAME

• PAPI-C - Component Based 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)

Description

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 suffixed 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 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_assign_eventset_component(3) * - assign a component index to an existing but empty eventset
• PAPI_attach(3) - attach specified event set to a specific process or thread id
• 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_detach(3) - detach specified event set from a previously specified process or thread id
• 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_component_info(3) * - get information about the component features
• PAPI_get_dmem_info(3) - get dynamic memory usage information
• 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
• PAPIF_get_exe_info(3) - Fortran version of PAPI_get_executable_info with different calling semantics
• 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_cmp_opt(3) * - query the component specific option settings of a specific event set
• PAPI_get_opt(3) - query the option settings of the PAPI library or a specific event set
• PAPI_get_overflow_event_index(3) - convert an overflow vector into a list of event indices
• 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_overflow_event_index(3) - decomposes an overflow_vector into an event index array
• 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 that are members of an event set
• PAPI_list_threads(3) - list the thread ids currently known to PAPI
• 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_components(3) * - return the number of components currently installed
• PAPI_num_cmp_hwctrs(3) * - return the number of hardware counters for a specified component
• PAPI_num_hwctrs(3) - return the number of hardware counters for the cpu
• 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_cmp_domain(3) * - set the component specific default execution domain for new event sets
• 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_cmp_granularity(3) * - set the component specific default granularity for new event sets
• 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

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 events
• papi_clockres(1) - provides availability and detail information for PAPI preset events
• papi_cost(1) - provides availability and detail information for PAPI preset events
• papi_command_line(1) - executes PAPI preset or native events from the command line
• papi_decode(1) - decodes PAPI preset events into a csv format suitable for PAPI_encode_events
• papi_event_chooser(1) - given a list of named events, lists other events that can be counted with them
• papi_mem_info(1) - provides information on the memory architecture of the current processor
• papi_native_avail(1) - provides detailed information for PAPI native events

See Also

The PAPI Website: http://icl.cs.utk.edu/papi