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 nameExplanation
General information requests
PAPI_CLOCKRATEGet clockrate in MHz.
PAPI_MAX_CPUSGet number of CPUs.
PAPI_MAX_HWCTRSGet number of counters.
PAPI_EXEINFOGet Executable addresses for text/data/bss.
PAPI_HWINFOGet information about the hardware.
PAPI_SHLIBINFOGet shared library information used by the program.
PAPI_SUBSTRATEINFOGet the PAPI features the substrate supports
PAPI_LIB_VERSIONGet the full PAPI version of the library
PAPI_PRELOADGet ‘‘LD_PRELOAD’’ environment equivalent.
Defaults for the global library
PAPI_DEFDOMGet/Set default counting domain for newly created event sets.
PAPI_DEFGRNGet/Set default counting granularity.
PAPI_DEBUGGet/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_MULTIPLEXGet/Set options for multiplexing of the eventset.
PAPI_MAX_MPX_CTRSGet maximum number of multiplexing counters.
PAPI_DEF_MPX_NSGet/Set the sampling time slice in nanoseconds for multiplexing, currently the same as PAPI_DEF_ITIMER_NS. The substrate is free to change the requested value according to the resolution of the underlying implementation.
Control of interrupt timers
Manipulating individual event sets
PAPI_ATTACHGet 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_DETACHGet 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_DOMAINGet/Set domain for a single event set. The event set is specified in ptr->domain.eventset
PAPI_GRANULGet/Set granularity for a single event set. The event set is specified in ptr->granularity.eventset. Not implemented yet.
Platform specific options
PAPI_DATA_ADDRESSSet 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_ADDRESSSet 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_itimer_option_t itimer;
  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_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 Programmer’s Reference PAPI_get_opt (3) October, 2006

  Innovative Computing Laboratory
2001 R&D Winner  
Computer Science Department
  University of Tennessee