1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 libpfm_perf_event_raw - support for perf_events raw events syntax
7
9 #include <perfmon/pfmlib.h>
10 PMU name: perf_raw
12 PMU desc: Raw perf_events event syntax
13
16 The library supports a pseudo PMU model to allow raw encodings of PMU
17 events for the Linux perf_events kernel interface.
18 With this PMU, it is possible to provide the raw hexadecimal encoding
20 of any hardware event for any PMU models. The raw encoding is passed as
21 is to the kernel. All events are encoded as PERF_TYPE_RAW. As such,
22 perf_events generic events, such as cycles, instructions, cannot be en‐
23 coded by this PMU.
24 The syntax is very simple: rX. X is the hexadecimal 64-bit value for
26 the event. It may include event filters on some PMU models. The hexa‐
27 decimal number is passed without the 0x prefix, e.g., r01c4.
28 The library's standard perf_events attributes are supported by this PMU
30 model. They are separated with colons as is customary with the li‐
31 brary.
32
35 The following modifiers are supported by this PMU model:
36 u Measure at user level which includes privilege levels 1, 2, 3.
38 This corresponds to PFM_PLM3. This is a boolean modifier.
39 k Measure at kernel level which includes privilege level 0. This
41 corresponds to PFM_PLM0. This is a boolean modifier.
42 h Measure at the hypervisor level. This corresponds to PFM_PLMH.
44 This is a boolean modifier
45 mg Measure guest execution only. This is a boolean modifier
47 mh Measure host execution only. This is a boolean modifier
49 period Specify the the sampling period value. Value can be expressed in
51 decimal or hexadecimal. Value is 64-bit wide. This option is
52 mutually exclusive with freq. The period is expressed in the
53 unit of the event. There is no default value.
54 freq Specify the the sampling frequency value. Value can be expressed
56 in decimal or hexadecimal. Value is 64-bit wide. This options
57 is mutually exclusive with period. The value is expressed in
58 Hertz. For instance, freq=100, means that the event should be
59 sampled 100 times per second on average. There is no default
60 value.
61 excl The associated event is the only event measured on the PMU. This
63 applies only to hardware events. This attribute requires admin
64 privileges. Default is off.
65 precise
67 Enables precise sampling mode. This option is only valid when
68 sampling on events. The options takes an integer argument. It
69 can have the following values: 1=enable precise sampling, 2=en‐
70 able precise sampling and eliminate skid, 3=enable precise sam‐
71 pling, eliminate skid and bias. Not all events necessarily sup‐
72 port precise mode at all levels, this is dependent on the under‐
73 lying PMU. Eliminating skid is a best effort feature. It may not
74 work for all samples. This option is mutually exclusive with
75 hw_smpl. This options implies using the hardware assist sampling
76 mechanism.
77 hw_smpl
79 Enables hardware assist sampling. This is a boolean option. It
80 is false by default. On some processors, it is possible to have
81 the hardware record samples in a buffer and then notify the ker‐
82 nel when it is full. Such feature may not be available for all
83 events. Using a hardware buffer does not necessarily eliminate
84 skid and bias, it usually lowers the overhead of interrupt-based
85 sampling by amortizing the interrupt over multiple samples. This
86 option is usually implicit with precise sampling events.
87 cpu This integer option is used with system-wide events, i.e.,
89 events attached to a CPU instead of a thread. The value desig‐
90 nate the CPU to attach the event to. It is up to the caller of
91 the library to use the cpu field in the library event encoding
92 argument to create the event. No verification on the validity of
93 the CPU number is made by the library. Default value is -1 for
94 this field.
95 pinned This boolean option is used with system-wide events, i.e.,
97 events attached to a CPU instead of a thread. If set, then the
98 event is marked as pinned. That means it needs to remain on the
99 counters at all time, i.e., it cannot be multiplexed. There can
100 only be as many pinned events as there are counters, yet the li‐
101 brary does not check for that, the perf_event subsystem does.
102 The default value for this field is false, i.e., the event is
103 not pinned.
104
107 Stephane Eranian <eranian@gmail.com>
108 February, 2014 LIBPFM(3)