|
Packit |
577717 |
.TH LIBPFM 3 "November, 2003" "" "Linux Programmer's Manual"
|
|
Packit |
577717 |
.SH NAME
|
|
Packit |
577717 |
libpfm_itanium2 - support for Itanium2 specific PMU features
|
|
Packit |
577717 |
.SH SYNOPSIS
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib.h>
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib_itanium2.h>
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_ear(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_dear(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_dear_tlb(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_dear_cache(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_dear_alat(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_iear(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_iear_tlb(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_iear_cache(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_is_btb(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_support_opcm(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_support_iarr(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_support_darr(unsigned int " i ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_get_event_maxincr(unsigned int "i ", unsigned int *"maxincr ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_get_event_umask(unsigned int "i ", unsigned long *"umask ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_get_event_group(unsigned int "i ", int *"grp ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_get_event_set(unsigned int "i ", int *"set ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_get_ear_mode(unsigned int "i ", pfmlib_ita2_ear_mode_t *"mode ");"
|
|
Packit |
577717 |
.BI "int pfm_ita2_irange_is_fine(pfmlib_output_param_t *"outp ", pfmlib_ita2_output_param_t *"mod_out ");"
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH DESCRIPTION
|
|
Packit |
577717 |
The libpfm library provides full support for all the Itanium 2 specific features
|
|
Packit |
577717 |
of the PMU. The interface is defined in \fBpfmlib_itanium2.h\fR. It consists
|
|
Packit |
577717 |
of a set of functions and structures which describe and allow access to the
|
|
Packit |
577717 |
Itanium 2 specific PMU features.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The Itanium 2 specific functions presented here are mostly used to retrieve
|
|
Packit |
577717 |
the characteristics of an event. Given a opaque event descriptor, obtained
|
|
Packit |
577717 |
by the \fBpfm_find_event()\fR or its derivative functions, they return a boolean value
|
|
Packit |
577717 |
indicating whether this event support this feature or is of a particular
|
|
Packit |
577717 |
kind.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_ear()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to a EAR event, i.e., an Event Address Register
|
|
Packit |
577717 |
type of events. Otherwise 0 is returned. For instance, \fBDATA_EAR_CACHE_LAT4\fR is an ear event, but
|
|
Packit |
577717 |
\fBCPU_CYCLES\fR is not. It can be a data or instruction EAR event.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_dear()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to an Data EAR event. Otherwise 0 is returned.
|
|
Packit |
577717 |
It can be a cache or TLB EAR event.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_dear_tlb()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to a Data EAR TLB event. Otherwise 0 is returned.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_dear_cache()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to a Data EAR cache event. Otherwise 0 is returned.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_dear_alat()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to a ALAT EAR cache event. Otherwise 0 is returned.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_iear()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to an instruction EAR event. Otherwise 0 is returned.
|
|
Packit |
577717 |
It can be a cache or TLB instruction EAR event.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_iear_tlb()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to an instruction EAR TLB event. Otherwise 0 is returned.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_is_iear_cache()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR corresponds to an instruction EAR cache event. Otherwise 0 is returned.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_support_opcm()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR supports opcode matching, i.e., can this event be measured accurately
|
|
Packit |
577717 |
when opcode matching via PMC8/PMC9 is active. Not all events supports this feature.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_support_iarr()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR supports code address range restrictions, i.e., can this event be measured accurately when
|
|
Packit |
577717 |
code range restriction is active. Otherwise 0 is returned. Not all events supports this feature.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_support_darr()\fR function returns 1 if the event
|
|
Packit |
577717 |
designated by \fBi\fR supports data address range restrictions, i.e., can this event be measured accurately when
|
|
Packit |
577717 |
data range restriction is active. Otherwise 0 is returned. Not all events supports this feature.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_get_event_maxincr()\fR function returns in \fBmaxincr\fR the maximum number of
|
|
Packit |
577717 |
occurrences per cycle for the event designated by \fBi\fR. Certain Itanium 2 events can occur more than
|
|
Packit |
577717 |
once per cycle. When an event occurs more than once per cycle, the PMD counter will be incremented accordingly.
|
|
Packit |
577717 |
It is possible to restrict measurement when event occur more than once per cycle. For instance,
|
|
Packit |
577717 |
\fBNOPS_RETIRED\fR can happen up to 6 times/cycle which means that the threshold can be adjusted between 0 and 5,
|
|
Packit |
577717 |
where 5 would mean that the PMD counter would be incremented by 1 only when the nop instruction is executed more
|
|
Packit |
577717 |
than 5 times/cycle. This function returns the maximum number of occurrences of the event per cycle, and
|
|
Packit |
577717 |
is the non-inclusive upper bound for the threshold to program in the PMC register.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_get_event_umask()\fR function returns in \fBumask\fR the umask for the event
|
|
Packit |
577717 |
designated by \fBi\fR.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_get_event_grp()\fR function returns in \fBgrp\fR the group to which the
|
|
Packit |
577717 |
event designated by \fBi\fR belongs. The notion of group is used for L1 and L2 cache events only.
|
|
Packit |
577717 |
For all other events, a group is irrelevant and can be ignored. If the event is an L2
|
|
Packit |
577717 |
cache event then the value of \fBgrp\fR will be \fBPFMLIB_ITA2_EVT_L2_CACHE_GRP\fR. Similarly,
|
|
Packit |
577717 |
if the event is an L1 cache event, the value of \fBgrp\fR will be \fBPFMLIB_ITA2_EVT_L1_CACHE_GRP\fR.
|
|
Packit |
577717 |
In any other cases, the value of \fBgrp\fR will be \fBPFMLIB_ITA2_EVT_NO_GRP\fR.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_get_event_set()\fR function returns in \fBset\fR the set to which the
|
|
Packit |
577717 |
event designated by \fBi\fR belongs. A set is a subdivision of a group and is therefore
|
|
Packit |
577717 |
only relevant for L1 and L2 cache events. An event can only belong to one group and
|
|
Packit |
577717 |
one set. This partitioning of the cache events is due to some hardware limitations which
|
|
Packit |
577717 |
impose some restrictions on events. For a given group, events from different sets
|
|
Packit |
577717 |
cannot be measured at the same time. If the event does not belong to a group
|
|
Packit |
577717 |
then the value of \fBset\fR is \fBPFMLIB_MONT_EVT_NO_SET\fR.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_irange_is_fine()\fR function returns 1 if the configuration description passed
|
|
Packit |
577717 |
in \fBoutp\fR, the generic output parameters and \fBmod_out\fR, the Itanium2 specific output parameters,
|
|
Packit |
577717 |
use code range restriction in fine mode. Otherwise the function returns 0. This function can only be
|
|
Packit |
577717 |
called after a call to the \fBpfm_dispatch_events()\fR function returns successfully and had the data
|
|
Packit |
577717 |
structures pointed to by \fBoutp\fR and \fBmod_out\fR as output parameters.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_ita2_get_event_ear_mode()\fR function returns in \fBmode\fR the EAR mode of the
|
|
Packit |
577717 |
event designated by \fBi\fR. If the event is not an EAR event, then \fBPFMLIB_ERR_INVAL\fR
|
|
Packit |
577717 |
is returned and mode is not updated. Otherwise mode can have the following values:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_EAR_TLB_MODE
|
|
Packit |
577717 |
The event is an EAR TLB mode. It can be either data or instruction TLB EAR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_EAR_CACHE_MODE
|
|
Packit |
577717 |
The event is a cache EAR. It can be either data or instruction cache EAR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_EAR_ALAT_MODE
|
|
Packit |
577717 |
The event is an ALAT EAR. It can only be a data EAR event.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.LP
|
|
Packit |
577717 |
When the Itanium 2 specific features are needed to support a measurement their descriptions must be passed
|
|
Packit |
577717 |
as model-specific input arguments to the \fBpfm_dispatch_events()\fR function. The Itanium 2 specific
|
|
Packit |
577717 |
input arguments are described in the \fBpfmlib_ita2_input_param_t\fR structure and the output
|
|
Packit |
577717 |
parameters in \fBpfmlib_ita2_output_param_t\fR. They are defined as follows:
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
typedef enum {
|
|
Packit |
577717 |
PFMLIB_ITA2_ISM_BOTH=0,
|
|
Packit |
577717 |
PFMLIB_ITA2_ISM_IA32=1,
|
|
Packit |
577717 |
PFMLIB_ITA2_ISM_IA64=2
|
|
Packit |
577717 |
} pfmlib_ita2_ism_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned int flags;
|
|
Packit |
577717 |
unsigned int thres;
|
|
Packit |
577717 |
pfmlib_ita2_ism_t ism;
|
|
Packit |
577717 |
} pfmlib_ita2_counter_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned char opcm_used;
|
|
Packit |
577717 |
unsigned long pmc_val;
|
|
Packit |
577717 |
} pfmlib_ita2_opcm_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned char btb_used;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
unsigned char btb_ds;
|
|
Packit |
577717 |
unsigned char btb_tm;
|
|
Packit |
577717 |
unsigned char btb_ptm;
|
|
Packit |
577717 |
unsigned char btb_ppm;
|
|
Packit |
577717 |
unsigned char btb_brt;
|
|
Packit |
577717 |
unsigned int btb_plm;
|
|
Packit |
577717 |
} pfmlib_ita2_btb_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef enum {
|
|
Packit |
577717 |
PFMLIB_ITA2_EAR_CACHE_MODE= 0,
|
|
Packit |
577717 |
PFMLIB_ITA2_EAR_TLB_MODE = 1,
|
|
Packit |
577717 |
PFMLIB_ITA2_EAR_ALAT_MODE = 2
|
|
Packit |
577717 |
} pfmlib_ita2_ear_mode_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned char ear_used;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
pfmlib_ita2_ear_mode_t ear_mode;
|
|
Packit |
577717 |
pfmlib_ita2_ism_t ear_ism;
|
|
Packit |
577717 |
unsigned int ear_plm;
|
|
Packit |
577717 |
unsigned long ear_umask;
|
|
Packit |
577717 |
} pfmlib_ita2_ear_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned int rr_plm;
|
|
Packit |
577717 |
unsigned long rr_start;
|
|
Packit |
577717 |
unsigned long rr_end;
|
|
Packit |
577717 |
} pfmlib_ita2_input_rr_desc_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned long rr_soff;
|
|
Packit |
577717 |
unsigned long rr_eoff;
|
|
Packit |
577717 |
} pfmlib_ita2_output_rr_desc_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned int rr_flags;
|
|
Packit |
577717 |
pfmlib_ita2_input_rr_desc_t rr_limits[4];
|
|
Packit |
577717 |
unsigned char rr_used;
|
|
Packit |
577717 |
} pfmlib_ita2_input_rr_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
unsigned int rr_nbr_used;
|
|
Packit |
577717 |
pfmlib_ita2_output_rr_desc_t rr_infos[4];
|
|
Packit |
577717 |
pfmlib_reg_t rr_br[8];
|
|
Packit |
577717 |
} pfmlib_ita2_output_rr_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
pfmlib_ita2_counter_t pfp_ita2_counters[PMU_ITA2_NUM_COUNTERS];
|
|
Packit |
577717 |
|
|
Packit |
577717 |
unsigned long pfp_ita2_flags;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
pfmlib_ita2_opcm_t pfp_ita2_pmc8;
|
|
Packit |
577717 |
pfmlib_ita2_opcm_t pfp_ita2_pmc9;
|
|
Packit |
577717 |
pfmlib_ita2_ear_t pfp_ita2_iear;
|
|
Packit |
577717 |
pfmlib_ita2_ear_t pfp_ita2_dear;
|
|
Packit |
577717 |
pfmlib_ita2_btb_t pfp_ita2_btb;
|
|
Packit |
577717 |
pfmlib_ita2_input_rr_t pfp_ita2_drange;
|
|
Packit |
577717 |
pfmlib_ita2_input_rr_t pfp_ita2_irange;
|
|
Packit |
577717 |
} pfmlib_ita2_input_param_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
pfmlib_ita2_output_rr_t pfp_ita2_drange;
|
|
Packit |
577717 |
pfmlib_ita2_output_rr_t pfp_ita2_irange;
|
|
Packit |
577717 |
} pfmlib_ita2_output_param_t;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH PER-EVENT OPTIONS
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The Itanium 2 processor provides two additional per-event features for
|
|
Packit |
577717 |
counters: thresholding and instruction set selection. They can be set using the
|
|
Packit |
577717 |
\fBpfp_ita2_counters\fR data structure for each event. The \fBism\fR
|
|
Packit |
577717 |
field can be initialized as follows:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_ISM_BOTH
|
|
Packit |
577717 |
The event will be monitored during IA-64 and IA-32 execution
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_ISM_IA32
|
|
Packit |
577717 |
The event will only be monitored during IA-32 execution
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_ISM_IA64
|
|
Packit |
577717 |
The event will only be monitored during IA-64 execution
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.LP
|
|
Packit |
577717 |
If \fBism\fR has a value of zero, it will default to PFMLIB_ITA2_ISM_BOTH.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The \fBthres\fR indicates the threshold for the event. A threshold of \fBn\fR means
|
|
Packit |
577717 |
that the counter will be incremented by one only when the event occurs more than \fBn\fR
|
|
Packit |
577717 |
times per cycle.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The \fBflags\fR field contains event-specific flags. The currently defined flags are:
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
PFMLIB_ITA2_FL_EVT_NO_QUALCHECK
|
|
Packit |
577717 |
When this flag is set it indicates that the library should ignore the qualifiers constraints
|
|
Packit |
577717 |
for this event. Qualifiers includes opcode matching, code and data range restrictions. When an
|
|
Packit |
577717 |
event is marked as not supporting a particular qualifier, it usually means that it is ignored, i.e.,
|
|
Packit |
577717 |
the extra level of filtering is ignored. For instance, the CPU_CYCLES event does not support code
|
|
Packit |
577717 |
range restrictions and by default the library will refuse to program it if range restriction is also
|
|
Packit |
577717 |
requested. Using the flag will override the check and the call to the \fBpfm_dispatch_events()\fR function will succeed.
|
|
Packit |
577717 |
In this case, CPU_CYCLES will be measured for the entire program and not just for the code range requested.
|
|
Packit |
577717 |
For certain measurements this is perfectly acceptable as the range restriction will only be applied relevant
|
|
Packit |
577717 |
to events which support it. Make sure you understand which events do not support certain qualifiers before
|
|
Packit |
577717 |
using this flag.
|
|
Packit |
577717 |
.LP
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.SH OPCODE MATCHING
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfp_ita2_pmc8\fR and \fBpfp_ita2_pmc9\fR fields of type \fBpfmlib_ita2_opcm_t\fR contain
|
|
Packit |
577717 |
the description of what to do with the opcode matchers. Itanium 2 supports opcode matching via
|
|
Packit |
577717 |
PMC8 and PMC9. When this feature is used the \fBopcm_used\fR field must be set to 1, otherwise
|
|
Packit |
577717 |
it is ignored by the library. The \fBpmc_val\fR simply contains the raw value to store in
|
|
Packit |
577717 |
PMC8 or PMC9. The library may adjust the value to enable/disable some options depending on the set
|
|
Packit |
577717 |
of features being used. The final value for PMC8 and PMC9 will be stored in the \fBpfp_pmcs\fR
|
|
Packit |
577717 |
table of the generic output parameters.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.SH EVENT ADDRESS REGISTERS
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfp_ita2_iear\fR field of type \fBpfmlib_ita2_ear_t\fR describes what to do with instruction
|
|
Packit |
577717 |
Event Address Registers (I-EARs). Again if this feature is used the \fBear_used\fR must be set to 1,
|
|
Packit |
577717 |
otherwise it will be ignored by the library. The \fBear_mode\fR must be set to either one of
|
|
Packit |
577717 |
\fBPFMLIB_ITA2_EAR_TLB_MODE\fR, \fBPFMLIB_ITA2_EAR_CACHE_MODE\fRto indicate the type of EAR to program.
|
|
Packit |
577717 |
The umask to store into PMC10 must be in \fBear_umask\fR. The privilege level mask at which the I-EAR will be
|
|
Packit |
577717 |
monitored must be set in \fBear_plm\fR which can be any combination of \fBPFM_PLM0\fR, \fBPFM_PLM1\fR,
|
|
Packit |
577717 |
\fBPFM_PLM2\fR, \fBPFM_PLM3\fR. If \fBear_plm\fR is 0 then the default privilege level mask in \fBpfp_dfl_plm\fR is used.
|
|
Packit |
577717 |
Finally the instruction set for which to monitor is in \fBear_ism\fR and can be any one of
|
|
Packit |
577717 |
\fBPFMLIB_ITA2_ISM_BOTH\fR, \fBPFMLIB_ITA2_ISM_IA32\fR, or \fBPFMLIB_ITA2_ISM_IA64\fR.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfp_ita2_dear\fR field of type \fBpfmlib_ita2_ear_t\fR describes what to do with data Event Address
|
|
Packit |
577717 |
Registers (D-EARs). The description is identical to the I-EARs except that it applies to PMC11 and
|
|
Packit |
577717 |
that a \fBear_mode\fR of \fBPFMLIB_ITA2_EAR_ALAT_MODE\fR is possible.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
In general, there are four different methods to program the EAR (data or instruction):
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 1
|
|
Packit |
577717 |
There is an EAR event in the list of events to monitor and \fBear_used\fR is cleared. In this
|
|
Packit |
577717 |
case the EAR will be programmed (PMC10 or PMC11) based on the information encoded in the event.
|
|
Packit |
577717 |
A counting monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to count \fBDATA_EAR_EVENT\fR or \fBL1I_EAR_EVENTS\fR
|
|
Packit |
577717 |
depending on the type of EAR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 2
|
|
Packit |
577717 |
There is an EAR event in the list of events to monitor and \fBear_used\fR is set. In this
|
|
Packit |
577717 |
case the EAR will be programmed (PMC10 or PMC11) using the information in the \fBpfp_ita2_iear\fR or
|
|
Packit |
577717 |
\fBpfp_ita2_dear\fR structure because it contains more detailed information, such as privilege level and
|
|
Packit |
577717 |
instruction set. A counting monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to count DATA_EAR_EVENT or
|
|
Packit |
577717 |
L1I_EAR_EVENTS depending on the type of EAR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 3
|
|
Packit |
577717 |
There is no EAR event in the list of events to monitor and and \fBear_used\fR is cleared. In this case
|
|
Packit |
577717 |
no EAR is programmed.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 4
|
|
Packit |
577717 |
There is no EAR event in the list of events to monitor and and \fBear_used\fR is set. In this case
|
|
Packit |
577717 |
case the EAR will be programmed (PMC10 or PMC11) using the information in the \fBpfp_ita2_iear\fR or
|
|
Packit |
577717 |
\fBpfp_ita2_dear\fR structure. This is the free running mode for the EAR.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH BRANCH TRACE BUFFER
|
|
Packit |
577717 |
The \fBpfp_ita2_btb\fR of type \fBpfmlib_ita2_btb_t\fR field is used to configure the Branch Trace Buffer (BTB). If the
|
|
Packit |
577717 |
\fBbtb_used\fR is set, then the library will take the configuration into account, otherwise any BTB configuration will be ignored.
|
|
Packit |
577717 |
The various fields in this structure provide means to filter out the kind of branches that gets recorded in the BTB.
|
|
Packit |
577717 |
Each one represents an element of the branch architecture of the Itanium 2 processor. Refer to the Itanium 2 specific
|
|
Packit |
577717 |
documentation for more details on the branch architecture. The fields are as follows:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B btb_ds
|
|
Packit |
577717 |
If the value of this field is 1, then detailed information about the branch prediction are recorded in place of information about the target
|
|
Packit |
577717 |
address. If the value is 0, then information about the target address of the branch is recorded instead.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B btb_tm
|
|
Packit |
577717 |
If this field is 0, then no branch is captured. If this field is 1, then non taken branches are captured. If this field is 2, then
|
|
Packit |
577717 |
taken branches are captured. Finally if this field is 3 then all branches are captured.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B btb_ptm
|
|
Packit |
577717 |
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
|
|
Packit |
577717 |
is 2, then branches with correctly predicted target address are captured. Finally if this field is 3 then all branches are captured regardless of
|
|
Packit |
577717 |
target address prediction.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B btb_ppm
|
|
Packit |
577717 |
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
|
|
Packit |
577717 |
is 2, then branches with correctly predicted path are captured. Finally if this field is 3 then all branches are captured regardless of
|
|
Packit |
577717 |
their path prediction.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B btb_brt
|
|
Packit |
577717 |
If this field is 0, then all branches are captured. If this field is 1, then only IP-relative branches are captured. If this field
|
|
Packit |
577717 |
is 2, then only return branches are captured. Finally if this field is 3 then only non-return indirect branches are captured.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B btb_plm
|
|
Packit |
577717 |
This is the privilege level mask at which the BTB captures branches. It can be any combination of \fBPFM_PLM0\fR, \fBPFM_PLM1\fR, \fBPFM_PLM2\fR,
|
|
Packit |
577717 |
\fBPFM_PLM3\fR. If \fBbtb_plm\fR is 0 then the default privilege level mask in \fBpfp_dfl_plm\fR is used.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
There are 4 methods to program the BTB and they are as follows:
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 1
|
|
Packit |
577717 |
The \fBBRANCH_EVENT\fR is in the list of event to monitor and \fBbtb_used\fR is cleared. In this case,
|
|
Packit |
577717 |
the BTB will be configured (PMC12) to record ALL branches. A counting monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to
|
|
Packit |
577717 |
count \fBBRANCH_EVENT\fR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 2
|
|
Packit |
577717 |
The \fBBRANCH_EVENT\fR is in the list of events to monitor and \fBbtb_used\fR is set. In this case,
|
|
Packit |
577717 |
the BTB will be configured (PMC12) using the information in the \fBpfp_ita2_btb\fR structure. A counting monitor
|
|
Packit |
577717 |
(PMC4/PMD4-PMC7/PMD7) will be programmed to count \fBBRANCH_EVENT\fR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 3
|
|
Packit |
577717 |
The \fBBRANCH_EVENT\fR is not in the list of events to monitor and \fBbtb_used\fR is set. In this case,
|
|
Packit |
577717 |
the BTB will be configured (PMC12) using the information in the \fBpfp_ita2_btb\fR structure. This is the
|
|
Packit |
577717 |
free running mode for the BTB.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B Method 4
|
|
Packit |
577717 |
The \fBBRANCH_EVENT\fR is not in the list of events to monitor and \fBbtb_used\fR is cleared. In this case,
|
|
Packit |
577717 |
the BTB is not programmed.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.SH DATA AND CODE RANGE RESTRICTIONS
|
|
Packit |
577717 |
The \fBpfp_ita2_drange\fR and \fBpfp_ita2_irange\fR fields control the range restrictions for the data and
|
|
Packit |
577717 |
code respectively. The idea is that the application passes a set of ranges, each designated by a start
|
|
Packit |
577717 |
and end address. Upon return from the \fBpfm_dispatch_events()\fR function, the application gets back the set of
|
|
Packit |
577717 |
registers and their values that needs to be programmed via a kernel interface.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Range restriction is implemented using the debug registers. There is a limited number of debug registers and they go in pair. With
|
|
Packit |
577717 |
8 data debug registers, a maximum of 4 distinct ranges can be specified. The same applies to code range restrictions. Moreover, there
|
|
Packit |
577717 |
are some severe constraints on the alignment and size of the ranges. Given that the size of a range is specified using a bitmask, there can
|
|
Packit |
577717 |
be situations where the actual range is larger than the requested range. For code ranges, the Itanium 2 processor can use what is called a fine mode,
|
|
Packit |
577717 |
where a range is designated using two pairs of code debug registers. In this mode, the bitmask is not used, the start and end
|
|
Packit |
577717 |
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
|
|
Packit |
577717 |
cannot cross a 4KB page boundary. The library will make a best effort in choosing the right mode for each range. For code ranges,
|
|
Packit |
577717 |
it will try the fine mode first and will default to using the bitmask mode otherwise. Fine mode applies to all code debug
|
|
Packit |
577717 |
registers or none, i.e., you cannot have a range using fine mode and another using the bitmask. the Itanium 2 processor somehow limits the use
|
|
Packit |
577717 |
of multiple pairs to accurately cover a code range. This can only be done for \fBIA64_INST_RETIRED\fR and even then, you need several
|
|
Packit |
577717 |
events to collect the counts. For all other events, only one pair can be used, which leads to more inaccuracy due to
|
|
Packit |
577717 |
approximation. Data ranges can used multiple debug register pairs to gain more accuracy. The library will never cover less than what is
|
|
Packit |
577717 |
requested. The algorithm will use more than one pair of debug registers
|
|
Packit |
577717 |
whenever possible to get a more precise range. Hence, up to the 4 pairs can be used to describe a single range.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If range restriction is to be used, the \fBrr_used\fR field must be set to one, otherwise settings will be ignored.
|
|
Packit |
577717 |
The ranges are described by the \fBpfmlib_ita2_input_rr_t\fR structure. Up to 4 ranges can be defined. Each
|
|
Packit |
577717 |
range is described in by a entry in \fBrr_limits\fR. Some flags for all ranges can be defined in \fBrr_flags\fR.
|
|
Packit |
577717 |
Currently defined flags are:
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_RR_INV
|
|
Packit |
577717 |
Inverse the code ranges. The qualifying events will be measurement when executing outside the specified
|
|
Packit |
577717 |
ranges.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ITA2_RR_NO_FINE_MODE
|
|
Packit |
577717 |
Force non fine mode for all code ranges (mostly for debug)
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.LP
|
|
Packit |
577717 |
The \fBpfmlib_ita2_input_rr_desc_t\fR structure is defined as follows:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_plm
|
|
Packit |
577717 |
The privilege level at which the range is active. It can be any combinations of
|
|
Packit |
577717 |
\fBPFM_PLM0\fR, \fBPFM_PLM1\fR, \fBPFM_PLM2\fR, \fBPFM_PLM3\fR. If \fBbtb_plm\fR is 0 then the
|
|
Packit |
577717 |
default privilege level mask in \fBpfp_dfl_plm\fR is used. The privilege level is only relevant
|
|
Packit |
577717 |
for code ranges, data ranges ignores the setting.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_start
|
|
Packit |
577717 |
This is the start address of the range. Any address is supported but for code range it
|
|
Packit |
577717 |
must be bundle aligned, i.e., 16-byte aligned.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_end
|
|
Packit |
577717 |
This is the end address of the range. Any address is supported but for code range it
|
|
Packit |
577717 |
must be bundle aligned, i.e., 16-byte aligned.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.LP
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The library will provide the values for the debug registers as well as some information
|
|
Packit |
577717 |
about the actual ranges in the output parameters and more precisely in the \fBpfmlib_ita2_output_rr_t\fR
|
|
Packit |
577717 |
structure for each range. The structure is defined as follows:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_nbr_used
|
|
Packit |
577717 |
Contains the number of debug registers used to cover the range. This is necessarily an even number
|
|
Packit |
577717 |
as debug registers always go in pair. The value of this field is between 0 and 7.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_br
|
|
Packit |
577717 |
This table contains the list of debug registers necessary to cover the ranges. Each element is
|
|
Packit |
577717 |
of type \fBpfmlib_reg_t\fR. The \fBreg_num\fR field contains the debug register index while
|
|
Packit |
577717 |
\fBreg_value\fR contains the debug register value. Both the index and value must be copied
|
|
Packit |
577717 |
into the kernel specific argument to program the debug registers. The library never programs them.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_infos
|
|
Packit |
577717 |
Contains information about the ranges defined. Because of alignment restrictions, the actual range
|
|
Packit |
577717 |
covered by the debug registers may be larger than the requested range. This table describe the differences
|
|
Packit |
577717 |
between the requested and actual ranges expressed as offsets:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_soff
|
|
Packit |
577717 |
Contains the start offset of the actual range described by the debug registers. If zero, it means
|
|
Packit |
577717 |
the library was able to match exactly the beginning of the range. Otherwise it represents the number
|
|
Packit |
577717 |
of byte by which the actual range precedes the requested range.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B rr_eoff
|
|
Packit |
577717 |
Contains the end offset of the actual range described by the debug registers. If zero, it means
|
|
Packit |
577717 |
the library was able to match exactly the end of the range. Otherwise it represents the number of
|
|
Packit |
577717 |
bytes by which the actual range exceeds the requested range.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.LP
|
|
Packit |
577717 |
.SH ERRORS
|
|
Packit |
577717 |
Refer to the description of the \fBpfm_dispatch_events()\fR function for errors when using the Itanium 2
|
|
Packit |
577717 |
specific input and output arguments.
|
|
Packit |
577717 |
.SH SEE ALSO
|
|
Packit |
577717 |
pfm_dispatch_events(3) and set of examples shipped with the library
|
|
Packit |
577717 |
.SH AUTHOR
|
|
Packit |
577717 |
Stephane Eranian <eranian@hpl.hp.com>
|
|
Packit |
577717 |
.PP
|