PAPI(3) - c6

1PAPI(3.9)                            PAPI                            PAPI(3.9)
2
3
4

NAME

6       PAPI - Performance Application Programming Interface
7
8

SYNOPSIS

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

Component PAPI

21       Beginning with version 3.9, PAPI supports extensions to  count  perfor‐
22       mance  information on multiple simultaneous components. This capability
23       is only provided in the low level interface. New or  modified  function
24       calls are prefixed with an asterisk.
25
26

PAPI Presets

28       An  extensive  list  of predefined events is implemented on all systems
29       where they can be supported. For a list of these events, see: PAPI_pre‐
30       sets(3)
31
32

PAPI Native Events

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

High Level Functions

40       A simple interface for instrumenting end-user applications.  Fully sup‐
41       ported on both C and Fortran.  See individual functions for details  on
42       usage.
43
44       PAPI_num_counters(3) - get the number of hardware counters available on the system
45       PAPI_flips(3) - simplified call to get Mflips/s (floating point instruction rate), real and processor time
46       PAPI_flops(3) - simplified call to get Mflops/s (floating point operation rate), real and processor time
47       PAPI_ipc(3) - gets instructions per cycle, real and processor time
48       PAPI_accum_counters(3) - add current counts to array and reset counters
49       PAPI_read_counters(3) - copy current counts to array and reset counters
50       PAPI_start_counters(3) - start counting hardware events
51       PAPI_stop_counters(3) - stop counters and return current counts
52
53       Note  that  the high-level interface is self-initializing.  You can mix
54       high   and   low   level   calls,   but   you    must    call    either
55       PAPI_library_init(3)orahighlevelroutinebefore  calling a low level rou‐
56       tine.
57
58
59

Low Level Functions

