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