1PAPI_get_opt(3) PAPI PAPI_get_opt(3)
2
6 PAPI_get_opt - get PAPI library or event set options
7 PAPI_get_cmp_opt - get component specific PAPI options
8 PAPI_set_opt - set PAPI library or event set options
9 PAPIF_get_clockrate - get the clockrate (Fortran only)
10 PAPIF_get_domain - get the counting domain (Fortran only)
11 PAPIF_get_granularity - get the counting granularity (Fortran only)
12 PAPIF_get_preload - get the library preload setting (Fortran only)
13
16 C Interface
17 #include <papi.h>
18 int PAPI_get_opt(int option, PAPI_option_t *ptr);
19 int PAPI_get_cmp_opt(int option, PAPI_option_t *ptr, int cidx);
20 int PAPI_set_opt(int option, PAPI_option_t *ptr);
21 Fortran Interface
22 #include fpapi.h
23 PAPIF_get_clockrate(C_INT clockrate)
24 PAPIF_get_domain(C_INT EventSet, C_INT domain, C_INT mode, C_INT check)
25 PAPIF_get_granularity(C_INT EventSet, C_INT granularity, C_INT mode, C_INT check)
26 PAPIF_get_preload(C_STRING preload, C_INT check)
27
30 PAPI_get_opt() and PAPI_set_opt() query or change the options of the
31 PAPI library or a specific event set created by PAPI_cre‐
32 ate_eventset(3).Someoptionsmayrequirethattheeventsetbe bound to a com‐
33 ponent before they can execute successfully. This can be done either by
34 adding an event or by explicitly calling PAPI_assign_eventset_compo‐
35 nent(3).
36 The C interface for these functions passes a pointer to the
38 PAPI_option_t structure. Not all options require or return information
39 in this structure, and not all options are implemented for both get and
40 set. Some options require a component index to be provided. These
41 options are handled explicitly by the PAPI_get_cmp_opt() call for 'get'
42 and implicitly through the option structure for 'set'.
43 The Fortran interface is a series of calls implementing various subsets
45 of the C interface. Not all options in C are available in Fortran.
46 NOTE: Some options, such as PAPI_DOMAIN and PAPI_MULTIPLEX, are also
48 available as separate entry points in both C and Fortran.
49 The reader is urged to see the example code in the PAPI distribution
51 for usage of PAPI_get_opt. The file papi.h contains definitions for
52 the structures unioned in the PAPI_option_t structure.
53
57 option -- is an input parameter describing the course of action. Possi‐
58 ble values are defined in papi.h and briefly described in the table
59 below. The Fortran calls are implementations of specific options.
60 ptr -- is a pointer to a structure that acts as both an input and out‐
62 put parameter. It is defined in papi.h and below.
63 cidx -- An integer identifier for a component. By convention, component
65 0 is always the cpu component.
66 EventSet -- input; a reference to an EventSetInfo structure
68 clockrate -- output; cycle time of this CPU in MHz; *may* be an esti‐
70 mate generated at init time with a quick timing routine
71 domain -- output; execution domain for which events are counted
73 granularity -- output; execution granularity for which events are
75 counted
76 mode -- input; determines if domain or granularity are default or for
78 the current event set
79 preload -- output; environment variable string for preloading
81 libraries
82
85 ┌───────────────────┬───────────────────────────────────────────────┐
86 │ │ │
87 │ │ │
88 │ │ │
89() │ │ │()
90 │ │ │
91 │ │ │
92 │ │ │
93 │ Predefined name │ Explanation │
94 ├───────────────────┴───────────────────────────────────────────────┤
95 │ General information requests │
96 ├───────────────────┬───────────────────────────────────────────────┤
97 │PAPI_CLOCKRATE │ Get clockrate in MHz. │
98 ├───────────────────┼───────────────────────────────────────────────┤
99 │PAPI_MAX_CPUS │ Get number of CPUs. │
100 ├───────────────────┼───────────────────────────────────────────────┤
101 │PAPI_MAX_HWCTRS │ Get number of counters. Requires a component │
102 │ │ index. │
103 ├───────────────────┼───────────────────────────────────────────────┤
104 │PAPI_EXEINFO │ Get Executable addresses for text/data/bss. │
105 ├───────────────────┼───────────────────────────────────────────────┤
106 │PAPI_HWINFO │ Get information about the hardware. │
107 ├───────────────────┼───────────────────────────────────────────────┤
108 │PAPI_SHLIBINFO │ Get shared library information used by the │
109 │ │ program. │
110 ├───────────────────┼───────────────────────────────────────────────┤
111 │PAPI_COMPONENTINFO │ Get the PAPI features the specified component │
112 │ │ supports. Requires a component index. │
113 ├───────────────────┼───────────────────────────────────────────────┤
114 │PAPI_LIB_VERSION │ Get the full PAPI version of the library │
115 ├───────────────────┼───────────────────────────────────────────────┤
116 │PAPI_PRELOAD │ Get ``LD_PRELOAD'' environment equivalent. │
117 ├───────────────────┴───────────────────────────────────────────────┤
118 │ Defaults for the global library │
119 ├───────────────────┬───────────────────────────────────────────────┤
120 │PAPI_DEFDOM │ Get/Set default counting domain for newly │
121 │ │ created event sets. Requires a component │
122 │ │ index. │
123 ├───────────────────┼───────────────────────────────────────────────┤
124 │PAPI_DEFGRN │ Get/Set default counting granularity. │
125 │ │ Requires a component index. │
126 ├───────────────────┼───────────────────────────────────────────────┤
127 │PAPI_DEBUG │ Get/Set the PAPI debug state and the debug │
128 │ │ handler. The available debug states are │
129 │ │ defined in papi.h. The debug state is avail‐ │
130 │ │ able in ptr->debug.level. The debug handler │
131 │ │ is available in ptr->debug.handler. For │
132 │ │ information regarding the behavior of the │
133 │ │ handler, please see the man page for │
134 │ │ PAPI_set_debug. │
135 ├───────────────────┴───────────────────────────────────────────────┤
136 │ Multiplexing control │
137 ├───────────────────┬───────────────────────────────────────────────┤
138 │PAPI_MULTIPLEX │ Get/Set options for multiplexing. │
139 ├───────────────────┼───────────────────────────────────────────────┤
140 │PAPI_MAX_MPX_CTRS │ Get maximum number of multiplexing counters. │
141 │ │ Requires a component index. │
142 ├───────────────────┼───────────────────────────────────────────────┤
143 │PAPI_DEF_MPX_USEC │ Get/Set the sampling time slice in microsec‐ │
144 │ │ onds for multiplexing. │
145 ├───────────────────┴───────────────────────────────────────────────┤
146 │ Manipulating individual event sets │
147 ├───────────────────┬───────────────────────────────────────────────┤
148 │PAPI_ATTACH │ Get thread or process id to which event set │
149 │ │ is attached. Returns TRUE if currently │
150 │ │ attached. Set event set specified in │
151 │ │ ptr->ptr->attach.eventset to be attached to │
152 │ │ thread or process id specified in in │
153 │ │ ptr->attach.tid │
154 ├───────────────────┼───────────────────────────────────────────────┤
155 │PAPI_DETACH │ Get thread or process id to which event set │
156 │ │ is attached. Returns TRUE if currently │
157 │ │ detached. Set event set specified in │
158 │ │ ptr->ptr->attach.eventset to be detached from │
159 │ │ any thread or process id. │
160 ├───────────────────┼───────────────────────────────────────────────┤
161 │PAPI_DOMAIN │ Get/Set domain for a single event set. The │
162 │ │ event set is specified in │
163 │ │ ptr->domain.eventset. Will error if eventset │
164 │ │ is not bound to a component. │
165 ├───────────────────┼───────────────────────────────────────────────┤
166 │PAPI_GRANUL │ Get/Set granularity for a single event set. │
167 │ │ The event set is specified in ptr->granular‐ │
168 │ │ ity.eventset. Will error if eventset is not │
169 │ │ bound to a component. │
170 ├───────────────────┴───────────────────────────────────────────────┤
171 │ Platform specific options │
172 ├───────────────────┬───────────────────────────────────────────────┤
173 │PAPI_DATA_ADDRESS │ Set data address range to restrict event │
174 │ │ counting for event set specified in │
175 │ │ ptr->addr.eventset. Starting and ending │
176 │ │ addresses are specified in ptr->addr.start │
177 │ │ and ptr->addr.end, respectively. If exact │
178 │ │ addresses cannot be instantiated, offsets are │
179 │ │ returned in ptr->addr.start_off and │
180 │ │ ptr->addr.end_off. Currently implemented on │
181 │ │ Itanium only. │
182 ├───────────────────┼───────────────────────────────────────────────┤
183 │PAPI_INSTR_ADDRESS │ Set instruction address range as described │
184 │ │ above. Itanium only. │
185 └───────────────────┴───────────────────────────────────────────────┘
186 The option_t *ptr structure is defined in papi.h and looks something
188 like the following example from the source tree. Users should use the
189 definition in papi.h which is in synch with the library used.
190 typedef union {
192 PAPI_preload_option_t preload;
193 PAPI_debug_option_t debug;
194 PAPI_granularity_option_t granularity;
195 PAPI_granularity_option_t defgranularity;
196 PAPI_domain_option_t domain;
197 PAPI_domain_option_t defdomain;
198 PAPI_attach_option_t attach;
199 PAPI_multiplex_option_t multiplex;
200 PAPI_hw_info_t *hw_info;
201 PAPI_shlib_info_t *shlib_info;
202 PAPI_exe_info_t *exe_info;
203 PAPI_component_info_t *sub_info;
204 PAPI_overflow_option_t ovf_info;
205 PAPI_addr_range_option_t addr;
206 } PAPI_option_t;
207
210 On success, these functions return PAPI_OK. On error, a non-zero error
211 code is returned.
212
215 PAPI_EINVAL
216 One or more of the arguments is invalid.
217 PAPI_ENOEVST
219 The event set specified does not exist.
220 PAPI_ENOCMP
222 The argument cidx is not a valid component.
223 PAPI_EISRUN
225 The event set is currently counting events.
226
229 PAPI_option_t options;
230 if ((num = PAPI_get_cmp_opt(PAPI_MAX_HWCTRS,NULL,0)) <= 0)
232 handle_error();
233 printf("This component has %d counters.0,num);
235 /* Set the domain of this EventSet
237 to counter user and kernel modes for this
238 process */
239 memset(&options,0x0,sizeof(options));
241 options.domain.eventset = EventSet;
242 options.domain.domain = PAPI_DOM_ALL;
243 if (PAPI_set_opt(PAPI_DOMAIN, &options) != PAPI_OK)
244 handle_error();
245
248 The granularity and domain functions are only implemented on some com‐
249 ponents. There are no known bugs in these functions.
250
253 PAPI_set_debug(3),PAPI_set_multiplex(3),PAPI_set_domain(3)
254 ()