PAPI Options

Getting and Setting Options

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:

int option;
PAPI_option_t ptr;
int retval = PAPI_get_opt(option, &ptr);

Arguments for PAPI_get_opt:

• 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 in the table below.
• ptr -- pointer to a structure determined by the selected option. See PAPI_option_t below or within papi.hfor a description of possible structures.

int option;
PAPI_option_t ptr;
int retval = PAPI_set_opt(option, &ptr);

Arguments for PAPI_set_opt:

• 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 in the table below.
• ptr -- pointer to a structure determined by the selected option. See PAPI_option_t below or within papi.h for a description of possible structures.

Fortran:

use iso_c_binding
integer(c_int) clockrate
call PAPIF_get_clockrate(clockrate)

• clockrate -- stores return value for clockrate in MHz for the current cpu.

use iso_c_binding
integer(c_int) EventSet, domain, mode, check
call PAPIF_get_domain(EventSet, domain, mode, check)

Fortran arguments for PAPIF_get_domain:

• EventSet -- an integer handle for a PAPI Event Set as created by PAPI_create_eventset.
• domain -- stores domain setting for specified EventSet.
• mode -- 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 in the table below.
• check -- an error return value for Fortran.

use iso_c_binding
integer(c_int) EventSet, granularity, mode, check
call PAPIF_get_granularity(EventSet, granularity, mode, check)

Fortran arguments for PAPIF_get_granularity:

• EventSet -- an integer handle for a PAPI Event Set as created by PAPI_create_eventset.
• granularity -- stores the granularity setting for the specified EventSet.
• mode -- 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 in the table below.
• check -- an error return value for Fortran.

use iso_c_binding
character(PAPI_MAX_STR_LEN, c_char) preload
integer(c_int) check
call PAPIF_get_preload(preload, check)

Fortran arguments for PAPIF_get_preload:

• preload -- stores return value for environment variable.
• check -- an error return value for Fortran.

The below table shows various Option definitions that are available. As a note the table is non exhaustive and if you would like to see all available Options please visit papi.h.

Option 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_COMPONENTINFO	Find out what the component 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 the default counting domain for newly created event sets.
PAPI_DEFGRN	Get/Set the 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 more 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_NS	Get the sampling time slice in nanoseconds for multiplexing and overflow.
PAPI_DEF_ITIMER	Get the type of itimer used in software multiplexing, overflowing and profiling.
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_CPU_ATTACH	Get ptr->cpu.cpu_num and Attach state for EventSet specified in ptr->cpu.eventset.
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.
PAPI_INHERIT	Get current inheritance state for specified EventSet.
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.

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. In the C interface, these functions pass a pointer to the PAPI_option_t structure. Not all options require or return information in this structure. 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 that a number of options are available as separate entry points in both C and Fortran. This can make calling sequences simpler. Some of the calls that are simply wrappers to PAPI_get_opt and PAPI_set_opt are listed below:

• PAPI_get_executable_info -- get the executable’s address space information.
• PAPI_get_hardware_info -- get information about the system hardware.
• PAPI_get_multiplex -- get the multiplexing status of specified event set.
• PAPI_get_shared_lib_info -- get information about the shared libraries used by the process.
• PAPI_get_component_info -- get information about the component features.
• PAPI_set_debug -- set the current debug level for PAPI.
• PAPI_set_domain -- set the default execution domain for new event sets.
• PAPI_set_granularity -- get/set the default granularity for new event sets.
• PAPI_set_multiplex -- convert a standard event set to a multiplexed event set.

The PAPI_option_t structure is actually a union of structures that provide specific information for each of the options defined in the table above. This union is defined as shown below:

typedef union {
    PAPI_preload_info_t preload;
    PAPI_debug_option_t debug;
    PAPI_inherit_option_t inherit;
    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_cpu_option_t cpu;
    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_component_info_t *cmp_info;
    PAPI_addr_range_option_t addr;
    PAPI_user_defined_events_file_t events_file;
} PAPI_option_t;

Each of these individual structures, as defined in papi.h, is shown below:

For PAPI_PRELOAD:

typedef struct _papi_preload_option {
    char lib_preload_env[PAPI_MAX_STR_LEN];   
    char lib_preload_sep;
    char lib_dir_env[PAPI_MAX_STR_LEN];
    char lib_dir_sep;
} PAPI_preload_info_t;

For PAPI_DEBUG:

