libpfm_itanium2 - support for Itanium2 specific PMU fea
tures
SYNOPSIS
#include <perfmon/pfmlib.h>
#include <perfmon/pfmlib_itanium2.h>
int pfm_ita2_is_ear(int i);
int pfm_ita2_is_dear(int i);
int pfm_ita2_is_dear_tlb(int i);
int pfm_ita2_is_dear_cache(int i);
int pfm_ita2_is_dear_alat(int i);
int pfm_ita2_is_iear(int i);
int pfm_ita2_is_iear_tlb(int i);
int pfm_ita2_is_iear_cache(int i);
int pfm_ita2_is_btb(int i);
int pfm_ita2_support_opcm(int i);
int pfm_ita2_support_iarr(int i);
int pfm_ita2_support_darr(int i);
int pfm_ita2_get_event_maxincr(int i, unsigned long *maxincr);
int pfm_ita2_get_event_umask(int i, unsigned long *umask);
int pfm_ita2_get_event_group(int i, int *grp);
int pfm_ita2_get_event_set(int i, int *set);
int pfm_ita2_get_ear_mode(int i, pfmlib_ita2_ear_mode_t *mode);
int pfm_ita2_irange_is_fine(pfmlib_param_t *evt);
DESCRIPTION
The libpfm library provides full support for all the Ita
nium 2 specific features of the PMU. The interface is
defined in pfmlib_itanium2.h. It consists of a set of
functions and a structure to describe the model specific
features used by the application.
The Itanium specific functions presented here are mostly
used to retrieve the characteristics of an event. Given a
opaque event descriptor, obtained by pfm_find_event or its
derivatives, they return a boolean value indicating
whetehr this event support this features or is of a par
ticular kind.
The pfm_ita2_is_ear() function returns 1 if the event des
ignated by i corresponds to a EAR event, i.e., an Event
Address Register type of events. Otherwise 0 is returned.
For instance, DATA_EAR_CACHE_LAT4 is an ear event, but
CPU_CYCLES is not. It can be a data or instruction EAR
event.
The pfm_ita2_is_dear() function returns 1 if the event
designated by i corresponds to an Data EAR event. Other
wise 0 is returned. It can be a cache or TLB EAR event.
The pfm_ita2_is_dear_tlb() function returns 1 if the event
erwise 0 is returned.
The pfm_ita2_is_dear_cache() function returns 1 if the
event designated by i corresponds to a Data EAR cache
event. Otherwise 0 is returned.
The pfm_ita2_is_dear_alat() function returns 1 if the
event designated by i corresponds to a ALAT EAR cache
event. Otherwise 0 is returned.
The pfm_ita2_is_iear() function returns 1 if the event
designated by i corresponds to an instruction EAR event.
Otherwise 0 is returned. It can be a cache or TLB
instruction EAR event.
The pfm_ita2_is_iear_tlb() function returns 1 if the event
designated by i corresponds to an instruction EAR TLB
event. Otherwise 0 is returned.
The pfm_ita2_is_iear_cache() function returns 1 if the
event designated by i corresponds to an instruction EAR
cache event. Otherwise 0 is returned.
The pfm_ita2_support_opcm() function returns 1 if the
event designated by i supports opcode matching, i.e., can
this event be measured accurately when opcode matching via
PMC8/PMC9 is active. Not all events supports this feature.
The pfm_ita2_support_iarr() function returns 1 if the
event designated by i supports code address range restric
tions, i.e., can this event be measured accurately when
code range restriction is active. Otherwise 0 is returned.
Not all events supports this feature.
The pfm_ita2_support_darr() function returns 1 if the
event designated by i supports data address range restric
tions, i.e., can this event be measured accurately when
data range restriction is active. Otherwise 0 is
returned. Not all events supports this feature.
The pfm_ita2_get_event_maxincr() function returns in max
incr the maximum number of occurrences per cycle for the
event designated by i. Certain Itanium 2 events can occur
more than once per cycle. When an event occurs more than
once per cycle, the PMD counter will be incremented
accordingly. It is possible to restrict measurement when
event occur more than once per cycle. For instance,
NOPS_RETIRED can happen up to 6 times/cycle which means
that the threshold can be adjusted between 0 and 5, where
5 would mean that the PMD counter would be incremented by
1 only when the nop instruction is executed more than 5
times/cycle. This function returns the maximum number of
occurrences of the event per cycle, and is the non-
PMC register.
The pfm_ita2_get_event_umask() function returns in umask
the umask for the event designated by i.
The pfm_ita2_get_event_grp() function returns in grp the
group to which the event designated by i belongs. The
notion of group is used for L1 and L2 cache events only.
For all other events, a group is irrelevant and can be
ignored. If the event is an L2 cache event then the value
of grp will be PFMLIB_ITA2_EVT_L2_CACHE_GRP. Similarly, if
the event is an L1 cache event, the value of grp will be
PFMLIB_ITA2_EVT_L1_CACHE_GRP. In any other cases, the
value of grp will be PFMLIB_ITA2_EVT_NO_GRP.
The pfm_ita2_get_event_set() function returns in set the
set to which the event designated by i belongs. A set is a
subdivision of a group and is therefore only relevant for
L1 and L2 cache events. An event can only belong to one
group and one set. This partioning of the cache events is
due to some hardware limitations which impose some
restrictions on events. For a given group, events from
different sets cannot be measured at the same time. If the
event does not belong to a group then the value of set is
-1;
The pfm_ita2_get_event_ear_mode() function returns in mode
the EAR mode of the event designated by i. If the event is
not an EAR event, then PFMLIB_ERR_INVAL is returned and
mode is not updated. Otherwise mode can have the following
values:
The pfm_ita2_irange_is_fine function returns 1 if the con
figuration description passed in evt uses code range
restriction in fine mode. Otherwise the function returns
0. This function can only be called after evt has been
passed to pfm_dispatch_events().
PFMLIB_ITA2_EAR_TLB_MODE
The event is an EAR TLB mode. It can be either data
or instruction TLB EAR.
PFMLIB_ITA2_EAR_CACHE_MODE
The event is a cache EAR. It can be either data or
instruction cache EAR.
PFMLIB_ITA2_EAR_ALAT_MODE
The event is an ALAT EAR. It can only be a data EAR
event.
When the Itanium 2 specific features are used, this
must be indicated to the library when calling
registers must be programmed and it can also put
some restrictions on what events can be used. The
pfmlib_param_t argument to the call does not know
anything about Itanium 2 specific features. The
description is in a model specific structure of
type pfmlib_ita2_param_t which must be pointed to
by the pfp_model field in the pfmlib_param_t struc
ture. The structure is quite complex as it
includes a description for each advanced feature.
The definition is as follows:
typedef enum {
PFMLIB_ITA2_ISM_BOTH=0,
PFMLIB_ITA2_ISM_IA32=1,
PFMLIB_ITA2_ISM_IA64=2
} pfmlib_ita2_ism_t;
typedef struct {
unsigned int thres;
pfmlib_ita2_ism_t ism;
} pfmlib_ita2_counter_t;
typedef struct {
unsigned char opcm_used;
unsigned long pmc_val;
} pfmlib_ita2_opcm_t;
typedef struct {
unsigned char btb_used;
unsigned char btb_ds;
unsigned char btb_tm;
unsigned char btb_ptm;
unsigned char btb_ppm;
unsigned char btb_brt;
unsigned int btb_plm;
} pfmlib_ita2_btb_t;
typedef enum {
PFMLIB_ITA2_EAR_CACHE_MODE=0x0,
PFMLIB_ITA2_EAR_TLB_MODE=0x1,
PFMLIB_ITA2_EAR_ALAT_MODE=0x2
} pfmlib_ita2_ear_mode_t;
typedef struct {
unsigned char ear_used;
pfmlib_ita2_ear_mode_t ear_mode;
pfmlib_ita2_ism_t ear_ism;
unsigned int ear_plm;
unsigned long ear_umask;
} pfmlib_ita2_ear_t;
unsigned int rr_plm;
unsigned long rr_start;
unsigned long rr_end;
unsigned long rr_soff;
unsigned long rr_eoff;
} pfmlib_ita2_rr_desc_t;
typedef struct {
unsigned int rr_flags;
unsigned int rr_nbr_used;
pfmlib_ita2_rr_desc_t rr_limits[4];
pfarg_dbreg_t rr_br[8];
unsigned char rr_used;
} pfmlib_ita2_rr_t;
typedef struct {
unsigned long pfp_magic;
pfmlib_ita2_counter_t pfp_ita2_counters[PMU_ITA2_NUM_COUNTERS];
pfmlib_ita2_opcm_t pfp_ita2_pmc8;
pfmlib_ita2_opcm_t pfp_ita2_pmc9;
pfmlib_ita2_ear_t pfp_ita2_iear;
pfmlib_ita2_ear_t pfp_ita2_dear;
pfmlib_ita2_btb_t pfp_ita2_btb;
pfmlib_ita2_rr_t pfp_ita2_drange;
pfmlib_ita2_rr_t pfp_ita2_irange;
} pfmlib_ita2_param_t;
To avoid errors, the structure begins with a magic
number field pfp_magic. It must be initialized to
PFMLIB_ITA2_PARAM_MAGIC. Any attempt to pass a
structure with a wrong magic number will be
rejected.
INSTRUCTION SET
The pfp_ita2_counters contains additional description for
each of the 4 PMU counters. Itanium 2 provides two addi
tional features for counters: thresholding and instruction
set. Both characteristics can be set on a per event basis.
The ism field can be initialized as follows:
PFMLIB_ITA2_ISM_BOTH
The event will be monitored during IA-64 and IA-32
execution
PFMLIB_ITA2_ISM_IA32
The event will only be monitored during IA-32 exe
cution
PFMLIB_ITA2_ISM_IA64
The event will only be monitored during IA-64
If ism has a value of zero, it will default to PFM
LIB_ITA2_ISM_BOTH.
The thres indicates the threshold for the event. A
threshold of n means that the counter will be
incremented by one only when the event occurs more
than n per cycle.
OPCODE MATCHING
The pfp_ita2_pmc8 and pfp_ita2_pmc9 fields of type pfm
lib_ita2_opcm_t contain the description of what to do with
the opcode matchers. Itanium 2 supports opcode matching
via PMC8 and PMC9. When this feature is used the opcm_used
field must be set to 1, otherwise it is ignored by the
library. The pmc_val simply contains the raw value to
store in PMC8 or PMC9. The library does not modify the
value, it is simply copied into the corresponding
pfarg_reg_t entry.
EVENT ADDRESS REGISTERS
The pfp_ita2_iear field of type pfmlib_ita2_ear_t
describes what to do with instruction EAR. Again if this
feature is used the ear_used must be set to 1, otherwise
it will be ignored by the library. The ear_mode must be
set to either one of PFMLIB_ITA2_EAR_TLB_MODE, PFM
LIB_ITA2_EAR_CACHE_MODEto indicate the type of EAR to pro
gram. The umask to store into PMC10 must be in ear_umask.
The privilege level mask at which the I-EAR will be moni
tored must be set in ear_plm which can be any combination
of PFM_PLM0, PFM_PLM1, PFM_PLM2, PFM_PLM3. If ear_plm is
0 then the default privilege level mask in pfp_dfl_plm is
used. Finally the instruction set for which to monitor is
in ear_ism and can be any one of PFMLIB_ITA2_ISM_BOTH,
PFMLIB_ITA2_ISM_IA32, or PFMLIB_ITA2_ISM_IA64.
The pfp_ita2_dear field of type pfmlib_ita2_ear_t
describes what to do with data EAR. The description is
identical to the one in the previous paragraph except that
it applies to PMC11 and that a ear_mode of PFM
LIB_ITA2_EAR_ALAT_MODE is possible.
In general, there are four different methods to program
the EAR (data or instruction):
Method 1
There is an EAR event in the list of events to mon
itor and ear_used is cleared. In this case the EAR
will be programmed (PMC10 or PMC11) based on the
information encoded in the event. A counting moni
tor (PMC4/PMD4-PMC7/PMD7) will be programmed to
count DATA_EAR_EVENT or L1I_EAR_EVENTS depending on
the type of EAR.
There is an EAR event in the list of events to mon
itor and ear_used is set. In this case the EAR will
be programmed (PMC10 or PMC11) using the informa
tion in the pfp_ita_iear or pfp_ita_dear structure
because it contains more detailed information, such
as privilege level and isntruction set. A counting
monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to
count DATA_EAR_EVENT or L1I_EAR_EVENTS depending on
the type of EAR.
Method 3
There is no EAR event in the list of events to mon
itor and and ear_used is cleared. In this case no
EAR is programmed.
Method 4
There is no EAR event in the list of events to mon
itor and and ear_used is set. In this case case the
EAR will be programmed (PMC10 or PMC11) using the
information in the pfp_ita2_iear or pfp_ita2_dear
structure. This is the free running mode for the
EAR.
BRANCH TRACE BUFFER
The pfp_ita2_btb of type pfmlib_ita2_btb_t field is used
to configure the Branch Trace Buffer (BTB). If the
btb_used is set, then the library will take the configura
tion into account, otherwise any BTB configuration will be
ignored. The various fields in this structure provide
means to filter out the kind of branches that gets
recorded in the BTB. Each one represents an element of
the branch architecture of the Itanium 2 processor. Refer
to the Itanium 2 specific documentation for more details
on the branch architecture. The fields are as follows:
btb_ds If the value of this field is 1, then detailed
information about the branch prediction are
recorded in place of information about the target
address. If the value is 0, then information about
the target address of the branch is recorded
instead.
btb_tm If this field is 0, then no branch is captured. If
this field is 1, then non taken branches are cap
tured. If this field is 2, then taken branches are
captured. Finally if this field is 3 then all
branches are captured.
btb_ptm
If this field is 0, then no branch is captured. If
this field is 1, then branches with a mispredicted
target address are captured. If this field is 2,
address are captured. Finally if this field is 3
then all branches are captured regardless of target
address prediction.
btb_ppm
If this field is 0, then no branch is captured. If
this field is 1, then branches with a mispredicted
path (taken/non taken) are captured. If this field
is 2, then branches with correctly predicted path
are captured. Finally if this field is 3 then all
branches are captured regardless of their path pre
diction.
btb_brt
If this field is 0, then no branch is captured. If
this field is 1, then only IP-relative branches are
captured. If this field is 2, then only return
branches are captured. Finally if this field is 3
then only non-return indirect branches are cap
tured.
btb_plm
This is the privilege level mask at which the BTB
captures branches. It can be any combination of
PFM_PLM0, PFM_PLM1, PFM_PLM2, PFM_PLM3. If btb_plm
is 0 then the default privilege level mask in
pfp_dfl_plm is used.
There are 4 methods to program the BTB and they are
as follows:
Method 1
The BRANCH_EVENT is in the list of event to monitor
and btb_used is cleared. In this case, the BTB will
be configured (PMC12) to record ALL branches. A
counting monitor (PMC4/PMD4-PMC7/PMD7) will be pro
grammed to count BRANCH_EVENT.
Method 2
The BRANCH_EVENT is in the list of events to moni
tor and btb_used is set. In this case, the BTB will
be configured (PMC12) using the information in the
pfp_ita_btb structure. A counting monitor
(PMC4/PMD4-PMC7/PMD7) will be programmed to count
BRANCH_EVENT.
Method 3
The BRANCH_EVENT is not in the list of events to
monitor and btb_used is set. In this case, the BTB
will be configured (PMC12) using the information in
the pfp_ita_btb structure. This is the free running
mode for the BTB.
The BRANCH_EVENT is not in the list of events to
monitor and btb_used is cleared. In this case, the
BTB is not programmed.
CODE RANGE RESTRICTIONS
The pfp_ita_drange and pfp_ita_irange fields control the
range restrictions for the data and code respectively. The
idea is that the application passes a set of ranges, each
designated by a start and end address. Upon return from
pfm_dispatch_events(), the application gets back what
needs to be passed to the perfmonctl() call with the
PFM_WRITE_DBRS or PFM_WRITE_IBRS command. Range restric
tion is implemented using the debug registers. There is a
limited number of debug registers and they go in pair.
With 8 data debug registers, a maximum of 4 distinct
ranges can be specified. The same applies to code range
restrictions. Moreover, they are some severe constraints
on the alignment and size of the range. Given that the
size range is specified using a bitmask, there can be sit
uations where the actual range is larger than the
requested range. For code ranges, Itanium 2 can use what
is called a fine mode, where a range is designated using
two pairs of code debug registers. In this mode, the bit
mask is not used, the start and end addresses are directly
specified. Not all code ranges qualify for fine mode, the
size of the range must be 4KB or less and the range cannot
cross a 4KB page boundary. The library will make a best
effort in choosing the right mode for each range. For code
ranges, it will try the fine mode first and will default
to using the bitmask otherwise. Fien mode applies to all
code debug registers or none, i.e., you cannot have a
range using fine mode and another using the bitmask. Ita
nium 2 somehow limits the use of multiple pairs to accu
rately cover a code range. This can only be done for
IA64_INST_RETIRED and even then, you need several events
to collect the counts. For all other events, only one pair
can be used, which leads to more inaccuracy due to approx
imation. The library will never cover less than what is
requested. The algorithm will use more than one pair of
debug registers whenever possible to get a more precise
range. Hence, up to the 4 pairs can be used to describe a
single range. The library returns the start and end off
sets of the actual range compared to the requested range.
Not all event can be measured while range restriction is
active, the library will detect such conditions and return
an error from pfm_dispatch_events().
If range restriction is to be used, the rr_used field must
be set to 1, otherwise settings will be ignored. The
structure is comprised of two main components: the
description of the ranges in the rr_limits table and the
output parameters to pass to perfmonctl() in the rr_br
structure contains the following fields:
rr_plm The privilege level at which the range is active.
It can be any combinations of PFM_PLM0, PFM_PLM1,
PFM_PLM2, PFM_PLM3. If btb_plm is 0 then the
default privilege level mask in pfp_dfl_plm is
used.
rr_start
This is the start address of the range. User and
kernel level addresses are supported.
rr_end This is the end address of the range. User and ker
nel level addresses are supported.
rr_soff
This field is updated by the library during the
call to pfm_dispatch_events. It contains the start
offset of the actual range described by the debug
registers.
rr_eoff
This field is updated by the library during the
call to pfm_dispatch_events. It contains the end
offset of the actual range described by the debug
registers.
The rr_flags is a bitmask of flags. The currently
defined flags are:
PFMLIB_ITA2_RR_INV
The code range will be inverted, i.e., the PMU will
capture events when they occur outside of the indi
cated range.
PFMLIB_ITA2_RR_NO_FINE_MODE
When set this flag forces the library not to use
the fine mode for code ranges (mostly used for
debugging).
Upon return, the rr_nbr_used field is updated with
the number of debug registers (not pairs) used to
map the ranges. The actual values for the debug
registers are in the rr_br table. Only the first
rr_nbr_used entries in that table are valid and can
be passed directly to perfmonctl().
ERRORS
Refer to the description of pfm_dispatch_events() for
errors when using the pfmlib_ita_param_t structure.
pfm_dispatch_events(3) and set of examples shipped with
the library
AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
Man(1) output converted with
man2html