NAME
PAPI_get_opt - get PAPI library or event set options
PAPI_set_opt - set PAPI library or event set options
PAPIF_get_clockrate - get the clockrate (Fortran only)
PAPIF_get_domain - get the counting domain (Fortran only)
PAPIF_get_granularity - get the counting granularity (Fortran only)
PAPIF_get_preload - get the library preload setting (Fortran only)
CONTENTS
Synopsis
Description
Arguments
Options Table
Return Values
Errors
Examples
Ibm Power6 Notes
Bugs
See Also
SYNOPSIS
C Interface
#include <papi.h>
int PAPI_get_opt(int option, PAPI_option_t *ptr);
int PAPI_set_opt(int option, PAPI_option_t *ptr);
Fortran Interface
#include fpapi.h
PAPIF_get_clockrate(C_INT clockrate)
PAPIF_get_domain(C_INT EventSet, C_INT domain, C_INT mode, C_INT check)
PAPIF_get_granularity(C_INT EventSet, C_INT granularity, C_INT mode, C_INT check)
PAPIF_get_preload(C_STRING preload, C_INT check)
DESCRIPTION
PAPI_get_opt() and
PAPI_set_opt() query or change the options of the PAPI library or a specific event set
created by
PAPI_create_eventset (3).
The C interface for these functions passes a pointer to the
PAPI_option_t structure. Not all options require or return information in this structure,
and not all options are implemented for both get and set.
The Fortran interface is a series of calls implementing various subsets of
the C interface. Not all options in C are available in Fortran.
NOTE: Some options, such as PAPI_DOMAIN and PAPI_MULTIPLEX, are also
available as separate entry points in both C and Fortran.
The reader is urged to see the example code in the PAPI distribution
for usage of PAPI_get_opt. The file
papi.h contains definitions for the structures unioned in the
PAPI_option_t structure.
ARGUMENTS
option -- is an input parameter describing the course of action. Possible
values are defined in
papi.h and briefly described in the table below. The Fortran calls are
implementations of specific options.
ptr -- is a pointer to a structure that acts as both an input and output parameter.
It is defined in
papi.h and below.
EventSet -- input; a reference to an EventSetInfo structure
clockrate -- output; cycle time of this CPU in MHz; *may* be an estimate
generated at init time with a quick timing routine
domain -- output; execution domain for which events are counted
granularity -- output; execution granularity for which events are counted
mode -- input; determines if domain or granularity are default
or for the current event set
preload -- output; environment variable string for preloading libraries
OPTIONS TABLE
Predefined name | Explanation |
General information requests |
PAPI_CLOCKRATE | Get clockrate in MHz.
|
PAPI_MAX_CPUS | Get number of CPUs.
|
PAPI_MAX_HWCTRS | Get number of counters.
|
PAPI_EXEINFO | Get Executable addresses for text/data/bss.
|
PAPI_HWINFO | Get information about the hardware.
|
PAPI_SHLIBINFO | Get shared library information used by the program.
|
PAPI_SUBSTRATEINFO | Get the PAPI features the substrate supports
|
PAPI_LIB_VERSION | Get the full PAPI version of the library
|
PAPI_PRELOAD | Get LD_PRELOAD environment equivalent.
|
Defaults for the global library |
PAPI_DEFDOM | Get/Set default counting domain for newly created event sets.
|
PAPI_DEFGRN | Get/Set default counting granularity.
|
PAPI_DEBUG | Get/Set the PAPI debug state and the debug handler. The available debug states are
defined in papi.h. The debug state is available in ptr->debug.level. The debug
handler is available in ptr->debug.handler. For information regarding the behavior
of the handler, please see the man page for PAPI_set_debug.
|
Multiplexing control |
PAPI_MULTIPLEX | Get/Set options for multiplexing.
|
PAPI_MAX_MPX_CTRS | Get maximum number of multiplexing counters.
|
PAPI_DEF_MPX_USEC | Get/Set the sampling time slice in microseconds for multiplexing.
|
Manipulating individual event sets |
PAPI_ATTACH | Get thread or process id to which event set is attached. Returns TRUE
if currently attached.
Set event set specified in ptr->ptr->attach.eventset
to be attached to thread or process id specified in
in ptr->attach.tid
|
PAPI_DETACH | Get thread or process id to which event set is attached. Returns TRUE
if currently detached.
Set event set specified in ptr->ptr->attach.eventset
to be detached from any thread or process id.
|
PAPI_DOMAIN | Get/Set domain for a single event set. The event set is specified
in ptr->domain.eventset
|
PAPI_GRANUL | Get/Set granularity for a single event set. The event set is specified
in ptr->granularity.eventset. Not implemented yet.
|
Platform specific options |
PAPI_DATA_ADDRESS | Set data address range to restrict event counting for event set specified
in ptr->addr.eventset. Starting and ending addresses are specified in
ptr->addr.start and ptr->addr.end, respectively. If exact addresses cannot
be instantiated, offsets are returned in ptr->addr.start_off and
ptr->addr.end_off. Currently implemented on Itanium only.
|
PAPI_INSTR_ADDRESS | Set instruction address range as described above. Itanium only.
|
The
option_t *ptr structure is defined in
papi.h and looks something like the following example from the source tree.
Users should use the definition in
papi.h which is in synch with the library used.
typedef union {
PAPI_preload_option_t preload;
PAPI_debug_option_t debug;
PAPI_granularity_option_t granularity;
PAPI_granularity_option_t defgranularity;
PAPI_domain_option_t domain;
PAPI_domain_option_t defdomain;
PAPI_attach_option_t attach;
PAPI_multiplex_option_t multiplex;
PAPI_hw_info_t *hw_info;
PAPI_shlib_info_t *shlib_info;
PAPI_exe_info_t *exe_info;
PAPI_substrate_info_t *sub_info;
PAPI_overflow_option_t ovf_info;
PAPI_addr_range_option_t addr;
} PAPI_option_t;
RETURN VALUES
On success, these functions return
PAPI_OK. On error, a non-zero error code is returned.
ERRORS
PAPI_EINVAL | |
One or more of the arguments is invalid.
|
PAPI_ENOEVST | |
The event set specified does not exist.
|
PAPI_EISRUN | |
The event set is currently counting events.
|
|
EXAMPLES
PAPI_option_t options;
if ((num = PAPI_get_opt(PAPI_MAX_HWCTRS,NULL)) <= 0)
handle_error();
printf("This machine has %d counters.0,num);
/* Set the domain of this EventSet
to counter user and kernel modes for this
process */
memset(&options,0x0,sizeof(options));
options.domain.eventset = EventSet;
options.domain.domain = PAPI_DOM_ALL;
if (PAPI_set_opt(PAPI_DOMAIN, &options) != PAPI_OK)
handle_error();
IBM POWER6 NOTES
If you call PAPI_set_opt(PAPI_DOMAIN, ...) on an event set containing
either of the events PM_RUN_CYC or PM_RUN_INST_CMPL with a domain
anything other than PAPI_DOM_USER | PAPI_DOM_KERNEL | PAPI_DOM_SUPERVISOR,
you may receive PAPI_ECNFLCT because of restrictions to event counters 5 &
6. For more details, see the IBM POWER6 NOTES in the
PAPI_add_event (3)
documentation.
BUGS
The granularity functions are not yet implemented.
The domain functions are only implemented on some platforms.
There are no known bugs in these functions.
SEE ALSO
PAPI_set_debug (3),
PAPI_set_multiplex (3),
PAPI_set_domain (3)
PAPI Programmers Reference | PAPI_get_opt (3) | October, 2006 |
|