typedef int (*PAPI_debug_handler_t) (int code);		
typedef struct _papi_debug_option {
    int level;
    PAPI_debug_handler_t handler;
} PAPI_debug_option_t;

For PAPI_INHERIT:

typedef struct _papi_inherit_option {
    int eventset;
    int inherit;
} PAPI_inherit_option_t;

For PAPI_DEFGRN and PAPI_GRANUL:

typedef struct _papi_granularity_option {
    int def_cidx; /* Requires a component index to set default granularity */
    int eventset;
    int granularity;
} PAPI_granularity_option_t;

For PAPI_DOMAIN and PAPI_DEFDOM:

typedef struct _papi_domain_option {
    int def_cidx; /* Requires a component index to set default domains */
    int eventset;
    int domain;
} PAPI_domain_option_t;

For PAPI_ATTACH and PAPI_DETACH:

typedef struct _papi_attach_option {
    int eventset;
    unsigned long tid;
} PAPI_attach_option_t;

For PAPI_CPU:

typedef struct _papi_cpu_option {
    int eventset;
    unsigned int cpu_num;
} PAPI_cpu_option_t;

For PAPI_MULTIPLEX:

typedef struct _papi_multiplex_option {
    int eventset;
    int ns;
    int flags;
} PAPI_multiplex_option_t;

For PAPI_ITIMER:

typedef struct _papi_itimer_option {
    int itimer_num;
    int itimer_sig;
    int ns;
    int flags;
} PAPI_itimer_option_t;

For PAPI_HWINFO:

typedef struct _papi_hw_info {
    int ncpu;                 /* Number of CPU's in an SMP Node */
    int threads;              /* Number of hdw threads per core */
    int cores;                /* Number of cores per socket */
    int sockets;              /* Number of sockets */
    int nnodes;               /* Number of Nodes in the entire system */
    int totalcpus;            /* Total number of CPU's in the entire system */
    int vendor;               /* Vendor number of CPU */
    char vendor_string[PAPI_MAX_STR_LEN];     /* Vendor string of CPU */
    int model;                /* Model number of CPU */
    char model_string[PAPI_MAX_STR_LEN];      /* Model string of CPU */
    float revision;           /* Revision of CPU */
    int cpuid_family;         /* cpuid family */
    int cpuid_model;          /* cpuid_model */
    int cpuid_stepping;       /*cpuid stepping */

    int cpu_max_mhz;          /* Maximum supported CPU speed */
    int cpu_min_mhz;          /* Minimum supported CPU speed */
    
    PAPI_mh_info_t mem_hierarchy;  /* PAPI memory heirarchy description */
    int virtualized;               /* Running in virtual machine */
    char virtual_vendor_string[PAPI_MAX_STR_LEN]; 
                                   /* Vendor for virtual machine */
    char virtual_vendor_version[PAPI_MAX_STR_LEN];
                                   /* Version of virtual machine */
    int reserved[8];

} PAPI_hw_info_t;

For PAPI_SHLIBINFO:

typedef struct _papi_shared_lib_info {
    PAPI_address_map_t *map;
    int count;
} PAPI_shlib_info_t;

For PAPI_EXEINFO:

typedef struct _papi_program_info {
    char fullname[PAPI_HUGE_STR_LEN];  /* path+name */
    PAPI_address_map_t address_info;   /* executable's address space info */
} PAPI_exe_info_t;

For PAPI_CMPINFO:

