I. Preface
PAPI Architecture (Internal Design)
III. How to install PAPI onto your system
IV. C and Fortran Calling Interfaces
V. Events
Initialization of a High-Level API
Reading, Adding, and Stopping Counters
Mflops/s, Real Time, and Processor Time
Initialization of a Low-Level API
Starting, Reading, Adding, and Stopping events in an Event Set
Resetting events in an Event Set
Removing events in an Event Set
Emptying and Destroying an Event Set
VII. PAPI Timers
VIII. PAPI System Information
Initialization of Multiplex Support
Converting an Event Set into a Multiplexed Event Set
Using PAPI with Parallel Programs
Initialization of Thread Support
Beginning Overflows in Event Sets
What is Statistical Profiling?
Converting Error Codes to Error Messages
XII. Appendices
Appendix A. Table of Preset Events
Appendix D. PAPI Supported Platforms
Appendix E. Table of Native Encoding for the Various Platforms
Appendix F. Table of Overhead for the Various Platforms
Appendix G. Table for Multiplexing
Appendix H. Table for Overflow
Appendix I. PAPI Supported Tools
XIII. Bibliography
This document is intended to provide the PAPI user with a
discussion of how to use the different components and functions of PAPI . The
intended users are atyle='font-size:12.0pt'>III. HOW TO INSTALL PAPI ONTO YOUR SYSTEM
This section provides an installation guide for PAPI. It states the necessary steps in order to install PAPI on the various supported operating systems.
This section states the header
files in which function calls are defined and the form of the function calls
for both the C and Fortran calling interfaces. Also, it provides a table that
shows the relation between certain pseudo-types and Fortran variable types.
V. EVENTS
This
section provides an explanation of events as well as an explanation of native
and preset events. The preset query and translation functions are also
discussed in this section. There are code examples using native events, preset
query, and preset translation with the corresponding output.
This section discusses the
high-level and low-level interfaces in detail. The initialization and functions
of these interfaces are also discussed. Code examples along with the
corresponding output are included as well.
VII. PAPI
TIMERS
This section explains the PAPI
functions associated with obtaining real and virtual time from the platform’s
timers. Code examples along with the corresponding output are included as well.
VIII. PAPI SYSTEM INFORMATION
This section explains the PAPI
functions associated with obtaining hardware and executable information. Code
examples along with the corresponding output are included as well.
This
section discusses the advanced features of PAPI, which includes multiplexing,
threads, MPI, overflows, and statistical profiling. The functions that are use
to implement these features are also discussed. Code examples along with the
corresponding output are included as well.
This section discusses the
various negative error codes that are returned by the PAPI functions. A table
with the names, values, and descriptions of the return codes are given as well
as a discussion of the PAPI function that can be used to convert error codes to
error messages along with a code example with the corresponding output.
This section provides
information on PAPI two mailing lists for the users to ask various questions
about the project.
XII. APPENDICES
These appendices provide various listings and tables, such as: a table of preset events and the platforms on which they are supported, a table of PAPI supported tools, more information on native events, multiplexing, overflow, and etc.
handle_error(1)
A function that passes the argument of 1 that the user should write to handle errors.
PAPI is an acronym for Performance Application Programming Interface. The PAPI Project is being developed at the University of Tennessee’s Innovative Computing Laboratory in the Computer Science Department. This project was created to design, standardize, and implement a portable and efficient API (Application Programming Interface) to access the hardware performance counters found on most modern microprocessors.
Hardware counters exist on every major processor today, such as Intel Pentium, IA-64, AMD Athlon, and IBM POWER series. These counters can provide performance tool developers with a basis for tool development and application developers with valuable information about sections of their code that can be improved. However, there are only a few APIs that allow access to these counters, and most of them are poorly documented, unstable, or unavailable. In addition, performance metrics may have different definitions and different programming interfaces on different platforms.
These considerations motivated the development of the PAPI Project. Some goals of the PAPI Project are as follows:
· To provide a solid foundation for cross platform performance analysis tools
· To present a set of standard definitions for performance metrics on all platforms
· To provide a standardize API among users, vendors, and academics
· To be easy to use, well documented, and freely available
The Figure below shows the internal design of the PAPI architecture. In this figure, we can see the two layers of the architecture:
The Portable Layer consists of the API (low level and high level) and machine independent support functions.
The Machine Specific Layer defines and exports a machine independent interface to machine dependent functions and data structures. These functions are defined in the substrate layer, which uses kernel extensions, operating system calls, or assembly language to access the hardware performance counters. PAPI uses the most efficient and flexible of the three, depending on what is available.
PAPI strives to provide a uniform environment across platforms. However, this is not always possible. Where hardware support for features, such as overflows and multiplexing is not supported, PAPI implements the features in software where possible. Also, processors do not support the same metrics, thus you can monitor different events depending on the processor in use. Therefore, the interface remains constant, but how it is implemented can vary. Throughout this guide, implementation decisions will be documented where it can make a difference to the user, such as overhead costs, sampling, and etc.
On some of the systems that PAPI supports (see Appendix D), you can install PAPI right out of the box without any additional setup. Others require drivers or patches to be installed first.
The general installation steps are below, but first
find your particular Operating System’s section of the /papi/INSTALL file for
current information on any additional steps that may be necessary.
General Installation
1. Pick the appropriate Makefile.<arch> for your system in the papi source distribution, edit it (if necessary) and compile.
% make -f Makefile.<arch>
2. Check for errors. Look for the libpapi.a and libpapi.so in the current directory. Optionally, run the test programs in the ‘ftests’ and ‘tests’ directories.
Not all tests will succeed on all platforms.
% ./run_tests.sh
This will run the tests in quiet mode, which will print PASSED, FAILED, or SKIPPED. Tests are SKIPPED if the functionality being tested is not supported by that platform.
3. Create a PAPI binary distribution or install PAPI directly.
To directly install PAPI from the build tree:
% make -f Makefile.<arch> DESTDIR=<install-dir> install
Please use an absolute pathname for <install-dir>, not a relative pathname.
To create a binary kit, papi-<arch>.tgz:
% make -f Makefile.<arch> dist
PAPI is written in C. The function calls stops:.5in'>The function calls in the Fortran interface are defined in the header file, fpapi.h and consist of the following form:
PAPIF_function_name(arg1, arg2, …, check)
As you can probably see, the C
function calls have equivalent Fortran function calls (PAPI_<call>
becomes PAPIF_<call>). Well, this is true for most function calls, except
for the functions that return C pointers to structures, such as PAPI_get_opt and
PAPI_get_executable_info, which are either not implemented in the Fortran
interface, or implemented with different calling semantics. In the function
calls of the Fortran interface, the return code of the corresponding C routine
is returned in the argument, check.
For most
architectures, the following relation holds between the pseudo-types listed and
Fortran variable types:
Pseudo-type |
Fortran type |
Description |
C_INT |
INTEGER |
Default
Integer type |
C_FLOAT |
REAL |
Default
Real type |
C_LONG_LONG |
INTEGER*8 |
Extended
size integer |
C_STRING |
CHARACTER*(PAPI_MAX_STR_LEN) |
Fortran
string |
C_INT
FUNCTION |
EXTERNAL
INTEGER FUNCTION |
Fortran
function returning integer result |
Array
arguments must be of sufficient size to hold the input/output from/to the
subroutine for predictable behavior. The array length is indicated either by
the accompanying argument or by internal PAPI definitions.
Subroutines
accepting C_STRING as an argument are on most implementations capable of
reading the character string length as provided by Fortran. In these
implementations, the string is truncated or space padded as necessary. For
other implementations, the length of the character array is assumed to be of
sufficient size. No character string longer than PAPI_MAX_STR_LEN is
returned by the PAPIF interface.
For more information on all of the function calls and their job descriptions, see Appendix B for the high-level functions and Appendix C for the low-level functions.
Events are occurrences of specific signals related to a processor’s function. Hardware performance counters exist as a small set of registers that count events, such as cache misses and floating point operations while the program executes on the processor. Monitoring these events facilitates correlation between the structure of source/object code and the efficiency of the mapping of that code to the underlying architecture. Each processor has a number of events that are native to and often to that architecture. PAPI provides a software abstraction of these architecture-dependent native events into a collection of preset events that are accessible through the PAPI interface.
Native events comprise the set of all events that are countable by the CPU. In many cases, these events will be available through a matching preset PAPI event. Even if no preset event is available native events can still be accessed directly. These events are intended to be used by people who are very familiar with the particular platform in use. PAPI provides access to native events on all supported platforms through the low-level interface. Native events use the same interface as used when setting up a preset event, but a CPU-specific bit pattern is used instead of the PAPI event definition.
Native encoding is usually:
((register code & 0xffffff) << 8 | (register number & 0xff))
Native encodings are platform dependent, so the above native encoding may or may not work with your platform. To determine the native encoding for your platform, see Appendix F or the README file for your platform in the PAPI source distribution. In addition, the native event lists for the various platforms can be found in the processor architecture manual.
Native events are specified as arguments to the low-level function, PAPI_add_event. In the following code example, a native event is added by using PAPI_add_event with the register code = 0x800000 and the register number = 0x01:
For more code examples, see tests/native.c in the papi source distribution.
Preset events, also known as predefined events, are a common set of events deemed relevant and useful for application performance tuning. These events are typically found in many CPUs that provide performance counters and give access to the memory hierarchy, cache coherence protocol events, cycle and instruction counts, functional unit, and pipeline status. Furthermore, preset events are mappings from symbolic names (PAPI preset name) to machine specific definitions (native countable events) for a particular hardware resource. For example, Total Cycles (in user mode) is PAPI_TOT_CYC. Also, PAPI supports presets that may be derived from the underlying hardware metrics. For example, Floating Point Instructions per Second is PAPI_FLOPS. A preset can be either directly available as a single counter, derived using a combination of counters, or unavailable on any particular platform.
The PAPI library names approximately 100 preset events, which are defined in the header file, papiStdEventDefs.h. For a given platform, a subset of these preset events can be counted though either a simple high-level programming interface or a more complete C or Fortran low-level interface. For a list and a job description of all the preset events, see Appendix A.
The exact semantics of an event counter are platform dependent. PAPI preset names are mapped onto available events in a way, so it can count as many similar types of events as possible on different platforms. Due to hardware implementation differences, it is not necessarily feasible to directly compare the counts of a particular PAPI event obtained on different hardware platforms. To determine which preset events are available on a specific platform, see Appendix E or run tests/avail.c in the papi source distribution.
The following low-level functions can be called to query about the existence of a preset (in other words, if the hardware supports that certain preset), to query details about a PAPI event, or to acquire details about all PAPI events, respectively:
C:
PAPI_query_event(EventCode)
PAPI_query_event_verbose(EventCode, info)
PAPI_query_all_events_verbose()
Fortran:
PAPIF_query_event(EventCode, check)
PAPIF_query_event_verbose(EventCode, EventName, EventDescr, EventLabel, avail, EventNote, flags, check)
EventCode -- a defined event, such as PAPI_TOT_INS.
EventName -- the event name, such as the preset
name, PAPI_BR_CN.
EventDescr -- a descriptive string for the event of
length less than PAPI_MAX_STR_LEN.
EventLabel -- a short descriptive label for the
event of length less than 18 characters.
avail -- zero if the event CANNOT be counted.
EventNote -- additional text information about an
event (if available).
flags -- provides additional information about
an event, e.g., PAPI_DERIVED for an event derived from 2 or more other
events.
Note
that PAPI_query_all_events_verbose is not implemented in Fortran because it
returns a C pointer to an array of C structures.
PAPI_query_event asks the PAPI library if the PAPI Preset event can be counted on this architecture. If the event CAN be counted, the function returns PAPI_OK. If the event CANNOT be counted, the function returns an error code. On some platforms, this function also can be used to check the syntax of a native event.
PAPI_query_event_verbose asks the PAPI library for a copy of an event descriptor. This descriptor can then be used to investigate the details about the event. In Fortran, the individual fields in the descriptor are returned as parameters.
PAPI_query_all_events_verbose asks the PAPI library to return a pointer to an array of event descriptors. The number of objects in the array is PAPI_MAX_PRESET_EVENTS and each object is a descriptor as returned by PAPI_query_event_verbose().
In the above code example, PAPI_query_event is used to see if a preset (“PAPI_TOT_INS”) exists, PAPI_query_event_verbose is used to query details about the event, and PAPI_query_all_events_verbose is used to acquire details about all PAPI events:
On success, PAPI_query_event and PAPI_query_event_verbose return PAPI_OK, and on error, a non-zero error code is returned.
On success, PAPI_query_all_events_verbose returns a pointer to an array of PAPI_preset_info_t structures and on error, a null pointer is returned.
For more information about the preset query functions, see Appendix C.
A preset event can be translated to a description, label, number, and string by calling the following low-level functions, respectively:
C:
PAPI_describe_event(EventName, EventCode, EventDescr)
PAPI_label_event(EventCode, EventLabel)
PAPI_event_name_to_code(EventName, EventCode)
PAPI_event_code_to_name(EventCode, EventName)
Fortran:
PAPIF_describe_event(EventName, EventCode, EventDesc, check)
PAPIF_label_event(EventCode, EventLabel, check)
PAPIF_event_name_to_code(EventName, EventCode, check)
PAPIF_event_code_to_name(EventCode, EventName, check)
EventCode -- a defined event of integer type, such as PAPI_TOT_INS.
EventName -- the event name, such as the preset
name, PAPI_BR_CN.
EventDescr -- a descriptive string for the event of
length less than PAPI_MAX_STR_LEN.
EventLabel -- a short descriptive label for the
event of length less than 18 characters.
Note that the preset does not actually have to exist to call these functions.
PAPI_describe_event is used to
translate either an ASCII PAPI preset name or an integer PAPI preset event code
into the corresponding event code or name as well as an ASCII description of
that event. If the EventName argument is a string of length > 0 it is
assumed to contain the name to look up and the corresponding event code is
returned in the argument, EventCode. Otherwise, the EventCode
argument is used to look up the event name, which is stored in the EventName
argument. Finally, a descriptive string of length less than PAPI_MAX_STR_LEN
is copied to the argument, EventDescr. Note that the functionality of
this call is a superset of the PAPI_event_name_to_code and
PAPI_event_code_to_name calls.
PAPI_label_event is used to translate an integer PAPI event code into a short (<=18 character) ASCII label that is more descriptive than the preset name but shorter than the description. These labels can be used as event identifiers in third party tools.
PAPI_event_name_to_code is used to translate an ASCII PAPI preset name into an integer PAPI event code.
PAPI_event_code_to_name is used to translate an integer PAPI event code into an ASCII PAPI preset name.
In the following code example, PAPI_event_name_to_code is used to translate a string into an integer (EventCode) and PAPI_label_event is used to label an event from an event code:
OUTPUT:
Note that the event code is in hexadecimal, which is consistent with all the preset translation functions. The hexadecimal values of each preset are specified in the header file, papiStdEventDefs.h.
On success, all the functions return PAPI_OK and on error, a non-zero error code is returned.
For more information about the preset translation functions, see Appendix C.
The high-level API (Application Programming Interface) simply provides the ability to start, stop, and read the counters for a specified list of events. It is meant for single thread applications and for programmers wanting simple and coarse-grained measurements. In addition, it is not thread safe and allows only PAPI preset events. Some of the benefits of using the high-level API rather than the low-level API are that it is easier to use and requires less setup (additional code).
It should also be noted that the high-level API could be used in conjunction with the low-level API and in fact does call the low-level API. However, the high-level API by itself is only able to access those events countable simultaneously by the underlying hardware.
There are six functions that represent the high-level API that allow the user to access and count specific hardware events. Note that these functions can be implemented in both C and Fortran. For a list and job description of all the high-level functions, see Appendix B. Also, for a code example of using the high-level interface, see Simple Code Examples: High Level API or tests/high-level.c in the PAPI source distribution.
The PAPI library can be initialized implicitly by calling one of the following three high-level functions:
C:
PAPI_num_counters()
PAPI_start_counters(*events, array_length)
PAPI_flops(*real_time, *proc_time, *flpins, *mflops)
Fortran:
PAPIF_num_counters(check)
PAPIF_start_counters(*events, array_length, check)
PAPIF_flops(real_time, proc_time, flpins, mflops, check)
*events -- an array of codes for events such as
PAPI_INT_INS or a native event code.
array_length -- the number of items in the events array.
*real_time -- the total real time since the first PAPI_flops call.
*proc_time -- the total process time since the first PAPI_flops call.
*flpins -- the total floating point instructions since the first PAPI_flops call.
*mflops – Mflops/s achieved since the latest PAPI_flops call.
Note
that one of the above functions must be called before calling any other PAPI
function.
PAPI_num_counters
returns the optimal length of the values array for high-level functions.
This value corresponds to the number of hardware counters supported by the
current substrate. PAPI_num_counters initializes the PAPI library using
PAPI_library_init if necessary.
PAPI_start_counters
initializes the PAPI library (if necessary) and starts counting the events
named in the events array. This function implicitly stops and
initializes any counters running as a result of a previous call to
PAPI_start_counters. It is the user’s responsibility to choose events that can
be counted simultaneously by reading the vendor’s documentation. The length of
the events array should be no longer than the value returned by
PAPI_num_counters.
The first call to PAPI_flops only initializes the library. For more information on PAPI_flops, see the following section:
Mflops/s, Real Time, and Processor Time.
In the following code example, PAPI_num_counters is used to initialize the library and to get the number of hardware counters available on the system. Also, PAPI_start_counters is used to start counting events:
On success, PAPI_num_counters returns the number of hardware counters available on the system and on error, a non-zero error code is returned.
Optionally, the PAPI
library can be initialize explicitly by using PAPI_library_init.
For more information on these functions, see Appendix B.
Counters can be read, added, and stopped by calling the following high-level functions, respectively:
C:
PAPI_read_counters(*values, array_length)
PAPI_accum_counters(*values, array_length)
PAPI_stop_counters(*values, array_length)
Fortran:
PAPIF_read_counters(*values, array_length, check)
PAPIF_accum_counters(*values, array_length, check)
PAPIF_stop_counters(*values, array_length, check)
*values -- an array where to put the counter values.
array_length -- the number of items in the *values array.
PAPI_read_counters and PAPI_accum_counters read (copy) and add the event counters into the array, values, respectively. The counters are reset and left running after the call of these functions.
PAPI_stop_counters stops the counters started by the function, PAPI_start_counters and return their values.
In the following code example, PAPI_read_counters and PAPI_stop_counters are used to copy and stop event counters in an array, respectively:
On success, all of these functions return PAPI_OK and on error, a non-zero error code is returned.
For more information on these functions, see Appendix B.
Mflops/s, real time, and processor time can be obtained by calling the following high-level function:
C:
PAPI_flops(*real_time, *proc_time, *flpins, *mflops)
Fortran:
PAPIF_flops(real_time, proc_time, flpins, mflops, check)
*real_time -- the total real time since the first PAPI_flops call.
*proc_time -- the total process time since the first PAPI_flops call.
*flpins -- the total floating point instructions since the first PAPI_flops call.
*mflops – Mflops/s achieved since the latest PAPI_flops call.
The
first call to PAPI_flops initializes the PAPI library, set up the counters to
monitor PAPI_FP_INS and PAPI_TOT_CYC events, and start the counters. Subsequent
calls will read the counters and return total real time, total process time,
total floating point instructions, and the Mflops/s rate since the last call to
PAPI_flops. Any call with flpins = -1 will reinitialize all counters to 0.
Note that most platforms are only capable of counting the number of floating point instructions completed. This may or may not translate to your definition of floating point operations. The measured rate is thus Mflops/s, and will in some circumstances count FMA instructions as one operation. Consult the hardware documentation for your system for more details.
PAPI_flops may be called by the user’s application program and contains calls to the following functions:
PAPI_perror, PAPI_library_init, PAPI_get_hardware_info, PAPI_create_eventset, PAPI_add_event, PAPI_start, PAPI_get_real_usec, PAPI_accum, and PAPI_shutdown.
On success, it returns PAPI_OK and on error, a non-zero error code is returned.
For more information on this function, see Appendix B. Also, for a code example, see test/flops.c in the papi source distribution.
The low-level API (Application Programming Interface) manages hardware events in user-defined groups called Event Sets. It is meant for experienced application programmers and tool developers wanting more fine-grained measurements. Unlike the high-level interface, it is thread safe and allows both PAPI preset and native events. Another features of the low-level API are the ability to obtain information about the executable and the hardware as well as to set options for multiplexing and overflow handling. Some of the benefits of using the low-level API rather than the high-level API are that it increases efficiency and functionality.
It should also be noted that the low-level interface could be used in conjunction with the high-level interface, but the user would have to be careful about initialization and threads.
The low-level API is only as powerful as the substrate upon which it is built. Thus, some features may not be available on every platform. The converse may also be true, that more advanced features may be available on every platform and defined in the header file. Therefore, the user is encouraged to read the documentation for each platform carefully. There are approximately 40 functions that represent the low-level API, where some of these functions are implemented only in C or Fortran. For more information on these function and their job descriptions, see Appendix C. Also, for a code example of using the low-level interface, see Simple Code Examples: Low-Level API or tests/low_level.c in the PAPI source distribution.
The PAPI library can be initialized explicitly by calling the following low-level function:
C:
PAPI_library_init(version)
Fortran:
PAPIF_library_init(check)
version
-- upon initialization, PAPI checks the
argument against the internal value of PAPI_VER_CURRENT when the library
was compiled. This guards against portability problems when updating the PAPI
shared libraries on your system.
Note that this function must be called before calling
any other PAPI function.
The following is a code example of using PAPI_library_init to initialize the PAPI library:
On success, this function returns PAPI_VER_CURRENT.
On error, a positive return code other than PAPI_VER_CURRENT indicates a library version mismatch and a negative return code indicates an initialization error.
For more information on this function, see Appendix C.
Event Sets are user-defined groups of hardware events (preset or native), which are used in conjunction with one another to provide meaningful information, such as: what low-level hardware counters to use, the most recently read counter values, the state of the Event Set (running/not running), and optional settings (e.g., overflow, profiling). Therefore, Event Sets allow a highly efficient implementation and as a result, users can have more detailed and accurate measurements. In addition, Event Sets are managed by the user through the use of integer handles, which helps simplify inter-language calling conventions. There are no real programming restrictions on the use of Event Sets. The user is free to allocate and use any number of them provided the substrate can provide the required resources. They may be used simultaneously and in fact may even share counter values.
An event set can be created by calling the following the low-level function:
C:
PAPI_create_eventset (*EventSet)
Fortran:
PAPIF_create_eventset(EventSet, check)
EventSet -- Address of an integer location to store the new EventSet handle.
Note that EventSet must be initialized to PAPI_NULL before calling this function. Then, the user may add hardware events to the EventSet by calling PAPI_add_event or similar functions.
On success, this function returns PAPI_OK and on error, a non-zero error code is returned.
For more information on this function, see Appendix C. Also, for a code example, see the next section.
Hardware events can be added to an event set by calling the following the low-level functions:
C:
PAPI_add_event(*EventSet, EventCode)
PAPI_add_events(*EventSet, *EventCode, number)
Fortran:
PAPIF_add_event(EventSet, EventCode, check)
PAPIF_add_events(EventSet, EventCode, number, check)
*EventSet -- an integer handle for a PAPI Event Set as created by PAPI_create_eventset.
EventCode -- a defined event such as PAPI_TOT_INS.
*EventCode -- an array of defined events.
number -- an integer indicating the number of events in the array *EventCode.
PAPI_add_event adds a single hardware event to a PAPI event set.
PAPI_add_events does the same as PAPI_add_event, but for an array of hardware event codes.
In the following code example, the preset event, PAPI_TOT_INS is added to an event set:
On success, both of these functions return PAPI_OK and on error, a non-zero error code is returned.
For more information on these functions, see Appendix C.
Hardware events in an event set can be started, read, added, and stopped by calling the following low-level functions, respectively:
C:
PAPI_start(EventSet)
PAPI_read(EventSet, *values)
PAPI_accum(EventSet, *values)
PAPI_stop(EventSet, *values)
Fortran:
PAPIF_start(EventSet, check)
PAPIF_read(EventSet, values, check)
PAPIF_accum(EventSet, values, check)
PAPIF_stop(EventSet, values, check)
EventSet -- an integer handle for a PAPI Event Set as created by PAPI_create_eventset.
*values -- an array to hold the counter values of the counting events.
PAPI_start starts the counting events in a previously defined event set.
PAPI_read reads (copies) the counters of the indicated event set into the array, values. The counters are left counting after the read without resetting.
PAPI_accum adds the counters of the indicated event set into the array, values. The counters are reset and left counting after the call of this function.
PAPI_stop stops the counting events in a previously defined event set and return the current events.
The following is a code example of using PAPI_start to start the counting of events in an event set, PAPI_read to read the counters of the same event set into the array values, and PAPI_stop to stop the counting of events in the event set:
On success, these functions return PAPI_OK and on error, a non-zero error code is returned.
For more information on these functions, see Appendix C.
The hardware event counts in an event set can be reset to zero by calling the following low-level function:
C:
PAPI_reset(EventSet)
Fortran:
PAPI_reset(EventSet, check)
EventSet -- an integer handle for a PAPI event set as created by PAPI_create_eventset.
Note that the event set must be running or stopped in order to call PAPI_reset.
For example, the EventSet in the code example of the previous section could have been reset to zero by adding the following lines:
if (PAPI_reset(EventSet) != PAPI_OK)
handle_error(1);
On success, this function returns PAPI_OK and on error, a
non-zero error code is returned.
For more information on this function, see Appendix C.
A hardware event and an array of hardware events can be removed from an event set by calling the following low-level functions, respectively:
C:
PAPI_rem_event(EventSet, EventCode)
PAPI_rem_events(EventSet, EventCode, number)
.0pt'>ARGUMENTS
EventSet -- an integer handle for a PAPI event set as created by PAPI_create_eventset.
EventCode -- a defined event such as PAPI_TOT_INS or a native event.
*EventCode -- an array of defined events.
number -- an integer indicating the number of events in the array *EventCode.
PAPI_rem_event removes a single hardware event from a PAPI event set.
PAPI_rem_events, does the same as PAPI_rem_event, but for an array of hardware event codes.
In the following
code example, PAPI_rem_event is used to removed the event, PAPI_TOT_INS, from
an event set:
On success, these functions return PAPI_OK and on error, a non-zero error code is returned.
For more information on these functions, see Appendix C.
All the events in an event set can be emptied and destroyed by calling the following low-level functions, respectively:
C:
PAPI_cleanup_eventset(EventSet)
PAPI_destroy_eventset(EventSet)
Fortran:
PAPIF_cleanup_eventset(EventSet, check)
PAPIF_destroy_eventset(EventSet, check)
EventSet -- an integer handle
for a PAPI event set as created by PAPI_create_eventset.
Note that the event set must be empty in order to use
PAPI_destroy_eventset.
In the following code example, PAPI_cleanup_eventset is used to empty all the events from an event set and PAPI_remove_eventset is used to deallocate the memory associated with the empty event set:
On success, these functions return PAPI_OK and on error, a non-zero error code is returned.
For more information on these functions, see Appendix C.
The counting state of an Event Set can be obtained by calling the following low-level function:
C:
PAPI_state(EventSet, *status)
Fortran:
PAPIF_state(EventSet, status, check)
EventSet -- an integer handle for a PAPI event set as created by PAPI_create_eventset.
status -- an integer containing a Boolean combination of one or
more of the following nonzero constants as defined in the PAPI header file,
papi.h:
PAPI_STOPPED |
EventSet is stopped |
|
PAPI_RUNNING |
EventSet is running |
|
PAPI_PAUSED |
EventSet temporarily disabled by the library |
|
PAPI_NOT_INIT |
EventSet defined, but not initialized |
|
PAPI_OVERFLOWING |
EventSet has overflow enabled |
|
PAPI_PROFILING |
PAPI_MULTIPLEXING |
EventSet has multiplexing enabled |
PAPI_ACCUMULATING |
EventSet has accumulating enabled |
In the following code example, PAPI_state is used to return the counting state of an EventSet:
OUTPUT:
On success, this function returns PAPI_OK and on error, a non-zero error code is returned.
For more information on this function, see Appendix C.
The options of the PAPI library or a specific event set can be obtained and set by calling the following low-level functions, respectively:
C:
PAPI_get_opt(option, ptr)
PAPI_set_opt(option, ptr)
Fortran:
PAPIF_get_clockrate(clockrate)
PAPIF_get_domain(EventSet, domain, mode, check)
PAPIF_get_granularity(EventSet, granularity, mode, check)
PAPIF_get_preload(preload, check)
option -- is an input parameter describing the course of action. The Fortran calls are implementations of specific options. Possible values are defined in papi.h and briefly described below:
Predefined name |
Explanation |
General information requests |
|
PAPI_GET_CLOCKRATE |
Return clockrate in MHz. |
PAPI_GET_MAX_CPUS |
Return number of CPUs. |
PAPI_GET_MAX_HWCTRS |
Return number of counters. |
PAPI_GET_EXEINFO |
Addresses for text/data/bss. |
PAPI_GET_HWINFO |
Info. about hardware. |
PAPI_GET_PRELOAD |
Get ‘‘LD_PRELOAD’’ environment
equivalent. |
Defaults for the global library |
|
PAPI_GET_DEFDOM |
Return the default counting
domain for newly created event sets. |
PAPI_SET_DEFDOM |
Set the default counting
domain. |