61       Advanced interface for all applications and  performance  tools.   Some
62       functions  may  be  implemented  only for C or Fortran.  See individual
63       functions for details on usage and support.
64
65
66
67       PAPI_accum(3) - accumulate and reset hardware events from an event set
68       PAPI_add_event(3) - add single PAPI preset or native hardware event to an event set
69       PAPI_add_events(3) - add array of PAPI preset or native hardware events to an event set
70       PAPI_assign_eventset_component(3)* - assign a component index to an existing but empty eventset
71       PAPI_attach(3) - attach specified event set to a specific process or thread id
72       PAPI_cleanup_eventset(3) - remove all PAPI events from an event set
73       PAPI_create_eventset(3) - create a new empty PAPI event set
74       PAPI_destroy_eventset(3) - deallocates memory associated with an empty PAPI event set
75       PAPI_detach(3) - detach specified event set from a previously specified process or thread id
76       PAPI_enum_event(3) - return the event code for the next available preset or natvie event
77       PAPI_event_code_to_name(3) - translate an integer PAPI event code into an ASCII PAPI preset or native name
78       PAPI_event_name_to_code(3) - translate an ASCII PAPI preset or native name into an integer PAPI event code
79       PAPI_get_component_info(3)* - get information about the component features
80       PAPI_get_dmem_info(3) - get dynamic memory usage information
81       PAPI_get_event_info(3) - get the name and descriptions for a given preset or native event code
82       PAPI_get_executable_info(3) - get the executables address space information
83       PAPIF_get_exe_info(3) - Fortran version of PAPI_get_executable_info with different calling semantics
84       PAPI_get_hardware_info(3) - get information about the system hardware
85       PAPI_get_multiplex(3) - get the multiplexing status of specified event set
86       PAPI_get_cmp_opt(3)* - query the component specific option settings of a specific event set
87       PAPI_get_opt(3) - query the option settings of the PAPI library or a specific event set
88       PAPIF_get_clockrate(3) - get the processor clockrate in MHz. Fortran only.
89       PAPIF_get_domain(3) - get the domain of the specified eventset. Fortran only.
90       PAPIF_get_granularity(3) - get the granularity of the specified eventset. Fortran only.
91       PAPIF_get_preload(3) - get the 'LD_PRELOAD' environment equivalent. Fortran only.
92       PAPI_get_real_cyc(3) - return the total number of cycles since some arbitrary starting point
93       PAPI_get_real_usec(3) - return the total number of microseconds since some arbitrary starting point
94       PAPI_get_shared_lib_info(3) - get information about the shared libraries used by the process
95       PAPI_get_thr_specific(3) - return a pointer to a thread specific stored data structure
96       PAPI_get_overflow_event_index(3) - decomposes an overflow_vector into an event index array
97       PAPI_get_virt_cyc(3) - return the process cycles since some arbitrary starting point
98       PAPI_get_virt_usec(3) - return the process microseconds since some arbitrary starting point
99       PAPI_is_initialized(3) - return the initialized state of the PAPI library
100       PAPI_library_init(3) - initialize the PAPI library
101       PAPI_list_events(3) - list the events that are members of an event set
102       PAPI_list_threads(3) - list the thread ids currently known to PAPI
103       PAPI_lock(3) - lock one of two PAPI internal user mutex variables
104       PAPI_multiplex_init(3) - initialize multiplex support in the PAPI library
105       PAPI_num_components(3)* - return the number of components currently installed
106       PAPI_num_cmp_hwctrs(3)* - return the number of hardware counters for a specified component
107       PAPI_num_hwctrs(3) - return the number of hardware counters for the cpu
108       PAPI_num_events(3) - return the number of events in an event set
109       PAPI_overflow(3) - set up an event set to begin registering overflows
110       PAPI_perror(3) - convert PAPI error codes to strings
111       PAPI_profil(3) - generate PC histogram data where hardware counter overflow occurs
112       PAPI_query_event(3) - query if a PAPI event exists
113       PAPI_read(3) - read hardware events from an event set with no reset
114       PAPI_register_thread(3) - inform PAPI of the existence of a new thread
115       PAPI_remove_event(3) - remove a hardware event from a PAPI event set
116       PAPI_remove_events(3) - remove an array of hardware events from a PAPI event set
117       PAPI_reset(3) - reset the hardware event counts in an event set
118       PAPI_set_debug(3) - set the current debug level for PAPI
119       PAPI_set_cmp_domain(3)* - set the component specific default execution domain for new event sets
120       PAPI_set_domain(3) - set the default execution domain for new event sets
121       PAPIF_set_event_domain(3) - set the execution domain for a specific event set. Fortran only.
122       PAPI_set_cmp_granularity(3)* - set the component specific default granularity for new event sets
123       PAPI_set_granularity(3) - set the default granularity for new event sets
124       PAPI_set_multiplex(3) - convert a standard event set to a multiplexed event set
125       PAPI_set_opt(3) - change the option settings of the PAPI library or a specific event set
126       PAPI_set_thr_specific(3) - save a pointer as a thread specific stored data structure
127       PAPI_shutdown(3) - finish using PAPI and free all related resources
128       PAPI_sprofil(3) - generate hardware counter profiles from multiple code regions
129       PAPI_start(3) - start counting hardware events in an event set
130       PAPI_state(3) - return the counting state of an event set
131       PAPI_stop(3) - stop counting hardware events in an event set and return current events
132       PAPI_strerror(3) - return a pointer to the error message corresponding to a specified error code
133       PAPI_thread_id(3) - get the thread identifier of the current thread
134       PAPI_thread_init(3) - initialize thread support in the PAPI library
135       PAPI_unlock(3) - unlock one of two PAPI internal user mutex variables
136       PAPI_unregister_thread(3) - inform PAPI that a previously registered thread is disappearing
137       PAPI_write(3) - write counter values into counters
138
139

PAPI Utility Commands

141       A collection of simple utility commands  is  available  in  the  \utils
142       directory.  See individual utilities for details on usage.
143
144       papi_avail(1) - provides availability and detail information for PAPI preset events
145       papi_clockres(1) - provides availability and detail information for PAPI preset events
146       papi_cost(1) - provides availability and detail information for PAPI preset events
147       papi_command_line(1) - executes PAPI preset or native events from the command line
148       papi_decode(1) - decodes PAPI preset events into a csv format suitable for PAPI_encode_events
149       papi_event_chooser(1) - given a list of named events, lists other events that can be counted with them
150       papi_mem_info(1) - provides information on the memory architecture of the current processor
151       papi_native_avail(1) - provides detailed information for PAPI native events
152
153
154