typedef struct _papi_component_option {
     char name[PAPI_MAX_STR_LEN];            /* Name of the component we're using */
     char short_name[PAPI_MIN_STR_LEN];      /* Short name of component,
					     to be prepended to event names */
     char description[PAPI_MAX_STR_LEN];     /* Description of the component */
     char version[PAPI_MIN_STR_LEN];         /* Version of this component */
     char support_version[PAPI_MIN_STR_LEN]; /* Version of the support library */
     char kernel_version[PAPI_MIN_STR_LEN];  /* Version of the kernel PMC support driver */
     char disabled_reason[PAPI_HUGE_STR_LEN]; /* Reason for failure of initialization */
     int disabled;   /* 0 if enabled, otherwise error code from initialization */
     int initialized;                        /* Component is ready to use */
     int CmpIdx;				/* Index into the vector array for this component; set at init time */
     int num_cntrs;               /* Number of hardware counters the component supports */
     int num_mpx_cntrs;           /* Number of hardware counters the component or PAPI can multiplex supports */
     int num_preset_events;       /* Number of preset events the component supports */
     int num_native_events;       /* Number of native events the component supports */
     int default_domain;          /* The default domain when this component is used */
     int available_domains;       /* Available domains */ 
     int default_granularity;     /* The default granularity when this component is used */
     int available_granularities; /* Available granularities */
     int hardware_intr_sig;       /* Signal used by hardware to deliver PMC events */
     int component_type;          /* Type of component */
     char *pmu_names[PAPI_PMU_MAX];         /* list of pmu names supported by this component */
     int reserved[8];             /* */
     unsigned int hardware_intr:1;         /* hw overflow intr, does not need to be emulated in software*/
     unsigned int precise_intr:1;          /* Performance interrupts happen precisely */
     unsigned int posix1b_timers:1;        /* Using POSIX 1b interval timers (timer_create) instead of setitimer */
     unsigned int kernel_profile:1;        /* Has kernel profiling support (buffered interrupts or sprofil-like) */
     unsigned int kernel_multiplex:1;      /* In kernel multiplexing */
     unsigned int fast_counter_read:1;     /* Supports a user level PMC read instruction */
     unsigned int fast_real_timer:1;       /* Supports a fast real timer */
     unsigned int fast_virtual_timer:1;    /* Supports a fast virtual timer */
     unsigned int attach:1;                /* Supports attach */
     unsigned int attach_must_ptrace:1;	   /* Attach must first ptrace and stop the thread/process*/
     unsigned int cntr_umasks:1;           /* counters have unit masks */
     unsigned int cpu:1;                   /* Supports specifying cpu number to use with event set */
     unsigned int inherit:1;               /* Supports child processes inheriting parents counters */
     unsigned int reserved_bits:19;
} PAPI_component_info_t;

For PAPI_DATA_ADDRESS and PAPI_INSTR_ADDRESS:

/* address range specification for range restricted counting */
typedef struct _papi_addr_range_option { /* if both are zero, range disabled */
	int eventset;           /* Eventset to restrict */
	vptr_t start;          /* User requested start address of address range */
	vptr_t end;            /* User requested end address of an address range */
	int start_off;          /* Hardware specified offset from start address */
	int end_off;            /* Hardware specified offset from end address */
} PAPI_addr_range_option_t;

The file, papi.h, contains current definitions for the structures unioned in the PAPI_option_t structure. Users should refer to papi.h for specifics on the use of fields in these structures.

In the following code example, PAPI_get_opt is used to acquire the option, PAPI_MAX_HWCTRS, of an event set and PAPI_set_opt is used to set the option, PAPI_DOMAIN, to the same event set:

#include <papi.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void handle_error (int retval)
{
    printf("PAPI error %d: %s\n", retval, PAPI_strerror(retval));
    exit(1);
}

int main()
{
    int num, retval, EventSet = PAPI_NULL;
    PAPI_option_t options;
 
    /* Initialize the PAPI library */
    retval = PAPI_library_init(PAPI_VER_CURRENT); 
    if (retval != PAPI_VER_CURRENT)
        handle_error(retval);
   
    retval = PAPI_get_opt(PAPI_MAX_HWCTRS,NULL);
    if (retval  < 0)
        handle_error(retval);
 
    printf("This machine has %d counters.\n", retval);

    retval = PAPI_create_eventset(&EventSet);
    if (retval != PAPI_OK)
        handle_error(retval);
  
    /* Fill memory at options address */    
    memset(&options,0x0,sizeof(options));

    /* Must set componen index */
    retval = PAPI_assign_eventset_component(EventSet, 0); 
    if (retval != PAPI_OK)
        handle_error(retval);    

    options.domain.eventset = EventSet;
    options.domain.domain = PAPI_DOM_ALL;
 
    retval = PAPI_set_opt(PAPI_DOMAIN, &options);
    if (retval != PAPI_OK)
        handle_error(retval);

    /* Executes if all low-level PAPI
    function calls returned PAPI_OK */
    printf("\033[0;32m\n\nPASSED\n\033[0m");
    exit(0);     
}

Possible output (varies on different platforms):

This machine has 5 counters.


PASSED

On success, all PAPI functions return PAPI_OK and the possible above output is returned. On error, a non-zero error code is returned.

For more code examples, see src/ctests/second.c in the PAPI source distribution, or search the ctests codebase for PAPI_set_opt or PAPI_get_opt.