.TH LIBPFM 3 "November, 2003" "" "Linux Programmer's Manual"
.SH NAME
libpfm_montecito - support for Itanium 2 9000 (Montecito) processor specific PMU features
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.B #include <perfmon/pfmlib_montecito.h>
.sp
.BI "int pfm_mont_is_ear(unsigned int " i ");"
.BI "int pfm_mont_is_dear(unsigned int " i ");"
.BI "int pfm_mont_is_dear_tlb(unsigned int " i ");"
.BI "int pfm_mont_is_dear_cache(unsigned int " i ");"
.BI "int pfm_mont_is_dear_alat(unsigned int " i ");"
.BI "int pfm_mont_is_iear(unsigned int " i ");"
.BI "int pfm_mont_is_iear_tlb(unsigned int " i ");"
.BI "int pfm_mont_is_iear_cache(unsigned int " i ");"
.BI "int pfm_mont_is_etb(unsigned int " i ");"
.BI "int pfm_mont_support_opcm(unsigned int " i ");"
.BI "int pfm_mont_support_iarr(unsigned int " i ");"
.BI "int pfm_mont_support_darr(unsigned int " i ");"
.BI "int pfm_mont_get_event_maxincr(unsigned int "i ", unsigned int *"maxincr ");"
.BI "int pfm_mont_get_event_umask(unsigned int "i ", unsigned long *"umask ");"
.BI "int pfm_mont_get_event_group(unsigned int "i ", int *"grp ");"
.BI "int pfm_mont_get_event_set(unsigned int "i ", int *"set ");"
.BI "int pfm_mont_get_event_type(unsigned int "i ", int *"type ");"
.BI "int pfm_mont_get_ear_mode(unsigned int "i ", pfmlib_mont_ear_mode_t *"mode ");"
.BI "int pfm_mont_irange_is_fine(pfmlib_output_param_t *"outp ", pfmlib_mont_output_param_t *"mod_out ");"
.sp
.SH DESCRIPTION
The libpfm library provides full support for all the Itanium 2 900 (Montecito)
processor specific features of the PMU. The interface is defined in \fBpfmlib_montecito.h\fR.
It consists of a set of functions and structures which describe and allow access to the
model specific PMU features.
.sp
The Itanium 2 900 (Montecito) processor specific functions presented here are mostly used to retrieve
the characteristics of an event. Given a opaque event descriptor, obtained
by the \fBpfm_find_event()\fR or its derivative functions, they return a boolean value
indicating whether this event support this feature or is of a particular
kind.
.sp
The \fBpfm_mont_is_ear()\fR function returns 1 if the event
designated by \fBi\fR corresponds to a EAR event, i.e., an Event Address Register
type of events. Otherwise 0 is returned. For instance, \fBDATA_EAR_CACHE_LAT4\fR is an ear event, but
\fBCPU_OP_CYCLES_ALL\fR is not. It can be a data or instruction EAR event.
.sp
The \fBpfm_mont_is_dear()\fR function returns 1 if the event
designated by \fBi\fR corresponds to an Data EAR event. Otherwise 0 is returned.
It can be a cache or TLB EAR event.
.sp
The \fBpfm_mont_is_dear_tlb()\fR function returns 1 if the event
designated by \fBi\fR corresponds to a Data EAR TLB event. Otherwise 0 is returned.
.sp
The \fBpfm_mont_is_dear_cache()\fR function returns 1 if the event
designated by \fBi\fR corresponds to a Data EAR cache event. Otherwise 0 is returned.
.sp
The \fBpfm_mont_is_dear_alat()\fR function returns 1 if the event
designated by \fBi\fR corresponds to a ALAT EAR cache event. Otherwise 0 is returned.
.sp
The \fBpfm_mont_is_iear()\fR function returns 1 if the event
designated by \fBi\fR corresponds to an instruction EAR event. Otherwise 0 is returned.
It can be a cache or TLB instruction EAR event.
.sp
The \fBpfm_mont_is_iear_tlb()\fR function returns 1 if the event
designated by \fBi\fR corresponds to an instruction EAR TLB event. Otherwise 0 is returned.
.sp
The \fBpfm_mont_is_iear_cache()\fR function returns 1 if the event
designated by \fBi\fR corresponds to an instruction EAR cache event. Otherwise 0 is returned.
.sp
The \fBpfm_mont_support_opcm()\fR function returns 1 if the event
designated by \fBi\fR supports opcode matching, i.e., can this event be measured accurately
when opcode matching via PMC32/PMC34 is active. Not all events supports this feature.
.sp
The \fBpfm_mont_support_iarr()\fR function returns 1 if the event
designated by \fBi\fR 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.
.sp
The \fBpfm_mont_support_darr()\fR function returns 1 if the event
designated by \fBi\fR 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.
.sp
The \fBpfm_mont_get_event_maxincr()\fR function returns in \fBmaxincr\fR the maximum number of
occurrences per cycle for the event designated by \fBi\fR. Certain Itanium 2 9000 (Montecito) 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,
\fBNOPS_RETIRED\fR 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-inclusive upper bound for the threshold to program in the PMC register.
.sp
The \fBpfm_mont_get_event_umask()\fR function returns in \fBumask\fR the umask for the event
designated by \fBi\fR.
.sp
The \fBpfm_mont_get_event_grp()\fR function returns in \fBgrp\fR the group to which the
event designated by \fBi\fR belongs. The notion of group is used for L1D and L2D cache events only.
For all other events, a group is irrelevant and can be ignored. If the event is
an L2D cache event then the value of \fBgrp\fR will be \fBPFMLIB_MONT_EVT_L2D_CACHE_GRP\fR. Similarly,
if the event is an L1D cache event, the value of \fBgrp\fR will be \fBPFMLIB_MONT_EVT_L1D_CACHE_GRP\fR.
In any other cases, the value of \fBgrp\fR will be \fBPFMLIB_MONT_EVT_NO_GRP\fR.
.sp
The \fBpfm_mont_get_event_set()\fR function returns in \fBset\fR the set to which the
event designated by \fBi\fR 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 partitioning 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 \fBset\fR is \fBPFMLIB_MONT_EVT_NO_SET\fR.
.sp
The \fBpfm_mont_get_event_type()\fR function returns in \fBtype\fR the type of
the event designated by \fBi\fR belongs. The itanium2 9000 (Montecito) events
can have any one of the following types:
.sp
.TP
.B PFMLIB_MONT_EVT_ACTIVE
The event can only occur when the processor thread that generated it is
currently active
.TP
.B PFMLIB_MONT_EVT_FLOATING
The event can be generated when the processor thread is inactive
.TP
.B PFMLIB_MONT_EVT_CAUSAL
The event does not belong to a processor thread
.TP
.B PFMLIB_MONT_EVT_SELF_FLOATING
Hybrid event. It is floating if measured with .me. If is causal otherwise.
.LP
.sp
The \fBpfm_mont_irange_is_fine()\fR function returns 1 if the configuration description passed
in \fBoutp\fR, the generic output parameters and \fBmod_out\fR, the Itanium 2
9000 (Montecito) specific output parameters,
use code range restriction in fine mode. Otherwise the function returns 0. This function can only be
called after a call to the \fBpfm_dispatch_events()\fR function returns successfully and had the data
structures pointed to by \fBoutp\fR and \fBmod_out\fR as output parameters.
.sp
The \fBpfm_mont_get_event_ear_mode()\fR function returns in \fBmode\fR the EAR mode of the
event designated by \fBi\fR. If the event is not an EAR event, then \fBPFMLIB_ERR_INVAL\fR
is returned and mode is not updated. Otherwise mode can have the following values:
.TP
.B PFMLIB_MONT_EAR_TLB_MODE
The event is an EAR TLB mode. It can be either data or instruction TLB EAR.
.TP
.B PFMLIB_MONT_EAR_CACHE_MODE
The event is a cache EAR. It can be either data or instruction cache EAR.
.TP
.B PFMLIB_MONT_EAR_ALAT_MODE
The event is an ALAT EAR. It can only be a data EAR event.
.sp
.LP
When the Itanium 2 9000 (Montecito) specific features are needed to support a measurement their
descriptions must be passed as model-specific input arguments to the \fBpfm_dispatch_events()\fR function.
The Itanium 2 9000 (Montecito) specific input arguments are described in the \fBpfmlib_mont_input_param_t\fR
structure and the output parameters in \fBpfmlib_mont_output_param_t\fR. They are defined as follows:
.sp
.nf
typedef struct {
unsigned int flags;
unsigned int thres;
} pfmlib_mont_counter_t;
typedef struct {
unsigned char opcm_used;
unsigned char opcm_m;
unsigned char opcm_i;
unsigned char opcm_f;
unsigned char opcm_b;
unsigned long opcm_match;
unsigned long opcm_mask;
} pfmlib_mont_opcm_t;
typedef struct {
unsigned char etb_used;
unsigned int etb_plm;
unsigned char etb_ds;
unsigned char etb_tm;
unsigned char etb_ptm;
unsigned char etb_ppm;
unsigned char etb_brt;
} pfmlib_mont_etb_t;
typedef struct {
unsigned char ipear_used;
unsigned int ipear_plm;
unsigned short ipear_delay;
} pfmlib_mont_ipear_t;
typedef enum {
PFMLIB_MONT_EAR_CACHE_MODE= 0,
PFMLIB_MONT_EAR_TLB_MODE = 1,
PFMLIB_MONT_EAR_ALAT_MODE = 2
} pfmlib_mont_ear_mode_t;
typedef struct {
unsigned char ear_used;
pfmlib_mont_ear_mode_t ear_mode;
unsigned int ear_plm;
unsigned long ear_umask;
} pfmlib_mont_ear_t;
typedef struct {
unsigned int rr_plm;
unsigned long rr_start;
unsigned long rr_end;
} pfmlib_mont_input_rr_desc_t;
typedef struct {
unsigned long rr_soff;
unsigned long rr_eoff;
} pfmlib_mont_output_rr_desc_t;
typedef struct {
unsigned int rr_flags;
pfmlib_mont_input_rr_desc_t rr_limits[4];
unsigned char rr_used;
} pfmlib_mont_input_rr_t;
typedef struct {
unsigned int rr_nbr_used;
pfmlib_mont_output_rr_desc_t rr_infos[4];
pfmlib_reg_t rr_br[8];
} pfmlib_mont_output_rr_t;
typedef struct {
pfmlib_mont_counter_t pfp_mont_counters[PMU_MONT_NUM_COUNTERS];
unsigned long pfp_mont_flags;
pfmlib_mont_opcm_t pfp_mont_opcm1;
pfmlib_mont_opcm_t pfp_mont_opcm2;
pfmlib_mont_ear_t pfp_mont_iear;
pfmlib_mont_ear_t pfp_mont_dear;
pfmlib_mont_ipear_t pfp_mont_ipear;
pfmlib_mont_etb_t pfp_mont_etb;
pfmlib_mont_input_rr_t pfp_mont_drange;
pfmlib_mont_input_rr_t pfp_mont_irange;
} pfmlib_mont_input_param_t;
typedef struct {
pfmlib_mont_output_rr_t pfp_mont_drange;
pfmlib_mont_output_rr_t pfp_mont_irange;
} pfmlib_mont_output_param_t;
.fi
.sp
.SH PER-EVENT OPTIONS
.sp
The Itanium 2 9000 (Montecito) processor provides one per-event feature for
counters: thresholding. It can be set using the
\fBpfp_mont_counters\fR data structure for each event.
.sp
The \fBthres\fR indicates the threshold for the event. A threshold of \fBn\fR means
that the counter will be incremented by one only when the event occurs more than \fBn\fR
times per cycle.
The \fBflags\fR field contains event-specific flags. The currently defined flags are:
.sp
.TP
PFMLIB_MONT_FL_EVT_NO_QUALCHECK
When this flag is set it indicates that the library should ignore the qualifiers constraints
for this event. Qualifiers includes opcode matching, code and data range restrictions. When an
event is marked as not supporting a particular qualifier, it usually means that it is ignored, i.e.,
the extra level of filtering is ignored. For instance, the FE_BUBBLE_ALL event does not support code
range restrictions and by default the library will refuse to program it if range restriction is also
requested. Using the flag will override the check and the call to the \fBpfm_dispatch_events()\fR function will succeed.
In this case, FE_BUBBLE_ALL will be measured for the entire program and not just for the code range requested.
For certain measurements this is perfectly acceptable as the range restriction will only be applied relevant
to events which support it. Make sure you understand which events do not support certain qualifiers before
using this flag.
.LP
.SH OPCODE MATCHING
.sp
The \fBpfp_mont_opcm1\fR and \fBpfp_mont_opcm2\fR fields of type \fBpfmlib_mont_opcm_t\fR contain
the description of what to do with the opcode matchers. The Itanium 2 9000 (Montecito) processor supports
opcode matching via PMC32 and PMC34. When this feature is used the \fBopcm_used\fR field must be set to 1,
otherwise it is ignored by the library. The Itanium 2 9000 (Montecito) processor implements two full
41-bit opcode matchers. As such, it is possible to match all instructions individually.
It is possible to match a single instruction or an instruction pattern based on
opcode or slot type. The slots are specified in:
.TP
.B opcm_m
Match when the instruction is in a M-slot (memory)
.TP
.B opcm_i
Match when the instruction is in an I-slot (ALU)
.TP
.B opcm_f
Match when the instruction is in an F-slot (FPU)
.TP
.B opcm_b
Match when the instruction is in a B-slot (Branch)
.sp
.LP
Any combinations of slot settings is supported. To match all slot types, simply
set all fields to 1.
.sp
The 41-bit opcode is specified in \fBopcm_match\fR and a 41-bit mask is passed in
\fBopcm_mask\fR. When a bit is set in \fBopcm_mask\fR the corresponding bit is
ignored in \fBopcm_match\fR.
.SH EVENT ADDRESS REGISTERS
.sp
The \fBpfp_mont_iear\fR field of type \fBpfmlib_mont_ear_t\fR describes what to do with instruction
Event Address Registers (I-EARs). Again if this feature is used the \fBear_used\fR must be set to 1,
otherwise it will be ignored by the library. The \fBear_mode\fR must be set to either one of
\fBPFMLIB_MONT_EAR_TLB_MODE\fR, \fBPFMLIB_MONT_EAR_CACHE_MODE\fRto indicate the type of EAR to program.
The umask to store into PMC10 must be in \fBear_umask\fR. The privilege level mask at which the I-EAR will be
monitored must be set in \fBear_plm\fR which can be any combination of \fBPFM_PLM0\fR, \fBPFM_PLM1\fR,
\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.
.sp
The \fBpfp_mont_dear\fR field of type \fBpfmlib_mont_ear_t\fR describes what to do with data Event Address
Registers (D-EARs). The description is identical to the I-EARs except that it applies to PMC11 and
that a \fBear_mode\fR of \fBPFMLIB_MONT_EAR_ALAT_MODE\fR is possible.
In general, there are four different methods to program the EAR (data or instruction):
.TP
.B Method 1
There is an EAR event in the list of events to monitor and \fBear_used\fR is cleared. In this
case the EAR will be programmed (PMC10 or PMC11) based on the information encoded in the event.
A counting monitor (PMC4/PMD4-PMC7/PMD7) will be programmed to count \fBDATA_EAR_EVENT\fR or \fBL1I_EAR_EVENTS\fR
depending on the type of EAR.
.TP
.B Method 2
There is an EAR event in the list of events to monitor and \fBear_used\fR is set. In this
case the EAR will be programmed (PMC10 or PMC11) using the information in the \fBpfp_ita_iear\fR or
\fBpfp_ita_dear\fR 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
L1I_EAR_EVENTS depending on the type of EAR.
.TP
.B Method 3
There is no EAR event in the list of events to monitor and and \fBear_used\fR is cleared. In this case
no EAR is programmed.
.TP
.B Method 4
There is no EAR event in the list of events to monitor and and \fBear_used\fR is set. In this case
case the EAR will be programmed (PMC10 or PMC11) using the information in the \fBpfp_mont_iear\fR or
\fBpfp_mont_dear\fR structure. This is the free running mode for the EAR.
.sp
.SH EXECUTION TRACE BUFFER
The \fBpfp_mont_etb\fR of type \fBpfmlib_mont_etb_t\fR field is used to configure the Execution Trace Buffer (ETB). If the
\fBetb_used\fR is set, then the library will take the configuration into account, otherwise any ETB configuration will be ignored.
The various fields in this structure provide means to filter out the kind of changes in the control flow (branches, traps, rfi, ...)
that get recorded in the ETB. Each one represents an element of the branch architecture of the Itanium 2 9000 (Montecito) processor.
Refer to the Itanium 2 9000 (Montecito) specific documentation for more details on the branch architecture. The fields are as follows:
.TP
.B etb_tm
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
taken branches are captured. Finally if this field is 3 then all branches are captured.
.TP
.B etb_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 then all branches are captured regardless of
target address prediction.
.TP
.B etb_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 prediction.
.TP
.B etb_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 captured.
.TP
.B etb_plm
This is the privilege level mask at which the ETB captures branches. It can be any combination of \fBPFM_PLM0\fR, \fBPFM_PLM1\fR, \fBPFM_PLM2\fR,
\fBPFM_PLM3\fR. If \fBetb_plm\fR is 0 then the default privilege level mask in \fBpfp_dfl_plm\fR is used.
.sp
There are 4 methods to program the ETB and they are as follows:
.sp
.TP
.B Method 1
The \fBETB_EVENT\fR is in the list of event to monitor and \fBetb_used\fR is cleared. In this case,
the ETB will be configured (PMC39) to record ALL branches. A counting monitor will be programmed to
count \fBETB_EVENT\fR.
.TP
.B Method 2
The \fBETB_EVENT\fR is in the list of events to monitor and \fBetb_used\fR is set. In this case,
the BTB will be configured (PMC39) using the information in the \fBpfp_mont_etb\fR structure. A counting monitor
(PMC4/PMD4-PMC7/PMD7) will be programmed to count \fBBRANCH_EVENT\fR.
.TP
.B Method 3
The \fBETB_EVENT\fR is not in the list of events to monitor and \fBetb_used\fR is set. In this case,
the ETB will be configured (PMC39) using the information in the \fBpfp_mont_etb\fR structure. This is the
free running mode for the ETB.
.TP
.B Method 4
The \fBETB_EVENT\fR is not in the list of events to monitor and \fBetb_used\fR is cleared. In this case,
the ETB is not programmed.
.SH DATA AND CODE RANGE RESTRICTIONS
The \fBpfp_mont_drange\fR and \fBpfp_mont_irange\fR 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 the \fBpfm_dispatch_events()\fR function, the application gets back the set of
registers and their values that needs to be programmed via a kernel interface.
Range restriction 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, there
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
be situations where the actual range is larger than the requested range. For code ranges, Itanium 2 9000 (Montecito) processor can use what is called a fine mode,
where a range is designated using two pairs of code debug registers. In this mode, the bitmask 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 64KB or less and the range
cannot cross a 64KB 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 mode otherwise. Fine mode applies to all code debug
registers or none, i.e., you cannot have a range using fine mode and another using the bitmask. The Itanium 2 9000 (Montecito) processor
somehow limits the use 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
events to collect the counts. For all other events, only one pair can be used, which leads to more inaccuracy due to
approximation. Data ranges can used multiple debug register pairs to gain more accuracy. 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.
If range restriction is to be used, the \fBrr_used\fR field must be set to one, otherwise settings will be ignored.
The ranges are described by the \fBpfmlib_mont_input_rr_t\fR structure. Up to 4 ranges can be defined. Each
range is described in by a entry in \fBrr_limits\fR. Some flags for all ranges can be defined in \fBrr_flags\fR.
Currently defined flags are:
.sp
.TP
.B PFMLIB_MONT_RR_INV
Inverse the code ranges. The qualifying events will be measurement when executing outside the specified
ranges.
.TP
.B PFMLIB_MONT_RR_NO_FINE_MODE
Force non fine mode for all code ranges (mostly for debug)
.sp
.LP
The \fBpfmlib_mont_input_rr_desc_t\fR structure is defined as follows:
.TP
.B rr_plm
The privilege level at which the range is active. It can be any combinations of
\fBPFM_PLM0\fR, \fBPFM_PLM1\fR, \fBPFM_PLM2\fR, \fBPFM_PLM3\fR. If \fBetb_plm\fR is 0 then the
default privilege level mask in \fBpfp_dfl_plm\fR is used. The privilege level is only relevant
for code ranges, data ranges ignores the setting.
.TP
.B rr_start
This is the start address of the range. Any address is supported but for code range it
must be bundle aligned, i.e., 16-byte aligned.
.TP
.B rr_end
This is the end address of the range. Any address is supported but for code range it
must be bundle aligned, i.e., 16-byte aligned.
.sp
.LP
The library will provide the values for the debug registers as well as some information
about the actual ranges in the output parameters and more precisely in the \fBpfmlib_mont_output_rr_t\fR
structure for each range. The structure is defined as follows:
.TP
.B rr_nbr_used
Contains the number of debug registers used to cover the range. This is necessarily an even number
as debug registers always go in pair. The value of this field is between 0 and 7.
.TP
.B rr_br
This table contains the list of debug registers necessary to cover the ranges. Each element is
of type \fBpfmlib_reg_t\fR. The \fBreg_num\fR field contains the debug register index while
\fBreg_value\fR contains the debug register value. Both the index and value must be copied
into the kernel specific argument to program the debug registers. The library never programs them.
.TP
.B rr_infos
Contains information about the ranges defined. Because of alignment restrictions, the actual range
covered by the debug registers may be larger than the requested range. This table describe the differences
between the requested and actual ranges expressed as offsets:
.TP
.B rr_soff
Contains the start offset of the actual range described by the debug registers. If zero, it means
the library was able to match exactly the beginning of the range. Otherwise it represents the number
of byte by which the actual range precedes the requested range.
.TP
.B rr_eoff
Contains the end offset of the actual range described by the debug registers. If zero, it means
the library was able to match exactly the end of the range. Otherwise it represents the number of
bytes by which the actual range exceeds the requested range.
.sp
.LP
.SH IP EVENT CAPTURE (IP-EAR)
The Execution Trace Buffer (ETB) can be configured to record the addresses of
consecutive retiring instructions. In this case the ETB contains IP addresses
and not branches related information. This feature cannot be used in conjunction
with regular branch captures as described above. To active this feature the
\fBipear_used\fR field of the \fBpfmlib_mont_ipear_t\fR must be set to 1.
The other fields in this structure are used as follows:
.sp
.TP
.B ipear_plm
The privilege level of the instructions to capture. It can be any combination of \fBPFM_PLM0\fR, \fBPFM_PLM1\fR, \fBPFM_PLM2\fR,
\fBPFM_PLM3\fR. If \fBetb_plm\fR is 0 then the default privilege level mask in \fBpfp_dfl_plm\fR is used.
.TP
.B ipear_delay
The number of cycles by which to delay the freeze of the ETB after a PMU interrupt (which freeze the rest of counters).
.LP
.sp
.SH ERRORS
Refer to the description of the \fBpfm_dispatch_events()\fR function for errors when using
the Itanium 2 9000 (Montecito) specific input and output arguments.
.SH SEE ALSO
pfm_dispatch_events(3) and set of examples shipped with the library
.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.PP