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