libpfm_perf_event_raw(3) — Linux manual page

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
              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         top

       Stephane Eranian <[email protected]>

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
       [email protected].  This page was obtained
       from the project's upstream Git repository
       ⟨git://git.code.sf.net/p/perfmon2/libpfm4 perfmon2-libpfm4⟩ on
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-04-24.)  If you
       discover 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 [email protected]

                             February, 2014                    LIBPFM(3)