libpfm_itanium - support for Itanium specific PMU features
SYNOPSIS
#include <perfmon/pfmlib.h>
#include <perfmon/pfmlib_itanium.h>
int pfm_ita_is_ear(int i);
int pfm_ita_is_dear(int i);
int pfm_ita_is_dear_tlb(int i);
int pfm_ita_is_dear_cache(int i);
int pfm_ita_is_iear(int i);
int pfm_ita_is_iear_tlb(int i);
int pfm_ita_is_iear_cache(int i);
int pfm_ita_is_btb(int i);
int pfm_ita_support_opcm(int i);
int pfm_ita_support_iarr(int i);
int pfm_ita_support_darr(int i);
int pfm_ita_get_event_maxincr(int i, unsigned long *maxincr);
int pfm_ita_get_event_umask(int i, unsigned long *umask);
DESCRIPTION
The libpfm library provides full support for all the Ita
nium specific features of the PMU. The interface is
defined in pfmlib_itanium.h. It consists of a set of func
tions and a structure to describe the model specific fea
tures 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
whether this event support this features or is of a par
ticular kind.
The pfm_ita_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_ita_is_dear() function returns 1 if the event des
ignated by i corresponds to an Data EAR event. Otherwise 0
is returned. It can be a cache or TLB EAR event.
The pfm_ita_is_dear_tlb() function returns 1 if the event
designated by i corresponds to a Data EAR TLB event. Oth
erwise 0 is returned.
The pfm_ita_is_dear_cache() function returns 1 if the
event designated by i corresponds to a Data EAR cache
event. Otherwise 0 is returned.
ignated by i corresponds to an instruction EAR event. Oth
erwise 0 is returned. It can be a cache or TLB instruc
tion EAR event.
The pfm_ita_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_ita_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_ita_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_ita_support_iarr() function returns 1 if the event
designated by i supports code address range restrictions,
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_ita_support_darr() function returns 1 if the event
designated by i supports data address range restrictions,
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_ita_get_event_maxincr() function returns in max
incr the maximum number of occurrences per cycle for the
event designated by i. Certain Itanium 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-inclu
sive upper bound for the threshold to program in the PMC
register.
The pfm_ita_get_event_umask() function returns in umask
the umask for the event designated by i.
When the Itanium specific features are used, this must be
indicated to the library when calling pfm_dispatch_events
because it influences which PMC registers must be pro
grammed and it can also put some restrictions on what
events can be used. The pfmlib_param_t argument to the
tures. The description is in a model specific structure of
type pfmlib_ita_param_t which must be pointed to by the
pfp_model field in the pfmlib_param_t structure. The
structure is quite complex as it includes a description
for each advanced feature. The definition is as follows:
typedef enum {
PFMLIB_ITA_ISM_BOTH=0,
PFMLIB_ITA_ISM_IA32,
PFMLIB_ITA_ISM_IA64
} pfmlib_ita_ism_t;
typedef struct {
unsigned long thres;
pfmlib_ita_ism_t ism;
} pfmlib_ita_counter_t;
typedef struct {
unsigned char opcm_used;
unsigned long pmc_val;
} pfmlib_ita_opcm_t;
typedef struct {
unsigned char btb_used;
unsigned char btb_tar;
unsigned char btb_tac;
unsigned char btb_bac;
unsigned char btb_tm;
unsigned char btb_ptm;
unsigned char btb_ppm;
unsigned int btb_plm;
} pfmlib_ita_btb_t;
typedef struct {
unsigned char ear_used;
unsigned char ear_is_tlb;
unsigned long ear_umask;
unsigned int ear_plm;
pfmlib_ita_ism_t ear_ism;
} pfmlib_ita_ear_t;
typedef struct {
unsigned int rr_plm;
unsigned long rr_start;
unsigned long rr_end;
unsigned long rr_soff;
unsigned long rr_eoff;
} pfmlib_ita_rr_desc_t;
typedef struct {
unsigned char rr_used;
unsigned int rr_nbr_used;
pfmlib_ita_rr_desc_t rr_limits[4];
pfarg_dbreg_t rr_br[8];
} pfmlib_ita_rr_t;
typedef struct {
unsigned long pfp_magic;
pfmlib_ita_counter_t pfp_ita_counters[PMU_ITA_NUM_COUNTERS];
pfmlib_ita_opcm_t pfp_ita_pmc8;
pfmlib_ita_opcm_t pfp_ita_pmc9;
pfmlib_ita_ear_t pfp_ita_iear;
pfmlib_ita_ear_t pfp_ita_dear;
pfmlib_ita_btb_t pfp_ita_btb;
pfmlib_ita_rr_t pfp_ita_drange;
pfmlib_ita_rr_t pfp_ita_irange;
} pfmlib_ita_param_t;
To avoid errors, the structure begins with a magic number
field pfp_magic. It must be initialized to PFM
LIB_ITA_PARAM_MAGIC. Any attempt to pass a structure with
a wrong magic number will be rejected.
INSTRUCTION SET
The pfp_ita_counters contains additional description for
each of the 4 PMU counters. Itanium 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_ITA_ISM_BOTH
The event will be monitored during IA-64 and IA-32
execution
PFMLIB_ITA_ISM_IA32
The event will only be monitored during IA-32 exe
cution
PFMLIB_ITA_ISM_IA64
The event will only be monitored during IA-64 exe
cution
If ism has a value of zero, it will default to PFM
LIB_ITA_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.
The pfp_ita_pmc8 and pfp_ita_pmc9 fields of type pfm
lib_ita_opcm_t contain the description of what to do with
the opcode matchers. Itanium 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_ita_iear field of type pfmlib_ita_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_is_tlb must be set to 1 if
the event being measured in an instruction EAR TLB event.
The umask to store into PMC10 must be in ear_umask. The
privilege level mask at which the I-EAR will be monitored
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_ITA_ISM_BOTH, PFM
LIB_ITA_ISM_IA32, or PFMLIB_ITA_ISM_IA64.
The pfp_ita_dear field of type pfmlib_ita_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.
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 INSTRUCTION_EAR_EVENTS
depending on the type of EAR.
Method 2
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 instruction set. A counting
monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to
count DATA_EAR_EVENT or INSTRUCTION_EAR_EVENTS
depending on the type of EAR.
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_ita_iear or pfp_ita_dear
structure. This is the free running mode for the
EAR.
BRANCH TRACE BUFFER
The pfp_ita_btb of type pfmlib_ita_btb_t field is used to
configure the Branch Trace Buffer (BTB). If the btb_used
is set, then the library will take the configuration into
account, otherwise any BTB configuration will be ignored.
The various fields in this structure provide means to fil
ter out the kind of branches that gets recorded in the
BTB. Each one represents an element of the branch archi
tecture of the Itanium processor. Refer to the Itanium
specific documentation for more details on the branch
architecture. The fields are as follows:
btb_tar
If the value of this field is 1, then branches pre
dicted by the Target Address Register (TAR) predic
tions are captured. If 0 no branch predicted by the
TAR is included.
btb_tac
If this field is 1, then branches predicted by the
Target Address Cache (TAC) are captured. If 0 no
branch predicted by the TAC is included.
btb_bac
If this field is 1, then branches predicted by the
Branch Address Corrector (BAC) are captured. If 0
no branch predicted by the BAC is included.
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,
then branches with correctly predicted target
address are captured. Finally if this field is 3
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_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 events to moni
tor 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
programmed 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.
Method 4
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
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. The library will make the best effort to
cover only what is requested. It will never cover less
than what is requested. The algorithm will use more than
one pair of debug registers to get a more precise range if
necessary. Hence, up to the 4 pairs can be used to
describe a single range. The library returns the start and
end offsets of the actual range compared to the requested
range. Not all event can be measured while range restric
tion 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 one, 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
table. Each range description is a pfmlib_ita_rr_desc_t
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 rr_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
registers.
The rr_flags is reserved at this point.
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.
SEE ALSO
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