1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 libpfm_montecito - support for Itanium 2 9000 (Montecito) processor
7 specific PMU features
8
10 #include <perfmon/pfmlib.h>
11 #include <perfmon/pfmlib_montecito.h>
12 int pfm_mont_is_ear(unsigned int i);
14 int pfm_mont_is_dear(unsigned int i);
15 int pfm_mont_is_dear_tlb(unsigned int i);
16 int pfm_mont_is_dear_cache(unsigned int i);
17 int pfm_mont_is_dear_alat(unsigned int i);
18 int pfm_mont_is_iear(unsigned int i);
19 int pfm_mont_is_iear_tlb(unsigned int i);
20 int pfm_mont_is_iear_cache(unsigned int i);
21 int pfm_mont_is_etb(unsigned int i);
22 int pfm_mont_support_opcm(unsigned int i);
23 int pfm_mont_support_iarr(unsigned int i);
24 int pfm_mont_support_darr(unsigned int i);
25 int pfm_mont_get_event_maxincr(unsigned int i, unsigned int *maxincr);
26 int pfm_mont_get_event_umask(unsigned int i, unsigned long *umask);
27 int pfm_mont_get_event_group(unsigned int i, int *grp);
28 int pfm_mont_get_event_set(unsigned int i, int *set);
29 int pfm_mont_get_event_type(unsigned int i, int *type);
30 int pfm_mont_get_ear_mode(unsigned int i, pfmlib_mont_ear_mode_t *mode);
31 int pfm_mont_irange_is_fine(pfmlib_output_param_t *outp, pfmlib_mont_output_param_t *mod_out);
32
35 The libpfm library provides full support for all the Itanium 2 900
36 (Montecito) processor specific features of the PMU. The interface is
37 defined in pfmlib_montecito.h. It consists of a set of functions and
38 structures which describe and allow access to the model specific PMU
39 features.
40 The Itanium 2 900 (Montecito) processor specific functions presented
42 here are mostly used to retrieve the characteristics of an event. Given
43 a opaque event descriptor, obtained by pfm_find_event or its deriva‐
44 tives, they return a boolean value indicating whether this event sup‐
45 port this feature or is of a particular kind.
46 The pfm_mont_is_ear() function returns 1 if the event designated by i
48 corresponds to a EAR event, i.e., an Event Address Register type of
49 events. Otherwise 0 is returned. For instance, DATA_EAR_CACHE_LAT4 is
50 an ear event, but CPU_OP_CYCLES_ALL is not. It can be a data or
51 instruction EAR event.
52 The pfm_mont_is_dear() function returns 1 if the event designated by i
54 corresponds to an Data EAR event. Otherwise 0 is returned. It can be a
55 cache or TLB EAR event.
56 The pfm_mont_is_dear_tlb() function returns 1 if the event designated
58 by i corresponds to a Data EAR TLB event. Otherwise 0 is returned.
59 The pfm_mont_is_dear_cache() function returns 1 if the event designated
61 by i corresponds to a Data EAR cache event. Otherwise 0 is returned.
62 The pfm_mont_is_dear_alat() function returns 1 if the event designated
64 by i corresponds to a ALAT EAR cache event. Otherwise 0 is returned.
65 The pfm_mont_is_iear() function returns 1 if the event designated by i
67 corresponds to an instruction EAR event. Otherwise 0 is returned. It
68 can be a cache or TLB instruction EAR event.
69 The pfm_mont_is_iear_tlb() function returns 1 if the event designated
71 by i corresponds to an instruction EAR TLB event. Otherwise 0 is
72 returned.
73 The pfm_mont_is_iear_cache() function returns 1 if the event designated
75 by i corresponds to an instruction EAR cache event. Otherwise 0 is
76 returned.
77 The pfm_mont_support_opcm() function returns 1 if the event designated
79 by i supports opcode matching, i.e., can this event be measured accu‐
80 rately when opcode matching via PMC32/PMC34 is active. Not all events
81 supports this feature.
82 The pfm_mont_support_iarr() function returns 1 if the event designated
84 by i supports code address range restrictions, i.e., can this event be
85 measured accurately when code range restriction is active. Otherwise 0
86 is returned. Not all events supports this feature.
87 The pfm_mont_support_darr() function returns 1 if the event designated
89 by i supports data address range restrictions, i.e., can this event be
90 measured accurately when data range restriction is active. Otherwise 0
91 is returned. Not all events supports this feature.
92 The pfm_mont_get_event_maxincr() function returns in maxincr the maxi‐
94 mum number of occurrences per cycle for the event designated by i. Cer‐
95 tain Itanium 2 9000 (Montecito) events can occur more than once per
96 cycle. When an event occurs more than once per cycle, the PMD counter
97 will be incremented accordingly. It is possible to restrict measure‐
98 ment when event occur more than once per cycle. For instance,
99 NOPS_RETIRED can happen up to 6 times/cycle which means that the
100 threshold can be adjusted between 0 and 5, where 5 would mean that the
101 PMD counter would be incremented by 1 only when the nop instruction is
102 executed more than 5 times/cycle. This function returns the maximum
103 number of occurrences of the event per cycle, and is the non-inclusive
104 upper bound for the threshold to program in the PMC register.
105 The pfm_mont_get_event_umask() function returns in umask the umask for
107 the event designated by i.
108 The pfm_mont_get_event_grp() function returns in grp the group to which
110 the event designated by i belongs. The notion of group is used for L1D
111 and L2D cache events only. For all other events, a group is irrelevant
112 and can be ignored. If the event is an L2D cache event then the value
113 of grp will be PFMLIB_MONT_EVT_L2D_CACHE_GRP. Similarly, if the event
114 is an L1D cache event, the value of grp will be PFM‐
115 LIB_MONT_EVT_L1D_CACHE_GRP. In any other cases, the value of grp will
116 be PFMLIB_MONT_EVT_NO_GRP.
117 The pfm_mont_get_event_set() function returns in set the set to which
119 the event designated by i belongs. A set is a subdivision of a group
120 and is therefore only relevant for L1 and L2 cache events. An event can
121 only belong to one group and one set. This partioning of the cache
122 events is due to some hardware limitations which impose some restric‐
123 tions on events. For a given group, events from different sets cannot
124 be measured at the same time. If the event does not belong to a group
125 then the value of set is PFMLIB_MONT_EVT_NO_SET.
126 The pfm_mont_get_event_type() function returns in type the type of the
128 event designated by i belongs. The itanium2 9000 (Montecito) events
129 can have any one of the following types:
130 PFMLIB_MONT_EVT_ACTIVE
133 The event can only occur when the processor thread that gener‐
134 ated it is currently active
135 PFMLIB_MONT_EVT_FLOATING
137 The event can be generated when the processor thread is inactive
138 PFMLIB_MONT_EVT_CAUSAL
140 The event does not belong to a processor thread
141 PFMLIB_MONT_EVT_SELF_FLOATING
143 Hybrid event. It is floating if measured with .me. If is causal
144 otherwise.
145 The pfm_mont_irange_is_fine function returns 1 if the configuration
147 description passed in outp, the generic output parameters and mod_out,
148 the Itanium 2 9000 (Montecito) specific output parameters, use code
149 range restriction in fine mode. Otherwise the function returns 0. This
150 function can only be called after a call pfm_dispatch_events() which
151 returned successfully and had the data structures pointed to by outp
152 and mod_out as output parameters.
153 The pfm_mont_get_event_ear_mode() function returns in mode the EAR mode
155 of the event designated by i. If the event is not an EAR event, then
156 PFMLIB_ERR_INVAL is returned and mode is not updated. Otherwise mode
157 can have the following values:
158 PFMLIB_MONT_EAR_TLB_MODE
160 The event is an EAR TLB mode. It can be either data or instruc‐
161 tion TLB EAR.
162 PFMLIB_MONT_EAR_CACHE_MODE
164 The event is a cache EAR. It can be either data or instruction
165 cache EAR.
166 PFMLIB_MONT_EAR_ALAT_MODE
168 The event is an ALAT EAR. It can only be a data EAR event.
169 When the Itanium 2 9000 (Montecito) specific features are needed to
172 support a measurement their descriptions must be passed as model-spe‐
173 cific input arguments to the pfm_dispatch_events call. The Itanium 2
174 9000 (Montecito) specific input arguments are described in the pfm‐
175 lib_mont_input_param_t structure and the output parameters in pfm‐
176 lib_mont_output_param_t. They are defined as follows:
177 typedef struct {
179 unsigned int flags;
180 unsigned int thres;
181 } pfmlib_mont_counter_t;
182 typedef struct {
184 unsigned char opcm_used;
185 unsigned char opcm_m;
186 unsigned char opcm_i;
187 unsigned char opcm_f;
188 unsigned char opcm_b;
189 unsigned long opcm_match;
190 unsigned long opcm_mask;
191 } pfmlib_mont_opcm_t;
192 typedef struct {
194 unsigned char etb_used;
195 unsigned int etb_plm;
196 unsigned char etb_ds;
197 unsigned char etb_tm;
198 unsigned char etb_ptm;
199 unsigned char etb_ppm;
200 unsigned char etb_brt;
201 } pfmlib_mont_etb_t;
202 typedef struct {
204 unsigned char ipear_used;
205 unsigned int ipear_plm;
206 unsigned short ipear_delay;
207 } pfmlib_mont_ipear_t;
208 typedef enum {
210 PFMLIB_MONT_EAR_CACHE_MODE= 0,
211 PFMLIB_MONT_EAR_TLB_MODE = 1,
212 PFMLIB_MONT_EAR_ALAT_MODE = 2
213 } pfmlib_mont_ear_mode_t;
214 typedef struct {
216 unsigned char ear_used;
217 pfmlib_mont_ear_mode_t ear_mode;
218 unsigned int ear_plm;
219 unsigned long ear_umask;
220 } pfmlib_mont_ear_t;
221 typedef struct {
223 unsigned int rr_plm;
224 unsigned long rr_start;
225 unsigned long rr_end;
226 } pfmlib_mont_input_rr_desc_t;
227 typedef struct {
229 unsigned long rr_soff;
230 unsigned long rr_eoff;
231 } pfmlib_mont_output_rr_desc_t;
232 typedef struct {
235 unsigned int rr_flags;
236 pfmlib_mont_input_rr_desc_t rr_limits[4];
237 unsigned char rr_used;
238 } pfmlib_mont_input_rr_t;
239 typedef struct {
241 unsigned int rr_nbr_used;
242 pfmlib_mont_output_rr_desc_t rr_infos[4];
243 pfmlib_reg_t rr_br[8];
244 } pfmlib_mont_output_rr_t;
245 typedef struct {
247 pfmlib_mont_counter_t pfp_mont_counters[PMU_MONT_NUM_COUNTERS];
248 unsigned long pfp_mont_flags;
250 pfmlib_mont_opcm_t pfp_mont_opcm1;
252 pfmlib_mont_opcm_t pfp_mont_opcm2;
253 pfmlib_mont_ear_t pfp_mont_iear;
254 pfmlib_mont_ear_t pfp_mont_dear;
255 pfmlib_mont_ipear_t pfp_mont_ipear;
256 pfmlib_mont_etb_t pfp_mont_etb;
257 pfmlib_mont_input_rr_t pfp_mont_drange;
258 pfmlib_mont_input_rr_t pfp_mont_irange;
259 } pfmlib_mont_input_param_t;
260 typedef struct {
262 pfmlib_mont_output_rr_t pfp_mont_drange;
263 pfmlib_mont_output_rr_t pfp_mont_irange;
264 } pfmlib_mont_output_param_t;
265
269 The Itanium 2 9000 (Montecito) processor provides one per-event feature
270 for counters: thresholding. It can be set using the pfp_mont_counters
271 data structure for each event.
272 The thres indicates the threshold for the event. A threshold of n means
274 that the counter will be incremented by one only when the event occurs
275 more than n times per cycle.
276 The flags field contains event-specific flags. The currently defined
278 flags are:
279 PFMLIB_MONT_FL_EVT_NO_QUALCHECK
282 When this flag is set it indicates that the library should
283 ignore the qualifiers constraints for this event. Qualifiers
284 includes opcode matching, code and data range restrictions. When
285 an event is marked as not supporting a particular qualifier, it
286 usually means that it is ignored, i.e., the extra level of fil‐
287 tering is ignored. For instance, the FE_BUBBLE_ALL event does
288 not support code range restrictions and by default the library
289 will refuse to program it if range restriction is also
290 requested. Using the flag will override the check and the call
291 to pfm_dispatch_events will succeed. In this case, FE_BUB‐
292 BLE_ALL will be measured for the entire program and not just for
293 the code range requested. For certain measurements this is per‐
294 fectly acceptable as the range restriction will only be applied
295 relevant to events which support it. Make sure you understand
296 which events do not support certains qualifiers before using
297 this flag.
298
300 The pfp_mont_opcm1 and pfp_mont_opcm2 fields of type pfmlib_mont_opcm_t
301 contain the description of what to do with the opcode matchers. The
302 Itanium 2 9000 (Montecito) processor supports opcode matching via PMC32
303 and PMC34. When this feature is used the opcm_used field must be set to
304 1, otherwise it is ignored by the library. The Itanium 2 9000 (Mon‐
305 tecito) processor implements two full 41-bit opcode matchers. As such,
306 it is possible to match all instructions individually. It is possible
307 to match a single instruction or an instruction pattern based on opcode
308 or slot type. The slots are specified in:
309 opcm_m Match when the instuction is in a M-slot (memory)
311 opcm_i Match when the instruction is in an I-slot (ALU)
313 opcm_f Match when the instruction is in an F-slot (FPU)
315 opcm_b Match when the instruction is in a B-slot (Branch)
317 Any combinations of slot settings is supported. To match all slot
320 types, simply set all fields to 1.
321 The 41-bit opcode is specified in opcm_match and a 41-bit mask is
323 passed in opcm_mask. When a bit is set in opcm_mask the corresponding
324 bit is ignored in opcm_match.
325
328 The pfp_mont_iear field of type pfmlib_mont_ear_t describes what to do
329 with instruction Event Address Registers (I-EARs). Again if this fea‐
330 ture is used the ear_used must be set to 1, otherwise it will be
331 ignored by the library. The ear_mode must be set to either one of PFM‐
332 LIB_MONT_EAR_TLB_MODE, PFMLIB_MONT_EAR_CACHE_MODEto indicate the type
333 of EAR to program. The umask to store into PMC10 must be in ear_umask.
334 The privilege level mask at which the I-EAR will be monitored must be
335 set in ear_plm which can be any combination of PFM_PLM0, PFM_PLM1,
336 PFM_PLM2, PFM_PLM3. If ear_plm is 0 then the default privilege level
337 mask in pfp_dfl_plm is used.
338 The pfp_mont_dear field of type pfmlib_mont_ear_t describes what to do
340 with data Event Address Registers (D-EARs). The description is identi‐
341 cal to the I-EARs except that it applies to PMC11 and that a ear_mode
342 of PFMLIB_MONT_EAR_ALAT_MODE is possible.
343 In general, there are four different methods to program the EAR (data
345 or instruction):
346 Method 1
348 There is an EAR event in the list of events to monitor and
349 ear_used is cleared. In this case the EAR will be programmed
350 (PMC10 or PMC11) based on the information encoded in the event.
351 A counting monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to
352 count DATA_EAR_EVENT or L1I_EAR_EVENTS depending on the type of
353 EAR.
354 Method 2
356 There is an EAR event in the list of events to monitor and
357 ear_used is set. In this case the EAR will be programmed (PMC10
358 or PMC11) using the information in the pfp_ita_iear or
359 pfp_ita_dear structure because it contains more detailed infor‐
360 mation, such as privilege level and isntruction set. A counting
361 monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to count
362 DATA_EAR_EVENT or L1I_EAR_EVENTS depending on the type of EAR.
363 Method 3
365 There is no EAR event in the list of events to monitor and and
366 ear_used is cleared. In this case no EAR is programmed.
367 Method 4
369 There is no EAR event in the list of events to monitor and and
370 ear_used is set. In this case case the EAR will be programmed
371 (PMC10 or PMC11) using the information in the pfp_mont_iear or
372 pfp_mont_dear structure. This is the free running mode for the
373 EAR.
374
377 The pfp_mont_etb of type pfmlib_mont_etb_t field is used to configure
378 the Execution Trace Buffer (ETB). If the etb_used is set, then the
379 library will take the configuration into account, otherwise any ETB
380 configuration will be ignored. The various fields in this structure
381 provide means to filter out the kind of changes in the control flow
382 (branches, traps, rfi, ...) that get recorded in the ETB. Each one
383 represents an element of the branch architecture of the Itanium 2 9000
384 (Montecito) processor. Refer to the Itanium 2 9000 (Montecito) spe‐
385 cific documentation for more details on the branch architecture. The
386 fields are as follows:
387 etb_tm If this field is 0, then no branch is captured. If this field is
389 1, then non taken branches are captured. If this field is 2,
390 then taken branches are captured. Finally if this field is 3
391 then all branches are captured.
392 etb_ptm
394 If this field is 0, then no branch is captured. If this field is
395 1, then branches with a mispredicted target address are cap‐
396 tured. If this field is 2, then branches with correctly pre‐
397 dicted target address are captured. Finally if this field is 3
398 then all branches are captured regardless of target address pre‐
399 diction.
400 etb_ppm
402 If this field is 0, then no branch is captured. If this field is
403 1, then branches with a mispredicted path (taken/non taken) are
404 captured. If this field is 2, then branches with correctly pre‐
405 dicted path are captured. Finally if this field is 3 then all
406 branches are captured regardless of their path prediction.
407 etb_brt
409 If this field is 0, then no branch is captured. If this field is
410 1, then only IP-relative branches are captured. If this field is
411 2, then only return branches are captured. Finally if this field
412 is 3 then only non-return indirect branches are captured.
413 etb_plm
415 This is the privilege level mask at which the ETB captures
416 branches. It can be any combination of PFM_PLM0, PFM_PLM1,
417 PFM_PLM2, PFM_PLM3. If etb_plm is 0 then the default privilege
418 level mask in pfp_dfl_plm is used.
419 There are 4 methods to program the ETB and they are as follows:
421 Method 1
424 The ETB_EVENT is in the list of event to monitor and etb_used is
425 cleared. In this case, the ETB will be configured (PMC39) to
426 record ALL branches. A counting monitor will be programmed to
427 count ETB_EVENT.
428 Method 2
430 The ETB_EVENT is in the list of events to monitor and etb_used
431 is set. In this case, the BTB will be configured (PMC39) using
432 the information in the pfp_mont_etb structure. A counting moni‐
433 tor (PMC4/PMD4-PMC7/PMD7) will be programmed to count
434 BRANCH_EVENT.
435 Method 3
437 The ETB_EVENT is not in the list of events to monitor and
438 etb_used is set. In this case, the ETB will be configured
439 (PMC39) using the information in the pfp_mont_etb structure.
440 This is the free running mode for the ETB.
441 Method 4
443 The ETB_EVENT is not in the list of events to monitor and
444 etb_used is cleared. In this case, the ETB is not programmed.
445
448 The pfp_mont_drange and pfp_mont_irange fields control the range
449 restrictions for the data and code respectively. The idea is that the
450 application passes a set of ranges, each designated by a start and end
451 address. Upon return from pfm_dispatch_events(), the application gets
452 back the set of registers and their values that needs to be programmed
453 via a kernel interface.
454 Range restriction is implemented using the debug registers. There is a
456 limited number of debug registers and they go in pair. With 8 data
457 debug registers, a maximum of 4 distinct ranges can be specified. The
458 same applies to code range restrictions. Moreover, there are some
459 severe constraints on the alignment and size of the ranges. Given that
460 the size of a range is specified using a bitmask, there can be situa‐
461 tions where the actual range is larger than the requested range. For
462 code ranges, Itanium 2 9000 (Montecito) processor can use what is
463 called a fine mode, where a range is designated using two pairs of code
464 debug registers. In this mode, the bitmask is not used, the start and
465 end addresses are directly specified. Not all code ranges qualify for
466 fine mode, the size of the range must be 64KB or less and the range
467 cannot cross a 64KB page boundary. The library will make a best effort
468 in choosing the right mode for each range. For code ranges, it will try
469 the fine mode first and will default to using the bitmask mode other‐
470 wise. Fine mode applies to all code debug registers or none, i.e., you
471 cannot have a range using fine mode and another using the bitmask. The
472 Itanium 2 9000 (Montecito) processor somehow limits the use of multiple
473 pairs to accurately cover a code range. This can only be done for
474 IA64_INST_RETIRED and even then, you need several events to collect the
475 counts. For all other events, only one pair can be used, which leads to
476 more inaccuracy due to approximation. Data ranges can used multiple
477 debug register pairs to gain more accuracy. The library will never
478 cover less than what is requested. The algorithm will use more than
479 one pair of debug registers whenever possible to get a more precise
480 range. Hence, up to the 4 pairs can be used to describe a single range.
481 If range restriction is to be used, the rr_used field must be set to
483 one, otherwise settings will be ignored. The ranges are described by
484 the pfmlib_mont_input_rr_t structure. Up to 4 ranges can be defined.
485 Each range is described in by a entry in rr_limits. Some flags for all
486 ranges can be defined in rr_flags. Currently defined flags are:
487 PFMLIB_MONT_RR_INV
490 Inverse the code ranges. The qualifying events will be measure‐
491 ment when executing outside the specified ranges.
492 PFMLIB_MONT_RR_NO_FINE_MODE
494 Force non fine mode for all code ranges (mostly for debug)
495 The pfmlib_mont_input_rr_desc_t structure is defined as follows:
498 rr_plm The privilege level at which the range is active. It can be any
501 combinations of PFM_PLM0, PFM_PLM1, PFM_PLM2, PFM_PLM3. If
502 etb_plm is 0 then the default privilege level mask in
503 pfp_dfl_plm is used. The privilege level is only relevant for
504 code ranges, data ranges ingores the setting.
505 rr_start
507 This is the start address of the range. Any address is supported
508 but for code range it must be bundle aligned, i.e., 16-byte
509 aligned.
510 rr_end This is the end address of the range. Any address is supported
512 but for code range it must be bundle aligned, i.e., 16-byte
513 aligned.
514 The library will provide the values for the debug registers as well as
517 some information about the actual ranges in the output parameters and
518 more precisely in the pfmlib_mont_output_rr_t structure for each range.
519 The structure is defined as follows:
520 rr_nbr_used
522 Contains the number of debug registers used to cover the range.
523 This is necessarily an even number as debug registers always go
524 in pair. The value of this field is between 0 and 7.
525 rr_br This table contains the list of debug registers necessary to
527 cover the ranges. Each element is of type pfmlib_reg_t. The
528 reg_num field contains the debug register index while reg_value
529 contains the debug register value. Both the index and value must
530 be copied into the kernel specific argument to program the debug
531 registers. The library never programs them.
532 rr_infos
534 Contains information about the ranges defined. Because of align‐
535 ment restrictions, the actual range covered by the debug regis‐
536 ters may be larger than the requested range. This table describe
537 the differences between the requested and actual ranges
538 expressed as offsets:
539 rr_soff
541 Contains the start offset of the actual range described by the
542 debug registers. If zero, it means the library was able to match
543 exactly the beginning of the range. Otherwise it represents the
544 number of byte by which the actual range preceeds the requested
545 range.
546 rr_eoff
548 Contains the end offset of the actual range described by the
549 debug registers. If zero, it means the library was able to match
550 exactly the end of the range. Otherwise it represents the number
551 of bytes by which the actual range exceeds the requested range.
552
555 The Execution Trace Buffer (ETB) can be configured to record the
556 addresses of consecutive retiring instructions. In this case the ETB
557 contains IP addresses and not branches related information. This fea‐
558 ture cannot be used in conjunction with regular branche captures as
559 described above. To active this feature the ipear_used field of the
560 pfmlib_mont_ipear_t must be set to 1. The other fields in this struc‐
561 ture are used as follows:
562 ipear_plm
565 The privilege level of the instructions to capture. It can be
566 any combination of PFM_PLM0, PFM_PLM1, PFM_PLM2, PFM_PLM3. If
567 etb_plm is 0 then the default privilege level mask in
568 pfp_dfl_plm is used.
569 ipear_delay
571 The number of cycles by which to delay the freeze of the ETB
572 after a PMU interrupt (which freeze the rest of counters).
573
575 Refer to the description of pfm_dispatch_events() for errors when using
576 the Itanium 2 9000 (Montecito) specific input and output arguments.
577
579 pfm_dispatch_events(3) and set of examples shipped with the library
580
582 Stephane Eranian <eranian@hpl.hp.com>
583 November, 2003 LIBPFM(3)