NAME | SYNOPSIS | DESCRIPTION | MODIFIERS | AUTHORS | COLOPHON

LIBPFM(3)                 Linux Programmer's Manual                LIBPFM(3)

NAME         top

       libpfm_perf_event_raw - support for perf_events raw events syntax

SYNOPSIS         top

       #include <perfmon/pfmlib.h>

       PMU name: perf_raw
       PMU desc: Raw perf_events event syntax

DESCRIPTION         top

       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         top

       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 on
              sampling events. This is an integer value. It can have the
              following values: 1 enable precise sampling, 2 enable precise
              sampling and eliminate skid. Not all events necessarily
              support precise mode, this is dependent on the underlying PMU.
              Eliminating skid is a best effort feature. It may not work for
              all samples.

       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         top

       Stephane Eranian <eranian@gmail.com>

COLOPHON         top

       This page is part of the perfmon2 (a performance monitoring library)
       project.  Information about the project can be found at 
       ⟨http://perfmon2.sourceforge.net/⟩.  If you have a bug report for this
       manual page, send it to perfmon2-devel@lists.sourceforge.net.  This
       page was obtained from the project's upstream Git repository 
       ⟨git://git.code.sf.net/p/perfmon2/libpfm4⟩ on 2017-03-13.  If you dis‐
       cover any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

                               February, 2014                      LIBPFM(3)