NAME

• PAPI_get_opt - get PAPI library or event set options
• PAPI_get_cmp_opt - get component specific PAPI 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)

Synopsis

C Interface

#include <papi.h>
int PAPI_get_opt(int  option, PAPI_option_t * ptr );
int PAPI_get_cmp_opt(int  option, PAPI_option_t * ptr, int  cidx );
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). Some options may require that the eventset be bound to a component before they can execute successfully. This can be done either by adding an event or by explicitly calling PAPI_assign_eventset_component (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. Some options require a component index to be provided. These options are handled explicitly by the PAPI_get_cmp_opt() call for 'get' and implicitly through the option structure for '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.

cidx -- An integer identifier for a component. By convention, component 0 is always the cpu component.

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

Errors

PAPI_EINVAL One or more of the arguments is invalid.

PAPI_ENOEVST The event set specified does not exist.

PAPI_ENOCMP The argument cidx is not a valid component.

PAPI_EISRUN The event set is currently counting events.

Examples

PAPI_option_t options;
if ((num = PAPI_get_cmp_opt(PAPI_MAX_HWCTRS,NULL,0)) <= 0)
handle_error();
printf("This component has %d counters.\n",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();

Bugs

The granularity and domain functions are only implemented on some components. There are no known bugs in these functions.

OPTIONS TABLE

General information requests

Defaults for the global library

Multiplexing control

Manipulating individual event sets

Platform specific options

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_component_info_t *sub_info;
PAPI_overflow_option_t ovf_info;
PAPI_addr_range_option_t addr;
} PAPI_option_t;

See Also

PAPI_set_debug(3), PAPI_set_multiplex(3), PAPI_set_domain(3)