NAME

       libpfm_perf_event_raw - support for perf_events raw events syntax

SYNOPSIS

       #include <perfmon/pfmlib.h>

       PMU name: perf_raw
       PMU desc: Raw perf_events event syntax

DESCRIPTION

       The library supports a pseudo PMU model to allow raw encodings of PMU events for the Linux
       perf_events kernel interface.

       With this PMU, it is possible to provide the raw  hexadecimal  encoding  of  any  hardware
       event  for  any PMU models. The raw encoding is passed as is to the kernel. All events are
       encoded  as  PERF_TYPE_RAW.  As  such,  perf_events  generic  events,  such   as   cycles,
       instructions, cannot be encoded by this PMU.

       The  syntax  is  very simple: rX. X is the hexadecimal 64-bit value for the event.  It may
       include event filters on some PMU models. The hexadecimal number is passed without the  0x
       prefix, e.g., r01c4.

       The  library's  standard perf_events attributes are supported by this PMU model.  They are
       separated with colons as is customary with the library.

MODIFIERS

       The following modifiers are supported by this PMU model:

       u      Measure at user level which includes privilege levels 1, 2, 3. This corresponds  to
              PFM_PLM3.  This is a boolean modifier.

       k      Measure  at  kernel  level  which  includes  privilege level 0. This corresponds to
              PFM_PLM0.  This is a boolean modifier.

       h      Measure at the hypervisor level. This corresponds to PFM_PLMH.  This is  a  boolean
              modifier

       mg     Measure guest execution only. This is a boolean modifier

       mh     Measure host execution only. This is a boolean modifier

       period Specify  the  the  sampling  period  value.  Value  can  be expressed in decimal or
              hexadecimal.  Value is 64-bit wide. This option is mutually  exclusive  with  freq.
              The period is expressed in the unit of the event. There is no default value.

       freq   Specify  the  the  sampling  frequency  value. Value can be expressed in decimal or
              hexadecimal.  Value is 64-bit wide. This options is mutually exclusive with period.
              The  value  is  expressed  in  Hertz.  For instance, freq=100, means that the event
              should be sampled 100 times per second on average. There is no default value.

       excl   The associated event is the only event measured on the PMU. This  applies  only  to
              hardware events. This attribute requires admin privileges. Default is off.

       precise
              Enables  precise  sampling mode. This option is only valid when sampling on events.
              The options takes an integer argument. It can have the following  values:  1=enable
              precise  sampling,  2=enable  precise sampling and eliminate skid, 3=enable precise
              sampling, eliminate skid and bias. Not all events necessarily support precise  mode
              at  all levels, this is dependent on the underlying PMU. Eliminating skid is a best
              effort feature. It may not work for all samples. This option is mutually  exclusive
              with hw_smpl. This options implies using the hardware assist sampling mechanism.

       hw_smpl
              Enables hardware assist sampling. This is a boolean option. It is false by default.
              On some processors, it is possible to have the hardware record samples in a  buffer
              and  then notify the kernel when it is full.  Such feature may not be available for
              all events. Using a hardware buffer does not necessarily eliminate skid  and  bias,
              it  usually  lowers  the  overhead  of  interrupt-based  sampling by amortizing the
              interrupt over multiple samples. This  option  is  usually  implicit  with  precise
              sampling events.

       cpu    This integer option is used with system-wide events, i.e., events attached to a CPU
              instead of a thread. The value designate the CPU to attach the event to. It  is  up
              to  the  caller  of  the library to use the cpu field in the library event encoding
              argument to create the event. No verification on the validity of the CPU number  is
              made by the library. Default value is -1 for this field.

       pinned This boolean option is used with system-wide events, i.e., events attached to a CPU
              instead of a thread. If set, then the event is marked  as  pinned.  That  means  it
              needs  to remain on the counters at all time, i.e., it cannot be multiplexed. There
              can only be as many pinned events as there are counters, yet the library  does  not
              check  for that, the perf_event subsystem does. The default value for this field is
              false, i.e., the event is not pinned.

AUTHORS

       Stephane Eranian <eranian@gmail.com>

                                          February, 2014                                LIBPFM(3)